@ricsam/formula-engine 0.2.1 → 0.2.3

package/dist/types/core/commands/types.d.ts

@@ -4,7 +4,27 @@
  * Commands encapsulate all mutating operations on the engine,
  * enabling undo/redo, schema validation with rollback, and action serialization.
  */
-import type { CellAddress } from "../types";
+import type { CellAddress, SerializedCellValue } from "../types";
+export type CellContentKind = "empty" | "scalar" | "formula";
+export type RemovedScope = {
+    type: "workbook";
+    workbookName: string;
+} | {
+    type: "sheet";
+    workbookName: string;
+    sheetName: string;
+};
+export type MutationInvalidation = {
+    touchedCells: Array<{
+        address: CellAddress;
+        beforeKind: CellContentKind;
+        afterKind: CellContentKind;
+    }>;
+    resourceKeys: string[];
+    removedScopes?: RemovedScope[];
+};
+export declare function getSerializedCellValueKind(value: SerializedCellValue | undefined): CellContentKind;
+export declare function emptyMutationInvalidation(): MutationInvalidation;
 /**
  * Serializable action representation of a command.
  * Used for persistence, collaboration, and changelog functionality.
@@ -23,6 +43,10 @@ export interface EngineCommand {
      * Commands that only affect metadata or styles don't need re-evaluation.
      */
     readonly requiresReevaluation: boolean;
+    /**
+     * Returns the exact mutation footprint for the last execute/undo pass.
+     */
+    getInvalidationFootprint?(phase: "execute" | "undo"): MutationInvalidation;
     /**
      * Execute the command (forward operation).
      */

package/dist/types/core/engine-snapshot.d.ts

