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

package/types/src/calculation/formula/Formula.d.ts

@@ -4,7 +4,7 @@ import { ICellRanges, ICellRange } from '../../cellRange';
 import { ICalcGrid } from '../grid';
 import { ReferenceCoords } from '../Types';
 import { ICalculation } from '../ICalculation';
-import { IFormulaBlock } from './IFormulaBlock';
+import { IFormulaBlock, IFormulaBlockView } from './IFormulaBlock';
 /**
  * A formula for a cell.
  */
@@ -12,6 +12,7 @@ export declare class Formula implements ICalculation.IFormula {
     protected _coords: IRange.CellCoords | null;
     private _blockOwn;
     protected _options: Formula.ConstructorOptions;
+    private _isCompiled;
     /**
      * The compiled body this formula reads through.
      *
@@ -23,16 +24,31 @@ export declare class Formula implements ICalculation.IFormula {
      * undo replaces the block in the versioned store and any captured instance is a snapshot of the
      * definition as it was. A cell formula is handed its block at construction and keeps it.
      */
-    protected get _block(): IFormulaBlock;
+    protected get _block(): IFormulaBlockView;
+    /**
+     * @param isCompiled Whether the engine has compiled the body behind `block` yet. Supplied by a
+     * sheet cell, whose block is the sheet's own entry and may still be pending; a detached formula
+     * holds a compiled block and omits it. Read on every call, never captured: the entry heals in
+     * place when the engine vends, and so does this handle.
+     */
     constructor(coords: IRange.CellCoords | null, // temporary
-    block: IFormulaBlock, options: Formula.ConstructorOptions);
+    block: IFormulaBlockView, options: Formula.ConstructorOptions, isCompiled?: () => boolean);
+    /** {@inheritDoc ICalculation.IFormula.isCompiled} */
+    isCompiled(): boolean;
     /** {@inheritDoc ICalculation.IFormula.getTokens} */
     getTokens(evalIndex?: number): readonly ICalculation.FormulaToken[];
     /** {@inheritDoc ICalculation.IFormula.isValid} */
     isValid(): boolean;
     /** {@inheritDoc ICalculation.IFormula.autoCorrect} */
     autoCorrect(): ICalculation.IFormula | null;
-    /** {@inheritDoc ICalculation.IFormula.evaluate} */
+    /**
+     * {@inheritDoc ICalculation.IFormula.evaluate}
+     *
+     * @remarks
+     * Through the grid, not this formula's own block: evaluating needs the engine's calc scope.
+     * ({@link TemporaryFormula} overrides this - an in-flight formula was never written to a grid
+     * and evaluates locally.)
+     */
     evaluate(options?: number | ICalculation.EvaluateOptions): Promise<Scalar | IRange>;
     /** {@inheritDoc ICalculation.IFormula.getCalculationStatus} */
     getCalculationStatus(): ICalculation.ResultStatus;
