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

package/types/src/sheet/WorksheetCollection.d.ts

@@ -0,0 +1,39 @@
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
+import { IWorksheetCollection } from './IWorksheetCollection';
+import { IWorksheet } from './IWorksheet';
+import { ISheet } from './ISheet';
+/**
+ * Implementation for {@link IWorksheetCollection}.
+ *
+ * @remarks
+ * A front over the workbook's own sheet state — the workbook keeps the store and the events,
+ * this class keeps the API. `onCollectionChange` is the workbook's `onSheetsChange`, forwarded
+ * with this collection as the source.
+ */
+export declare class WorksheetCollection extends AbstractCollection<IWorksheet, IWorksheetCollection.GetItemsOptions> implements IWorksheetCollection {
+    private _add;
+    private _get;
+    private _addListeners;
+    private _getSelected;
+    constructor(add: (options: IWorksheetCollection.AddOptions | string | number) => IWorksheet, get: (name?: string, visibility?: ISheet.Visibility) => IWorksheet[], addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove, getSelected: () => IWorksheet | null);
+    /** {@inheritDoc IWorksheetCollection.getActive} */
+    getActive(): IWorksheet | null;
+    /** {@inheritDoc IWorksheetCollection.getAt} */
+    getAt(index: number): IWorksheet | null;
+    /** {@inheritDoc IWorksheetCollection.getByIndex} */
+    getByIndex(index: number): IWorksheet | null;
+    /** {@inheritDoc IWorksheetCollection.getAll} */
+    getAll(): IWorksheet[];
+    /** {@inheritDoc IWorksheetCollection.add} */
+    add(options?: IWorksheetCollection.AddOptions | string | number): IWorksheet;
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IWorksheetCollection.GetItemsOptions): IWorksheet[];
+    /** {@inheritDoc IWorksheetCollection.getByName} */
+    getByName(name: string): IWorksheet;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IWorksheetCollection.isIWorksheetCollection} */
+    get isIWorksheetCollection(): true;
+}
+//# sourceMappingURL=WorksheetCollection.d.ts.map

package/types/src/sheet/_CellBuffer.d.ts

@@ -6,7 +6,7 @@ import { ICellRange } from '../cellRange';
 import { ICell } from '../cell';
 import { ICellStyle } from '../style';
 import { InternalTupleUpdate } from './_SheetStateTypes';
-import { SheetMutationContext } from './Sheet';
+import { SheetMutationContext } from './Worksheet';
 import { ScanStyleUpdate } from './_SheetMutations';
 /**
  * What {@link CellBuffer} needs from its sheet.
@@ -34,6 +34,11 @@ export interface CellBufferContext {
     isLocalStyle(transaction: ITransaction, rowIndex: number, colIndex: number, update: ICellStyle.Update): boolean;
     /** What the sheet's cell writes are made through; the held ones are scanned and written with it. */
     getMutations(): SheetMutationContext;
+    /**
+     * Whether a write is to be made as it comes: a batch it would be held in is told of each of its
+     * steps, and a held write would be told late.
+     */
+    isMadeAsItComes(): boolean;
 }
 /**
  * Single-cell writes made inside an open transaction, held and made as ONE write when something
@@ -163,6 +168,11 @@ export declare class CellBuffer {
     getGeneration(): number;
     /** Makes the held writes, as one. */
     flush(): void;
+    /**
+     * Makes the held writes and closes the transaction they were held in, so what is written next is
+     * not nested in it. A transaction still open inside that one keeps it open.
+     */
+    release(): void;
     /** Drops the held writes: the transaction they were made in rolled back, or the sheet closed. */
     discard(): void;
     private _toRange;

package/types/src/sheet/_CopyUtils.d.ts

@@ -1,8 +1,8 @@
 import { IRange } from '@sheetxl/primitives';
 import { IMovable } from '../movable';
 import { ICellRange, ICellHeaderRange } from '../cellRange';
-import { ISheet } from './ISheet';
-import { Sheet } from './Sheet';
+import { IWorksheet } from './IWorksheet';
+import { Worksheet } from './Worksheet';
 /**
  * The pasted images of `areas` (absolute ranges within the marked source `coordFrom`):
  * each area's offset within the source, tiled across the fitted destination `rangeTo` with
@@ -15,19 +15,26 @@ import { Sheet } from './Sheet';
  * is already LCM-expanded or clipped, so tiling here is a pure function of the two ranges.
  */
 export declare function tileMarkedAreas(areas: readonly IRange.Coords[], coordFrom: Readonly<IRange.Coords>, rangeTo: Readonly<IRange.Coords>, transpose?: boolean): IRange.Coords[];
