@cj-tech-master/excelts 9.2.1 → 9.3.0

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

@@ -22,15 +22,28 @@ export interface IParseStream extends EmitterLike {
     pipe(dest: any): any;
     [Symbol.asyncIterator]?: () => AsyncIterator<Uint8Array | string>;
 }
-export interface IStreamBuf extends EmitterLike {
-    write(data: any): boolean | void | Promise<boolean>;
+/**
+ * Minimal write-side shape required to receive XLSX bytes. Anything that
+ * behaves like a Node `WritableStream` (a `write()` method plus `end()` and
+ * event emitter basics) satisfies this — including Node's `fs.WriteStream`,
+ * `PassThrough`, and our `@stream` Writable class.
+ */
+export interface IWritableStream extends EmitterLike {
+    write(data: string | Uint8Array): boolean | void | Promise<boolean>;
     end(): void;
-    read(): any;
-    toBuffer?(): any;
     pipe?(dest: any): any;
 }
+/**
+ * An in-memory buffered stream. Extends the write-side shape with `read()`
+ * and optional `toBuffer()` for callers that use the stream as a sink and
+ * then harvest the accumulated bytes (e.g. `writeBuffer()`'s internal buffer).
+ */
+export interface IStreamBuf extends IWritableStream {
+    read(): Uint8Array | null;
+    toBuffer?(): Uint8Array | null;
+}
 export interface IZipWriter extends EmitterLike {
-    append(data: any, options: {
+    append(data: string | Uint8Array, options: {
         name: string;
         base64?: boolean;
     }): void;
@@ -39,13 +52,46 @@ export interface IZipWriter extends EmitterLike {
         write(chunk: string): void;
         end(): void;
     };
-    pipe(stream: any): void;
+    pipe(stream: IWritableStream): void;
     finalize(): void;
     /** Wait for downstream backpressure to clear. Resolves immediately if no backpressure. */
     waitForDrain(): Promise<void>;
 }
+/**
+ * Options for reading (loading) an XLSX workbook.
+ *
+ * All officially supported options are declared below with proper types so
+ * callers get IDE completion and type-checking. Additional fields are
+ * permitted via the index signature for forward compatibility and for
+ * callers who subclass `XLSX` to pass through private flags.
+ */
 export interface XlsxReadOptions {
+    /**
+     * When the input to `load()` is a string, interpret it as a base64-encoded
+     * zip archive instead of a binary buffer. Defaults to `false`.
+     */
     base64?: boolean;
+    /**
+     * Maximum number of rows to parse from each worksheet. Rows beyond this
+     * limit are silently skipped. Useful for previewing very large sheets
+     * without loading everything into memory.
+     */
+    maxRows?: number;
+    /**
+     * Maximum number of columns to parse from each worksheet. Columns beyond
+     * this limit are silently skipped. Useful for previewing very wide sheets.
+     */
+    maxCols?: number;
+    /**
+     * List of worksheet XML node names to skip while parsing (e.g.
+     * `"dataValidations"`, `"conditionalFormatting"`). Use for workbooks that
+     * contain corrupted or unsupported elements you want to ignore.
+     */
+    ignoreNodes?: string[];
+    /**
+     * Forward-compatibility / subclass extension escape hatch. Unknown keys are
+     * passed through to internal loaders; unrecognised keys are ignored.
+     */
     [key: string]: unknown;
 }
 export interface ZipWriterOptions {
@@ -55,8 +101,33 @@ export interface ZipWriterOptions {
     /** Timestamp writing strategy for ZIP entry metadata (optional). */
     timestamps?: ZipTimestampMode;
 }
+/**
+ * Options for writing an XLSX workbook.
+ *
+ * All officially supported options are declared below with proper types so
+ * callers get IDE completion and type-checking. Additional fields are
+ * permitted via the index signature for forward compatibility and for
+ * callers who subclass `XLSX` to pass through private flags.
+ */
 export interface XlsxWriteOptions {
+    /** ZIP archive options (compression level, timestamps, ...). */
     zip?: ZipWriterOptions;
+    /**
+     * Use a shared-string table for cell text values. Defaults to `true`.
+     * Set to `false` to write string values inline (larger file, but streams
+     * better for very large sheets).
+     */
+    useSharedStrings?: boolean;
+    /**
+     * Emit style definitions (fonts, fills, borders, number formats, …).
+     * Defaults to `true`. Set to `false` to skip style blocks for maximum
+     * compatibility with minimal readers.
+     */
+    useStyles?: boolean;
+    /**
+     * Forward-compatibility / subclass extension escape hatch. Unknown keys are
+     * passed through to internal writers; unrecognised keys are ignored.
+     */
     [key: string]: unknown;
 }
 export type XlsxOptions = XlsxReadOptions & XlsxWriteOptions;
@@ -73,7 +144,7 @@ export interface MediaModel {
 }
 interface ZipEntryLike {
     name: string;
-    type: "Directory" | "File";
+    type: "Directory" | "File" | "Symlink";
     stream: IParseStream;
     drain: () => Promise<void>;
 }
@@ -102,6 +173,9 @@ declare class XLSX {
         PivotTable: string;
         FeaturePropertyBag: string;
         CtrlProp: string;
+        SheetMetadata: string;
+        ExternalLink: string;
+        ExternalLinkPath: string;
     };
     constructor(workbook: Workbook);
     /**
@@ -133,19 +207,28 @@ declare class XLSX {
     /**
      * Read workbook from a stream
      */
-    read(stream: IParseStream, options?: XlsxReadOptions): Promise<any>;
+    read(stream: IParseStream, options?: XlsxReadOptions): Promise<Workbook>;
     /**
      * Write workbook to a stream
      */
-    write(stream: any, options?: XlsxWriteOptions): Promise<XLSX>;
+    write(stream: IWritableStream, options?: XlsxWriteOptions): Promise<XLSX>;
     /**
-     * Load workbook from buffer/ArrayBuffer/Uint8Array
+     * Load a workbook from binary data.
+     *
+     * Accepted inputs:
+     *  - `Uint8Array` (and `Buffer`, which is a Uint8Array at runtime)
+     *  - `ArrayBuffer` / `SharedArrayBuffer`
+     *  - Any `ArrayBufferView` (DataView, Int8Array, Float32Array, …) — the
+     *    underlying bytes are reinterpreted as a zip archive
+     *  - `string` — treated as base64-encoded data when `options.base64 === true`;
+     *    raw binary cannot be round-tripped through a JS string and is rejected
+     *    to prevent silent corruption.
      */
-    load(data: any, options?: XlsxReadOptions): Promise<any>;
+    load(data: Uint8Array | ArrayBuffer | ArrayBufferView | string, options?: XlsxReadOptions): Promise<Workbook>;
     /**
      * Internal: Load from Uint8Array buffer
      */
-    protected loadBuffer(buffer: Uint8Array, options?: XlsxReadOptions): Promise<any>;
+    protected loadBuffer(buffer: Uint8Array, options?: XlsxReadOptions): Promise<Workbook>;
     /**
      * Internal: Load workbook from an async stream of ZIP entries.
      *
@@ -194,6 +277,53 @@ declare class XLSX {
     parseWorkbook(stream: IParseStream): Promise<any>;
     parseSharedStrings(stream: IParseStream): Promise<any>;
     reconcile(model: any, options?: XlsxOptions): void;
+    /**
+     * Join the three on-disk sources that together describe external workbook
+     * references into a single dense `model.externalLinks: ExternalLinkModel[]`.
+     *
+     * Sources:
+     *   - `<externalReferences>` list in workbook.xml (declaration order)
+     *   - `xl/_rels/workbook.xml.rels` (rId → internal path)
+     *   - `xl/externalLinks/externalLink{N}.xml` (sheet names, cached values)
+     *   - `xl/externalLinks/_rels/externalLink{N}.xml.rels` (target, TargetMode)
+     *
+     * The 1-based index of each resulting ExternalLinkModel matches the `[N]`
+     * used in formula strings — this is the single source of truth formula
+     * code should rely on.
+     */
+    protected _reconcileExternalLinks(model: any): void;
+    /**
+     * Write-time pass that brings the workbook model into a shape the writer
+     * can serialise cleanly. Two concerns:
+     *
+     *   1. Build the final external-link list for this write, combining
+     *      user-declared links (`wb.externalLinks`) with auto-discovered
+     *      ones from previous writes (cached on the Workbook). The result
+     *      is assigned to `model.externalLinks` and consumed by the writer;
+     *      `wb.externalLinks` is **not** modified.
+     *
+     *   2. Scan every formula cell for `[Book]Sheet!` prefixes. Filename-form
+     *      references that don't match an existing link trigger
+     *      `_recordAutoExternalLink()` on the Workbook, which adds the target
+     *      to the private writer cache (so subsequent writes are fixed-point
+     *      stable) but leaves `wb.externalLinks` untouched.
+     *
+     *   3. Rewrite every external-ref formula so it uses the numeric `[N]`
+     *      form, the canonical OOXML storage form. This mutation lands on
+     *      the cell's model object — matching the library's existing
+     *      write-time pattern for `ssId`, `styleId`, `si`, and `cm`.
+     *      Subsequent writes see the `[N]` form directly and resolve it
+     *      against `model.externalLinks`, giving idempotent output.
+     */
+    protected _normaliseExternalLinks(model: any): void;
+    /**
+     * Rewrite a single formula so every external-ref prefix uses the numeric
+     * `[N]` form. When an unknown filename-form reference is found we record
+     * it on the workbook's private writer cache (so the next write can still
+     * resolve it) and append a local link to `scratch.links` so subsequent
+     * refs in the same formula see the freshly-assigned index.
+     */
+    private _normaliseFormulaExternalRefs;
     /**
      * Reconcile pivot tables by linking them to worksheets and their cache data.
      */
@@ -229,7 +359,21 @@ declare class XLSX {
     _processPivotTableRelsEntry(stream: IParseStream, model: any, name: string): Promise<void>;
     _processPivotCacheDefinitionEntry(stream: IParseStream, model: any, name: string): Promise<void>;
     _processPivotCacheRecordsEntry(stream: IParseStream, model: any, name: string): Promise<void>;
-    loadFromFiles(zipData: Record<string, Uint8Array>, options?: any): Promise<any>;
+    /**
+     * Parse `xl/externalLinks/externalLink{N}.xml` into the intermediate
+     * ParsedExternalLink shape. Reconciliation (joining with the rels file
+     * and the workbook's `<externalReferences>` list) happens later in
+     * {@link reconcile}.
+     */
+    _processExternalLinkEntry(stream: IParseStream, model: any, index: number): Promise<void>;
+    /**
+     * Parse `xl/externalLinks/_rels/externalLink{N}.xml.rels`. The Target /
+     * TargetMode carried here is what Excel uses to locate the actual external
+     * file at open time, so we must preserve it verbatim (including relative
+     * paths like `"测试.xlsx"`).
+     */
+    _processExternalLinkRelsEntry(stream: IParseStream, model: any, index: number): Promise<void>;
+    loadFromFiles(zipData: Record<string, Uint8Array>, options?: XlsxReadOptions): Promise<Workbook>;
     /**
      * Process default entries (drawings, comments, tables, etc.)
      * @param rawData Optional raw entry data for passthrough preservation (used by loadFromFiles)
@@ -253,12 +397,27 @@ declare class XLSX {
     addOfficeRels(zip: IZipWriter, _model: any): Promise<void>;
     addWorkbookRels(zip: IZipWriter, model: any): Promise<void>;
     addFeaturePropertyBag(zip: IZipWriter, model: any): Promise<void>;
+    addMetadata(zip: IZipWriter, model: any): Promise<void>;
     addSharedStrings(zip: IZipWriter, model: any): Promise<void>;
     addStyles(zip: IZipWriter, model: any): Promise<void>;
     addWorkbook(zip: IZipWriter, model: any): Promise<void>;
     addWorksheets(zip: IZipWriter, model: any): Promise<void>;
     addDrawings(zip: IZipWriter, model: any): Promise<void>;
     addTables(zip: IZipWriter, model: any): Promise<void>;
+    /**
+     * Write every external workbook reference into the archive. For each
+     * {@link ExternalLinkModel} in `model.externalLinks` we emit two files:
+     *
+     *   xl/externalLinks/externalLink{index}.xml          — sheet names + cache
+     *   xl/externalLinks/_rels/externalLink{index}.xml.rels — target path
+     *
+     * The target-path rel carries `TargetMode="External"` with a **bare
+     * relative** `Target` whenever the user supplied one. This is the single
+     * line that makes Office / WPS resolve the referenced workbook relative
+     * to the current file's directory (not the `%USERPROFILE%\Documents`
+     * fallback) — the root of the behaviour reported in exceljs#3039.
+     */
+    addExternalLinks(zip: IZipWriter, model: any): Promise<void>;
     /**
      * Write passthrough files (charts, etc.) that were preserved during read.
      * These files are written back unchanged to preserve unsupported features.

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

@@ -13,12 +13,15 @@
  * - writeBuffer: Write to buffer (Uint8Array)
  * - addMedia: Supports buffer, base64, and filename (via readFileAsync)
  */
+import type { Workbook } from "../workbook.js";
+import type { XlsxReadOptions, XlsxWriteOptions } from "./xlsx.browser.js";
 import { XLSX as XLSXBase } from "./xlsx.browser.js";
+import type { ReadableLike } from "../../stream/types.js";
 declare class XLSX extends XLSXBase {
-    constructor(workbook: any);
+    constructor(workbook: Workbook);
     private static iterateZipEntries;
-    read(stream: any, options?: any): Promise<any>;
-    readFile(filename: string, options?: any): Promise<any>;
-    writeFile(filename: string, options?: any): Promise<void>;
+    read(stream: ReadableLike, options?: XlsxReadOptions): Promise<Workbook>;
+    readFile(filename: string, options?: XlsxReadOptions): Promise<Workbook>;
+    writeFile(filename: string, options?: XlsxWriteOptions): Promise<void>;
 }
 export { XLSX };

package/dist/types/modules/formula/compile/address-utils.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Formula Address Utilities — Shared helpers for address parsing and conversion.
+ *
+ * These pure functions are used across the compile, runtime, and materialize
+ * layers. Centralizing them here eliminates duplication and ensures consistent
+ * behavior.
+ *
+ * ## Design Constraint
+ *
+ * This module must NOT import from `@excel/utils/col-cache` or any live
+ * workbook type. All functions are self-contained.
+ */
+/**
+ * Convert a column letter string (e.g. "A", "AA", "XFD") to a 1-based number.
+ *
+ * - `"A"` → 1
+ * - `"Z"` → 26
+ * - `"AA"` → 27
+ * - `"XFD"` → 16384
+ */
+export declare function colLetterToNumber(col: string): number;
+/**
+ * A parsed defined-name range reference.
+ */
+export interface ParsedNameRange {
+    readonly sheet: string;
+    readonly startRow: number;
+    readonly startCol: number;
+    readonly endRow: number;
+    readonly endCol: number;
+}
+/**
+ * Parse a defined-name range string like `"Sheet1!$A$1:$B$2"` or `"'Sheet Name'!$C$3"`
+ * into a `ParsedNameRange`. Returns `null` if the format is unrecognized.
+ */
+export declare function parseDefinedNameRange(rangeStr: string): ParsedNameRange | null;
+/**
+ * A parsed simple cell address (no sheet name).
+ */
+export interface ParsedAddress {
+    readonly row: number;
+    readonly col: number;
+}
+/**
+ * Parse a simple cell address like `"A1"`, `"$B$2"`, or `"AA100"`.
+ * Dollar signs are stripped. Returns `null` on parse failure.
+ */
+export declare function parseSimpleAddress(addr: string): ParsedAddress | null;
+/**
+ * A parsed rectangular range (no sheet name).
+ */
+export interface ParsedRefRange {
+    readonly top: number;
+    readonly left: number;
+    readonly bottom: number;
+    readonly right: number;
+}
+/**
+ * Parse a cell range string like `"A1:B2"` into a `ParsedRefRange`.
+ * Returns `null` if the format is unrecognized.
+ */
+export declare function parseRefRange(ref: string): ParsedRefRange | null;

package/dist/types/modules/formula/compile/binder.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Binder — Transform raw AST into BoundExpr.
+ *
+ * The binder performs static symbol resolution:
+ * - Cell/range references → BoundCellRef / BoundAreaRef with resolved sheet
+ * - Defined names → BoundCellRef / BoundAreaRef (if resolvable) or BoundNameExpr
+ * - Structured references → BoundCellRef / BoundAreaRef
+ * - Function calls → BoundCall or BoundSpecialCall
+ * - 3D references → BoundRef3D
+ *
+ * The binder operates on snapshot data only — no live workbook objects.
+ */
+import type { WorkbookSnapshot } from "../integration/workbook-snapshot.js";
+import type { AstNode } from "../syntax/ast.js";
+import type { BoundExpr } from "./bound-ast.js";
+/**
+ * Static context for the binder. Contains all information needed to
+ * resolve symbols at compile time.
+ */
+export interface BindingContext {
+    /** The workbook snapshot. */
+    readonly snapshot: WorkbookSnapshot;
+    /** The current sheet name (for relative references). */
+    readonly currentSheet: string;
+    /**
+     * Identifier names that are bound locally (uppercase). Populated by
+     * LAMBDA when descending into its body; prevents local parameter names
+     * from being shadowed by same-named workbook-level defined names at
+     * compile time. LET uses a different mechanism (it keeps the body
+     * bound as-is and resolves names at runtime via `localBindings`), but
+     * LAMBDA's body is pre-bound when the lambda is constructed so we have
+     * to inject scope info up front.
+     */
+    readonly localNames?: ReadonlySet<string>;
+}
+/**
+ * Bind a raw AST node to produce a BoundExpr.
+ *
+ * This is the main entry point for the compilation phase. It recursively
+ * walks the AST and resolves all symbols against the snapshot.
+ */
+export declare function bind(node: AstNode, ctx: BindingContext): BoundExpr;

package/dist/types/modules/formula/compile/bound-ast.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Bound Expression AST — The output of the compilation (binding) phase.
+ *
+ * After parsing produces a raw AST, the binder resolves all static symbols:
+ * - Defined names → resolved cell/range references or formula expressions
+ * - Structured references → resolved cell/range references
+ * - Sheet names → validated against the snapshot
+ * - Function names → validated against the registry
+ *
+ * The result is a `BoundExpr` tree where every reference is resolved and
+ * every function call is validated. The runtime evaluator only executes
+ * `BoundExpr` nodes — it never needs to perform symbol resolution.
+ *
+ * ## Node Types (compile output)
+ *
+ * After binding, only these node types exist:
+ *
+ * - `BoundLiteral` — number, string, boolean, error, null (missing)
+ * - `BoundCellRef` — resolved cell reference (sheet + row + col)
+ * - `BoundAreaRef` — resolved rectangular range (sheet + bounds)
+ * - `BoundColRangeRef` — resolved whole-column range
+ * - `BoundRowRangeRef` — resolved whole-row range
+ * - `BoundRef3D` — resolved 3D reference (multiple sheets)
+ * - `BoundBinaryOp` — binary operation
+ * - `BoundUnaryOp` — unary operation (including @)
+ * - `BoundPercent` — postfix %
+ * - `BoundCall` — function call (eagerly evaluated args)
+ * - `BoundSpecialCall` — special form (IF, LET, LAMBDA, etc.) with lazy args
+ * - `BoundArray` — array constant {1,2;3,4}
+ * - `BoundNameExpr` — UNRESOLVED name (only for names that must be resolved at runtime,
+ *   e.g. formula-based defined names that produce lambdas, or truly unknown names)
+ * - `BoundLambda` — LAMBDA expression (params + body)
+ */
+export declare const enum BoundExprKind {
+    Literal = 1,
+    CellRef = 2,
+    AreaRef = 3,
+    ColRangeRef = 4,
+    RowRangeRef = 5,
+    Ref3D = 6,
+    BinaryOp = 7,
+    UnaryOp = 8,
+    Percent = 9,
+    Call = 10,
+    SpecialCall = 11,
+    Array = 12,
+    NameExpr = 13,
+    Lambda = 14,
+    StructuredRef = 15
+}
+/**
+ * A resolved literal value.
+ */
+export interface BoundLiteral {
+    readonly kind: BoundExprKind.Literal;
+    /** number | string | boolean | null (for Missing/blank) */
+    readonly value: number | string | boolean | null;
+    /** If this is an error literal (e.g. #N/A), the error code. */
+    readonly errorCode?: string;
+}
+/**
+ * A fully resolved cell reference.
+ * After binding, sheet is always resolved (never undefined).
+ */
+export interface BoundCellRef {
+    readonly kind: BoundExprKind.CellRef;
+    /** Resolved sheet name. */
+    readonly sheet: string;
+    /** 1-based row number. */
+    readonly row: number;
+    /** 1-based column number. */
+    readonly col: number;
+}
+/**
+ * A fully resolved rectangular area reference.
+ */
+export interface BoundAreaRef {
+    readonly kind: BoundExprKind.AreaRef;
+    /** Resolved sheet name. */
+    readonly sheet: string;
+    /** 1-based bounds. */
+    readonly top: number;
+    readonly left: number;
+    readonly bottom: number;
+    readonly right: number;
+}
+/**
+ * A resolved whole-column range (e.g. A:B).
+ * Row bounds are determined at runtime from sheet dimensions.
+ */
+export interface BoundColRangeRef {
+    readonly kind: BoundExprKind.ColRangeRef;
+    readonly sheet: string;
+    readonly leftCol: number;
+    readonly rightCol: number;
+}
+/**
+ * A resolved whole-row range (e.g. 1:5).
+ * Column bounds are determined at runtime from sheet dimensions.
+ */
+export interface BoundRowRangeRef {
+    readonly kind: BoundExprKind.RowRangeRef;
+    readonly sheet: string;
+    readonly topRow: number;
+    readonly bottomRow: number;
+}
+/**
+ * A resolved 3D reference spanning multiple sheets.
+ * The inner reference is either a cell or an area.
+ */
+export interface BoundRef3D {
+    readonly kind: BoundExprKind.Ref3D;
+    /** Sheet names in workbook order, from start to end (inclusive). */
+    readonly sheets: readonly string[];
+    /** The cell/area that is replicated across sheets. */
+    readonly inner: BoundCellRef | BoundAreaRef;
+}
+/**
+ * Binary operation with two sub-expressions.
+ */
+export interface BoundBinaryOp {
+    readonly kind: BoundExprKind.BinaryOp;
+    readonly op: string;
+    readonly left: BoundExpr;
+    readonly right: BoundExpr;
+}
+/**
+ * Unary operation (prefix +, -, or @ implicit intersection).
+ */
+export interface BoundUnaryOp {
+    readonly kind: BoundExprKind.UnaryOp;
+    readonly op: string;
+    readonly operand: BoundExpr;
+}
+/**
+ * Postfix percent operation.
+ */
+export interface BoundPercent {
+    readonly kind: BoundExprKind.Percent;
+    readonly operand: BoundExpr;
+}
+/**
+ * A standard (eager) function call.
+ * All arguments are evaluated before the function is called.
+ */
+export interface BoundCall {
+    readonly kind: BoundExprKind.Call;
+    /** Uppercase, canonical function name. */
+    readonly name: string;
+    /** Bound argument expressions. */
+    readonly args: readonly BoundExpr[];
+}
+/**
+ * Special form identifiers for lazy/short-circuit evaluation.
+ */
+export type SpecialFormName = "IF" | "IFERROR" | "IFNA" | "IFS" | "SWITCH" | "CHOOSE" | "LET" | "LAMBDA" | "INDIRECT" | "OFFSET" | "MAP" | "REDUCE" | "SCAN" | "MAKEARRAY" | "BYROW" | "BYCOL";
+/**
+ * A special-form function call with lazy argument evaluation.
+ * The evaluator handles these with custom logic (short-circuit, binding, etc.).
+ */
+export interface BoundSpecialCall {
+    readonly kind: BoundExprKind.SpecialCall;
+    readonly name: SpecialFormName;
+    /** Argument expressions (evaluated lazily by the evaluator). */
+    readonly args: readonly BoundExpr[];
+}
+/**
+ * Array constant: {1,2;3,4}.
+ */
+export interface BoundArray {
+    readonly kind: BoundExprKind.Array;
+    /** rows[i][j] = element expression. */
+    readonly rows: readonly (readonly BoundExpr[])[];
+}
+/**
+ * An unresolved name reference.
+ *
+ * This exists for names that cannot be fully resolved at compile time:
+ * - Formula-based defined names (e.g. =LAMBDA(x,y,x+y))
+ * - Names that resolve to lambdas stored in cells
+ * - LET-bound local variables (resolved at runtime from localBindings)
+ * - Truly unknown names (#NAME? at runtime)
+ *
+ * For names that resolve to simple cell/range references, the binder
+ * produces `BoundCellRef` or `BoundAreaRef` directly.
+ */
+export interface BoundNameExpr {
+    readonly kind: BoundExprKind.NameExpr;
+    /** The original name (case-preserved). */
+    readonly name: string;
+    /** Uppercase name for lookup. */
+    readonly upperName: string;
+}
+/**
+ * A LAMBDA expression with parameter names and a body.
+ * Produced by the binder when it encounters a LAMBDA special form.
+ */
+export interface BoundLambda {
+    readonly kind: BoundExprKind.Lambda;
+    /** Parameter names (uppercase). */
+    readonly params: readonly string[];
+    /** The body expression. */
+    readonly body: BoundExpr;
+}
+/**
+ * An unresolved structured reference that requires runtime context.
+ *
+ * This is produced by the binder when:
+ * - The table name is empty (implicit `@` syntax — needs current cell position)
+ * - The reference includes `#This Row` (needs current cell's row)
+ *
+ * The evaluator resolves these at runtime using the current cell address.
+ */
+export interface BoundStructuredRef {
+    readonly kind: BoundExprKind.StructuredRef;
+    /** Table name (empty string for implicit table). */
+    readonly tableName: string;
+    /** Column names. */
+    readonly columns: readonly string[];
+    /** Special items (#Headers, #Data, #Totals, #All, #This Row). */
+    readonly specials: readonly string[];
+}
+export type BoundExpr = BoundLiteral | BoundCellRef | BoundAreaRef | BoundColRangeRef | BoundRowRangeRef | BoundRef3D | BoundBinaryOp | BoundUnaryOp | BoundPercent | BoundCall | BoundSpecialCall | BoundArray | BoundNameExpr | BoundLambda | BoundStructuredRef;
+export declare function boundLiteral(value: number | string | boolean | null, errorCode?: string): BoundLiteral;
+export declare function boundCellRef(sheet: string, row: number, col: number): BoundCellRef;
+export declare function boundAreaRef(sheet: string, top: number, left: number, bottom: number, right: number): BoundAreaRef;
+export declare function boundCall(name: string, args: BoundExpr[]): BoundCall;
+export declare function boundSpecialCall(name: SpecialFormName, args: BoundExpr[]): BoundSpecialCall;
+export declare function boundNameExpr(name: string): BoundNameExpr;
+export declare function boundErrorLiteral(errorCode: string): BoundLiteral;