@bilig/headless 0.8.0 → 0.8.2

package/dist/work-paper-runtime-surface.js

@@ -0,0 +1,702 @@
+import { formatAddress } from '@bilig/formula';
+import { assertRange, isCellRange } from './work-paper-runtime-helpers.js';
+import { formatTrackedA1, sourceRangeRef } from './work-paper-address-format.js';
+import { clearWorkPaperHistoryStacks, mergeWorkPaperUndoHistory, readWorkPaperHistoryStack, } from './work-paper-history.js';
+import { WorkPaperEvaluationSuspendedError, WorkPaperNoOperationToRedoError, WorkPaperNoOperationToUndoError, WorkPaperNoSheetWithIdError, WorkPaperNoSheetWithNameError, WorkPaperOperationError, } from './work-paper-errors.js';
+import { captureWorkPaperNamedExpressionValueSnapshot, computeWorkPaperNamedExpressionChanges, } from './work-paper-named-expression-helpers.js';
+import { applyWorkPaperHistoryOperation } from './work-paper-history-operations.js';
+import { applyWorkPaperCellMutationRefs } from './work-paper-cell-mutation-refs.js';
+import { materializeTrackedIndexChangeSourcesWithMetadata, materializeTrackedIndexChangesWithMetadata, } from './tracked-cell-index-changes.js';
+import { collectWorkPaperRangeDependencies, toWorkPaperDependencyRefs } from './work-paper-dependency-refs.js';
+import { captureWorkPaperVisibilitySnapshot, computeWorkPaperCellChangesFromVisibilitySnapshots, } from './work-paper-visibility-snapshot.js';
+import { computeWorkPaperTrackedCellChangesFromEvents, tryReadTinyTrackedEventChangesWithoutVisibility as tryReadTinyTrackedEventChangesWithoutVisibilityFromReducer, } from './work-paper-tracked-change-reducer.js';
+import { TINY_TRACKED_CHANGE_LIMIT, readTrackedCellChange, readTrustedPhysicalTrackedChangeMetadata, readTinySortedPhysicalTrackedEventChanges as readTinySortedPhysicalTrackedEventChangesFromStore, trackedEventHasNoValueChanges, tryBuildDirectSingleLiteralTrackedChange, withEventChanges, } from './work-paper-tracked-event-helpers.js';
+import { tryRenameWorkPaperSheetWithoutVisibilitySnapshots } from './work-paper-sheet-rename-fast-path.js';
+import { WORKPAPER_PUBLIC_ERROR_NAMES } from './work-paper-config.js';
+import { WorkPaperPublicSurface } from './work-paper-public-surface.js';
+export const EMPTY_NAMED_EXPRESSION_VALUES = new Map();
+export class WorkPaperRuntimeSurface extends WorkPaperPublicSurface {
+    getStats() {
+        this.assertNotDisposed();
+        return {
+            batchDepth: this.batchDepth,
+            evaluationSuspended: this.evaluationSuspended,
+            lastMetrics: structuredClone(this.engine.getLastMetrics()),
+        };
+    }
+    rebuildAndRecalculate() {
+        this.assertNotDisposed();
+        this.engineEvents.materializePendingLazyChanges();
+        if (this.shouldSuppressEvents()) {
+            try {
+                this.engine.recalculateNow();
+                this.sheetDimensionCache.invalidateAll();
+            }
+            catch (error) {
+                throw new WorkPaperOperationError(this.messageOf(error, 'Recalculation failed'));
+            }
+            return [];
+        }
+        const beforeVisibility = this.ensureVisibilityCache();
+        const beforeNames = this.namedExpressions.size > 0 ? this.ensureNamedExpressionValueCache() : EMPTY_NAMED_EXPRESSION_VALUES;
+        this.engineEvents.drain();
+        try {
+            this.engine.recalculateNow();
+            this.sheetDimensionCache.invalidateAll();
+        }
+        catch (error) {
+            throw new WorkPaperOperationError(this.messageOf(error, 'Recalculation failed'));
+        }
+        const afterVisibility = this.captureVisibilitySnapshot();
+        const afterNames = this.namedExpressions.size > 0 ? this.captureNamedExpressionValueSnapshot() : EMPTY_NAMED_EXPRESSION_VALUES;
+        this.visibilityCache = afterVisibility;
+        this.namedExpressionValueCache = afterNames;
+        const changes = [
+            ...this.computeCellChanges(beforeVisibility, afterVisibility),
+            ...this.computeNamedExpressionChanges(beforeNames, afterNames),
+        ];
+        if (changes.length > 0 && this.emitter.hasListeners('valuesUpdated')) {
+            this.emitter.emitDetailed({ eventName: 'valuesUpdated', payload: { changes } });
+        }
+        return changes;
+    }
+    batch(batchOperations) {
+        this.assertNotDisposed();
+        this.engineEvents.materializePendingLazyChanges();
+        const isOutermost = this.batchDepth === 0;
+        if (isOutermost) {
+            this.batchUsesTrackedFastPath = this.canUseTrackedMutationFastPath();
+            if (this.batchUsesTrackedFastPath) {
+                this.batchStartVisibility = null;
+                this.batchStartNamedValues = EMPTY_NAMED_EXPRESSION_VALUES;
+            }
+            else {
+                this.batchStartVisibility = this.ensureVisibilityCache();
+                this.batchStartNamedValues = this.ensureNamedExpressionValueCache();
+            }
+            this.batchUndoStackLength = this.getUndoStack().length;
+            this.engineEvents.drain();
+        }
+        this.batchDepth += 1;
+        try {
+            batchOperations();
+        }
+        finally {
+            this.batchDepth -= 1;
+            if (isOutermost) {
+                if (this.batchUsesTrackedFastPath) {
+                    this.engineEvents.withRetainedIndices(() => {
+                        this.flushPendingBatchOps();
+                    });
+                }
+                else {
+                    this.flushPendingBatchOps();
+                }
+                this.mergeUndoHistory(this.batchUndoStackLength);
+            }
+        }
+        if (!isOutermost) {
+            return [];
+        }
+        const shouldEmitValuesUpdated = this.emitter.hasListeners('valuesUpdated');
+        const changes = this.batchUsesTrackedFastPath
+            ? this.computeTrackedChangesWithoutVisibilityCache(this.engineEvents.drain(), {
+                preferLazyPublicChanges: !shouldEmitValuesUpdated,
+            })
+            : this.computeChangesAfterMutation(this.batchStartVisibility ?? new Map(), this.batchStartNamedValues ?? new Map());
+        this.batchUsesTrackedFastPath = false;
+        this.batchStartVisibility = null;
+        this.batchStartNamedValues = null;
+        if (!this.evaluationSuspended) {
+            this.flushQueuedEvents();
+            if (changes.length > 0 && shouldEmitValuesUpdated) {
+                this.emitter.emitDetailed({ eventName: 'valuesUpdated', payload: { changes } });
+            }
+        }
+        return changes;
+    }
+    suspendEvaluation() {
+        this.assertNotDisposed();
+        this.engineEvents.materializePendingLazyChanges();
+        if (this.evaluationSuspended) {
+            return;
+        }
+        this.evaluationSuspended = true;
+        this.flushPendingBatchOps();
+        if (this.visibilityCache === null && this.namedExpressions.size === 0) {
+            this.suspendedVisibility = null;
+            this.suspendedNamedValues = EMPTY_NAMED_EXPRESSION_VALUES;
+            this.suspendedUsesTrackedFastPath = true;
+        }
+        else {
+            this.suspendedVisibility = this.ensureVisibilityCache();
+            this.suspendedNamedValues = this.ensureNamedExpressionValueCache();
+            this.suspendedUsesTrackedFastPath = false;
+        }
+        this.engineEvents.drain();
+        this.emitter.emitDetailed({ eventName: 'evaluationSuspended', payload: {} });
+    }
+    resumeEvaluation() {
+        this.assertNotDisposed();
+        this.engineEvents.materializePendingLazyChanges();
+        if (!this.evaluationSuspended) {
+            return [];
+        }
+        if (this.suspendedUsesTrackedFastPath) {
+            this.engineEvents.withRetainedIndices(() => {
+                this.flushSuspendedCellMutations();
+            });
+        }
+        else {
+            this.flushSuspendedCellMutations();
+        }
+        const shouldEmitValuesUpdated = this.emitter.hasListeners('valuesUpdated');
+        const changes = this.suspendedUsesTrackedFastPath
+            ? this.computeTrackedChangesWithoutVisibilityCache(this.engineEvents.drain(), {
+                preferLazyPublicChanges: !shouldEmitValuesUpdated,
+            })
+            : this.computeChangesAfterMutation(this.suspendedVisibility ?? new Map(), this.suspendedNamedValues ?? new Map());
+        this.evaluationSuspended = false;
+        this.suspendedVisibility = null;
+        this.suspendedNamedValues = null;
+        this.suspendedUsesTrackedFastPath = false;
+        this.flushQueuedEvents();
+        this.emitter.emitDetailed({ eventName: 'evaluationResumed', payload: { changes } });
+        if (changes.length > 0 && shouldEmitValuesUpdated) {
+            this.emitter.emitDetailed({ eventName: 'valuesUpdated', payload: { changes } });
+        }
+        return changes;
+    }
+    isEvaluationSuspended() {
+        return this.evaluationSuspended;
+    }
+    undo() {
+        this.assertNotDisposed();
+        return this.applyHistoryOperation('undo');
+    }
+    redo() {
+        this.assertNotDisposed();
+        return this.applyHistoryOperation('redo');
+    }
+    isThereSomethingToUndo() {
+        return this.getUndoStack().length > 0;
+    }
+    isThereSomethingToRedo() {
+        return this.getRedoStack().length > 0;
+    }
+    clearUndoStack() {
+        this.getUndoStack().length = 0;
+    }
+    clearRedoStack() {
+        this.getRedoStack().length = 0;
+    }
+    getCellDependents(address) {
+        this.flushPendingBatchOps();
+        if (!isCellRange(address)) {
+            return this.toDependencyRefs(this.engine.getDependents(this.sheetName(address.sheet), this.a1(address)).directDependents);
+        }
+        return this.collectRangeDependencies(address, (cellAddress) => this.engine.getDependents(this.sheetName(cellAddress.sheet), this.a1(cellAddress)).directDependents);
+    }
+    getCellPrecedents(address) {
+        this.flushPendingBatchOps();
+        if (!isCellRange(address)) {
+            return this.getDirectPrecedentRefs(address);
+        }
+        return this.collectRangeDependencies(address, (cellAddress) => this.getDirectPrecedentStrings(cellAddress));
+    }
+    getSheetName(sheetId) {
+        return this.engine.workbook.getSheetById(sheetId)?.name;
+    }
+    getSheetNames() {
+        return this.listSheetRecords().map((sheet) => sheet.name);
+    }
+    getSheetId(name) {
+        return this.engine.workbook.getSheet(name)?.id;
+    }
+    doesSheetExist(name) {
+        return this.engine.workbook.getSheet(name) !== undefined;
+    }
+    countSheets() {
+        return this.listSheetRecords().length;
+    }
+    moveCells(source, target) {
+        if (!this.isItPossibleToMoveCells(source, target)) {
+            throw new WorkPaperOperationError('Cells cannot be moved');
+        }
+        const sourceHeight = source.end.row - source.start.row;
+        const sourceWidth = source.end.col - source.start.col;
+        return this.captureChanges(undefined, () => {
+            this.engine.moveRange(sourceRangeRef(this.sheetName(source.start.sheet), source), {
+                sheetName: this.sheetName(target.sheet),
+                startAddress: formatAddress(target.row, target.col),
+                endAddress: formatAddress(target.row + sourceHeight, target.col + sourceWidth),
+            });
+            this.sheetDimensionCache.invalidate(source.start.sheet);
+            this.sheetDimensionCache.invalidate(target.sheet);
+        });
+    }
+    applyHistoryOperation(kind) {
+        return applyWorkPaperHistoryOperation({
+            getStack: () => (kind === 'undo' ? this.getUndoStack() : this.getRedoStack()),
+            canUseTrackedMutationFastPath: () => this.canUseTrackedMutationFastPath(),
+            captureTrackedChangesWithoutVisibilityCache: (mutate, options) => this.captureTrackedChangesWithoutVisibilityCache(mutate, options),
+            captureChanges: (mutate, options) => this.captureChanges(undefined, mutate, options),
+            applyOperation: () => (kind === 'undo' ? this.engine.undo() : this.engine.redo()),
+            createMissingOperationError: () => (kind === 'undo' ? new WorkPaperNoOperationToUndoError() : new WorkPaperNoOperationToRedoError()),
+            invalidateAllSheetDimensions: () => this.sheetDimensionCache.invalidateAll(),
+        });
+    }
+    resetChangeTrackingCaches() {
+        this.sheetRecordsCache = null;
+        this.visibilityCache = null;
+        this.namedExpressionValueCache = null;
+        this.engineEvents.clearEvents();
+    }
+    ensureVisibilityCache() {
+        if (!this.visibilityCache) {
+            this.visibilityCache = this.captureVisibilitySnapshot();
+        }
+        return this.visibilityCache;
+    }
+    ensureNamedExpressionValueCache() {
+        if (!this.namedExpressionValueCache) {
+            this.namedExpressionValueCache =
+                this.namedExpressions.size > 0 ? this.captureNamedExpressionValueSnapshot() : EMPTY_NAMED_EXPRESSION_VALUES;
+        }
+        return this.namedExpressionValueCache;
+    }
+    flushPendingBatchOps() {
+        this.mutationQueues.flushPendingBatchOps();
+    }
+    applyCellMutationRefs(refs, options) {
+        applyWorkPaperCellMutationRefs(this.runtimeAdapters.cellMutationApplyRuntime, refs, options);
+    }
+    flushSuspendedCellMutations() {
+        this.mutationQueues.flushSuspendedCellMutations();
+    }
+    enqueueSuspendedLiteralMutation(sheetId, row, col, content, cellIndex) {
+        return (this.evaluationSuspended &&
+            this.mutationQueues.enqueueSuspendedLiteralMutation({
+                sheetId,
+                row,
+                col,
+                content,
+                cellIndex,
+            }));
+    }
+    enqueueDeferredBatchLiteral(sheetId, row, col, content, cellIndex) {
+        return (this.batchDepth !== 0 &&
+            !this.evaluationSuspended &&
+            this.mutationQueues.enqueueDeferredBatchLiteral({
+                sheetId,
+                row,
+                col,
+                content,
+                cellIndex,
+            }));
+    }
+    prepareReadableState() {
+        this.assertNotDisposed();
+        this.flushPendingBatchOps();
+    }
+    assertNotDisposed() {
+        if (this.disposed) {
+            throw new WorkPaperOperationError('Workbook has been disposed');
+        }
+    }
+    assertReadable() {
+        this.prepareReadableState();
+        if (this.evaluationSuspended) {
+            throw new WorkPaperEvaluationSuspendedError();
+        }
+    }
+    sheetRecord(sheetId) {
+        const sheet = this.engine.workbook.getSheetById(sheetId);
+        if (!sheet) {
+            throw new WorkPaperNoSheetWithIdError(sheetId);
+        }
+        return sheet;
+    }
+    sheetName(sheetId) {
+        return this.sheetRecord(sheetId).name;
+    }
+    capabilityContext() {
+        return {
+            config: this.config,
+            requireSheet: (sheetId) => {
+                void this.sheetRecord(sheetId);
+            },
+            doesSheetExist: (sheetName) => this.doesSheetExist(sheetName),
+            getSheetIdByName: (sheetName) => this.getSheetId(sheetName),
+        };
+    }
+    requireSheetId(name) {
+        const sheetId = this.getSheetId(name);
+        if (sheetId === undefined) {
+            throw new WorkPaperNoSheetWithNameError(name);
+        }
+        return sheetId;
+    }
+    a1(address) {
+        return formatAddress(address.row, address.col);
+    }
+    trackedA1(row, col) {
+        return formatTrackedA1(row, col);
+    }
+    rangeRef(range) {
+        assertRange(range);
+        return sourceRangeRef(this.sheetName(range.start.sheet), range);
+    }
+    getDirectPrecedentStrings(address) {
+        const precedents = new Set(this.engine.getDependencies(this.sheetName(address.sheet), this.a1(address)).directPrecedents);
+        const formula = this.getCellFormula(address);
+        if (formula) {
+            this.getNamedExpressionsFromFormula(formula).forEach((name) => {
+                precedents.add(name);
+            });
+        }
+        return [...precedents];
+    }
+    getDirectPrecedentRefs(address) {
+        return this.toDependencyRefs(this.getDirectPrecedentStrings(address));
+    }
+    listSheetRecords() {
+        if (this.sheetRecordsCache) {
+            return this.sheetRecordsCache;
+        }
+        this.sheetRecordsCache = [...this.engine.workbook.sheetsByName.values()].toSorted((left, right) => left.order - right.order || left.name.localeCompare(right.name));
+        return this.sheetRecordsCache;
+    }
+    captureVisibilitySnapshot() {
+        return captureWorkPaperVisibilitySnapshot({
+            sheets: this.listSheetRecords(),
+            cellStore: this.engine.workbook.cellStore,
+            strings: this.engine.strings,
+        });
+    }
+    captureNamedExpressionValueSnapshot() {
+        if (this.namedExpressions.size === 0) {
+            return EMPTY_NAMED_EXPRESSION_VALUES;
+        }
+        return captureWorkPaperNamedExpressionValueSnapshot(this.namedExpressions.values(), (expression) => this.evaluateNamedExpression(expression));
+    }
+    computeCellChanges(beforeVisibility, afterVisibility) {
+        return computeWorkPaperCellChangesFromVisibilitySnapshots({
+            beforeVisibility,
+            afterVisibility,
+            sheets: this.listSheetRecords(),
+        });
+    }
+    materializeTrackedEventChanges(event, lazy = false) {
+        if (event.patches && event.patches.length > 0) {
+            const cellPatches = event.patches.filter((patch) => patch.kind === 'cell');
+            return { changes: cellPatches, canReusePublicChanges: false, ordered: false };
+        }
+        const trustedPhysicalMetadata = lazy && event.changedCellIndices instanceof Uint32Array
+            ? readTrustedPhysicalTrackedChangeMetadata(event.changedCellIndices)
+            : undefined;
+        const materialized = materializeTrackedIndexChangesWithMetadata(this.engine, event.changedCellIndices, {
+            lazy,
+            ...(event.explicitChangedCount !== undefined ? { explicitChangedCount: event.explicitChangedCount } : {}),
+            ...trustedPhysicalMetadata,
+        });
+        if (lazy) {
+            this.engineEvents.trackLazyChanges(materialized.changes);
+        }
+        return {
+            changes: materialized.changes,
+            canReusePublicChanges: true,
+            ordered: materialized.ordered,
+        };
+    }
+    readSingleTrackedCellChange(cellIndex) {
+        return readTrackedCellChange({
+            cellIndex,
+            workbook: this.engine.workbook,
+            strings: this.engine.strings,
+            trackedA1: (row, col) => this.trackedA1(row, col),
+        });
+    }
+    readTinySortedPhysicalTrackedEventChanges(event) {
+        return readTinySortedPhysicalTrackedEventChangesFromStore({
+            event,
+            workbook: this.engine.workbook,
+            strings: this.engine.strings,
+            trackedA1: (row, col) => this.trackedA1(row, col),
+        });
+    }
+    tryReadTinyTrackedEventChangesWithoutVisibility(event) {
+        return tryReadTinyTrackedEventChangesWithoutVisibilityFromReducer({
+            event,
+            listSheets: () => this.listSheetRecords(),
+            materializeTrackedEventChanges: (trackedEvent, lazy) => this.materializeTrackedEventChanges(trackedEvent, lazy),
+            readSingleTrackedCellChange: (cellIndex) => this.readSingleTrackedCellChange(cellIndex),
+            readTinySortedPhysicalTrackedEventChanges: (trackedEvent) => this.readTinySortedPhysicalTrackedEventChanges(trackedEvent),
+            sheetOrder: (sheetId) => this.sheetRecord(sheetId).order,
+        });
+    }
+    computeCellChangesFromTrackedEvents(beforeVisibility, events, updateVisibility = true, options = {}) {
+        return computeWorkPaperTrackedCellChangesFromEvents({
+            beforeVisibility,
+            events,
+            updateVisibility,
+            ...(options.preferLazyPublicChanges !== undefined ? { preferLazyPublicChanges: options.preferLazyPublicChanges } : {}),
+            listSheets: () => this.listSheetRecords(),
+            materializeTrackedEventChanges: (event, lazy) => this.materializeTrackedEventChanges(event, lazy),
+            materializeTrackedEventSources: (trackedEvents, sourceOptions) => {
+                const materializedSources = materializeTrackedIndexChangeSourcesWithMetadata(this.engine, trackedEvents, {
+                    deferLazyDetach: true,
+                    ...(sourceOptions.preferLazyPublicChanges !== undefined ? { lazy: sourceOptions.preferLazyPublicChanges } : {}),
+                });
+                if (!materializedSources) {
+                    return null;
+                }
+                this.engineEvents.trackLazyChanges(materializedSources.changes);
+                return materializedSources;
+            },
+            readSingleTrackedCellChange: (cellIndex) => this.readSingleTrackedCellChange(cellIndex),
+            readTinySortedPhysicalTrackedEventChanges: (event) => this.readTinySortedPhysicalTrackedEventChanges(event),
+            sheetOrder: (sheetId) => this.sheetRecord(sheetId).order,
+        });
+    }
+    computeNamedExpressionChanges(beforeNames, afterNames) {
+        return computeWorkPaperNamedExpressionChanges({
+            beforeNames,
+            afterNames,
+            expressionsByKey: this.namedExpressions,
+        });
+    }
+    canUseTrackedStructuralFastPath() {
+        return this.batchDepth === 0 && !this.evaluationSuspended && this.visibilityCache === null && this.namedExpressions.size === 0;
+    }
+    canUseTrackedMutationFastPath() {
+        return this.batchDepth === 0 && !this.evaluationSuspended && this.visibilityCache === null && this.namedExpressions.size === 0;
+    }
+    canUseNamedExpressionChangeFastPath() {
+        return this.batchDepth === 0 && !this.evaluationSuspended && this.visibilityCache === null && !this.emitter.hasAnyListeners();
+    }
+    canUseMetadataOnlySheetRenameFastPath() {
+        return this.batchDepth === 0 && !this.evaluationSuspended && this.visibilityCache === null && !this.emitter.hasAnyListeners();
+    }
+    downgradeTrackedBatchFastPath() {
+        if (!this.batchUsesTrackedFastPath || this.batchDepth === 0) {
+            return;
+        }
+        this.batchStartVisibility = this.ensureVisibilityCache();
+        this.batchStartNamedValues = this.namedExpressions.size > 0 ? this.ensureNamedExpressionValueCache() : EMPTY_NAMED_EXPRESSION_VALUES;
+        this.batchUsesTrackedFastPath = false;
+    }
+    computeTrackedChangesWithoutVisibilityCache(events, options = {}) {
+        if (events.length > 0 && events.every(trackedEventHasNoValueChanges)) {
+            return [];
+        }
+        if (events.length === 1) {
+            const event = events[0];
+            if (!options.preferLazyPublicChanges || event.changedCellIndices.length <= TINY_TRACKED_CHANGE_LIMIT) {
+                const tinyChanges = this.tryReadTinyTrackedEventChangesWithoutVisibility(event);
+                if (tinyChanges) {
+                    return tinyChanges;
+                }
+            }
+        }
+        const fastPath = this.computeCellChangesFromTrackedEvents(new Map(), events, false, options);
+        if (!fastPath) {
+            throw new WorkPaperOperationError('Mutation emitted an unsupported invalidation pattern for tracked changes');
+        }
+        return fastPath.changes;
+    }
+    tryRenameSheetWithoutVisibilitySnapshots(oldName, newName) {
+        return tryRenameWorkPaperSheetWithoutVisibilitySnapshots(this.runtimeAdapters.sheetRenameFastPathRuntime, oldName, newName);
+    }
+    captureTrackedChangesWithoutVisibilityCache(mutate, options = {}) {
+        this.assertNotDisposed();
+        if (this.engineEvents.hasPendingLazyChanges) {
+            this.engineEvents.materializePendingLazyChanges(options.preservePendingTrackedPositions === undefined ? {} : { preservePositions: options.preservePendingTrackedPositions });
+        }
+        if (this.engineEvents.hasTrackedEvents) {
+            this.engineEvents.drain();
+        }
+        try {
+            this.engineEvents.withRetainedIndices(mutate);
+        }
+        catch (error) {
+            if (error instanceof Error && WORKPAPER_PUBLIC_ERROR_NAMES.has(error.name)) {
+                throw error;
+            }
+            throw new WorkPaperOperationError(this.messageOf(error, 'Mutation failed'));
+        }
+        const events = this.engineEvents.drain();
+        const directSingleLiteralChanges = tryBuildDirectSingleLiteralTrackedChange({
+            events,
+            ...(options.singleLiteralChange !== undefined ? { expected: options.singleLiteralChange } : {}),
+            cellStore: this.engine.workbook.cellStore,
+            strings: this.engine.strings,
+            trackedA1: (row, col) => this.trackedA1(row, col),
+        });
+        if (directSingleLiteralChanges) {
+            if (directSingleLiteralChanges.length > 0 && this.emitter.hasListeners('valuesUpdated')) {
+                this.emitter.emitDetailed({ eventName: 'valuesUpdated', payload: { changes: directSingleLiteralChanges } });
+            }
+            return directSingleLiteralChanges;
+        }
+        const shouldEmitValuesUpdated = this.emitter.hasListeners('valuesUpdated');
+        const changes = this.computeTrackedChangesWithoutVisibilityCache(events, {
+            preferLazyPublicChanges: !shouldEmitValuesUpdated,
+        });
+        if (changes.length > 0 && shouldEmitValuesUpdated) {
+            this.emitter.emitDetailed({ eventName: 'valuesUpdated', payload: { changes } });
+        }
+        return changes;
+    }
+    batchStructuralChanges(batchOperations) {
+        this.engineEvents.materializePendingLazyChanges();
+        if (!this.canUseTrackedStructuralFastPath()) {
+            this.downgradeTrackedBatchFastPath();
+            return this.batch(batchOperations);
+        }
+        this.assertNotDisposed();
+        const undoStackStart = this.getUndoStack().length;
+        this.engineEvents.drain();
+        this.batchDepth += 1;
+        try {
+            this.engineEvents.withRetainedIndices(batchOperations);
+        }
+        finally {
+            this.batchDepth -= 1;
+            this.flushPendingBatchOps();
+            this.mergeUndoHistory(undoStackStart);
+        }
+        const shouldEmitValuesUpdated = this.emitter.hasListeners('valuesUpdated');
+        const changes = this.computeTrackedChangesWithoutVisibilityCache(this.engineEvents.drain(), {
+            preferLazyPublicChanges: !shouldEmitValuesUpdated,
+        });
+        this.flushQueuedEvents();
+        if (changes.length > 0 && shouldEmitValuesUpdated) {
+            this.emitter.emitDetailed({ eventName: 'valuesUpdated', payload: { changes } });
+        }
+        return changes;
+    }
+    computeChangesAfterMutation(beforeVisibility, beforeNames) {
+        const hasNamedExpressions = this.namedExpressions.size > 0;
+        const afterNames = hasNamedExpressions ? this.captureNamedExpressionValueSnapshot() : EMPTY_NAMED_EXPRESSION_VALUES;
+        const fastPath = this.computeCellChangesFromTrackedEvents(beforeVisibility, this.engineEvents.drain());
+        let cellChanges;
+        if (fastPath) {
+            cellChanges = fastPath.changes;
+            this.visibilityCache = fastPath.nextVisibility;
+        }
+        else {
+            const afterVisibility = this.captureVisibilitySnapshot();
+            cellChanges = this.computeCellChanges(beforeVisibility, afterVisibility);
+            this.visibilityCache = afterVisibility;
+        }
+        this.namedExpressionValueCache = afterNames;
+        return hasNamedExpressions ? [...cellChanges, ...this.computeNamedExpressionChanges(beforeNames, afterNames)] : cellChanges;
+    }
+    captureChanges(semanticEvent, mutate, options = {}) {
+        this.assertNotDisposed();
+        this.engineEvents.materializePendingLazyChanges(options.preservePendingTrackedPositions === undefined ? {} : { preservePositions: options.preservePendingTrackedPositions });
+        this.downgradeTrackedBatchFastPath();
+        if (semanticEvent !== undefined) {
+            this.flushPendingBatchOps();
+        }
+        if (this.shouldSuppressEvents()) {
+            try {
+                mutate();
+            }
+            catch (error) {
+                if (error instanceof Error && WORKPAPER_PUBLIC_ERROR_NAMES.has(error.name)) {
+                    throw error;
+                }
+                throw new WorkPaperOperationError(this.messageOf(error, 'Mutation failed'));
+            }
+            if (semanticEvent) {
+                this.queuedEvents.push(semanticEvent);
+            }
+            return [];
+        }
+        const beforeVisibility = this.ensureVisibilityCache();
+        const beforeNames = this.namedExpressions.size > 0 ? this.ensureNamedExpressionValueCache() : EMPTY_NAMED_EXPRESSION_VALUES;
+        this.engineEvents.drain();
+        try {
+            mutate();
+        }
+        catch (error) {
+            if (error instanceof Error && WORKPAPER_PUBLIC_ERROR_NAMES.has(error.name)) {
+                throw error;
+            }
+            throw new WorkPaperOperationError(this.messageOf(error, 'Mutation failed'));
+        }
+        const changes = semanticEvent === undefined
+            ? this.computeChangesAfterMutation(beforeVisibility, beforeNames)
+            : (() => {
+                const afterVisibility = this.captureVisibilitySnapshot();
+                const afterNames = this.captureNamedExpressionValueSnapshot();
+                this.visibilityCache = afterVisibility;
+                this.namedExpressionValueCache = afterNames;
+                return [
+                    ...this.computeCellChanges(beforeVisibility, afterVisibility),
+                    ...this.computeNamedExpressionChanges(beforeNames, afterNames),
+                ];
+            })();
+        if (semanticEvent) {
+            const event = withEventChanges(semanticEvent, changes);
+            if (this.shouldSuppressEvents()) {
+                this.queuedEvents.push(event);
+            }
+            else {
+                this.emitter.emitDetailed(event);
+            }
+        }
+        if (!this.shouldSuppressEvents() && changes.length > 0 && this.emitter.hasListeners('valuesUpdated')) {
+            this.emitter.emitDetailed({ eventName: 'valuesUpdated', payload: { changes } });
+        }
+        return changes;
+    }
+    shouldSuppressEvents() {
+        return this.batchDepth > 0 || this.evaluationSuspended;
+    }
+    flushQueuedEvents() {
+        const events = [...this.queuedEvents];
+        this.queuedEvents.length = 0;
+        events.forEach((event) => {
+            this.emitter.emitDetailed(event);
+        });
+    }
+    getUndoStack() {
+        return readWorkPaperHistoryStack(this.engine, 'undoStack');
+    }
+    getRedoStack() {
+        return readWorkPaperHistoryStack(this.engine, 'redoStack');
+    }
+    clearHistoryStacks() {
+        clearWorkPaperHistoryStacks(this.getUndoStack(), this.getRedoStack());
+    }
+    mergeUndoHistory(startIndex) {
+        mergeWorkPaperUndoHistory(this.getUndoStack(), startIndex, (sheetId) => this.getSheetName(sheetId));
+    }
+    nextSheetName() {
+        let index = 1;
+        while (this.doesSheetExist(`Sheet${index}`)) {
+            index += 1;
+        }
+        return `Sheet${index}`;
+    }
+    collectRangeDependencies(range, readDependencies) {
+        return collectWorkPaperRangeDependencies({
+            range,
+            readDependencies,
+            resolver: {
+                defaultSheetName: () => this.listSheetRecords()[0].name,
+                requireSheetId: (name) => this.requireSheetId(name),
+            },
+        });
+    }
+    toDependencyRefs(values) {
+        return toWorkPaperDependencyRefs(values, {
+            defaultSheetName: () => this.listSheetRecords()[0].name,
+            requireSheetId: (name) => this.requireSheetId(name),
+        });
+    }
+}
+//# sourceMappingURL=work-paper-runtime-surface.js.map