+/**
+ * Runs every part's `prepare`, and waits only when one of them has something to wait for: with
+ * nothing to prepare, the paste stays in its caller's synchronous extent.
+ */
+export declare function prepareParts<D, O>(parts: readonly {
+    prepare?(destination: D, options?: O): Promise<void> | void;
+}[], destination: D, options?: O): Promise<void> | void;
 /**
  * Converts a header snapshot to sheet.
  */
 export declare function headerToSheetSnapshot(rangeMark: ICellHeaderRange, coordMark: IRange.Coords, optionsMark: ICellHeaderRange.CopyOptions): Partial<ICellRange.ISnapshot>;
 /**
- * Wraps a copySheetTo function into a ISheet.ISnapshot.
+ * Wraps a copySheetTo function into a IWorksheet.ISnapshot.
  * * This will error if snapshot is a cut and called a second.
  * @internal
  */
-export declare function callbackToSheetSnapshot(sheetFrom: ISheet, sheetMark: ISheet, coordsFrom: readonly IRange.Coords[], description: string, optionsMark: ICellRange.CopyOptions, copySheetTo: (sheetRange: ICellRange, options?: ICellRange.CopyOptions) => Promise<IRange.Coords> | IRange.Coords): ICellRange.ISnapshot;
+export declare function callbackToSheetSnapshot(sheetFrom: IWorksheet, sheetMark: IWorksheet, coordsFrom: readonly IRange.Coords[], description: string, optionsMark: ICellRange.CopyOptions, copySheetTo: (sheetRange: ICellRange, options?: ICellRange.CopyOptions) => IRange.Coords): ICellRange.ISnapshot;
 /**
  * Converts an array of Snapshots into a single snapshot.
  */
-export declare function arrToSheetSnapshot(snapshots: Partial<ICellRange.ISnapshot>[], sheet: ISheet, sheetMark: ISheet, coordsMark: IRange.Coords, optionsMark: ICellRange.CopyOptions, descriptionMark: string, snapshotNative?: ICellRange.ISnapshot | null): ICellRange.ISnapshot;
-export declare function movablesToSheetSnapshot(sheetMark: Sheet, coordsMark: readonly IRange.Coords[], movablesSelectionMark: readonly IMovable[], markOptions: ICellRange.CopyOptions): ICellRange.ISnapshot<ISheet> | null;
+export declare function arrToSheetSnapshot(snapshots: Partial<ICellRange.ISnapshot>[], sheet: IWorksheet, sheetMark: IWorksheet, coordsMark: IRange.Coords, optionsMark: ICellRange.CopyOptions, descriptionMark: string, snapshotNative?: ICellRange.ISnapshot | null): ICellRange.ISnapshot;
+export declare function movablesToSheetSnapshot(sheetMark: Worksheet, coordsMark: readonly IRange.Coords[], movablesSelectionMark: readonly IMovable[], markOptions: ICellRange.CopyOptions): ICellRange.ISnapshot<IWorksheet> | null;
 //# sourceMappingURL=_CopyUtils.d.ts.map

package/types/src/sheet/_IgnoredErrors.d.ts

