@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.2

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

@@ -0,0 +1,214 @@
+import { Scalar, IRange } from '@sheetxl/primitives';
+import { CoordUtils } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
+import { Tuple, ISpatialMap } from '../collections';
+import { ICellRange } from '../cellRange';
+import { ICell } from '../cell';
+import { IStyle } from '../style';
+import { InternalTupleUpdate } from './_SheetStateTypes';
+import { SheetMutationContext } from './Sheet';
+import { ScanStyleUpdate } from './_SheetMutations';
+/**
+ * What {@link CellBuffer} needs from its sheet.
+ * @internal
+ */
+export interface CellBufferContext {
+    readonly isDataColumn: boolean;
+    readonly transactions: ITransaction.IStore;
+    /**
+     * The records a flush writes: the sheet's, and the calculation's it marks dirty. A read of one
+     * from the store makes the held writes first.
+     */
+    readonly writes: readonly string[];
+    isClosed(): boolean;
+    getEntireCoords(): IRange.Coords | null;
+    /**
+     * The sheet's spills as `transaction` sees them - a read that does not flush: nothing a held
+     * write makes changes them.
+     */
+    getSpills(transaction: ITransaction): ISpatialMap;
+    /**
+     * Whether a style update written to one cell changes that cell alone, as `transaction` sees the
+     * sheet; see {@link CellBuffer.holdStyle}.
+     */
+    isLocalStyle(transaction: ITransaction, rowIndex: number, colIndex: number, update: IStyle.Update): boolean;
+    /** What the sheet's cell writes are made through; the held ones are scanned and written with it. */
+    getMutations(): SheetMutationContext;
+}
+/**
+ * Single-cell writes made inside an open transaction, held and made as ONE write when something
+ * needs them made.
+ *
+ * @remarks
+ * A loop that writes a cell per call makes one full write per cell, and leaves one formula block
+ * per cell. Held, the loop is one write, and the formulas in it conflate into runs as they do in
+ * one `setValues`.
+ *
+ * A held run IS that one write, left open: each cell goes through the write's own scan as it
+ * comes ({@link scanCell}), and making the run is the scan's finish ({@link finishTupleScan}). So
+ * a cell is resolved once, by the rules of any other write, and what the scan refuses it refuses
+ * at the call.
+ *
+ * Holding has no outward behavior. Inside a transaction the events and the undo step are the
+ * transaction's anyway, and everything that could see the difference makes the held writes first
+ * (`ITransaction.Hooks`): a read of a record they change - the sheet's, or the calculation's they
+ * mark dirty - a transaction beginning inside the one that holds them, and its commit. Only what
+ * cannot fail once scanned is held: a write that is part of an array, or that carries a merge, a
+ * hyperlink or comments, is made as it comes, after the held ones. A LOCKED sheet is held like any
+ * other: the scan rules on every cell against its exemptions and throws at the call, and the run
+ * it makes stands its commit-time catch-all down exactly as one `setValues` over those cells does.
+ *
+ * A scan asks for its cells in one order. The sheet stores along its major axis and a loop usually
+ * writes across it (row by row into a column-major sheet), so the order is decided by the second
+ * cell written, and the scan and the {@link Tuple.IBuilder} the values are placed in follow it. A
+ * write that does not continue that order - a step back, a second value to the same cell, a change
+ * between `updateCells` and `setValue` - flushes what is held and starts a new run.
+ *
+ * A style set on a cell on its own ({@link holdStyle}) is held in the same run: styling the cell
+ * just written, or styling it again, continues it. The styles of a cell styled more than once are
+ * written in the order they were set.
+ *
+ * The first write of a run is scanned on its own, within its one cell. The second begins the scan
+ * the run keeps - over the whole sheet, since where the run ends is not known - and the first
+ * cell goes through it again. A loop that makes every write as it comes never pays for the sheet.
+ *
+ * A read of a held cell answers from what the scan has: the value from the builder it was placed
+ * in, and a clear, a formula or a style from the scan's collectors. Nothing is kept by cell.
+ * @internal
+ */
+export declare class CellBuffer {
+    private readonly _ctx;
+    private _transaction;
+    private _count;
+    private _isCell;
+    private _scan;
+    private _isBeginning;
+    private _isOriented;
+    private _isTransposed;
+    private _builder;
+    private _changes;
+    private _firstWrites;
+    private _firstValue;
+    private _lastMajor;
+    private _lastMinor;
+    private _isValueAtLast;
+    private _hasValues;
+    private _majorMin;
+    private _majorMax;
+    private _minorMin;
+    private _minorMax;
+    private _generation;
+    constructor(ctx: CellBufferContext);
+    /** Whether any write is held. */
+    isHolding(): boolean;
+    /**
+     * Holds a write if it can be held.
+     *
+     * @returns `true` if the write is held; `false` if it is to be made as it comes.
+     */
+    hold(boundedTuples: Tuple.Region<ICell.Update> | null, options: ICellRange.UpdateCellsOptions | undefined, coordValidator: CoordUtils.CoordValidator | null | undefined, internalOptions: InternalTupleUpdate | null): boolean;
+    /**
+     * Holds a style set on one cell on its own, if it can be held.
+     *
+     * @param isLocal Whether the update changes only its cell - asked only once the rest allows the
+     * hold. A border changes the neighbor's edge and a continuous alignment is drawn across the
+     * neighbors, and a read of a neighbor does not see a held write.
+     * @returns `true` if the style is held; `false` if it is to be written as it comes.
+     */
+    holdStyle(rowIndex: number, colIndex: number, update: IStyle.Update, options: IStyle.UpdateOptions | undefined, isLocal: () => boolean): boolean;
+    private _holdIn;
+    /**
+     * The transaction the held writes are made into. While any is held it is the innermost one, and
+     * a read through it sees the sheet without them and does not make them.
+     */
+    getTransaction(): ITransaction | null;
+    /**
+     * What a read of a cell's value returns once the held writes are made, answered without making
+     * them.
+     *
+     * @remarks
+     * The answer is the value the scan stores: a number as the write normalizes it, text as the
+     * write coerced and cut it, `null` for a cleared cell - and for a formula, which has no value
+     * until it is calculated.
+     *
+     * @returns The value; {@link CellBuffer.NotHeld} if no held write is to the cell's value - none
+     * is to the cell, or it writes a style alone, or it is a merged cell other than its first - so
+     * the sheet as it is answers.
+     */
+    read(rowIndex: number, colIndex: number): Scalar | typeof CellBuffer.NotHeld;
+    /** {@link read}, at `major`/`minor` in the scan's orientation. */
+    private _valueAt;
+    /**
+     * What a held write leaves in its cell, answered without making the held writes.
+     *
+     * @returns The value, the formula text (`null` for none) and the style update; {@link
+     * CellBuffer.NotHeld} if no held write is to the cell; `undefined` if the held write has to be
+     * made to know - it clears the cell's style, link and comments.
+     */
+    readCell(rowIndex: number, colIndex: number): CellBuffer.HeldCell | typeof CellBuffer.NotHeld | undefined;
+    /**
+     * The style update a held write carries to its cell - an implied one included, such as the
+     * number format of text that reads as a date - or the styles set on it on their own, in order.
+     *
+     * @returns The update; `undefined` if the held writes leave the cell's style as it is.
+     */
+    readStyleUpdate(rowIndex: number, colIndex: number): ScanStyleUpdate | undefined;
+    /**
+     * Whether the run `generation` counted is still held: neither made nor dropped.
+     *
+     * @see {@link getGeneration}
+     */
+    isHeldGeneration(generation: number): boolean;
+    /** Identifies the run being held; see {@link isHeldGeneration}. */
+    getGeneration(): number;
+    /** Makes the held writes, as one. */
+    flush(): void;
+    /** Drops the held writes: the transaction they were made in rolled back, or the sheet closed. */
+    discard(): void;
+    private _toRange;
+    /**
+     * Whether a write at `major`/`minor`, in the sheet's orientation, continues the run held.
+     *
+     * @param isCell The kind of value write; `null` for a style set on its own, which may also be to
+     * the cell last written.
+     */
+    private _continues;
+    /** Begins a scan for the run. */
+    private _begin;
+    /** Scans one cell; `major`/`minor` in the scan's orientation. */
+    private _scanCell;
+    private _beginRun;
+    private _orientTo;
+    /**
+     * Scans and holds one write that continues the run, at `major`/`minor` in the sheet's
+     * orientation.
+     *
+     * @returns `false` if the scan refused it; it is not held then, and the run is as it was.
+     */
+    private _push;
+    /** Holds a style set on its own, continuing the run, at `major`/`minor` in the sheet's orientation. */
+    private _pushStyle;
+    /**
+     * The second cell written decides the run's order: the run's scan begins, over the whole sheet,
+     * and the writes to the first cell go through it again, in order.
+     */
+    private _orient;
+    private _clear;
+}
+/** @internal */
+export declare namespace CellBuffer {
+    /** {@link CellBuffer.read}: no held write is to the cell. */
+    const NotHeld: unique symbol;
+    /** {@link CellBuffer.readCell}: what the held writes leave in their cell. */
+    interface HeldCell {
+        /** The value written; `null` too when {@link isValueHeld} is `false`. */
+        value: Scalar;
+        /** `false` if no held write is to the cell's value: the sheet's stands. */
+        isValueHeld: boolean;
+        /** The run's formula imaged at the cell, without a leading `=`; `null` for none. */
+        formula: string | null;
+        /** The style updates held for the cell, an implied one included; `undefined` for none. */
+        style: ScanStyleUpdate | undefined;
+    }
+}
+//# sourceMappingURL=_CellBuffer.d.ts.map

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

