@cj-tech-master/excelts 9.6.1 → 10.0.0

package/dist/browser/modules/pdf/builder/pdf-editor.js

@@ -144,7 +144,7 @@ export class PdfEditorPage {
     }
     /** @internal */
     _hasOverlay() {
-        return (this._overlay._stream.toString().length > 0 ||
+        return (this._overlay._stream.hasContent() ||
             this._overlay._images.length > 0 ||
             this._overlay._builderAnnotations.length > 0 ||
             this._overlay._formFields.length > 0);

package/dist/browser/modules/pdf/core/pdf-stream.d.ts

@@ -19,12 +19,30 @@ import type { PdfColor } from "../types.js";
  * and non-stroking (fills/text). We provide methods for both.
  */
 export declare class PdfContentStream {
+    /**
+     * Content stream fragments in draw order. Most entries are plain operator
+     * strings produced eagerly. A function entry is a *deferred* fragment:
+     * its body is only evaluated at serialization time. This is required for
+     * text whose final byte encoding depends on font decisions (embedded
+     * CIDFont vs. Type1/WinAnsi vs. Type3 fallback) that are not finalised
+     * until `PdfDocumentBuilder.build()`. Deferring keeps the fragment at its
+     * exact draw-order position (preserving z-order) while letting the actual
+     * encoding run after the font manager's state is settled.
+     */
     private parts;
     /**
      * Append a raw PDF operator string to the content stream.
      * Use this for operators not covered by the typed API (e.g. `d1` for Type3 glyphs).
      */
     raw(operator: string): this;
+    /**
+     * Append a deferred fragment whose body is evaluated only at serialization
+     * time. Used by text drawing so the final byte encoding can be chosen after
+     * the document's fonts are resolved at build time. The fragment occupies its
+     * draw-order slot immediately, so z-order relative to other operators is
+     * preserved.
+     */
+    deferred(produce: () => string): this;
     /**
      * Save the current graphics state (push onto state stack).
      * Must be balanced with a corresponding restore().
@@ -222,7 +240,16 @@ export declare class PdfContentStream {
      */
     roundedRect(x: number, y: number, width: number, height: number, r: number): this;
     /**
-     * Get the content stream as a string.
+     * Whether any fragment has been appended. Unlike `toString().length > 0`,
+     * this does NOT evaluate deferred fragments, so it is safe to call before
+     * fonts are resolved (e.g. when probing for overlay content during an
+     * editor save, prior to `writeFontResources`). A deferred text fragment
+     * counts as content even though its bytes are not produced yet.
+     */
+    hasContent(): boolean;
+    /**
+     * Get the content stream as a string. Deferred fragments (see `deferred`)
+     * are evaluated here, after font resolution has completed at build time.
      */
     toString(): string;
     /**

package/dist/browser/modules/pdf/core/pdf-stream.js

@@ -23,6 +23,16 @@ import { pdfNumber } from "./pdf-object.js";
  */
 export class PdfContentStream {
     constructor() {
+        /**
+         * Content stream fragments in draw order. Most entries are plain operator
+         * strings produced eagerly. A function entry is a *deferred* fragment:
+         * its body is only evaluated at serialization time. This is required for
+         * text whose final byte encoding depends on font decisions (embedded
+         * CIDFont vs. Type1/WinAnsi vs. Type3 fallback) that are not finalised
+         * until `PdfDocumentBuilder.build()`. Deferring keeps the fragment at its
+         * exact draw-order position (preserving z-order) while letting the actual
+         * encoding run after the font manager's state is settled.
+         */
         this.parts = [];
     }
     // ===========================================================================
@@ -36,6 +46,17 @@ export class PdfContentStream {
         this.parts.push(operator);
         return this;
     }
+    /**
+     * Append a deferred fragment whose body is evaluated only at serialization
+     * time. Used by text drawing so the final byte encoding can be chosen after
+     * the document's fonts are resolved at build time. The fragment occupies its
+     * draw-order slot immediately, so z-order relative to other operators is
+     * preserved.
+     */
+    deferred(produce) {
+        this.parts.push(produce);
+        return this;
+    }
     // ===========================================================================
     // Graphics State
     // ===========================================================================
@@ -435,10 +456,25 @@ export class PdfContentStream {
     // Serialization
     // ===========================================================================
     /**
-     * Get the content stream as a string.
+     * Whether any fragment has been appended. Unlike `toString().length > 0`,
+     * this does NOT evaluate deferred fragments, so it is safe to call before
+     * fonts are resolved (e.g. when probing for overlay content during an
+     * editor save, prior to `writeFontResources`). A deferred text fragment
+     * counts as content even though its bytes are not produced yet.
+     */
+    hasContent() {
+        return this.parts.length > 0;
+    }
+    /**
+     * Get the content stream as a string. Deferred fragments (see `deferred`)
+     * are evaluated here, after font resolution has completed at build time.
      */
     toString() {
-        return this.parts.join("\n");
+        const out = [];
+        for (const part of this.parts) {
+            out.push(typeof part === "function" ? part() : part);
+        }
+        return out.join("\n");
     }
     /**
      * Get the content stream as a Uint8Array (UTF-8 encoded).

package/dist/browser/modules/pdf/font/font-manager.d.ts

@@ -76,9 +76,35 @@ export declare class FontManager {
      * Get the embedded font's resource name (if registered).
      */
     getEmbeddedResourceName(): string;
+    /**
+     * Resolve the resource name a draw-time-resolved Type1 resource should
+     * actually render (and be measured) with, given the font manager's
+     * *current* state. If an embedded font exists (possibly auto-discovered
+     * at build time, after the text was drawn against a Type1 resource), the
+     * embedded resource name is returned so both measurement and encoding go
+     * through the CIDFont. Otherwise the original Type1 resource name is kept;
+     * `measureText` handles Type3-fallback widths internally from that name.
+     *
+     * Centralises the routing rule shared by the deferred text renderer and
+     * any deferred measurement (anchor alignment, word wrapping) so the two
+     * never disagree.
+     */
+    resolveRenderResourceName(type1ResourceName: string): string;
     /**
      * Record that a text string will be rendered, tracking its code points.
      * Must be called for every text string before writing the PDF.
+     *
+     * Two sets are maintained because font selection may be decided *after*
+     * drawing (e.g. `PdfDocumentBuilder.build()` auto-discovers and embeds a
+     * system font once it sees the accumulated non-WinAnsi code points):
+     *
+     *   - `usedCodePoints` — every code point seen, always. If an embedded
+     *     font ends up being used (whether registered up front or
+     *     auto-discovered at build time), the subset must cover all of these,
+     *     including plain ASCII, so the CIDFont can encode the full run.
+     *   - `type3CodePoints` — non-WinAnsi code points only. Drives the
+     *     build-time decision to auto-embed a system font, and the Type3
+     *     fallback when none is available.
      */
     trackText(text: string): void;
     /**

package/dist/browser/modules/pdf/font/font-manager.js

@@ -182,30 +182,47 @@ export class FontManager {
     getEmbeddedResourceName() {
         return this.embeddedResourceName;
     }
+    /**
+     * Resolve the resource name a draw-time-resolved Type1 resource should
+     * actually render (and be measured) with, given the font manager's
+     * *current* state. If an embedded font exists (possibly auto-discovered
+     * at build time, after the text was drawn against a Type1 resource), the
+     * embedded resource name is returned so both measurement and encoding go
+     * through the CIDFont. Otherwise the original Type1 resource name is kept;
+     * `measureText` handles Type3-fallback widths internally from that name.
+     *
+     * Centralises the routing rule shared by the deferred text renderer and
+     * any deferred measurement (anchor alignment, word wrapping) so the two
+     * never disagree.
+     */
+    resolveRenderResourceName(type1ResourceName) {
+        return this.embeddedFont ? this.embeddedResourceName : type1ResourceName;
+    }
     /**
      * Record that a text string will be rendered, tracking its code points.
      * Must be called for every text string before writing the PDF.
+     *
+     * Two sets are maintained because font selection may be decided *after*
+     * drawing (e.g. `PdfDocumentBuilder.build()` auto-discovers and embeds a
+     * system font once it sees the accumulated non-WinAnsi code points):
+     *
+     *   - `usedCodePoints` — every code point seen, always. If an embedded
+     *     font ends up being used (whether registered up front or
+     *     auto-discovered at build time), the subset must cover all of these,
+     *     including plain ASCII, so the CIDFont can encode the full run.
+     *   - `type3CodePoints` — non-WinAnsi code points only. Drives the
+     *     build-time decision to auto-embed a system font, and the Type3
+     *     fallback when none is available.
      */
     trackText(text) {
-        if (this.embeddedFont) {
-            for (let i = 0; i < text.length; i++) {
-                const cp = text.codePointAt(i);
-                this.usedCodePoints.add(cp);
-                if (cp > 0xffff) {
-                    i++; // skip low surrogate
-                }
+        for (let i = 0; i < text.length; i++) {
+            const cp = text.codePointAt(i);
+            if (cp > 0xffff) {
+                i++; // skip low surrogate
             }
-        }
-        else {
-            // No embedded font — track non-WinAnsi chars for Type3 fallback
-            for (let i = 0; i < text.length; i++) {
-                const cp = text.codePointAt(i);
-                if (cp > 0xffff) {
-                    i++;
-                }
-                if (!isWinAnsiCodePoint(cp)) {
-                    this.type3CodePoints.add(cp);
-                }
+            this.usedCodePoints.add(cp);
+            if (!isWinAnsiCodePoint(cp)) {
+                this.type3CodePoints.add(cp);
             }
         }
     }

package/dist/browser/modules/pdf/render/page-renderer.d.ts

@@ -29,10 +29,58 @@ export declare function renderPage(page: LayoutPage, options: ResolvedPdfOptions
  * when needed.  For each sub-run the matrix origin is advanced along the
  * text direction (cos, sin) by the rendered width.
  *
- * When `useType3` is false this collapses to a single BT/ET pair — identical
- * to the old `emitText()` path but wrapped in begin/end for convenience.
+ * The emitted operators are written as a *deferred* fragment (see
+ * `PdfContentStream.deferred`). The fragment is only evaluated at
+ * serialization time, by which point `PdfDocumentBuilder.build()` has
+ * finalised the document's fonts (auto-discovered embedded CIDFont,
+ * Type3 fallback, or plain Type1). This is essential: at draw time the
+ * font manager has not yet decided whether a non-WinAnsi code point (e.g.
+ * U+2192 →) will be served by an embedded font or a Type3 glyph, so eager
+ * encoding would irreversibly degrade those characters to spaces via the
+ * WinAnsi fallback. Deferring the encode keeps the fragment at its exact
+ * draw-order slot (preserving z-order) while choosing the correct bytes
+ * once fonts are known.
+ *
+ * The `useType3` argument is the caller's *draw-time* guess and is ignored;
+ * the deferred body recomputes the routing from the now-settled font
+ * manager state.
+ */
+export declare function emitTextWithMatrix(stream: PdfContentStream, text: string, a: number, b: number, c: number, d: number, tx: number, ty: number, type1ResourceName: string, fontSize: number, fontManager: FontManager, _useType3: boolean): void;
+/** Options for a deferred, font-aware text block (see `emitTextBlock`). */
+export interface TextBlockOptions {
+    /** The text to draw (may contain `\n` when `maxWidth` is set). */
+    text: string;
+    /** Left/anchor x in unrotated page space. */
+    x: number;
+    /** Baseline y of the first line in unrotated page space. */
+    y: number;
+    /** Draw-time-resolved Type1 resource name; re-routed at build time. */
+    type1ResourceName: string;
+    fontSize: number;
+    /** Horizontal anchor; applied per line (including each wrapped line). */
+    anchor: "start" | "middle" | "end";
+    /** Word-wrap width in points; enables multi-line layout when set. */
+    maxWidth?: number;
+    /** Line-height multiple applied to `fontSize` for wrapped lines. */
+    lineHeightFactor: number;
+    /** Clockwise rotation in degrees about (x, y); applied to every line. */
+    rotation: number;
+}
+/**
+ * Emit a text block as a single *deferred* fragment so that anchor
+ * alignment, word wrapping, and glyph encoding are all computed at
+ * serialization time — after `PdfDocumentBuilder.build()` has finalised the
+ * document's fonts.
+ *
+ * This matters because text measurement (anchor offset, line breaking) must
+ * use the *same* font that ultimately renders the glyphs. At draw time the
+ * font may still be unresolved (a non-WinAnsi run can trigger a build-time
+ * auto-embed of a system CIDFont), so measuring against the provisional
+ * Type1/Helvetica metrics would misplace centred/right-aligned text and
+ * break lines at the wrong points. Deferring keeps measurement and encoding
+ * consistent while preserving the fragment's draw-order slot (z-order).
  */
-export declare function emitTextWithMatrix(stream: PdfContentStream, text: string, a: number, b: number, c: number, d: number, tx: number, ty: number, type1ResourceName: string, fontSize: number, fontManager: FontManager, useType3: boolean): void;
+export declare function emitTextBlock(stream: PdfContentStream, options: TextBlockOptions, fontManager: FontManager): void;
 /**
  * Generate a deterministic ExtGState resource name for a given alpha value.
  * Uses 4 decimal digits to avoid collisions between close alpha values.

package/dist/browser/modules/pdf/render/page-renderer.js

@@ -675,7 +675,7 @@ function drawRotatedGeneral(stream, cell, lines, fontManager, resourceName, font
         emitTextWithMatrix(stream, line, cos, sin, -sin, cos, tx, ty, resourceName, fontSize, fontManager, useType3);
     }
 }
-/** Emit a text string with hex encoding if available. */
+/** Emit a text string with hex encoding if available, onto a sink stream. */
 function emitText(stream, fontManager, text, resourceName) {
     const hex = fontManager.encodeText(text, resourceName);
     if (hex) {
@@ -690,40 +690,133 @@ function emitText(stream, fontManager, text, resourceName) {
  * when needed.  For each sub-run the matrix origin is advanced along the
  * text direction (cos, sin) by the rendered width.
  *
- * When `useType3` is false this collapses to a single BT/ET pair — identical
- * to the old `emitText()` path but wrapped in begin/end for convenience.
+ * The emitted operators are written as a *deferred* fragment (see
+ * `PdfContentStream.deferred`). The fragment is only evaluated at
+ * serialization time, by which point `PdfDocumentBuilder.build()` has
+ * finalised the document's fonts (auto-discovered embedded CIDFont,
+ * Type3 fallback, or plain Type1). This is essential: at draw time the
+ * font manager has not yet decided whether a non-WinAnsi code point (e.g.
+ * U+2192 →) will be served by an embedded font or a Type3 glyph, so eager
+ * encoding would irreversibly degrade those characters to spaces via the
+ * WinAnsi fallback. Deferring the encode keeps the fragment at its exact
+ * draw-order slot (preserving z-order) while choosing the correct bytes
+ * once fonts are known.
+ *
+ * The `useType3` argument is the caller's *draw-time* guess and is ignored;
+ * the deferred body recomputes the routing from the now-settled font
+ * manager state.
+ */
+export function emitTextWithMatrix(stream, text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager, _useType3) {
+    stream.deferred(() => renderTextBlock(text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager));
+}
+/**
+ * Emit a text block as a single *deferred* fragment so that anchor
+ * alignment, word wrapping, and glyph encoding are all computed at
+ * serialization time — after `PdfDocumentBuilder.build()` has finalised the
+ * document's fonts.
+ *
+ * This matters because text measurement (anchor offset, line breaking) must
+ * use the *same* font that ultimately renders the glyphs. At draw time the
+ * font may still be unresolved (a non-WinAnsi run can trigger a build-time
+ * auto-embed of a system CIDFont), so measuring against the provisional
+ * Type1/Helvetica metrics would misplace centred/right-aligned text and
+ * break lines at the wrong points. Deferring keeps measurement and encoding
+ * consistent while preserving the fragment's draw-order slot (z-order).
+ */
+export function emitTextBlock(stream, options, fontManager) {
+    stream.deferred(() => renderTextBlockLayout(options, fontManager));
+}
+/**
+ * Lay out and render a text block from the font manager's *current*
+ * (build-time) state. Resolves the render resource name once and uses it for
+ * both measurement and encoding so the two never disagree.
+ *
+ * Layout is computed in the text's *local* coordinate frame — x grows along
+ * the baseline, y grows upward — then mapped to page space through the
+ * rotation matrix. This makes anchor alignment, multi-line word wrapping, and
+ * rotation compose correctly together: each line is offset by its anchor
+ * shift (along local x) and its line index (down local y), and a single
+ * rotation maps the whole block into place. Upright text (rotation 0) reduces
+ * to the identity mapping.
+ */
+function renderTextBlockLayout(options, fontManager) {
+    const { text, x, y, type1ResourceName, fontSize, anchor, maxWidth, lineHeightFactor, rotation } = options;
+    // Resolve the resource name once; measurement and rendering share it so a
+    // build-time auto-embedded CIDFont (or Type3 fallback) is measured with the
+    // metrics that will actually render the glyphs.
+    const measureResource = fontManager.resolveRenderResourceName(type1ResourceName);
+    const measure = (s) => fontManager.measureText(s, measureResource, fontSize);
+    const lines = maxWidth ? wrapTextLines(text, measure, maxWidth) : [text];
+    const leading = fontSize * lineHeightFactor;
+    // Rotation matrix [a b; c d] = [cos sin; -sin cos]; identity when upright.
+    const theta = (rotation * Math.PI) / 180;
+    const cos = rotation === 0 ? 1 : Math.cos(theta);
+    const sin = rotation === 0 ? 0 : Math.sin(theta);
+    const anchorFactor = anchor === "middle" ? 0.5 : anchor === "end" ? 1 : 0;
+    const parts = [];
+    for (let i = 0; i < lines.length; i++) {
+        // Local-frame origin of this line: anchor shift along x, line index down y.
+        const localX = anchorFactor === 0 ? 0 : -measure(lines[i]) * anchorFactor;
+        const localY = -i * leading;
+        // Map local origin into page space through the rotation matrix.
+        const tx = x + localX * cos + localY * -sin;
+        const ty = y + localX * sin + localY * cos;
+        parts.push(renderTextBlock(lines[i], cos, sin, -sin, cos, tx, ty, type1ResourceName, fontSize, fontManager));
+    }
+    return parts.join("\n");
+}
+/**
+ * Produce the PDF operator string for a positioned text run, choosing the
+ * encoding from the font manager's *current* (build-time) state:
+ *   - embedded font  → single BT/ET with CIDFont hex encoding
+ *   - Type3 fallback → split into WinAnsi (Type1) and per-glyph Type3 runs
+ *   - neither        → single BT/ET with Type1/WinAnsi encoding
+ *
+ * Must only be called after font resolution (i.e. from a deferred fragment).
  */
-export function emitTextWithMatrix(stream, text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager, useType3) {
+function renderTextBlock(text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager) {
+    const sink = new PdfContentStream();
+    // Type3 splitting only applies when there is no embedded font but Type3
+    // fallback glyphs were generated. Otherwise the run renders as a single
+    // BT/ET pair, choosing the resource name from the now-settled state:
+    // if an embedded font exists (possibly auto-discovered at build time,
+    // after this run was drawn against a Type1 resource), the run must use it
+    // so `emitText` → `encodeText` produces CIDFont hex; without that switch
+    // the stale Type1 resource name would make `encodeText` return null and
+    // non-WinAnsi characters would degrade to spaces via the WinAnsi fallback.
+    const useType3 = fontManager.hasType3Fonts() && !fontManager.hasEmbeddedFont();
     if (!useType3) {
-        stream.beginText();
-        stream.setFont(type1ResourceName, fontSize);
-        stream.setTextMatrix(a, b, c, d, tx, ty);
-        emitText(stream, fontManager, text, type1ResourceName);
-        stream.endText();
-        return;
+        const resourceName = fontManager.resolveRenderResourceName(type1ResourceName);
+        sink.beginText();
+        sink.setFont(resourceName, fontSize);
+        sink.setTextMatrix(a, b, c, d, tx, ty);
+        emitText(sink, fontManager, text, resourceName);
+        sink.endText();
+        return sink.toString();
     }
     // Type3 path: split into runs and advance origin along text direction
     const runs = splitTextRuns(text, fontManager);
     let curTx = tx;
     let curTy = ty;
     for (const run of runs) {
-        stream.beginText();
+        sink.beginText();
         if (run.type3) {
-            stream.setFont(run.type3.resourceName, fontSize);
-            stream.setTextMatrix(a, b, c, d, curTx, curTy);
-            stream.showTextHex(run.type3.hex);
+            sink.setFont(run.type3.resourceName, fontSize);
+            sink.setTextMatrix(a, b, c, d, curTx, curTy);
+            sink.showTextHex(run.type3.hex);
         }
         else {
-            stream.setFont(type1ResourceName, fontSize);
-            stream.setTextMatrix(a, b, c, d, curTx, curTy);
-            emitText(stream, fontManager, run.text, type1ResourceName);
+            sink.setFont(type1ResourceName, fontSize);
+            sink.setTextMatrix(a, b, c, d, curTx, curTy);
+            emitText(sink, fontManager, run.text, type1ResourceName);
         }
-        stream.endText();
+        sink.endText();
         const w = fontManager.measureText(run.text, run.type3?.resourceName ?? type1ResourceName, fontSize);
         // Advance along the text direction (first column of the matrix)
         curTx += a * w;
         curTy += b * w;
     }
+    return sink.toString();
 }
 /**
  * Split a line of text into runs of consecutive WinAnsi and non-WinAnsi

package/dist/browser/modules/word/advanced/field-engine.js

@@ -42,7 +42,7 @@ export function updateFields(doc, options) {
     // Build style → paragraphs index for STYLEREF
     const styleIndex = buildStyleIndex(doc);
     // Collect INDEX entries (XE fields) from all body content
-    const indexEntries = collectIndexEntries(doc);
+    const indexEntries = collectIndexEntries(doc, layout);
     // Update body content
     const newBody = updateBody(doc, layout, bookmarkInfo, seqValues, styleIndex, indexEntries, opts);
     // If TOC was updated, register the TOC1..TOCn paragraph styles so the
@@ -610,23 +610,33 @@ function findStyleRef(styleIndex, styleName, bodyIndex) {
 // =============================================================================
 // Index Entry Collection (for INDEX field)
 // =============================================================================
-/** Collect all XE (Index Entry) fields from the document body. */
-function collectIndexEntries(doc) {
+/**
+ * Collect all XE (Index Entry) fields from the document body, tagging each
+ * with the page it falls on. Page numbers come from `layout.contentPages`
+ * keyed by the enclosing top-level body index (the same mechanism used for
+ * headings/TOC); entries inside nested structures inherit their outer block's
+ * page, falling back to 1 when layout produced no page for that block.
+ */
+function collectIndexEntries(doc, layout) {
     const entries = [];
-    walkBlocks(doc.body, {
-        visitRunContent(content) {
-            if (content.type !== "field") {
-                return;
-            }
-            const { type, args } = parseFieldInstruction(content.instruction);
-            if (type === "XE") {
-                const term = parseXeTerm(args);
-                if (term) {
-                    entries.push({ term, page: 1 });
+    const { contentPages } = layout;
+    for (let i = 0; i < doc.body.length; i++) {
+        const page = contentPages[i] ?? 1;
+        walkBlocks([doc.body[i]], {
+            visitRunContent(content) {
+                if (content.type !== "field") {
+                    return;
+                }
+                const { type, args } = parseFieldInstruction(content.instruction);
+                if (type === "XE") {
+                    const term = parseXeTerm(args);
+                    if (term) {
+                        entries.push({ term, page });
+                    }
                 }
             }
-        }
-    });
+        });
+    }
     return entries;
 }
 /** Parse the term from an XE field argument: XE "term" or XE term. */
@@ -643,17 +653,32 @@ function buildIndexContent(entries, args) {
     if (entries.length === 0) {
         return "";
     }
-    // Sort entries alphabetically by term
-    const sorted = [...entries].sort((a, b) => a.term.localeCompare(b.term));
+    // Merge entries that share the same term: a term marked on several pages
+    // produces a single index line listing each distinct page (Word behaviour),
+    // e.g. "widget, 1, 4" rather than two separate "widget" rows.
+    const byTerm = new Map();
+    for (const entry of entries) {
+        let pages = byTerm.get(entry.term);
+        if (!pages) {
+            pages = new Set();
+            byTerm.set(entry.term, pages);
+        }
+        pages.add(entry.page);
+    }
+    // Sort terms alphabetically; within each term sort pages numerically.
+    const merged = [...byTerm.entries()]
+        .map(([term, pages]) => ({ term, pages: [...pages].sort((a, b) => a - b) }))
+        .sort((a, b) => a.term.localeCompare(b.term));
+    const formatEntry = (e) => `${e.term}\t${e.pages.join(", ")}`;
     // Check for \h switch (group by first letter with headings)
     const grouped = /\\h\b/i.test(args);
     if (!grouped) {
-        return sorted.map(e => `${e.term}\t${e.page}`).join("\n");
+        return merged.map(formatEntry).join("\n");
     }
     // Group by first letter
     const lines = [];
     let currentLetter = "";
-    for (const entry of sorted) {
+    for (const entry of merged) {
         const letter = entry.term.charAt(0).toUpperCase();
         if (letter !== currentLetter) {
             currentLetter = letter;
@@ -662,7 +687,7 @@ function buildIndexContent(entries, args) {
             }
             lines.push(currentLetter);
         }
-        lines.push(`${entry.term}\t${entry.page}`);
+        lines.push(formatEntry(entry));
     }
     return lines.join("\n");
 }

package/dist/browser/modules/word/advanced/glossary.d.ts

@@ -4,45 +4,19 @@
  * Provides types and utilities for working with Glossary Document parts,
  * which contain AutoText entries, Quick Parts, and other Building Blocks.
  *
- * INTEGRATION STATUS: This module provides data structures and query helpers
- * for building blocks. The actual reading/writing of glossary parts from/to
- * DOCX archives is handled via the opaqueParts round-trip mechanism —
- * glossary parts in existing files are preserved as opaque parts during
- * read/write. This module is useful for:
+ * INTEGRATION STATUS: This module provides the glossary data model and query
+ * helpers. To embed a glossary in a document, assign a {@link GlossaryDocument}
+ * to `doc.glossary`; the packager then serialises it to
+ * `word/glossary/document.xml`, registers the `glossaryDocument` relationship,
+ * and adds the `[Content_Types].xml` override (the canonical OOXML location
+ * Word reads Quick Parts / AutoText from). Glossary parts in existing files are
+ * round-tripped via the same channel. This module is useful for:
  * - Building glossary data structures programmatically
  * - Querying/filtering building block collections
- * - Preparing data for future direct glossary part writing
- *
- * To add glossary content to a document currently, include it as an
- * OpaquePart with path "word/glossary/document.xml".
+ * - Assembling a glossary to attach via `doc.glossary`
  */
-import type { BodyContent, SectionProperties } from "../types.js";
-/** 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>;
-}
+import type { BodyContent, BuildingBlock, BuildingBlockGallery, GlossaryDocument, SectionProperties } from "../types.js";
+export type { BuildingBlock, BuildingBlockGallery, GlossaryDocument } from "../types.js";
 /**
  * Create a building block entry.
  *

package/dist/browser/modules/word/advanced/glossary.js

@@ -4,17 +4,16 @@
  * Provides types and utilities for working with Glossary Document parts,
  * which contain AutoText entries, Quick Parts, and other Building Blocks.
  *
- * INTEGRATION STATUS: This module provides data structures and query helpers
- * for building blocks. The actual reading/writing of glossary parts from/to
- * DOCX archives is handled via the opaqueParts round-trip mechanism —
- * glossary parts in existing files are preserved as opaque parts during
- * read/write. This module is useful for:
+ * INTEGRATION STATUS: This module provides the glossary data model and query
+ * helpers. To embed a glossary in a document, assign a {@link GlossaryDocument}
+ * to `doc.glossary`; the packager then serialises it to
+ * `word/glossary/document.xml`, registers the `glossaryDocument` relationship,
+ * and adds the `[Content_Types].xml` override (the canonical OOXML location
+ * Word reads Quick Parts / AutoText from). Glossary parts in existing files are
+ * round-tripped via the same channel. This module is useful for:
  * - Building glossary data structures programmatically
  * - Querying/filtering building block collections
- * - Preparing data for future direct glossary part writing
- *
- * To add glossary content to a document currently, include it as an
- * OpaquePart with path "word/glossary/document.xml".
+ * - Assembling a glossary to attach via `doc.glossary`
  */
 import { generateGuid } from "../core/internal-utils.js";
 // =============================================================================