@@ -0,0 +1,46 @@
+import { IRange } from '@sheetxl/primitives';
+import { CoordUtils } from '@sheetxl/utils';
+import { ICell } from '../cell';
+import { ISpatialMap } from '../collections';
+import { IWorksheet } from './IWorksheet';
+/**
+ * The checks a cell ignores, interned: equal sets are one object, in the schema's order, so a
+ * region's payload identity is its content and two fragments of one ignore regroup.
+ * @internal
+ */
+export type ErrorCheckSet = readonly ICell.ErrorCheck[];
+/** The interned set of `checks`; `null` for none (an unknown name is dropped). */
+export declare function internChecks(checks: Iterable<ICell.ErrorCheck>): ErrorCheckSet | null;
+/**
+ * The cells where Excel's error checks are ignored: one spatial map whose payload is the set of
+ * checks a cell ignores. Presence is the ignore; an entry goes when its set empties. Immutable;
+ * each change returns a new holder.
+ *
+ * @remarks
+ * Excel's rules (`openpy-parity/probe-ignored-errors.ps1`, 2026-10-18): the regions move with
+ * structural edits like cell content, an insert inside one splitting it; they are never copied
+ * (copy, paste, fill, the destination of a cut); and writing or clearing a cell, contents or
+ * formats, removes its ignores.
+ * @internal
+ */
+export declare class IgnoredErrors {
+    static readonly Empty: IgnoredErrors;
+    private readonly _map;
+    private constructor();
+    /** From {@link IWorksheet.JSON.ignoredErrors}; references that overlap ignore the union. */
+    static fromJSON(json: IWorksheet.JSON['ignoredErrors'], entireCoords: IRange.Coords): IgnoredErrors;
+    isEmpty(): boolean;
+    /** The map, for the sheet's range-state readers; `null` when nothing is ignored. */
+    getMap(): ISpatialMap<ErrorCheckSet> | null;
+    /** The checks `cell` ignores, or `null`. */
+    getAt(cell: IRange.CellCoords): ErrorCheckSet | null;
+    /** With `check` ignored, or no longer ignored, over `ranges`. */
+    set(ranges: readonly IRange.Coords[], check: ICell.ErrorCheck, ignored: boolean): IgnoredErrors;
+    /** Shifted by a structural edit of `ranges`, one range at a time, in order. */
+    shift(ranges: readonly IRange.Coords[], direction: IRange.Direction, coordValidator?: CoordUtils.CoordValidator): IgnoredErrors;
+    /** Without any ignore over `ranges`, for cells written or cleared. */
+    remove(...touched: (readonly IRange.Coords[])[]): IgnoredErrors;
+    /** As {@link IWorksheet.JSON.ignoredErrors}, in range order, or `null` when nothing is ignored. */
+    toJSON(entireCoords: IRange.Coords): IWorksheet.JSON['ignoredErrors'] | null;
+}
+//# sourceMappingURL=_IgnoredErrors.d.ts.map

package/types/src/sheet/_InvalidSheetRange.d.ts

@@ -2,13 +2,13 @@ import { IRange, Scalar, IRangeStats } from '@sheetxl/primitives';
 import { IListener } from '../listener';
 import { ICellStyle } from '../style';
 import { ICell } from '../cell';
-import { ISheet } from './ISheet';
+import { IWorksheet } from './IWorksheet';
 import { ICellRange, ICellRegions, ICellRanges, ICellHeaderRanges } from '../cellRange';
 import { SheetRanges, SheetRangesOptions } from './SheetRanges';
 export declare function RETURN_FALSE(): boolean;
 export declare function RETURN_TRUE(): boolean;
 export declare function RETURN_NULL(): any;
-export declare function getInvalidCell(sheet: ISheet | null): ICell;
+export declare function getInvalidCell(sheet: IWorksheet | null): ICell;
 /**
  * This is for 0 size ranges.
  * @internal
@@ -42,6 +42,7 @@ export declare class InvalidSheetRanges extends SheetRanges {
     getStats(): IRangeStats;
     getCounts(): ICellRange.Counts;
     getRegions(): ICellRegions;
+    getAnomalies(): ICellRegions;
     getDirectPrecedents(): Promise<ICellRanges | null>;
     getDirectDependents(): Promise<ICellRanges | null>;
     getPrecedents(): Promise<ICellRanges | null>;

package/types/src/sheet/_Kinds.d.ts

@@ -0,0 +1,34 @@
+import { Scalar } from '@sheetxl/primitives';
+import { ISparseGrid, ISpatialMap, ISpatialQuery } from '../collections';
+/**
+ * What a cell holds (`ICellRange.Feature.Kind`). A formula cell is the kind of its result.
+ * @internal
+ */
+export declare const CellKind: {
+    readonly Number: "number";
+    /** A number under a date or time format. */
+    readonly Date: "date";
+    readonly Text: "text";
+    /** Text a typed entry would read as a number: Excel's number stored as text. */
+    readonly NumberText: "numberText";
+    readonly Boolean: "boolean";
+    readonly Error: "error";
+    readonly RichData: "richData";
+};
+/** @internal */
+export type CellKind = typeof CellKind[keyof typeof CellKind];
+/** What the kinds are read from. @internal */
+export interface KindSource {
+    readonly values: ISparseGrid<Scalar>;
+    /** The date-category number formats, by where they are applied. */
+    readonly dateFormats: ISpatialQuery<string>;
+    /** The number a text would enter as if typed, or `null`. */
+    parseNumber(text: string): number | null;
+}
+/**
+ * The kind partition of one sheet: one scan of the values, the same pass the reconciled error
+ * view makes, then the numbers under a date format become dates.
+ * @internal
+ */
+export declare function buildKinds(source: KindSource): ISpatialMap<CellKind>;
+//# sourceMappingURL=_Kinds.d.ts.map