@@ -0,0 +1,138 @@
+import type { ContextDependency } from "../evaluator/evaluation-context";
+import type { DependencyNode } from "./managers/dependency-node";
+import type { CellAddress, CellInRangeResult, CellValue, ConditionalStyle, DirectCellStyle, FormulaError, NamedExpression, RangeAddress, RelativeRange, SpreadsheetRange, TableDefinition, TrackedReference, Workbook } from "./types";
+export declare const ENGINE_SNAPSHOT_VERSION: 3;
+export type NodeSnapshotId = string;
+export type NamedExpressionManagerSnapshot = {
+    sheetExpressions: Map<string, Map<string, Map<string, NamedExpression>>>;
+    workbookExpressions: Map<string, Map<string, NamedExpression>>;
+    globalExpressions: Map<string, NamedExpression>;
+};
+export type WorkbookManagerSnapshot = Map<string, Workbook>;
+export type TableManagerSnapshot = Map<string, Map<string, TableDefinition>>;
+export type StyleManagerSnapshot = {
+    conditionalStyles: ConditionalStyle[];
+    cellStyles: DirectCellStyle[];
+};
+export type ReferenceManagerSnapshot = Map<string, TrackedReference>;
+export type SerializedValueEvaluationResultSnapshot = {
+    type: "value";
+    result: CellValue;
+    sourceCell?: CellAddress;
+};
+export type SerializedErrorEvaluationResultSnapshot = {
+    type: "error";
+    err: FormulaError;
+    message: string;
+    errAddressId: NodeSnapshotId;
+    sourceCell?: CellAddress;
+};
+export type SerializedSingleEvaluationResultSnapshot = SerializedValueEvaluationResultSnapshot | SerializedErrorEvaluationResultSnapshot;
+export type SerializedCellInRangeResultSnapshot = {
+    relativePos: CellInRangeResult["relativePos"];
+    result: SerializedSingleEvaluationResultSnapshot;
+};
+export type SerializedEvaluateAllCellsResultSnapshot = SerializedErrorEvaluationResultSnapshot | {
+    type: "values";
+    values: SerializedCellInRangeResultSnapshot[];
+};
+export type SerializedMaterializedSpillSnapshot = {
+    kind: "materialized";
+    relativeSpillArea: RelativeRange;
+    source: string;
+    sourceCell?: CellAddress;
+    sourceRange?: RangeAddress;
+    values: SerializedCellInRangeResultSnapshot[];
+};
+export type SerializedSourceRangeSpillSnapshot = {
+    kind: "source-range";
+    relativeSpillArea: RelativeRange;
+    source: string;
+    sourceCell?: CellAddress;
+    sourceRange: RangeAddress;
+};
+export type SerializedSpillResultSnapshot = SerializedMaterializedSpillSnapshot | SerializedSourceRangeSpillSnapshot;
+export type SerializedSpilledValuesEvaluationResultSnapshot = {
+    type: "spilled-values";
+    spill: SerializedSpillResultSnapshot;
+};
+export type SerializedFunctionEvaluationResultSnapshot = SerializedSingleEvaluationResultSnapshot | SerializedSpilledValuesEvaluationResultSnapshot;
+export type SerializedSpillMetaEvaluationResultSnapshot = SerializedErrorEvaluationResultSnapshot | SerializedSpilledValuesEvaluationResultSnapshot | {
+    type: "does-not-spill";
+};
+type SerializedBaseNodeSnapshot = {
+    snapshotId: NodeSnapshotId;
+    key: string;
+    dependencies: NodeSnapshotId[];
+};
+export type SerializedCellValueNodeSnapshot = SerializedBaseNodeSnapshot & {
+    kind: "cell-value";
+    evaluationResult: SerializedSingleEvaluationResultSnapshot;
+    spillMetaSnapshotId?: NodeSnapshotId;
+};
+export type SerializedSpillMetaNodeSnapshot = SerializedBaseNodeSnapshot & {
+    kind: "spill-meta";
+    evaluationResult: SerializedSpillMetaEvaluationResultSnapshot;
+};
+export type SerializedEmptyCellNodeSnapshot = SerializedBaseNodeSnapshot & {
+    kind: "empty";
+    evaluationResult: SerializedSingleEvaluationResultSnapshot;
+};
+export type SerializedRangeNodeSnapshot = SerializedBaseNodeSnapshot & {
+    kind: "range";
+    result: SerializedEvaluateAllCellsResultSnapshot;
+};
+export type SerializedAstNodeSnapshot = SerializedBaseNodeSnapshot & {
+    kind: "ast";
+    contextDependency: ContextDependency;
+    evaluationResult: SerializedFunctionEvaluationResultSnapshot;
+};
+export type SerializedResourceNodeSnapshot = SerializedBaseNodeSnapshot & {
+    kind: "resource";
+};
+export type SerializedDependencyNodeSnapshot = SerializedCellValueNodeSnapshot | SerializedSpillMetaNodeSnapshot | SerializedEmptyCellNodeSnapshot | SerializedRangeNodeSnapshot | SerializedAstNodeSnapshot | SerializedResourceNodeSnapshot;
+export type DependencyManagerSnapshot = {
+    nodes: SerializedDependencyNodeSnapshot[];
+    spilledValues: Array<[string, {
+        origin: CellAddress;
+        spillOnto: SpreadsheetRange;
+    }]>;
+};
+export type SerializedSCCSnapshot = {
+    id: number;
+    nodes: NodeSnapshotId[];
+    evaluationOrder: NodeSnapshotId[];
+    resolved: boolean;
+    hardEdgeSCCs: NodeSnapshotId[][];
+};
+export type SerializedEvaluationOrderSnapshot = {
+    nodeKey: string;
+    evaluationOrder: NodeSnapshotId[];
+    hasCycle: boolean;
+    cycleNodes?: NodeSnapshotId[];
+    hash: string;
+};
+export type CacheManagerSnapshot = {
+    evaluationOrders: SerializedEvaluationOrderSnapshot[];
+    sccs: Array<{
+        hash: string;
+        scc: SerializedSCCSnapshot;
+    }>;
+};
+export type EngineSnapshotV3 = {
+    version: typeof ENGINE_SNAPSHOT_VERSION;
+    managers: {
+        workbook: WorkbookManagerSnapshot;
+        namedExpression: NamedExpressionManagerSnapshot;
+        table: TableManagerSnapshot;
+        style: StyleManagerSnapshot;
+        reference: ReferenceManagerSnapshot;
+        dependency: DependencyManagerSnapshot;
+        cache: CacheManagerSnapshot;
+    };
+};
+export type EngineSnapshotV2 = EngineSnapshotV3;
+export declare function getAstNodeSnapshotId(node: DependencyNode & {
+    getContextDependency(): ContextDependency;
+}): NodeSnapshotId;
+export {};

package/dist/types/core/engine.d.ts

@@ -2,7 +2,7 @@
  * Main FormulaEngine class
  * Core API implementation for spreadsheet calculations
  */
-import { type CellAddress, type CellStyle, type ConditionalStyle, type CopyCellsOptions, type DirectCellStyle, type NamedExpression, type RangeAddress, type SerializedCellValue, type SingleEvaluationResult, type SpreadsheetRange, type SpreadsheetRangeEnd, type TableDefinition } from "./types";
+import { type CellAddress, type CellStyle, type ConditionalStyle, type CopyCellsOptions, type DirectCellStyle, type FiniteSpreadsheetRange, type NamedExpression, type RangeAddress, type SerializedCellValue, type SingleEvaluationResult, type SpreadsheetRange, type SpreadsheetRangeEnd, type TableDefinition } from "./types";
 import type { FillDirection } from "@ricsam/selection-manager";
 import { AutoFill } from "./autofill-utils";
 import { WorkbookManager } from "./managers/workbook-manager";
