@cj-tech-master/excelts 9.6.1 → 10.0.0

package/dist/browser/modules/word/reader/docx-reader.js

@@ -6,7 +6,7 @@
  */
 import { unzip } from "../../archive/read-archive.js";
 import { parseXml, findChild, textContent } from "../../xml/dom.js";
-import { RelType } from "../constants.js";
+import { RelType, ContentType } from "../constants.js";
 import { utf8Decoder } from "../core/internal-utils.js";
 import { isRun } from "../core/text-utils.js";
 import { DocxError, DocxParseError, DocxMissingPartError, DocxEncryptedError, DocxLimitExceededError } from "../errors.js";
@@ -2457,6 +2457,107 @@ async function _readDocxInner(buffer, policy) {
             break;
         }
     }
+    // Extract OLE embedded objects wired on document.xml.rels. We surface
+    // them as structured `oleObjects` so callers can query/round-trip them
+    // (getOleObjectData/extractOleObjects) without depending on the part's
+    // own .rels (OLE binaries carry no .rels — their relationship lives on
+    // document.xml.rels). The body still references each object through an
+    // opaqueDrawing carrying the same r:id. Honours `preserveOleObjects`.
+    let oleObjects;
+    if (policy.preserveOleObjects) {
+        const collected = [];
+        // progId may be recoverable from the body's <o:OLEObject ProgID="…">.
+        // The <w:object> markup is preserved either as a body-level opaqueDrawing
+        // or (more commonly) as a run-level opaqueRun inside a paragraph. Collect
+        // raw XML from both so the ProgID round-trips.
+        const progIdByRId = new Map();
+        const scanOleMarkup = (rawXml) => {
+            // Match ProgID + r:id from within the same <o:OLEObject> element so a
+            // preview <v:imagedata r:id="…"> earlier in the markup is not mistaken
+            // for the OLE binary's relationship id.
+            const oleTagRe = /<o:OLEObject\b[^>]*>/gi;
+            let m;
+            while ((m = oleTagRe.exec(rawXml)) !== null) {
+                const tag = m[0];
+                const progMatch = tag.match(/ProgID="([^"]+)"/i);
+                const ridMatch = tag.match(/r:id="([^"]+)"/i);
+                if (progMatch && ridMatch) {
+                    progIdByRId.set(ridMatch[1], progMatch[1]);
+                }
+            }
+        };
+        for (const item of body) {
+            if (item.type === "opaqueDrawing") {
+                scanOleMarkup(item.rawXml);
+            }
+            else if (item.type === "paragraph") {
+                for (const child of item.children) {
+                    if (isRun(child)) {
+                        for (const rc of child.content) {
+                            if (rc.type === "opaqueRun") {
+                                scanOleMarkup(rc.rawXml);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        for (const rel of docRels) {
+            if (rel.type !== RelType.Package) {
+                continue;
+            }
+            const olePath = resolvePartPath(documentPartPath, rel.target);
+            if (!olePath.startsWith("word/embeddings/")) {
+                continue;
+            }
+            const oleData = entries.get(olePath);
+            if (!oleData) {
+                continue;
+            }
+            consumedPaths.add(olePath);
+            collected.push({
+                path: olePath,
+                data: oleData,
+                rId: rel.id,
+                progId: progIdByRId.get(rel.id),
+                contentType: ContentType.OleObject
+            });
+        }
+        if (collected.length > 0) {
+            oleObjects = collected;
+        }
+    }
+    // Glossary document (Building Blocks). The glossary is a self-contained
+    // sub-document: word/glossary/document.xml plus its own companion parts
+    // (styles/settings/webSettings/fontTable) referenced from
+    // word/glossary/_rels/document.xml.rels. We carry document.xml verbatim as
+    // `rawXml` and ALL sibling glossary parts (including the .rels) verbatim in
+    // `rawParts`, so a read→write round-trip re-emits a complete, Word-valid
+    // glossary rather than dropping it (opaqueParts would lose both the
+    // glossaryDocument relationship and the companion .rels). The structured
+    // `blocks` are not reverse-parsed.
+    let glossary;
+    for (const rel of docRels) {
+        if (rel.type !== RelType.Glossary) {
+            continue;
+        }
+        const glossaryPath = resolvePartPath(documentPartPath, rel.target);
+        const glossaryData = entries.get(glossaryPath);
+        if (glossaryData) {
+            // Collect every word/glossary/** part (document.xml, its .rels and all
+            // companions) verbatim, and mark them consumed so they are not also
+            // emitted via opaqueParts.
+            const rawParts = new Map();
+            for (const [path, data] of entries) {
+                if (path.startsWith("word/glossary/")) {
+                    rawParts.set(path, data);
+                    consumedPaths.add(path);
+                }
+            }
+            glossary = { blocks: [], rawXml: decoder.decode(glossaryData), rawParts };
+        }
+        break;
+    }
     // Resolve altChunk data: body elements of type "altChunk" reference a rId.
     // The target file is stored in docRels + entries. We populate the altChunk
     // body item with its data here AND mark the target path as consumed so the
@@ -2575,6 +2676,8 @@ async function _readDocxInner(buffer, policy) {
         theme,
         watermark,
         opaqueParts: opaqueParts.length > 0 ? opaqueParts : undefined,
-        vbaProject
+        vbaProject,
+        oleObjects,
+        glossary
     };
 }

package/dist/browser/modules/word/reader/math-parser.js

@@ -122,8 +122,14 @@ function parseMathContent(el) {
                         const v = mathAttrVal(el, "val");
                         return v !== "0" && v !== "false";
                     };
-                    if (boolAttr("show")) {
-                        ph.show = true;
+                    // `show` is tri-state: it may be explicitly off (`m:val="0"`), which
+                    // is what makes a phantom invisible, explicitly on, or absent
+                    // (defaults to on). Preserve an explicit value so a round-trip keeps
+                    // the invisibility, but leave it unset when the element is absent.
+                    const showEl = findMathChild(phantPrEl, "show");
+                    if (showEl) {
+                        const v = mathAttrVal(showEl, "val");
+                        ph.show = v !== "0" && v !== "false";
                     }
                     if (boolAttr("zeroWid")) {
                         ph.zeroWidth = true;

package/dist/browser/modules/word/security/cfb-reader.js

@@ -336,9 +336,8 @@ export function writeCfb(entries) {
     const miniNodes = streamNodes.filter(n => n.size > 0 && n.size < MINI_STREAM_CUTOFF);
     const regularNodes = streamNodes.filter(n => n.size >= MINI_STREAM_CUTOFF);
     // Assemble the mini-stream and the mini-FAT.
-    let miniStream = new Uint8Array(0);
     const miniFat = [];
-    {
+    const miniStream = (() => {
         const parts = [];
         let miniSectorIdx = 0;
         let totalLen = 0;
@@ -354,13 +353,14 @@ export function writeCfb(entries) {
             parts.push(padded);
             totalLen += padded.length;
         }
-        miniStream = new Uint8Array(totalLen);
+        const stream = new Uint8Array(totalLen);
         let off = 0;
         for (const p of parts) {
-            miniStream.set(p, off);
+            stream.set(p, off);
             off += p.length;
         }
-    }
+        return stream;
+    })();
     root.size = miniStream.length;
     // ---------------------------------------------------------------------------
     // 4. Lay out regular sectors.

package/dist/browser/modules/word/types.d.ts

@@ -1283,7 +1283,13 @@ export interface MathPreSubSuperScript {
 export interface MathPhantom {
     readonly type: "mathPhantom";
     readonly content: readonly MathContent[];
-    /** Phantom shows up in the layout (default: false). */
+    /**
+     * Whether the phantom's base content is drawn. In OOXML `m:show` defaults to
+     * ON, so the base stays visible unless this is explicitly set to `false`
+     * (serialized as `<m:show m:val="0"/>`). Set `false` for the classic
+     * "occupies space but invisible" phantom; leave undefined to keep the
+     * default (visible) behaviour.
+     */
     readonly show?: boolean;
     /** Zero width (default: false). */
     readonly zeroWidth?: boolean;
@@ -1714,6 +1720,10 @@ export interface ImageWatermark {
     readonly scale?: number;
     /** Washout effect. */
     readonly washout?: boolean;
+    /** Display width in points. Defaults to 415.2pt (full body width). */
+    readonly widthPt?: number;
+    /** Display height in points. Defaults to 415.2pt scaled to image ratio, or 233.5pt. */
+    readonly heightPt?: number;
 }
 /** Watermark (text or image). */
 export type Watermark = TextWatermark | ImageWatermark;
@@ -2403,6 +2413,39 @@ export interface PersonInfo {
  * - "macroEnabledTemplate" — .dotm (macro-enabled template)
  */
 export type DocxDocumentType = "document" | "template" | "macroEnabledDocument" | "macroEnabledTemplate";
+/** Building block gallery category. */
+export type BuildingBlockGallery = "autoText" | "quickParts" | "coverPages" | "tableOfContents" | "headers" | "footers" | "pageNumbers" | "tables" | "textBoxes" | "watermarks" | "equations" | "bibliographies" | "custom1" | "custom2" | "custom3" | "custom4" | "custom5";
+/** A single building block (AutoText/Quick Part) entry. */
+export interface BuildingBlock {
+    /** Name of the building block (displayed in gallery). */
+    readonly name: string;
+    /** Gallery this block belongs to. */
+    readonly gallery: BuildingBlockGallery;
+    /** Category within the gallery. */
+    readonly category?: string;
+    /** Description/tooltip. */
+    readonly description?: string;
+    /** The content of the building block. */
+    readonly content: readonly BodyContent[];
+    /** Section properties specific to this building block. */
+    readonly sectionProperties?: SectionProperties;
+    /** Unique identifier (GUID). */
+    readonly guid?: string;
+}
+/** The glossary document model. */
+export interface GlossaryDocument {
+    /** Building block entries. */
+    readonly blocks: readonly BuildingBlock[];
+    /** Raw parts preserved for round-trip (style, settings, fontTable). */
+    readonly rawParts?: ReadonlyMap<string, Uint8Array>;
+    /**
+     * Verbatim `word/glossary/document.xml` markup. Populated by the reader so a
+     * read→write round-trip preserves the glossary byte-faithfully even though
+     * the structured `blocks` are not reverse-parsed. When present the writer
+     * emits this verbatim and ignores `blocks`.
+     */
+    readonly rawXml?: string;
+}
 export interface DocxDocument {
     /**
      * Document type. Determines the content type used in the package.
@@ -2468,6 +2511,24 @@ export interface DocxDocument {
     readonly opaqueParts?: readonly OpaquePart[];
     /** VBA project binary (word/vbaProject.bin) for .docm/.dotm round-trip. */
     readonly vbaProject?: Uint8Array;
+    /**
+     * OLE embedded objects wired into the document. Unlike a bare
+     * {@link OpaquePart}, each entry here is registered by the packager as a
+     * relationship on `word/_rels/document.xml.rels` (so the `r:id` used by the
+     * body `<w:object>`/`<o:OLEObject>` markup actually resolves) and gets a
+     * `[Content_Types].xml` override. The body still references the object via
+     * an {@link OpaqueDrawing} carrying the matching `r:id`. Mirrors the
+     * `vbaProject` model-field pattern.
+     */
+    readonly oleObjects?: readonly OleObjectPart[];
+    /**
+     * Glossary document (Building Blocks / AutoText / Quick Parts). When set,
+     * the packager serialises it to `word/glossary/document.xml`, registers the
+     * `glossaryDocument` relationship on `document.xml.rels`, and adds the
+     * `[Content_Types].xml` override — the canonical OOXML location Word reads
+     * Quick Parts from.
+     */
+    readonly glossary?: GlossaryDocument;
 }
 /** A relationship entry preserved for round-trip. */
 export interface OpaqueRelationship {
@@ -2508,6 +2569,40 @@ export interface OpaquePart {
     /** Relationships of this part (from its .rels file). */
     readonly relationships?: readonly OpaqueRelationship[];
 }
+/**
+ * An OLE embedded object that the packager wires into the main document.
+ *
+ * The binary is written at {@link path}, a relationship with the exact
+ * {@link rId} is registered on `word/_rels/document.xml.rels` (so body
+ * `<w:object r:id="…">` markup resolves), and a `[Content_Types].xml`
+ * override is added. An optional preview image is wired the same way.
+ */
+export interface OleObjectPart {
+    /** Part path of the OLE binary (e.g. "word/embeddings/oleObject1.bin"). */
+    readonly path: string;
+    /** Raw OLE binary data (ideally an OLE2 compound document). */
+    readonly data: Uint8Array;
+    /**
+     * Relationship ID referenced from the body markup. Registered verbatim on
+     * the document relationships so the reference always resolves.
+     */
+    readonly rId: string;
+    /** OLE ProgId (e.g. "Excel.Sheet.12", "Package"). Carried for round-trip. */
+    readonly progId?: string;
+    /**
+     * Content type for the binary. Defaults to
+     * `application/vnd.openxmlformats-officedocument.oleObject`.
+     */
+    readonly contentType?: string;
+    /** Optional preview image part path (e.g. "word/media/oleImage1.png"). */
+    readonly previewPath?: string;
+    /** Preview image bytes (when {@link previewPath} is set). */
+    readonly previewData?: Uint8Array;
+    /** Relationship ID for the preview image, registered on the document. */
+    readonly previewRId?: string;
+    /** Content type for the preview image (e.g. "image/png"). */
+    readonly previewContentType?: string;
+}
 /** An opaque drawing element (e.g. chart) preserved in a paragraph. */
 export interface OpaqueDrawing {
     readonly type: "opaqueDrawing";

package/dist/browser/modules/word/writer/docx-packager.js

@@ -20,6 +20,7 @@ import { renderComments, renderCommentsExtended } from "./comment-writer.js";
 import { createContentTypes, addContentTypeDefault, addContentTypeOverride, addImageContentTypeDefaults, renderContentTypes } from "./content-types.js";
 import { renderDocument } from "./document-writer.js";
 import { renderFootnotes, renderEndnotes } from "./footnote-writer.js";
+import { renderGlossaryDocument } from "./glossary-writer.js";
 import { renderHeader, renderFooter, renderWatermarkHeader } from "./header-footer-writer.js";
 import { renderNumbering } from "./numbering-writer.js";
 import { renderSettings, renderFontTable, renderCoreProperties, renderAppProperties, renderCustomProperties, renderWebSettings, renderPeople, renderTheme } from "./parts-writer.js";
@@ -1083,7 +1084,13 @@ async function _packageDocxInner(doc, options) {
     // word/styles.xml
     archive.add(PartPath.Styles, renderXml(xml => renderStyles(xml, doc.docDefaults, doc.styles)));
     // word/settings.xml
-    archive.add(PartPath.Settings, renderXml(xml => renderSettings(xml, doc.settings, rawXmlPolicy)));
+    // When the document defines a page background, Word only paints it if
+    // <w:displayBackgroundShape/> is present in settings. Inject it
+    // automatically so setBackground() actually shows up on screen.
+    const settingsForRender = doc.background && !doc.settings?.displayBackgroundShape
+        ? { ...(doc.settings ?? {}), displayBackgroundShape: true }
+        : doc.settings;
+    archive.add(PartPath.Settings, renderXml(xml => renderSettings(xml, settingsForRender, rawXmlPolicy)));
     // word/fontTable.xml
     archive.add(PartPath.FontTable, renderXml(xml => renderFontTable(xml, doc.fonts)));
     // word/fonts/*.odttf (embedded fonts)
@@ -1345,6 +1352,81 @@ async function _packageDocxInner(doc, options) {
         addRelationship(documentRels, RelType.VbaProject, "vbaProject.bin");
         addContentTypeOverride(contentTypes, "/word/vbaProject.bin", ContentType.VbaProject);
     }
+    // OLE embedded objects (word/embeddings/*.bin + optional preview media).
+    // Each object is registered with the *exact* rId referenced from the body
+    // `<w:object r:id="…">` markup, so the reference always resolves. The
+    // `preserveOleObjects` security policy can still strip the binaries below.
+    if (doc.oleObjects && securityPolicy.preserveOleObjects) {
+        for (const ole of doc.oleObjects) {
+            archive.add(ole.path, ole.data);
+            // Target is relative to word/ (document.xml lives in word/).
+            const oleTarget = ole.path.replace(/^word\//, "");
+            addRelationshipWithId(documentRels, ole.rId, RelType.Package, oleTarget);
+            addContentTypeOverride(contentTypes, `/${ole.path}`, ole.contentType ?? ContentType.OleObject);
+            if (ole.previewPath && ole.previewData && ole.previewRId) {
+                archive.add(ole.previewPath, ole.previewData);
+                addRelationshipWithId(documentRels, ole.previewRId, RelType.Image, ole.previewPath.replace(/^word\//, ""));
+                if (ole.previewContentType) {
+                    addContentTypeOverride(contentTypes, `/${ole.previewPath}`, ole.previewContentType);
+                }
+                else {
+                    const ext = getFileExt(ole.previewPath);
+                    const inferred = ext ? inferContentType(ext) : undefined;
+                    if (inferred) {
+                        addContentTypeOverride(contentTypes, `/${ole.previewPath}`, inferred);
+                    }
+                }
+            }
+        }
+    }
+    // word/glossary/document.xml (Building Blocks / AutoText / Quick Parts).
+    //
+    // A glossary is a self-contained sub-document: Word expects it to carry its
+    // own styles / settings / webSettings / fontTable parts (referenced from
+    // word/glossary/_rels/document.xml.rels) rather than sharing the main
+    // document's. Omitting them makes Word discard the whole glossary on open.
+    //
+    //  - Round-tripped glossary (`rawParts` set): re-emit every captured
+    //    word/glossary/** part verbatim (document.xml, its .rels, companions).
+    //  - Freshly-built glossary: synthesise document.xml + the companion parts
+    //    + the glossary's own .rels, reusing the main document's styles/fonts so
+    //    block content (e.g. Heading1) resolves.
+    if (doc.glossary && (doc.glossary.rawXml || doc.glossary.blocks.length > 0)) {
+        addRelationship(documentRels, RelType.Glossary, "glossary/document.xml");
+        if (doc.glossary.rawParts && doc.glossary.rawParts.size > 0) {
+            for (const [path, data] of doc.glossary.rawParts) {
+                archive.add(path, data);
+                if (path.endsWith(".rels")) {
+                    continue; // .rels parts are typed by the Default rels content type
+                }
+                const ct = path === "word/glossary/document.xml"
+                    ? ContentType.Glossary
+                    : inferContentType(getFileExt(path));
+                if (ct) {
+                    addContentTypeOverride(contentTypes, `/${path}`, ct);
+                }
+            }
+        }
+        else {
+            archive.add("word/glossary/document.xml", renderGlossaryDocument(doc.glossary));
+            addContentTypeOverride(contentTypes, "/word/glossary/document.xml", ContentType.Glossary);
+            // Synthesise the companion sub-document parts + the glossary's own rels.
+            const glossaryRels = createRelationships();
+            addRelationshipWithId(glossaryRels, "rId1", RelType.Styles, "styles.xml");
+            addRelationshipWithId(glossaryRels, "rId2", RelType.Settings, "settings.xml");
+            addRelationshipWithId(glossaryRels, "rId3", RelType.WebSettings, "webSettings.xml");
+            addRelationshipWithId(glossaryRels, "rId4", RelType.FontTable, "fontTable.xml");
+            archive.add("word/glossary/_rels/document.xml.rels", renderXml(xml => renderRelationships(glossaryRels, xml)));
+            archive.add("word/glossary/styles.xml", renderXml(xml => renderStyles(xml, doc.docDefaults, doc.styles)));
+            archive.add("word/glossary/settings.xml", renderXml(xml => renderSettings(xml, undefined, rawXmlPolicy)));
+            archive.add("word/glossary/webSettings.xml", renderXml(xml => renderWebSettings(xml, undefined, rawXmlPolicy)));
+            archive.add("word/glossary/fontTable.xml", renderXml(xml => renderFontTable(xml, doc.fonts)));
+            addContentTypeOverride(contentTypes, "/word/glossary/styles.xml", ContentType.Styles);
+            addContentTypeOverride(contentTypes, "/word/glossary/settings.xml", ContentType.Settings);
+            addContentTypeOverride(contentTypes, "/word/glossary/webSettings.xml", ContentType.WebSettings);
+            addContentTypeOverride(contentTypes, "/word/glossary/fontTable.xml", ContentType.FontTable);
+        }
+    }
     // Write opaque (unrecognized) parts for round-trip preservation.
     //
     // Opaque parts are written as-is into the ZIP. Their paths must not
@@ -1385,8 +1467,23 @@ async function _packageDocxInner(doc, options) {
             PartPath.CustomProps,
             PartPath.Thumbnail,
             "word/vbaProject.bin",
-            "word/_rels/vbaProject.bin.rels"
+            "word/_rels/vbaProject.bin.rels",
+            "word/glossary/document.xml",
+            "word/glossary/_rels/document.xml.rels"
         ]);
+        // Glossary sub-document parts (emitted either verbatim from rawParts or
+        // synthesised); reserve them so opaqueParts can't collide.
+        if (doc.glossary && (doc.glossary.rawXml || doc.glossary.blocks.length > 0)) {
+            reservedExact.add("word/glossary/styles.xml");
+            reservedExact.add("word/glossary/settings.xml");
+            reservedExact.add("word/glossary/webSettings.xml");
+            reservedExact.add("word/glossary/fontTable.xml");
+            if (doc.glossary.rawParts) {
+                for (const path of doc.glossary.rawParts.keys()) {
+                    reservedExact.add(path);
+                }
+            }
+        }
         // Headers/footers we are emitting in this run.
         if (doc.headers) {
             let i = 1;
@@ -1430,6 +1527,15 @@ async function _packageDocxInner(doc, options) {
                 }
             }
         }
+        // OLE embedded objects emitted by this run.
+        if (doc.oleObjects) {
+            for (const ole of doc.oleObjects) {
+                reservedExact.add(ole.path);
+                if (ole.previewPath) {
+                    reservedExact.add(ole.previewPath);
+                }
+            }
+        }
         for (const part of doc.opaqueParts) {
             if (reservedExact.has(part.path)) {
                 throw new DocxWriteError(`Opaque part path "${part.path}" conflicts with a part the packager ` +

package/dist/browser/modules/word/writer/glossary-writer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DOCX Module — Glossary (Building Blocks) Part Writer
+ *
+ * Serialises a {@link GlossaryDocument} into the canonical
+ * `word/glossary/document.xml` OOXML form:
+ *
+ * ```xml
+ * <w:glossaryDocument>
+ *   <w:docParts>
+ *     <w:docPart>
+ *       <w:docPartPr>
+ *         <w:name w:val="…"/>
+ *         <w:category><w:name w:val="…"/><w:gallery w:val="…"/></w:category>
+ *         <w:behaviors><w:behavior w:val="content"/></w:behaviors>
+ *         <w:guid w:val="{…}"/>
+ *       </w:docPartPr>
+ *       <w:docPartBody>… body content …</w:docPartBody>
+ *     </w:docPart>
+ *   </w:docParts>
+ * </w:glossaryDocument>
+ * ```
+ *
+ * Lives in the writer layer (not `advanced/`) so the packager can depend on
+ * it without creating a `advanced/ → writer/` import cycle.
+ */
+import type { GlossaryDocument } from "../types.js";
+/** Render a {@link GlossaryDocument} to a `word/glossary/document.xml` string. */
+export declare function renderGlossaryDocument(glossary: GlossaryDocument): string;

package/dist/browser/modules/word/writer/glossary-writer.js

@@ -0,0 +1,121 @@
+/**
+ * DOCX Module — Glossary (Building Blocks) Part Writer
+ *
+ * Serialises a {@link GlossaryDocument} into the canonical
+ * `word/glossary/document.xml` OOXML form:
+ *
+ * ```xml
+ * <w:glossaryDocument>
+ *   <w:docParts>
+ *     <w:docPart>
+ *       <w:docPartPr>
+ *         <w:name w:val="…"/>
+ *         <w:category><w:name w:val="…"/><w:gallery w:val="…"/></w:category>
+ *         <w:behaviors><w:behavior w:val="content"/></w:behaviors>
+ *         <w:guid w:val="{…}"/>
+ *       </w:docPartPr>
+ *       <w:docPartBody>… body content …</w:docPartBody>
+ *     </w:docPart>
+ *   </w:docParts>
+ * </w:glossaryDocument>
+ * ```
+ *
+ * Lives in the writer layer (not `advanced/`) so the packager can depend on
+ * it without creating a `advanced/ → writer/` import cycle.
+ */
+import { XmlWriter } from "../../xml/writer.js";
+import { DOCUMENT_NAMESPACES, STD_DOC_ATTRIBUTES } from "../constants.js";
+import { renderBodyContent } from "./document-writer.js";
+/**
+ * Map the friendly {@link BuildingBlockGallery} token to the OOXML
+ * `ST_DocPartGallery` value used in `<w:gallery w:val="…">` (ECMA-376
+ * §17.18.23). Values MUST be exact enum members — Word rejects (and silently
+ * discards) the entire glossary if it sees an out-of-enum gallery value.
+ * There is no plain "quickParts" value; Quick Parts map to "custQuickParts".
+ */
+const GALLERY_TO_OOXML = {
+    autoText: "autoTxt",
+    quickParts: "custQuickParts",
+    coverPages: "coverPg",
+    tableOfContents: "tblOfContents",
+    headers: "hdrs",
+    footers: "ftrs",
+    pageNumbers: "pgNum",
+    tables: "tbls",
+    textBoxes: "txtBox",
+    watermarks: "watermarks",
+    equations: "eq",
+    bibliographies: "bib",
+    custom1: "custom1",
+    custom2: "custom2",
+    custom3: "custom3",
+    custom4: "custom4",
+    custom5: "custom5"
+};
+/** Render a {@link GlossaryDocument} to a `word/glossary/document.xml` string. */
+export function renderGlossaryDocument(glossary) {
+    // Byte-faithful round-trip: a glossary read from an existing document is
+    // carried as verbatim XML and re-emitted unchanged.
+    if (glossary.rawXml) {
+        return glossary.rawXml;
+    }
+    const writer = new XmlWriter();
+    renderGlossary(writer, glossary);
+    return writer.xml;
+}
+function renderGlossary(xml, glossary) {
+    xml.openXml(STD_DOC_ATTRIBUTES);
+    xml.openNode("w:glossaryDocument", DOCUMENT_NAMESPACES);
+    xml.openNode("w:docParts");
+    for (const block of glossary.blocks) {
+        renderDocPart(xml, block);
+    }
+    xml.closeNode(); // w:docParts
+    xml.closeNode(); // w:glossaryDocument
+}
+function renderDocPart(xml, block) {
+    xml.openNode("w:docPart");
+    // CT_DocPartPr — child order is fixed by the schema (ECMA-376 §17.12.1):
+    // name → style → category → types → behaviors → description → guid.
+    // Emitting these out of order makes Word reject the package on open.
+    xml.openNode("w:docPartPr");
+    xml.leafNode("w:name", { "w:val": block.name });
+    xml.openNode("w:category");
+    xml.leafNode("w:name", { "w:val": block.category ?? "General" });
+    xml.leafNode("w:gallery", { "w:val": GALLERY_TO_OOXML[block.gallery] ?? "placeholder" });
+    xml.closeNode(); // w:category
+    // `<w:types>` is optional; we omit it so we never emit an out-of-enum
+    // ST_DocPartType value. A docPart placed in the body inserts its content.
+    xml.openNode("w:behaviors");
+    xml.leafNode("w:behavior", { "w:val": "content" });
+    xml.closeNode(); // w:behaviors
+    if (block.description) {
+        xml.leafNode("w:description", { "w:val": block.description });
+    }
+    if (block.guid) {
+        xml.leafNode("w:guid", { "w:val": normaliseGuid(block.guid) });
+    }
+    xml.closeNode(); // w:docPartPr
+    // docPartBody — reuse the main body renderer. A fresh render context keeps
+    // id counters local; building-block content here is plain text/tables so it
+    // does not need image/chart rId remapping.
+    xml.openNode("w:docPartBody");
+    for (const item of block.content) {
+        renderBodyContent(xml, item);
+    }
+    // CT_Body must end with a paragraph; emit one if the block had no content.
+    if (block.content.length === 0) {
+        xml.openNode("w:p");
+        xml.closeNode();
+    }
+    xml.closeNode(); // w:docPartBody
+    xml.closeNode(); // w:docPart
+}
+/** Word expects the docPart guid wrapped in braces: `{XXXXXXXX-…}`. */
+function normaliseGuid(guid) {
+    const trimmed = guid.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+        return trimmed;
+    }
+    return `{${trimmed}}`;
+}