@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/types/modules/stream/pull-stream.d.ts

@@ -17,15 +17,32 @@ export declare class PullStream extends EventEmitter {
     protected finished: boolean;
     protected _match?: number;
     private _destroyed;
-    constructor(_options?: PullStreamOptions);
+    private _highWaterMark;
+    private _needsDrain;
+    constructor(options?: PullStreamOptions);
     /** Reset the internal buffer to empty. */
     private _resetBuffer;
     protected get buffer(): Uint8Array;
     protected set buffer(buf: Uint8Array);
     /**
-     * Write data to the stream
+     * Write data to the stream.
+     *
+     * Returns `false` when the buffer's readable size exceeds `highWaterMark`
+     * (backpressure signal). Producers should pause and resume on the next
+     * `'drain'` event.
      */
     write(chunk: Uint8Array): boolean;
+    /**
+     * Set `_needsDrain` based on current buffer size, return whether the
+     * producer should keep writing (true) or pause (false).
+     */
+    private _evaluateBackpressure;
+    /**
+     * Internal: subclasses or pull paths must call this after consuming bytes
+     * (advancing `_bufferReadIndex`) to potentially emit `'drain'`. Idempotent
+     * and free when no backpressure is in effect.
+     */
+    protected _maybeEmitDrain(): void;
     /**
      * Signal end of input
      */

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

@@ -157,7 +157,19 @@ export interface IDuplex<TRead = any, TWrite = any> extends IReadable<TRead>, IW
 /**
  * Options for pull stream (reserved for future use)
  */
-export type PullStreamOptions = object;
+export type PullStreamOptions = {
+    /**
+     * Buffer high-water mark in bytes. When the readable buffer exceeds this
+     * size, `write()` returns `false` to signal backpressure to the producer.
+     * Once the buffer drops back to the low-water mark (half the HWM), a
+     * `'drain'` event is emitted. Defaults to `Infinity` (no backpressure).
+     *
+     * Set this when the stream is fed by a fast producer with a slow `pull()`
+     * consumer to keep memory bounded — the legacy default of `Infinity`
+     * preserves existing behaviour for callers that drain promptly.
+     */
+    highWaterMark?: number;
+};
 /**
  * Pull stream interface - allows pulling data on demand
  */

package/dist/types/modules/word/advanced/diff.d.ts

@@ -0,0 +1,61 @@
+/**
+ * DOCX Module - Document Comparison (Diff)
+ *
+ * Compares two DocxDocument models and returns a list of differences.
+ * This is a text-level comparison — it compares paragraphs by their text content
+ * and reports additions, deletions, and modifications.
+ *
+ * @example
+ * ```ts
+ * import { diffDocuments } from "excelts/word";
+ *
+ * const changes = diffDocuments(oldDoc, newDoc);
+ * console.log(changes.filter(c => c.type === "modified"));
+ * ```
+ */
+import type { DocxDocument } from "../types.js";
+/** Type of change detected between two documents. */
+export type DiffChangeType = "added" | "deleted" | "modified" | "unchanged";
+/** A single diff entry representing a change between two documents. */
+export interface DiffEntry {
+    /** Type of change. */
+    readonly type: DiffChangeType;
+    /** Paragraph index in the old document (undefined for "added"). */
+    readonly oldIndex?: number;
+    /** Paragraph index in the new document (undefined for "deleted"). */
+    readonly newIndex?: number;
+    /** Text content from old document. */
+    readonly oldText?: string;
+    /** Text content from new document. */
+    readonly newText?: string;
+}
+/** Summary statistics for a diff result. */
+export interface DiffSummary {
+    /** Total number of paragraphs compared. */
+    readonly totalParagraphs: number;
+    /** Number of unchanged paragraphs. */
+    readonly unchanged: number;
+    /** Number of added paragraphs. */
+    readonly added: number;
+    /** Number of deleted paragraphs. */
+    readonly deleted: number;
+    /** Number of modified paragraphs. */
+    readonly modified: number;
+}
+/** Result of a document comparison. */
+export interface DiffResult {
+    /** Individual change entries. */
+    readonly entries: readonly DiffEntry[];
+    /** Summary statistics. */
+    readonly summary: DiffSummary;
+}
+/**
+ * Compare two DocxDocuments and return a diff of their text content.
+ *
+ * Uses the Myers diff algorithm (LCS-based) for optimal minimal edit sequence.
+ *
+ * @param oldDoc - The original document.
+ * @param newDoc - The modified document.
+ * @returns DiffResult with entries and summary.
+ */
+export declare function diffDocuments(oldDoc: DocxDocument, newDoc: DocxDocument): DiffResult;

package/dist/types/modules/word/advanced/drawing-shapes.d.ts

@@ -0,0 +1,269 @@
+/**
+ * DOCX Module - Enhanced DrawingML Shape Builder
+ *
+ * Provides a comprehensive API for creating DrawingML shapes beyond the
+ * basic shape type. Includes support for:
+ * - All 187 preset geometry types
+ * - Gradient and pattern fills
+ * - Shadow, glow, reflection effects
+ * - 3D rotation and bevel
+ * - Shape connectors and groups
+ * - Custom geometry paths
+ * - Text body formatting within shapes
+ */
+import type { DrawingShape, Paragraph, HexColor, Emu, HorizontalPositionRelative, VerticalPositionRelative, WrapStyle, WrapTextSide } from "../types.js";
+/** All standard OOXML preset shape types. */
+export type StandardShapeType = "rect" | "roundRect" | "snip1Rect" | "snip2SameRect" | "snip2DiagRect" | "snipRoundRect" | "round1Rect" | "round2SameRect" | "round2DiagRect" | "ellipse" | "triangle" | "rtTriangle" | "parallelogram" | "trapezoid" | "diamond" | "pentagon" | "hexagon" | "heptagon" | "octagon" | "decagon" | "dodecagon" | "pie" | "chord" | "teardrop" | "frame" | "halfFrame" | "corner" | "diagStripe" | "plus" | "cross" | "cube" | "can" | "foldedCorner" | "smileyFace" | "heart" | "lightningBolt" | "sun" | "moon" | "cloud" | "arc" | "bracketPair" | "bracePair" | "plaque" | "donut" | "noSmoking" | "blockArc" | "gear6" | "gear9" | "rightArrow" | "leftArrow" | "upArrow" | "downArrow" | "leftRightArrow" | "upDownArrow" | "quadArrow" | "leftRightUpArrow" | "bentArrow" | "uturnArrow" | "leftUpArrow" | "bentUpArrow" | "curvedRightArrow" | "curvedLeftArrow" | "curvedUpArrow" | "curvedDownArrow" | "stripedRightArrow" | "notchedRightArrow" | "homePlate" | "chevron" | "rightArrowCallout" | "downArrowCallout" | "leftArrowCallout" | "upArrowCallout" | "leftRightArrowCallout" | "quadArrowCallout" | "circularArrow" | "flowChartProcess" | "flowChartAlternateProcess" | "flowChartDecision" | "flowChartInputOutput" | "flowChartPredefinedProcess" | "flowChartInternalStorage" | "flowChartDocument" | "flowChartMultidocument" | "flowChartTerminator" | "flowChartPreparation" | "flowChartManualInput" | "flowChartManualOperation" | "flowChartConnector" | "flowChartOffpageConnector" | "flowChartPunchedCard" | "flowChartPunchedTape" | "flowChartSummingJunction" | "flowChartOr" | "flowChartCollate" | "flowChartSort" | "flowChartExtract" | "flowChartMerge" | "flowChartOnlineStorage" | "flowChartDelay" | "flowChartMagneticTape" | "flowChartMagneticDisk" | "flowChartMagneticDrum" | "flowChartDisplay" | "wedgeRectCallout" | "wedgeRoundRectCallout" | "wedgeEllipseCallout" | "cloudCallout" | "borderCallout1" | "borderCallout2" | "borderCallout3" | "accentCallout1" | "accentCallout2" | "accentCallout3" | "callout1" | "callout2" | "callout3" | "accentBorderCallout1" | "accentBorderCallout2" | "accentBorderCallout3" | "irregularSeal1" | "irregularSeal2" | "star4" | "star5" | "star6" | "star7" | "star8" | "star10" | "star12" | "star16" | "star24" | "star32" | "ribbon" | "ribbon2" | "ellipseRibbon" | "ellipseRibbon2" | "verticalScroll" | "horizontalScroll" | "wave" | "doubleWave" | "mathPlus" | "mathMinus" | "mathMultiply" | "mathDivide" | "mathEqual" | "mathNotEqual" | "line" | "straightConnector1" | "bentConnector2" | "bentConnector3" | "bentConnector4" | "bentConnector5" | "curvedConnector2" | "curvedConnector3" | "curvedConnector4" | "curvedConnector5" | "actionButtonBlank" | "actionButtonHome" | "actionButtonHelp" | "actionButtonInformation" | "actionButtonBackPrevious" | "actionButtonForwardNext" | "actionButtonBeginning" | "actionButtonEnd" | "actionButtonReturn" | "actionButtonDocument" | "actionButtonSound" | "actionButtonMovie";
+/** Solid fill. */
+export interface SolidFill {
+    readonly type: "solid";
+    readonly color: HexColor;
+    /** Transparency (0-100, percent). */
+    readonly transparency?: number;
+}
+/** Gradient stop. */
+export interface GradientStop {
+    readonly position: number;
+    readonly color: HexColor;
+    readonly transparency?: number;
+}
+/** Gradient fill. */
+export interface GradientFill {
+    readonly type: "gradient";
+    readonly stops: readonly GradientStop[];
+    /** Angle in 60,000ths of a degree. 0 = left-to-right. */
+    readonly angle?: number;
+    /** Gradient type: linear or radial (path). */
+    readonly gradientType?: "linear" | "radial";
+}
+/** Pattern fill. */
+export interface PatternFill {
+    readonly type: "pattern";
+    /** Pattern preset (e.g. "pct10", "dkHorz", "ltVert", "dnDiag"). */
+    readonly preset: string;
+    readonly foregroundColor: HexColor;
+    readonly backgroundColor: HexColor;
+}
+/** No fill (transparent). */
+export interface NoFill {
+    readonly type: "none";
+}
+/** Shape fill specification. */
+export type ShapeFill = SolidFill | GradientFill | PatternFill | NoFill;
+/** Line dash style. */
+export type LineDash = "solid" | "dot" | "dash" | "lgDash" | "dashDot" | "lgDashDot" | "lgDashDotDot" | "sysDot" | "sysDash" | "sysDashDot" | "sysDashDotDot";
+/** Line end type (arrow head). */
+export type LineEndType = "none" | "triangle" | "stealth" | "diamond" | "oval" | "arrow";
+/** Line end size. */
+export type LineEndSize = "sm" | "med" | "lg";
+/** Line/outline specification. */
+export interface ShapeOutline {
+    /** Width in EMU. */
+    readonly width?: Emu;
+    /** Color. */
+    readonly color?: HexColor;
+    /** Dash style. */
+    readonly dash?: LineDash;
+    /** Join type. */
+    readonly join?: "round" | "bevel" | "miter";
+    /** Head end (start of line). */
+    readonly headEnd?: {
+        type: LineEndType;
+        width?: LineEndSize;
+        length?: LineEndSize;
+    };
+    /** Tail end (end of line). */
+    readonly tailEnd?: {
+        type: LineEndType;
+        width?: LineEndSize;
+        length?: LineEndSize;
+    };
+    /** No outline. */
+    readonly noLine?: boolean;
+}
+/** Shadow effect. */
+export interface ShadowEffect {
+    readonly type: "outer" | "inner";
+    readonly color: HexColor;
+    readonly transparency?: number;
+    /** Blur radius in EMU. */
+    readonly blurRadius?: Emu;
+    /** Distance in EMU. */
+    readonly distance?: Emu;
+    /** Direction in 60,000ths of a degree. */
+    readonly direction?: number;
+}
+/** Glow effect. */
+export interface GlowEffect {
+    readonly color: HexColor;
+    readonly transparency?: number;
+    /** Radius in EMU. */
+    readonly radius: Emu;
+}
+/** Reflection effect. */
+export interface ReflectionEffect {
+    /** Blur radius in EMU. */
+    readonly blurRadius?: Emu;
+    /** Start transparency (0-100). */
+    readonly startOpacity?: number;
+    /** End transparency (0-100). */
+    readonly endOpacity?: number;
+    /** Distance in EMU. */
+    readonly distance?: Emu;
+    /** Direction in 60,000ths of a degree. */
+    readonly direction?: number;
+    /** Fade direction. */
+    readonly fadeDirection?: number;
+}
+/** 3D effect. */
+export interface Effect3D {
+    /** Rotation on X/Y/Z axes (in 60,000ths of a degree). */
+    readonly rotX?: number;
+    readonly rotY?: number;
+    readonly rotZ?: number;
+    /** Camera preset. */
+    readonly camera?: "orthographicFront" | "perspectiveFront" | "isometricTopDown" | "obliqueTopLeft";
+    /** Bevel top. */
+    readonly bevelTop?: {
+        width: Emu;
+        height: Emu;
+        preset?: string;
+    };
+    /** Bevel bottom. */
+    readonly bevelBottom?: {
+        width: Emu;
+        height: Emu;
+        preset?: string;
+    };
+    /** Extrusion depth in EMU. */
+    readonly extrusionDepth?: Emu;
+    /** Extrusion color. */
+    readonly extrusionColor?: HexColor;
+}
+/** Shape effects. */
+export interface ShapeEffects {
+    readonly shadow?: ShadowEffect;
+    readonly glow?: GlowEffect;
+    readonly reflection?: ReflectionEffect;
+    readonly effect3d?: Effect3D;
+    /** Soft edges radius in EMU. */
+    readonly softEdges?: Emu;
+}
+/** Vertical text anchor. */
+export type TextVerticalAnchor = "t" | "ctr" | "b";
+/** Text wrapping type within shape. */
+export type TextWrap = "none" | "square";
+/** Text body configuration for shapes. */
+export interface ShapeTextBody {
+    /** Content paragraphs. */
+    readonly paragraphs: readonly Paragraph[];
+    /** Vertical alignment. */
+    readonly anchor?: TextVerticalAnchor;
+    /** Wrap text within shape. */
+    readonly wrap?: TextWrap;
+    /** Internal margins (EMU). */
+    readonly margins?: {
+        readonly top?: Emu;
+        readonly bottom?: Emu;
+        readonly left?: Emu;
+        readonly right?: Emu;
+    };
+    /** Auto-fit text. */
+    readonly autoFit?: "none" | "normal" | "shrink";
+    /** Vertical text (for CJK). */
+    readonly vertical?: boolean;
+    /** Number of columns. */
+    readonly columns?: number;
+    /** Column spacing in EMU. */
+    readonly columnSpacing?: Emu;
+}
+/** Complete shape creation options. */
+export interface CreateShapeOptions {
+    /** Shape type (preset geometry). */
+    readonly shapeType: string;
+    /** Width in EMU. */
+    readonly width: Emu;
+    /** Height in EMU. */
+    readonly height: Emu;
+    /** Fill specification. */
+    readonly fill?: ShapeFill;
+    /** Outline specification. */
+    readonly outline?: ShapeOutline;
+    /** Effects (shadow, glow, etc.). */
+    readonly effects?: ShapeEffects;
+    /** Text content. */
+    readonly textBody?: ShapeTextBody;
+    /** Alternative text (accessibility). */
+    readonly altText?: string;
+    /** Shape name. */
+    readonly name?: string;
+    /** Rotation in 60,000ths of a degree. */
+    readonly rotation?: number;
+    /** Flip horizontally. */
+    readonly flipH?: boolean;
+    /** Flip vertically. */
+    readonly flipV?: boolean;
+    /** Horizontal position. */
+    readonly horizontalPosition?: {
+        readonly relativeTo?: HorizontalPositionRelative;
+        readonly offset?: Emu;
+        readonly align?: "left" | "center" | "right";
+    };
+    /** Vertical position. */
+    readonly verticalPosition?: {
+        readonly relativeTo?: VerticalPositionRelative;
+        readonly offset?: Emu;
+        readonly align?: "top" | "center" | "bottom";
+    };
+    /** Text wrapping. */
+    readonly wrap?: {
+        readonly style: WrapStyle;
+        readonly side?: WrapTextSide;
+    };
+    /** Behind document text. */
+    readonly behindDoc?: boolean;
+}
+/**
+ * Create an enhanced DrawingML shape with full styling options.
+ *
+ * Basic properties (solid fill, outline color/width, text paragraphs, positioning)
+ * are mapped directly to the `DrawingShape` interface fields. Advanced properties
+ * (gradient/pattern fills, effects, line details, text body formatting) are
+ * serialized into the `rawXml` field for preservation during packaging.
+ *
+ * @param options - Complete shape creation options.
+ * @returns A DrawingShape element for the document body.
+ */
+export declare function createShape(options: CreateShapeOptions): DrawingShape;
+/**
+ * Create a simple rectangle shape.
+ */
+export declare function createRect(width: Emu, height: Emu, options?: Partial<Omit<CreateShapeOptions, "shapeType" | "width" | "height">>): DrawingShape;
+/**
+ * Create a rounded rectangle shape.
+ */
+export declare function createRoundRect(width: Emu, height: Emu, options?: Partial<Omit<CreateShapeOptions, "shapeType" | "width" | "height">>): DrawingShape;
+/**
+ * Create an ellipse/circle shape.
+ */
+export declare function createEllipse(width: Emu, height: Emu, options?: Partial<Omit<CreateShapeOptions, "shapeType" | "width" | "height">>): DrawingShape;
+/**
+ * Create a line connector.
+ */
+export declare function createLine(width: Emu, height: Emu, options?: Partial<Omit<CreateShapeOptions, "shapeType" | "width" | "height">>): DrawingShape;
+/**
+ * Create an arrow shape.
+ */
+export declare function createArrow(direction: "right" | "left" | "up" | "down", width: Emu, height: Emu, options?: Partial<Omit<CreateShapeOptions, "shapeType" | "width" | "height">>): DrawingShape;
+/**
+ * Create a flowchart shape.
+ */
+export declare function createFlowchartShape(kind: "process" | "decision" | "terminator" | "document" | "data" | "connector" | "preparation", width: Emu, height: Emu, options?: Partial<Omit<CreateShapeOptions, "shapeType" | "width" | "height">>): DrawingShape;
+/**
+ * Create a callout shape.
+ */
+export declare function createCallout(style: "rect" | "roundRect" | "ellipse" | "cloud", width: Emu, height: Emu, options?: Partial<Omit<CreateShapeOptions, "shapeType" | "width" | "height">>): DrawingShape;
+/**
+ * Create a star shape.
+ */
+export declare function createStar(points: 4 | 5 | 6 | 7 | 8 | 10 | 12 | 16 | 24 | 32, width: Emu, height: Emu, options?: Partial<Omit<CreateShapeOptions, "shapeType" | "width" | "height">>): DrawingShape;

package/dist/types/modules/word/advanced/field-engine.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Word Document Field Calculation Engine
+ *
+ * Computes and updates field cachedValues based on layout (pagination) results.
+ * Supports PAGE, NUMPAGES, SECTIONPAGES, SECTION, TOC, REF, PAGEREF, SEQ, IF, STYLEREF,
+ * INDEX, = (formula), INCLUDETEXT.
+ *
+ * The engine performs a layout pass via layoutDocument, then traverses the document
+ * body to update each field's cachedValue in an immutable-style manner (deep-cloning
+ * modified portions of the tree).
+ */
+import { type LayoutOptions } from "../layout/layout.js";
+import type { DocxDocument } from "../types.js";
+/** 字段计算选项 */
+export interface FieldUpdateOptions {
+    /** 布局选项（传递给 layoutDocument）。 */
+    readonly layoutOptions?: LayoutOptions;
+    /** 是否更新 TOC（默认 true）。 */
+    readonly updateToc?: boolean;
+    /** 是否更新页码字段（默认 true）。 */
+    readonly updatePageFields?: boolean;
+    /** 是否更新交叉引用（默认 true）。 */
+    readonly updateReferences?: boolean;
+    /** 是否更新序列号（默认 true）。 */
+    readonly updateSequences?: boolean;
+}
+/**
+ * 更新文档中所有字段的 cachedValue。
+ *
+ * 执行分页布局，然后遍历所有字段更新其缓存值。
+ * 对于 TOC 字段，会生成完整的目录段落。
+ *
+ * @param doc - 文档模型（不会被修改，返回新对象）
+ * @param options - 更新选项
+ * @returns 更新后的文档模型
+ */
+export declare function updateFields(doc: DocxDocument, options?: FieldUpdateOptions): DocxDocument;
+/**
+ * 仅更新 TOC（目录）字段。
+ * 扫描文档中的标题（Heading1-9 样式或 outline level），
+ * 生成目录缓存段落。
+ */
+export declare function updateTableOfContents(doc: DocxDocument, options?: FieldUpdateOptions): DocxDocument;

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