package/types/src/sheet/_Labels.d.ts

@@ -0,0 +1,38 @@
+import { IRange } from '@sheetxl/primitives';
+import { IWorksheet } from './IWorksheet';
+/**
+ * A label and where it was read from.
+ * @internal
+ */
+export interface FoundLabel {
+    /** The label as the cell shows it. */
+    readonly text: string;
+    /** The label's cell, `B4`. */
+    readonly address: string;
+    readonly coords: IRange.CellCoords;
+}
+/**
+ * The text that labels a cell's row (`'row'`) or column (`'column'`).
+ *
+ * @remarks
+ * Deterministic, and the address is always returned so a reader can judge it:
+ *
+ * 1. The first cell of the line within the cell's current region (Ctrl+Shift+*), when it is text —
+ *    the row label at the left edge of the block, the header at its top.
+ * 2. Otherwise the first cell of each earlier run of filled cells on that line, nearest first —
+ *    leftward for a row, upward for a column — when it is text. Only a run's edge is read: a text
+ *    in the middle of a run of values (a scenario name, a unit) is part of the data, not the line's
+ *    label. The cost is the runs on the line, not its cells; there is no cap, because a cap is
+ *    only a different arbitrary answer.
+ *
+ * `null` when the cell is itself the first cell of the line or no run before it starts with text.
+ * @internal
+ */
+export declare function findLabel(sheet: IWorksheet, cell: IRange.CellCoords, axis: 'row' | 'column'): FoundLabel | null;
+/**
+ * A label reduced to what two labels are compared on: case, punctuation and runs of space
+ * dropped, so `Total Revenue:` and `total  revenue` agree.
+ * @internal
+ */
+export declare const normalizeLabel: (text: string) => string;
+//# sourceMappingURL=_Labels.d.ts.map

package/types/src/sheet/_ListenerAnchor.d.ts

@@ -92,12 +92,18 @@ export declare namespace ListenerAnchor {
      * applies that when it writes a reference out (`TokenUtils`: an endpoint outside the sheet's
      * bounds is written as `#REF!`); the node applies it here, to the same effect.
      *
+     * That is the `TwoCell` rule, the default. The other anchor types are the movable's
+     * ({@link IAnchored.Type}): `OneCell` shifts the top-left as a one-cell reference and keeps the
+     * extent, staying put when that cell is deleted; `Absolute` never moves, so a view listening to
+     * the rows it shows keeps hearing about those rows.
+     *
      * Handed to the map as {@link IAnchoredMap.ConstructorOptions.shiftEntry}.
      *
      * @param details The shift, as the map describes it.
      * @param entire The bounds of the sheet the node is on.
+     * @param anchor How the node follows the shift. Defaults to `TwoCell`.
      */
-    function shiftReference(details: ISpatialMap.ShiftDetails, entire: IRange.Coords): IRange.Coords | null;
+    function shiftReference(details: ISpatialMap.ShiftDetails, entire: IRange.Coords, anchor?: IAnchored.Type): IRange.Coords | null;
     /** The container hooks a node registers; see {@link Anchored.ContainerCallbacks}. */
     type Callbacks = Anchored.ContainerCallbacks;
 }

package/types/src/sheet/_RangeStateSweep.d.ts

@@ -1,9 +1,8 @@
 import { IRange } from '@sheetxl/primitives';
-import { RunCoords } from '@sheetxl/utils';
-import { RangeSweep, PieceStore } from '../collections/_RangeSweep';
+import { RangeSweep, RunCoords, PieceStore } from '@sheetxl/utils';
 import { RangeState } from './_SheetStateTypes';
 import { SheetReadContext } from './_SheetStateReader';
