@cj-tech-master/excelts 9.6.1 → 10.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://github.com/cjnoname/excelts/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/cjnoname/excelts/actions/workflows/ci.yml)   [中文](README_zh.md)
 
-The TypeScript ecosystem is heavily fragmented when it comes to document and data processing. To handle Excel, PDF, CSV, XML, ZIP, and streaming, developers often need to pull in a different package for each task — and then yet another set of packages to make them work in the browser, plus separate streaming wrappers on top. These libraries vary in API style, quality, and maintenance status, creating a tax on every project that needs more than one of them.
+The TypeScript ecosystem is heavily fragmented when it comes to document and data processing. To work with spreadsheets, documents, PDFs, and the many data and archive formats around them, developers often need to pull in a different package for each task — and then yet another set of packages to make them work in the browser, plus separate streaming wrappers on top. These libraries vary in API style, quality, and maintenance status, creating a tax on every project that needs more than one of them.
 
 ExcelTS was built to fix this. One package, one consistent API, one codebase — working identically across Node.js, Bun, and browsers. Streaming is a first-class citizen in every module, not an afterthought bolted on through a third-party adapter. The goal is simple: install once, import what you need, and get the same reliable behavior everywhere — with maximum streaming performance out of the box.
 
@@ -12,13 +12,13 @@ ExcelTS is a zero-dependency TypeScript toolkit for spreadsheets and documents:
 
 - **AI-Friendly** — Clean, consistent API designed for AI coding agents. Every module has comprehensive documentation and runnable examples for AI to learn from
 - **Zero Runtime Dependencies** — Pure TypeScript, no external packages
-- **Eight Modules** — Excel, Formula, PDF, CSV, Markdown, XML, Archive, Stream
+- **Nine Modules** — Excel, Word, Formula, PDF, CSV, Markdown, XML, Archive, Stream
 - **Cross-Platform** — Node.js 22+, Bun, Chrome 89+, Firefox 102+, Safari 14.1+
 - **ESM First** — Native ES Modules with CommonJS compatibility and full tree-shaking
 
 ## Modules
 
-ExcelTS is organized into eight standalone modules. Each module has its own documentation and runnable examples.
+ExcelTS is organized into nine standalone modules. Each module has its own documentation and runnable examples.
 
 ### Excel — XLSX/JSON Workbook Manager
 
@@ -27,6 +27,13 @@ Create, read, and modify Excel spreadsheets with full styling, formulas, images,
 - [Documentation](src/modules/excel/README.md) | [中文](src/modules/excel/README_zh.md)
 - [Examples](src/modules/excel/examples/)
 
+### Word — DOCX Document Processor
+
+Read, write, and manipulate DOCX files with a full builder, reader, and converter surface. Build documents with headings, tables, images, lists, headers/footers, drawing shapes, math, and charts. Read and modify existing files with text search/replace, format-aware queries, and bookmark/comment lookup. Convert to and from HTML and Markdown, bridge Excel workbooks into Word tables, and render Word straight to PDF. Advanced features include a template engine, form fields, OpenDoPE data binding, font embedding with subsetting, track-changes accept/reject, document diff/merge, streaming writer, password protection, Agile-encryption decryption, and digital-signature inspection.
+
+- [Documentation](src/modules/word/README.md) | [中文](src/modules/word/README_zh.md)
+- [Examples](src/modules/word/examples/)
+
 ### Formula — Excel-Compatible Calculation Engine
 
 Standalone 433-function calculation engine with tokenizer, parser, dependency graph, dynamic-array spill, and `LAMBDA`/`LET`/`MAP`/`REDUCE` support. Ships as a separate subpath so it stays out of bundles that only need to read/write XLSX. **Works in two modes**: paired with `Workbook` via `installFormulaEngine()`, or standalone on any `WorkbookLike` host via `calculateFormulas()` — the engine itself has zero excel runtime dependencies.
@@ -150,6 +157,14 @@ const archive = await zip().add("hello.txt", "Hello!").bytes();
 import { parseMarkdown, formatMarkdown } from "@cj-tech-master/excelts/markdown";
 const table = parseMarkdown("| A | B |\n|---|---|\n| 1 | 2 |");
 
