@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

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

@@ -0,0 +1,80 @@
+/**
+ * The clone boundary: a test mode that treats the model/engine crossing as if it were a wire
+ * (DESIGN-CALC-SERVICE §11, goal G1, plan step 6).
+ *
+ * @remarks
+ * Every request into a grid and every {@link ICalcGrid.Results} out of one passes through here.
+ * With the mode `off` - always, outside a test - it is an identity call and costs nothing.
+ *
+ * Two things it finds, and they are different:
+ *
+ * - What a walk can see: a function, a class instance, a value `structuredClone` refuses or
+ *   silently downgrades. Each is recorded as a {@link Violation} with the PATH it sat at, which
+ *   is the point: a payload that degrades silently fails somewhere else entirely, and the path
+ *   is what names the field to convert.
+ * - What only running can see: a reference the two sides SHARE. A walk cannot tell a run array
+ *   the sheet also holds from one minted for the message; a clone does, because the sides stop
+ *   agreeing. That is what `clone` mode is for, and why `audit` alone is not the exit criterion.
+ *
+ * Not a boundary for READS. `getValues`, `getFormulas`, `getSnapshot` and the graph walks answer
+ * synchronously out of engine objects; making them push or await is §11's list, not this one.
+ * This covers what is already message-shaped.
+ *
+ * @internal Test-mode only. Deliberately not exported from the barrel.
+ */
+export declare namespace CloneBoundary {
+    /**
+     * `off` is the default and the only mode outside a test.
+     *
+     * `audit` records what would not survive the crossing and passes the ORIGINAL through, so a
+     * suite stays green and the run produces the list. `clone` substitutes the
+     * `structuredClone` - the real wire - and is the exit criterion for "ready for a worker".
+     */
+    type Mode = 'off' | 'audit' | 'clone';
+    /** What a value at a path does to a `structuredClone`. */
+    type ViolationKind = 
+    /** A function or a symbol: `structuredClone` throws. */
+    'function'
+    /** A class instance: cloned as a plain object, its methods gone, and nothing says so. */
+     | 'live'
+    /** An `Error` subclass: clones to a bare `Error` - the subclass and its own fields are lost. */
+     | 'downgraded';
+    interface Violation {
+        /** Which crossing: `'request:setInputs'`, `'results:onCalculated'`, ... */
+        where: string;
+        /** Where in the payload, with array indices collapsed: `results.formulaInserts[].value`. */
+        path: string;
+        kind: ViolationKind;
+        /** The constructor name, or `'function'` / `'symbol'`. */
+        type: string;
+    }
+    /** Thrown by `clone` mode when the payload cannot be cloned at all. */
+    class BoundaryError extends Error {
+        readonly violations: readonly Violation[];
+        constructor(where: string, violations: readonly Violation[], cause: unknown);
+    }
+    /** Sets the mode. Anything but a known mode (including `undefined`) is `off`. */
+    const setMode: (mode: string | null | undefined) => void;
+    const getMode: () => Mode;
+    /**
+     * Called once per DISTINCT violation (a payload of 50000 cells reports its field once), so a
+     * host can write the run's list somewhere a test runner does not swallow.
+     */
+    const setListener: (listener: ((violation: Violation) => void) | null) => void;
+    /** Every distinct violation seen since the mode was set. */
+    const getViolations: () => readonly Violation[];
+    const clearViolations: () => void;
+    /**
+     * A request on its way to a grid.
+     *
+     * @param where The request's `type`, for the report.
+     */
+    const request: <T>(request: T, where: string) => T;
+    /**
+     * An {@link ICalcGrid.Results} on its way back: a resolution, or a record the engine pushed.
+     *
+     * @param where Which of the two, for the report.
+     */
+    const results: <T>(results: T, where: string) => T;
+}
+//# sourceMappingURL=_CloneBoundary.d.ts.map

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

@@ -0,0 +1,13 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICalculation } from './ICalculation';
+/**
+ * Re-points every structured reference that names the table `from` at the table `to`. A
+ * reference with no table name is left alone: it names the table it is written in.
+ */
+export declare function renameTableTransform(from: string, to: string): ICalculation.FormulaTransform;
+/**
+ * `text`, parsed at `at`, with its references to the table `from` re-pointed at `to`, or the text
+ * itself when it names no such table or does not parse.
+ */
+export declare function renameTableInText(text: string, at: IRange.CellCoords, from: string, to: string): string;
+//# sourceMappingURL=_TableRename.d.ts.map