@@ -40,6 +56,11 @@ export declare class Formula implements ICalculation.IFormula {
     getReferences(): ICellRanges | null;
     /** {@inheritDoc ICalculation.IFormula.hasRefError} */
     hasRefError(): boolean;
+    /**
+     * The written references at this formula's cell, absolute, from its block: a committed formula's
+     * is the model's view of the engine's record, so nothing asks the engine. `null` with no cell.
+     */
+    protected _referencesAt(): ReferenceCoords[] | null;
     /**
      * Resolve raw ABSOLUTE precedent refs (cell/range coords or named ids) into an {@link ICellRanges}, or
      * `null` when there are none. Shared by the committed path ({@link getReferences}) and
@@ -47,13 +68,20 @@ export declare class Formula implements ICalculation.IFormula {
      */
     protected _resolveReferences(rawRefs: ReferenceCoords[] | undefined): ICellRanges | null;
     /** {@inheritDoc ICalculation.IFormula.setReferenceAt} */
-    setReferenceAt(index: number, reference: ICellRange.Address, options?: string | ITransaction.OperationOptions): this;
+    setReferenceAt(index: number, reference: ICellRange.Address, options?: string | ITransaction.OperationOptions): Promise<this>;
+    /**
+     * The formula after a rewrite: the cell's own handle, which reads the entry the grid adopted
+     * the block into inside the batch; this one when the rewrite emptied the cell.
+     */
+    protected _rewritten(written: IFormulaBlockView | null, coords: IRange.CellCoords): this;
     /** {@inheritDoc ICalculation.IFormula.setReferenceModeAt} */
-    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>;
+    /** A reference edit rewrites the compiled body; there is none to rewrite while pending. */
+    protected _checkCompiled(): void;
     /** {@inheritDoc ICalculation.IFormula.isReferenceOnly} */
     isReferenceOnly(): boolean;
     /** {@inheritDoc ICalculation.IFormula.isVolatile} */
-    isVolatile(): boolean;
+    isVolatile(): Promise<boolean>;
     /** {@inheritDoc ICalculation.IFormula.getExpression} */
     getExpression(options?: ICalculation.FormulaTextOptions): string;
     /** {@inheritDoc ICalculation.IFormula.getAnchor} */
@@ -69,20 +97,17 @@ export declare class Formula implements ICalculation.IFormula {
     get isIFormula(): true;
 }
 export declare class TemporaryFormula extends Formula {
+    /**
+     * Narrowed to the full {@link IFormulaBlock}. An in-flight formula evaluates LOCALLY rather
+     * than reading a grid, and that path reaches engine-side members (`_doEval` calls
+     * `finalizeValueForCell`) - so unlike the committed base, which needs only
+     * {@link IFormulaBlockView}, this holds a real compiled block.
+     */
+    protected get _block(): IFormulaBlock;
     protected _doEval: (block: IFormulaBlock, options: number | ICalculation.EvaluateOptions) => Promise<Scalar | IRange>;
     constructor(coords: IRange.CellCoords | null, block: IFormulaBlock, options: Formula.ConstructorOptions, doEval: (block: IFormulaBlock, options: number | ICalculation.EvaluateOptions) => Promise<Scalar | IRange>);
     /** {@inheritDoc ICalculation.IFormula.evaluate} */
     evaluate(options: number | ICalculation.EvaluateOptions): Promise<Scalar | IRange>;
-    /**
-     * {@inheritDoc ICalculation.IFormula.getReferences}
-     *
-     * @remarks
-     * Sources references from THIS block, not the grid — a temporary / in-flight formula (what the editor
-     * tokenizes while typing) was never written to the grid, so `getReferencesAt` at these coords would
-     * come back empty (blank cell) or stale (an existing formula being edited). The block yields RELATIVE
-     * refs; convert to absolute exactly as `ICalcGrid.getReferencesAt` does, then resolve as usual.
-     */
-    getReferences(): ICellRanges | null;
     /**
      * {@inheritDoc ICalculation.IFormula.hasRefError}
      *
@@ -100,7 +125,7 @@ export declare class TemporaryFormula extends Formula {
      * committed cell); an in-flight edit (an editor range drag) must instead just produce the new text
      * (via `getExpression`) without committing. Returns a new `TemporaryFormula` so it stays evaluable + chainable.
      */
-    setReferenceAt(index: number, reference: ICellRange.Address): this;
+    setReferenceAt(index: number, reference: ICellRange.Address): Promise<this>;
     /**
      * {@inheritDoc ICalculation.IFormula.setReferenceModeAt}
      *
@@ -109,14 +134,20 @@ export declare class TemporaryFormula extends Formula {
      * block's reference and writes through the (pure) {@link setReferenceAt} instead of a grid transaction.
      * Returns `this` unchanged when there's no reference at `index` (e.g. the caret isn't on one).
      */
-    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>;
 }
 export declare namespace Formula {
     interface ConstructorOptions {
         getRanges(address: ICellRanges.Address, options?: ICellRange.GetRangeOptions): ICellRanges;
         getRange(address: ICellRange.Address, options?: ICellRange.GetRangeOptions): ICellRange;
-        getCalcGrid?(): ICalcGrid;
-        doBatchCalcGrid?(callback: (calcGrid: ICalcGrid) => IRange.Coords, options?: string | ITransaction.OperationOptions): void;
+        /** The grid the formula is in: what it evaluates and rewrites its references through. */
+        getCalcGrid?(): Pick<ICalcGrid, 'evaluateAt' | 'setReferenceAt' | 'setReferenceModeAt' | 'isVolatileAt'> | null;
+        doBatchCalcGrid?(callback: (calcGrid: ICalcGrid) => Promise<IRange.Coords | null>, options?: string | ITransaction.OperationOptions): Promise<void>;
+        /**
+         * The engine's status, read when a pending formula is asked to evaluate: a `Starting` engine
+         * is awaited, an `Off` one is not started (see {@link ICalculation.IFormula.isCompiled}).
+         */
+        getCalculationStatus?(): ICalculation.Status;
         /**
          * Resolve a sheet's internal stableId (`Sheet1-<uuid>`, rename-safe) to its current display name,
          * or `null` when it can't be resolved. Reference coords from the calc engine carry stableId scopes;
@@ -143,6 +174,12 @@ export declare namespace Formula {
          * coords (the temporary path's `scope`-carrying originals) may ignore it.
          */
         autoCorrect?(text: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula | null;
+        /**
+         * The form of the text {@link autoCorrect} and {@link createAt} are handed and compile.
+         *
+         * @defaultValue `'storage'`
+         */
+        inputTarget?: ICalculation.FormulaTarget;
         /**
          * Compile `text` as a DETACHED formula anchored at `coords`. Supplied by the calculation, which
          * owns the editing compiler (`Calculation.createFormula`), for the same reason

package/types/src/calculation/formula/FormulaBlock.d.ts

@@ -3,9 +3,9 @@ import { ICalculation } from '../ICalculation';
 import { CalcScope } from '../state';
 import { CompiledFormula } from '../compiler';
 import { ASTNode, FunctionNode } from '../compiler/ASTTypes';
-import { NamedReference, StructuredReference, ReferenceCoords, SetReferenceOptions } from '../Types';
+import { NamedReference, StructuredReference, ReferenceCoords, SetReferenceOptions, PrecedentTemplate } from '../Types';
 import { LambdaValue } from './LambdaValue';
-import { IFormulaBlock } from './IFormulaBlock';
+import { IFormulaBlock, FormulaRecord } from './IFormulaBlock';
 /**
  * Optional resolver callbacks injected by `Calculation` at construction time.
  *
@@ -42,9 +42,16 @@ export declare class FormulaBlock implements IFormulaBlock {
      * When `null` both reference types return formula errors.
      */
     protected _resolvers: FormulaBlockResolvers | null;
+    /**
+     * {@link getPrecedentTemplate}'s answer, computed on first ask. `undefined` = not asked yet,
+     * `null` = this block's precedents are not a pure translation.
+     */
+    protected _precedentTemplate: PrecedentTemplate | null | undefined;
+    /** {@link getRecord}'s answer, built on first ask; every vend of this block shares it. */
+    private _record;
     constructor(compiled: CompiledFormula, context: IFormulaContext, scope: CalcScope, gridId: string | null, getEntireCoords: () => IRange.Coords, resolvers?: FormulaBlockResolvers | null);
     /** @inheritdoc IFormulaBlock.getTextAt */
-    getTextAt(row: number, column: number, r1c1?: boolean, formulaTransform?: ICalculation.FormulaTransform, evalIndex?: number, canonical?: boolean): string;
+    getTextAt(row: number, column: number, r1c1?: boolean, evalIndex?: number, target?: ICalculation.FormulaTarget): string;
     /**
      * The display (non-canonical) locale: separators from the workbook locale (Plane 1) and boolean/
      * error/specifier literals from the active spreadsheet-language pack (Plane 3). Resolved per call so
@@ -52,6 +59,15 @@ export declare class FormulaBlock implements IFormulaBlock {
      * on the emit path; the parse callbacks and raw word-lists go unused here.
      */
     private _displayLocale;
+    /** @inheritdoc IFormulaBlock.getRecord */
+    getRecord(): FormulaRecord;
+    /**
+     * The written references as the record carries them: {@link getReferences} before anything is
+     * resolved against a cell or a symbol.
+     */
+    private _recordReferences;
+    /** @inheritdoc IFormulaBlock.getNode */
+    getNode(): ICalculation.FormulaNode | null;
     /** @inheritdoc IFormulaBlock.getTokensAt */
     getTokensAt(row: number, column: number, evalIndex?: number): ICalculation.FormulaToken[];
     /** @inheritdoc IFormulaBlock.getError */
@@ -62,20 +78,35 @@ export declare class FormulaBlock implements IFormulaBlock {
     getReferencedSymbolIds(): string[];
     /** @inheritdoc IFormulaBlock.hasTotals */
     hasTotals(): boolean;
+    /** @inheritdoc IFormulaBlock.isBlankCacheable */
+    isBlankCacheable(arrayMode?: boolean): boolean;
+    /** @inheritdoc IFormulaBlock.demandFirstCell */
+    demandFirstCell(): void;
     /** @inheritdoc IFormulaBlock.isReferenceOnly */
     isReferenceOnly(): boolean;
     /** @inheritdoc IFormulaBlock.isEquals */
     isEquals(other: IFormulaBlock): boolean;
     /** @inheritdoc IFormulaBlock.getReferences */
     getReferences(row: number, column: number): ReferenceCoords[];
+    /** @inheritdoc IFormulaBlockView.getReferencesAt */
+    getReferencesAt(row: number, column: number): ReferenceCoords[];
+    /** Built on first ask; the same array for every cell, so a run of cells conflates by identity. */
+    private _formatReferences;
+    /** @inheritdoc IFormulaBlock.getFormatReferences */
+    getFormatReferences(): IRange.FixableCoords[];
     /** @inheritdoc IFormulaBlock.getReferenceAt */
     getReferenceAt(row: number, column: number, index: number): ReferenceCoords;
     /** @inheritdoc IFormulaBlock.setReferenceAt */
     setReferenceAt(index: number, reference: ReferenceCoords, options?: SetReferenceOptions): this;
     /** @inheritdoc IFormulaBlock.reanchorReferences */
     reanchorReferences(scopeFrom: string, force?: boolean): this;
-    /** @inheritdoc IFormulaBlock.replaceSheetReferences */
-    replaceSheetReferences(fromSheetDisplay: string, toSheetDisplay: string): this;
+    /** @inheritdoc IFormulaBlock.replaceScopeIds */
+    replaceScopeIds(fromScopeId: string | null, toScopeId: string | null): this;
+    /**
+     * This block with every structured reference to `tableId` replaced by the node `replace` builds
+     * for it (`null` keeps the reference), or this block when nothing was replaced.
+     */
+    replaceTableReferences(tableId: string, replace: (reference: StructuredReference) => ASTNode | null): this;
     /**
      * Resolves a named reference by evaluating its shared body at the caller's anchor
      * (Design 3, apply-at-eval). The body value is taken **raw** (no finalize) so a
@@ -105,6 +136,8 @@ export declare class FormulaBlock implements IFormulaBlock {
     protected _resolveStructuredRef(structuredReference: StructuredReference, row: number, column: number, reuse?: IRange.Coords): IRange.FixableCoords | FormulaError.Known;
     /** @inheritdoc IFormulaBlock.resolvedPrecedentsAt */
     resolvedPrecedentsAt(row: number, column: number, includeInvalidIntersect?: boolean, verticalAbs?: boolean[], horizontalAbs?: boolean[]): readonly (Readonly<IRange.FixableCoords> | FormulaError.Known)[];
+    /** @inheritdoc IFormulaBlock.getPrecedentTemplate */
+    getPrecedentTemplate(): PrecedentTemplate | null;
     /** @inheritdoc IFormulaBlock.evaluateAt */
     evaluateAt(row: number, column: number, evalIndex?: number): Scalar | Promise<Scalar>;
     /** @inheritdoc IFormulaBlock.wrapImplicit */
@@ -118,8 +151,11 @@ export declare class FormulaBlock implements IFormulaBlock {
      * closure so both paths run the identical semantics.
      * @param row The anchor the formula is being evaluated at (lambda values record it).
      * @param column The anchor column.
+     * @param frame The lambda-parameter frame in scope, when this node is executing inside an
+     * activation. Only a LAZY argument's handle needs it — it must resolve a bound name the same way
+     * the enclosing body would have.
      */
-    protected _executeNode(node: ASTNode, regs: any[], row: number, column: number): any;
+    protected _executeNode(node: ASTNode, regs: any[], row: number, column: number, frame?: ReadonlyMap<number, any> | null): any;
     /**
      * Closes a `LAMBDA` node over the current registers — the node's whole evaluation (design §3.3).
      *
@@ -132,6 +168,25 @@ export declare class FormulaBlock implements IFormulaBlock {
      * shared named-body block at every level, and only a copy keeps an outer activation's captured
      * environment intact underneath it. See `LambdaValue`.
      */
+    /**
+     * Fills the shared argument buffer for a call that has at least one LAZY argument, deciding per
+     * call whether to defer at all.
+     *
+     * @remarks
+     * The engine declines whenever an eager argument is a CONTAINER, because the call is then about
+     * to LIFT: the body runs once per element and different elements may select different arms, so
+     * every arm is needed. Excel abandons laziness there too — `=IF(B1:B3>0,1,A1+1)` in A1 IS a
+     * circular reference where the scalar-condition form is not (measured, `probe-lazy-args.ps1`).
+     *
+     * A declined argument is evaluated ONCE, here, and handed over as the VALUE rather than as a
+     * filled handle: the lift SAMPLES an arm per element (`IF(A1:A5>2,A1:A5,0)` answers element by
+     * element), and only the marshaller can sample it. The handle it hands the body is rebuilt there,
+     * around the sampled member. So the arm is evaluated once and indexed, never re-evaluated.
+     *
+     * Deferring evaluates nothing, so nothing can re-enter `_reuseArgs` while it is being filled.
+     * The decline path does evaluate, and takes a private array for exactly that reason.
+     */
+    protected _fillLazyArgs(argsIndexed: ASTNode[], argsLength: number, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number, depth: number): void;
     protected _createLambdaValue(node: FunctionNode, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number): LambdaValue;
     /**
      * The callee verdicts + apply for a `Call` node (design §3.4, §1.1):
@@ -149,9 +204,9 @@ export declare class FormulaBlock implements IFormulaBlock {
      * Apply over VALUES — the marshalled-callable twin of {@link _applyCallee}'s lambda branch
      * (design §4). Reached through {@link LambdaValue.makeCallable} while a CONSUMER's body
      * (`BYROW`, `REDUCE`, …) is running; the arguments are plain engine values, so binding needs no
-     * argument nodes. `undefined` is the callable's spelling for an unsupplied argument — it binds
-     * the OMITTED sentinel at an OPTIONAL parameter and is `#VALUE!` at a required one, mirroring
-     * the spelled-call rule (§2.6).
+     * argument nodes. An `undefined` IN the list is the callable's spelling for an explicitly
+     * empty argument and binds the OMITTED sentinel; a list SHORT of the required count is the
+     * arity `#VALUE!`, mirroring the spelled-call rule (§2.6).
      */
     _applyValues(callee: LambdaValue, args: readonly any[]): any;
     /**
@@ -164,20 +219,68 @@ export declare class FormulaBlock implements IFormulaBlock {
      * enclosing frame — see `_applyCallee`).
      *
      * @remarks
-     * The walker mirrors the eager pipeline exactly: literals and eagerly-resolved references read
-     * from the activation registers (a copy of the creation snapshot), operators and functions
-     * execute through the same `_executeNode`, and a node's result lands in its register before the
-     * parent reads it. Only three things differ from eager evaluation — a bound name may read the
-     * FRAME (a lambda parameter has no register), an unbound name resolves NOW at the creation
-     * anchor (`deferredResolve`), and a nested `LAMBDA` closes over this activation.
-     *
-     * Recursion arrives only via a defined name cycling back through a deferred resolve, and
-     * `depth` is the budget that bounds it. NOTE the engine's eager `IF` makes a terminating
-     * recursion still BURN to the depth limit before unwinding (the un-taken branch is evaluated,
-     * bottoms out at `#NUM!`, and the selector discards it) — correct results at O(limit) cost;
-     * Excel Online avoids the cost with a lazy `Conditional` term. Recorded in the plan.
+     * The body's list runs against the lambda's register SNAPSHOT (`LambdaValue.regs`), the same
+     * loop and node semantics as the eager pass, with this frame in scope. The snapshot is shared
+     * by every application of the value: a body writes each register it reads before it reads it,
+     * so a sequential re-application (`BYROW` over a range) leaves nothing stale behind. Only a
+     * RE-ENTRANT application — the same value applied while an activation of it is still running,
+     * which takes the value being passed to itself (`LET(f,LAMBDA(self,n,…self(self,n-1)…),f(f,3))`)
+     * — gets a private copy, since the inner run would otherwise clobber registers the outer
+     * parent has yet to read.
+     *
+     * Recursion arrives via a defined name cycling back through a deferred resolve (each level a
+     * fresh value with its own snapshot), and `depth` is the budget that bounds it.
      */
     protected _evaluateBody(lambda: LambdaValue, frame: ReadonlyMap<number, any>): any;
+    /**
+     * The VALUE of a lazy argument's subtree — {@link _evaluateSubtree} plus the one conversion the
+     * marshaller used to make on the way in.
+     *
+     * @remarks
+     * A bare reference's register holds resolved COORDS, an internal shape: every eager consumer
+     * turns it into a reference at the slot it lands in. A forced handle has no slot — its value IS
+     * the call's answer — so the conversion happens here, and `=IF(TRUE,E200,0)` answers a reference
+     * exactly as the eagerly-marshalled arm did.
+     */
+    _valueOfLazy(node: ASTNode, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number): any;
+    /**
+     * Evaluates one subtree that the eager pass did not — a lambda's BODY at apply, or a LAZY
+     * argument when the call's answer turns out to be its handle. The deferred half of the
+     * carve-out (design §3.3).
+     *
+     * @param node The subtree root — a node the compiler stamped a `deferred` list on, or (for a
+     * partial evaluation) any node inside one.
+     * @param regs The register file to evaluate against — a lambda ACTIVATION, or the block's own
+     * live file for a lazy argument, which is forced within the evaluation that built it.
+     * @param frame slot → argument value for the enclosing activation, or `null` outside one.
+     * @param row The anchor to evaluate at.
+     * @param column The anchor column.
+     *
+     * @remarks
+     * The same loop as the eager pass over the subtree's own post-order list: literals and
+     * eagerly-resolved references are already in their registers, and everything else executes
+     * through `_executeNode` into its register before the parent reads it. The frame is the one
+     * thing the eager pass never has.
+     *
+     * Recursion arrives via a defined name cycling back through a deferred resolve, and the caller's
+     * `depth` bounds it. With lazy arguments a terminating recursion costs O(depth): the base case's
+     * untaken arm is a handle nobody forces.
+     */
+    protected _evaluateSubtree(node: ASTNode, regs: any[], frame: ReadonlyMap<number, any> | null, row: number, column: number): any;
+    /**
+     * Runs an execution list — the eager `executions` or a deferred root's list — writing each
+     * node's result into its register. Answers the promise chain when a node is async, in which
+     * case the rest of the list is queued behind it.
+     */
+    protected _runList(list: ASTNode[], regs: any[], row: number, column: number, frame: ReadonlyMap<number, any> | null): Promise<any> | undefined;
+    /**
+     * The execution list of a subtree that is NOT a deferred root — a partial evaluation (the
+     * editor's tooltip) pointing inside a lazy argument. The enclosing root's list restricted to
+     * the subtree keeps its post-order, and is cached on the node. Not a hot path.
+     */
+    private _listWithin;
+    /** Whether the cell being evaluated is in a block that demands its first cell (`FormulaSpatialValue.arrayFirstCell`). */
+    private _demandsFirstCell;
     /**
      * Calls a function.
      *

package/types/src/calculation/formula/FormulaRecordView.d.ts

@@ -0,0 +1,79 @@
+import { FormulaError, IRange } from '@sheetxl/primitives';
+import { ISymbolRegistry } from '../symbol';
+import { ICalculation } from '../ICalculation';
+import { ReferenceCoords, StructuredReference } from '../Types';
+import { CompilerLocale } from '../compiler/CompilerLocale';
+import { FormulaRecord, IFormulaBlockView } from './IFormulaBlock';
+/**
+ * What imaging a {@link FormulaRecord} needs beside the record (DESIGN-CALC-SERVICE §8): the
+ * symbol map to resolve its stable ids against, the grid the formula sits on, and the reader's
+ * locale. The facade supplies the model's own map; the engine never images for it.
+ */
+export interface FormulaImager {
+    /** Stable ids to display names. */
+    readonly symbols: ISymbolRegistry;
+    /** The grid the formula sits on: the home scope of a display image (`Table1[@Qty]` drops the table's name). */
+    readonly gridId: string | null;
+    /** The grid's bounds: a relative reference driven off them images `#REF!`. */
+    getEntireCoords(): IRange.Coords;
+    /** The reader's separators and literal words, for a display image. */
+    getDisplayLocale(): CompilerLocale;
+    /**
+     * The cells a table reference designates from `row`, against the model's table as it is now.
+     * Without it a table reference is a hole.
+     */
+    resolveTableReference?(reference: StructuredReference, row: number): IRange.FixableCoords | FormulaError.Known;
+}
+/**
+ * A block as the model reads it: the engine's record imaged against the reader's own symbols
+ * (DESIGN-CALC-SERVICE §8).
+ *
+ * @remarks
+ * What the facade hands the model for every block the engine vends. The record is plain data and
+ * crosses the channel; the imager is the facade's and never does. Text is the same function of
+ * (tokens, symbols, anchor, locale) the compiled block images by - only where it runs differs -
+ * so what a sheet reads is what the engine would image, by the model's names.
+ */
+export declare class FormulaRecordView implements IFormulaBlockView {
+    /** The block as data: what this view images. */
+    readonly record: FormulaRecord;
+    private readonly _imager;
+    private _error;
+    constructor(record: FormulaRecord, imager: FormulaImager);
+    /**
+     * {@inheritDoc IFormulaBlockView.getTextAt}
+     *
+     * @remarks
+     * A record that did not parse has no faithful tokens and answers with the text as written.
+     */
+    getTextAt(row: number, column: number, r1c1?: boolean, evalIndex?: number, target?: ICalculation.FormulaTarget): string;
+    /** {@inheritDoc IFormulaBlockView.getTokensAt} */
+    getTokensAt(row: number, column: number, evalIndex?: number): ICalculation.FormulaToken[];
+    /** {@inheritDoc IFormulaBlockView.isReferenceOnly} */
+    isReferenceOnly(): boolean;
+    /** {@inheritDoc IFormulaBlockView.getError} */
+    getError(): FormulaError.Parse | null;
+    /**
+     * {@inheritDoc IFormulaBlockView.getReferencesAt}
+     *
+     * @remarks
+     * From the record's references: a name is spelled by the model's symbols, a table reference is
+     * resolved against the model's table.
+     */
+    getReferencesAt(row: number, column: number): ReferenceCoords[];
+    get [Symbol.toStringTag](): string;
+}
+/**
+ * The tokens of the subtree evaluated at `evalIndex`, from the flat token list alone.
+ *
+ * @remarks
+ * A subtree's tokens are contiguous, and its nodes are indexed after the node they hang from:
+ * so the subtree is the widest run around the node's own tokens in which every token's index is
+ * the node's or greater. A token of the enclosing node - the operator or separator between two
+ * siblings, the parenthesis around an argument list - carries the smaller index that bounds it.
+ * Whitespace at either end is not part of the expression, and whitespace alone never places a
+ * node: the cells of a range carry the range's index, and the whitespace after one may carry
+ * the cell's own, which no consumer holding tokens can ask for.
+ */
+export declare function subtreeTokens(tokens: readonly ICalculation.FormulaToken[], evalIndex: number): ICalculation.FormulaToken[];
+//# sourceMappingURL=FormulaRecordView.d.ts.map