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

package/types/src/calculation/engine/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The calculation backend's code: what a started engine builds and runs.
+ *
+ * @remarks
+ * `Calculation` reaches every value here through this one module and nothing else, so the facade a
+ * workbook constructs carries none of it (DESIGN-CALC-SERVICE §5, §13.25). Types are imported
+ * directly; only values belong on this list.
+ */
+export { CalcBackend } from './CalcBackend';
+//# sourceMappingURL=index.d.ts.map

package/types/src/calculation/executor/CalcExecutor.d.ts

@@ -338,6 +338,17 @@ export declare class CalcExecutor {
      * cell stores a scalar and registers no spill. Anything else as it is.
      */
     private _fitCell;
+    /**
+     * Whether a representative that read its position answers the same wherever it sits in the
+     * blank region: every variant of its formula ({@link IFormulaBlock.getPositionVariants}) answers
+     * `finalized` at its cell without reading the position, or anything else per cell.
+     *
+     * @remarks
+     * Each position test is `TRUE` or `FALSE` at every cell, so the variants cover every answer the
+     * region can give. A variant reads only what the formula itself read (no lazy argument, so no
+     * arm it skipped), all of it final by now, so it is evaluated without the pass's read hook.
+     */
+    private _isPositionFree;
     /**
      * The representative of a gated block has finalized (PLAN-WATCHES-BLANK-AWARE §4): its scalar is
      * shared with the block's blank region, or the gate is closed and the region is re-collected
@@ -345,8 +356,9 @@ export declare class CalcExecutor {
      *
      * @remarks
      * Shared only when nothing the evaluation read was per cell (`CalcScope.perCellRead`: a draw, a
-     * position, a computed reference), the result is a scalar, and the node ran on its own - not a
-     * promise, not pending on one, not in a cycle. A per-cell read is a fact of the formula and
+     * computed reference; a position unless {@link _isPositionFree} rules it out), the result is a
+     * scalar, and the node ran on its own - not a promise, not pending on one, not in a cycle. A
+     * per-cell read is a fact of the formula and
      * closes the gate for good ({@link FormulaSpatialValue.blankRefused}); the rest may not recur
      * and close it for this pass ({@link _fallbackBlank}).
      *
@@ -391,6 +403,13 @@ export declare class CalcExecutor {
      * reaches every cell, so the nodes go dense ({@link FormulaSpatialValue.densify}) rather than
      * being minted one by one through the sparse store.
      */
+    /**
+     * The representative's answer depends on the position, in a grid whose owner reads it a tile at
+     * a time (`CalcGridBackend.ConstructorOptions.paged`): the block keeps its sparse store and
+     * evaluates its blank region only inside the owner's tiles ({@link FormulaSpatialValue.blankPaged}),
+     * and what the rest of the region holds is cleared.
+     */
+    private _pageBlank;
     private _fallbackBlank;
     /**
      * What the pass reads for `node` right now — a member's starting value, before any demand

package/types/src/calculation/executor/CalcExecutorUtils.d.ts

@@ -39,6 +39,12 @@ export declare class DownstreamSignal extends CalcSignal {
     constructor(node: CalcNode);
 }
 export declare function rangeToTuples(range: IRange, offsetMajor?: number, offsetMinor?: number): Tuple.Region<Scalar>;
+/**
+ * A finalized result as an `evaluate()` call hands it out. A range is re-packed over a grid of
+ * cell-value runs (`createCellValueRun`), so the API returns what a cell would hold; the grid write
+ * is the packing, and the result reads its grid alone. Anything else is returned as it is.
+ */
+export declare function packForReturn<T>(finalized: T): T;
 /**
  * Fits a result to a fixed (array-entered) extent, per dimension: a dimension of 1 broadcasts, a
  * longer one is clipped, a shorter one is padded with `#N/A`. Measured against Excel

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

@@ -93,6 +93,15 @@ export declare class Formula implements ICalculation.IFormula {
      * Provides a string representation of the formula.
      */
     toString(): string;
+    /**
+     * The formula text with its leading `=`, as `ICell.getFormulaText` gives it, so that
+     * logging or stringifying a formula reads as the formula.
+     *
+     * @remarks
+     * Typed `unknown` so a subclass with a persisted form of its own (`NamedFormula`) can answer
+     * with that instead.
+     */
+    toJSON(): unknown;
     /** {@inheritDoc ICalculation.IFormula.isIFormula} */
     get isIFormula(): true;
 }

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