package/types/src/calculation/compiler/ASTTypes.d.ts

@@ -43,6 +43,38 @@ export interface ASTNode<T extends TokenType = TokenType, V = any> {
      * @see {@link ICalculation.FormulaToken.evalIndex}
      */
     evalIndex?: number;
+    /**
+     * Compile-time: the implicit-intersection MODE this call is evaluated in — `true` VALUE mode
+     * (a multi-cell reference at a single-value slot intersects with the formula cell), `false`
+     * ARRAY mode (it reads its first cell). Set on `Function` and `Call` nodes by
+     * `CompilerUtils.annotateImplicitIntersect` (DESIGN-IMPLICIT-INTERSECTION §2).
+     */
+    implicitIntersect?: boolean;
+    /**
+     * Compile-time: under a first-cell DEMAND (a block whose every cell is its own 1x1 array-entered
+     * extent — a conditional-format body), only element `[0,0]` of this node's result is ever read,
+     * so a lift or an operator here builds that one element. Set on every node reachable from the
+     * root through elementwise positions by `CompilerUtils.annotateFirstCell`
+     * (DESIGN-LIFT-AND-DEMAND §2); inert unless the block evaluating the formula demands it.
+     */
+    firstCell?: boolean;
+    /**
+     * Compile-time: this `+`/`-` is the root of a formula body — the formula's own root or a
+     * `LAMBDA`'s body — so a cancelling result snaps to 0 (`Operators.RootInfix`). Set by
+     * `CompilerUtils.compileAST`.
+     */
+    snapsCancellation?: boolean;
+    /**
+     * The ROOT only: the formula came from a LEGACY cell, so `annotateImplicitIntersect` gives its
+     * WHOLE tree value mode instead of deriving a mode per node. Carried in from the reader's
+     * transform (`ICalculation.FormulaNode.legacyIntersect`); never persisted.
+     */
+    legacyIntersect?: boolean;
+    /**
+     * Compile-time memo: whether this expression is statically array-valued (a range, an array
+     * literal, an array-returning call, an operator over one). Read by the mode annotation.
+     */
+    arrayValued?: boolean;
     /**
      * For live editing. We may need to add original start/end offsets to align?
      *
@@ -91,6 +123,13 @@ export interface ASTNode<T extends TokenType = TokenType, V = any> {
      * converts the sentinel to blank.
      */
     rawFrameRead?: boolean;
+    /**
+     * Set by the binder pass on an `IF`/`IFERROR`/`IFNA` call whose answer can reach `ISOMITTED`
+     * — its direct argument, a `LET` binding's value, or such a call's own argument. The call
+     * passes an EMPTY argument on as the OMITTED sentinel (`ISOMITTED(IF(TRUE,))` is TRUE), where
+     * an unstamped call reads it as blank.
+     */
+    passOmitted?: boolean;
     /**
      * Set by the compiler on a `named` node INSIDE a `LAMBDA` body: resolved at apply time, not in
      * the eager reference pass.
@@ -102,6 +141,38 @@ export interface ASTNode<T extends TokenType = TokenType, V = any> {
      * accepted cost — design §3.4); only the eager VALUE resolution is skipped.
      */
     deferredResolve?: boolean;
+    /**
+     * Set by the compiler on an argument node that binds to a `Lazy` parameter: the ENGINE hands the
+     * body a handle over this subtree instead of its value.
+     *
+     * @remarks
+     * The subtree is absent from the eager execution list (the same carve-out a `LAMBDA` body gets)
+     * and is evaluated only if the call's answer turns out to be the handle. An `Empty` argument is
+     * never marked — an omitted comma is a value the caller supplied, and it marshals as one.
+     */
+    lazyArg?: boolean;
+    /**
+     * Set by the compiler on every node WITHIN a lazy argument's subtree, the root included. What
+     * the execution-list carve-out reads.
+     */
+    inLazy?: boolean;
+    /**
+     * Set by the compiler on a call node that has at least one {@link lazyArg} — so the hot argument
+     * loop pays one boolean for a feature almost no call uses.
+     */
+    hasLazyArgs?: boolean;
+    /**
+     * Set by the compiler on the ROOT of a deferred subtree — a `LAMBDA` body or a {@link lazyArg} —
+     * to the post-order execution list of that subtree, the root included: the same shape as
+     * `CompiledFormula.executions`, for the piece of the formula the eager pass leaves out.
+     *
+     * @remarks
+     * A nested root's nodes are on the nested list, not this one (its root node is here, and
+     * evaluating it closes over or defers what is underneath). A bound name executes wherever it
+     * sits; an unbound name (`deferredResolve`) is on the list too, since the eager reference pass
+     * skips it and resolving it is what the deferral is for.
+     */
+    deferred?: ASTNode[];
     /**
      * If ast had an error.
      *

package/types/src/calculation/compiler/CompilerUtils.d.ts

@@ -1,6 +1,6 @@
 import { FormulaError, IFunction, IRuntime } from '@sheetxl/primitives';
 import { ICalculation } from '../ICalculation';
-import { ISymbolRegistry } from '../symbol';
+import { ISymbolRegistry, SheetCtx } from '../symbol';
 import { TokenType } from '../TokenType';
 import { CompiledFormula, ParseError } from './Types';
 import { ASTNode } from './ASTTypes';
@@ -62,6 +62,30 @@ export declare function normalizeStructuredRefs(ast: ASTNode): ASTNode;
  * @returns A new AST (structurally shared where unchanged).
  */
 export declare function rewriteThisRowToAt(ast: ASTNode): ASTNode;
+/**
+ * Collapses a table reference with EMPTY brackets to the bare table name: `Table1[]` → `Table1`.
+ *
+ * @remarks
+ * Both are the data body. Excel accepts either on entry and shows the bare name; on disk it writes
+ * `Table1[]`, which is io-xlsx's spelling. Commit-path only, the boundary {@link rewriteThisRowToAt}
+ * observes. A reference with no table name (`[]`) and an unterminated one are left alone.
+ *
+ * @returns A new AST (structurally shared where unchanged).
+ */
+export declare function collapseEmptyStructuredRefs(ast: ASTNode): ASTNode;
+/**
+ * Gives an unqualified structured reference (`[@Qty]`, `[#All]`) its table name: `Table1[@Qty]`.
+ *
+ * @remarks
+ * Linking already bound it to the table at the formula's cell; this drops the typed image that kept
+ * the name out of the text. Every reference is stored qualified, as Excel writes it. Which ones show
+ * without the name is decided at display time, from where the formula sits.
+ *
+ * Commit-path only, the boundary {@link rewriteThisRowToAt} observes: an editor keeps what was typed.
+ *
+ * @returns A new AST (structurally shared where unchanged).
+ */
+export declare function qualifyStructuredRefs(ast: ASTNode): ASTNode;
 /**
  * Sorts the items inside every `TableReference` into Excel's canonical order — section specifiers
  * in band order (`#All` | `#Headers`, `#Data`, `#Totals`), then the column selector.
@@ -81,6 +105,55 @@ export declare function rewriteThisRowToAt(ast: ASTNode): ASTNode;
  * @returns A new AST (structurally shared where unchanged).
  */
 export declare function reorderStructuredRefItems(ast: ASTNode): ASTNode;
+/**
+ * Annotates every call node with its implicit-intersection MODE (DESIGN-IMPLICIT-INTERSECTION §2,
+ * measured on Excel 16.0 by `probe-ii-propagation{,2,3}.ps1`): `true` is VALUE mode, where a
+ * multi-cell reference at a single-value slot intersects with the formula cell; `false` is ARRAY
+ * mode, where it reads its first cell. The mode is INHERITED — a call evaluates its arguments in
+ * the mode it was given — and set at four places only:
+ *
+ * - the root: array mode when the root expression is statically array-valued (`=LINEST(..)`,
+ *   `=TRANSPOSE(..)`, `=A1:A3+0`), value mode when it is scalar (`=SUM(..)`, `=INDEX(..,1,1)`);
+ * - an operand of an operator, or the argument at a lifting scalar slot, when that operand is
+ *   array-valued (the lift needs the whole array);
+ * - a `LAMBDA` body, always;
+ * - an array-entered block, at evaluation (`CalculationContext.isImplicitIntersect`).
+ *
+ * A LEGACY (pre-dynamic-array) formula skips all four: its WHOLE tree is value mode, which is the
+ * era's own regime (DESIGN-IMPLICIT-INTERSECTION §2, `probe-ii-propagation3.ps1` §I —
+ * `=SUM(LINEST(y,x,ref)+0)` intersects in a legacy cell where the operator would otherwise give
+ * the call array mode). It changes the answer for the LINEST family's logical slots ALONE: every
+ * other legacy site Excel spells with an `@`, which the reader's transform has already inserted,
+ * and the two slots that take no `@` either read their first cell in both eras (`N`, `T`) or
+ * intersect in both (`AGGREGATE`'s `k`).
+ *
+ * "Array-valued" is static: a range or array literal, a call whose declared return is an array or
+ * a reference, an operator over one, a pass-through (`IF`, `IFERROR`, …) over one, `INDEX` with a
+ * zero, empty or array index, a name or a lambda application (unknown, so array — what Excel does
+ * at the root). The two runtime refinements Excel makes (`INDEX` on a CELL holding 0, and a
+ * defined name taking the mode of its reference site) are not modelled here.
+ */
+export declare function annotateImplicitIntersect(root: ASTNode, getFunction: ((name: string) => IFunction | null) | null | undefined, legacy?: boolean): void;
+/**
+ * Annotates the nodes whose result is read only at element `[0,0]` when the formula is evaluated
+ * under a first-cell demand (DESIGN-LIFT-AND-DEMAND §2, PLAN-CF-BODY-DEMAND step 3): the body of a
+ * block whose every cell is its own 1x1 array-entered extent, which is how Excel evaluates a
+ * conditional-format formula.
+ *
+ * @remarks
+ * The demand starts at the root and is INHERITED through elementwise positions only — an operator
+ * that is not a reference operator, a one-element paren, a lifting scalar slot, an `any` slot
+ * (`IF`/`IFS`/`SWITCH`/`CHOOSE` arms, which size and sample in the lift), a `LET` body. At each of
+ * those `[0,0]` of the output depends only on `[0,0]` of each operand, and `(0,0)` is never a pad,
+ * so computing one element is computing `[0,0]`. It stops (`false`) at every other position: a
+ * range, array, reference-only, lambda or flattened slot takes its argument whole (`SUM` still sees
+ * the array), and so do a reference operator, `@`, a name, a lambda body and a `LET` binding (a
+ * binding may be read under an aggregate).
+ *
+ * Idempotent and a property of the tree alone, so a compiled formula shared by several blocks
+ * carries it harmlessly: nothing reads it unless the block evaluating the formula demands it.
+ */
+export declare function annotateFirstCell(root: ASTNode, getFunction: ((name: string) => IFunction | null) | null | undefined): void;
 export declare function compileAST(runtime: IRuntime, symbols: ISymbolRegistry | undefined, original: ASTNode, preserveExpression?: boolean, error?: ParseError | null, getFunction?: ((name: string) => IFunction | null) | null): CompiledFormula;
 /**
  * Convert a chevrotain error into a {@link FormulaError.Parse}.
@@ -279,35 +352,52 @@ export declare const findInvalidCallee: (root: ASTNode, getFunction: ((name: str
  */
 export declare function rewriteUnknownFunctionCalls(root: ASTNode, getFunction: ((name: string) => IFunction | null) | null): ASTNode;
 /**
- * Annotates the `LET`/`LAMBDA` scopes in a parsed AST: each declaration position is marked a
- * BINDER and every use its scope covers is bound to that binder's slot.
+ * `bound` with `name` added last — an inner declaration replaces an outer one spelled the same
+ * (case-insensitively). Builds {@link ICalculation.FormulaTokenContext.bound}.
+ */
+export declare function appendBound(bound: readonly ICalculation.BoundName[] | undefined, entry: ICalculation.BoundName): readonly ICalculation.BoundName[];
+/**
+ * The declarations of a literal `LAMBDA(…)` node, as {@link ICalculation.BoundName.params}, or
+ * `undefined` for any other node.
+ */
+export declare function lambdaParamsOf(node: ASTNode | undefined): ICalculation.BoundName['params'];
+export declare function bindScopes(root: ASTNode, getFunction?: ((name: string) => IFunction | null) | null): ASTNode;
+/**
+ * Re-reads every REFERENCE token in the formula as a NAME, when any `LET`/`LAMBDA` declaration
+ * position is a cell reference.
  *
- * @param root The parsed AST (post read-transform, pre {@link linkSymbols}).
+ * @param root The parsed AST.
  * @param getFunction Resolves a function name to its declaration; see {@link _binderKind}.
- * @returns A new root, or the SAME root when nothing is bound (copy-on-write).
+ * @returns A new root, the SAME root when no declaration is reference-shaped, or a MESSAGE when
+ * the formula has to be refused at entry.
  *
  * @remarks
- * **Runs before {@link linkSymbols}, and that is the point.** A bound node is claimed here, so no
- * `NamedFormula` symbol is minted for it, no dependency edge is drawn, and no dead id is left
- * behind: a parameter is not a name. The node stays a `named` node — the public lite view (and so
- * io-xlsx's `_xlpm.` spelling) is unchanged — but it stops being a REFERENCE and reads its value
- * from its binding rather than from the resolver.
- *
- * Declaration positions are purely syntactic, the same rule io-xlsx's `_prefixScopeParameters`
- * proved on the lite tree:
- * - `LAMBDA` — every argument except the last declares; the last is the body.
- * - `LET` — the even-indexed arguments except the last declare, the odd ones are their values, and
- *   the last is the body.
- *
- * Binding ORDER is the one rule the shape does not give away, and it is measured: a `LET` name is
- * in scope only from the argument AFTER its own value, so the same spelling in an earlier one is
- * the outer / defined name — `LET(zz,zz,zz)` binds only the third `zz`.
- *
- * Shadowing needs no special case: the environment is a stack and a use takes the INNERMOST
- * binding, so an inner scope's name wins over an outer one's, and a parameter wins over a defined
- * name (it never reaches the resolver at all).
+ * `LET(A1,7,A1)` is 7 in Excel, and the consequence is far wider than the name that caused it:
+ * ONE reference-shaped declaration anywhere in a formula stops EVERY A1-style token in that
+ * formula from reading as a cell. It is not a scope rule and not a shadow — the switch covers the
+ * whole formula text, measured in every direction (probe-let-ref-names.ps1):
+ *
+ * | formula | Excel |
+ * | --- | --- |
+ * | `LET(BA1,7,BA1)` | 7 — the declaration resolves |
+ * | `LET(BA1,7,BA2)` | `#NAME?` — a token bound nowhere no longer names a cell |
+ * | `LET(BA1,BA2,BA1)` | `#NAME?` — the declaration's OWN value expression is included |
+ * | `BA2+LET(BA1,7,BA1)` | `#NAME?` — so is text BEFORE the `LET`, outside it |
+ * | `LET(BA1,7,BA1)+LET(q,1,q+BA2)` | `#NAME?` — and an unrelated SIBLING scope |
+ * | `LET(BA1,7,BA2,9,BA1+BA2)` | 16 — two declarations, both resolving |
+ * | `LET(BA1,7,BA2,9,SUM(BA1:BA2))` | `#VALUE!` — `7:9`, the range OPERATOR over two values |
+ *
+ * Excel refuses to create a defined name that looks like a cell reference, so a re-read token can
+ * only resolve to a `LET`/`LAMBDA` declaration; everything else is `#NAME?`, which is what the
+ * ordinary resolver answers once the node is a name. That is why this pass has no resolution of
+ * its own — it changes what the tokens ARE and lets `bindScopes` and the resolver do the rest.
+ *
+ * The one entry refusal is `$`: a name cannot contain one, so under the switch any `$` in an
+ * A1-style token makes the formula untypeable — in a declaration or in a use, on one axis or both
+ * (`LET(BA1,7,BA1+$BA$2)`, `LET(BA1,7,BA1+BA$2)`, `LET($BA$1,7,$BA$1)`;
+ * probe-let-ref-names2.ps1 §B).
  */
-export declare function bindScopes(root: ASTNode, getFunction?: ((name: string) => IFunction | null) | null): ASTNode;
+export declare const retypeReferenceBinders: (root: ASTNode, getFunction?: ((name: string) => IFunction | null) | null) => ASTNode | string;
 /**
  * Finds a malformed `LET`/`LAMBDA` scope — a shape Excel refuses at ENTRY.
  *
@@ -318,29 +408,30 @@ export declare function bindScopes(root: ASTNode, getFunction?: ((name: string)
  * @remarks
  * Same channel and same reason as {@link findArityViolation}: Excel decides these before the
  * formula can exist, so we do too — a refused shape is a parse error, not a cell that evaluates to
- * something. Read from the shipping Excel Online analyzer
- * (`d:/dev/excel-calc-ref/excelOnlineCalc.min.js`, `applySpecificWorksheetFunctionChecks`), which
- * reports `Duplicate_binder` / `Invalid_binder` / `Missing_binder` per declaration and
- * `Insufficient_function_arguments` with `numArgsExpected: max(3, n + 1 + n % 2)` for `LET` — the
- * `n % 2` term being exactly the even-argument-count refusal.
- *
- * Duplicates compare case-INSENSITIVELY (Excel keys them in a `stringCompareCI` map), the same
- * normalization a name comparison gets everywhere else.
+ * something. Excel refuses a duplicate, invalid or missing binder per declaration, and a `LET`
+ * with too few arguments — at least `max(3, n + 1 + n % 2)` for `n` arguments, the `n % 2` term
+ * being exactly the even-argument-count refusal.
+ *
+ * Duplicates compare case-INSENSITIVELY, the same normalization a name comparison gets everywhere
+ * else.
  */
 export declare const findBinderViolation: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => string | null;
+export declare function linkSymbols(ast: ASTNode, symbols: ISymbolRegistry, scope?: string | null, sheetCtx?: SheetCtx, home?: {
+    rowIndex: number;
+    colIndex: number;
+} | null): ASTNode;
 /**
- * Visits the AST and links display names to stable IDs using the symbol registry.
- *
- * @param ast The root AST node to start the traversal.
- * @param symbols The symbol registry used to resolve display names to stable IDs.
- * @param scope The sheet this formula is written on, or `null`/omitted when there is none.
- *   Only defined names need it, and only because they can be sheet-scoped: `MonthName` on January
- *   and the same text on February are two different names when each sheet defines its own, so the
- *   vantage is part of the question. Without it every reference binds to whichever definition
- *   happened to win globally.
- * @returns The updated AST with linked symbols.
+ * The first structured reference Excel refuses at entry, after {@link linkSymbols}: an unqualified one
+ * (`[@Qty]`) whose formula is not in a table or whose table has no such column, and a qualified one
+ * naming a table that does not exist (`Nope[Qty]`) or a column its table does not have
+ * (`Table1[Nope]`).
+ *
+ * @remarks
+ * A bare name (`=Nope`) is not a structured reference and is not refused: it is `#NAME?`.
+ *
+ * @returns A message, or `null` when every structured reference names its table's columns.
  */
-export declare function linkSymbols(ast: ASTNode, symbols: ISymbolRegistry, scope?: string | null): ASTNode;
+export declare function findUnboundTableReference(ast: ASTNode, symbols?: ISymbolRegistry): string | null;
 /**
  * Returns a new AST with every relative Cell node's coordinates shifted by (rowDelta, colDelta),
  * wrapping out-of-bounds results within [0, max) (Excel behavioral).

package/types/src/calculation/compiler/FormulaCompiler.d.ts

@@ -1,5 +1,5 @@
 import { IFunction, IRuntime } from '@sheetxl/primitives';
-import { ISymbolRegistry } from '../symbol';
+import { ISymbolRegistry, SheetCtx } from '../symbol';
 import { ICalculation } from '../ICalculation';
 import { IFormulaCompiler, CompiledFormula } from './Types';
 import { FormulaParseOptions } from './FormulaParser';
@@ -37,13 +37,16 @@ export declare class FormulaCompiler implements IFormulaCompiler {
     private readonly _editing;
     constructor(options?: FormulaCompilerOptions);
     /** @inheritdoc IFormulaCompiler.compile */
-    compile(runtime: IRuntime, rowIndex: number, colIndex: number, expression: string, symbols?: ISymbolRegistry, getFunction?: ((name: string) => IFunction | null) | null, scope?: string | null, formulaTransform?: ICalculation.FormulaTransform): CompiledFormula;
+    compile(runtime: IRuntime, rowIndex: number, colIndex: number, expression: string, symbols?: ISymbolRegistry, getFunction?: ((name: string) => IFunction | null) | null, scope?: string | null, legacyIntersect?: boolean, sheetCtx?: SheetCtx): CompiledFormula;
     /** @inheritdoc IFormulaCompiler.autoCorrect */
     autoCorrect(expression: string): string | null;
     /**
      * The zero-recovery parse-failure result: a compiled formula whose only token is the raw expression
      * as `unparsed`, evaluating to the parse error. Nothing is lost (the text round-trips), nothing is
      * spent — this is the calc profile's entire failure path, and editing's last resort.
+     *
+     * `partialTable` (editing only): an expression that is nothing but a structured reference being
+     * typed (`[@Co`) still gets its table tokens — no prefix parses, so recovery never reaches it.
      */
     private _compileUnparsed;
     /**
@@ -61,9 +64,31 @@ export declare class FormulaCompiler implements IFormulaCompiler {
      * Append the un-parseable `tail` to `tokens` as `unparsed` token(s): stamp the enclosing function
      * context (from the last token that has one) so a caret in the tail still resolves to the right
      * function + argument, and split off a trailing identifier run (`[A-Za-z_][A-Za-z0-9_]*` at a token
-     * boundary, not glued to a preceding digit like `12abc`) as its own `isLookup` token, so a partial
-     * name being typed can still drive autocomplete.
+     * boundary, not glued to a preceding digit like `12abc`) as its own `named` token — what it would
+     * parse as once the rest of the formula does — so a partial name being typed can still drive
+     * autocomplete.
+     *
+     * A tail ending inside a structured reference's brackets (`Sales[Co`) becomes that reference's
+     * tokens instead — see {@link appendPartialStructuredReference}.
      */
     private _appendUnparsedTail;
 }
