@cj-tech-master/excelts 9.2.1 → 9.3.0

package/README.md

@@ -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
-- **Seven Modules** — Excel, PDF, CSV, Markdown, XML, Archive, Stream
+- **Eight Modules** — Excel, 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 seven standalone modules. Each module has its own documentation and runnable examples.
+ExcelTS is organized into eight 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/)
 
+### 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.
+
+- [Documentation](src/modules/formula/README.md) | [中文](src/modules/formula/README_zh.md)
+- [Examples](src/modules/formula/examples/)
+
 ### PDF — Zero-Dependency PDF Engine
 
 Full-featured PDF generation, reading, building, editing, and signing. Write PDFs with font embedding, AES-256 encryption, images, and Excel-to-PDF conversion. Build free-form PDFs with text, vector graphics, SVG paths, annotations, and form fields. Edit existing PDFs with overlays, form filling, page manipulation, and merging. Read any PDF with text, image, annotation, form field, bookmark, and metadata extraction. Verify and create digital signatures with PKCS#7/CMS.
@@ -142,6 +149,18 @@ const archive = await zip().add("hello.txt", "Hello!").bytes();
 // Markdown — parse and format tables
 import { parseMarkdown, formatMarkdown } from "@cj-tech-master/excelts/markdown";
 const table = parseMarkdown("| A | B |\n|---|---|\n| 1 | 2 |");
+
+// Formula — opt-in calculation engine (kept out of the base bundle)
+//
+// Mode A: paired with Workbook — enables wb.calculateFormulas()
+import { installFormulaEngine } from "@cj-tech-master/excelts/formula";
+installFormulaEngine(); // once at startup
+sheet.getCell("A4").value = { formula: "SUM(A1:A3)" };
+workbook.calculateFormulas(); // now populates cell.result
+
+// Mode B: standalone — pure function, zero excel runtime, any WorkbookLike
+import { calculateFormulas } from "@cj-tech-master/excelts/formula";
+calculateFormulas(anyWorkbookLikeObject);
 ```
 
 ## Browser Support
@@ -159,6 +178,10 @@ const buffer = await new Workbook().addWorksheet("S1").workbook.xlsx.writeBuffer
 <script src="https://unpkg.com/@cj-tech-master/excelts/dist/iife/excelts.iife.min.js"></script>
 ```
 
+> The IIFE bundle does not include the formula calculation engine. Use
+> ESM + `@cj-tech-master/excelts/formula` if you need
+> `Workbook.calculateFormulas()`.
+
 For older browsers without native `CompressionStream` API, ExcelTS automatically uses a built-in pure JavaScript DEFLATE implementation — no polyfills needed.
 
 ## Requirements

package/README_zh.md

@@ -10,23 +10,30 @@ ExcelTS 正是为了解决这个问题而生。一个包、一套 API、一份
 
 ExcelTS 是一个零依赖的 TypeScript 电子表格和文档工具包：
 
-- **AI 友好** — 简洁一致的 API，专为 AI 编程助手设计。每个模块都配有完整的文档和可运行的示例供 AI 学习
-- **零运行时依赖** — 纯 TypeScript，无外部包
-- **七大模块** — Excel、PDF、CSV、Markdown、XML、Archive、Stream
+- **AI 友好** — 简洁一致的 API,专为 AI 编程助手设计。每个模块都配有完整的文档和可运行的示例供 AI 学习
+- **零运行时依赖** — 纯 TypeScript,无外部包
+- **八大模块** — Excel、Formula、PDF、CSV、Markdown、XML、Archive、Stream
 - **跨平台** — Node.js 22+、Bun、Chrome 89+、Firefox 102+、Safari 14.1+
-- **ESM 优先** — 原生 ES Modules，兼容 CommonJS，完整的 tree-shaking 支持
+- **ESM 优先** — 原生 ES Modules,兼容 CommonJS,完整的 tree-shaking 支持
 
 ## 模块
 
-ExcelTS 由七个独立模块组成，每个模块都有自己的文档和可运行示例。
+ExcelTS 由八个独立模块组成,每个模块都有自己的文档和可运行示例。
 
 ### Excel — XLSX/JSON 工作簿管理器
 
