js.documents 7.16.2 → 7.17.0

package/README.md

@@ -270,7 +270,7 @@ const pdfBytes = docxToPdf(docxBytes, {
 
 The tree and the flat `ContentDocument` are one format in two encodings, related by three laws (stated on [document-schema.js#20](https://github.com/ExaDev/document-schema.js/issues/20), proven over this package's real corpus by the bijection suite in `src/convert/bijection.test.ts`): (i) `flattenTree(assembleTree(c))` reproduces `c` exactly, up to one declared normalisation (a present-but-empty sheet `embeddedObjects` array normalises to the field absent); (ii) effective-property equality holds universally — a factored and an unfactored serialisation of one document resolve to the same properties; (iii) minting is idempotent — factoring a second time produces the identical styles table.
 
-Three flat-form signals drive the grouping, and all three are reproduced exactly on the way back: `headingLevel`, `list.level`, and — since document-schema.js 4.2.0 — the `constructStart`/`constructEnd` block pair that delimits a fidelity construct (a docx SDT, an ODF field, a tracked-change span, a bookmark, a hyperlink region, a division). `decompose` promotes each marker pair to a construct group carrying the `ConstructDescriptor` and holding the delimited region as its children, decomposed on its own; `flattenTree` writes the pair back around that region. A construct is a semantic wrapper rather than a container, so it neither disturbs the enclosing heading/list nesting it sits inside nor resets the style chain resolving onto it — content inside a construct still inherits the ambient heading's or section's factored properties, exactly as if the construct were not there. Markers must pair up within one container's block flow: an unmatched `constructEnd`, or a `constructStart` a container never closes, throws document-schema.js's `ConstructMarkerImbalanceError` (carrying its `ConstructMarkerImbalance` payload, so the offending block index is available without parsing the message) rather than being repaired into a plausible tree. The format codecs emit and consume these markers on both sides today — ooxml.js's docx pair (SDTs, bookmarks, tracked changes, block-scoped fields), odf.js's odt reader for divisions, index wrappers, and cross-paragraph bookmarks with its writer covering the construct kinds it models and refusing the rest by name, markdown-codec, rtf-codec, and epub-codec in both directions, and this package's own PDF reconstruction emitting division and anchor pairs — so the marker machinery has real producers and consumers, not just the boundary transform. Reaching further than the codecs is still a mixed picture, not a blanket guarantee: `buildMarkdownText` passes markers through to markdown-codec's own bracket-resolving writer, which renders each construct it has a markdown spelling for (a footnote definition, a blockquote division, a titled image's link wrapper) and renders the rest transparently with a diagnostic — markdown-codec's own read side emits those pairs, so this package's editor and conversion round trips depend on it; building docx bytes from marker-carrying flat content writes a bookmark anchor's pair as real `w:bookmarkStart`/`w:bookmarkEnd` around the blocks it spans, and the odt builder does the same through `text:bookmark-start`/`-end` — the one construct family expressible append-only in either format's body flow — while the wrapper-shaped kinds (an SDT, a tracked change, a division) are dropped rather than written, since neither editor model has a surface for them; and the layout engines (`convertWordprocessingToLayout`, `convertShape`) silently skip a marker block during pagination — harmless there, since a marker carries no content of its own to render.
+Three flat-form signals drive the grouping, and all three are reproduced exactly on the way back: `headingLevel`, `list.level`, and — since document-schema.js 4.2.0 — the `constructStart`/`constructEnd` block pair that delimits a fidelity construct (a docx SDT, an ODF field, a tracked-change span, a bookmark, a hyperlink region, a division). `decompose` promotes each marker pair to a construct group carrying the `ConstructDescriptor` and holding the delimited region as its children, decomposed on its own; `flattenTree` writes the pair back around that region. A construct is a semantic wrapper rather than a container, so it neither disturbs the enclosing heading/list nesting it sits inside nor resets the style chain resolving onto it — content inside a construct still inherits the ambient heading's or section's factored properties, exactly as if the construct were not there. Markers must pair up within one container's block flow: an unmatched `constructEnd`, or a `constructStart` a container never closes, throws document-schema.js's `ConstructMarkerImbalanceError` (carrying its `ConstructMarkerImbalance` payload, so the offending block index is available without parsing the message) rather than being repaired into a plausible tree. The format codecs emit and consume these markers on both sides today — ooxml.js's docx pair (SDTs, bookmarks, tracked changes, block-scoped fields), odf.js's odt reader for divisions, index wrappers, and cross-paragraph bookmarks with its writer covering the construct kinds it models and refusing the rest by name, markdown-codec, rtf-codec, and epub-codec in both directions, and this package's own PDF reconstruction emitting division and anchor pairs — so the marker machinery has real producers and consumers, not just the boundary transform. Reaching further than the codecs is still a mixed picture, not a blanket guarantee: `buildMarkdownText` passes markers through to markdown-codec's own bracket-resolving writer, which renders each construct it has a markdown spelling for (a footnote definition, a blockquote division, a titled image's link wrapper) and renders the rest transparently with a diagnostic — markdown-codec's own read side emits those pairs, so this package's editor and conversion round trips depend on it; building docx bytes from marker-carrying flat content writes a bookmark anchor's pair as real `w:bookmarkStart`/`w:bookmarkEnd` around the blocks it spans and a content control's pair as a real `w:sdt` region (the descriptor driving `w:sdtPr`, the blocks between the markers landing inside its own `w:sdtContent`), and the odt builder does the bookmark pair through `text:bookmark-start`/`-end` and a division's pair as a real `text:section` region the between-blocks land inside — so the one wrapper kind each format natively spells at body scope now survives the build, round-tripping through its own reader as the identical construct pair — while the remaining kinds (a tracked change's region machinery, an ODF index wrapper's generated-content model) are dropped rather than written, since neither editor model has a surface for them; and the layout engines (`convertWordprocessingToLayout`, `convertShape`) silently skip a marker block during pagination — harmless there, since a marker carries no content of its own to render.
 
 `assembleTree` is the one constructor behind every construction site — decompose, then `factorStyles`, the minting pass that hoists property tuples occurring two or more times onto a group-wrapper ref plus a `styles` table entry (deterministic order; `frames`/`sourcePath`/`styleId` are per-node facts and never factor). The transform belongs to `document-schema.js`, which owns both encodings and publishes `assembleTree`, `decompose`, `flattenTree`, `factorStyles`, `ConstructMarkerImbalanceError`, and the `TreeChildren` type for any caller composing its own boundary — import them from there, not from this package. documents.js consumes that transform at its own boundary and re-exports none of it; the readers, builders, layout engines, and editors here keep producing and consuming the flat form, so the tree exists only where a `DocumentTree` is constructed or consumed:
 

package/dist/edit/docx/content.cjs

@@ -22,20 +22,24 @@ var ConstructMarkerState = class {
 			const id = this.nextBookmarkId;
 			this.nextBookmarkId += 1;
 			this.open.push({
-				isBookmark: true,
+				kind: "bookmark",
 				id
 			});
 			body.appendBookmarkStart(id, detail.name);
 			return;
 		}
-		this.open.push({
-			isBookmark: false,
-			id: -1
-		});
+		if (detail.kind === "contentControl") {
+			this.open.push({ kind: "region" });
+			body.openContentControlRegion(detail);
+			return;
+		}
+		this.open.push({ kind: "dropped" });
 	}
 	closeConstruct(body) {
 		const entry = this.open.pop();
-		if (entry?.isBookmark) body.appendBookmarkEnd(entry.id);
+		if (entry === void 0) return;
+		if (entry.kind === "bookmark") body.appendBookmarkEnd(entry.id);
+		else if (entry.kind === "region") body.closeRegion();
 	}
 };
 function buildDocxPackage(content, options) {

package/dist/edit/docx/content.js

@@ -21,20 +21,24 @@ var ConstructMarkerState = class {
 			const id = this.nextBookmarkId;
 			this.nextBookmarkId += 1;
 			this.open.push({
-				isBookmark: true,
+				kind: "bookmark",
 				id
 			});
 			body.appendBookmarkStart(id, detail.name);
 			return;
 		}
-		this.open.push({
-			isBookmark: false,
-			id: -1
-		});
+		if (detail.kind === "contentControl") {
+			this.open.push({ kind: "region" });
+			body.openContentControlRegion(detail);
+			return;
+		}
+		this.open.push({ kind: "dropped" });
 	}
 	closeConstruct(body) {
 		const entry = this.open.pop();
-		if (entry?.isBookmark) body.appendBookmarkEnd(entry.id);
+		if (entry === void 0) return;
+		if (entry.kind === "bookmark") body.appendBookmarkEnd(entry.id);
+		else if (entry.kind === "region") body.closeRegion();
 	}
 };
 function buildDocxPackage(content, options) {

package/dist/edit/docx/editor.cjs

@@ -35,15 +35,26 @@ var DocxBodyImpl = class {
 	body;
 	imageContext;
 	pkg;
+	openRegions = [];
+	nextSdtId = 1;
 	constructor(body, imageContext, pkg) {
 		this.body = body;
 		this.imageContext = imageContext;
 		this.pkg = pkg;
 	}
+	appendToBody(element) {
+		const region = this.openRegions.at(-1);
+		if (region !== void 0) {
+			region.children.push(element);
+			return;
+		}
+		this.body.children.splice(bodyInsertionPoint(this.body), 0, element);
+	}
 	appendParagraph(init) {
 		const paragraphElement = require_edit_docx_paragraph.buildParagraph(init);
-		this.body.children.splice(bodyInsertionPoint(this.body), 0, paragraphElement);
-		return new require_edit_docx_paragraph.DocxParagraph(this.body.children, paragraphElement, this.imageContext, this.pkg);
+		this.appendToBody(paragraphElement);
+		const container = this.openRegions.at(-1)?.children ?? this.body.children;
+		return new require_edit_docx_paragraph.DocxParagraph(container, paragraphElement, this.imageContext, this.pkg);
 	}
 	insertParagraphAt(index, init) {
 		const paragraphElement = require_edit_docx_paragraph.buildParagraph(init);
@@ -54,22 +65,65 @@ var DocxBodyImpl = class {
 	}
 	appendTable(init) {
 		const tableElement = require_edit_docx_table.buildTable(init);
-		this.body.children.splice(bodyInsertionPoint(this.body), 0, tableElement);
-		return new require_edit_docx_table.DocxTable(this.body.children, tableElement);
+		this.appendToBody(tableElement);
+		const container = this.openRegions.at(-1)?.children ?? this.body.children;
+		return new require_edit_docx_table.DocxTable(container, tableElement);
 	}
 	appendPageBreak() {
 		const run = require_xml_fragment.el("w:r", {}, [require_xml_fragment.el("w:br", { "w:type": "page" })]);
 		const paragraph = require_xml_fragment.el("w:p", {}, [run]);
-		this.body.children.splice(bodyInsertionPoint(this.body), 0, paragraph);
+		this.appendToBody(paragraph);
 	}
 	appendBookmarkStart(id, name) {
-		this.body.children.splice(bodyInsertionPoint(this.body), 0, require_xml_fragment.el("w:bookmarkStart", {
+		this.appendToBody(require_xml_fragment.el("w:bookmarkStart", {
 			"w:id": String(id),
 			"w:name": require_xml_entities.encodeXmlText(name)
 		}));
 	}
 	appendBookmarkEnd(id) {
-		this.body.children.splice(bodyInsertionPoint(this.body), 0, require_xml_fragment.el("w:bookmarkEnd", { "w:id": String(id) }));
+		this.appendToBody(require_xml_fragment.el("w:bookmarkEnd", { "w:id": String(id) }));
+	}
+	openContentControlRegion(descriptor) {
+		const id = this.nextSdtId;
+		this.nextSdtId += 1;
+		const sdtPr = [require_xml_fragment.el("w:id", { "w:val": String(id) })];
+		if (descriptor.alias !== void 0) sdtPr.push(require_xml_fragment.el("w:alias", { "w:val": require_xml_entities.encodeXmlText(descriptor.alias) }));
+		if (descriptor.tag !== void 0) sdtPr.push(require_xml_fragment.el("w:tag", { "w:val": require_xml_entities.encodeXmlText(descriptor.tag) }));
+		if (descriptor.lock !== void 0) sdtPr.push(require_xml_fragment.el("w:lock", { "w:val": descriptor.lock === "content" ? "contentLocked" : descriptor.lock === "container" ? "sdtLocked" : "sdtContentLocked" }));
+		switch (descriptor.controlType) {
+			case "plainText":
+				sdtPr.push(require_xml_fragment.el("w:text", {}));
+				break;
+			case "comboBox":
+			case "dropDown":
+				sdtPr.push(require_xml_fragment.el(descriptor.controlType === "comboBox" ? "w:comboBox" : "w:dropDownList", {}, (descriptor.options ?? []).map((option) => require_xml_fragment.el("w:listItem", {
+					"w:displayText": require_xml_entities.encodeXmlText(option),
+					"w:value": require_xml_entities.encodeXmlText(option)
+				}))));
+				break;
+			case "date":
+				sdtPr.push(require_xml_fragment.el("w:date", descriptor.value === void 0 ? {} : { "w:fullDate": require_xml_entities.encodeXmlText(descriptor.value) }));
+				break;
+			case "checkbox":
+				sdtPr.push(require_xml_fragment.el("w:checkbox", {}, [require_xml_fragment.el("w:checked", { "w:val": descriptor.checked === true ? "true" : "false" })]));
+				break;
+			case "picture":
+				sdtPr.push(require_xml_fragment.el("w:picture", {}));
+				break;
+			case "group":
+				sdtPr.push(require_xml_fragment.el("w:group", {}));
+				break;
+			case "repeatingSection":
+				sdtPr.push(require_xml_fragment.el("w:repeatingSection", {}));
+				break;
+			case "index": sdtPr.push(require_xml_fragment.el("w:docPartObj", {}, [require_xml_fragment.el("w:docPartGallery", { "w:val": "Table of Contents" })]));
+		}
+		const sdtContent = require_xml_fragment.el("w:sdtContent", {}, []);
+		this.appendToBody(require_xml_fragment.el("w:sdt", {}, [require_xml_fragment.el("w:sdtPr", {}, sdtPr), sdtContent]));
+		this.openRegions.push(sdtContent);
+	}
+	closeRegion() {
+		this.openRegions.pop();
 	}
 };
 var DocxEditor = class {

package/dist/edit/docx/editor.d.cts

@@ -1,7 +1,7 @@
 import { t as ClockPort } from "../../clock-C7SUuYN0.cjs";
 import { DocxParagraph, ParagraphInit } from "./paragraph.cjs";
 import { DocxTable, TableInit } from "./table.cjs";
-import { LayoutMetadata } from "document-schema.js";
+import { ContentControlDescriptor, LayoutMetadata } from "document-schema.js";
 import { Package } from "ooxml.js";
 //#region src/edit/docx/editor.d.ts
 interface DocxBody {
@@ -11,6 +11,8 @@ interface DocxBody {
   appendPageBreak(): void;
   appendBookmarkStart(id: number, name: string): void;
   appendBookmarkEnd(id: number): void;
+  openContentControlRegion(descriptor: ContentControlDescriptor): void;
+  closeRegion(): void;
 }
 declare class DocxEditor {
   readonly body: DocxBody;

package/dist/edit/docx/editor.d.ts

@@ -2,7 +2,7 @@ import { t as ClockPort } from "../../clock-C7SUuYN0.js";
 import { DocxParagraph, ParagraphInit } from "./paragraph.js";
 import { DocxTable, TableInit } from "./table.js";
 import { Package } from "ooxml.js";
-import { LayoutMetadata } from "document-schema.js";
+import { ContentControlDescriptor, LayoutMetadata } from "document-schema.js";
 //#region src/edit/docx/editor.d.ts
 interface DocxBody {
   insertParagraphAt(index: number, init?: ParagraphInit): DocxParagraph;
@@ -11,6 +11,8 @@ interface DocxBody {
   appendPageBreak(): void;
   appendBookmarkStart(id: number, name: string): void;
   appendBookmarkEnd(id: number): void;
+  openContentControlRegion(descriptor: ContentControlDescriptor): void;
+  closeRegion(): void;
 }
 declare class DocxEditor {
   readonly body: DocxBody;

package/dist/edit/docx/editor.js

@@ -34,15 +34,26 @@ var DocxBodyImpl = class {
 	body;
 	imageContext;
 	pkg;
+	openRegions = [];
+	nextSdtId = 1;
 	constructor(body, imageContext, pkg) {
 		this.body = body;
 		this.imageContext = imageContext;
 		this.pkg = pkg;
 	}
+	appendToBody(element) {
+		const region = this.openRegions.at(-1);
+		if (region !== void 0) {
+			region.children.push(element);
+			return;
+		}
+		this.body.children.splice(bodyInsertionPoint(this.body), 0, element);
+	}
 	appendParagraph(init) {
 		const paragraphElement = buildParagraph(init);
-		this.body.children.splice(bodyInsertionPoint(this.body), 0, paragraphElement);
-		return new DocxParagraph(this.body.children, paragraphElement, this.imageContext, this.pkg);
+		this.appendToBody(paragraphElement);
+		const container = this.openRegions.at(-1)?.children ?? this.body.children;
+		return new DocxParagraph(container, paragraphElement, this.imageContext, this.pkg);
 	}
 	insertParagraphAt(index, init) {
 		const paragraphElement = buildParagraph(init);
@@ -53,22 +64,65 @@ var DocxBodyImpl = class {
 	}
 	appendTable(init) {
 		const tableElement = buildTable(init);
-		this.body.children.splice(bodyInsertionPoint(this.body), 0, tableElement);
-		return new DocxTable(this.body.children, tableElement);
+		this.appendToBody(tableElement);
+		const container = this.openRegions.at(-1)?.children ?? this.body.children;
+		return new DocxTable(container, tableElement);
 	}
 	appendPageBreak() {
 		const run = el("w:r", {}, [el("w:br", { "w:type": "page" })]);
 		const paragraph = el("w:p", {}, [run]);
-		this.body.children.splice(bodyInsertionPoint(this.body), 0, paragraph);
+		this.appendToBody(paragraph);
 	}
 	appendBookmarkStart(id, name) {
-		this.body.children.splice(bodyInsertionPoint(this.body), 0, el("w:bookmarkStart", {
+		this.appendToBody(el("w:bookmarkStart", {
 			"w:id": String(id),
 			"w:name": encodeXmlText(name)
 		}));
 	}
 	appendBookmarkEnd(id) {
-		this.body.children.splice(bodyInsertionPoint(this.body), 0, el("w:bookmarkEnd", { "w:id": String(id) }));
+		this.appendToBody(el("w:bookmarkEnd", { "w:id": String(id) }));
+	}
+	openContentControlRegion(descriptor) {
+		const id = this.nextSdtId;
+		this.nextSdtId += 1;
+		const sdtPr = [el("w:id", { "w:val": String(id) })];
+		if (descriptor.alias !== void 0) sdtPr.push(el("w:alias", { "w:val": encodeXmlText(descriptor.alias) }));
+		if (descriptor.tag !== void 0) sdtPr.push(el("w:tag", { "w:val": encodeXmlText(descriptor.tag) }));
+		if (descriptor.lock !== void 0) sdtPr.push(el("w:lock", { "w:val": descriptor.lock === "content" ? "contentLocked" : descriptor.lock === "container" ? "sdtLocked" : "sdtContentLocked" }));
+		switch (descriptor.controlType) {
+			case "plainText":
+				sdtPr.push(el("w:text", {}));
+				break;
+			case "comboBox":
+			case "dropDown":
+				sdtPr.push(el(descriptor.controlType === "comboBox" ? "w:comboBox" : "w:dropDownList", {}, (descriptor.options ?? []).map((option) => el("w:listItem", {
+					"w:displayText": encodeXmlText(option),
+					"w:value": encodeXmlText(option)
+				}))));
+				break;
+			case "date":
+				sdtPr.push(el("w:date", descriptor.value === void 0 ? {} : { "w:fullDate": encodeXmlText(descriptor.value) }));
+				break;
+			case "checkbox":
+				sdtPr.push(el("w:checkbox", {}, [el("w:checked", { "w:val": descriptor.checked === true ? "true" : "false" })]));
+				break;
+			case "picture":
+				sdtPr.push(el("w:picture", {}));
+				break;
+			case "group":
+				sdtPr.push(el("w:group", {}));
+				break;
+			case "repeatingSection":
+				sdtPr.push(el("w:repeatingSection", {}));
+				break;
+			case "index": sdtPr.push(el("w:docPartObj", {}, [el("w:docPartGallery", { "w:val": "Table of Contents" })]));
+		}
+		const sdtContent = el("w:sdtContent", {}, []);
+		this.appendToBody(el("w:sdt", {}, [el("w:sdtPr", {}, sdtPr), sdtContent]));
+		this.openRegions.push(sdtContent);
+	}
+	closeRegion() {
+		this.openRegions.pop();
 	}
 };
 var DocxEditor = class {

package/dist/edit/odt/content.cjs

@@ -194,20 +194,24 @@ var ConstructMarkerState = class {
 		const detail = marker.descriptor;
 		if (detail.kind === "anchor" && detail.anchorType === "bookmark") {
 			this.open.push({
-				isBookmark: true,
+				kind: "bookmark",
 				name: detail.name
 			});
 			body.appendBookmarkStart(detail.name);
 			return;
 		}
-		this.open.push({
-			isBookmark: false,
-			name: ""
-		});
+		if (detail.kind === "division") {
+			this.open.push({ kind: "region" });
+			body.openDivisionRegion(detail);
+			return;
+		}
+		this.open.push({ kind: "dropped" });
 	}
 	closeConstruct(body) {
 		const entry = this.open.pop();
-		if (entry?.isBookmark) body.appendBookmarkEnd(entry.name);
+		if (entry === void 0) return;
+		if (entry.kind === "bookmark") body.appendBookmarkEnd(entry.name);
+		else if (entry.kind === "region") body.closeRegion();
 	}
 };
 function appendBlock(body, block, markers) {

package/dist/edit/odt/content.js

@@ -193,20 +193,24 @@ var ConstructMarkerState = class {
 		const detail = marker.descriptor;
 		if (detail.kind === "anchor" && detail.anchorType === "bookmark") {
 			this.open.push({
-				isBookmark: true,
+				kind: "bookmark",
 				name: detail.name
 			});
 			body.appendBookmarkStart(detail.name);
 			return;
 		}
-		this.open.push({
-			isBookmark: false,
-			name: ""
-		});
+		if (detail.kind === "division") {
+			this.open.push({ kind: "region" });
+			body.openDivisionRegion(detail);
+			return;
+		}
+		this.open.push({ kind: "dropped" });
 	}
 	closeConstruct(body) {
 		const entry = this.open.pop();
-		if (entry?.isBookmark) body.appendBookmarkEnd(entry.name);
+		if (entry === void 0) return;
+		if (entry.kind === "bookmark") body.appendBookmarkEnd(entry.name);
+		else if (entry.kind === "region") body.closeRegion();
 	}
 };
 function appendBlock(body, block, markers) {

package/dist/edit/odt/editor.cjs

@@ -31,42 +31,52 @@ function findOfficeText(contentRoot) {
 var OdtBodyImpl = class {
 	officeText;
 	pkg;
+	openDivisions = [];
 	constructor(officeText, pkg) {
 		this.officeText = officeText;
 		this.pkg = pkg;
 	}
+	containerChildren() {
+		return this.openDivisions.at(-1)?.section.children ?? this.officeText.children;
+	}
 	appendParagraph(init) {
 		const paragraphElement = require_edit_odt_paragraph.buildParagraph(this.pkg, init);
-		this.officeText.children.push(paragraphElement);
-		return new require_edit_odt_paragraph.OdtParagraph(this.officeText.children, paragraphElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(paragraphElement);
+		return new require_edit_odt_paragraph.OdtParagraph(container, paragraphElement, this.pkg);
 	}
 	appendTable(init) {
 		const tableElement = require_edit_odt_table.buildTable(this.pkg, init);
-		this.officeText.children.push(tableElement);
-		return new require_edit_odt_table.OdtTable(this.officeText.children, tableElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(tableElement);
+		return new require_edit_odt_table.OdtTable(container, tableElement, this.pkg);
 	}
 	appendList() {
 		const listElement = require_edit_odt_list.buildList(this.pkg);
-		this.officeText.children.push(listElement);
-		return new require_edit_odt_list.OdtList(this.officeText.children, listElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(listElement);
+		return new require_edit_odt_list.OdtList(container, listElement, this.pkg);
 	}
 	appendFormula(formula, frame) {
 		const paragraphElement = require_edit_odt_paragraph.buildParagraph(this.pkg);
 		paragraphElement.children.push(require_edit_odt_formula.insertFormulaFrameMedia(this.pkg, frame, formula));
-		this.officeText.children.push(paragraphElement);
-		return new require_edit_odt_paragraph.OdtParagraph(this.officeText.children, paragraphElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(paragraphElement);
+		return new require_edit_odt_paragraph.OdtParagraph(container, paragraphElement, this.pkg);
 	}
 	appendEmbeddedObject(object, directory) {
 		const paragraphElement = require_edit_odt_paragraph.buildParagraph(this.pkg);
 		paragraphElement.children.push((0, odf_js.writeEmbeddedObject)(object, directory, this.pkg));
-		this.officeText.children.push(paragraphElement);
-		return new require_edit_odt_paragraph.OdtParagraph(this.officeText.children, paragraphElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(paragraphElement);
+		return new require_edit_odt_paragraph.OdtParagraph(container, paragraphElement, this.pkg);
 	}
 	appendVectors(vectors) {
 		const paragraphElement = require_edit_odt_paragraph.buildParagraph(this.pkg);
 		for (const vector of vectors) paragraphElement.children.push(require_edit_odg_vector.buildVectorElement(this.pkg, vector, { textFlowAnchored: true }));
-		this.officeText.children.push(paragraphElement);
-		return new require_edit_odt_paragraph.OdtParagraph(this.officeText.children, paragraphElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(paragraphElement);
+		return new require_edit_odt_paragraph.OdtParagraph(container, paragraphElement, this.pkg);
 	}
 	appendPageBreak() {
 		const paragraphElement = require_edit_odt_paragraph.buildParagraph(this.pkg);
@@ -74,10 +84,10 @@ var OdtBodyImpl = class {
 			name: "text:style-name",
 			value: require_edit_odt_automatic_styles.ensurePageBreakStyleName(this.pkg)
 		});
-		this.officeText.children.push(paragraphElement);
+		this.containerChildren().push(paragraphElement);
 	}
 	appendBookmarkStart(name) {
-		this.officeText.children.push({
+		this.containerChildren().push({
 			type: "element",
 			tag: "text:bookmark-start",
 			attributes: [{
@@ -88,7 +98,7 @@ var OdtBodyImpl = class {
 		});
 	}
 	appendBookmarkEnd(name) {
-		this.officeText.children.push({
+		this.containerChildren().push({
 			type: "element",
 			tag: "text:bookmark-end",
 			attributes: [{
@@ -98,6 +108,51 @@ var OdtBodyImpl = class {
 			children: []
 		});
 	}
+	openDivisionRegion(descriptor) {
+		const attributes = [];
+		if (descriptor.name !== void 0) attributes.push({
+			name: "text:name",
+			value: require_xml_entities.encodeXmlText(descriptor.name)
+		});
+		if (descriptor.protected === true) attributes.push({
+			name: "text:protected",
+			value: "true"
+		});
+		const section = {
+			type: "element",
+			tag: "text:section",
+			attributes,
+			children: []
+		};
+		this.containerChildren().push(section);
+		this.openDivisions.push({
+			section,
+			linked: descriptor.linked
+		});
+	}
+	closeRegion() {
+		const entry = this.openDivisions.pop();
+		if (entry === void 0) return;
+		if (entry.linked !== void 0) {
+			const sourceAttributes = [{
+				name: "xlink:type",
+				value: "simple"
+			}, {
+				name: "xlink:href",
+				value: require_xml_entities.encodeXmlText(entry.linked.href)
+			}];
+			if (entry.linked.sectionName !== void 0) sourceAttributes.push({
+				name: "text:section-name",
+				value: require_xml_entities.encodeXmlText(entry.linked.sectionName)
+			});
+			entry.section.children.push({
+				type: "element",
+				tag: "text:section-source",
+				attributes: sourceAttributes,
+				children: []
+			});
+		}
+	}
 };
 var OdtEditor = class {
 	body;

package/dist/edit/odt/editor.d.cts

@@ -2,7 +2,7 @@ import { t as ClockPort } from "../../clock-C7SUuYN0.cjs";
 import { n as ParagraphInit, t as OdtParagraph } from "../../paragraph-CRaLSzWz.cjs";
 import { t as OdtList } from "../../list-C_UPIZWM.cjs";
 import { a as TableInit, n as OdtTable } from "../../table-COmzfIOe.cjs";
-import { Box, ContentFormula, ContentVector, LayoutMetadata } from "document-schema.js";
+import { Box, ContentFormula, ContentVector, DivisionDescriptor, LayoutMetadata } from "document-schema.js";
 import { Package } from "odf.js";
 //#region src/edit/odt/editor.d.ts
 interface OdtBody {
@@ -14,6 +14,8 @@ interface OdtBody {
   appendVectors(vectors: readonly ContentVector[]): OdtParagraph;
   appendBookmarkStart(name: string): void;
   appendBookmarkEnd(name: string): void;
+  openDivisionRegion(descriptor: DivisionDescriptor): void;
+  closeRegion(): void;
 }
 declare class OdtEditor {
   readonly body: OdtBody;

package/dist/edit/odt/editor.d.ts

@@ -2,7 +2,7 @@ import { t as ClockPort } from "../../clock-C7SUuYN0.js";
 import { n as ParagraphInit, t as OdtParagraph } from "../../paragraph-D4f705GG.js";
 import { t as OdtList } from "../../list-C2GWIe6E.js";
 import { a as TableInit, n as OdtTable } from "../../table-BmMyqRML.js";
-import { Box, ContentFormula, ContentVector, LayoutMetadata } from "document-schema.js";
+import { Box, ContentFormula, ContentVector, DivisionDescriptor, LayoutMetadata } from "document-schema.js";
 import { Package } from "odf.js";
 //#region src/edit/odt/editor.d.ts
 interface OdtBody {
@@ -14,6 +14,8 @@ interface OdtBody {
   appendVectors(vectors: readonly ContentVector[]): OdtParagraph;
   appendBookmarkStart(name: string): void;
   appendBookmarkEnd(name: string): void;
+  openDivisionRegion(descriptor: DivisionDescriptor): void;
+  closeRegion(): void;
 }
 declare class OdtEditor {
   readonly body: OdtBody;

package/dist/edit/odt/editor.js

@@ -30,42 +30,52 @@ function findOfficeText(contentRoot) {
 var OdtBodyImpl = class {
 	officeText;
 	pkg;
+	openDivisions = [];
 	constructor(officeText, pkg) {
 		this.officeText = officeText;
 		this.pkg = pkg;
 	}
+	containerChildren() {
+		return this.openDivisions.at(-1)?.section.children ?? this.officeText.children;
+	}
 	appendParagraph(init) {
 		const paragraphElement = buildParagraph(this.pkg, init);
-		this.officeText.children.push(paragraphElement);
-		return new OdtParagraph(this.officeText.children, paragraphElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(paragraphElement);
+		return new OdtParagraph(container, paragraphElement, this.pkg);
 	}
 	appendTable(init) {
 		const tableElement = buildTable(this.pkg, init);
-		this.officeText.children.push(tableElement);
-		return new OdtTable(this.officeText.children, tableElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(tableElement);
+		return new OdtTable(container, tableElement, this.pkg);
 	}
 	appendList() {
 		const listElement = buildList(this.pkg);
-		this.officeText.children.push(listElement);
-		return new OdtList(this.officeText.children, listElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(listElement);
+		return new OdtList(container, listElement, this.pkg);
 	}
 	appendFormula(formula, frame) {
 		const paragraphElement = buildParagraph(this.pkg);
 		paragraphElement.children.push(insertFormulaFrameMedia(this.pkg, frame, formula));
-		this.officeText.children.push(paragraphElement);
-		return new OdtParagraph(this.officeText.children, paragraphElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(paragraphElement);
+		return new OdtParagraph(container, paragraphElement, this.pkg);
 	}
 	appendEmbeddedObject(object, directory) {
 		const paragraphElement = buildParagraph(this.pkg);
 		paragraphElement.children.push(writeEmbeddedObject(object, directory, this.pkg));
-		this.officeText.children.push(paragraphElement);
-		return new OdtParagraph(this.officeText.children, paragraphElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(paragraphElement);
+		return new OdtParagraph(container, paragraphElement, this.pkg);
 	}
 	appendVectors(vectors) {
 		const paragraphElement = buildParagraph(this.pkg);
 		for (const vector of vectors) paragraphElement.children.push(buildVectorElement(this.pkg, vector, { textFlowAnchored: true }));
-		this.officeText.children.push(paragraphElement);
-		return new OdtParagraph(this.officeText.children, paragraphElement, this.pkg);
+		const container = this.containerChildren();
+		container.push(paragraphElement);
+		return new OdtParagraph(container, paragraphElement, this.pkg);
 	}
 	appendPageBreak() {
 		const paragraphElement = buildParagraph(this.pkg);
@@ -73,10 +83,10 @@ var OdtBodyImpl = class {
 			name: "text:style-name",
 			value: ensurePageBreakStyleName(this.pkg)
 		});
-		this.officeText.children.push(paragraphElement);
+		this.containerChildren().push(paragraphElement);
 	}
 	appendBookmarkStart(name) {
-		this.officeText.children.push({
+		this.containerChildren().push({
 			type: "element",
 			tag: "text:bookmark-start",
 			attributes: [{
@@ -87,7 +97,7 @@ var OdtBodyImpl = class {
 		});
 	}
 	appendBookmarkEnd(name) {
-		this.officeText.children.push({
+		this.containerChildren().push({
 			type: "element",
 			tag: "text:bookmark-end",
 			attributes: [{
@@ -97,6 +107,51 @@ var OdtBodyImpl = class {
 			children: []
 		});
 	}
+	openDivisionRegion(descriptor) {
+		const attributes = [];
+		if (descriptor.name !== void 0) attributes.push({
+			name: "text:name",
+			value: encodeXmlText$1(descriptor.name)
+		});
+		if (descriptor.protected === true) attributes.push({
+			name: "text:protected",
+			value: "true"
+		});
+		const section = {
+			type: "element",
+			tag: "text:section",
+			attributes,
+			children: []
+		};
+		this.containerChildren().push(section);
+		this.openDivisions.push({
+			section,
+			linked: descriptor.linked
+		});
+	}
+	closeRegion() {
+		const entry = this.openDivisions.pop();
+		if (entry === void 0) return;
+		if (entry.linked !== void 0) {
+			const sourceAttributes = [{
+				name: "xlink:type",
+				value: "simple"
+			}, {
+				name: "xlink:href",
+				value: encodeXmlText$1(entry.linked.href)
+			}];
+			if (entry.linked.sectionName !== void 0) sourceAttributes.push({
+				name: "text:section-name",
+				value: encodeXmlText$1(entry.linked.sectionName)
+			});
+			entry.section.children.push({
+				type: "element",
+				tag: "text:section-source",
+				attributes: sourceAttributes,
+				children: []
+			});
+		}
+	}
 };
 var OdtEditor = class {
 	body;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js.documents",
-  "version": "7.16.2",
+  "version": "7.17.0",
   "description": "Bidirectional docx/pptx <-> PDF conversion and a read+write editable OOXML document model, built on ooxml.js and Zod 4 codecs.",
   "type": "module",
   "repository": {