+/**
+ * Append a structured reference still being typed at the end of `tail` — `Sales[`, `Sales[Co`,
+ * `Sales[#Da`, `Sales[[#This Row],[Co`, `[@Co` — as the tokens it will be once it closes, in the shape
+ * `generateFormulaTokens` gives a complete one: a `tableReference` for the name, `paren` tokens for every
+ * bracket, and a `tableColumn` / `tableSpecifier` per part whose value is an
+ * {@link ICalculation.TablePartRef} naming the table (`''` when unqualified).
+ *
+ * The unfinished part is marked `partial` with what may finish it, and a part not yet started — right
+ * after the `[` or `@` that opened it — is an empty token, so an editor completes from the tokens alone.
+ *
+ * The name may already sit in `tokens` as the `named` token the parsed prefix ended with; it is
+ * re-typed in place. Anything in `tail` before the reference is one `unparsed` token.
+ *
+ * @returns `false`, with `tokens` untouched, when the tail does not end inside a structured reference.
+ */
+export declare function appendPartialStructuredReference(tokens: ICalculation.FormulaToken[], tail: string, context: ICalculation.FormulaTokenContext | undefined, 
+/** The display name of the table at the formula's cell, which an unqualified reference names. */
+homeTable?: () => string | undefined): boolean;
 //# sourceMappingURL=FormulaCompiler.d.ts.map