-创建、读取和修改 Excel 电子表格，完整支持样式、公式、图片和流式处理。
+创建、读取和修改 Excel 电子表格,完整支持样式、公式、图片和流式处理。
 
 - [文档](src/modules/excel/README.md) | [中文](src/modules/excel/README_zh.md)
 - [示例](src/modules/excel/examples/)
 
+### Formula — Excel 兼容公式引擎
+
+独立的 433 函数计算引擎,包含 tokenizer、parser、依赖图、动态数组 spill,支持 `LAMBDA`/`LET`/`MAP`/`REDUCE`。作为单独的 subpath 发布,不会被打进只读写 XLSX 的 bundle。**两种使用模式**:通过 `installFormulaEngine()` 和 `Workbook` 配合使用,或通过 `calculateFormulas()` 对任意 `WorkbookLike` 宿主单独使用 — 引擎本身**零 excel 运行时依赖**。
+
+- [文档](src/modules/formula/README.md) | [中文](src/modules/formula/README_zh.md)
+- [示例](src/modules/formula/examples/)
+
 ### PDF — 零依赖 PDF 引擎
 
 功能完整的 PDF 生成和读取。写入支持字体嵌入、AES-256 加密、图片和 Excel 转 PDF。读取支持从任意 PDF 提取文本、图片、注解、表单字段和元数据。
@@ -127,6 +134,18 @@ const archive = await zip().add("hello.txt", "Hello!").bytes();
 // Markdown — 解析和格式化表格
 import { parseMarkdown, formatMarkdown } from "@cj-tech-master/excelts/markdown";
 const table = parseMarkdown("| A | B |\n|---|---|\n| 1 | 2 |");
+
+// Formula — 可选的公式引擎(默认不打进主 bundle)
+//
+// 模式 A: 配合 Workbook — 启用 wb.calculateFormulas()
+import { installFormulaEngine } from "@cj-tech-master/excelts/formula";
+installFormulaEngine(); // 启动时调用一次
+sheet.getCell("A4").value = { formula: "SUM(A1:A3)" };
+workbook.calculateFormulas(); // 现在能填 cell.result 了
+
+// 模式 B: 单独使用 — 纯函数,零 excel 运行时,接受任意 WorkbookLike
+import { calculateFormulas } from "@cj-tech-master/excelts/formula";
+calculateFormulas(anyWorkbookLikeObject);
 ```
 
 ## 浏览器支持
@@ -144,6 +163,10 @@ const buffer = await new Workbook().addWorksheet("S1").workbook.xlsx.writeBuffer
 <script src="https://unpkg.com/@cj-tech-master/excelts/dist/iife/excelts.iife.min.js"></script>
 ```
 
+> IIFE 打包产物不包含公式计算引擎。如果需要调用
+> `Workbook.calculateFormulas()`，请改用 ESM + 导入
+> `@cj-tech-master/excelts/formula`。
+
 对于不支持原生 `CompressionStream` API 的旧版浏览器，ExcelTS 自动使用内置的纯 JavaScript DEFLATE 实现 — 无需 polyfill。
 
 ## 系统要求

package/dist/browser/index.browser.d.ts

@@ -31,7 +31,7 @@ export { DefinedNames, type DefinedNameModel } from "./modules/excel/defined-nam
 export type { CheckboxState } from "./modules/excel/form-control.js";
 export type { ColumnDefn, ColumnHeaderValue } from "./modules/excel/column.js";
 export type { RangeInput } from "./modules/excel/range.js";
-export type { WorkbookModel, WorkbookMedia } from "./modules/excel/workbook.js";
+export type { WorkbookModel, WorkbookMedia, WorkbookProtectionModel, ExternalLinkModel, ExternalLinkCachedSheet } from "./modules/excel/workbook.js";
 export { decodeCol, encodeCol, decodeRow, encodeRow, decodeCell, encodeCell, decodeRange, encodeRange } from "./modules/excel/utils/address.js";
 export type { CellAddress, SheetRange, Origin } from "./modules/excel/utils/address.js";
 export type { SheetToJSONOptions, AddJSONOptions, AddAOAOptions } from "./modules/excel/worksheet.js";

