@cj-tech-master/excelts 9.6.1 → 10.0.0

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

@@ -13,6 +13,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderPage = renderPage;
 exports.emitTextWithMatrix = emitTextWithMatrix;
+exports.emitTextBlock = emitTextBlock;
 exports.alphaGsName = alphaGsName;
 exports.computeTextStartY = computeTextStartY;
 exports.computeTextX = computeTextX;
@@ -684,7 +685,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) {
@@ -699,40 +700,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.
+ */
+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).
+ */
+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).
  */
-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 pdf_stream_1.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/cjs/modules/word/advanced/field-engine.js

@@ -46,7 +46,7 @@ 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
@@ -614,23 +614,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 = [];
-    (0, walker_1.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;
+        (0, walker_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. */
@@ -647,17 +657,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;
@@ -666,7 +691,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/cjs/modules/word/advanced/glossary.js

@@ -5,17 +5,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`
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createBuildingBlock = createBuildingBlock;

package/dist/cjs/modules/word/advanced/math-convert.js

@@ -83,20 +83,98 @@ function convertNodeToMathML(node) {
     }
 }
 function convertMathRunToMathML(node) {
-    const text = (0, encode_1.xmlEncode)(node.text);
-    // Operators and special characters
-    if (isOperator(node.text)) {
-        return `<mo>${text}</mo>`;
+    const raw = node.text;
+    // A single OMML run can hold a mix of letters, digits, operators and
+    // whitespace (e.g. "a + b = "). MathML presentation markup expects each
+    // token to be wrapped in the element matching its semantic category:
+    // <mi> for identifiers, <mn> for numbers, <mo> for operators and <mtext>
+    // for runs of whitespace / other text. Tokenize the run and emit one
+    // element per token so a mixed run is no longer flattened into a single
+    // (incorrect) <mi>.
+    const normalVariant = node.properties?.italic === false;
+    const tokens = tokenizeMathRun(raw);
+    // Fast path / backwards-compatibility: a run that is a single token keeps
+    // producing exactly one element (e.g. "x" -> <mi>x</mi>, "42" -> <mn>42</mn>,
+    // "+" -> <mo>+</mo>), matching the historical output.
+    return tokens.map(tok => emitMathToken(tok, normalVariant)).join("");
+}
+function classifyMathChar(ch) {
+    if (/\s/.test(ch)) {
+        return "text";
+    }
+    if (isOperator(ch)) {
+        return "operator";
+    }
+    if (/[0-9.]/.test(ch)) {
+        return "number";
+    }
+    if (/[A-Za-z]/.test(ch)) {
+        return "identifier";
+    }
+    // Letters outside ASCII (Greek, CJK, etc.) and any other symbol fall back to
+    // identifier — this matches how OMML treats variable names.
+    return "identifier";
+}
+function tokenizeMathRun(text) {
+    const tokens = [];
+    // Use code points so astral / combined characters are not split mid-symbol.
+    const chars = Array.from(text);
+    for (const ch of chars) {
+        const kind = classifyMathChar(ch);
+        const last = tokens[tokens.length - 1];
+        // Operators are always emitted as their own token (each operator is a
+        // distinct <mo>). Numbers, identifiers and text coalesce with the
+        // previous token of the same kind so "42" stays a single <mn> and a run
+        // of spaces stays a single <mtext>.
+        if (last && last.kind === kind && kind !== "operator") {
+            last.value += ch;
+        }
+        else {
+            tokens.push({ kind, value: ch });
+        }
     }
-    // Numbers
-    if (/^\d+(\.\d+)?$/.test(node.text)) {
-        return `<mn>${text}</mn>`;
+    return mergeDecimalPoints(tokens);
+}
+/**
+ * A "." between two digit groups is a decimal point, not an operator. The
+ * char classifier sees "." as an operator (it is a valid math operator on its
+ * own, e.g. function composition), so stitch `<number> "." <number>` back into
+ * a single number token here.
+ */
+function mergeDecimalPoints(tokens) {
+    const out = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i];
+        const prev = out[out.length - 1];
+        const next = tokens[i + 1];
+        if (tok.kind === "operator" &&
+            tok.value === "." &&
+            prev &&
+            prev.kind === "number" &&
+            next &&
+            next.kind === "number") {
+            prev.value += "." + next.value;
+            i++; // consume the following number token
+            continue;
+        }
+        out.push(tok);
     }
-    // Identifiers
-    if (node.properties?.italic === false) {
-        return `<mi mathvariant="normal">${text}</mi>`;
+    return out;
+}
+function emitMathToken(tok, normalVariant) {
+    const text = (0, encode_1.xmlEncode)(tok.value);
+    switch (tok.kind) {
+        case "operator":
+            return `<mo>${text}</mo>`;
+        case "number":
+            // A lone "." is not a number; treat it as an operator/text fallback.
+            return /\d/.test(tok.value) ? `<mn>${text}</mn>` : `<mo>${text}</mo>`;
+        case "text":
+            return `<mtext>${text}</mtext>`;
+        case "identifier":
+        default:
+            return normalVariant ? `<mi mathvariant="normal">${text}</mi>` : `<mi>${text}</mi>`;
     }
-    return `<mi>${text}</mi>`;
 }
 function convertFractionToMathML(node) {
     const num = childrenToMathML(node.numerator);
@@ -258,7 +336,11 @@ function convertMMLElement(el) {
         }
         case "msqrt": {
             const content = convertMMLChildren(el.children);
-            return { type: "mathRadical", content };
+            // A bare square root has no degree. OOXML still emits an (empty)
+            // <m:deg/>, so we must set hideDegree → <m:degHide m:val="1"/>;
+            // otherwise Word treats the empty degree as visible and draws an empty
+            // degree box (a small square) at the radical's upper-left.
+            return { type: "mathRadical", content, hideDegree: true };
         }
         case "mroot": {
             const children = getElementChildren(el);

package/dist/cjs/modules/word/advanced/ole-objects.js

@@ -19,6 +19,9 @@ exports.extractOleObjects = extractOleObjects;
 exports.hasOleObjects = hasOleObjects;
 exports.getOleObjectData = getOleObjectData;
 exports.createOleEmbedding = createOleEmbedding;
+exports.addOleObject = addOleObject;
+const encode_1 = require("../../xml/encode.js");
+const constants_1 = require("../constants");
 const opc_paths_1 = require("../core/opc-paths");
 // =============================================================================
 // OLE Object Extraction
@@ -34,14 +37,33 @@ const opc_paths_1 = require("../core/opc-paths");
 function extractOleObjects(doc) {
     const objects = [];
     const summary = {};
-    // Scan opaque parts for OLE embeddings
+    const pushObject = (obj) => {
+        objects.push(obj);
+        summary[obj.progId] = (summary[obj.progId] ?? 0) + 1;
+    };
+    // Structured OLE objects wired on document.xml.rels (preferred form —
+    // these carry the real rId and, when available, the round-tripped progId).
+    if (doc.oleObjects) {
+        for (const ole of doc.oleObjects) {
+            pushObject({
+                rId: ole.rId,
+                progId: ole.progId ?? detectProgIdFromData(ole.data),
+                objectType: "embedded",
+                displayAs: "icon",
+                imageRId: ole.previewRId,
+                fileName: (0, opc_paths_1.getFileName)(ole.path),
+                data: ole.data
+            });
+        }
+    }
+    // Scan opaque parts for OLE embeddings (legacy / hand-built documents that
+    // did not go through the structured oleObjects channel).
     if (doc.opaqueParts) {
         for (const part of doc.opaqueParts) {
             if (isOleEmbedding(part.path)) {
                 const obj = parseOlePartMetadata(part);
                 if (obj) {
-                    objects.push(obj);
-                    summary[obj.progId] = (summary[obj.progId] ?? 0) + 1;
+                    pushObject(obj);
                 }
             }
         }
@@ -51,11 +73,10 @@ function extractOleObjects(doc) {
         if (element.type === "opaqueDrawing") {
             const oleFromDrawing = extractOleFromRawXml(element.rawXml);
             if (oleFromDrawing) {
-                // Check if we already have this object from opaque parts
-                const exists = objects.some(o => o.rId === oleFromDrawing.rId);
+                // Check if we already have this object (by rId)
+                const exists = objects.some(o => o.rId === oleFromDrawing.rId && o.rId !== "");
                 if (!exists) {
-                    objects.push(oleFromDrawing);
-                    summary[oleFromDrawing.progId] = (summary[oleFromDrawing.progId] ?? 0) + 1;
+                    pushObject(oleFromDrawing);
                 }
             }
         }
@@ -66,6 +87,9 @@ function extractOleObjects(doc) {
  * Check if a document contains any OLE embedded objects.
  */
 function hasOleObjects(doc) {
+    if (doc.oleObjects && doc.oleObjects.length > 0) {
+        return true;
+    }
     if (doc.opaqueParts) {
         for (const part of doc.opaqueParts) {
             if (isOleEmbedding(part.path)) {
@@ -80,6 +104,14 @@ function hasOleObjects(doc) {
  * Returns undefined if not found.
  */
 function getOleObjectData(doc, rId) {
+    // Structured OLE objects carry the exact rId used on document.xml.rels.
+    if (doc.oleObjects) {
+        for (const ole of doc.oleObjects) {
+            if (ole.rId === rId) {
+                return ole.data;
+            }
+        }
+    }
     if (!doc.opaqueParts) {
         return undefined;
     }
@@ -132,16 +164,14 @@ function createOleEmbedding(data, progId, options) {
     const olePart = {
         path: `word/embeddings/${fileName}`,
         data,
-        contentType: "application/vnd.openxmlformats-officedocument.oleObject",
+        contentType: constants_1.ContentType.OleObject,
         relationships: undefined
     };
     const oleRId = `rIdOle${oleSeq}`;
-    // progId is metadata for downstream consumers — not stored on
-    // OpaquePart but accepted in the signature so callers can pass it
-    // alongside without a separate channel. We don't need it here.
-    void progId;
+    // progId is carried back on the result so addOleObject() can persist it
+    // into the body `<o:OLEObject ProgID="…">` markup for round-trip.
     if (!options?.previewImage) {
-        return { olePart, oleRId };
+        return { olePart, oleRId, progId };
     }
     if (!options.previewContentType) {
         throw new Error("createOleEmbedding: options.previewImage requires options.previewContentType");
@@ -156,7 +186,78 @@ function createOleEmbedding(data, progId, options) {
         relationships: undefined
     };
     const previewRId = `rIdOleImg${previewSeq}`;
-    return { olePart, oleRId, previewPart, previewRId };
+    return { olePart, oleRId, progId, previewPart, previewRId };
+}
+/**
+ * Wire an {@link OleEmbeddingResult} into a document so the OLE object is
+ * actually rendered and resolvable, returning a new {@link DocxDocument}.
+ *
+ * Unlike just stuffing the part into `opaqueParts` (which leaves the binary
+ * dangling — no relationship, no body reference), this:
+ *
+ *  - registers the OLE binary (and optional preview) on
+ *    `doc.oleObjects` so the packager emits a `word/_rels/document.xml.rels`
+ *    relationship with the exact rId and a `[Content_Types].xml` override;
+ *  - appends a body paragraph carrying a `<w:object>` / `<o:OLEObject>`
+ *    that references the same rId and embeds the ProgId, so the object is
+ *    visible in Word and round-trips through `readDocx`.
+ *
+ * @param doc - The document to add the OLE object to.
+ * @param embedding - Result from {@link createOleEmbedding}.
+ * @param options - Display geometry (defaults to a 2"×2" icon box).
+ */
+function addOleObject(doc, embedding, options) {
+    const widthPt = options?.widthPt ?? 96;
+    const heightPt = options?.heightPt ?? 96;
+    const drawAspect = (options?.displayAs ?? "icon") === "icon" ? "Icon" : "Content";
+    const olePartEntry = {
+        path: embedding.olePart.path,
+        data: embedding.olePart.data,
+        rId: embedding.oleRId,
+        progId: embedding.progId,
+        contentType: embedding.olePart.contentType,
+        ...(embedding.previewPart && embedding.previewRId
+            ? {
+                previewPath: embedding.previewPart.path,
+                previewData: embedding.previewPart.data,
+                previewRId: embedding.previewRId,
+                previewContentType: embedding.previewPart.contentType
+            }
+            : {})
+    };
+    // Build the VML-hosted <w:object>. The o:OLEObject carries ProgID + the
+    // r:id of the binary; the v:shape provides geometry and (when present) the
+    // preview image fill via v:imagedata. This is the canonical OOXML shape for
+    // an embedded OLE object (ECMA-376 §17.3.3.19 + VML).
+    const shapeId = `_ole_${embedding.oleRId}`;
+    const styleWidth = widthPt.toFixed(0);
+    const styleHeight = heightPt.toFixed(0);
+    const imageData = embedding.previewRId != null
+        ? `<v:imagedata r:id="${(0, encode_1.xmlEncodeAttr)(embedding.previewRId)}" o:title=""/>`
+        : "";
+    const rawXml = `<w:object>` +
+        `<v:shape id="${(0, encode_1.xmlEncodeAttr)(shapeId)}" type="#_x0000_t75" ` +
+        `style="width:${styleWidth}pt;height:${styleHeight}pt">` +
+        imageData +
+        `</v:shape>` +
+        `<o:OLEObject Type="Embed" ProgID="${(0, encode_1.xmlEncodeAttr)(embedding.progId)}" ` +
+        `ShapeID="${(0, encode_1.xmlEncodeAttr)(shapeId)}" DrawAspect="${drawAspect}" ` +
+        `r:id="${(0, encode_1.xmlEncodeAttr)(embedding.oleRId)}"/>` +
+        `</w:object>`;
+    const referencedRIds = [embedding.oleRId];
+    if (embedding.previewRId != null) {
+        referencedRIds.push(embedding.previewRId);
+    }
+    const drawing = {
+        type: "opaqueDrawing",
+        rawXml,
+        referencedRIds
+    };
+    return {
+        ...doc,
+        body: [...doc.body, drawing],
+        oleObjects: [...(doc.oleObjects ?? []), olePartEntry]
+    };
 }
 /** Module-level counters used to allocate unique file names per call. */
 let _oleSeq = 0;
@@ -248,17 +349,20 @@ function tryDecodeAscii(data) {
     return str;
 }
 function extractOleFromRawXml(rawXml) {
-    // Parse OLE object info from raw XML using regex (lightweight)
-    const progIdMatch = rawXml.match(/ProgID="([^"]+)"/i) ?? rawXml.match(/progId="([^"]+)"/i);
-    const rIdMatch = rawXml.match(/r:id="([^"]+)"/i);
-    const typeMatch = rawXml.match(/Type="([^"]+)"/i);
+    // Pull metadata from the <o:OLEObject> element specifically, so a preview
+    // image's <v:imagedata r:id="…"> earlier in the markup is not mistaken for
+    // the OLE binary's relationship id.
+    const oleTag = rawXml.match(/<o:OLEObject\b[^>]*>/i)?.[0] ?? rawXml;
+    const progIdMatch = oleTag.match(/ProgID="([^"]+)"/i) ?? oleTag.match(/progId="([^"]+)"/i);
+    const rIdMatch = oleTag.match(/r:id="([^"]+)"/i);
+    const typeMatch = oleTag.match(/Type="([^"]+)"/i);
     if (!progIdMatch) {
         return null;
     }
     const progId = progIdMatch[1];
     const rId = rIdMatch ? rIdMatch[1] : "";
     const objectType = typeMatch && typeMatch[1].toLowerCase().includes("link") ? "linked" : "embedded";
-    // Extract dimensions
+    // Extract dimensions (from the surrounding shape, hence full rawXml)
     const widthMatch = rawXml.match(/(?:cx|width)="(\d+)"/i);
     const heightMatch = rawXml.match(/(?:cy|height)="(\d+)"/i);
     return {