@@ -28,6 +28,7 @@ export declare class InvalidSheetRanges extends SheetRanges {
     insert(): this;
     delete(): this;
     insertFrom(): Promise<this | null>;
+    canInsertFrom(): boolean;
     getSnapshot(): ICellRange.ISnapshot;
     copyFrom(): Promise<this | null>;
     getEntireRows(): this;
@@ -41,10 +42,10 @@ export declare class InvalidSheetRanges extends SheetRanges {
     getStats(): IRangeStats;
     getCounts(): ICellRange.Counts;
     getRegions(): ICellRegions;
-    getDirectPrecedents(): ICellRanges | null;
-    getDirectDependents(): ICellRanges | null;
-    getPrecedents(): ICellRanges | null;
-    getDependents(): ICellRanges | null;
+    getDirectPrecedents(): Promise<ICellRanges | null>;
+    getDirectDependents(): Promise<ICellRanges | null>;
+    getPrecedents(): Promise<ICellRanges | null>;
+    getDependents(): Promise<ICellRanges | null>;
     isContentful(): boolean;
     getRowCount(): number;
     getColumnCount(): number;
@@ -58,7 +59,6 @@ export declare class InvalidSheetRanges extends SheetRanges {
     isSingleCell(): boolean;
     isEqual(): boolean;
     getFixed(): this;
-    getCount(): number;
     at(): ICellRange;
     doBatch<R>(): R | Promise<R>;
     getCoords(): readonly Readonly<IRange.FixableCoords>[];

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

@@ -0,0 +1,104 @@
+import { IRange } from '@sheetxl/primitives';
+import { ISpatialMap } from '../collections';
+import { IListener } from '../listener';
+import { IAnchored } from '../anchored/IAnchored';
+import { Anchored } from '../anchored/Anchored';
+import { ICellRange, ICellRanges } from '../cellRange';
+/**
+ * The reference a range listener watches, as an entry in a versioned anchored map.
+ *
+ * @remarks
+ * This is the smallest thing that can be anchored. It deliberately does NOT extend
+ * `AbstractAnchored`: it has no store record of its own, no emitter, and no creation commit, so a
+ * UI layer can register one per scroll step. What it gets from living in the map is everything a
+ * conditional format's anchor gets - it shifts, splits and goes `#REF!` through `IAnchoredMap.shift`,
+ * and it comes back on undo because the map is in the snapshot.
+ *
+ * The callback is NOT here. It lives on the sheet instance keyed by {@link getNodeId}, because a
+ * callback is an observer, never document state.
+ *
+ * @internal
+ */
+export declare class ListenerAnchor implements IAnchored {
+    /** For runtime type checking. */
+    readonly isIAnchored: true;
+    protected _nodeId: number;
+    protected _options: ICellRange.ListenerOptions;
+    protected _resolveRanges: (coords: IRange.Coords[] | null) => ICellRanges;
+    protected _getContainerCoords: () => IRange.Coords[] | null;
+    protected _deleted: boolean;
+    protected _closed: boolean;
+    constructor(options: ListenerAnchor.ConstructorOptions);
+    /**
+     * Identifies this node. The sheet holds the callback under the same key.
+     */
+    getNodeId(): number;
+    /**
+     * The node's coords in the snapshot the sheet is currently at, or `null` when it holds no entry.
+     *
+     * @remarks
+     * `null` is not an error state to guard against - it IS the answer for a range that was deleted
+     * (`#REF!`) and for a snapshot from before the node was registered (`#N/A`).
+     */
+    getContainerCoords(): IRange.Coords[] | null;
+    /**
+     * What the listener asked for when it registered.
+     */
+    getListenerOptions(): ICellRange.ListenerOptions;
+    /** {@inheritDoc IAnchored.getRanges} */
+    getRanges(): ICellRanges;
+    /** {@inheritDoc IAnchored.isProtected} */
+    isProtected(): boolean;
+    /** {@inheritDoc IAnchored.addListeners} */
+    addListeners(_listeners: IAnchored.IListeners, _options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IAnchored.delete} */
+    delete(): void;
+    /**
+     * The node's ranges are back, so it is no longer `#REF!`.
+     *
+     * @remarks
+     * Undo restores the map, and with it the entry a delete removed. The flag has to follow, or a
+     * reference that came back would keep reporting the error it had on the way out.
+     */
+    undelete(): void;
+    /** {@inheritDoc IAnchored.isDeleted} */
+    isDeleted(): boolean;
+    /** {@inheritDoc IAnchored.close} */
+    close(): void;
+    /** {@inheritDoc IAnchored.isClosed} */
+    isClosed(): boolean;
+}
+/** @internal */
+export declare namespace ListenerAnchor {
+    interface ConstructorOptions {
+        nodeId: number;
+        listenerOptions: ICellRange.ListenerOptions;
+        /** Builds the ranges for the node's coords; an INVALID ranges when it has none. */
+        resolveRanges: (coords: IRange.Coords[] | null) => ICellRanges;
+        /** The node's coords in the map the sheet is currently at, or `null` when it holds no entry. */
+        getContainerCoords: () => IRange.Coords[] | null;
+    }
+    /**
+     * Shift one of a node's ranges the way the calc graph shifts a formula precedent.
+     *
+     * @remarks
+     * The map the nodes live in is asked not to split on a shift, and to bring each entry here
+     * instead of using its own arithmetic. The answer is then, by construction, the answer
+     * `=SUM(A1:C3)` gets for the same operation: `shiftReferenceAxis` is the rule `shiftPrecedents`
+     * applies to every reference it rewrites. Inserting one cell at A1 shifting down leaves the
+     * reference `A2:C4`; deleting A1:A3 shifting up leaves it `#REF!`.
+     *
+     * A reference pushed past the edge of the sheet is `#REF!` as well, whole or in part. The graph
+     * 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.
+     *
+     * 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.
+     */
+    function shiftReference(details: ISpatialMap.ShiftDetails, entire: IRange.Coords): IRange.Coords | null;
+    /** The container hooks a node registers; see {@link Anchored.ContainerCallbacks}. */
+    type Callbacks = Anchored.ContainerCallbacks;
+}
+//# sourceMappingURL=_ListenerAnchor.d.ts.map

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

@@ -0,0 +1,16 @@
+import { IRange } from '@sheetxl/primitives';
+import { RunCoords } from '@sheetxl/utils';
+import { RangeSweep, PieceStore } from '../collections/_RangeSweep';
+import { RangeState } from './_SheetStateTypes';
+import { SheetReadContext } from './_SheetStateReader';
+export { type PieceStore } from '../collections/_RangeSweep';
+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
+ * key, overlapping same-key values as arrays in overlap order).
+ * @internal
+ */
+export declare class RangeStateSweep extends RangeSweep<RangeState.Intersection> {
+    protected _materialize(region: number): RangeState.Intersection;
+}
+//# sourceMappingURL=_RangeStateSweep.d.ts.map

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

@@ -0,0 +1,61 @@
+import { Scalar } from '@sheetxl/primitives';
+import { IStringCollection } from '../string';
+import { ICell } from '../cell';
+import { IListLike } from '../collections';
+import { MixedTypedArrayList } from '../collections/MixedTypedArrayList';
+/**
+ * Makes the list a run of cell values is stored as, over the sheet's string collection.
+ *
+ * The representation is chosen from what the writer saw ({@link Tuple.Hint}) and the run's length,
+ * never by looking at the values again:
+ * - 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.
+ *
+ * @internal
+ */
+export declare class ScalarListFactory {
+    /** Below this length a run is a plain array. */
+    static readonly TypedThreshold = 64;
+    readonly codec: MixedTypedArrayList.Codec<Scalar>;
+    private readonly _strings;
+    private _codes;
+    private _nums;
+    constructor(strings: IStringCollection);
+    /**
+     * The list for a run a builder collected. Passed to `Tuple.Builder` as its `createList`.
+     *
+     * @param values The run's values, in an array that may be the writer's reused scratch: never
+     * retained, what the list keeps is copied out.
+     * @param length How many of `values` are the run's. Never 0.
+     * @param hint The {@link Tuple.Hint} bits the writer saw; computed here when a writer has none.
+     * @throws When a number is NaN or infinite: the entry points normalize those to `#NUM!`, so one
+     * arriving here is an internal path that skipped its boundary, and storing it would launder the
+     * defect into a plausible-looking cell.
+     */
+    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,
+     * 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.
+     */
+    fromJSONRun(values: readonly ICell.JSON[], onError?: (offset: number) => void): IListLike<Scalar>;
+    /**
+     * 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
+     * resolved into a plain array.
+     *
+     * @param codes The {@link MixedTypedArrayList.Type} per position; never `Rich`.
+     * @param values The number per position; ignored for a boolean or a blank.
+     */
+    fromEncoded(codes: Uint8Array, values: ArrayLike<number>): IListLike<Scalar>;
+    /** The representation for `length` classified values, from what the classification saw. */
+    private _fromCodes;
+    private _decode;
+}
+//# sourceMappingURL=_ScalarListFactory.d.ts.map

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

@@ -0,0 +1,74 @@
+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';
+/**
+ * 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}.
+ *
+ * @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;
+/**
+ * Resolve a raw destination to the nearest destination {@link autoFill} accepts — what
+ * {@link ICellRange.AutoFillOptions.snap} runs before the fill.
+ * @internal
+ */
+export declare function autoFillRange(ctx: SheetMutationContext, template: IRange.Coords, destination: IRange.Coords): IRange.Coords;
+/**
+ * What an `autoFill` run with `preview` hands back instead of committing: the destination plus a
+ * cell-level projection of the fill that *would* happen. `SheetRange` wraps this in a read-only
+ * `ICellRange` — see {@link ICellRange.autoFill}.
+ * @internal
+ */
+export interface AutoFillProjection {
+    /** The destination the projection covers. */
+    coords: IRange.Coords;
+    /**
+     * The projected (uncommitted) cell at these coords. Cells the fill does not touch read straight from
+     * the sheet; filled cells are derived — value, style and, when the template tiles a merge across the
+     * fill, the merge itself (so `getRange`/`getSpans`/`getExtrusions` report the projected block, and a
+     * coord inside one resolves to that block's anchor, where the value lives).
+     */
+    getCellAt(rowIndex: number, colIndex: number): ICell;
+}
+/**
+ * The single-entry series memo behind `autoFill({ preview })` — the "last autofill".
+ *
+ * @remarks
+ * A drag previews the same template in the same direction over and over, changing only the destination;
+ * the series does not depend on the destination, so scanning it once serves the whole drag. Held on the
+ * sheet (one entry) and validated against `state` identity: the transaction store rebuilds the state
+ * object on every real change (reference-equal *is* its "nothing changed" signal), so any mutation,
+ * undo or redo drops the memo without anything having to invalidate it explicitly.
+ * @internal
+ */
+export interface AutoFillPreviewCache {
+    /** The sheet state the series was read from. */
+    state: unknown;
+    template: IRange.Coords;
+    isForward: boolean;
+    filler: IAutoFill.Filler;
+    /** The caller's `fillerOptions` **by reference** — a caller that rebuilds it simply misses the memo. */
+    fillerOptions: IAutoFill.Options | undefined;
+    /** Series per line of the opposite axis; `null` marks a line that produced nothing to fill. */
+    seriesByLine: Map<number, IAutoFill.FillAt | null>;
+}
+/**
+ * Fill the template's series/pattern into the destination (outward drag of the fill handle). Handles
+ * merges (tiles them, never splits), date series, previewing, table extension, and copies the
+ * per-feature style maps into the filled range. Delegates a negative (inward) fill to
+ * {@link autoFillShrink}. See SHEET-SPLIT-DESIGN §5.4.
+ * @internal
+ */
+export declare function autoFill(ctx: SheetMutationContext, template: IRange.Coords, destination: IRange.Coords, options?: ICellRange.AutoFillOptions): boolean | AutoFillProjection;
+/**
+ * An inward fill — Excel's drag of the fill handle back over the source range. The strip of the
+ * template beyond the destination edge is vacated: its cells are cleared, not filled.
+ * @internal
+ */
+export declare function autoFillShrink(ctx: SheetMutationContext, template: IRange.Coords, destination: IRange.Coords, direction: IRange.Direction, options?: ICellRange.AutoFillOptions): boolean;
+//# sourceMappingURL=_SheetAutoFillUtils.d.ts.map

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

@@ -24,8 +24,8 @@ export declare function doAutoFit(sheet: Sheet, ranges: readonly IRange.Coords[]
  * The same phases as `doAutoFit` ({@link measureRange}, then {@link reduceColumnWidths} /
  * {@link reduceRowHeights}) minus the commit. Everything that differs follows from not writing:
  *
- * - The clamps are IDENTITY. `expandOnly` reconciles a measurement with the size a header already
- *   has; a query has no such size to reconcile against.
+ * - No {@link ApplyPolicy}. `expandOnly` reconciles a measurement with the size a header already
+ *   has; a query has no such size to reconcile against, and measurement never reads the policy.
  * - `axes: Both` still lays the rows out against the widths the column pass produced — a wrapped
  *   cell's height is a function of its column width — but those widths reach
  *   {@link refreshSegmentWidths} as a lookup rather than being read back from headers that were

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

@@ -0,0 +1,43 @@
+import { IRange } from '@sheetxl/primitives';
+/**
+ * The kinds of change a sheet announces from its commits, and the scope they are announced
+ * under.
+ *
+ * @remarks
+ * Every mutation appends the ranges it wrote under one of these, so a commit carries what to
+ * announce rather than what its last operation changed. The categories are recorded as the
+ * `sheet.events` intent (`_SheetIntents`), so they are unioned across the operations of a batch
+ * 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
+ * separately.
+ *
+ * @internal
+ */
+/**
+ * A category of change to announce, named after the mutation kind that produces it.
+ *
+ * @remarks
+ * * `data` - cell values written, cleared or pasted.
+ * * `style` - styles and number formats.
+ * * `comments` - comments and notes.
+ * * `hyperlinks` - hyperlinks.
+ * * `merges` - merge and unmerge.
+ * * `spills` - spill regions written or cleared.
+ * * `address` - a structural shift: an insert, a delete or a move of cells.
+ * * `layout` - sizes and hidden runs.
+ * * `anchored` - a model anchored over a range: a table, a conditional format, a validation, a
+ *   protected range.
+ * * `sheets` - the sheet itself, over the cells a reader of it may now read differently. A rename
+ *   is one: every cross-sheet formula naming it resolves again.
+ *
+ * `data`, `style`, `merges`, `spills`, `address` and `layout` each have an event of their own;
+ * the rest reach a consumer only through the union. A consumer that wants "did anything happen in
+ * my box" takes the union rather than naming categories, so a category added later cannot
+ * silently stop reaching it.
+ */
+export type EventCategory = 'data' | 'style' | 'comments' | 'hyperlinks' | 'merges' | 'spills' | 'address' | 'layout' | 'anchored' | 'sheets';
+/** What one sheet has to announce from a commit, by category. */
+export type SheetEvents = Readonly<Partial<Record<EventCategory, readonly IRange.Coords[]>>>;
+//# sourceMappingURL=_SheetEvents.d.ts.map

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

@@ -1,9 +1,40 @@
 import { IRange } from '@sheetxl/primitives';
+import { RunCoords } from '@sheetxl/utils';
 import { ITransaction } from '../transaction';
 import { ICondition } from '../condition';
 import { Sheet } from './Sheet';
 /**
- * Sheet specific filter utils. Mirrors `_SheetSortUtils.doSort`.
+ * What a filter evaluation settles: on one axis, the runs that stay visible and the runs that hide.
+ *
+ * @remarks
+ * The two halves of a filter are split so a caller with its own transaction (a table, which also
+ * writes its levels) can evaluate first and write inside: {@link evalFilter} may await a calc, and
+ * a transaction never stays open across an await.
+ */
+export interface FilterRuns {
+    /** The axis the runs index. */
+    axis: IRange.Axis;
+    /** The runs that match every condition, ascending. */
+    visibleRuns: readonly RunCoords[];
+    /** The runs that fail one, ascending. */
+    hiddenRuns: readonly RunCoords[];
+}
+/**
+ * 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>;
+/**
+ * Writes the hidden bits {@link evalFilter} settled. Inside the caller's open transaction.
+ *
+ * @remarks
+ * Full recompute, every apply (DESIGN-FILTER.md §2): unhide every row/column that now matches,
+ * 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;
+/**
+ * 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>;
 //# sourceMappingURL=_SheetFilterUtils.d.ts.map