package/dist/browser/index.browser.js

@@ -16,6 +16,10 @@ export * from "./modules/excel/anchor.js";
 export { Table } from "./modules/excel/table.js";
 export { DataValidations } from "./modules/excel/data-validations.js";
 export { FormCheckbox } from "./modules/excel/form-control.js";
+// Note: the formula engine lives at the `./formula` subpath so it stays
+// out of bundles that only need to read / write XLSX files. Import
+// `@cj-tech-master/excelts/formula` to enable `Workbook.calculateFormulas()`
+// and automatic recalculation in `excelToPdf()`.
 // =============================================================================
 // Enums
 // =============================================================================

package/dist/browser/index.d.ts

@@ -30,7 +30,7 @@ export { DefinedNames, type DefinedNameModel } from "./modules/excel/defined-nam
 export type { CheckboxState } from "./modules/excel/form-control.js";
 export type { ColumnDefn, ColumnHeaderValue } from "./modules/excel/column.js";
 export type { RangeInput } from "./modules/excel/range.js";
-export type { WorkbookModel, WorkbookMedia } from "./modules/excel/workbook.js";
+export type { WorkbookModel, WorkbookMedia, WorkbookProtectionModel, ExternalLinkModel, ExternalLinkCachedSheet } from "./modules/excel/workbook.js";
 export type { NodeInput } from "./modules/excel/stream/workbook-reader.js";
 export { decodeCol, encodeCol, decodeRow, encodeRow, decodeCell, encodeCell, decodeRange, encodeRange } from "./modules/excel/utils/address.js";
 export type { CellAddress, SheetRange, Origin } from "./modules/excel/utils/address.js";

package/dist/browser/index.js

@@ -12,6 +12,10 @@ export * from "./modules/excel/anchor.js";
 export { Table } from "./modules/excel/table.js";
 export { DataValidations } from "./modules/excel/data-validations.js";
 export { FormCheckbox } from "./modules/excel/form-control.js";
+// Note: the formula engine lives at the `./formula` subpath so it stays
+// out of bundles that only need to read / write XLSX files. Import
+// `@cj-tech-master/excelts/formula` to enable `Workbook.calculateFormulas()`
+// and automatic recalculation in `excelToPdf()`.
 // =============================================================================
 // Node.js Only: Streaming Classes
 // These can also be accessed via Workbook.createStreamWriter/createStreamReader

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

@@ -2,7 +2,7 @@ import type { Column } from "./column.js";
 import type { ValueType, FormulaType } from "./enums.js";
 import { Note } from "./note.js";
 import type { Row } from "./row.js";
-import type { Style, NumFmt, Font, Alignment, Protection, Borders, Fill, CellRichTextValue, CellErrorValue, DataValidation, CellValue, CellHyperlinkValue } from "./types.js";
+import type { Style, NumFmt, Font, Alignment, Protection, Borders, Fill, CellRichTextValue, CellErrorValue, DataValidation, CellValue, CellValueInput, CellHyperlinkValue, RichText } from "./types.js";
 import type { Workbook } from "./workbook.js";
 import type { Worksheet } from "./worksheet.js";
 export type FormulaResult = string | number | boolean | Date | CellErrorValue;
