@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/calculation/ICalculation.d.ts

@@ -1,4 +1,4 @@
-import { FormulaError, IRange, Scalar, IRuntime } from '@sheetxl/primitives';
+import { IRange, Scalar, IRuntime } from '@sheetxl/primitives';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
 import { IModel } from '../model';
@@ -6,6 +6,7 @@ import { IFunctionCollection } from '../scripting';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { INamed } from '../named';
 import { INamedFormulasCollection } from './INamedFormulasCollection';
+import { IExternalBookCollection } from '../externalBook';
 /**
  * Calculation is the process of computing formulas and then displaying the results
  * as values in the cells that contain the formulas.
@@ -35,17 +36,51 @@ export interface ICalculation extends IModel {
      */
     stop: () => Promise<void>;
     /**
-     * Returns when all calculations are complete and there are no pending calculations.
+     * Resolves once the engine is running and idle: its calculation state is
+     * {@link ICalculation.CalculationState.Done}, or {@link ICalculation.CalculationState.Pending} in
+     * manual mode.
      *
      * @remarks
-     * * This is useful when needing to ensure that the values in the calculation cycle are up-to-date.
-     * * For streaming functions still will return the current value.
+     * * After it, every answer the engine owes has landed: a formula written before it reads as
+     *   compiled, and its value is current (in automatic mode).
+     * * Manual mode does not wait for a recalculation nobody has asked for; call {@link calculate}.
+     * * Waits for what consumers derive from the results too ({@link waitUntil}): a conditional
+     *   format reads as painted after it, including one a read just asked to evaluate.
+     * * A streaming or async function's result in flight is not waited for: its cell reads as the
+     *   current value until the result arrives.
+     * * Starts the engine if it is {@link ICalculation.Status.Off}. An engine in
+     *   {@link ICalculation.Status.Error} is not started; {@link start} tries again.
+     *
+     * @param options Pass `{ full: true }` to recalculate every grid rather than only the dirty ones.
+     */
+    ready(options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+    /**
+     * Counts `work` that a consumer derives from the engine's results as calculation in flight
+     * until it settles: {@link ready} waits for it, and {@link getCalculationState} reads
+     * `Calculating` meanwhile.
+     *
+     * @remarks
+     * For anything whose answer follows from a pass and lands after it - a conditional format
+     * re-judging its cells once the pass delivers its formula's values - so that a reader who
+     * waited for `ready()` reads the answer rather than the one before it. Not counted in manual
+     * mode, where the pass such work waits for runs only when asked.
+     *
+     * @param work The derived work. Its failure is the consumer's: it settles the wait either way.
+     * @returns `work`.
      */
-    ready(): Promise<ICalculation.Status>;
+    waitUntil<T>(work: Promise<T>): Promise<T>;
     /**
-     * Returns the current status of the calculation engine.
+     * Returns the current status of the calculation engine: whether it is running at all.
      */
     getStatus(): ICalculation.Status;
+    /**
+     * Whether the running engine has work in hand - Excel's `Application.CalculationState`.
+     *
+     * @remarks
+     * Meaningful while {@link ICalculation.Status.Running}; `Calculating` while starting, `Done`
+     * otherwise. See {@link ICalculation.CalculationState}.
+     */
+    getCalculationState(): ICalculation.CalculationState;
     /**
      * Returns the functions available for the calculation engine.
      */
@@ -54,19 +89,40 @@ export interface ICalculation extends IModel {
      * Returns the named formulas available in the calculation engine.
      */
     getNamedFormulas(): INamedFormulasCollection;
+    /**
+     * The workbook's external books — the `[n]` a formula cites — in position order.
+     *
+     * @remarks
+     * Owned by the engine, as defined names are: a book is a symbol formulas bind into, and which
+     * formulas cite a book is the engine's index. Also reachable as `IWorkbook.getExternalBooks()`.
+     */
+    getExternalBooks(): IExternalBookCollection;
     /** @inheritdoc IFormulaContext.getRuntime */
     getRuntime(): IRuntime;
     /**
      * Parses a formula expression and returns a *transient* formula object.
      *
+     * @param expression The formula expression, with or without a leading `=`.
+     * @param coords Optional anchor coordinates.
+     * @param options Optional parse options.
+     *
      * @remarks
      * - This does **not** register the formula in the workbook or dependency graph.
+     * - The expression is read as storage text (English function names, `,` separators) unless
+     *   `options.target` is `'display'` — text a user typed in their language and locale.
      * - Use it for:
      *   - interactive editing (tooltips, watches, function help)
      *   - condition / validation expressions
      *   - ad-hoc “what-if” evaluations
+     *
+     * @example
+     * ```typescript
+     * calculation.createFormula('SUM(A1,1.5)');
+     * // With a German language pack active:
+     * calculation.createFormula('SUMME(A1;1,5)', undefined, { target: 'display' });
+     * ```
      */
-    createFormula(expression: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula;
+    createFormula(expression: string, coords?: Partial<IRange.CellCoords>, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
     /**
      * Evaluates a expression in the context of the sheet and returns the resulting value.
      *
@@ -75,8 +131,9 @@ export interface ICalculation extends IModel {
      *
      * @remarks
      * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
+     * The expression is read as storage text unless `options.target` is `'display'`.
      */
-    evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords> & ICalculation.CreateFormulaOptions): Promise<Scalar | IRange>;
     /**
      * When the engine recalculates on its own — Excel's Calculation Options.
      *
@@ -141,6 +198,8 @@ export interface ICalculation extends IModel {
      * {@link IListener.ISource.addListeners}
      */
     addListeners(listeners: ICalculation.IListeners, options?: IListener.Options): IListener.Remove;
+    /** For runtime type checking. */
+    readonly isICalculation: true;
 }
 /**
  * {@inheritDoc ICalculation}
@@ -235,13 +294,27 @@ export declare namespace ICalculation {
          * `maxIterateChange` in the last sweep. Always `false` with iteration off.
          */
         isConverged(): boolean;
-        /** How many sweeps the last evaluation ran — up to the workbook's `maxIterations`. */
+        /** How many sweeps the last evaluation ran — up to the workbook's `maxIteration`. */
         getIterationCount(): number;
         /**
-         * The largest change any member made in the last sweep — what stopped the iteration when
-         * {@link isConverged}, what it never got under when not. `0` with iteration off.
+         * The largest change any member of THIS cycle made in the last sweep — what stopped the
+         * iteration when {@link isConverged}, what it never got under when not. `0` with iteration off.
+         *
+         * @remarks
+         * Convergence is decided across every cycle at once, as Excel decides it, so a cycle can stop
+         * on the cap because a different one would not settle. This number is still its own.
          */
         getLastChange(): number;
+        /**
+         * The same for the sweep before the last, or `NaN` when there was only one (and with iteration
+         * off).
+         *
+         * @remarks
+         * Read beside {@link getLastChange} it says whether a run that hit the cap was getting
+         * anywhere: a change that shrank between the two sweeps settles at a higher `maxIteration`,
+         * one that held or grew does not settle at any.
+         */
+        getPreviousChange(): number;
     }
     /**
      * Represents a formula that can be evaluated.
@@ -255,8 +328,27 @@ export declare namespace ICalculation {
         evaluate(options?: number | ICalculation.EvaluateOptions): Promise<Scalar | IRange>;
         /**
          * Returns the status.
+         *
+         * @remarks
+         * `Pending` for a formula the engine has not compiled yet (see {@link isCompiled}).
          */
         getCalculationStatus(): ICalculation.ResultStatus;
+        /**
+         * Whether the calculation engine has compiled this formula.
+         *
+         * @remarks
+         * A formula is model state: it is stored, and reads back, the moment it is set - in every
+         * engine state, a stopped or never-started one included. The COMPILED body arrives when the
+         * engine gets to it. Until then this is `false`; {@link getExpression} answers from the text as
+         * written, {@link getTokens} is empty, {@link getReferences} is `null`, a reference edit
+         * throws, and {@link evaluate} waits for a `Starting` engine and rejects on an `Off` one rather
+         * than starting it. The handle heals: it reads the engine's block the first time one exists, so
+         * one taken cold is fully functional once the engine has compiled the cell.
+         *
+         * A formula created detached ({@link ICalculation.createFormula}) or a defined name is
+         * compiled on creation and is always `true`.
+         */
+        isCompiled(): boolean;
         /**
          * Return the formula's expression — the text WITHOUT a leading `=`.
          *
@@ -267,11 +359,18 @@ export declare namespace ICalculation {
          * shape, which is what OOXML `<f>` and `<definedName>` hold and what {@link setExpression}
          * takes back, so read/modify/write needs no adjusting in between.
          *
-         * Displaying a formula means prefixing `'=' +` — Excel's own API answers that prefixed form
-         * (`Range.Formula`, `Name.RefersTo`) because ITS setters treat the `=` as the formula-ness
-         * marker: assigning `Range.Formula = "SUM(1,2)"` stores text. Ours do not — every entry point
-         * accepts the expression with or without it — so the prefix is presentation, and belongs at
-         * the point of display rather than in a second accessor.
+         * The form with the leading `=` — what Excel's API answers (`Range.Formula`) and what a cell
+         * is entered with — is {@link ICell.getFormulaText}.
+         *
+         * The text is the storage form (English names, `,` separators) whatever language or locale is
+         * active. For the form a person reads or edits, pass `{ target: 'display' }`.
+         *
+         * @example
+         * ```typescript
+         * // With a German language pack active:
+         * formula.getExpression();                       // 'SUM(A1,1.5)'
+         * formula.getExpression({ target: 'display' });  // 'SUMME(A1;1,5)'
+         * ```
          */
         getExpression(options?: ICalculation.FormulaTextOptions): string;
         /**
@@ -334,7 +433,7 @@ export declare namespace ICalculation {
          * This is the primary way to "refactor" a formula—for example, if a user
          * drags a highlighted range in the UI to a new location.
          */
-        setReferenceAt(index: number, reference: ICellRange.Address, options?: string | ITransaction.OperationOptions): this;
+        setReferenceAt(index: number, reference: ICellRange.Address, options?: string | ITransaction.OperationOptions): Promise<this>;
         /**
          * Cycles the absolute/relative (`$`) style of the reference at the specified index.
          *
@@ -358,7 +457,7 @@ export declare namespace ICalculation {
          *
          * * This is the `F4 Cycle` behavior commonly found in spreadsheet editors.
          */
-        setReferenceModeAt(index: number, side?: ICalculation.ReferenceSide, mode?: number, options?: string | ITransaction.OperationOptions): this;
+        setReferenceModeAt(index: number, side?: ICalculation.ReferenceSide, mode?: number, options?: string | ITransaction.OperationOptions): Promise<this>;
         /**
          * Returns true if the formula consists entirely of cell or range references and
          * range operators (`:`, ` `, `#`, etc.) with no function calls or computed expressions.
@@ -375,13 +474,20 @@ export declare namespace ICalculation {
          * @remarks
          * - Volatile formulas are re-evaluated on every calculation cycle regardless
          *   of whether their inputs have changed.
-         * - This is a runtime property tracked by the calculation engine — it cannot
-         *   be derived from static AST analysis alone.
+         * - A property of the formula text first, closed over the names it mentions, so an arm no
+         *   branch selects still counts (`=IF(TRUE,1,RAND())`) and the answer stands with nothing
+         *   calculated — a named formula is never evaluated by a pass. A cell is also volatile when
+         *   its last evaluation read cells its text does not name (`OFFSET`, `INDIRECT`, an `INDEX`
+         *   on a computed index, a `SUMIF` sum range extended to its criteria range): its inputs can
+         *   move with its values. And when the engine registered it as it evaluated: a member of an
+         *   iterated cycle, or a function that marks itself at run time.
          * - Named formulas where `isVolatile()` is true should not be used as
          *   navigation targets even if `isReferenceOnly()` returns true, since their
          *   resolved range may differ by context.
+         * - Asked of the engine: resolves in order behind the writes made before it, and `false`
+         *   while the engine is `Off`.
          */
-        isVolatile(): boolean;
+        isVolatile(): Promise<boolean>;
         /**
          * Return the formula as an array of tokenized values.
          *
@@ -408,8 +514,10 @@ export declare namespace ICalculation {
          * `null` when this formula is already {@link isValid | valid} or no safe correction exists.
          *
          * @remarks
-         * Currently ONE deliberately narrow rule: append the missing trailing closers (`)`, `}`) —
-         * `=SUM(A1:A2` → `=SUM(A1:A2)` — and only when the repaired text parses clean. A repair that
+         * Currently ONE deliberately narrow rule: append the missing trailing closers (`]`, `)`, `}`) —
+         * `=SUM(A1:A2` → `=SUM(A1:A2)`, `=SUM(Sales[Amount` → `=SUM(Sales[Amount])` — and only when the
+         * repaired text parses clean. Excel closes parens and braces but not a structured reference's
+         * brackets. A repair that
          * would still be invalid (`=SUM(` → `=SUM()` fails arity) is never returned, nor is anything
          * attempted for over-closed / interleaved brackets or an unterminated string. Never mutates
          * this formula. Interactive hosts call this at commit; programmatic writes (`setValue`, file
@@ -467,6 +575,14 @@ export declare namespace ICalculation {
          * The comment, or `null` if none has been set.
          */
         getComment(): string | null;
+        /**
+         * What the file said about this name beyond its value — macro bindings, Excel 4.0 and publishing
+         * flags — or `null` when it said nothing.
+         *
+         * @remarks
+         * Read-only: carried and written back as read. None of it changes how the name evaluates.
+         */
+        getFileAttributes(): Readonly<INamed.FileAttributes> | null;
         /**
          * If `true` the name is not shown in the UI. This does not affect resolution in formulas.
          */
@@ -508,7 +624,7 @@ export declare namespace ICalculation {
          * index-aligned reference list (the `setReferenceAt` currency, `#REF!` slots included); this
          * is the graph answer.
          */
-        getDirectPrecedents(): ICellRanges | null;
+        getDirectPrecedents(): Promise<ICellRanges | null>;
         /**
          * Everything upstream of this name — {@link getDirectPrecedents} walked to exhaustion.
          *
@@ -519,9 +635,10 @@ export declare namespace ICalculation {
          * CELL (`X = A1*2`, `A1 = SomeName`) is that cell's precedent, not this answer's — a tree
          * walk crosses it through the cell's own {@link ICell.getDirectPrecedents}.
          */
-        getPrecedents(): ICellRanges | null;
+        getPrecedents(): Promise<ICellRanges | null>;
         /**
-         * What references this SYMBOL — cells and names, one answer; `null` when nothing does.
+         * What references this SYMBOL — cells and names, one answer; `null` when nothing does. Asked of
+         * the engine, as {@link ICell.getDirectPrecedents} is.
          *
          * @remarks
          * **Symbol-level, not target-level.** `=SUM(Revenue)` is a dependent of `Revenue`;
@@ -546,7 +663,7 @@ export declare namespace ICalculation {
          * {@link ICell.getDirectDependents} does: a column of 400 formulas reading the name comes back
          * as one range. Name nodes lead, cells follow.
          */
-        getDirectDependents(): ICellRanges | null;
+        getDirectDependents(): Promise<ICellRanges | null>;
         /**
          * The transitive downstream of this name — everything that would recalculate if its expression
          * changed, cells and names both.
@@ -561,17 +678,21 @@ export declare namespace ICalculation {
          * every cell downstream of either. A cycle terminates and reports the names on it, this one
          * included.
          */
-        getDependents(): ICellRanges | null;
+        getDependents(): Promise<ICellRanges | null>;
         /**
          * Removes this named formula from its collection.
          */
         delete(): void;
     }
     /**
-     * What a {@link FormulaTokenContext} names — the two constructs that open an argument
-     * list, and the two registries that can resolve {@link FormulaTokenContext.name}.
+     * What a {@link FormulaTokenContext} names — the construct that opened the argument list.
+     *
+     * @remarks
+     * `'let'` and `'lambda'` are functions that also open a scope of {@link TokenType.Parameter} names;
+     * they are told apart here so an editor can find those names without matching a localized function
+     * name.
      */
-    type FormulaTokenContextType = 'function' | 'table';
+    type FormulaTokenContextType = 'function' | 'table' | 'let' | 'lambda';
     /**
      * What a token sits INSIDE — the enclosing call and, for a token that is one, which argument.
      *
@@ -599,9 +720,39 @@ export declare namespace ICalculation {
          */
         argIndex: number;
         /**
-         * Whether {@link name} is a function (`SUM(`) or a table (`Sales[`).
+         * Whether {@link name} is a function (`SUM(`), a table (`Sales[`), or a scope-opening `LET(` /
+         * `LAMBDA(`.
          */
         type: FormulaTokenContextType;
+        /**
+         * The `LET` / `LAMBDA` names in scope here, outermost first.
+         *
+         * @remarks
+         * In scope as the binder decides: a `LAMBDA` parameter in every later argument, a `LET` name from
+         * the argument after its value on. An inner declaration spelled the same (case-insensitively)
+         * replaces the outer one, with the inner spelling. Absent when no name is in scope.
+         */
+        bound?: readonly BoundName[];
+    }
+    /**
+     * A `LET` / `LAMBDA` name in scope — one entry of {@link FormulaTokenContext.bound}.
+     */
+    interface BoundName {
+        /** The name as declared. */
+        readonly name: string;
+        /**
+         * The parameters of the `LAMBDA` this name can be called as, in order.
+         *
+         * @remarks
+         * Present only for a `LET` name whose value is a literal `LAMBDA(…)` — `f` in
+         * `LET(f,LAMBDA(x,[y],x+y),f(1))`. Absent for a `LAMBDA` parameter, and for a `LET` name bound to
+         * anything else, including an expression that evaluates to a lambda (`IF(c,LAMBDA(…),LAMBDA(…))`).
+         * `optional` marks a bracketed declaration (`[y]`).
+         */
+        readonly params?: readonly {
+            readonly name: string;
+            readonly optional?: boolean;
+        }[];
     }
     /**
      * Which part of a reference a cell token is, relative to a range operator `:` — the signal
@@ -646,6 +797,43 @@ export declare namespace ICalculation {
          * Never set on a USE of the parameter, nor outside a `LAMBDA` declaration list.
          */
         readonly optional?: boolean;