@@ -15,6 +15,7 @@ import { StyleManager } from "./managers/style-manager";
 import type { Schema, CreateSchema, SchemaDeclaration } from "./schema/schema";
 import { TableOrm } from "./schema/table-orm";
 import { CellOrm } from "./schema/cell-orm";
+import { GridOrm } from "./schema/grid-orm";
 import type { TableSchemaHeaders } from "./managers/schema-manager";
 import { type EngineAction } from "./commands/types";
 type Metadata = {
@@ -87,6 +88,22 @@ export declare class FormulaEngine<TMetadata extends Metadata = Metadata, TCreat
         value: SerializedCellValue;
         metadata?: MetadataType<TMetadata, "cell">;
     }): CellOrm<TValue>;
+    /**
+     * Add a grid schema at runtime
+     * @param namespace - Unique namespace for the schema
+     * @param address - Grid address (workbookName and sheetName)
+     * @param range - Finite range of cells for the grid
+     * @param parse - Parse function for the cell values
+     * @param write - Write function for serializing values (optional for primitive types)
+     * @returns The GridOrm instance for immediate use
+     */
+    addGridSchema<TValue>(namespace: string, address: {
+        workbookName: string;
+        sheetName: string;
+    }, range: FiniteSpreadsheetRange, parse: (value: unknown, metadata: MetadataType<TMetadata, "cell">) => TValue, write?: (value: TValue) => {
+        value: SerializedCellValue;
+        metadata?: MetadataType<TMetadata, "cell">;
+    }): GridOrm<TValue, MetadataType<TMetadata, "cell">>;
     getCellEvaluationResult(cellAddress: CellAddress): SingleEvaluationResult | undefined;
     getCellValue(cellAddress: CellAddress, debug?: boolean): SerializedCellValue;
     /**
@@ -503,6 +520,7 @@ export declare class FormulaEngine<TMetadata extends Metadata = Metadata, TCreat
         references: Map<string, import("./types").TrackedReference>;
     };
     onUpdate(listener: () => void): () => void;
+    private buildSerializedSnapshot;
     serializeEngine(): string;
     resetToSerializedEngine(data: string): void;
     /**

package/dist/types/core/managers/cache-manager.d.ts

@@ -1,4 +1,6 @@
 import type { EvaluationOrder, SCC } from "../types";
+import type { DependencyNode } from "./dependency-node";
+import type { CacheManagerSnapshot, NodeSnapshotId } from "../engine-snapshot";
 export declare class CacheManager {
     private _evaluationOrderCache;
     /**
@@ -8,7 +10,14 @@ export declare class CacheManager {
     constructor();
     setEvaluationOrder(nodeKey: string, evaluationOrder: EvaluationOrder): void;
     getEvaluationOrder(nodeKey: string): EvaluationOrder | undefined;
+    deleteEvaluationOrder(nodeKey: string): void;
+    deleteEvaluationOrders(nodeKeys: Iterable<string>): void;
     setSCC(sccHash: string, scc: SCC): void;
     getSCC(sccHash: string): SCC | undefined;
+    clearSCCCache(): void;
     clear(): void;
+    toSnapshot(getNodeSnapshotId: (node: DependencyNode) => NodeSnapshotId | undefined): CacheManagerSnapshot;
+    restoreFromSnapshot(snapshot: CacheManagerSnapshot, resolveNodeSnapshotId: (nodeId: NodeSnapshotId) => DependencyNode | undefined): void;
+    private serializeSCC;
+    private deserializeSCC;
 }

package/dist/types/core/managers/dependency-manager.d.ts

@@ -1,3 +1,4 @@
+import { type CacheManagerSnapshot, type DependencyManagerSnapshot } from "../engine-snapshot";
 import { type ContextDependency } from "../../evaluator/evaluation-context";
 import { type CellAddress, type EvaluationOrder, type SerializedCellValue, type SpilledValue } from "../types";
 import { AstEvaluationNode } from "../../evaluator/dependency-nodes/ast-evaluation-node";
@@ -10,6 +11,9 @@ import { CacheManager } from "./cache-manager";
 import type { DependencyNode } from "./dependency-node";
 import { WorkbookManager } from "./workbook-manager";
 import { VirtualCellValueNode } from "../../evaluator/dependency-nodes/virtual-cell-value-node";
+import type { EvaluationManager } from "./evaluation-manager";
+import type { MutationInvalidation } from "../commands/types";
+import { ResourceDependencyNode } from "../../evaluator/dependency-nodes/resource-dependency-node";
 export interface DependencyTreeNode {
     type: "cell" | "range" | "empty";
     circular?: boolean;
@@ -17,7 +21,7 @@ export interface DependencyTreeNode {
     directDepsUpdated?: boolean;
     resolved?: boolean;
     canResolve: boolean;
-    resultType: "awaiting-evaluation" | "spilled-values" | "value" | "range" | "error" | "does-not-spill";
+    resultType: "awaiting-evaluation" | "spilled-values" | "value" | "range" | "error" | "does-not-spill" | "resource";
     deps?: DependencyTreeNode[];
     frontierDependencies?: DependencyTreeNode[];
     self?: boolean;
@@ -48,7 +52,33 @@ export declare class DependencyManager {
      * Key is workbook:sheetName:rangeKey, e.g. Workbook1:Sheet1:A1:D10, from rangeAddressToKey
      */
     private ranges;