@@ -13,6 +13,7 @@ export interface FormulaValueData {
     sharedFormula?: string;
     result?: FormulaResult;
     date1904?: boolean;
+    isDynamicArray?: boolean;
 }
 interface FullAddress {
     sheetName: string;
@@ -62,12 +63,24 @@ export interface CellModel {
     formula?: string;
     sharedFormula?: string;
     result?: FormulaResult;
-    richText?: CellRichTextValue;
+    /**
+     * Rich-text runs associated with this cell.
+     *
+     * - When `type === RichText`, this holds a CellRichTextValue (object wrapping
+     *   the runs array) — this is the historical, cell-level rich-text payload.
+     * - When `type === Hyperlink`, this holds a plain RichText[] — the runs used
+     *   for formatted display of the hyperlink text.
+     *
+     * Callers should branch on `type` before accessing the shape.
+     */
+    richText?: CellRichTextValue | RichText[];
     sharedString?: number;
     error?: CellErrorValue;
     rawValue?: unknown;
+    isDynamicArray?: boolean;
 }
 export type CellValueType = CellValue;
+export type CellValueInputType = CellValueInput;
 declare class Cell {
     static Types: typeof ValueType;
     private _row;
@@ -111,7 +124,7 @@ declare class Cell {
     get isHyperlink(): boolean;
     get hyperlink(): string | undefined;
     get value(): CellValueType;
-    set value(v: CellValueType);
+    set value(v: CellValueInputType);
     get note(): string | NoteConfig | undefined;
     set note(note: string | NoteConfig);
     get comment(): Note | undefined;
@@ -121,6 +134,7 @@ declare class Cell {
     toString(): string;
     get formula(): string | undefined;
     get result(): FormulaResult | undefined;
+    set result(value: FormulaResult | undefined);
     get formulaType(): FormulaType;
     get fullAddress(): FullAddress;
     get name(): string;

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

@@ -10,6 +10,51 @@ import { escapeHtml } from "./utils/under-dash.js";
 // empty string, and empty objects `{}`. This is used to prevent an empty `{}`
 // style property on a row from shadowing a real style property on a column.
 const hasOwnKeys = (v) => !!v && (typeof v !== "object" || Object.keys(v).length > 0);
+/**
+ * Flatten a rich-text array into its plain-text representation by
+ * concatenating each run's `text`. Missing/null runs contribute "".
+ */
+function flattenRichText(runs) {
+    let out = "";
+    for (const run of runs) {
+        if (run && typeof run.text === "string") {
+            out += run.text;
+        }
+    }
+    return out;
+}
+/**
+ * Normalize a CellHyperlinkValue so the {@link NormalizedHyperlink} invariants
+ * hold.
+ *
+ * - If the caller supplied `richText` but no `text`, text is derived.
+ * - If the caller supplied `text` but no `richText`, richText stays absent.
+ * - If both are supplied, `richText` wins and `text` is regenerated
+ *   (to keep `text === flatten(richText)`).
+ * - An empty `richText: []` is dropped (treated as "no rich text").
+ */
+function normalizeHyperlinkValue(value) {
+    let text;
+    let richText;
+    if (Array.isArray(value.richText) && value.richText.length > 0) {
+        richText = value.richText;
+        text = flattenRichText(richText);
+    }
+    else {
+        text = typeof value.text === "string" ? value.text : "";
+    }
+    const out = {
+        text,
+        hyperlink: typeof value.hyperlink === "string" ? value.hyperlink : ""
+    };
+    if (richText) {
+        out.richText = richText;
+    }
+    if (typeof value.tooltip === "string" && value.tooltip.length > 0) {
+        out.tooltip = value.tooltip;
+    }
+    return out;
+}
 // Cell requirements
 //  Operate inside a worksheet
 //  Store and retrieve a value with a range of types: text, number, date, hyperlink, reference, formula, etc.
@@ -234,12 +279,30 @@ class Cell {
     }
     /** @internal */
     _upgradeToHyperlink(hyperlink) {
-        // if this cell is a string, turn it into a Hyperlink
-        if (this.type === Cell.Types.String) {
-            this._value = Value.create(Cell.Types.Hyperlink, this, {
-                text: String(this._value.value),
-                hyperlink
-            });
+        // Upgrade this cell to a Hyperlink while preserving the existing display
+        // text. Supports promotion from both plain String cells and RichText cells.
+        // For RichText cells, the runs are preserved on the new hyperlink value.
+        switch (this.type) {
+            case Cell.Types.String: {
+                this._value = Value.create(Cell.Types.Hyperlink, this, {
+                    text: String(this._value.value),
+                    hyperlink
+                });
+                break;
+            }
+            case Cell.Types.RichText: {
+                const current = this._value.value;
+                const runs = current && Array.isArray(current.richText) ? current.richText : [];
+                this._value = Value.create(Cell.Types.Hyperlink, this, {
+                    text: flattenRichText(runs),
+                    richText: runs.length > 0 ? runs : undefined,
+                    hyperlink
+                });
+                break;
+            }
+            default:
+                // Other cell types (Number, Date, Formula, ...) are not auto-upgraded.
+                break;
         }
     }
     // =========================================================================
@@ -250,6 +313,11 @@ class Cell {
     get result() {
         return this._value.result;
     }
+    set result(value) {
+        if (this.type === Cell.Types.Formula) {
+            this._value.result = value;
+        }
+    }
     get formulaType() {
         return this._value.formulaType ?? Enums.FormulaType.None;
     }
@@ -506,34 +574,95 @@ class HyperlinkValue {
     constructor(cell, value) {
         this.model = {
             address: cell.address,
-            type: Cell.Types.Hyperlink,
-            text: value ? value.text : undefined,
-            hyperlink: value ? value.hyperlink : undefined
+            type: Cell.Types.Hyperlink
         };
-        if (value && value.tooltip) {
-            this.model.tooltip = value.tooltip;
+        if (value) {
+            // Formula + hyperlink: surface as a Hyperlink whose display is the
+            // formula's evaluated result, but persist the formula on the model so
+            // it round-trips on write. The cell value getter ignores the formula
+            // fields, keeping the public Hyperlink shape clean.
+            if ("formula" in value && typeof value.formula === "string") {
+                const fh = value;
+                const display = fh.result === undefined || fh.result === null ? "" : String(fh.result);
+                this.model.text = display;
+                this.model.hyperlink = fh.hyperlink ?? "";
+                if (fh.tooltip !== undefined) {
+                    this.model.tooltip = fh.tooltip;
+                }
+                // Internal-only fields preserved for write-time re-emission.
+                this.model.formula =
+                    fh.formula;
+                if (fh.result !== undefined) {
+                    this.model.result = fh.result;
+                }
+                return;
+            }
+            const normalized = normalizeHyperlinkValue(value);
+            this.model.text = normalized.text;
+            this.model.hyperlink = normalized.hyperlink;
+            if (normalized.richText) {
+                this.model.richText = normalized.richText;
+            }
+            if (normalized.tooltip !== undefined) {
+                this.model.tooltip = normalized.tooltip;
+            }
         }
     }
     get value() {
-        return {
+        const out = {
             text: this.model.text ?? "",
-            hyperlink: this.model.hyperlink ?? "",
-            tooltip: this.model.tooltip
+            hyperlink: this.model.hyperlink ?? ""
         };
+        if (this.model.richText && this.model.richText.length > 0) {
+            out.richText = this.model.richText;
+        }
+        if (this.model.tooltip !== undefined) {
+            out.tooltip = this.model.tooltip;
+        }
+        return out;
     }
     set value(value) {
-        this.model.text = value.text;
-        this.model.hyperlink = value.hyperlink;
-        if (value.tooltip) {
-            this.model.tooltip = value.tooltip;
+        const normalized = normalizeHyperlinkValue(value);
+        this.model.text = normalized.text;
+        this.model.hyperlink = normalized.hyperlink;
+        if (normalized.richText) {
+            this.model.richText = normalized.richText;
+        }
+        else {
+            delete this.model.richText;
+        }
+        if (normalized.tooltip !== undefined) {
+            this.model.tooltip = normalized.tooltip;
+        }
+        else {
+            delete this.model.tooltip;
         }
     }
     get text() {
         return this.model.text;
     }
     set text(value) {
+        // Setting text while richText is present would break the invariant
+        // (text must equal flattenRichText(richText)). Dropping richText is the
+        // only safe resolution.
+        if (this.model.richText) {
+            delete this.model.richText;
+        }
         this.model.text = value;
     }
+    get richText() {
+        return this.model.richText;
+    }
+    set richText(value) {
+        if (Array.isArray(value) && value.length > 0) {
+            this.model.richText = value;
+            this.model.text = flattenRichText(value);
+        }
+        else {
+            delete this.model.richText;
+            // leave model.text untouched — caller may still want the plain text
+        }
+    }
     get hyperlink() {
         return this.model.hyperlink;
     }
@@ -625,7 +754,8 @@ class FormulaValue {
             ref: value ? value.ref : undefined,
             formula: value ? value.formula : undefined,
             sharedFormula: value ? value.sharedFormula : undefined,
-            result: value ? value.result : undefined
+            result: value ? value.result : undefined,
+            isDynamicArray: value ? value.isDynamicArray : undefined
         };
     }
     _copyModel(model) {
@@ -645,6 +775,9 @@ class FormulaValue {
         if (model.sharedFormula) {
             copy.sharedFormula = model.sharedFormula;
         }
+        if (model.isDynamicArray) {
+            copy.isDynamicArray = model.isDynamicArray;
+        }
         return copy;
     }
     get value() {
@@ -666,6 +799,9 @@ class FormulaValue {
         if (value.sharedFormula) {
             this.model.sharedFormula = value.sharedFormula;
         }
+        if (value.isDynamicArray !== undefined) {
+            this.model.isDynamicArray = value.isDynamicArray;
+        }
     }
     validate(value) {
         switch (Value.getType(value)) {
@@ -953,14 +1089,26 @@ const Value = {
             if ("checkbox" in value && typeof value.checkbox === "boolean") {
                 return Cell.Types.Checkbox;
             }
-            if ("text" in value && value.text && "hyperlink" in value && value.hyperlink) {
-                return Cell.Types.Hyperlink;
+            // Hyperlink detection: requires `hyperlink` and either non-empty `text`
+            // or a non-empty `richText` array, OR a formula (formula+hyperlink is
+            // surfaced as a Hyperlink with the formula's result as display).
+            // Checked before RichText/Formula so combined payloads route correctly.
+            if ("hyperlink" in value && typeof value.hyperlink === "string" && value.hyperlink) {
+                const hasText = "text" in value && typeof value.text === "string" && value.text.length > 0;
+                const hasRichText = "richText" in value && Array.isArray(value.richText) && value.richText.length > 0;
+                const hasFormula = "formula" in value && typeof value.formula === "string";
+                if (hasText || hasRichText || hasFormula) {
+                    return Cell.Types.Hyperlink;
+                }
             }
             if (("formula" in value && value.formula) ||
                 ("sharedFormula" in value && value.sharedFormula)) {
                 return Cell.Types.Formula;
             }
-            if ("richText" in value && value.richText) {
+            // RichText only when the runs array is non-empty. An empty `richText: []`
+            // carries no content and falls through to JSON rather than producing a
+            // RichText cell with no runs.
+            if ("richText" in value && Array.isArray(value.richText) && value.richText.length > 0) {
                 return Cell.Types.RichText;
             }
             if ("sharedString" in value && value.sharedString) {

package/dist/browser/modules/excel/defined-names.d.ts

@@ -2,6 +2,7 @@ import { Range } from "./range.js";
 import type { Address } from "./types.js";
 import { CellMatrix } from "./utils/cell-matrix.js";
 import { type DecodedRange } from "./utils/col-cache.js";
+import { type SyntaxProbe } from "../formula/default-syntax-probe.js";
 interface DefinedNameCell {
     sheetName?: string;
     address: string;
@@ -13,25 +14,119 @@ type CellLocation = Address | DecodedRange;
 interface DefinedNameModel {
     name: string;
     ranges: string[];
+    localSheetId?: number;
+    /** Formula expression for formula-based defined names (e.g. "LAMBDA(x,y,x+y)") */
+    formulaExpression?: string;
+    /** Original XML text — preserved for opaque names round-trip */
+    rawText?: string;
+    /**
+     * Classification determined by the semantic layer:
+     * - "reference": pure cell/range union — stored in matrixMap
+     * - "formula": parseable expression — stored in formulaMap
+     * - "opaque": unrecognised content preserved for round-trip — stored in opaqueMap
+     */
+    kind?: "reference" | "formula" | "opaque";
+}
+/** Stored entry for an opaque (unrecognised) defined name. */
+interface OpaqueEntry {
+    rawText: string;
+    localSheetId?: number;
 }
 declare class DefinedNames {
     matrixMap: Record<string, CellMatrix>;
-    constructor();
+    /**
+     * Formula-based defined names: storageKey → formula expression string.
+     */
+    formulaMap: Record<string, string>;
+    /**
+     * Tracks the localSheetId for each storage key.
+     * If a key is not in this map, the name is workbook-scoped (global).
+     */
+    localSheetIdMap: Record<string, number>;
+    /**
+     * Opaque defined names: storageKey → original text + optional localSheetId.
+     */
+    opaqueMap: Record<string, OpaqueEntry>;
+    /**
+     * Reverse mapping: storageKey → original name (bare, without scope suffix).
+     * Needed because storageKey encodes the scope, but consumers need the bare name.
+     */
+    nameForKey: Record<string, string>;
+    /**
+     * Optional explicit formula-syntax probe. When set, this is used to
+     * classify non-range, non-wrapper defined-name text during `set model`.
+     * When unset, the classifier falls back to the process-wide default
+     * probe (set by `installFormulaEngine()`). When neither is available,
+     * classification is conservative — non-range text becomes opaque.
+     */
+    private readonly _explicitProbe;
+    /**
+     * @param probe Optional formula-syntax probe used when classifying
+     *   defined-name text. Injecting a probe here makes classification
+     *   deterministic for this instance regardless of process-global
+     *   `installFormulaEngine()` state. When omitted, the instance defers
+     *   to the default probe at classification time (see `set model`).
+     */
+    constructor(probe?: SyntaxProbe);
     getMatrix(name: string): CellMatrix;
     add(locStr: string, name: string): void;
     addEx(location: CellLocation, name: string): void;
+    /**
+     * Register a formula-based defined name.
+     *
+     * Unlike `add()` which binds a name to a cell/range reference, this binds
+     * a name to an arbitrary formula expression that will be evaluated at
+     * calculation time.
+     *
+     * @param name - The defined name (e.g. "MyArray")
+     * @param expression - The formula expression (e.g. "{1,2;3,4}", "LAMBDA(x,y,x+y)")
+     */
+    addFormula(name: string, expression: string): void;
     remove(locStr: string, name: string): void;
     removeEx(location: CellLocation, name: string): void;
     removeAllNames(location: CellLocation): void;
     forEach(callback: (name: string, cell: DefinedNameCell) => void): void;
     getNames(addressStr: string): string[];
     getNamesEx(address: Address): string[];
+    /**
+     * Return all defined name entries in this collection, including scope info.
+     * Each entry has the bare name and optional localSheetId.
+     * Same bare name may appear multiple times with different scopes.
+     */
+    getAllNames(): {
+        name: string;
+        localSheetId?: number;
+    }[];
+    /**
+     * Return all defined name entries with full details (name, ranges, scope).
+     *
+     * This is the primary enumeration API. Each entry is self-contained —
+     * no second lookup is needed. Same bare name may appear multiple times
+     * with different scopes.
+     */
+    getAllEntries(): DefinedNameModel[];
     _explore(matrix: CellMatrix, cell: DefinedNameCell): Range;
+    /**
+     * Get ranges for a specific scoped entry.
+     *
+     * Unlike `getRanges(name)` which uses the bare name (and may hit the
+     * wrong scope when the same name exists both globally and locally),
+     * this method uses the internal `storageKey` to look up the exact entry.
+     */
+    getRangesScoped(name: string, localSheetId?: number): DefinedNameModel;
     getRanges(name: string, matrix?: CellMatrix): DefinedNameModel;
     normaliseMatrix(matrix: CellMatrix, sheetName: string): void;
     spliceRows(sheetName: string, start: number, numDelete: number, numInsert: number): void;
     spliceColumns(sheetName: string, start: number, numDelete: number, numInsert: number): void;
     get model(): DefinedNameModel[];
+    /**
+     * Deserialise an array of `DefinedNameModel` entries (typically from XLSX parsing).
+     *
+     * Stage 2 of the two-phase design: each entry's `rawText` is classified
+     * into reference / formula / opaque by `classifyDefinedName()`.  Entries
+     * that arrive without `rawText` (programmatic API) fall back to inspecting
+     * the existing `ranges` and `formulaExpression` fields for compatibility.
+     */
     set model(value: DefinedNameModel[]);
 }
 export { DefinedNames, type DefinedNameModel };