@devmm/puredocs-excel-formula 1.0.0 → 1.0.1

package/dist/index.d.cts

@@ -10,7 +10,32 @@ declare const enum FormulaError {
     Calc = 8,
     Spill = 9
 }
-type FormulaValueKind = 'blank' | 'number' | 'text' | 'boolean' | 'error' | 'array';
+type FormulaValueKind = 'blank' | 'number' | 'text' | 'boolean' | 'error' | 'array' | 'lambda';
+/**
+ * A callable value produced by LAMBDA. Kept as an opaque interface so
+ * formula-value.ts stays decoupled from the AST/context modules.
+ */
+interface LambdaLike {
+    /** Number of declared parameters. */
+    readonly arity: number;
+    /** Invokes the lambda with the given argument values (runs to completion). */
+    call(args: FormulaValue[]): FormulaValue;
+    /**
+     * Runs the lambda body ONCE in tail-aware mode. Returns either the final value
+     * or a TailCall describing the next tail call, so a trampoline can iterate
+     * without growing the JS stack. Optional; call() is the fallback.
+     */
+    step?(args: FormulaValue[]): FormulaValue | TailCall;
+}
+/**
+ * A pending tail call produced by evaluating a node in tail position. The
+ * trampoline in a lambda's call() loops on these instead of recursing.
+ */
+declare class TailCall {
+    readonly lambda: LambdaLike;
+    readonly args: FormulaValue[];
+    constructor(lambda: LambdaLike, args: FormulaValue[]);
+}
 declare class FormulaValue {
     #private;
     readonly kind: FormulaValueKind;
@@ -34,17 +59,20 @@ declare class FormulaValue {
     static boolean(v: boolean): FormulaValue;
     static error(e: FormulaError): FormulaValue;
     static array(a: ArrayValue): FormulaValue;
+    static lambda(fn: LambdaLike): FormulaValue;
     get isBlank(): boolean;
     get isNumber(): boolean;
     get isText(): boolean;
     get isBoolean(): boolean;
     get isError(): boolean;
     get isArray(): boolean;
+    get isLambda(): boolean;
     get isNumeric(): boolean;
     get numberValue(): number;
     get textValue(): string;
     get booleanValue(): boolean;
     get arrayVal(): ArrayValue;
+    get lambdaVal(): LambdaLike;
     coerceToNumber(): FormulaValue;
     tryAsDouble(): {
         ok: true;
@@ -121,10 +149,11 @@ declare const enum TokenType {
     GreaterThanOrEqual = 21,
     SheetReference = 22,
     NamedRange = 23,
-    Exclamation = 24,
-    AtSign = 25,
-    ErrorLiteral = 26,
-    EOF = 27
+    SpillReference = 24,
+    Exclamation = 25,
+    AtSign = 26,
+    ErrorLiteral = 27,
+    EOF = 28
 }
 interface Token {
     readonly type: TokenType;
@@ -220,10 +249,25 @@ declare namespace FormulaHelper {
 interface WorksheetLike {
     getCellValue(reference: string): unknown;
     name: string;
+    /** Optional: whether a 1-based row is hidden (used by SUBTOTAL/AGGREGATE). */
+    isRowHidden?(row: number): boolean;
+    /** Optional: formula text of a cell (used by SUBTOTAL to skip nested calls). */
+    getCellFormula?(reference: string): string | null;
+    /** Optional: spill range (e.g. "A1:A3") of a dynamic-array anchor, for A1#. */
+    getSpillRange?(reference: string): string | null;
 }
 interface WorkbookLike {
     worksheets: readonly WorksheetLike[];
     getWorksheet(name: string): WorksheetLike;
+    /**
+     * Optional resolver for defined names (named ranges). Returns the refers-to
+     * expression (without leading '='), following Excel scoping: a name scoped to
+     * `sheetName` wins over the workbook-global name. When this method is absent
+     * (or returns undefined), named-range references evaluate to #NAME?.
+     *
+     * @devmm/puredocs-excel's Workbook implements this.
+     */
+    getDefinedName?(name: string, sheetName?: string): string | undefined;
 }
 declare class FormulaContext {
     #private;
@@ -233,19 +277,46 @@ declare class FormulaContext {
     formulaCol: number;
     /** Optional workbook reference for cross-sheet references. */
     workbook?: WorkbookLike;
+    /**
+     * Optional named-range resolver, installed by the evaluator when the workbook
+     * exposes getDefinedName. Given a name, returns its evaluated value. Left
+     * undefined when no resolver is available, in which case named ranges are
+     * #NAME? (unchanged legacy behaviour).
+     */
+    nameResolver?: (name: string) => FormulaValue;
+    /**
+     * Shared recursion budget for LAMBDA calls, threaded across all contexts in a
+     * single evaluation. Guards non-tail recursion (which grows the JS stack);
+     * tail recursion is trampolined and does not count against it.
+     */
+    recursionGuard?: {
+        depth: number;
+        max: number;
+    };
+    /** Pushes a new binding frame (used by LET/LAMBDA). */
+    pushScope(bindings: Map<string, FormulaValue>): void;
+    /** Pops the innermost binding frame. */
+    popScope(): void;
     constructor(sheet: WorksheetLike, formulaRow?: number, formulaCol?: number, evaluating?: Set<string>, registry?: FunctionRegistry);
     get worksheet(): WorksheetLike;
     getCellValue(cellReference: string): FormulaValue;
     getRangeValues(startRef: string, endRef: string): FormulaValue;
     getSheetCellValue(sheetName: string, cellReference: string): FormulaValue;
     getSheetRangeValues(sheetName: string, startRef: string, endRef: string): FormulaValue;
-    resolveNamedRange(_name: string): FormulaValue;
+    resolveNamedRange(name: string): FormulaValue;
+    /**
+     * Resolves a spill-range reference (A1#) to the array spilling from the anchor
+     * cell. Requires the worksheet to expose getSpillRange; otherwise #REF!.
+     */
+    resolveSpillRange(anchorRef: string): FormulaValue;
     getRangeBounds(startRef: string, endRef: string): {
         startRow: number;
         startCol: number;
         endRow: number;
         endCol: number;
     };
+    /** True if a built-in function with this name is registered. */
+    hasFunction(name: string): boolean;
     evaluateFunction(name: string, args: FormulaNode[]): FormulaValue;
 }
 
@@ -256,6 +327,13 @@ declare class FormulaContext {
 
 declare abstract class FormulaNode {
     abstract evaluate(ctx: FormulaContext): FormulaValue;
+    /**
+     * Evaluates this node in tail position. Returns a TailCall when the node's
+     * value is a call to a lambda in tail position (so the caller's trampoline can
+     * iterate without growing the stack); otherwise the final value. The default
+     * is a plain evaluate — only control-flow and call nodes override it.
+     */
+    evaluateTail(ctx: FormulaContext): FormulaValue | TailCall;
 }
 declare class NumberNode extends FormulaNode {
     readonly value: number;
@@ -310,6 +388,12 @@ declare class NamedRangeNode extends FormulaNode {
     constructor(name: string);
     evaluate(ctx: FormulaContext): FormulaValue;
 }
+/** Spill-range reference (A1#): the array that spills from an anchor cell. */
+declare class SpillReferenceNode extends FormulaNode {
+    readonly anchorRef: string;
+    constructor(anchorRef: string);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
 declare const enum BinaryOperator {
     Add = 0,
     Subtract = 1,
@@ -354,6 +438,18 @@ declare class FunctionCallNode extends FormulaNode {
     readonly args: FormulaNode[];
     constructor(functionName: string, args: FormulaNode[]);
     evaluate(ctx: FormulaContext): FormulaValue;
+    evaluateTail(ctx: FormulaContext): FormulaValue | TailCall;
+}
+/**
+ * Calls the value produced by an expression (e.g. an inline LAMBDA:
+ * `LAMBDA(x,x+1)(5)`). The callee must evaluate to a lambda, else #VALUE!.
+ */
+declare class CallNode extends FormulaNode {
+    readonly callee: FormulaNode;
+    readonly args: FormulaNode[];
+    constructor(callee: FormulaNode, args: FormulaNode[]);
+    evaluate(ctx: FormulaContext): FormulaValue;
+    evaluateTail(ctx: FormulaContext): FormulaValue | TailCall;
 }
 
 /**
@@ -438,6 +534,129 @@ declare class LruCache<K, V> {
     resize(newCapacity: number): void;
 }
 
+/** A rectangular precedent region on a specific sheet (1-based, inclusive). */
+interface PrecedentRef {
+    /** Upper-cased sheet name. */
+    readonly sheet: string;
+    readonly startRow: number;
+    readonly startCol: number;
+    readonly endRow: number;
+    readonly endCol: number;
+}
+interface ExtractResult {
+    readonly refs: PrecedentRef[];
+    readonly volatile: boolean;
+}
+/** Resolves a defined name to its refers-to expression, for name expansion. */
+type NameResolver = (name: string, sheet: string) => string | undefined;
+/**
+ * Extracts the precedents and volatility of a formula AST.
+ *
+ * @param ast          The parsed formula.
+ * @param formulaSheet Upper-cased name of the sheet the formula lives on;
+ *                     unqualified references resolve against it.
+ * @param registry     Function registry used to test volatility.
+ * @param resolveName  Optional resolver so NamedRangeNode precedents expand to
+ *                     the references inside their refers-to expression.
+ */
+declare function extractReferences(ast: FormulaNode, formulaSheet: string, registry?: FunctionRegistry, resolveName?: NameResolver): ExtractResult;
+/** True if the 1-based cell (sheet,row,col) falls inside a precedent region. */
+declare function refContains(ref: PrecedentRef, sheet: string, row: number, col: number): boolean;
+
+interface CoreCellLike {
+    setComputedValue(value: unknown): unknown;
+    setFormula(formula: string): unknown;
+    setArrayRef(spillRef: string | null): unknown;
+    clear(): void;
+}
+interface CoreSheetLike {
+    getCellValue(ref: string): unknown;
+    getCell(ref: string): CoreCellLike;
+    getCellFormula?(ref: string): string | null;
+    getSpillRange?(ref: string): string | null;
+    isRowHidden?(row: number): boolean;
+}
+interface CoreWorkbookLike {
+    getWorksheet(name: string): CoreSheetLike;
+    getDefinedName(name: string, sheet?: string): string | undefined;
+}
+/**
+ * Adapts a @devmm/puredocs-excel Workbook to a RecalcModel so the engine can
+ * read cell values and write computed results back into the document (via
+ * Cell.setComputedValue, which preserves the formula). Named ranges defined on
+ * the workbook are resolved automatically.
+ */
+declare function createWorkbookRecalcModel(workbook: CoreWorkbookLike): RecalcModel;
+/** Minimal storage abstraction the engine reads inputs from and writes results to. */
+interface RecalcModel {
+    /** Current value of a cell (raw input value, or last computed value). */
+    getCellValue(sheet: string, ref: string): unknown;
+    /** Store a computed formula result. Must NOT clear the cell's formula. */
+    setCellValue(sheet: string, ref: string, value: unknown): void;
+    /**
+     * Optional: persist a formula string on a cell so it serialises with the
+     * document. When present, the engine calls it from setCellFormula so the
+     * model stays the source of truth for the formula text.
+     */
+    setCellFormula?(sheet: string, ref: string, formula: string): void;
+    /** Optional: clear a cell (value + formula) — used by clearCellFormula. */
+    clearCell?(sheet: string, ref: string): void;
+    /** Optional: mark/unmark a cell as a dynamic-array anchor with its spill range. */
+    setCellArrayRef?(sheet: string, ref: string, spillRef: string | null): void;
+    /** Optional: formula text of a cell (lets SUBTOTAL skip nested calls). */
+    getCellFormula?(sheet: string, ref: string): string | null;
+    /** Optional: spill range of a dynamic-array anchor (enables A1#). */
+    getSpillRange?(sheet: string, ref: string): string | null;
+    /** Optional: whether a 1-based row is hidden (SUBTOTAL/AGGREGATE). */
+    isRowHidden?(sheet: string, row: number): boolean;
+    /** Optional defined-name resolver (enables named ranges in formulas). */
+    getDefinedName?(name: string, sheet?: string): string | undefined;
+}
+/** One recomputed cell, in evaluation order. */
+interface RecalcResult {
+    readonly sheet: string;
+    readonly ref: string;
+    /** The written JS value (null/number/string/boolean). For a dynamic array,
+     *  this is the anchor's top-left value. */
+    readonly value: unknown;
+    /** True when the cell is part of a circular reference. */
+    readonly circular?: boolean;
+    /** For a dynamic-array anchor: the spilled block size (rows × cols). */
+    readonly spill?: {
+        rows: number;
+        cols: number;
+    };
+}
+declare class RecalcEngine {
+    #private;
+    constructor(model: RecalcModel, registry?: FunctionRegistry);
+    /**
+     * Registers (or replaces) a formula for a cell and recalculates that cell and
+     * everything downstream of it. Returns the recomputed cells in the order they
+     * were evaluated. The leading '=' of the formula is optional.
+     */
+    setCellFormula(sheet: string, ref: string, formula: string): RecalcResult[];
+    /**
+     * Removes a formula from a cell and recalculates its dependents (which may now
+     * read a plain input value instead). Returns the recomputed dependent cells.
+     */
+    clearCellFormula(sheet: string, ref: string): RecalcResult[];
+    /**
+     * Writes a raw input value to a cell and recalculates every formula that
+     * depends on it. Use this for non-formula edits so dependents stay current.
+     */
+    setCellValue(sheet: string, ref: string, value: unknown): RecalcResult[];
+    /**
+     * Signals that a cell changed by some external means (the model was already
+     * updated) and recalculates its dependents.
+     */
+    onCellChanged(sheet: string, ref: string): RecalcResult[];
+    /** Recalculates every registered formula in dependency order. */
+    recalcAll(): RecalcResult[];
+    /** The precedents recorded for a formula cell (mainly for tests/inspection). */
+    getPrecedents(sheet: string, ref: string): readonly PrecedentRef[];
+}
+
 declare function registerMath(r: FunctionRegistry): void;
 
 declare function registerText(r: FunctionRegistry): void;
@@ -452,4 +671,12 @@ declare function registerStatistical(r: FunctionRegistry): void;
 
 declare function registerInfo(r: FunctionRegistry): void;
 
-export { ArrayValue, BinaryOpNode, BinaryOperator, BlankNode, BooleanNode, CellReferenceNode, ErrorNode, FormulaContext, FormulaError, FormulaException, type FormulaFunction, FormulaHelper, FormulaLexer, FormulaNode, FormulaParser, FormulaValue, type FormulaValueKind, FunctionCallNode, type FunctionDef, FunctionRegistry, ImplicitIntersectionNode, LruCache, NamedRangeNode, NumberNode, RangeReferenceNode, SheetCellReferenceNode, SheetRangeReferenceNode, StringNode, type Token, TokenType, UnaryOpNode, UnaryOperator, type WorkbookLike, type WorksheetLike, clearAstCache, evaluateFormula, getAstCacheStats, parseFormula, registerDate, registerInfo, registerLogical, registerLookup, registerMath, registerStatistical, registerText, setAstCacheCapacity };
+declare function registerFinance(r: FunctionRegistry): void;
+
+declare function registerMeta(r: FunctionRegistry): void;
+
+declare function registerAggregate(r: FunctionRegistry): void;
+
+declare function registerArray(r: FunctionRegistry): void;
+
+export { ArrayValue, BinaryOpNode, BinaryOperator, BlankNode, BooleanNode, CallNode, CellReferenceNode, ErrorNode, type ExtractResult, FormulaContext, FormulaError, FormulaException, type FormulaFunction, FormulaHelper, FormulaLexer, FormulaNode, FormulaParser, FormulaValue, type FormulaValueKind, FunctionCallNode, type FunctionDef, FunctionRegistry, ImplicitIntersectionNode, type LambdaLike, LruCache, type NameResolver, NamedRangeNode, NumberNode, type PrecedentRef, RangeReferenceNode, RecalcEngine, type RecalcModel, type RecalcResult, SheetCellReferenceNode, SheetRangeReferenceNode, SpillReferenceNode, StringNode, type Token, TokenType, UnaryOpNode, UnaryOperator, type WorkbookLike, type WorksheetLike, clearAstCache, createWorkbookRecalcModel, evaluateFormula, extractReferences, getAstCacheStats, parseFormula, refContains, registerAggregate, registerArray, registerDate, registerFinance, registerInfo, registerLogical, registerLookup, registerMath, registerMeta, registerStatistical, registerText, setAstCacheCapacity };

package/dist/index.d.ts

@@ -10,7 +10,32 @@ declare const enum FormulaError {
     Calc = 8,
     Spill = 9
 }
-type FormulaValueKind = 'blank' | 'number' | 'text' | 'boolean' | 'error' | 'array';
+type FormulaValueKind = 'blank' | 'number' | 'text' | 'boolean' | 'error' | 'array' | 'lambda';
+/**
+ * A callable value produced by LAMBDA. Kept as an opaque interface so
+ * formula-value.ts stays decoupled from the AST/context modules.
+ */
+interface LambdaLike {
+    /** Number of declared parameters. */
+    readonly arity: number;
+    /** Invokes the lambda with the given argument values (runs to completion). */
+    call(args: FormulaValue[]): FormulaValue;
+    /**
+     * Runs the lambda body ONCE in tail-aware mode. Returns either the final value
+     * or a TailCall describing the next tail call, so a trampoline can iterate
+     * without growing the JS stack. Optional; call() is the fallback.
+     */
+    step?(args: FormulaValue[]): FormulaValue | TailCall;
+}
+/**
+ * A pending tail call produced by evaluating a node in tail position. The
+ * trampoline in a lambda's call() loops on these instead of recursing.
+ */
+declare class TailCall {
+    readonly lambda: LambdaLike;
+    readonly args: FormulaValue[];
+    constructor(lambda: LambdaLike, args: FormulaValue[]);
+}
 declare class FormulaValue {
     #private;
     readonly kind: FormulaValueKind;
@@ -34,17 +59,20 @@ declare class FormulaValue {
     static boolean(v: boolean): FormulaValue;
     static error(e: FormulaError): FormulaValue;
     static array(a: ArrayValue): FormulaValue;
+    static lambda(fn: LambdaLike): FormulaValue;
     get isBlank(): boolean;
     get isNumber(): boolean;
     get isText(): boolean;
     get isBoolean(): boolean;
     get isError(): boolean;
     get isArray(): boolean;
+    get isLambda(): boolean;
     get isNumeric(): boolean;
     get numberValue(): number;
     get textValue(): string;
     get booleanValue(): boolean;
     get arrayVal(): ArrayValue;
+    get lambdaVal(): LambdaLike;
     coerceToNumber(): FormulaValue;
     tryAsDouble(): {
         ok: true;
@@ -121,10 +149,11 @@ declare const enum TokenType {
     GreaterThanOrEqual = 21,
     SheetReference = 22,
     NamedRange = 23,
-    Exclamation = 24,
-    AtSign = 25,
-    ErrorLiteral = 26,
-    EOF = 27
+    SpillReference = 24,
+    Exclamation = 25,
+    AtSign = 26,
+    ErrorLiteral = 27,
+    EOF = 28
 }
 interface Token {
     readonly type: TokenType;
@@ -220,10 +249,25 @@ declare namespace FormulaHelper {
 interface WorksheetLike {
     getCellValue(reference: string): unknown;
     name: string;
+    /** Optional: whether a 1-based row is hidden (used by SUBTOTAL/AGGREGATE). */
+    isRowHidden?(row: number): boolean;
+    /** Optional: formula text of a cell (used by SUBTOTAL to skip nested calls). */
+    getCellFormula?(reference: string): string | null;
+    /** Optional: spill range (e.g. "A1:A3") of a dynamic-array anchor, for A1#. */
+    getSpillRange?(reference: string): string | null;
 }
 interface WorkbookLike {
     worksheets: readonly WorksheetLike[];
     getWorksheet(name: string): WorksheetLike;
+    /**
+     * Optional resolver for defined names (named ranges). Returns the refers-to
+     * expression (without leading '='), following Excel scoping: a name scoped to
+     * `sheetName` wins over the workbook-global name. When this method is absent
+     * (or returns undefined), named-range references evaluate to #NAME?.
+     *
+     * @devmm/puredocs-excel's Workbook implements this.
+     */
+    getDefinedName?(name: string, sheetName?: string): string | undefined;
 }
 declare class FormulaContext {
     #private;
@@ -233,19 +277,46 @@ declare class FormulaContext {
     formulaCol: number;
     /** Optional workbook reference for cross-sheet references. */
     workbook?: WorkbookLike;
+    /**
+     * Optional named-range resolver, installed by the evaluator when the workbook
+     * exposes getDefinedName. Given a name, returns its evaluated value. Left
+     * undefined when no resolver is available, in which case named ranges are
+     * #NAME? (unchanged legacy behaviour).
+     */
+    nameResolver?: (name: string) => FormulaValue;
+    /**
+     * Shared recursion budget for LAMBDA calls, threaded across all contexts in a
+     * single evaluation. Guards non-tail recursion (which grows the JS stack);
+     * tail recursion is trampolined and does not count against it.
+     */
+    recursionGuard?: {
+        depth: number;
+        max: number;
+    };
+    /** Pushes a new binding frame (used by LET/LAMBDA). */
+    pushScope(bindings: Map<string, FormulaValue>): void;
+    /** Pops the innermost binding frame. */
+    popScope(): void;
     constructor(sheet: WorksheetLike, formulaRow?: number, formulaCol?: number, evaluating?: Set<string>, registry?: FunctionRegistry);
     get worksheet(): WorksheetLike;
     getCellValue(cellReference: string): FormulaValue;
     getRangeValues(startRef: string, endRef: string): FormulaValue;
     getSheetCellValue(sheetName: string, cellReference: string): FormulaValue;
     getSheetRangeValues(sheetName: string, startRef: string, endRef: string): FormulaValue;
-    resolveNamedRange(_name: string): FormulaValue;
+    resolveNamedRange(name: string): FormulaValue;
+    /**
+     * Resolves a spill-range reference (A1#) to the array spilling from the anchor
+     * cell. Requires the worksheet to expose getSpillRange; otherwise #REF!.
+     */
+    resolveSpillRange(anchorRef: string): FormulaValue;
     getRangeBounds(startRef: string, endRef: string): {
         startRow: number;
         startCol: number;
         endRow: number;
         endCol: number;
     };
+    /** True if a built-in function with this name is registered. */
+    hasFunction(name: string): boolean;
     evaluateFunction(name: string, args: FormulaNode[]): FormulaValue;
 }
 
@@ -256,6 +327,13 @@ declare class FormulaContext {
 
 declare abstract class FormulaNode {
     abstract evaluate(ctx: FormulaContext): FormulaValue;
+    /**
+     * Evaluates this node in tail position. Returns a TailCall when the node's
+     * value is a call to a lambda in tail position (so the caller's trampoline can
+     * iterate without growing the stack); otherwise the final value. The default
+     * is a plain evaluate — only control-flow and call nodes override it.
+     */
+    evaluateTail(ctx: FormulaContext): FormulaValue | TailCall;
 }
 declare class NumberNode extends FormulaNode {
     readonly value: number;
@@ -310,6 +388,12 @@ declare class NamedRangeNode extends FormulaNode {
     constructor(name: string);
     evaluate(ctx: FormulaContext): FormulaValue;
 }
+/** Spill-range reference (A1#): the array that spills from an anchor cell. */
+declare class SpillReferenceNode extends FormulaNode {
+    readonly anchorRef: string;
+    constructor(anchorRef: string);
+    evaluate(ctx: FormulaContext): FormulaValue;
+}
 declare const enum BinaryOperator {
     Add = 0,
     Subtract = 1,
@@ -354,6 +438,18 @@ declare class FunctionCallNode extends FormulaNode {
     readonly args: FormulaNode[];
     constructor(functionName: string, args: FormulaNode[]);
     evaluate(ctx: FormulaContext): FormulaValue;
+    evaluateTail(ctx: FormulaContext): FormulaValue | TailCall;
+}
+/**
+ * Calls the value produced by an expression (e.g. an inline LAMBDA:
+ * `LAMBDA(x,x+1)(5)`). The callee must evaluate to a lambda, else #VALUE!.
+ */
+declare class CallNode extends FormulaNode {
+    readonly callee: FormulaNode;
+    readonly args: FormulaNode[];
+    constructor(callee: FormulaNode, args: FormulaNode[]);
+    evaluate(ctx: FormulaContext): FormulaValue;
+    evaluateTail(ctx: FormulaContext): FormulaValue | TailCall;
 }
 
 /**
@@ -438,6 +534,129 @@ declare class LruCache<K, V> {
     resize(newCapacity: number): void;
 }
 
+/** A rectangular precedent region on a specific sheet (1-based, inclusive). */
+interface PrecedentRef {
+    /** Upper-cased sheet name. */
+    readonly sheet: string;
+    readonly startRow: number;
+    readonly startCol: number;
+    readonly endRow: number;
+    readonly endCol: number;
+}
+interface ExtractResult {
+    readonly refs: PrecedentRef[];
+    readonly volatile: boolean;
+}
+/** Resolves a defined name to its refers-to expression, for name expansion. */
+type NameResolver = (name: string, sheet: string) => string | undefined;
+/**
+ * Extracts the precedents and volatility of a formula AST.
+ *
+ * @param ast          The parsed formula.
+ * @param formulaSheet Upper-cased name of the sheet the formula lives on;
+ *                     unqualified references resolve against it.
+ * @param registry     Function registry used to test volatility.
+ * @param resolveName  Optional resolver so NamedRangeNode precedents expand to
+ *                     the references inside their refers-to expression.
+ */
+declare function extractReferences(ast: FormulaNode, formulaSheet: string, registry?: FunctionRegistry, resolveName?: NameResolver): ExtractResult;
+/** True if the 1-based cell (sheet,row,col) falls inside a precedent region. */
+declare function refContains(ref: PrecedentRef, sheet: string, row: number, col: number): boolean;
+
+interface CoreCellLike {
+    setComputedValue(value: unknown): unknown;
+    setFormula(formula: string): unknown;
+    setArrayRef(spillRef: string | null): unknown;
+    clear(): void;
+}
+interface CoreSheetLike {
+    getCellValue(ref: string): unknown;
+    getCell(ref: string): CoreCellLike;
+    getCellFormula?(ref: string): string | null;
+    getSpillRange?(ref: string): string | null;
+    isRowHidden?(row: number): boolean;
+}
+interface CoreWorkbookLike {
+    getWorksheet(name: string): CoreSheetLike;
+    getDefinedName(name: string, sheet?: string): string | undefined;
+}
+/**
+ * Adapts a @devmm/puredocs-excel Workbook to a RecalcModel so the engine can
+ * read cell values and write computed results back into the document (via
+ * Cell.setComputedValue, which preserves the formula). Named ranges defined on
+ * the workbook are resolved automatically.
+ */
+declare function createWorkbookRecalcModel(workbook: CoreWorkbookLike): RecalcModel;
+/** Minimal storage abstraction the engine reads inputs from and writes results to. */
+interface RecalcModel {
+    /** Current value of a cell (raw input value, or last computed value). */
+    getCellValue(sheet: string, ref: string): unknown;
+    /** Store a computed formula result. Must NOT clear the cell's formula. */
+    setCellValue(sheet: string, ref: string, value: unknown): void;
+    /**
+     * Optional: persist a formula string on a cell so it serialises with the
+     * document. When present, the engine calls it from setCellFormula so the
+     * model stays the source of truth for the formula text.
+     */
+    setCellFormula?(sheet: string, ref: string, formula: string): void;
+    /** Optional: clear a cell (value + formula) — used by clearCellFormula. */
+    clearCell?(sheet: string, ref: string): void;
+    /** Optional: mark/unmark a cell as a dynamic-array anchor with its spill range. */
+    setCellArrayRef?(sheet: string, ref: string, spillRef: string | null): void;
+    /** Optional: formula text of a cell (lets SUBTOTAL skip nested calls). */
+    getCellFormula?(sheet: string, ref: string): string | null;
+    /** Optional: spill range of a dynamic-array anchor (enables A1#). */
+    getSpillRange?(sheet: string, ref: string): string | null;
+    /** Optional: whether a 1-based row is hidden (SUBTOTAL/AGGREGATE). */
+    isRowHidden?(sheet: string, row: number): boolean;
+    /** Optional defined-name resolver (enables named ranges in formulas). */
+    getDefinedName?(name: string, sheet?: string): string | undefined;
+}
+/** One recomputed cell, in evaluation order. */
+interface RecalcResult {
+    readonly sheet: string;
+    readonly ref: string;
+    /** The written JS value (null/number/string/boolean). For a dynamic array,
+     *  this is the anchor's top-left value. */
+    readonly value: unknown;
+    /** True when the cell is part of a circular reference. */
+    readonly circular?: boolean;
+    /** For a dynamic-array anchor: the spilled block size (rows × cols). */
+    readonly spill?: {
+        rows: number;
+        cols: number;
+    };
+}
+declare class RecalcEngine {
+    #private;
+    constructor(model: RecalcModel, registry?: FunctionRegistry);
+    /**
+     * Registers (or replaces) a formula for a cell and recalculates that cell and
+     * everything downstream of it. Returns the recomputed cells in the order they
+     * were evaluated. The leading '=' of the formula is optional.
+     */
+    setCellFormula(sheet: string, ref: string, formula: string): RecalcResult[];
+    /**
+     * Removes a formula from a cell and recalculates its dependents (which may now
+     * read a plain input value instead). Returns the recomputed dependent cells.
+     */
+    clearCellFormula(sheet: string, ref: string): RecalcResult[];
+    /**
+     * Writes a raw input value to a cell and recalculates every formula that
+     * depends on it. Use this for non-formula edits so dependents stay current.
+     */
+    setCellValue(sheet: string, ref: string, value: unknown): RecalcResult[];
+    /**
+     * Signals that a cell changed by some external means (the model was already
+     * updated) and recalculates its dependents.
+     */
+    onCellChanged(sheet: string, ref: string): RecalcResult[];
+    /** Recalculates every registered formula in dependency order. */
+    recalcAll(): RecalcResult[];
+    /** The precedents recorded for a formula cell (mainly for tests/inspection). */
+    getPrecedents(sheet: string, ref: string): readonly PrecedentRef[];
+}
+
 declare function registerMath(r: FunctionRegistry): void;
 
 declare function registerText(r: FunctionRegistry): void;
@@ -452,4 +671,12 @@ declare function registerStatistical(r: FunctionRegistry): void;
 
 declare function registerInfo(r: FunctionRegistry): void;
 
-export { ArrayValue, BinaryOpNode, BinaryOperator, BlankNode, BooleanNode, CellReferenceNode, ErrorNode, FormulaContext, FormulaError, FormulaException, type FormulaFunction, FormulaHelper, FormulaLexer, FormulaNode, FormulaParser, FormulaValue, type FormulaValueKind, FunctionCallNode, type FunctionDef, FunctionRegistry, ImplicitIntersectionNode, LruCache, NamedRangeNode, NumberNode, RangeReferenceNode, SheetCellReferenceNode, SheetRangeReferenceNode, StringNode, type Token, TokenType, UnaryOpNode, UnaryOperator, type WorkbookLike, type WorksheetLike, clearAstCache, evaluateFormula, getAstCacheStats, parseFormula, registerDate, registerInfo, registerLogical, registerLookup, registerMath, registerStatistical, registerText, setAstCacheCapacity };
+declare function registerFinance(r: FunctionRegistry): void;
+
+declare function registerMeta(r: FunctionRegistry): void;
+
+declare function registerAggregate(r: FunctionRegistry): void;
+
+declare function registerArray(r: FunctionRegistry): void;
+
+export { ArrayValue, BinaryOpNode, BinaryOperator, BlankNode, BooleanNode, CallNode, CellReferenceNode, ErrorNode, type ExtractResult, FormulaContext, FormulaError, FormulaException, type FormulaFunction, FormulaHelper, FormulaLexer, FormulaNode, FormulaParser, FormulaValue, type FormulaValueKind, FunctionCallNode, type FunctionDef, FunctionRegistry, ImplicitIntersectionNode, type LambdaLike, LruCache, type NameResolver, NamedRangeNode, NumberNode, type PrecedentRef, RangeReferenceNode, RecalcEngine, type RecalcModel, type RecalcResult, SheetCellReferenceNode, SheetRangeReferenceNode, SpillReferenceNode, StringNode, type Token, TokenType, UnaryOpNode, UnaryOperator, type WorkbookLike, type WorksheetLike, clearAstCache, createWorkbookRecalcModel, evaluateFormula, extractReferences, getAstCacheStats, parseFormula, refContains, registerAggregate, registerArray, registerDate, registerFinance, registerInfo, registerLogical, registerLookup, registerMath, registerMeta, registerStatistical, registerText, setAstCacheCapacity };