+    private resourceNodes;
+    private hardDependents;
+    private frontierDependents;
+    private registeredDependencies;
+    private coverageWatchersBySheet;
+    private frontierWatchersBySheet;
     constructor(cacheManager: CacheManager, workbookManager: WorkbookManager);
+    private getSheetWatcherKey;
+    private addReverseEdge;
+    private removeReverseEdge;
+    private getWatcherRange;
+    private addWatcher;
+    private removeWatcher;
+    private registerWatcherNode;
+    private unregisterWatcherNode;
+    private isWatcherNodeResolved;
+    private getAllPersistentNodes;
+    private getExistingCellValueNode;
+    private getExistingSpillMetaNode;
+    private getExistingEmptyCellNode;
+    private collectExistingNodesForCell;
+    private collectSpillOriginsAffectingCell;
+    private getLinkedSpillMetaNode;
+    private getLinkedCellValueNode;
+    registerNode(node: DependencyNode): void;
+    unregisterNode(node: DependencyNode): void;
+    private rebuildRuntimeIndexes;
     get spilledValues(): IterableIterator<SpilledValue>;
     isSpillOrigin(cellAddress: CellAddress): boolean;
     getSpillValue(cellAddress: CellAddress): SpilledValue | undefined;
@@ -64,11 +94,23 @@ export declare class DependencyManager {
         };
     };
     clearEvaluationCache(): void;
+    toSnapshot(evaluationManager: EvaluationManager): {
+        dependency: DependencyManagerSnapshot;
+        cache: CacheManagerSnapshot;
+    };
+    restoreFromSnapshot(snapshots: {
+        dependency: DependencyManagerSnapshot;
+        cache: CacheManagerSnapshot;
+    }, evaluationManager: EvaluationManager): void;
+    private serializeNodeSnapshot;
+    private createNodeFromSnapshot;
     setSpilledValue(nodeKey: string, spilledValue: SpilledValue): void;
     getSpilledValue(nodeKey: string): SpilledValue | undefined;
+    deleteSpilledValue(nodeKey: string): void;
     getEmptyCellNode(nodeKey: string): EmptyCellEvaluationNode;
     getSpillMetaNode(nodeKey: string): SpillMetaNode;
     getCellValueNode(nodeKey: string): CellValueNode;
+    getResourceNode(resourceKey: string): ResourceDependencyNode;
     getCellValueOrEmptyCellNode(nodeKey: string): CellValueNode | EmptyCellEvaluationNode;
     getSpillMetaOrEmptySpillMetaNode(nodeKey: string): SpillMetaNode | EmptyCellEvaluationNode;
     getVirtualCellValueNode(cellAddress: CellAddress, cellValue: SerializedCellValue): VirtualCellValueNode;