+// Word — create, read, and convert DOCX
+import { Document, toBuffer, readDocx } from "@cj-tech-master/excelts/word";
+const wdoc = Document.create();
+Document.addHeading(wdoc, "Report", 1);
+Document.addParagraph(wdoc, "Generated by ExcelTS.");
+const docxBytes = await toBuffer(Document.build(wdoc));
+const parsedDocx = await readDocx(docxBytes); // round-trip read
+
 // Formula — opt-in calculation engine (kept out of the base bundle)
 //
 // Mode A: paired with Workbook — enables wb.calculateFormulas()

package/README_zh.md

@@ -2,7 +2,7 @@
 
 [![构建状态](https://github.com/cjnoname/excelts/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/cjnoname/excelts/actions/workflows/ci.yml)   [English](README.md)
 
-TypeScript 生态在文档和数据处理领域长期存在碎片化问题。处理 Excel、PDF、CSV、XML、ZIP 和流式操作，往往需要分别引入不同的包；到了浏览器端又要换一套方案；流式处理还得再额外接入一个适配库。这些库的 API 风格、质量和维护状态参差不齐，给每个需要组合使用它们的项目都带来了额外的负担。
+TypeScript 生态在文档和数据处理领域长期存在碎片化问题。要处理电子表格、文档、PDF 以及围绕它们的各种数据和归档格式，往往需要分别引入不同的包；到了浏览器端又要换一套方案；流式处理还得再额外接入一个适配库。这些库的 API 风格、质量和维护状态参差不齐，给每个需要组合使用它们的项目都带来了额外的负担。
 
 ExcelTS 正是为了解决这个问题而生。一个包、一套 API、一份代码 — 在 Node.js、Bun 和浏览器中行为完全一致。流式处理是每个模块的一等公民，而非通过第三方适配器后期拼装的附属品。目标很简单：安装一次，按需导入，在任何环境下都获得相同的可靠体验 — 同时将流式处理的性能发挥到极致。
 
@@ -12,13 +12,13 @@ ExcelTS 是一个零依赖的 TypeScript 电子表格和文档工具包：
 
 - **AI 友好** — 简洁一致的 API,专为 AI 编程助手设计。每个模块都配有完整的文档和可运行的示例供 AI 学习
 - **零运行时依赖** — 纯 TypeScript,无外部包
-- **八大模块** — Excel、Formula、PDF、CSV、Markdown、XML、Archive、Stream
+- **九大模块** — Excel、Word、Formula、PDF、CSV、Markdown、XML、Archive、Stream
 - **跨平台** — Node.js 22+、Bun、Chrome 89+、Firefox 102+、Safari 14.1+
 - **ESM 优先** — 原生 ES Modules,兼容 CommonJS,完整的 tree-shaking 支持
 
 ## 模块
 
-ExcelTS 由八个独立模块组成,每个模块都有自己的文档和可运行示例。
+ExcelTS 由九个独立模块组成,每个模块都有自己的文档和可运行示例。
 
 ### Excel — XLSX/JSON 工作簿管理器
 
@@ -27,6 +27,13 @@ ExcelTS 由八个独立模块组成,每个模块都有自己的文档和可运
 - [文档](src/modules/excel/README.md) | [中文](src/modules/excel/README_zh.md)
 - [示例](src/modules/excel/examples/)
 
+### Word — DOCX 文档处理器
+
+读取、写入和操作 DOCX 文件,提供完整的构建器、读取器和转换器能力。可构建含标题、表格、图片、列表、页眉/页脚、绘图形状、数学公式和图表的文档；可对现有文件做文本查找/替换、格式感知查询、书签/批注查找等读取与修改;可与 HTML 和 Markdown 互相转换,将 Excel 工作簿桥接为 Word 表格,并将 Word 直接渲染为 PDF。高级功能包括模板引擎、表单字段、OpenDoPE 数据绑定、字体嵌入与子集化、修订追踪接受/拒绝、文档比对/合并、流式写入器、密码保护、Agile 加密解密以及数字签名检测。
+
+- [文档](src/modules/word/README.md) | [中文](src/modules/word/README_zh.md)
+- [示例](src/modules/word/examples/)
+
 ### Formula — Excel 兼容公式引擎
 
 独立的 433 函数计算引擎,包含 tokenizer、parser、依赖图、动态数组 spill,支持 `LAMBDA`/`LET`/`MAP`/`REDUCE`。作为单独的 subpath 发布,不会被打进只读写 XLSX 的 bundle。**两种使用模式**:通过 `installFormulaEngine()` 和 `Workbook` 配合使用,或通过 `calculateFormulas()` 对任意 `WorkbookLike` 宿主单独使用 — 引擎本身**零 excel 运行时依赖**。
@@ -135,6 +142,14 @@ const archive = await zip().add("hello.txt", "Hello!").bytes();
 import { parseMarkdown, formatMarkdown } from "@cj-tech-master/excelts/markdown";
 const table = parseMarkdown("| A | B |\n|---|---|\n| 1 | 2 |");
 
+// Word — 创建、读取和转换 DOCX
+import { Document, toBuffer, readDocx } from "@cj-tech-master/excelts/word";
+const wdoc = Document.create();
+Document.addHeading(wdoc, "报告", 1);
+Document.addParagraph(wdoc, "由 ExcelTS 生成。");
+const docxBytes = await toBuffer(Document.build(wdoc));
+const parsedDocx = await readDocx(docxBytes); // 往返读取
+
 // Formula — 可选的公式引擎(默认不打进主 bundle)
 //
 // 模式 A: 配合 Workbook — 启用 wb.calculateFormulas()

package/dist/browser/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/browser/modules/excel/note.js

@@ -36,7 +36,11 @@ class Note {
     set model(value) {
         const { note } = value;
         const { texts } = note;
-        if (texts && texts.length === 1 && Object.keys(texts[0]).length === 1) {
+        // A single, plain text run with no extra box geometry can be flattened
+        // back to a simple string. Custom width/height must keep the full config
+        // so the sizing survives the model round-trip.
+        const hasCustomSize = note.width !== undefined || note.height !== undefined;
+        if (texts && texts.length === 1 && Object.keys(texts[0]).length === 1 && !hasCustomSize) {
             this.note = texts[0].text;
         }
         else {

package/dist/browser/modules/excel/row.js

@@ -213,12 +213,13 @@ class Row {
             // (e.g. DB entities). Cell.value setter handles unknown values via Value.getType
             // fallback to JSON type, so this cast is safe at runtime.
             this._worksheet.eachColumnKey((column, key) => {
-                if (value[key] !== undefined) {
+                const resolved = resolveColumnKeyValue(value, key);
+                if (resolved !== undefined) {
                     this.getCellEx({
                         address: colCache.encodeAddress(this._number, column.number),
                         row: this._number,
                         col: column.number
-                    }).value = value[key];
+                    }).value = resolved;
                 }
             });
         }
@@ -459,4 +460,36 @@ class Row {
         this.style = value.style ? structuredClone(value.style) : {};
     }
 }
+/**
+ * Resolve a column key against a row object, supporting dotted nested paths.
+ *
+ * A key without a `.` takes the original fast path (`obj[key]`), preserving
+ * exact backward compatibility — including keys that legitimately contain a
+ * dot only as a flat property name, which still resolve via the fast path
+ * first. A dotted key (e.g. `"address.city"`) is resolved by walking each
+ * segment; if any segment is missing or not an object, the result is
+ * `undefined` (the same signal the caller already uses to skip a cell).
+ *
+ * @param obj - The row object supplied to `row.values = {...}` / `addRow({...})`.
+ * @param key - The column key, optionally a dotted path.
+ * @returns The resolved value, or `undefined` when the path cannot be followed.
+ */
+function resolveColumnKeyValue(obj, key) {
+    // Fast path: a flat key (no dot) or an exact flat property match. This keeps
+    // existing behaviour identical and also lets a literal "a.b" property win
+    // over nested traversal when it is actually present on the object.
+    const direct = obj[key];
+    if (direct !== undefined || !key.includes(".")) {
+        return direct;
+    }
+    // Dotted path: walk segments, bailing out to undefined on any gap.
+    let current = obj;
+    for (const segment of key.split(".")) {
+        if (current === null || typeof current !== "object") {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
 export { Row };

package/dist/browser/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/browser/modules/excel/stream/workbook-writer.browser.js

@@ -387,13 +387,33 @@ export class WorkbookWriterBase {
      * ```
      */
     addImage(image) {
+        const { svg, ...raster } = image;
+        if (svg &&
+            raster.link &&
+            raster.buffer == null &&
+            raster.base64 == null &&
+            raster.filename == null) {
+            throw new ImageError("An SVG image requires an embedded raster fallback (buffer/base64/filename); it cannot be combined with an external link.");
+        }
         const id = this.media.length;
         const medium = {
-            ...image,
+            ...raster,
             type: "image",
-            name: `image${id}.${image.extension}`
+            name: `image${id}.${raster.extension}`
         };
         this.media.push(medium);
+        if (svg) {
+            // Register the SVG companion as a second image medium and link it back to
+            // the raster blip so the drawing serializer emits the svgBlip extension.
+            const svgId = this.media.length;
+            this.media.push({
+                ...svg,
+                type: "image",
+                extension: "svg",
+                name: `image${svgId}.svg`
+            });
+            medium.svgMediaId = svgId;
+        }
         return id;
     }
     getImage(id) {

package/dist/browser/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/browser/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/browser/modules/excel/utils/drawing-utils.js

@@ -122,6 +122,23 @@ export function buildDrawingAnchorsAndRels(media, existingRels, options) {
             },
             range: medium.range
         };
+        // SVG companion: allocate (and dedupe) a rel for the vector media, then
+        // record its rId so the blip serializer emits the asvg:svgBlip extension.
+        if (bookImage.svgMediaId !== undefined) {
+            const svgKey = `svg:${bookImage.svgMediaId}`;
+            let rIdSvg = imageRIdMap[svgKey];
+            if (!rIdSvg) {
+                const svgImage = options.getBookImage(bookImage.svgMediaId);
+                if (svgImage) {
+                    rIdSvg = options.nextRId(rels);
+                    imageRIdMap[svgKey] = rIdSvg;
+                    rels.push(buildImageRel(rIdSvg, svgImage));
+                }
+            }
+            if (rIdSvg) {
+                anchor.picture.svgRId = rIdSvg;
+            }
+        }
         // Pass through watermark opacity as alphaModFix
         if (medium.opacity !== undefined) {
             const clamped = Math.max(0, Math.min(1, medium.opacity));
@@ -172,8 +189,8 @@ export function filterDrawingAnchors(anchors) {
         if (a.range?.br && a.shape) {
             return true;
         }
-        // One-cell anchors need a valid picture or graphicFrame (charts)
-        if (!a.range?.br && !a.picture && !a.graphicFrame) {
+        // One-cell anchors need a valid picture, graphicFrame (charts) or shape.
+        if (!a.range?.br && !a.picture && !a.graphicFrame && !a.shape) {
             return false;
         }
         // Two-cell anchors need either picture, shape, or graphicFrame (charts)

package/dist/browser/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/browser/modules/excel/workbook.browser.js

@@ -20,7 +20,7 @@ import { parseNumberFromCsv } from "../csv/utils/number.js";
 import { getChartSupport } from "./chart-host-registry.js";
 import { Chartsheet } from "./chartsheet.js";
 import { DefinedNames } from "./defined-names.js";
-import { ExcelDownloadError, ExcelNotSupportedError, WorksheetNameError } from "./errors.js";
+import { ExcelDownloadError, ExcelNotSupportedError, ImageError, WorksheetNameError } from "./errors.js";
 import { withPivotChartSource } from "./pivot-chart.js";
 import { WorkbookReader } from "./stream/workbook-reader.browser.js";
 import { WorkbookWriter } from "./stream/workbook-writer.browser.js";
@@ -1733,10 +1733,40 @@ 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) {
+        const { svg, ...raster } = image;
+        if (svg &&
+            raster.link &&
+            raster.buffer == null &&
+            raster.base64 == null &&
+            raster.filename == null) {
+            // An SVG companion needs an embedded raster fallback; a *linked* (external)
+            // raster has no package part to attach the svgBlip extension to.
+            throw new ImageError("An SVG image requires an embedded raster fallback (buffer/base64/filename); it cannot be combined with an external link.");
+        }
         const id = this.media.length;
-        this.media.push({ ...image, type: "image" });
+        const rasterMedia = { ...raster, type: "image" };
+        this.media.push(rasterMedia);
+        if (svg) {
+            // Register the SVG as a second `type: "image"` media so it flows through
+            // the existing media naming, content-types, and zip-writing paths. Link
+            // it back to the raster blip so the drawing serializer can emit the
+            // asvg:svgBlip extension.
+            const svgId = this.media.length;
+            this.media.push({ ...svg, type: "image", extension: "svg" });
+            rasterMedia.svgMediaId = svgId;
+        }
         return id;
     }
     getImage(id) {

package/dist/browser/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/browser/modules/excel/worksheet.js

@@ -105,6 +105,8 @@ class Worksheet {
         this.autoFilter = options.autoFilter ?? null;
         // for images, etc
         this._media = [];
+        // for user-drawn shapes (rectangles, lines, text boxes, …)
+        this._shapes = [];
         // for charts
         this._charts = [];
         this._sparklineGroups = [];
@@ -1009,6 +1011,85 @@ class Worksheet {
         };
         this._media.push(new Image(this, model));
     }
+    /**
+     * 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) {
+        const range = options.range;
+        // A shape must cover an area, mirroring images. Reject inputs that resolve
+        // to no size up front, with a clear shape-specific message — otherwise the
+        // failure surfaces much later as a confusing `ImageError` from the internal
+        // range parser when the worksheet is serialized.
+        const hasArea = (typeof range === "string" && range.includes(":")) ||
+            (typeof range === "object" &&
+                range !== null &&
+                ("br" in range || "ext" in range || "pos" in range));
+        if (!hasArea) {
+            throw new ImageError('addShape requires a range covering an area: a cell range like "B2:D5", or an object with `br`, `ext`, or `pos`.');
+        }
+        this._shapes.push({
+            type: "shape",
+            shapeType: options.type ?? "rect",
+            range,
+            fillColor: options.fillColor,
+            lineColor: options.lineColor,
+            lineWidth: options.lineWidth,
+            text: options.text,
+            name: options.name
+        });
+    }
+    /** All shapes added to this worksheet. */
+    getShapes() {
+        return this._shapes.slice();
+    }
+    /**
+     * 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.
+     */
+    _resolveShapeModel(shape) {
+        let range;
+        try {
+            const probe = new Image(this, { type: "image", imageId: "", range: shape.range });
+            // The probe is always an "image" type, so its model carries `range`.
+            range = probe.model.range;
+        }
+        catch {
+            // Range could not be parsed into an anchor (addShape validates the common
+            // cases up front; this guards exotic inputs). Drop the anchor so the
+            // serializer skips this shape rather than failing the whole worksheet.
+            range = undefined;
+        }
+        if (!range) {
+            return { ...shape, anchorRange: undefined };
+        }
+        return {
+            ...shape,
+            anchorRange: {
+                tl: range.tl,
+                br: range.br,
+                ext: range.ext,
+                pos: range.pos,
+                editAs: range.editAs
+            }
+        };
+    }
     getImages() {
         return this._media.filter(m => m.type === "image");
     }
@@ -1754,6 +1835,7 @@ class Worksheet {
             views: this.views,
             autoFilter: this.autoFilter,
             media: this._media.map(medium => medium.model),
+            shapes: this._shapes.map(shape => this._resolveShapeModel(shape)),
             sheetProtection: this.sheetProtection,
             tables: Object.values(this.tables).map(table => table.model),
             pivotTables: this.pivotTables,
@@ -1819,6 +1901,7 @@ class Worksheet {
         this.views = value.views;
         this.autoFilter = value.autoFilter;
         this._media = value.media.map(medium => new Image(this, medium));
+        this._shapes = value.shapes ? value.shapes.slice() : [];
         // Restore watermark state from media entries
         this._watermark = value.watermark ?? null;
         if (!this._watermark) {