+        /**
+         * `true` on a `parameter` token that DECLARES its name — `x` in `LET(x,1,x+1)`, `a` in
+         * `LAMBDA(a,a+1)` — rather than using it.
+         */
+        readonly declaration?: boolean;
+    }
+    /**
+     * The {@link FormulaToken.value} of a `tableColumn` or `tableSpecifier` token — one part inside a
+     * structured reference's brackets.
+     *
+     * @remarks
+     * A part's own brackets are `paren` tokens, like the reference's: `Sales[[#Data],[Qty]]` is
+     * `Sales` `[` `[` `#Data` `]` `,` `[` `Qty` `]` `]`, so a part token's `text` is the part alone.
+     */
+    interface TablePartRef {
+        /**
+         * The display name of the table the part belongs to.
+         *
+         * @remarks
+         * For an unqualified reference (`[@Qty]`), the table holding the formula's cell; `''` when there
+         * is none.
+         */
+        readonly table: string;
+        /**
+         * The column's display name, or the canonical specifier (`#Data`, `#This Row`).
+         */
+        readonly name: string;
+        /**
+         * Set only on the unfinished part of a structured reference still being typed — the part an
+         * editor completes — to what may finish it.
+         *
+         * @remarks
+         * `'column'` after `@` or once a column name has started; `'specifier'` once `#` is typed;
+         * `'any'` for a part not yet started. A part not yet started is an empty token (`text` `''`)
+         * right after the `[` or `@` that opened it.
+         */
+        readonly partial?: 'column' | 'specifier' | 'any';
     }
     /**
      * The {@link FormulaToken.value} of an error-REFERENCE token — `#REF!` or `#NAME?`, a reference
@@ -658,18 +846,19 @@ export declare namespace ICalculation {
      * (`PtgRefErr` vs `PtgRefErr3d`).
      *
      * Only error tokens that are REFERENCES take this shape. An error LITERAL (`#DIV/0!`, `#N/A`) is a
-     * value, never scoped, and its `value` stays a plain {@link FormulaError}. Both arrive as
-     * `type: 'error'`, so a consumer that wants the error either way reads `value.error ?? value`.
+     * value, never scoped, and its `value` is the label alone. Both arrive as `type: 'error'`, so a
+     * consumer that wants the label either way reads `value.error ?? value`, and
+     * `FormulaError.getBuiltInByLabel` turns it into the error.
      *
      * Reference-layer only: EVALUATION of a `#REF!` still produces the plain {@link FormulaError}, so
      * a cell value never holds one of these.
      */
     interface ErrorRef {
         /**
-         * The error the dead reference resolves to — `#REF!` (deleted cells) or `#NAME?` (a stored
-         * unresolvable name).
+         * The canonical label of the error the dead reference resolves to — `#REF!` (deleted cells) or
+         * `#NAME?` (a stored unresolvable name).
          */
-        readonly error: FormulaError.Known;
+        readonly error: string;
         /**
          * The sheet name for a qualified error reference (`Data!#REF!`).
          *
@@ -682,6 +871,12 @@ export declare namespace ICalculation {
     }
     /**
      * Represents a portion of a formula for rendering typical in an editor.
+     *
+     * @remarks
+     * A token is plain data — no functions, no class instances — so a token array survives
+     * `JSON.stringify` and `structuredClone`, and can cross a worker or process boundary. What the parse
+     * knows about a token (its {@link FormulaToken.context}, the names in scope there, what an unfinished
+     * part may become) is carried on the token in that form, so every consumer reads the same answer.
      */
     interface FormulaToken {
         /**
@@ -693,10 +888,12 @@ export declare namespace ICalculation {
          *
          * @remarks
          * Reference tokens are structured — a `cell` token carries {@link IRange.FixableCellCoords},
-         * a `named` token a {@link NamedRef}, and an error REFERENCE token (`#REF!`, `#NAME?`) an
+         * a `named` or `parameter` token a {@link NamedRef}, a `tableColumn` or `tableSpecifier` token a
+         * {@link TablePartRef}, and an error REFERENCE token (`#REF!`, `#NAME?`) an
          * {@link ErrorRef}, each holding its own sheet qualifier (`coords.scope` / `ref.scope`) so
          * serializers can re-emit `Sheet1!…`. Most other tokens (operators, function names, separators)
-         * carry a string; literals carry their parsed value (number, boolean, error).
+         * carry a string; literals carry their parsed value (number, boolean), an error literal its
+         * canonical label (`#DIV/0!`).
          */
         value: string | IRange.FixableCellCoords | NamedRef | ErrorRef | any;
         /**
@@ -727,31 +924,17 @@ export declare namespace ICalculation {
          */
         evalIndex?: number;
         /**
-         * `true` when this token is part of a reference *literal* — a cell (`A1`), a range operator that
-         * binds one (`:`, ` `, `#`, `@`), a named reference, or a structured-reference part. Lets an editor
-         * color the whole reference span (operators included) without enumerating token types.
+         * The reference *literal* this token is part of, as an offset into
+         * {@link ICalculation.IFormula.getReferences}. Tokens sharing an index are one reference span — an
+         * editor colors them as one unit.
          *
          * @remarks
-         * Distinct from merely having a {@link referenceIndex}: a function that *returns* a reference (e.g.
-         * `INDEX`, `OFFSET`) carries a `referenceIndex` but is **not** a reference literal, so `isReference`
-         * is absent on its `function` token. Color by `referenceIndex` only when `isReference` is `true`.
-         */
-        isReference?: boolean;
-        /**
-         * `true` when this token is a **name-completion candidate** — an identifier that could be resolved
-         * against the function / named-reference / table registries: a function name, a named reference, a
-         * table reference, or a partial identifier still being typed (a trailing run in an `unparsed` tail).
-         * The sibling of {@link isReference}: it lets an editor decide, from the caret's token alone, that an
-         * autocomplete list belongs here — without re-scanning the raw text. Use the token's `text` as the
-         * prefix to filter. Absent on non-candidate tokens (numbers, strings, cells, operators, punctuation).
-         */
-        isLookup?: boolean;
-        /**
-         * Indicates that the token is part of a reference.
-         *
-         * @remarks
-         * * Multiple tokens can be part of the same reference.
-         * * The referenceIndex will be the offset of the range in the {@link ICalculation.IFormula.getReferences} array.
+         * * Carried by a cell (`A1`), the range operator joining two cells (`:` in `A1:B2`), a spill anchor
+         *   (`#`), an error reference (`#REF!`), and every part of a structured reference (`Sales[Col]`,
+         *   brackets included).
+         * * Absent on a named reference (names stay uncolored, as in Excel), on a function that *returns* a
+         *   reference (`INDEX`, `OFFSET`), and on an operator whose operands are not both cells
+         *   (`A1:INDEX(…)`, `@A1`).
          */
         referenceIndex?: number;
         /**
@@ -806,10 +989,15 @@ export declare namespace ICalculation {
          * reference, a structured-reference part).
          */
         readonly isReference?: boolean;
+        /**
+         * The ROOT only: this formula came from a LEGACY (pre-dynamic-array) cell, so its whole tree
+         * evaluates in implicit-intersection VALUE mode.
+         */
+        readonly legacyIntersect?: boolean;
     }
     /**
-     * A structural transform over a formula's AST — a visitor applied where formulas serialize
-     * ({@link ISheet.ToJSONOptions.formulaTransform | toJSON}) or parse.
+     * A structural transform over a formula's tree: a visitor a file format applies to formula
+     * text as it reads or writes it ({@link FormulaText.transform}).
      *
      * @remarks
      * Called once for every node, children before parents (depth-first). Return a replacement
@@ -826,6 +1014,21 @@ export declare namespace ICalculation {
      * side-effect free and no-op-safe on a partially parsed (errored) tree.
      */
     type FormulaTransform = (node: FormulaNode, parent: FormulaNode | undefined) => FormulaNode | void;
+    /**
+     * Who a formula's text is for.
+     *
+     * @remarks
+     * - `'storage'` — the form files, APIs and re-parses use: English function names, `,` argument
+     *   separators, `.` decimals, English boolean and error words, and an external book as its `[n]`
+     *   position. It reads the same in every language and locale.
+     * - `'display'` — the form a person reads and edits: function names, booleans, errors and
+     *   structured-reference specifiers from the active language pack, separators from the workbook
+     *   locale, and an external book as its own path (`'C:\dir\[Book.xlsx]Sheet1'!A1`).
+     *
+     * The same choice applies to text going in: {@link ICalculation.createFormula} reads storage
+     * text unless told the text is display.
+     */
+    type FormulaTarget = 'storage' | 'display';
     /**
      * Options for evaluating a formula.
      */
@@ -862,14 +1065,30 @@ export declare namespace ICalculation {
          *   scalar unless {@link alwaysReturnRange} is set.
          * - A cell whose evaluation errors carries the error as that cell's value; other
          *   cells are unaffected.
-         * - Cells evaluate sequentially — an async cell (a formula hitting an async function)
-         *   settles before the next cell starts.
+         * - Evaluated by the engine, in one pass, exactly as a formula filled across the shape.
          * - Honored by temporary formulas ({@link ICalculation.evaluate} /
          *   {@link ICalculation.createFormula}); a committed cell formula ignores it.
          * - Often used for "preview this formula over this region" or batched
          *   validation of an expression over a condition range.
          */
         block?: IRange.Coords;
+        /**
+         * With {@link block}: evaluate each cell of the block as an array-entered formula whose extent
+         * is that one cell.
+         *
+         * @remarks
+         * This is how a conditional-format or data-validation formula is evaluated. Nothing
+         * implicitly intersects — a range reads as the whole array wherever it appears — and each
+         * cell keeps the top-left value of its own result, the way an array-entered formula fits its
+         * result to its extent. So `$J$1:$J$9="x"` answers `J1="x"` in every cell, while
+         * `SUM(IF($J$1:$J$9="x",1,0))>1` still sums the whole array.
+         *
+         * By default a cell whose result is an array spills, as a formula filled across the block
+         * would.
+         *
+         * @defaultValue `false`
+         */
+        arrayFirstCell?: boolean;
         /**
          * If specified, the result will always be returned as an `IRange`,
          * even when the logical result is a single scalar value.
@@ -901,21 +1120,29 @@ export declare namespace ICalculation {
          */
         evalIndex?: number;
         /**
-         * If `true`, function names are returned in CANONICAL (English) form — the
-         * persistence/interchange representation (files, clipboard interchange, APIs).
-         * Default `false` = display form, localized via the active language pack
-         * (I18N-DESIGN.md Plane 3).
+         * Who the text is for.
          *
-         * @defaultValue `false`
+         * @defaultValue `'storage'`
+         *
+         * @remarks
+         * Pass `'display'` for text a person reads or edits. See {@link FormulaTarget}.
          */
-        canonical?: boolean;
+        target?: FormulaTarget;
+    }
+    /**
+     * Options for parsing formula text ({@link ICalculation.createFormula}, {@link ICalculation.evaluate}).
+     */
+    interface CreateFormulaOptions {
         /**
-         * A structural transform applied to the compiled AST before imaging — how a format
-         * exporter (e.g. xlsx) applies its version-compatibility spellings.
+         * What form the text is in.
          *
-         * @see {@link FormulaTransform}
+         * @defaultValue `'storage'`
+         *
+         * @remarks
+         * Pass `'display'` for text a person typed or read in their language and locale. See
+         * {@link FormulaTarget}.
          */
-        formulaTransform?: FormulaTransform;
+        target?: FormulaTarget;
     }
     interface Events extends IModel.Events {
         /**
@@ -943,6 +1170,10 @@ export declare namespace ICalculation {
          * Called when the calculation status has changed.
          */
         onStatusChange?(source: ICalculation): void;
+        /**
+         * Called when the calculation state has changed - see {@link ICalculation.getCalculationState}.
+         */
+        onCalculationStateChange?(source: ICalculation): void;
         /**
          * Called when a calculation is completed.
          */
@@ -968,11 +1199,14 @@ export declare namespace ICalculation {
      */
     const Status: {
         /**
-         * The calculation engine is in manual mode and will only update cell values when a calculation is explicitly triggered.
+         * The calculation engine is running: it follows the model and answers for it. Whether it has
+         * work in hand is its calculation state (`getCalculationState()`), not this.
          */
-        readonly Ready: "ready";
+        readonly Running: "running";
         /**
-         * The calculation engine has encountered an error and is unable to perform calculations.
+         * The calculation engine failed to start and is unable to perform calculations. Unusable as
+         * {@link ICalculation.Status.Off} is, but {@link ICalculation.ready} does not start it again;
+         * {@link ICalculation.start} does.
          * This status represents engine-level errors, separate from cell-level errors (which are represented as Scalar.Error values).
          */
         readonly Error: "error";
@@ -993,6 +1227,26 @@ export declare namespace ICalculation {
     /**
      * Represents the calculation mode of the engine, which determines when and how formulas are recalculated.
      */
+    /**
+     * Whether the running engine has work in hand - Excel's `XlCalculationState`.
+     */
+    const CalculationState: {
+        /**
+         * Nothing is out of date and nothing is in flight.
+         */
+        readonly Done: "done";
+        /**
+         * Work is in hand: a pass running or owed, answers the engine owes the model that have not
+         * landed, or work a consumer derives from the results ({@link ICalculation.waitUntil}).
+         */
+        readonly Calculating: "calculating";
+        /**
+         * Changes have been made that need a recalculation, and none will run until one is asked for:
+         * manual mode between an edit and {@link ICalculation.calculate}.
+         */
+        readonly Pending: "pending";
+    };
+    type CalculationState = typeof CalculationState[keyof typeof CalculationState];
     const CalculationMode: {
         /**
          * In automatic calculation mode, the calculation engine automatically recalculates all dependent formulas
@@ -1020,9 +1274,9 @@ export declare namespace ICalculation {
      * @remarks
      * With it off a reference cycle evaluates to `0` and is reported as unresolved. With it on the
      * cells of the cycle are re-evaluated in turn, each read seeing the latest value, until no cell
-     * moved by {@link maxChange} or {@link maxIterations} sweeps ran — and the results persist into
+     * moved by {@link maxChange} or {@link maxIteration} sweeps ran — and the results persist into
      * the next recalculation, which re-runs every cycle the way it re-runs `NOW()`: `=A1+1` in A1 is
-     * a counter that advances by `maxIterations` per recalc. A cycle that stops on the sweep cap is
+     * a counter that advances by `maxIteration` per recalc. A cycle that stops on the sweep cap is
      * still reported ({@link ICircularReference.isConverged}); a converged one is not.
      *
      * Office Scripts calls the count `maxIteration`; the file format `iterateCount` / `iterateDelta`.
@@ -1037,7 +1291,7 @@ export declare namespace ICalculation {
          *
          * @defaultValue `100`
          */
-        maxIterations: number;
+        maxIteration: number;
         /**
          * Sweeps stop early once every cell in the cycle moved by less than this. A non-numeric
          * change (text, error) never counts as settled.
@@ -1106,6 +1360,19 @@ export declare namespace ICalculation {
         scope?: string;
     }
     interface JSON {
+        /**
+         * The unmarked formulas were entered before dynamic arrays: every formula that is not an
+         * array anchor evaluates in legacy implicit-intersection mode, where each call takes one
+         * value from a range argument in a single-value slot.
+         *
+         * @remarks
+         * What an xlsx file means by a plain `<f>`: Excel marks the formulas that need the dynamic
+         * reading (`cm=` and `t="array"`, which load as `formulaArray`) and everything else is
+         * legacy. Nothing in a formula's text says its era, so it is carried here, once for the
+         * workbook, the way the file carries it. Content authored in the app leaves it unset. A
+         * sheet pasted into another workbook takes that workbook's era.
+         */
+        legacyIntersect?: boolean;
         /**
          * Indicates whether the workbook has completed its last calculation cycle.
          *
@@ -1132,12 +1399,10 @@ export declare namespace ICalculation {
          */
         concurrentCalc?: boolean;
         /**
-         * Specifies whether concurrent calculations are allowed in manual calculation mode.
-         *
-         * @remarks
-         * If `true`, manual calculations can utilize multiple threads.
+         * How many threads concurrent calculation uses, when the count was set by hand rather than
+         * left to the number of processors. Kept from the file.
          */
-        concurrentManualCount?: boolean;
+        concurrentManualCount?: number;
         /**
          * Specifies whether the workbook forces a full recalculation of all formulas.
          *
@@ -1174,7 +1439,7 @@ export declare namespace ICalculation {
          * @remarks
          * This value is only used if `iterate` is set to `true`.
          */
-        maxIterations?: number;
+        maxIteration?: number;
         /**
          * Defines the maximum change between iterations that must be reached before the iterative calculation stops.
          *