-export { type PieceStore } from '../collections/_RangeSweep';
+export { type PieceStore } from '@sheetxl/utils';
 export declare function collectPieces(ctx: SheetReadContext, bounds: IRange.Coords, searchTypes: RangeState.SearchTypes | null, injectReferences: IRange.JSONReference<any>[][] | undefined, containedBounds: IRange.Coords | undefined, hiddenRows: readonly RunCoords[] | null, hiddenColumns: readonly RunCoords[] | null): PieceStore | null;
 /**
  * The range-state sweep: regions materialize as `RangeState.Intersection` (values merged by type

package/types/src/sheet/_ScalarListFactory.d.ts

@@ -1,6 +1,6 @@
-import { Scalar } from '@sheetxl/primitives';
+import { Scalar, IRichData } from '@sheetxl/primitives';
 import { IStringCollection } from '../string';
-import { ICell } from '../cell';
+import { IRichDataKind, IRichDataCollection } from '../richData';
 import { IListLike } from '../collections';
 import { MixedTypedArrayList } from '../collections/MixedTypedArrayList';
 /**
@@ -11,8 +11,14 @@ import { MixedTypedArrayList } from '../collections/MixedTypedArrayList';
  * - shorter than {@link ScalarListFactory.TypedThreshold}: a plain array (a typed list costs
  *   more than its values below that, measured at 64 on Node);
  * - one value throughout: a `RepeatingList` of period 1, which the engine reads once;
- * - holding rich data: a plain array (no pool for it yet);
- * - otherwise a {@link MixedTypedArrayList}, strings and errors by id.
+ * - otherwise a {@link MixedTypedArrayList}, strings, errors and rich values by id.
+ *
+ * @remarks
+ * The typed list is the representation that crosses threads: a worker or the Rust engine reads
+ * the codes and numbers from (shared) array buffers, and a string travels as its id into the
+ * string table, a rich value as its id into the rich data collection (DESIGN-RICH-DATA-REGISTRY
+ * §3.3; the wire format is DESIGN-CALC-SERVICE G7). A factory made with no rich data collection
+ * keeps a run holding rich data as a plain array of the values.
  *
  * @internal
  */