@@ -0,0 +1,86 @@
+/**
+ * DOCX Module - Glossary Document (Building Blocks)
+ *
+ * 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:
+ * - 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".
+ */
+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>;
+}
+/**
+ * Create a building block entry.
+ *
+ * @param name - Display name of the building block.
+ * @param gallery - Which gallery it belongs to.
+ * @param content - The body content of the building block.
+ * @param options - Additional options.
+ * @returns A BuildingBlock instance.
+ *
+ * @example
+ * ```ts
+ * const autoText = createBuildingBlock("Greeting", "autoText", [
+ *   paragraph([text("Dear Sir/Madam,")])
+ * ]);
+ * ```
+ */
+export declare function createBuildingBlock(name: string, gallery: BuildingBlockGallery, content: readonly BodyContent[], options?: {
+    category?: string;
+    description?: string;
+    sectionProperties?: SectionProperties;
+}): BuildingBlock;
+/**
+ * Create a glossary document from building blocks.
+ */
+export declare function createGlossaryDocument(blocks: readonly BuildingBlock[]): GlossaryDocument;
+/**
+ * Find a building block by name and gallery.
+ */
+export declare function findBuildingBlock(glossary: GlossaryDocument, name: string, gallery?: BuildingBlockGallery): BuildingBlock | undefined;
+/**
+ * List all building blocks in a specific gallery.
+ */
+export declare function listBuildingBlocks(glossary: GlossaryDocument, gallery: BuildingBlockGallery): readonly BuildingBlock[];
+/**
+ * Extract AutoText entries from a glossary document.
+ */
+export declare function getAutoTextEntries(glossary: GlossaryDocument): readonly BuildingBlock[];
+/**
+ * Extract Quick Parts from a glossary document.
+ */
+export declare function getQuickParts(glossary: GlossaryDocument): readonly BuildingBlock[];

