@cj-tech-master/excelts 9.6.1 → 10.0.0

package/dist/types/modules/excel/cell.d.ts

@@ -43,6 +43,10 @@ export interface NoteConfig {
     };
     editAs?: string;
     anchor?: string;
+    /** Comment box width in points. Defaults to 97.8pt when omitted. */
+    width?: number;
+    /** Comment box height in points. Defaults to 59.1pt when omitted. */
+    height?: number;
 }
 export interface NoteModel {
     type: string;

package/dist/types/modules/excel/stream/workbook-writer.browser.d.ts

@@ -20,9 +20,16 @@ import type { Writable } from "../../stream/index.js";
  * Extends the public {@link ImageData} shape with the unique stored name
  * (`name`) assigned by `addImage`, and pins `type` to `"image"`.
  */
-export interface Medium extends ImageData {
+export interface Medium extends Omit<ImageData, "extension"> {
     type: "image";
     name: string;
+    /**
+     * Widened from `ImageData.extension` so an SVG companion medium can carry
+     * the `"svg"` extension (the public `addImage` input stays raster-only).
+     */
+    extension: string;
+    /** Media index of an SVG companion (raster blip + svgBlip extension). */
+    svgMediaId?: number;
 }
 interface CommentRef {
     commentName: string;

package/dist/types/modules/excel/types.d.ts

@@ -497,6 +497,24 @@ export interface ImageData {
      * are required.
      */
     link?: string;
+    /**
+     * Attach a scalable SVG alongside a raster fallback.
+     *
+     * Excel stores SVG pictures as a raster `a:blip` (the `extension`/`buffer`/
+     * `base64`/`filename` on this object — typically a PNG) plus an
+     * `asvg:svgBlip` extension pointing at the vector data. The raster image is
+     * what older Excel versions and non-SVG consumers render, so it is required;
+     * modern Excel renders the crisp SVG. This library does **not** rasterize —
+     * you supply both the SVG bytes and the raster fallback you want embedded.
+     */
+    svg?: {
+        /** SVG bytes (mutually use one of buffer/base64/filename). */
+        buffer?: Buffer;
+        /** Base64-encoded SVG. */
+        base64?: string;
+        /** Path to an `.svg` file (Node only). */
+        filename?: string;
+    };
 }
 export interface ImagePosition {
     tl: {
@@ -556,6 +574,69 @@ export interface ImageHyperlinkValue {
     hyperlink: string;
     tooltip?: string;
 }
+/**
+ * Preset geometry for a drawing shape. Mirrors the OOXML `prst` vocabulary;
+ * the most common presets are surfaced here, but any valid preset name is
+ * accepted as a fallback `string`.
+ */
+export type ShapeType = "rect" | "roundRect" | "ellipse" | "triangle" | "line" | "rightArrow" | "leftArrow" | "upArrow" | "downArrow" | "diamond" | "hexagon" | "star5" | (string & {});
+/** Options for `Worksheet.addShape`. */
+export interface AddShapeOptions {
+    /** Preset geometry (defaults to `"rect"`). */
+    type?: ShapeType;
+    /** Where the shape sits — a cell range (e.g. `"B2:D5"`) or anchor object. */
+    range: AddImageRange;
+    /** Solid fill colour as hex RGB (e.g. `"FF0000"`). Omit for no fill. */
+    fillColor?: string;
+    /** Outline colour as hex RGB (e.g. `"000000"`). */
+    lineColor?: string;
+    /** Outline width in points. */
+    lineWidth?: number;
+    /** Optional centred text label. */
+    text?: string;
+    /** Display name (defaults to `"Shape N"`). */
+    name?: string;
+}
+/** Internal serialized model for a worksheet shape. */
+export interface ShapeModel {
+    type: "shape";
+    shapeType: string;
+    range: AddImageRange;
+    fillColor?: string;
+    lineColor?: string;
+    lineWidth?: number;
+    text?: string;
+    name?: string;
+    /**
+     * Resolved anchor coordinates, filled in by the worksheet model getter so
+     * the serializer doesn't need range-parsing logic. Mirrors the three image
+     * anchoring modes: two-cell (`tl`+`br`), one-cell (`tl`+`ext`) and absolute
+     * (`pos`+`ext`). Internal only.
+     */
+    anchorRange?: {
+        tl: {
+            nativeCol: number;
+            nativeColOff: number;
+            nativeRow: number;
+            nativeRowOff: number;
+        };
+        br?: {
+            nativeCol: number;
+            nativeColOff: number;
+            nativeRow: number;
+            nativeRowOff: number;
+        };
+        ext?: {
+            width?: number;
+            height?: number;
+        };
+        pos?: {
+            x: number;
+            y: number;
+        };
+        editAs?: string;
+    };
+}
 /**
  * Watermark placement mode in the Excel worksheet.
  *

package/dist/types/modules/excel/utils/drawing-utils.d.ts

@@ -19,6 +19,12 @@ export interface DrawingAnchor {
          * (`<a:blip r:link>`) instead of an embedded one (`<a:blip r:embed>`).
          */
         external?: boolean;
+        /**
+         * Relationship id of an SVG companion. When set, the raster `a:blip`
+         * (referenced by `rId`) carries an `asvg:svgBlip` extension pointing at
+         * the SVG media via this id.
+         */
+        svgRId?: string;
     };
     range: any;
 }
@@ -54,6 +60,8 @@ export interface MediaLike {
     buffer?: unknown;
     base64?: unknown;
     filename?: unknown;
+    /** Media index of an SVG companion (raster blip + svgBlip extension). */
+    svgMediaId?: number;
 }
 /**
  * Resolves a media filename into the drawing-level relative target path.

package/dist/types/modules/excel/workbook.browser.d.ts

@@ -34,6 +34,12 @@ export interface WorkbookMedia {
     name?: string;
     /** External link target — when set, the image is referenced, not embedded. */
     link?: string;
+    /**
+     * Media index of the SVG companion for this raster image. When set, the
+     * picture is written as a raster `a:blip` plus an `asvg:svgBlip` extension
+     * referencing the SVG media at this index. Internal bookkeeping only.
+     */
+    svgMediaId?: number;
 }
 /** Internal model type for serialization */
 export interface WorkbookModel {
@@ -820,6 +826,16 @@ declare class Workbook {
      * const id = workbook.addImage({ extension: "png", link: "https://example.com/logo.png" });
      * worksheet.addImage(id, "B2:D6");
      * ```
+     *
+     * @example SVG with raster fallback — crisp in modern Excel, safe everywhere
+     * ```typescript
+     * const id = workbook.addImage({
+     *   buffer: pngFallbackBytes, // shown by older Excel / non-SVG consumers
+     *   extension: "png",
+     *   svg: { buffer: svgBytes } // shown by Excel 2016+
+     * });
+     * worksheet.addImage(id, "B2:D6");
+     * ```
      */
     addImage(image: ImageData): number;
     getImage(id: number | string): WorkbookMedia | undefined;

package/dist/types/modules/excel/worksheet.d.ts

@@ -14,7 +14,7 @@ import { Range, type RangeInput } from "./range.js";
 import { Row, type RowModel } from "./row.js";
 import type { AddSparklineGroupOptions, SparklineGroup } from "./sparkline/index.js";
 import { Table, type TableModel } from "./table.js";
-import type { AddImageRange, AutoFilter, CellValue, ColBreak, ConditionalFormattingOptions, DataValidation, IgnoredError, RowBreak, RowValues, TableProperties, ThreadedComment, WatermarkOptions, WorksheetProperties, WorksheetState, WorksheetView } from "./types.js";
+import type { AddImageRange, AddShapeOptions, AutoFilter, CellValue, ColBreak, ConditionalFormattingOptions, DataValidation, IgnoredError, RowBreak, RowValues, ShapeModel, TableProperties, ThreadedComment, WatermarkOptions, WorksheetProperties, WorksheetState, WorksheetView } from "./types.js";
 import { type Origin } from "./utils/address.js";
 import type { Workbook } from "./workbook.js";
 type DataValidationModel = {
@@ -110,6 +110,7 @@ interface WorksheetModel {
     views: Partial<WorksheetView>[];
     autoFilter: AutoFilter | null;
     media: ImageModel[];
+    shapes?: ShapeModel[];
     sheetProtection: SheetProtection | null;
     tables: TableModel[];
     pivotTables: PivotTable[];
@@ -156,6 +157,7 @@ declare class Worksheet {
     views: Partial<WorksheetView>[];
     autoFilter: AutoFilter | null;
     private _media;
+    private _shapes;
     private _charts;
     private _sparklineGroups;
     sheetProtection: SheetProtection | null;
@@ -362,6 +364,34 @@ declare class Worksheet {
      * embed an image within the worksheet to cover a range
      */
     addImage(imageId: string | number, range: AddImageRange): void;
+    /**
+     * Add a free-form drawing shape (rectangle, ellipse, line, text box, …) to
+     * the worksheet, anchored to a cell range.
+     *
+     * Unlike images, shapes need no media file — the geometry, fill, outline and
+     * optional text label are written directly into the drawing part.
+     *
+     * @example
+     * ```typescript
+     * worksheet.addShape({
+     *   type: "rect",
+     *   range: "B2:D5",
+     *   fillColor: "FFD966",
+     *   lineColor: "000000",
+     *   lineWidth: 1,
+     *   text: "Important"
+     * });
+     * ```
+     */
+    addShape(options: AddShapeOptions): void;
+    /** All shapes added to this worksheet. */
+    getShapes(): ShapeModel[];
+    /**
+     * Resolve a shape's `range` into concrete two-cell anchor coordinates,
+     * reusing the `Image` range parser so cell-address/anchor handling stays in
+     * one place. Returns a serializable ShapeModel for the worksheet xform.
+     */
+    private _resolveShapeModel;
     getImages(): Image[];
     /**
      * Add a chart to the worksheet, positioned at the given range.

package/dist/types/modules/excel/xlsx/xform/comment/vml-shape-xform.d.ts

@@ -5,6 +5,8 @@ interface ShapeModel {
             insetmode?: string;
             inset?: number[];
         };
+        width?: number;
+        height?: number;
     };
     refAddress?: any;
 }
@@ -20,6 +22,11 @@ declare class VmlShapeXform extends BaseXform {
     parseOpen(node: any): boolean;
     parseText(text: string): void;
     parseClose(name: string): boolean;
+    /**
+     * Extract a points-valued length (e.g. `width:120pt`) from a VML style
+     * string. Returns `undefined` when the property is absent or not in `pt`.
+     */
+    static parseStyleLength(style: string, prop: "width" | "height"): number | undefined;
     static V_SHAPE_ATTRIBUTES: (model: ShapeModel, index: number) => any;
 }
 export { VmlShapeXform };

package/dist/types/modules/excel/xlsx/xform/drawing/blip-xform.d.ts

@@ -8,6 +8,12 @@ interface BlipModel {
      * instead of an embedded one via `r:embed`.
      */
     external?: boolean;
+    /**
+     * Relationship id of an SVG companion. When set, the raster blip carries an
+     * `asvg:svgBlip` extension referencing the SVG media so Excel 2016+ renders
+     * the vector image while older consumers fall back to the raster blip.
+     */
+    svgRId?: string;
 }
 declare class BlipXform extends BaseXform<BlipModel> {
     constructor();

package/dist/types/modules/excel/xlsx/xform/drawing/one-cell-anchor-xform.d.ts

@@ -6,6 +6,7 @@ interface OneCellModel {
         ext: any;
     };
     picture?: any;
+    shape?: any;
     /** Graphic frame model (for charts and other embedded objects) */
     graphicFrame?: any;
 }

package/dist/types/modules/excel/xlsx/xform/drawing/pic-xform.d.ts

@@ -6,6 +6,8 @@ interface PicModel {
     alphaModFix?: number;
     /** When true, render the picture as an external linked image (`r:link`). */
     external?: boolean;
+    /** Relationship id of an SVG companion (asvg:svgBlip extension). */
+    svgRId?: string;
     [key: string]: any;
 }
 declare class PicXform extends BaseXform {

package/dist/types/modules/excel/xlsx/xform/drawing/shape-xform.d.ts

@@ -0,0 +1,47 @@
+import { BaseXform } from "../base-xform.js";
+/** Fill specification for a drawing shape. */
+export interface ShapeFill {
+    /** Solid fill colour as a hex RGB string (e.g. "FF0000"). Omit for no fill. */
+    color?: string;
+}
+/** Line (outline) specification for a drawing shape. */
+export interface ShapeLine {
+    /** Line colour as a hex RGB string (e.g. "000000"). */
+    color?: string;
+    /** Line width in points. */
+    width?: number;
+}
+/**
+ * Model for a user-visible drawing shape (`<xdr:sp>`).
+ *
+ * Distinct from the form-control shape rendered by `SpXform` — this one is
+ * visible, carries a configurable preset geometry, solid fill, outline and an
+ * optional text label, and is NOT wrapped in an `a14` AlternateContent block.
+ */
+export interface ShapeRenderModel {
+    /** Marks this as a user shape so the anchor routes to ShapeXform. */
+    kind: "userShape";
+    /** Unique drawing id. */
+    cNvPrId: number;
+    /** Display name (e.g. "Rectangle 1"). */
+    name: string;
+    /** Preset geometry name (e.g. "rect", "ellipse", "line", "roundRect"). */
+    shapeType: string;
+    fill?: ShapeFill;
+    line?: ShapeLine;
+    /** Optional text label centred in the shape. */
+    text?: string;
+}
+/**
+ * Renders a user-visible drawing shape. Geometry/position is governed by the
+ * enclosing anchor (`xfrm` is written as zero, matching how Excel anchors a
+ * shape to a cell range), while preset geometry, fill, outline and text are
+ * taken from the model. Write-only: shapes are not parsed back on read (the
+ * same limitation that already applies to all non-chart drawing content).
+ */
+declare class ShapeXform extends BaseXform {
+    model: ShapeRenderModel;
+    get tag(): string;
+    render(xmlStream: any, model: ShapeRenderModel): void;
+}
+export { ShapeXform };

package/dist/types/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/types/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/types/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/types/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/types/modules/word/advanced/ole-objects.d.ts

@@ -81,6 +81,8 @@ export interface OleEmbeddingResult {
     readonly olePart: OpaquePart;
     /** Suggested rId to use for the OLE binary in the document model. */
     readonly oleRId: string;
+    /** OLE ProgId the embedding was created with (e.g. "Excel.Sheet.12"). */
+    readonly progId: string;
     /** Preview image media part (only when `options.previewImage` was supplied). */
     readonly previewPart?: OpaquePart;
     /** Suggested rId for the preview image. */
@@ -113,3 +115,29 @@ export declare function createOleEmbedding(data: Uint8Array, progId: string, opt
     /** Override preview file name. Defaults to `image<N>.<ext>` from previewContentType. */
     previewFileName?: string;
 }): OleEmbeddingResult;
+/**
+ * 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).
+ */
+export declare function addOleObject(doc: DocxDocument, embedding: OleEmbeddingResult, options?: {
+    /** Display width in points (default 96 = 2 inches at 48pt/in icon). */
+    widthPt?: number;
+    /** Display height in points (default 96). */
+    heightPt?: number;
+    /** Display mode. Default "icon". */
+    displayAs?: OleDisplayAs;
+}): DocxDocument;

package/dist/types/modules/word/builder/run-builders.d.ts

@@ -263,7 +263,13 @@ export declare function mathSubScript(base: MathContent[], subScript: MathConten
 export declare function mathSubSuperScript(base: MathContent[], subScript: MathContent[], superScript: MathContent[]): MathContent;
 /** Create a math pre-sub-superscript (subscript/superscript before the base). */
 export declare function mathPreSubSuperScript(base: MathContent[], preSubScript: MathContent[], preSuperScript: MathContent[]): MathContent;
-/** Create a math phantom (invisible expression that takes up space). */
+/**
+ * Create a math phantom (an expression that takes up space).
+ *
+ * Note: in OOXML the phantom base is *shown* by default. To make the classic
+ * "occupies space but invisible" phantom pass `{ show: false }`; passing only
+ * `transparent: true` is not sufficient to hide the base in Word.
+ */
 export declare function mathPhantom(content: MathContent[], options?: {
     show?: boolean;
     zeroWidth?: boolean;

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

@@ -168,6 +168,10 @@ export declare const ContentType: {
     readonly Xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
     readonly CustomXml: "application/xml";
     readonly VbaProject: "application/vnd.ms-office.vbaProject";
+    /** Glossary (Building Blocks) document part. */
+    readonly Glossary: "application/vnd.openxmlformats-officedocument.wordprocessingml.document.glossary+xml";
+    /** OLE embedded object binary. */
+    readonly OleObject: "application/vnd.openxmlformats-officedocument.oleObject";
 };
 /** Map from image file extension to content type. */
 export declare const IMAGE_CONTENT_TYPES: Record<string, string>;

package/dist/types/modules/word/convert/docx-to-semantic.d.ts

@@ -11,7 +11,8 @@
  * - Hyperlink extraction
  * - Image registration into ConversionContext
  * - Table structure with merge (colSpan/rowSpan)
- * - List/numbering detection (basic)
+ * - List/numbering detection: consecutive numbered paragraphs are aggregated
+ *   into ordered/unordered `list` blocks with nested sub-lists by level
  * - Footnote/endnote reference and content
  * - Math content (text fallback)
  */