@@ -21,9 +27,17 @@ export declare class ScalarListFactory {
     static readonly TypedThreshold = 64;
     readonly codec: MixedTypedArrayList.Codec<Scalar>;
     private readonly _strings;
+    private readonly _richData;
+    private readonly _richValues;
     private _codes;
     private _nums;
-    constructor(strings: IStringCollection);
+    /**
+     * @param richData What rich values loaded through this factory are made for; omitted, made
+     * outside any workbook.
+     * @param richValues Where a run stores its rich values by id; omitted, a run holding one is a
+     * plain array.
+     */
+    constructor(strings: IStringCollection, richData?: () => IRichDataKind.Context, richValues?: IRichDataCollection);
     /**
      * The list for a run a builder collected. Passed to `Tuple.Builder` as its `createList`.
      *
@@ -37,14 +51,48 @@ export declare class ScalarListFactory {
      */
     readonly createList: (values: Scalar[], length?: number, hint?: number) => IListLike<Scalar>;
     /**
-     * The list for a run as a file holds it (`ISheet.JSON` data): numbers and booleans as they are,
+     * The list for a run as a file holds it (`IWorksheet.JSON` data): numbers and booleans as they are,
      * strings as their id in this factory's collection, errors and rich data typed. One look at each
      * value classifies it into a reused scratch; nothing is resolved for a typed run.
      *
      * @param values The run's JSON values. Never empty.
      * @param onError Called with the offset of every error value, for the error index.
+     * @param richAt The rich value a saved id names (the file's rich data table). A value saved
+     *   inline, as older files hold them, needs none.
+     */
+    fromJSONRun(values: readonly Scalar.JSON[], onError?: (offset: number) => void, richAt?: (id: number) => IRichData | null): IListLike<Scalar>;
+    /**
+     * One value as a file holds it, decoded on its own. {@link fromJSONRun} is the same decoding for
+     * a whole run, into a typed list.
+     *
+     * @param json The value. `null` and `undefined` are blank.
+     * @param decodeString Resolves a string id. Omitted, a string is the literal text (as an
+     * external link's cache holds it).
+     * @param richData What a rich value is made for; omitted, made outside any workbook.
+     */
+    static fromJSONValue(json: Scalar.JSON | null | undefined, decodeString?: (id: number) => string, richData?: IRichDataKind.Context): Scalar;
+    /**
+     * A run as a file holds it (`IWorksheet.JSON` data): the inverse of {@link fromJSONRun}.
+     *
+     * @param run A run as the grid stores it (a blank ends a run, so it holds none).
+     * @param addString Returns the persisted id for a string.
+     * @param toResourceId Returns the persisted id for a resource a rich value holds.
+     * @param addRich Returns the persisted id for a rich value; omitted, a rich value is written
+     *   inline.
+     */
+    static toJSONRun(run: IListLike<Scalar>, addString: (value: string) => number, toResourceId?: IRichData.ToResourceId, addRich?: (value: IRichData) => number): Scalar.JSON[];
+    /**
+     * One value as a run holds it in a file: the encoding {@link toJSONRun} applies to each. Numbers and
+     * booleans as they are, strings as their id (as a string), errors and rich data typed.
+     *
+     * @param value The value to encode. Never `null`.
+     * @param addString Returns the persisted id for a string.
+     * @param toResourceId Returns the persisted id for a resource a rich value holds.
+     * @param addRich Returns the persisted id for a rich value; omitted, a rich value is written
+     *   inline.
+     * @returns `undefined` for a value with no encoding.
      */
-    fromJSONRun(values: readonly ICell.JSON[], onError?: (offset: number) => void): IListLike<Scalar>;
+    static toJSONValue(value: Scalar, addString: (value: string) => number, toResourceId?: IRichData.ToResourceId, addRich?: (value: IRichData) => number): Scalar.JSON | undefined;
     /**
      * The list for a run whose values are already codes and numbers, as a file holds them: string
      * ids, error codes, ints and doubles. Nothing is resolved for a typed run; a short run is

package/types/src/sheet/_SheetAutoFillUtils.d.ts

@@ -2,8 +2,8 @@ import { IRange } from '@sheetxl/primitives';
 import { ICellRange } from '../cellRange';
 import { ICell } from '../cell';
 import { IAutoFill } from '../autoFill';
-import { ISheet } from './ISheet';
-import { SheetMutationContext } from './Sheet';
+import { IWorksheet } from './IWorksheet';
+import { SheetMutationContext } from './Worksheet';
 /**
  * The default fill a range implies — which cells it reads, which it covers, which types can be
  * offered, and the one to open on. See {@link ICellRange.getDefaultAutoFillCriteria}.
@@ -11,7 +11,7 @@ import { SheetMutationContext } from './Sheet';
  * @returns `null` when the range is one cell deep along the direction — there is nowhere to fill.
  * @internal
  */
-export declare function getDefaultAutoFillCriteria(sheet: ISheet, rangeCoords: IRange.Coords, direction?: IRange.Direction, destination?: IRange.Coords): IAutoFill.DefaultCriteria | null;
+export declare function getDefaultAutoFillCriteria(sheet: IWorksheet, rangeCoords: IRange.Coords, direction?: IRange.Direction, destination?: IRange.Coords): IAutoFill.DefaultCriteria | null;
 /**
  * Resolve a raw destination to the nearest destination {@link autoFill} accepts — what
  * {@link ICellRange.AutoFillOptions.snap} runs before the fill.

package/types/src/sheet/_SheetAutoFitUtils.d.ts

@@ -1,7 +1,7 @@
 import { IRange } from '@sheetxl/primitives';
 import { Size } from '@sheetxl/utils';
 import { ICellRange } from '../cellRange';
-import { Sheet } from './Sheet';
+import { Worksheet } from './Worksheet';
 /**
  * Automatically adjusts row heights and column widths to fit cell content and styles.
  * - Merges and sorts input ranges for efficient processing.
@@ -15,7 +15,7 @@ import { Sheet } from './Sheet';
  * @param options AutoFit options (axis, expandOnly, skipCustomSize, etc).
  * @internal
  */
-export declare function doAutoFit(sheet: Sheet, ranges: readonly IRange.Coords[], options?: ICellRange.AutoFitOptions): void;
+export declare function doAutoFit(sheet: Worksheet, ranges: readonly IRange.Coords[], options?: ICellRange.AutoFitOptions): void;
 /**
  * The size `range`'s content needs — what {@link doAutoFit} would commit, reduced to a `Size`
  * instead of written.
@@ -42,5 +42,5 @@ export declare function doAutoFit(sheet: Sheet, ranges: readonly IRange.Coords[]
  * @param options Measurement options (axes, minContent, formulaView).
  * @internal
  */
-export declare function doBestFit(sheet: Sheet, range: IRange.Coords, options?: ICellRange.BestFitOptions): Size;
+export declare function doBestFit(sheet: Worksheet, range: IRange.Coords, options?: ICellRange.BestFitOptions): Size;
 //# sourceMappingURL=_SheetAutoFitUtils.d.ts.map

package/types/src/sheet/_SheetChangeEvent.d.ts

@@ -0,0 +1,72 @@
+import { IRange } from '@sheetxl/primitives';
+import { ITransaction } from '../transaction';
+import { ICellRanges } from '../cellRange';
+import { IWorksheet } from './IWorksheet';
+import { Worksheet } from './Worksheet';
+import { ShiftIntent } from './_SheetIntents';
+/** What a {@link SheetChangeEvent} says beside its kind and coords. @internal */
+export interface SheetChangeDetails {
+    /** What wrote the change; `null` for one not written. */
+    commit: ITransaction.ICommit | null;
+    /** The commit the change moved from; `null` when there is none. */
+    previous?: ITransaction.ICommit | null;
+    /** The change is an undo. */
+    isUndo?: boolean;
+    /** The change moved cells, so its coords do not name the same cells before it. */
+    isStructural?: boolean;
+    /** The inserts and deletes that moved them, as the change reports them (an undo's inverted). */
+    shifts?: readonly ShiftIntent[];
+}
+/** A change not written and of no known extent: what a cache or a collection announces. @internal */
+export declare const UnknownChange: SheetChangeDetails;
+/**
+ * {@link IWorksheet.ChangeEvent} over the coords a change announced.
+ *
+ * @remarks
+ * The ranges are built on first read: most listeners only need to know that something changed,
+ * and building an {@link ICellRanges} for every announcement would tax every write for them. The
+ * previous ranges cost a snapshot sheet, so they are built only when asked for too.
+ *
+ * @internal
+ */
+export declare class SheetChangeEvent implements IWorksheet.ChangeEvent {
+    private readonly _sheet;
+    private _kind;
+    private _coords;
+    private readonly _details;
+    private _ranges;
+    private _previousRanges;
+    private _shifts;
+    constructor(_sheet: Worksheet, _kind: IWorksheet.ChangeEventKey, _coords: readonly IRange.Coords[] | null, _details: SheetChangeDetails);
+    /** {@inheritDoc IWorksheet.ChangeEvent.getSheet} */
+    getSheet(): IWorksheet;
+    /** {@inheritDoc IWorksheet.ChangeEvent.getKind} */
+    getKind(): IWorksheet.ChangeEventKey;
+    /** {@inheritDoc IWorksheet.ChangeEvent.getRanges} */
+    getRanges(): ICellRanges | null;
+    /** {@inheritDoc IWorksheet.ChangeEvent.getCommit} */
+    getCommit(): ITransaction.ICommit | null;
+    /** {@inheritDoc IWorksheet.ChangeEvent.isUndo} */
+    isUndo(): boolean;
+    /** {@inheritDoc IWorksheet.ChangeEvent.getPreviousCommit} */
+    getPreviousCommit(): ITransaction.ICommit | null;
+    /** {@inheritDoc IWorksheet.ChangeEvent.getPreviousRanges} */
+    getPreviousRanges(): ICellRanges | null;
+    /** {@inheritDoc IWorksheet.ChangeEvent.getShifts} */
+    getShifts(): readonly IWorksheet.Shift[];
+    /**
+     * One event for two deliveries conflated into one: the union of the ranges (unknown wins), the
+     * latest commit, and the earliest previous one, so the pair spans both.
+     *
+     * @remarks
+     * A callback can be shared across event keys. Two kinds conflated into one delivery say no
+     * extent, and either side may not be a change event at all.
+     *
+     * An operation announces each of its writes, so one delivery can merge many. The first merge
+     * makes an event of its own, and later merges into it append in place: nothing else holds it.
+     */
+    static merge(prev: IWorksheet.ChangeEvent | null | undefined, next: IWorksheet.ChangeEvent | null | undefined): IWorksheet.ChangeEvent | null | undefined;
+    private _merged;
+    private _toMerged;
+}
+//# sourceMappingURL=_SheetChangeEvent.d.ts.map

package/types/src/sheet/_SheetCoords.d.ts

@@ -1,8 +1,8 @@
 import { IRange } from '@sheetxl/primitives';
 import { ICell } from '../cell';
 import { ICellRange, ICellRanges } from '../cellRange';
-import { ISheetProtection } from '../sheetProtection';
-import { SheetCoordContext } from './Sheet';
+import { IWorksheetProtection } from '../sheetProtection';
+import { SheetCoordContext } from './Worksheet';
 /**
  * Coordinate/address resolution for a {@link Sheet}: parses addresses into coords, validates bounds,
  * runs protection checks, and constructs the `ICellRange`/`ICellRanges` handles. Functions take a
@@ -17,7 +17,7 @@ import { SheetCoordContext } from './Sheet';
  * @internal
  */
 export interface ProtectionCheck {
-    (coords?: IRange.Coords[]): ISheetProtection.PropertyKeys[];
+    (coords?: IRange.Coords[]): IWorksheetProtection.PropertyKeys[];
 }
 /** @internal */
 export declare function createRange(ctx: SheetCoordContext, coords: Readonly<IRange.FixableCoords> | string, getOptions?: ICellRange.GetRangeOptions, readOnly?: string | null): ICellRange;

package/types/src/sheet/_SheetEvents.d.ts

@@ -10,7 +10,7 @@ import { IRange } from '@sheetxl/primitives';
  * and travel on the commit, which is what lets an undo announce the same categories the forward
  * commit did.
  *
- * The scope is {@link ISheet.getId}, so a commit that spans sheets announces each of them
+ * The scope is {@link IWorksheet.getId}, so a commit that spans sheets announces each of them
  * separately.
  *
  * @internal

package/types/src/sheet/_SheetFilterUtils.d.ts

@@ -3,8 +3,8 @@ import { RunCoords } from '@sheetxl/utils';
 import { ITransaction } from '../transaction';
 import { ICondition } from '../condition';
 import { NumberFormatRef } from '../numFmt/BuiltInFormats';
-import { ISheet } from './ISheet';
-import { Sheet } from './Sheet';
+import { IWorksheet } from './IWorksheet';
+import { Worksheet } from './Worksheet';
 /** A run of one column's rows that show their values under the same number format. */
 export interface TextFormatRun {
     rowStart: number;
@@ -19,7 +19,7 @@ export interface TextFormatRun {
  * What a cell shows follows from its value and its number format. The formats lie in few runs
  * whatever the number of rows, so a reader of the column's text formats values and builds no cell.
  */
-export declare function getTextFormatRuns(sheet: ISheet, coords: Readonly<IRange.Coords>): TextFormatRun[];
+export declare function getTextFormatRuns(sheet: IWorksheet, coords: Readonly<IRange.Coords>): TextFormatRun[];
 /**
  * What a filter evaluation settles: on one axis, the runs that stay visible and the runs that hide.
  *
@@ -39,7 +39,7 @@ export interface FilterRuns {
 /**
  * Read-only: resolves every condition and settles the final visible and hidden runs.
  */
-export declare function evalFilter(sheet: Sheet, coords: Readonly<IRange.Coords>, condition: ICondition.Input | ICondition.RangeOptions | null | undefined): Promise<FilterRuns>;
+export declare function evalFilter(sheet: Worksheet, coords: Readonly<IRange.Coords>, condition: ICondition.Input | ICondition.RangeOptions | null | undefined): Promise<FilterRuns>;
 /**
  * Writes the hidden bits {@link evalFilter} settled. Inside the caller's open transaction.
  *
@@ -48,10 +48,10 @@ export declare function evalFilter(sheet: Sheet, coords: Readonly<IRange.Coords>
  * then hide every row/column that doesn't — including one the user hid manually, matching real
  * Excel AutoFilter (there's no persisted "hidden by filter" vs. "hidden by user" bit to preserve).
  */
-export declare function applyFilterRuns(sheet: Sheet, runs: FilterRuns, options?: ITransaction.OperationOptions): void;
+export declare function applyFilterRuns(sheet: Worksheet, runs: FilterRuns, options?: ITransaction.OperationOptions): void;
 /**
  * Sheet specific filter utils. Mirrors `_SheetSortUtils.doSort`: {@link evalFilter}, then one
  * transaction around {@link applyFilterRuns}.
  */
-export declare function doFilter(sheet: Sheet, coords: Readonly<IRange.Coords>, condition: ICondition.Input | ICondition.RangeOptions, options?: ITransaction.OperationOptions): Promise<IRange.Coords>;
+export declare function doFilter(sheet: Worksheet, coords: Readonly<IRange.Coords>, condition: ICondition.Input | ICondition.RangeOptions, options?: ITransaction.OperationOptions): Promise<IRange.Coords>;
 //# sourceMappingURL=_SheetFilterUtils.d.ts.map