package/dist/types/modules/word/advanced/math-convert.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MathML ↔ OMML Conversion
+ *
+ * Provides bidirectional conversion between MathML strings and the internal
+ * OMML (Office Math Markup Language) model used by the Word module.
+ *
+ * @stability experimental
+ *
+ * Coverage: fractions, superscript, subscript, radicals, nary operators
+ * (sum/integral/product), delimiters (parentheses/brackets), and matrices.
+ */
+import type { MathContent } from "../types.js";
+/**
+ * Convert OMML model content to a MathML string.
+ *
+ * @param content - Array of MathContent nodes from the OMML model
+ * @returns A complete MathML string wrapped in `<math>` element
+ *
+ * @stability experimental
+ */
+export declare function ommlToMathML(content: readonly MathContent[]): string;
+/**
+ * Convert a MathML string to OMML model content.
+ *
+ * @param mathml - A MathML string (with or without the outer `<math>` wrapper)
+ * @returns Array of MathContent nodes for the OMML model
+ *
+ * @stability experimental
+ */
+export declare function mathMLToOmml(mathml: string): MathContent[];

package/dist/types/modules/word/advanced/ole-objects.d.ts

@@ -0,0 +1,115 @@
+/**
+ * DOCX Module - OLE Embedded Objects
+ *
+ * Provides support for reading and round-tripping OLE (Object Linking and Embedding)
+ * objects within DOCX files. OLE objects allow embedding other documents (Excel
+ * spreadsheets, PowerPoint presentations, PDFs, etc.) within a Word document.
+ *
+ * OLE objects in OOXML are stored as:
+ * - Binary data in word/embeddings/*.bin (OLE2 compound document)
+ * - Referenced via r:id in w:object/o:OLEObject elements
+ * - May have a preview image (EMF/WMF) in word/media/
+ *
+ * This module focuses on preservation (round-trip) and metadata extraction,
+ * not full OLE compound document manipulation.
+ */
+import type { DocxDocument, OpaquePart } from "../types.js";
+/** OLE object type classification. */
+export type OleObjectType = "embedded" | "linked";
+/** OLE object display style. */
+export type OleDisplayAs = "icon" | "content";
+/** Metadata about an OLE embedded object. */
+export interface OleObject {
+    /** Unique relationship ID for the OLE binary. */
+    readonly rId: string;
+    /** OLE ProgId (e.g. "Excel.Sheet.12", "PowerPoint.Slide.12", "Package"). */
+    readonly progId: string;
+    /** Whether the object is embedded or linked. */
+    readonly objectType: OleObjectType;
+    /** Display mode. */
+    readonly displayAs: OleDisplayAs;
+    /** Relationship ID for the preview image (EMF/WMF). */
+    readonly imageRId?: string;
+    /** Shape ID for the hosting VML shape. */
+    readonly shapeId?: string;
+    /** Object width in EMU. */
+    readonly width?: number;
+    /** Object height in EMU. */
+    readonly height?: number;
+    /** File name of the embedded data within the archive. */
+    readonly fileName?: string;
+    /** The raw binary data of the OLE object. */
+    readonly data?: Uint8Array;
+    /** Link target (for linked objects). */
+    readonly linkTarget?: string;
+    /** Raw XML of the w:object element for round-trip preservation. */
+    readonly rawXml?: string;
+}
+/** Result of extracting OLE objects from a document. */
+export interface OleExtractionResult {
+    /** All OLE objects found in the document. */
+    readonly objects: readonly OleObject[];
+    /** Mapping of progId to count. */
+    readonly summary: Readonly<Record<string, number>>;
+}
+/**
+ * Extract metadata about OLE embedded objects from a parsed DOCX document.
+ * OLE objects are preserved in opaqueParts during reading; this function
+ * inspects them to extract meaningful metadata.
+ *
+ * @param doc - The parsed DOCX document.
+ * @returns Extraction result with OLE object metadata.
+ */
+export declare function extractOleObjects(doc: DocxDocument): OleExtractionResult;
+/**
+ * Check if a document contains any OLE embedded objects.
+ */
+export declare function hasOleObjects(doc: DocxDocument): boolean;
+/**
+ * Get the binary data of a specific OLE object by its relationship ID.
+ * Returns undefined if not found.
+ */
+export declare function getOleObjectData(doc: DocxDocument, rId: string): Uint8Array | undefined;
+/**
+ * Result of `createOleEmbedding`. Contains the OLE binary part and,
+ * when a preview image was supplied, an additional media part for it
+ * plus the relationship rIds the caller should reference from the body
+ * model.
+ */
+export interface OleEmbeddingResult {
+    /** OLE binary opaque part (always present). */
+    readonly olePart: OpaquePart;
+    /** Suggested rId to use for the OLE binary in the document model. */
+    readonly oleRId: string;
+    /** Preview image media part (only when `options.previewImage` was supplied). */
+    readonly previewPart?: OpaquePart;
+    /** Suggested rId for the preview image. */
+    readonly previewRId?: string;
+}
+/**
+ * Create an OLE embedding plus, optionally, its preview image.
+ *
+ * Returns an {@link OleEmbeddingResult} with one or two `OpaquePart`s plus
+ * suggested relationship IDs. Each call gets a unique counter-based file
+ * name so calling this helper repeatedly does not produce path
+ * collisions; pass `options.fileName` to force a specific name.
+ *
+ * The previous signature returned only one `OpaquePart` and silently
+ * dropped `options.previewImage` / `options.previewContentType`. That has
+ * been removed — the new shape forces callers to wire up preview parts
+ * properly when they want one.
+ *
+ * @param data - The binary data of the OLE object (OLE2 compound document).
+ * @param progId - The OLE ProgId (e.g. "Excel.Sheet.12").
+ * @param options - Additional options.
+ */
+export declare function createOleEmbedding(data: Uint8Array, progId: string, options?: {
+    /** Override file name. Defaults to `oleObject<N>.bin` with a process-unique counter. */
+    fileName?: string;
+    /** Optional preview image bytes (typically EMF or PNG). */
+    previewImage?: Uint8Array;
+    /** Content type for the preview image. Required when `previewImage` is set. */
+    previewContentType?: string;
+    /** Override preview file name. Defaults to `image<N>.<ext>` from previewContentType. */
+    previewFileName?: string;
+}): OleEmbeddingResult;