@@ -47,6 +47,8 @@ export declare class FormulaBlock implements IFormulaBlock {
      * `null` = this block's precedents are not a pure translation.
      */
     protected _precedentTemplate: PrecedentTemplate | null | undefined;
+    /** {@link getPositionVariants}' answer, built on first ask. `undefined` = not asked yet. */
+    protected _positionVariants: FormulaBlock[] | 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);
@@ -78,10 +80,14 @@ export declare class FormulaBlock implements IFormulaBlock {
     getReferencedSymbolIds(): string[];
     /** @inheritdoc IFormulaBlock.hasTotals */
     hasTotals(): boolean;
+    /** @inheritdoc IFormulaBlock.hasVolatile */
+    hasVolatile(): boolean;
     /** @inheritdoc IFormulaBlock.isBlankCacheable */
     isBlankCacheable(arrayMode?: boolean): boolean;
     /** @inheritdoc IFormulaBlock.demandFirstCell */
     demandFirstCell(): void;
+    /** @inheritdoc IFormulaBlock.getPositionVariants */
+    getPositionVariants(): FormulaBlock[] | null;
     /** @inheritdoc IFormulaBlock.isReferenceOnly */
     isReferenceOnly(): boolean;
     /** @inheritdoc IFormulaBlock.isEquals */

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

@@ -346,6 +346,15 @@ export interface IFormulaBlock extends IFormulaBlockView {
      * either all of them call a total function or none do.
      */
     hasTotals(): boolean;
+    /**
+     * Whether the formula names a volatile function anywhere in its tree.
+     *
+     * @remarks
+     * Read straight off the compiled cache — see `CompiledFormula.hasVolatile`: the declaration of
+     * each function answers, at compile time, so a call in an arm no branch selects still counts.
+     * A name the formula mentions is not descended into; its body answers for itself.
+     */
+    hasVolatile(): boolean;
     /**
      * Whether the cells of a block running this formula whose relative inputs are all blank share
      * one value within a pass, as far as the formula TEXT can say.
@@ -365,6 +374,13 @@ export interface IFormulaBlock extends IFormulaBlockView {
      * `[0,0]` read (`CompilerUtils.annotateFirstCell`). Idempotent.
      */
     demandFirstCell(): void;
+    /**
+     * This formula with every position test (`ISODD(ROW())`, `ROW()>1`) replaced by `TRUE` and by
+     * `FALSE`, in every combination — see `CompilerUtils.positionVariants`. When all of them answer
+     * alike at a cell without reading the position, the formula's answer there does not depend on
+     * the position. `null` when there is nothing to vary. Built once.
+     */
+    getPositionVariants(): IFormulaBlock[] | null;
     /**
      * If the formula is logically equal to another formula.
      *

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

@@ -39,9 +39,11 @@ export interface LambdaParam {
  *
  * @remarks
  * CALCULATION-PRIVATE, like stable ids: nothing here reaches a public API. The one boundary rule
- * is the cell's — an unconsumed lambda renders `#CALC!` (`finalizeValue`), and every consumer that
- * needs a scalar or a location fails to COERCE it with `#VALUE!` (the `isLambda` brand is what the
- * coercion sites check, the same structural pattern as `isIRange`).
+ * is the cell's — an unconsumed lambda renders `#CALC!`, as a top-level result in `finalizeValue`
+ * and as a member of an array result where the engine's value grid makes its runs
+ * (`createCellValueRun`) — and every consumer that needs a scalar or a location fails to COERCE it
+ * with `#VALUE!` (the `isLambda` brand is what the coercion sites check, the same structural
+ * pattern as `isIRange`).
  *
  * A lambda closes over its creation context by SNAPSHOT, not by reference: `regs` is a copy of the
  * creating formula's register file at the moment the `LAMBDA` node evaluated. The copy is what

package/types/src/calculation/functions/FunctionDeclarations.d.ts

@@ -8,6 +8,9 @@ import { IFunction } from '@sheetxl/primitives';
  * range in a slot is taken whole or intersected, for one. That question has an answer before any
  * engine starts, and the same answer wherever it is asked, so it is read here rather than from a
  * calculation's live function registry. The data is the declaration the compiler compiles from.
+ *
+ * The table loads with the formula parser: await `FormulaText.load()` first. Until then every
+ * name is unknown.
  */
 export declare namespace FunctionDeclarations {
     /** A declared function. */
@@ -20,7 +23,8 @@ export declare namespace FunctionDeclarations {
         isBuiltIn(): boolean;
     }
     /**
-     * Returns a built-in function's declaration, or `null` when no built-in has that name.
+     * Returns a built-in function's declaration, or `null` when no built-in has that name or the
+     * table is not loaded.
      *
      * @param name The canonical (English) name. Not case sensitive.
      */

package/types/src/calculation/functions/expandDeclaration.d.ts

@@ -0,0 +1,15 @@
+import { IFunction } from '@sheetxl/primitives';
+import { MinifiedDeclaration } from '@sheetxl/scripting';
+/**
+ * Expands one minified built-in declaration into its JSON, with the ids of the enums its
+ * parameters use.
+ *
+ * @remarks
+ * Pure: what a declaration says about its slots, with no implementation attached. The function
+ * registry binds the result to an implementation; `FunctionDeclarations` reads it as data.
+ */
+export declare function expandDeclaration(builtInName: string, builtIn: MinifiedDeclaration, expandEnum: (id: string) => IFunction.EnumJSON | undefined): {
+    decl: IFunction.DeclarationJSON;
+    enumIds: string[];
+};
+//# sourceMappingURL=expandDeclaration.d.ts.map

package/types/src/calculation/functions/initializeFunctions.d.ts

@@ -17,18 +17,6 @@ export declare function initializeFunctions(getContext: () => IFormulaContext, p
  * @param defaultCategory the default category to use if not specified in the declaration
  * @param enums the module's enums, which its parameters reference by id
  */
-/**
- * Expands one minified built-in declaration into its JSON, with the ids of the enums its
- * parameters use.
- *
- * @remarks
- * Pure: what a declaration says about its slots, with no implementation attached. The function
- * registry binds the result to an implementation; `FunctionDeclarations` reads it as data.
- */
-export declare function expandDeclaration(builtInName: string, builtIn: MinifiedDeclaration, expandEnum: (id: string) => IFunction.EnumJSON | undefined): {
-    decl: IFunction.DeclarationJSON;
-    enumIds: string[];
-};
 export declare const bindDeclarations: (mapFunctions: Map<string, IFunction>, getContext: () => IFormulaContext, implementations: Implementations, // TODO make this dynamic
 declarations: MinifiedDeclaration, // TODO make this dynamic
 getDynamicDescriptors?: DynamicDescriptors, defaultCategory?: string, enums?: MinifiedEnums) => void;

package/types/src/calculation/grid/CalcGrid.d.ts

@@ -45,12 +45,14 @@ export declare class CalcGrid implements ICalcGrid {
     protected readonly _sizeOf: string | undefined;
     /** The aggregate cache over the values; bound to the map INSTANCE, so it follows every clone. */
     protected _rangeStats: RangeStats;
+    /** The fixed size the grid was made with, or `null` for one sized by `sizeOf` or the default. */
+    protected readonly _fixedCoords: IRange.Coords | null;
     /**
      * Bumped whenever the value map is mutated IN PLACE (a vend that landed on this grid's own
-     * instance, a load): what {@link getErrorValues} invalidates its cached view by, since the
-     * map's identity does not change then.
+     * instance, a load): what the views derived from the values invalidate by, since the map's
+     * identity does not change then. See {@link getValuesEpoch}.
      */
-    protected _errorEpoch: number;
+    protected _valuesEpoch: number;
     /** The reconciled error-VALUE view; see {@link getErrorValues}. */
     protected _errorReconciled: {
         values: ISparseGrid<Scalar>;
@@ -67,6 +69,18 @@ export declare class CalcGrid implements ICalcGrid {
     protected _emitter: ListenerEmitter<ICalcGrid, ICalcGrid.IListeners> | null;
     protected _closed: boolean;
     constructor(options: CalcGrid.ConstructorOptions);
+    /** An empty grid's state, with the aggregate cache bound to its value map. */
+    protected _freshState(): CalcGrid.State;
+    /**
+     * Gives a grid that a restore left without state - one made in a commit since undone - an empty
+     * state at the current commit again, under the same id, folded into that commit. A redo then
+     * restores the grid's own record where this front reads it; a new grid under the id would read
+     * nothing there. The engine has to be told of the grid again as well: its grids are versioned too.
+     *
+     * @returns `true` when a state was made; `false` for a grid that has one, or is closed.
+     * @internal
+     */
+    _revive(): boolean;
     /**
      * Open this grid's maps from a content record, replacing what they hold: the formulas, the
      * values, their contentful summary, the error ones among them, the array extents the record
@@ -87,6 +101,24 @@ export declare class CalcGrid implements ICalcGrid {
      * own transaction.
      */
     protected _getState(transaction?: ITransaction | null): Readonly<CalcGrid.State>;
+    /**
+     * This grid, reading the record it holds now for as long as it is kept: what a snapshot sheet
+     * reads, so a copy reads its source as it was when marked, not after the destination - which
+     * can overlap it - was cleared. A read that names a transaction still answers for it.
+     * @internal
+     */
+    _pinned(): ICalcGrid;
+    /**
+     * This grid reading the record it held at a commit: what a sheet as of that commit reads.
+     * `null` when the store no longer has the commit, or the grid did not exist at it.
+     *
+     * @remarks
+     * Sound because history is never written: a pass that lands on a record history shares lands
+     * a clone, so the record a commit kept holds the values it was calculated with.
+     * @internal
+     */
+    _pinnedAt(commitId: string): ICalcGrid | null;
+    private _pinTo;
     /**
      * This grid's record as it was at a commit; the current one for the operation in progress;
      * `undefined` for a commit the store no longer has on its live history.
@@ -112,6 +144,8 @@ export declare class CalcGrid implements ICalcGrid {
     getVolatileRegions(): IRange.Address[] | null;
     /** {@inheritDoc ICalcGrid.getRangeStats} */
     getRangeStats(): RangeStats;
+    /** {@inheritDoc ICalcGrid.getValuesEpoch} */
+    getValuesEpoch(): number;
     /** {@inheritDoc ICalcGrid.getErrorValues} */
     getErrorValues(): ISpatialMap<boolean>;
     /**
@@ -195,6 +229,8 @@ export declare class CalcGrid implements ICalcGrid {
     _isOwned(): boolean;
     /** {@inheritDoc ICalcGrid.Backend.requestPass} @internal */
     _requestPass(): void;
+    /** {@inheritDoc ICalcGrid.Backend.demand} @internal */
+    _demand(rects: readonly IRange.Coords[]): void;
     /** {@inheritDoc ICalcGrid.getGraphNeighborsAt} */
     getGraphNeighborsAt(coords: IRange.Coords, kind: 'precedents' | 'dependents', direct: boolean): Promise<ICalcGrid.GraphNeighbors>;
     /** {@inheritDoc ICalcGrid.Backend.getNameGraph} @internal */
@@ -215,7 +251,7 @@ export declare class CalcGrid implements ICalcGrid {
      * as any answer does. Nothing is written here first - the text is the engine's to make.
      * @internal
      */
-    _setBody(options: ICalcGrid.BodyOptions): Promise<ICalcGrid.Results>;
+    _setBody(options: ICalcGrid.BodyOptions, isCurrent?: () => boolean): Promise<ICalcGrid.Results>;
     /** {@inheritDoc ICalcGrid.isVolatileAt} */
     isVolatileAt(row: number, column: number): Promise<boolean>;
     /** {@inheritDoc ICalcGrid.addListeners} */

package/types/src/calculation/grid/CalcGridBackend.d.ts

@@ -61,6 +61,10 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
     readonly _shadowOf: string | null;
     /** @see CalcGridBackend.ConstructorOptions.arrayFirstCell */
     readonly _arrayFirstCell: boolean;
+    /** @see CalcGridBackend.ConstructorOptions.paged */
+    readonly _paged: boolean;
+    /** The tiles of a paged body's blank region its owner reads now: see {@link getDemanded}. */
+    protected _demanded: readonly IRange.Coords[];
     _container: IContextContainer;
     _context: IFormulaContext;
     protected _isProcessingJSON: boolean;
@@ -198,6 +202,18 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
     getShadowOf(): string | null;
     /** @inheritdoc ICalcGrid.isArrayFirstCell */
     isArrayFirstCell(): boolean;
+    /** Whether this grid's body may evaluate its blank region a tile at a time: see `ConstructorOptions.paged`. */
+    isPaged(): boolean;
+    /**
+     * The tiles of the body's blank region its owner reads now, in this grid's coordinates. A paged
+     * body evaluates its blank region only inside them; empty for a grid that is not paged.
+     */
+    getDemanded(): readonly IRange.Coords[];
+    /**
+     * Take the owner's tiles. A tile that is new or released is dirtied: the next pass evaluates a
+     * new one and clears what a released one holds.
+     */
+    protected _demandNow(rects: readonly IRange.Coords[]): void;
     /** {@inheritDoc ICalcGrid.getEntireCoords} */
     getEntireCoords(): IRange.Coords;
     /**
@@ -242,6 +258,12 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
      * the model's question.
      */
     getDirectDependentsAt(coords: IRange.Coords): IRange.Coords[];
+    /**
+     * Pushes `dep` and the landed output of every spill anchored in it. An anchor rewrites its whole
+     * spill when it re-evaluates, and this is the hop that lets a transitive walk reach what reads the
+     * spill's far end, not just its anchor. A blocked spill landed on its anchor alone, so adds nothing.
+     */
+    private _pushWithSpills;
     /**
      * The direct precedents of a range: one hop upstream, as of the last calculation.
      *
@@ -459,6 +481,14 @@ export declare namespace CalcGridBackend {
          * conditional-format body. See {@link ICalcGrid.isArrayFirstCell}.
          */
         arrayFirstCell?: boolean;
+        /**
+         * `true` when the body's blank region may be evaluated a tile at a time: once the body's
+         * answer there depends on the position (`ISODD(ROW())`), only the tiles its owner asks for
+         * ({@link CalcGridBackend.getDemanded}) are evaluated, and the rest of the region holds
+         * nothing. For an owner that reads a window of the body at a time - a conditional format,
+         * which paints what is on screen.
+         */
+        paged?: boolean;
     }
 }
 /** A grid's per-grid maps, as one snapshot of the engine's history holds them. */

package/types/src/calculation/grid/CalcGridProxy.d.ts

@@ -67,6 +67,8 @@ export declare class CalcGridProxy implements ICalcGrid.Backend {
     calculate(full?: boolean): Promise<ICalculation.Status>;
     /** {@inheritDoc ICalcGrid.Backend.requestPass} */
     requestPass(): void;
+    /** {@inheritDoc ICalcGrid.Backend.demand} */
+    demand(rects: readonly IRange.Coords[]): void;
     /** {@inheritDoc ICalcGrid.markDirtyRegions} */
     markDirtyRegions(coords: IRange.Coords[]): void;
     /** {@inheritDoc ICalcGrid.delete} */

package/types/src/calculation/grid/CalcGridUtils.d.ts

@@ -43,7 +43,14 @@ export declare function errorValueEntriesOf(grid: ISparseGrid<Scalar>): ISpatial
  * region leaves the index and its runs are re-read for errors.
  */
 export declare function indexWrittenRuns(errorSpatial: ISpatialMap<string>, grid: ISparseGrid<Scalar>, bounds: IRange.Coords): void;
-/** Removes a cleared region from the error index (a spill's old extent, a deleted range). */
+/**
+ * Removes a cleared region from the error index (a spill's old extent, a deleted range).
+ *
+ * @remarks
+ * Exactly the region: the index joins like errors side by side into one entry, so an entry may
+ * run past `coords`, and only its part inside them goes. (`ISpatialMap.delete` drops every entry
+ * it touches whole, which would forget the errors beside a one-cell write.)
+ */
 export declare function clearErrorIndex(errorSpatial: ISpatialMap<string>, coords: IRange.Coords): void;
 /**
  * Updates contentful and invalidates spills.

package/types/src/calculation/grid/FormulaHost.d.ts

@@ -1,7 +1,6 @@
-import { IRange, IFormulaContext, Scalar } from '@sheetxl/primitives';
+import { IRange, IRuntime, Scalar } from '@sheetxl/primitives';
 import { ISparseGrid } from '../../collections';
 import { ITransaction } from '../../transaction';
-import { IContextContainer } from '../state';
 import { IFormulaBlockView } from '../formula';
 import { ICalcGrid } from './ICalcGrid';
 import { CalcGrid } from './CalcGrid';
@@ -22,8 +21,7 @@ export declare class FormulaHost {
     protected readonly _id: string;
     protected readonly _grid: CalcGrid;
     protected readonly _transactions: ITransaction.IStore | null;
-    protected readonly _container: IContextContainer;
-    protected readonly _context: IFormulaContext;
+    protected readonly _runtime: IRuntime;
     /**
      * The body as this side knows it: what was last handed to the grid, refined by what the grid
      * answered. Held here so that the owner of a formula never has to read it back out of the grid -
@@ -42,9 +40,21 @@ export declare class FormulaHost {
     } | null;
     /** The last body written as authored has not been answered: the grid's entry predates it. */
     protected _bodyPending: boolean;
+    /**
+     * A paged body's tiles the owner has asked for, by index from the body's top row, oldest ask
+     * first: what is sent as the demand. Capped (see {@link request}); the oldest go first.
+     */
+    protected _wanted: Map<number, true>;
+    /** The tiles the last pass evaluated, by index: see {@link ICalcGrid.BlankRegion.evaluated}. */
+    protected _evaluated: Set<number>;
+    /** A demand is waiting to be sent at the end of the current flush. */
+    protected _demandQueued: boolean;
+    /** A demand was sent since the last pass's results. */
+    protected _demandSent: boolean;
     protected readonly _onDispose: (() => void) | undefined;
     protected readonly _onCalculated: ((results: ICalcGrid.Results) => void) | undefined;
     protected readonly _onResync: (() => void) | undefined;
+    protected readonly _waitUntil: ((work: Promise<void>) => void) | undefined;
     constructor(options: FormulaHost.ConstructorOptions);
     /** The grid's id. */
     getId(): string;
@@ -86,12 +96,39 @@ export declare class FormulaHost {
      * rewrite a structural change made since - replaces it when it arrives.
      */
     getBody(): FormulaHost.Body | null;
+    /**
+     * Whether a body is written: answered, or sent and not yet answered. `false` when nothing has
+     * been written, and again after a restore to a version from before the write (see {@link _resync}).
+     */
+    hasBody(): boolean;
     /**
      * What the engine pushed after a pass over the body: a rewrite nobody asked for (a structural
      * change on the sheet the body reads), and the blank region.
      * @internal
      */
     _onComplete(results: ICalcGrid.Results): void;
+    /**
+     * Whether the body's value at a cell is its answer, asking for it when it is not.
+     *
+     * @remarks
+     * A body whose blank region is paged (`CalcGridBackend.ConstructorOptions.paged`) evaluates
+     * that region only inside the tiles - 256 rows across the body - its owner reads.
+     * A cell elsewhere holds nothing yet: this asks for its tile, once per flush however many cells
+     * ask, and the pass that evaluates it delivers as any pass does. Every other cell, and every
+     * cell of a body that is not paged, already holds its answer.
+     *
+     * The owner reads a window at a time (what is on screen), so the tiles asked for most recently
+     * are the ones kept: past 64 tiles the oldest is released, and what it held is cleared
+     * by the next pass.
+     *
+     * @returns `true` when the value at the cell is the body's answer there.
+     */
+    request(row: number, column: number): boolean;
+    /** The index of the tile holding `row`, counted from the body's top row. */
+    protected _tileOf(row: number, extent: IRange.Coords): number;
+    /** Sends the wanted tiles once the current flush is over, and asks for the pass. */
+    protected _queueDemand(): void;
+    protected _sendDemand(extent: IRange.Coords): void;
     /**
      * Take what the grid reports about the body: the answer to a write, or a rewrite nobody asked
      * for (a structural change on the sheet the body reads).
@@ -157,6 +194,12 @@ export declare class FormulaHost {
     getBlock(): IFormulaBlockView | null;
     /** The model's grid the body lives in. @internal */
     _getCalcGrid(): CalcGrid;
+    /**
+     * Whether the grid holds state at the current commit: `false` after a restore to a version from
+     * before the grid was made, when nothing written here lands anywhere (see `CalcGrid._revive`).
+     * @internal
+     */
+    _isLive(): boolean;
     /**
      * The body as the model's grid holds it, answered or not: its text is the engine's once the
      * engine has answered, and the text as written until then. `null` when nothing is written.
@@ -217,14 +260,16 @@ export declare namespace FormulaHost {
         grid: CalcGrid;
         /** The store the grid is versioned in: a write made outside an operation amends its current commit. */
         transactions?: ITransaction.IStore | null;
-        container: IContextContainer;
-        context: IFormulaContext;
+        /** The runtime a range over the body's values reads with. */
+        runtime: IRuntime;
         /** Called when the host is disposed, for whoever keeps track of live hosts. */
         onDispose?: () => void;
         /** Told after every pass that wrote the grid. */
         onCalculated?: (results: ICalcGrid.Results) => void;
         /** Told after a restore or revert has replaced the body under the host (see {@link FormulaHost._resync}). */
         onResync?: () => void;
+        /** Counts work the host starts for its owner as calculation in flight: see `ICalculation.waitUntil`. */
+        waitUntil?: (work: Promise<void>) => void;
     }
     /** A body as its host holds it. */
     interface Body {

package/types/src/calculation/grid/ICalcGrid.d.ts

@@ -141,6 +141,15 @@ export interface ICalcGrid {
      * collapses into a plain read once the executor emits those deltas.
      */
     getErrorValues(): ISpatialMap<boolean>;
+    /**
+     * A counter that moves whenever the values change in place, where {@link getValues} keeps its
+     * identity (an engine's answers landing, a load).
+     *
+     * @remarks
+     * With the identity of {@link getValues}, the key a view derived from the values is cached
+     * against: equal identity and equal epoch mean the values have not moved.
+     */
+    getValuesEpoch(): number;
     /**
      * The volatile regions the file listed: what an `Off` save writes back and a seed carries,
      * kept where a formula still sits under them. What the engine knows once it is up it answers
@@ -287,8 +296,10 @@ export interface ICalcGrid {
      */
     setReferenceModeAt(row: number, column: number, index: number, side?: ICalculation.ReferenceSide, mode?: number): Promise<IFormulaBlockView | null>;
     /**
-     * Whether the formula at the cell is volatile: found by the engine as it evaluates, so a
-     * question answered in order behind the writes sent before it.
+     * Whether the formula at the cell is volatile: its text, closed over the names it mentions,
+     * the computed reads its last evaluation registered, or the node a pass registered volatile —
+     * a question answered in order behind the writes sent before it. On a grid at a synthetic
+     * anchor (a name's), which no pass evaluates, the text is all there is.
      *
      * @param row The row of the cell to evaluate.
      * @param column The column of the cell to evaluate.
@@ -399,13 +410,18 @@ export declare namespace ICalcGrid {
      * the engine answers, and nothing the model holds for itself. The in-process engine grid is
      * one; a message-passing proxy under a worker is another.
      */
-    type Backend = Omit<ICalcGrid, 'getStateId' | 'getEntireCoords' | 'getFormulaAt' | 'getFormulas' | 'getValues' | 'getContentful' | 'getSpills' | 'getPending' | 'getCalcErrors' | 'getCirculars' | 'getErrorValues' | 'getVolatileRegions' | 'getRangeStats'> & {
+    type Backend = Omit<ICalcGrid, 'getStateId' | 'getEntireCoords' | 'getFormulaAt' | 'getFormulas' | 'getValues' | 'getContentful' | 'getSpills' | 'getPending' | 'getCalcErrors' | 'getCirculars' | 'getErrorValues' | 'getValuesEpoch' | 'getVolatileRegions' | 'getRangeStats'> & {
         /** Write a body as authored; the engine anchors it (see {@link ICalcGrid.BodyOptions}). */
         setBody(options: ICalcGrid.BodyOptions): Promise<ICalcGrid.Results>;
         /** {@link ICalcGrid.evaluateAt} coerced to one scalar, as a defined name's `evaluate()` is. */
         evaluateScalarAt(row: number, column: number, evalIndex?: number): Promise<Scalar>;
         /** Owe a pass seeded from this grid, run once the current flush is over. */
         requestPass(): void;
+        /**
+         * The tiles of a paged body's blank region the owner reads now - all of them, replacing the
+         * last set; see `CalcGridBackend.getDemanded`. Evaluated by the next pass.
+         */
+        demand(rects: readonly IRange.Coords[]): void;
         /**
          * The graph around the defined name whose body this grid holds - its precedents or
          * dependents, cells in calc currency and names - as {@link ICalcGrid.getGraphNeighborsAt}
@@ -575,14 +591,23 @@ export declare namespace ICalcGrid {
     /**
      * The cells of a body that a pass shares one answer for rather than writing, and that answer:
      * what every such cell reads as.
+     *
+     * @remarks
+     * A PAGED region shares nothing: the body's answer there depends on the position, and only the
+     * tiles its owner asked for are evaluated ({@link evaluated}). Every other cell of
+     * {@link rects} holds nothing and has no answer yet.
      */
     interface BlankRegion {
-        /** The shared answer. */
+        /** The shared answer; `undefined` for a paged region. */
         readonly value: Scalar | undefined;
         /** The rectangles it covers, in the grid's coordinates. */
         readonly rects: readonly IRange.Coords[];
         /** The body's extent: a read wider than it shares nothing. */
         readonly extent: IRange.Coords;
+        /** The region is evaluated a tile at a time rather than shared. */
+        readonly paged?: boolean;
+        /** For a paged region, the tiles this pass evaluated. */
+        readonly evaluated?: readonly IRange.Coords[];
     }
     /**
      * Returns from `ICalcGrid.beginUpdates()`.
@@ -665,10 +690,14 @@ export declare namespace ICalcGrid {
          */
         range: IRange.Coords | string;
     }
-    interface ISnapshot extends IHistory.ISnapshot<ICalcGrid.SnapshotDestination, ICalcGrid.Backend, IRange.Coords, any, ICalcGrid.Results> {
+    interface ISnapshot extends IHistory.ISnapshot<ICalcGrid.SnapshotDestination, ICalcGrid.Backend, IRange.Coords, any, Promise<ICalcGrid.Results>> {
         /**
          * Copies the snapshot's formulas to the destination grid.
          *
+         * @remarks
+         * The engine answers when it has the blocks; the destination holds the formulas pending in
+         * the meantime, so a paste starts this and does not wait for it.
+         *
          * @returns Resolves with the blocks minted at the destination (re-anchored, `#REF!` where a
          * relative reference left the sheet) and, for a cut, the coords vacated at the source. The
          * copied extent is the result's `bounds`.
@@ -828,7 +857,7 @@ export declare namespace ICalcGrid {
          * {@link ITypes.FormulaArrayKind | kinds} of array formula it is.
          *
          * @remarks
-         * See {@link ISheet.JSON.formulaArray} for what does and does not earn an entry.
+         * See {@link IWorksheet.JSON.formulaArray} for what does and does not earn an entry.
          */
         formulaArray?: IRange.JSONReferenceTuple<ITypes.FormulaArrayKind>[];
         /**

package/types/src/calculation/grid/_CalcRequest.d.ts

@@ -107,6 +107,14 @@ export type CalcRequest =
     type: 'markDirty';
     coords: readonly IRange.Coords[];
 }
+/**
+ * The tiles of a paged body's blank region its owner reads now - all of them, replacing the
+ * last set. See `CalcGridBackend.ConstructorOptions.paged`.
+ */
+ | {
+    type: 'demand';
+    rects: readonly IRange.Coords[];
+}
 /**
  * The model restored to `options.commitId`: the engine restores its own history there and re-vends
  * what changed. Only a `Running` engine acts on it - see `Calculation._sendRequestNow`.
@@ -188,7 +196,7 @@ export type CalcRequest =
  */
  | {
     type: 'sheets';
-    sheets: readonly (readonly [id: string, name: string | null])[];
+    sheets: readonly (readonly [id: string, name: string | null, gridless?: boolean])[];
     options?: ICalcGrid.RequestOptions;
 }
 /**
@@ -236,6 +244,8 @@ export interface CalcGridSpec {
     unanchored?: boolean;
     /** See `CalcGridBackend.ConstructorOptions.arrayFirstCell`. */
     arrayFirstCell?: boolean;
+    /** See `CalcGridBackend.ConstructorOptions.paged`. */
+    paged?: boolean;
     /** The grid's size, fixed: a name's. A sheet's is its seed's. */
     entireCoords?: IRange.Coords;
     /** The grid whose size this one has, whatever it is then: a body on a sheet. */