@@ -98,6 +140,19 @@ export declare class DependencyManager {
      * only resolved ast nodes can be saved
      */
     private saveAstNode;
+    private isFiniteEndAfter;
+    private doesAddressAffectWatcherFrontier;
+    private collectCoverageWatchers;
+    private collectFrontierWatchers;
+    private collectWatchersIntersectingRange;
+    private getNodeDependents;
+    private collectInvalidationExtras;
+    private invalidateNodeState;
+    private isResourceNodeInRemovedScope;
+    private isNodeInRemovedScope;
+    private collectNodesForRemovedScopes;
+    private purgeRemovedScopes;
+    invalidateFromMutation(footprint: MutationInvalidation): void;
     /**
      * Get transitive dependencies and transitive frontier dependencies
      * This is only used by buildEvaluationOrder, so we'll optimize it there

package/dist/types/core/managers/dependency-node.d.ts

@@ -1,9 +1,10 @@
 import { AstEvaluationNode } from "../../evaluator/dependency-nodes/ast-evaluation-node";
 import { CellValueNode } from "../../evaluator/dependency-nodes/cell-value-node";
 import { EmptyCellEvaluationNode } from "../../evaluator/dependency-nodes/empty-cell-evaluation-node";
+import { ResourceDependencyNode } from "../../evaluator/dependency-nodes/resource-dependency-node";
 import { SpillMetaNode } from "../../evaluator/dependency-nodes/spill-meta-node";
 import { RangeEvaluationNode } from "../../evaluator/range-evaluation-node";
-export type DependencyNode = CellValueNode | RangeEvaluationNode | EmptyCellEvaluationNode | AstEvaluationNode | SpillMetaNode;
+export type DependencyNode = CellValueNode | RangeEvaluationNode | EmptyCellEvaluationNode | AstEvaluationNode | SpillMetaNode | ResourceDependencyNode;
 export type CellNodeType = "cell-value" | "empty" | "spill-meta";
 export type CellNodeKey = `${CellNodeType}:${string}`;
 export type CellNodeKeyDictionary = {

package/dist/types/core/managers/evaluation-manager.d.ts

@@ -1,7 +1,8 @@
+import { AstEvaluationNode } from "../../evaluator/dependency-nodes/ast-evaluation-node";
 import { CellValueNode } from "../../evaluator/dependency-nodes/cell-value-node";
 import { RangeEvaluationNode } from "../../evaluator/range-evaluation-node";
 import { FormulaEvaluator } from "../../evaluator/formula-evaluator";
-import { type CellAddress, type CellValue, type SerializedCellValue, type SingleEvaluationResult, type SpreadsheetRange } from "../types";
+import { type CellAddress, type CellValue, type EvaluateAllCellsResult, type FunctionEvaluationResult, type SerializedCellValue, type SingleEvaluationResult, type SpreadsheetRange } from "../types";
 import type { DependencyManager } from "./dependency-manager";
 import type { WorkbookManager } from "./workbook-manager";
 import { SpillMetaNode } from "../../evaluator/dependency-nodes/spill-meta-node";
@@ -9,6 +10,8 @@ import { EmptyCellEvaluationNode } from "../../evaluator/dependency-nodes/empty-
 import type { TableManager } from "./table-manager";
 import type { DependencyNode } from "./dependency-node";
 import { VirtualCellValueNode } from "../../evaluator/dependency-nodes/virtual-cell-value-node";
+import type { NodeSnapshotId, SerializedEvaluateAllCellsResultSnapshot, SerializedFunctionEvaluationResultSnapshot, SerializedSingleEvaluationResultSnapshot, SerializedSpillMetaEvaluationResultSnapshot } from "../engine-snapshot";
+import type { MutationInvalidation } from "../commands/types";
 export declare class EvaluationManager {
     private workbookManager;
     private tableManager;
@@ -17,7 +20,24 @@ export declare class EvaluationManager {
     private isEvaluating;
     constructor(workbookManager: WorkbookManager, tableManager: TableManager, formulaEvaluator: FormulaEvaluator, dependencyManager: DependencyManager);
     clearEvaluationCache(): void;
+    invalidateFromMutation(footprint: MutationInvalidation): void;
     evaluationResultToSerializedValue(evaluation: SingleEvaluationResult, cellAddress: CellAddress, debug?: boolean): SerializedCellValue;
+    private buildSnapshotOrigin;
+    private serializeErrorEvaluationResultSnapshot;
+    serializeSingleEvaluationResultSnapshot(evaluation: SingleEvaluationResult, getNodeSnapshotId: (node: DependencyNode) => NodeSnapshotId): SerializedSingleEvaluationResultSnapshot | undefined;
+    deserializeSingleEvaluationResultSnapshot(evaluation: SerializedSingleEvaluationResultSnapshot, resolveNodeSnapshotId: (nodeId: NodeSnapshotId) => DependencyNode): SingleEvaluationResult;
+    serializeEvaluateAllCellsResultSnapshot(evaluation: EvaluateAllCellsResult, getNodeSnapshotId: (node: DependencyNode) => NodeSnapshotId): SerializedEvaluateAllCellsResultSnapshot | undefined;
+    deserializeEvaluateAllCellsResultSnapshot(evaluation: SerializedEvaluateAllCellsResultSnapshot, resolveNodeSnapshotId: (nodeId: NodeSnapshotId) => DependencyNode): EvaluateAllCellsResult;
+    serializeFunctionEvaluationResultSnapshot(evaluation: FunctionEvaluationResult, options: {
+        sourceNode: CellValueNode | SpillMetaNode | AstEvaluationNode;
+        getNodeSnapshotId: (node: DependencyNode) => NodeSnapshotId;
+    }): SerializedFunctionEvaluationResultSnapshot | undefined;
+    deserializeFunctionEvaluationResultSnapshot(evaluation: SerializedFunctionEvaluationResultSnapshot, resolveNodeSnapshotId: (nodeId: NodeSnapshotId) => DependencyNode): FunctionEvaluationResult;
+    serializeSpillMetaEvaluationResultSnapshot(evaluation: SpillMetaNode["evaluationResult"], options: {
+        sourceNode: CellValueNode | SpillMetaNode | AstEvaluationNode;
+        getNodeSnapshotId: (node: DependencyNode) => NodeSnapshotId;
+    }): SerializedSpillMetaEvaluationResultSnapshot | undefined;
+    deserializeSpillMetaEvaluationResultSnapshot(evaluation: SerializedSpillMetaEvaluationResultSnapshot, resolveNodeSnapshotId: (nodeId: NodeSnapshotId) => DependencyNode): SpillMetaNode["evaluationResult"];
     evaluateEmptyCell(node: EmptyCellEvaluationNode): void;
     evaluateRangeNode(node: RangeEvaluationNode): void;
     evaluateCellNode(node: CellValueNode | SpillMetaNode | VirtualCellValueNode): void;

package/dist/types/core/managers/frontier-dependency-manager.d.ts

@@ -18,13 +18,18 @@ type EvalOrderEntry = {
     candidates: SpillMetaNode[];
 };
 export declare class FrontierDependencyManager {
-    private frontierRange;
+    protected readonly frontierRange: RangeAddress;
     protected workbookManager: WorkbookManager;
     protected evaluationManager: DependencyManager;
     private evalOrder;
     private _resolved;
     private _directDepsUpdated;
-    constructor(frontierRange: RangeAddress, workbookManager: WorkbookManager, evaluationManager: DependencyManager);
+    private evalOrderInitialized;
+    constructor(frontierRange: RangeAddress, workbookManager: WorkbookManager, evaluationManager: DependencyManager, options?: {
+        skipInitialBuild?: boolean;
+    });
+    protected buildInitialEvalOrder(): void;
+    protected ensureEvalOrderBuilt(): void;
     /**
      * frontierDependencies is the set of dependency node keys that could spill values onto the target range (if evaluationResult is spilled-values)
      * Key is from cellAddressToKey
@@ -47,6 +52,11 @@ export declare class FrontierDependencyManager {
      */
     get iterateAllCells(): undefined | Iterable<CellInRangeResult>;
     getRangeEvalOrder(): EvalOrderEntry[];
+    getFrontierRange(): RangeAddress;
+    restoreResolvedSnapshot(options: {
+        dependencies: Set<DependencyNode>;
+    }): void;
+    invalidate(): void;
     get frontierDependencies(): Set<SpillMetaNode>;
     get discardedFrontierDependencies(): Set<SpillMetaNode>;
     maybeDiscardFrontierDependency(dependency: SpillMetaNode): void;

package/dist/types/core/managers/named-expression-manager.d.ts

@@ -1,4 +1,5 @@
 import type { NamedExpression } from "../types";
+import type { NamedExpressionManagerSnapshot } from "../engine-snapshot";
 import type { NamedExpressionNode } from "../../parser/ast";
 import type { EvaluationContext } from "../../evaluator/evaluation-context";
 export declare class NamedExpressionManager {
@@ -28,7 +29,7 @@ export declare class NamedExpressionManager {
         workbookName?: string;
         newName: string;
     }): boolean;
-    updateAllNamedExpressions(updateCallback: (formula: string) => string): void;
+    updateAllNamedExpressions(updateCallback: (formula: string) => string): string[];
     /**
      * Replace all named expressions
      */
@@ -57,6 +58,19 @@ export declare class NamedExpressionManager {
             sheetName: string;
         };
     }): NamedExpression | undefined;