package/types/src/calculation/compiler/FormulaParser.d.ts

@@ -4,7 +4,6 @@ import { ASTNode, ParseResult } from './ASTTypes';
 import { FormulaLexer, FormulaLexerOptions } from './FormulaLexer';
 import { CompilerLocale } from './CompilerLocale';
 import { SRParser } from './SRParser';
-import { ICalculation } from '../ICalculation';
 declare module 'chevrotain' {
     interface EmbeddedActionsParser {
         getLexerPosition(): number;
@@ -80,7 +79,7 @@ export declare class FormulaParser extends EmbeddedActionsParser {
      * none, so `=_xlfn.SUM(A1)` typed is an unknown name, as in Excel. Runs where the hardcoded
      * legacy visit used to run — no extra parse.
      */
-    parse(rowIndex: number, colIndex: number, expression: string, formulaTransform?: ICalculation.FormulaTransform): ParseResult;
+    parse(rowIndex: number, colIndex: number, expression: string): ParseResult;
     /**
      * Parses a flat sequence of infix-operator / operand pairs, then folds them into a
      * left-associative AST using the precedence table in `ParserUtils.binaryOperatorsPrecedence`.

package/types/src/calculation/compiler/LiteTransform.d.ts

@@ -1,6 +1,13 @@
 import { ICalculation } from '../ICalculation';
 import { ISymbolRegistry } from '../symbol';
 import { ASTNode } from './ASTTypes';
+/**
+ * The public node view of an internal AST — what {@link ICalculation.IFormula.getNode} answers.
+ *
+ * @param root The internal AST root.
+ * @param symbols The registry the AST was linked against.
+ */
+export declare function toFormulaNode(root: ASTNode, symbols: ISymbolRegistry | null | undefined): ICalculation.FormulaNode;
 /**
  * Applies a public {@link ICalculation.FormulaTransform} to an internal AST.
  *
@@ -12,4 +19,14 @@ import { ASTNode } from './ASTTypes';
  * that identity to skip recompilation.
  */
 export declare function applyTransformToAST(root: ASTNode, transform: ICalculation.FormulaTransform, symbols?: ISymbolRegistry | null): ASTNode;
+/**
+ * Walks a lite tree with a transform, post-order, and returns the transformed root: the SAME
+ * object when nothing changed.
+ */
+export declare function transformFormulaNode(root: ICalculation.FormulaNode, transform: ICalculation.FormulaTransform): ICalculation.FormulaNode;
+/**
+ * Rebuilds an AST from a lite tree: nodes a transform left alone come back as the AST nodes they
+ * were made from, replacements are built fresh.
+ */
+export declare function fromFormulaNode(root: ICalculation.FormulaNode): ASTNode;
 //# sourceMappingURL=LiteTransform.d.ts.map

package/types/src/calculation/compiler/ParserUtils.d.ts

@@ -1,4 +1,5 @@
 import { FormulaError, IRange } from '@sheetxl/primitives';
+import { ICalculation } from '../ICalculation';
 import { CompilerLocale } from './CompilerLocale';
 import { ASTNode, ASTVisitor, CellNode, FunctionNode } from './ASTTypes';
 /**
@@ -49,6 +50,21 @@ export declare function createTableReference(value: string, inputs: any[]): ASTN
  * word → canonical. Display re-imaging (`tokensToString`) re-localizes for a localized target.
  */
 export declare function createTableSpecifier(image: string, locale?: CompilerLocale): ASTNode;
+/**
+ * A column name as a structured reference spells it: a `'` before each `[`, `]`, `#` and `'`,
+ * which is Excel's escape inside a column specifier. Without it a name holding a bracket cannot be
+ * referenced at all — the bracket would close the reference.
+ */
+export declare function escapeColumnName(name: string): string;
+/**
+ * The column name a specifier spells — the inverse of {@link escapeColumnName}.
+ *
+ * @remarks
+ * A `'` before anything else is a literal `'`, not a dangling escape: `#` and `'` were referenced
+ * unescaped long before the escape was read, and text written then still has to name the same
+ * column (`[Q#1]` and `[Q'#1]` are both `Q#1`).
+ */
+export declare function unescapeColumnName(image: string): string;
 export declare function createTableColumn(image: string): ASTNode;
 export declare function createInfix(operator: string, left: ASTNode, right: ASTNode, isReference?: boolean): ASTNode;
 export declare function createPostfix(operator: string, input: ASTNode | null | undefined, isReference?: boolean): ASTNode;
@@ -108,11 +124,20 @@ export declare function createRefError(image?: string, locale?: CompilerLocale,
 export declare function createNameError(): ASTNode;
 /**
  * The plain error behind an `error` node/token value, whichever shape it is: an error REFERENCE
- * carries an {@link ICalculation.ErrorRef} (qualifier and all), an error LITERAL the bare
+ * carries an {@link ErrorReference} (qualifier and all), an error LITERAL the bare
  * {@link FormulaError}. Evaluation and precedent resolution want the error itself either way — an
  * `ErrorRef` never escapes the reference layer into a cell value.
  */
 export declare function errorOfValue(value: unknown): FormulaError.Known;
+/**
+ * An `error` node's value as its TOKEN carries it: the error's canonical label for a literal, an
+ * {@link ICalculation.ErrorRef} for a reference. Plain data either way.
+ */
+export declare function errorTokenValue(value: unknown): string | ICalculation.ErrorRef | undefined;
+/**
+ * The error an `error` TOKEN names, from the label it carries ({@link errorTokenValue}).
+ */
+export declare function errorOfTokenValue(value: unknown): FormulaError.Known | undefined;
 /**
  * Does an error token's `text` already carry its sheet qualifier (`Data!#REF!`)?
  *

package/types/src/calculation/compiler/SRParser.d.ts

@@ -29,9 +29,10 @@ export declare class SRParser extends EmbeddedActionsParser {
     /**
      * Parses a complete structured reference and returns a ParseResult.
      *
-     * Accepts the full token image in either form:
+     * Accepts the full token image in any of three forms:
      *   '[Column1]'                 — no table name (BracketedString token)
      *   'Table1[#Headers,[Col1]]'   — with table name (TableReference token)
+     *   '[1]!Table1[Col1]'          — with an EXTERNAL book prefix, which belongs to the table NAME
      */
     parse(rowIndex: number, colIndex: number, expression: string): ParseResult;
 }