+    resolveNamedExpressionWithScope(namedExpression: Pick<NamedExpressionNode, "name" | "sheetName" | "workbookName">, context: EvaluationContext): {
+        expression: string;
+        scope: {
+            type: "global";
+        } | {
+            type: "workbook";
+            workbookName: string;
+        } | {
+            type: "sheet";
+            workbookName: string;
+            sheetName: string;
+        };
+    } | undefined;
     resolveNamedExpression(namedExpression: Pick<NamedExpressionNode, "name" | "sheetName" | "workbookName">, context: EvaluationContext): string | undefined;
     getNamedExpressions(): {
         sheetExpressions: Map<string, Map<string, Map<string, NamedExpression>>>;
@@ -64,6 +78,8 @@ export declare class NamedExpressionManager {
         globalExpressions: Map<string, NamedExpression>;
     };
     resetNamedExpressions(namedExpressions: ReturnType<typeof this.getNamedExpressions>): void;
+    toSnapshot(): NamedExpressionManagerSnapshot;
+    restoreFromSnapshot(snapshot: NamedExpressionManagerSnapshot): void;
     /**
      * When adding a sheet, we need to initialize the new maps
      */

package/dist/types/core/managers/reference-manager.d.ts

@@ -5,6 +5,7 @@
  * update when sheets/workbooks are renamed and become invalid when deleted.
  */
 import type { RangeAddress, TrackedReference } from "../types";
+import type { ReferenceManagerSnapshot } from "../engine-snapshot";
 export declare class ReferenceManager {
     private references;
     constructor();
@@ -51,4 +52,6 @@ export declare class ReferenceManager {
      * Restore references from serialization
      */
     resetReferences(refs: Map<string, TrackedReference>): void;
+    toSnapshot(): ReferenceManagerSnapshot;
+    restoreFromSnapshot(snapshot: ReferenceManagerSnapshot): void;
 }

package/dist/types/core/managers/style-manager.d.ts

@@ -2,6 +2,7 @@
  * StyleManager - Manages conditional styling for cells
  */
 import type { CellAddress, CellStyle, ConditionalStyle, DirectCellStyle, RangeAddress } from "../types";
+import type { StyleManagerSnapshot } from "../engine-snapshot";
 import type { EvaluationManager } from "./evaluation-manager";
 export declare class StyleManager {
     private evaluationManager;
@@ -50,6 +51,8 @@ export declare class StyleManager {
      * Reset all styles (for deserialization)
      */
     resetStyles(conditionalStyles?: ConditionalStyle[], cellStyles?: DirectCellStyle[]): void;
+    toSnapshot(): StyleManagerSnapshot;
+    restoreFromSnapshot(snapshot: StyleManagerSnapshot): void;
     /**
      * Remove all styles for a workbook
      */

package/dist/types/core/managers/table-manager.d.ts

@@ -1,4 +1,5 @@
 import type { CellAddress, SerializedCellValue, SpreadsheetRange, SpreadsheetRangeEnd, TableDefinition } from "../types";
+import type { TableManagerSnapshot } from "../engine-snapshot";
 import type { WorkbookManager } from "./workbook-manager";
 export declare class TableManager {
     tables: Map<
@@ -65,6 +66,8 @@ export declare class TableManager {
         newWorkbookName: string;
     }): void;
     resetTables(newTables: Map<string, Map<string, TableDefinition>>): void;
+    toSnapshot(): TableManagerSnapshot;
+    restoreFromSnapshot(snapshot: TableManagerSnapshot): void;
     /**
      * When adding a workbook, we need to initialize the new maps
      */

package/dist/types/core/managers/workbook-manager.d.ts

@@ -1,4 +1,5 @@
 import { type CellAddress, type SerializedCellValue, type Sheet, type Workbook } from "../types";
+import type { WorkbookManagerSnapshot } from "../engine-snapshot";
 import type { RangeAddress } from "../types";
 interface IndexEntry {
     number: number;
@@ -54,6 +55,8 @@ export declare class WorkbookManager {
         newWorkbookName: string;
     }): void;
     resetWorkbooks(workbooks: Map<string, Workbook>): void;
+    toSnapshot(): WorkbookManagerSnapshot;
+    restoreFromSnapshot(snapshot: WorkbookManagerSnapshot): void;
     getSheet({ workbookName, sheetName, }: {
         workbookName: string;
         sheetName: string;
@@ -71,7 +74,7 @@ export declare class WorkbookManager {
         sheetName: string;
         newSheetName: string;
     }): Sheet;
-    updateAllFormulas(updateCallback: (formula: string) => string): void;
+    updateAllFormulas(updateCallback: (formula: string) => string): CellAddress[];
     updateFormulasExcluding(excludeCellsSet: Set<string>, updateCallback: (formula: string) => string): void;
     updateFormulasForWorkbook(workbookName: string, updateCallback: (formula: string) => string): void;
     getSheetSerialized({ workbookName, sheetName, }: {

package/dist/types/core/resource-keys.d.ts

@@ -0,0 +1,14 @@
+export declare function getNamedExpressionResourceKey(opts: {
+    expressionName: string;
+    workbookName?: string;
+    sheetName?: string;
+}): string;
+export declare function getTableResourceKey(opts: {
+    workbookName: string;
+    tableName: string;
+}): string;
+export declare function getSheetResourceKey(opts: {
+    workbookName: string;
+    sheetName: string;
+}): string;
+export declare function getWorkbookResourceKey(workbookName: string): string;

package/dist/types/evaluator/dependency-nodes/base-eval-node.d.ts

@@ -14,11 +14,16 @@ export declare class BaseEvalNode<T> {
     get resolved(): boolean;
     get evaluationResult(): T;
     setEvaluationResult(result: T): void;
+    invalidate(): void;
     resetDirectDepsUpdated(): void;
     /**
      * Get the direct dependencies of the node, either RangeEvaluationNode or DependencyNode
      */
     getDependencies(): Set<DependencyNode>;
+    restoreResolvedSnapshot(options: {
+        dependencies: Set<DependencyNode>;
+        evaluationResult: T;
+    }): void;
     /**
      * Just to mirror the method in RangeEvaluationNode
      */

package/dist/types/evaluator/dependency-nodes/cell-value-node.d.ts

@@ -7,4 +7,5 @@ export declare class CellValueNode extends BaseEvalNode<SingleEvaluationResult>
     toString(): string;
     spillMeta: SpillMetaNode | undefined;
     setSpillMetaNode(node: SpillMetaNode): void;
+    clearSpillMetaNode(): void;
 }

package/dist/types/evaluator/dependency-nodes/empty-cell-evaluation-node.d.ts

@@ -7,11 +7,18 @@ export declare class EmptyCellEvaluationNode extends FrontierDependencyManager {
     key: string;
     cellAddress: CellAddress;
     private _evaluationResult;
-    constructor(emptyCellKey: string, evaluationManager: DependencyManager, workbookManager: WorkbookManager);
+    constructor(emptyCellKey: string, evaluationManager: DependencyManager, workbookManager: WorkbookManager, options?: {
+        skipInitialBuild?: boolean;
+    });
     setEvaluationResult(result: SingleEvaluationResult): void;
     get evaluationResult(): SingleEvaluationResult;
     resolve(): void;
     canResolve(): boolean;
+    restoreResolvedSnapshot(options: {
+        dependencies: Set<import("../../core/managers/dependency-node").DependencyNode>;
+        evaluationResult: SingleEvaluationResult;
+    }): void;
+    invalidate(): void;
     toJSON(visitor?: Set<string>): any;
     toString(): string;
 }

package/dist/types/evaluator/dependency-nodes/resource-dependency-node.d.ts

@@ -0,0 +1,8 @@
+import { BaseEvalNode } from "./base-eval-node";
+export declare class ResourceDependencyNode extends BaseEvalNode<{
+    type: "resource";
+}> {
+    constructor(key: string);
+    invalidate(): void;
+    toString(): string;
+}

package/dist/types/evaluator/dependency-nodes/virtual-cell-value-node.d.ts

@@ -8,4 +8,5 @@ export declare class VirtualCellValueNode extends BaseEvalNode<SingleEvaluationR
     toString(): string;
     spillMeta: SpillMetaNode | undefined;
     setSpillMetaNode(node: SpillMetaNode): void;
+    clearSpillMetaNode(): void;
 }

package/dist/types/evaluator/range-evaluation-node.d.ts

@@ -7,10 +7,17 @@ export declare class RangeEvaluationNode extends FrontierDependencyManager {
     key: string;
     address: RangeAddress;
     private _result;
-    constructor(rangeKey: string, dependencyManager: DependencyManager, workbookManager: WorkbookManager);
+    constructor(rangeKey: string, dependencyManager: DependencyManager, workbookManager: WorkbookManager, options?: {
+        skipInitialBuild?: boolean;
+    });
     setResult(result: EvaluateAllCellsResult): void;
     get result(): EvaluateAllCellsResult;
     canResolve(): boolean;
+    restoreResolvedSnapshot(options: {
+        dependencies: Set<import("../core/managers/dependency-node").DependencyNode>;
+        result: EvaluateAllCellsResult;
+    }): void;
+    invalidate(): void;
     toJSON(visitor?: Set<string>): any;
     toString(): string;
 }