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

package/types/src/collections/RTree.d.ts

@@ -4,26 +4,43 @@ import { RangeCoordValue, RangeCoords } from '@sheetxl/utils';
  *
  * Use this to answer "which items overlap this region?" without a linear scan.
  *
- * @typeParam T must extend `RangeCoordValue` (carries `colStart/rowStart/colEnd/rowEnd`)
+ * {@link clone} is O(1): the copies share every node, and a change to either copies only the
+ * nodes on its path from the root, so each keeps the version it had.
+ *
+ * Items are returned by identity: {@link search} and {@link all} return the objects that were
+ * inserted. An item's coordinates must not change while it is in the tree.
  *
- * @TODO See RTree-REDESIGN.md for planned structural changes.
+ * @typeParam T must extend `RangeCoordValue` (carries `colStart/rowStart/colEnd/rowEnd`)
  */
 export declare class RTree<T extends RangeCoordValue> {
     protected _maxEntries: number;
     protected _minEntries: number;
-    protected _data: Node<T>;
+    /** The nodes and items, shared with every clone of this tree. */
+    protected _arena: Arena<T>;
+    /** The id carried by the arena nodes this tree may write in place. */
+    protected _owner: number;
+    protected _root: number;
+    protected _size: number;
+    /** The nodes reachable from the root; the arena holding many more is what triggers a compaction. */
+    protected _nodes: number;
+    protected _colStart: number;
+    protected _rowStart: number;
+    protected _colEnd: number;
+    protected _rowEnd: number;
     /**
      * Constructs an `RTree`, a high-performance 2D spatial index for points and
      * rectangles. Based on an optimized __R-tree__ data structure with
      * __bulk-insertion__ support.
      *
      * @param maxEntries An optional argument to RTree defines the maximum
-     *                   number of entries in a tree node. `9` (used by default)
-     *                   is a reasonable choice for most applications. Higher
-     *                   value means faster insertion and slower search, and
-     *                   vice versa.
+     *                   number of entries in a tree node, from `4` to `12`. `9`
+     *                   (used by default) is a reasonable choice for most
+     *                   applications. Higher value means faster insertion and
+     *                   slower search, and vice versa.
      */
     constructor(maxEntries?: number);
+    /** Returns the number of items in the tree. */
+    size(): number;
     /** Returns all items contained in the tree. */
     all(result?: T[]): T[];
     /**
@@ -64,6 +81,10 @@ export declare class RTree<T extends RangeCoordValue> {
      * Removes all items.
      */
     clear(): RTree<T>;
+    /**
+     * Returns a copy that shares this tree's nodes; changing either leaves the other as it was.
+     */
+    clone(): this;
     /**
      * Inserts an item. To insert many items at once, use `load()`.
      */
@@ -73,39 +94,98 @@ export declare class RTree<T extends RangeCoordValue> {
      * Pass `equals` to compare by value instead.
      */
     remove(item: T, equals?: (a: T, b: T) => boolean): RTree<T>;
-    protected _all(node: Node<T>, result: T[]): T[];
-    protected _build(items: T[], left: number, right: number, height: number): Node<T>;
-    protected _chooseSubtree(coords: RangeCoordValue, node: Node<T>, level: number, path: Node<T>[]): Node<T>;
-    protected _insert(node: Node<T>, level: number): void;
-    protected _split(insertPath: Node<T>[], level: number): void;
-    protected _splitRoot(node: Node<T>, newNode: Node<T>): void;
-    protected _chooseSplitIndex(node: Node<T>, min: number, length: number): number;
-    protected _chooseSplitAxis(node: Node<T>, min: number, length: number): void;
-    protected _allDistMargin(node: Node<T>, min: number, length: number, compare: (a: Node<T>, b: Node<T>) => number): number;
+    protected _rootIntersects(coords: RangeCoords): boolean;
+    protected _setRootBox(): void;
+    /** The arena, created on the first write: an empty tree holds none. */
+    protected _writableArena(): Arena<T>;
+    /** `node` if this tree owns it, otherwise an owned copy of it that nothing points at yet. */
+    protected _ownDetached(node: number): number;
+    /**
+     * `node` if this tree owns it, otherwise an owned copy put in its place: in slot `slot` of
+     * `parent` (which this tree must own), or as the root when `parent` is `NONE`.
+     */
+    protected _own(node: number, parent: number, slot: number): number;
+    protected _all(node: number, result: T[]): T[];
+    /**
+     * Builds a subtree over `order[left..right]` (indices into `itemBoxes`, four numbers an item,
+     * and into the payload from `first`) and returns its node, leaving its box in `_bx0`..`_bx3` and
+     * its height in `_BuiltHeight`. The same overlap-minimizing tiling as rbush's bulk load.
+     */
+    protected _build(order: Int32Array, itemBoxes: Float64Array, first: number, left: number, right: number, height: number): number;
+    /**
+     * Adds `child` (an item's payload index when `height` is `0`, otherwise a node of height
+     * `height - 1`) to a node of height `height`, copying the shared nodes on the way down and
+     * splitting full ones on the way up.
+     */
+    protected _insertEntry(child: number, colStart: number, rowStart: number, colEnd: number, rowEnd: number, height: number): void;
+    /**
+     * Adds an entry to an owned node; when the node is full, splits it and returns the new sibling
+     * (for the caller to add to the parent), otherwise `NONE`.
+     */
+    protected _addEntry(node: number, child: number, colStart: number, rowStart: number, colEnd: number, rowEnd: number): number;
+    /** Grows the tree by a level: a new root over the old root and `sibling`, of the same height. */
+    protected _splitRoot(sibling: number): void;
+    /**
+     * Finds `item` under `node` as `remove` does: a leaf's items are compared, a node whose children
+     * are leaves has every leaf searched, a deeper node only the children that contain the item. On
+     * a match, records the path in `_RemovePath`/`_RemoveSlots` and the item's slot in `_RemoveSlot`.
+     *
+     * The path is written only on the way back up, after the last call to `equals`, so an `equals`
+     * that uses another tree cannot disturb it.
+     */
+    protected _findItem(node: number, depth: number, item: T, equals: ((a: T, b: T) => boolean) | undefined): boolean;
+    /**
+     * Removes every item under `node` that `isRemove` matches, visiting only children that intersect
+     * the given box. A node is written only when something under it is removed, and copied first
+     * when it is shared, so a subtree with nothing to remove is never copied.
+     *
+     * @returns `UNCHANGED`, `EMPTY` (the node should be removed from its parent), or the node to keep
+     * in its place (a copy when it was shared).
+     */
+    protected _removeWithin(node: number, isRemove: (item: T) => boolean, colStart: number, rowStart: number, colEnd: number, rowEnd: number): number;
+    /**
+     * Compacts when the arena holds much more than this tree reaches: the nodes and items other
+     * versions still use, and the ones no version does. A compaction copies the tree's nodes and
+     * items, so it waits until the unreached nodes outnumber both, which keeps its cost per write
+     * constant.
+     */
+    protected _maybeCompact(): void;
+    /**
+     * Moves this tree into an arena of its own, copying what it reaches depth first so a parent is
+     * next to its first child. Other versions keep the old arena, which is freed with the last of them.
+     */
+    protected _detach(): void;
+    /**
+     * Throws if the tree is inconsistent: heights, boxes, counts, the size and the node count. For
+     * tests.
+     */
+    protected _validate(): void;
 }
 /**
- * Internal R-tree node.
+ * The storage of a tree and every clone of it.
  *
- * - Leaf nodes: `children === null`, `range` is a cast of the user item (`T`), `height === 0`.
- * - Internal nodes: `children` is an array of child nodes, `range` is the mutable aggregate
- *   bounding box of all descendants, `height >= 1`.
+ * Nodes are appended and never freed or rewritten once another version can reach them: a tree
+ * writes a node in place only when the node carries the tree's owner id, and {@link RTree.clone}
+ * gives both trees new ids, so no existing node carries either. That is what makes a clone free
+ * and an old version immutable. The garbage collects as a whole: a tree that reaches much less
+ * than its arena holds moves to a new one ({@link RTree._detach}), and the old one goes when the
+ * last version using it does.
  */
-interface Node<T> {
-    range: RangeCoordValue<T>;
-    children: Node<T>[] | null;
-    height: number;
+declare class Arena<T> {
+    boxes: Float64Array;
+    meta: Int32Array;
+    /** The number of nodes allocated. */
+    top: number;
+    /** Item by payload index. */
+    payload: T[];
+    /** The last owner id handed out. */
+    owners: number;
+    constructor(capacity: number);
+    /** A new node carrying `owner`; may replace `boxes` and `meta`, so neither is held across it. */
+    alloc(owner: number): number;
+    /** Grows the arrays to hold at least `capacity` nodes; replaces `boxes` and `meta` when it does. */
+    reserve(capacity: number): void;
+    nextOwner(): number;
 }
-/**
- * Rearranges items so that all items in the [left, k] are the smallest.
- * The k-th element will have the (k - left + 1)-th smallest value in [left, right].
- *
- * @template T
- * @param arr the array to partially sort (in place)
- * @param k middle index for partial sorting (as defined above)
- * @param left left index of the range to sort
- * @param right right index
- * @param compare compare function
- */
-export declare function quickSelect<T>(arr: T[], k: number, left?: number | undefined, right?: number | undefined, compare?: ((a: T, b: T) => number) | undefined): void;
 export {};
 //# sourceMappingURL=RTree.d.ts.map

package/types/src/collections/SparseGrid.d.ts

@@ -1,8 +1,9 @@
-import { CellCoords, Direction, RangeAxis, RangeCoords } from '@sheetxl/utils';
+import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
 import { Tuple } from './Tuple';
 import { IReadableList } from './IReadableList';
 import { IGrid } from './IGrid';
 import { ISparseGrid } from './ISparseGrid';
+import { IListLike } from './IList';
 /**
  * Implementation of {@link IGrid} that uses a ISparseList of ISparseList.
  */
@@ -19,13 +20,7 @@ export declare class SparseGrid<T = any> implements ISparseGrid<T> {
     private _isShared;
     private _createRun;
     constructor(options?: SparseGrid.ConstructorOptions);
-    /**
-     * Returns an IterableIterator over all the runs in the sparse grid.
-     * Each run is a contiguous list of values in the grid.
-     *
-     * @returns An iterator that yields [majorIndex, minorIndex, IReadableList] entries
-     */
-    /** {@inheritDoc ISparseGrid.getMaxCoords} */
+    /** {@inheritDoc ISparseGrid.getRuns} */
     getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator<T>;
     /** {@inheritDoc IGrid.getAxis} */
     getAxis(): RangeAxis;
@@ -35,6 +30,7 @@ export declare class SparseGrid<T = any> implements ISparseGrid<T> {
     values(options?: IGrid.IteratorOptions): IGrid.ValueIterator;
     /** {@inheritDoc IGrid.keys} */
     keys(options?: IGrid.IteratorOptions): IGrid.KeyIterator;
+    private _entriesPrivateResult;
     private _updateMajorSpan;
     /** {@inheritDoc IGrid.setValues} */
     setValues(values: Tuple.GridTuple<T>): this;
@@ -89,11 +85,13 @@ export declare namespace SparseGrid {
          */
         axis?: RangeAxis;
         /**
-         * Hook to allow for custom storing of contiguous values.
+         * Makes the list a run of contiguous values is stored as: the one place a value enters this
+         * grid, so a grid with a policy about what it holds applies it here, once per run.
          *
-         * @param values The values to wrap in a List.
+         * @param values The run's values: a writer's array, or a list another grid already held.
+         * @defaultValue wraps the values as they are
          */
-        createRun?: (values: T[]) => IReadableList<T>;
+        createRun?: (values: IListLike<T> | T[]) => IReadableList<T>;
     }
 }
 //# sourceMappingURL=SparseGrid.d.ts.map

package/types/src/collections/SpatialMap.d.ts

@@ -5,7 +5,6 @@ import { ISpatialMap } from './ISpatialMap';
  * The default implementation for {@link ISpatialMap}
  */
 export declare class SpatialMap<T = any> implements ISpatialMap<T> {
-    protected _shared: SharedRecord<T> | null;
     protected _rTree: FilterRTree<T>;
     protected _cloneKey: any;
     protected _options: ISpatialMap.ConstructorOptions<T> | undefined;
@@ -60,13 +59,12 @@ export declare class SpatialMap<T = any> implements ISpatialMap<T> {
     delete(coords: RangeCoords | null): this;
     /** {@inheritDoc ISpatialMap.clone} */
     clone(cloneKey?: any): this;
-    protected _copy(source: SharedRecord<T>, entries?: ReadonlyArray<ISpatialMap.Entry<T>>): SharedRecord<T>;
     protected _updateNodes(nodesInsert: ISpatialMap.Entry<T>[], nodesRemove?: ISpatialMap.Entry<T>[], onUpdates?: (nodesInsert: ISpatialMap.Entry<T>[], nodesRemove: ISpatialMap.Entry<T>[], map: ISpatialMap<T>) => void): void;
     protected _mergeNodes(range: RangeCoords, fullyContained?: boolean): ISpatialMap.Entry<T>[];
     protected _getReadTree(): FilterRTree<T>;
-    protected _ensureWritable(entries?: ReadonlyArray<ISpatialMap.Entry<T>>): void;
     /**
-     * entries is a special performance optimization to allow a single bulk load.
+     * The tree, with the search caches invalidated for a write; loads `entries` into it first if
+     * given.
      */
     protected _getWritableTree(entries?: ReadonlyArray<ISpatialMap.Entry<T>>): FilterRTree<T>;
     /**
@@ -78,10 +76,6 @@ export declare class SpatialMap<T = any> implements ISpatialMap<T> {
      */
     protected _createClone(options: ISpatialMap.ConstructorOptions<T> | undefined): this;
 }
-interface SharedRecord<T> {
-    refCount: number;
-    rTree: FilterRTree<T>;
-}
 /**
  * Internal class that extends RTree to support Filters.
  * is needed — the default passthrough in RTree works directly.

package/types/src/collections/SpatialMap3D.d.ts

@@ -11,6 +11,8 @@ import { ISpatialMap3D } from './ISpatialMap3D';
  */
 export declare class SpatialMap3D<T = any> implements ISpatialMap3D<T> {
     protected _mapScopeTo2Ds: Map<string, ISpatialMap<T>>;
+    /** The key this map was cloned under, if any - see {@link clone}. */
+    protected _cloneKey: any;
     protected _last2DKey: string | null | undefined;
     protected _last2DMap: ISpatialMap<T> | undefined;
     protected _options: SpatialMap3D.ConstructorOptions<T> | undefined;

package/types/src/collections/index.d.ts

@@ -9,7 +9,7 @@ export * from './ISpatialMap3D';
 export * as IteratorUtils from './IteratorUtils';
 export * from './ImmutableList';
 export * from './IList';
-export * from './OverlappingRangeIterator';
+export { OverlappingRange } from '@sheetxl/utils';
 export * from './SortedMap';
 export * from './SparseGrid';
 export * from './ScalarGrid';

package/types/src/comment/Comment.d.ts

@@ -1,11 +1,15 @@
 import { IRange } from '@sheetxl/primitives';
+import { Bounds } from '@sheetxl/utils';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 import { ICellRange, ICellRanges } from '../cellRange';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { IPerson, IPersonCollection } from '../person';
 import { IMovable } from '../movable';
 import { IRichText } from '../text';
+import { IFill, IStroke } from '../fill';
+import { IStyleCollection } from '../style';
+import { IShapeStyle } from '../shape';
 import { Anchored } from '../anchored/Anchored';
 import { AbstractAnchored } from '../anchored/AbstractAnchored';
 import { IComment } from './IComment';
@@ -31,6 +35,7 @@ export declare class Comment extends AbstractAnchored<State, IComment.Events> im
      * brings the same one back, and a note made again from a thread is given a new one.
      */
     private _boxes;
+    private _style;
     /** @internal */
     protected _initialize(options: Comment.ConstructorOptions): void;
     /** @internal */
@@ -54,8 +59,8 @@ export declare class Comment extends AbstractAnchored<State, IComment.Events> im
      * never asks the model for it, so this is free to answer the way Office Scripts does.
      */
     getId(): string;
-    /** {@inheritDoc IComment.getSheet} */
-    getSheet(): ISheet;
+    /** {@inheritDoc IComment.getWorksheet} */
+    getWorksheet(): IWorksheet;
     /** {@inheritDoc IComment.getRange} */
     getRange(options?: ICellRange.GetRangeOptions): ICellRange;
     /** {@inheritDoc IComment.getContent} */
@@ -94,17 +99,19 @@ export declare class Comment extends AbstractAnchored<State, IComment.Events> im
     setDescription(description: string | null): this;
     /** {@inheritDoc IComment.getMovable} */
     getMovable(): IMovable | null;
+    /** {@inheritDoc IComment.getStyle} */
+    getStyle(): IShapeStyle | null;
     /**
      * The live box, if there is one.
      * @internal
      */
     protected _getBox(): NoteMovable | null;
     /**
-     * Asks the sheet for a box: at `anchor`, its cells counted from this comment's, or where Excel
-     * puts a new note's. A comment with no sheet to place one on has no box.
+     * Asks the sheet for a box: at `placement`, or where Excel puts a new note's. A comment with no
+     * sheet to place one on has no box.
      * @internal
      */
-    protected _placeBox(anchor: IMovable.AnchorOffset | null, hidden: boolean): void;
+    protected _placeBox(placement: Comment.BoxPlacement | null, hidden: boolean): void;
     /**
      * The note is gone, or is a thread now: its box goes with it.
      * @internal
@@ -182,7 +189,20 @@ export declare namespace Comment {
          * What places a note's box. A comment given none has no movable.
          */
         boxes?: Comment.Boxes;
+        /**
+         * The workbook's styles, for resolving a note's colors. Lazy, as {@link getPeople} is.
+         */
+        getStyles?: () => IStyleCollection | null;
     }
+    /**
+     * Where a note's box is placed: by its cells counted from the note's, or by pixels from the
+     * sheet's top-left (see {@link IComment.BoxJSON.bounds}).
+     */
+    type BoxPlacement = {
+        anchor: IMovable.AnchorOffset;
+    } | {
+        bounds: Bounds;
+    };
     /**
      * What a note's box needs of the sheet it is on: to be placed, and to know whether it is where
      * a new note's goes.
@@ -192,11 +212,10 @@ export declare namespace Comment {
          * Places a note's box among the sheet's movables, with the note as its content.
          *
          * @param comment The note.
-         * @param anchor Where the box is, its cells counted from the note's; `null` for where Excel
-         * puts a new note's.
+         * @param placement Where the box is; `null` for where Excel puts a new note's.
          * @param hidden Whether the box appears only while its cell is pointed at.
          */
-        add(comment: Comment, anchor: IMovable.AnchorOffset | null, hidden: boolean): NoteMovable;
+        add(comment: Comment, placement: BoxPlacement | null, hidden: boolean): NoteMovable;
         /**
          * Whether a box is where a new note's goes, which a note saves nothing for.
          */
@@ -218,6 +237,10 @@ interface State extends AbstractAnchored.State {
     description: string | null;
     /** How a note's box is drawn when not the default: markup a file's writer replays. */
     boxXml: string | null;
+    /** The fill a note's box states. */
+    boxFill: IFill.JSON | null;
+    /** The line a note's box states. */
+    boxStroke: IStroke.JSON | null;
 }
 export {};
 //# sourceMappingURL=Comment.d.ts.map

package/types/src/comment/IComment.d.ts

@@ -1,11 +1,14 @@
+import { Bounds } from '@sheetxl/utils';
 import { IAnchored } from '../anchored';
 import { ICellRange } from '../cellRange';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 import { IPerson } from '../person';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { IMovable } from '../movable';
 import { IRichText } from '../text';
+import { IFill, IStroke } from '../fill';
+import { IShapeStyle } from '../shape';
 /**
  * A comment on a cell: the root of a thread, with its replies, or a note.
  *
@@ -54,6 +57,22 @@ export interface IComment extends IAnchored, IMovable.IContent {
      * ```
      */
     getMovable(): IMovable | null;
+    /**
+     * The fill and line of a note's box, or `null` for a threaded comment, which has no box.
+     *
+     * @remarks
+     * A note that states neither draws Excel's default: the system tooltip background
+     * ({@link IColor.Named.InfoBk}) and a thin line in the tooltip text color. Excel takes only
+     * literal colors here; a theme color is written to a file as the color it resolves to.
+     *
+     * @example
+     * ```ts
+     * const note = sheet.getComments().add('B2', 'Check this', { asNote: true });
+     * note.getStyle()!.setFill('#ccffcc');
+     * note.getStyle()!.getStroke().setWidth(2.25);
+     * ```
+     */
+    getStyle(): IShapeStyle | null;
     /**
      * Deletes the comment: its replies with it, or a note's box.
      */
@@ -61,7 +80,7 @@ export interface IComment extends IAnchored, IMovable.IContent {
     /**
      * The sheet the comment is on.
      */
-    getSheet(): ISheet;
+    getWorksheet(): IWorksheet;
     /**
      * The cell the comment is on.
      *
@@ -339,8 +358,26 @@ export declare namespace IComment {
          */
         anchor?: IMovable.AnchorOffset;
         /**
-         * How the box is drawn when that is not Excel's default, held as it was read: the VML
-         * `<v:shape>` without its id, its position or its cell.
+         * Where the box is in pixels from the sheet's top-left, for a box placed by position rather
+         * than by cells. Used only when there is no {@link anchor}; once loaded, the box is anchored
+         * to the cells under it and saves an `anchor`.
+         *
+         * @remarks
+         * A VML note shape with no `<x:Anchor>` (openpyxl writes them) is placed this way in Excel,
+         * literally, wherever its note's cell is.
+         */
+        bounds?: Bounds;
+        /**
+         * The box's fill, where it states one. Absent draws Excel's default.
+         */
+        fill?: IFill.JSON;
+        /**
+         * The box's line, where it states one. Absent draws Excel's default.
+         */
+        stroke?: IStroke.JSON;
+        /**
+         * The rest of how the box is drawn when that is not Excel's default, held as it was read: the
+         * VML `<v:shape>` without its id, its position, its cell, its fill or its line.
          */
         xml?: string;
     }

package/types/src/comment/_NoteBox.d.ts

@@ -1,6 +1,7 @@
 import { IRange } from '@sheetxl/primitives';
 import { Bounds } from '@sheetxl/utils';
 import { IMovable } from '../movable';
+import { IWorksheet } from '../sheet';
 import { Movable } from '../movable/Movable';
 /**
  * Where a note's box goes when nothing has moved it, and how a note stores where its box is.
@@ -8,7 +9,8 @@ import { Movable } from '../movable/Movable';
  * @remarks
  * The default is Excel's, probed with hidden COM on a 96-DPI machine (2026-09-30): a 144×79 px
  * box hung 15 px right of its cell and 10 px above its top, flipped to the other side when it
- * would pass the sheet's last column or row. It is pixel geometry first and the cells those
+ * would pass the sheet's last column or row. A note on a merged cell hangs beside the merge
+ * (probed 2026-10-20). It is pixel geometry first and the cells those
  * pixels fall on second, so tall, narrow and hidden rows and columns need no rule of their own.
  *
  * A note stores its box's anchor with the cells counted from the note's own, so a note copied
@@ -24,10 +26,25 @@ export declare const NOTE_DEFAULT_HEIGHT = 79;
  * The cell geometry placing a box needs: the same three a movable is built with.
  */
 export type NoteLayout = Required<Pick<Movable.ConstructorOptions, 'getBoundsAtCoords' | 'getCoordsAtBounds' | 'getMaxBounds'>>;
+/** The merge a cell is in, or `null` when it is in none. */
+export type MergeAt = (cell: IRange.CellCoords) => IRange.Coords | null;
+/** {@link MergeAt} through a sheet's cells, for once it has loaded. */
+export declare const sheetMergeAt: (sheet: IWorksheet) => MergeAt;
+/**
+ * The cells a note's box hangs beside: the note's cell, or the merge it anchors.
+ */
+export declare function noteBoxTarget(mergeAt: MergeAt, cell: IRange.CellCoords): IRange.Coords;
 /**
  * The bounds of a note's box when nothing has moved or resized it.
+ *
+ * @param target The cells the box hangs beside, from {@link noteBoxTarget}.
+ */
+export declare function defaultNoteBounds(target: IRange.Coords, layout: NoteLayout): Bounds;
+/**
+ * Bounds measured from the sheet's top-left (as a file's VML `style` places a box with no anchor)
+ * in the layout's coordinates.
  */
-export declare function defaultNoteBounds(cell: IRange.CellCoords, layout: NoteLayout): Bounds;
+export declare function sheetNoteBounds(bounds: Bounds, layout: NoteLayout): Bounds;
 /**
  * The cells and offsets a box's corners fall on, as a movable is loaded from.
  */

package/types/src/condition/AnchoredConditional.d.ts

@@ -4,6 +4,7 @@ import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 import { Tuple, ISparseGrid } from '../collections';
 import { ICalculation } from '../calculation';
+import { FormulaHost } from '../calculation/grid';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { ICondition } from '../condition';
 import { ConditionFormulaBinding } from '../condition/_ConditionFormula';
@@ -15,7 +16,7 @@ import * as _ConditionUtils from '../condition/_ConditionUtils';
  * Implementation of {@link IDataValidation}.
  */
 export declare abstract class AnchoredConditional<STATE extends AnchoredConditional.State, EVENTS extends ICondition.Events = ICondition.Events, JSON = any> extends AbstractAnchored<STATE, EVENTS> implements IAnchored, ITransaction.ITransactional, IListener.ISource<IAnchored> {
-    protected _rangeListener: ICellRange.Listener | null;
+    protected _rangeListener: ICellRange.Listener<ICellRanges> | null;
     protected _getValueGrid: () => ISparseGrid<Scalar>;
     /**
      * One registered watch per formula the condition asked for, keyed by the formula: its remove, and
@@ -45,8 +46,29 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
     protected abstract _getActionDescription(action: 'delete' | 'initialize' | 'updateListener'): string | null;
     /** @internal */
     protected abstract _getType(): string;
-    /** @internal */
-    protected abstract _processValueUpdates(range: ICellRange | null): void;
+    /**
+     * Re-judges the rule after a change.
+     *
+     * @returns What the re-judging awaits, when it does: counted as calculation in flight until it
+     * settles (see `ICalculation.waitUntil`).
+     * @internal
+     */
+    protected abstract _processValueUpdates(range: ICellRange | null): void | Promise<void>;
+    /**
+     * Whether this rule's formula watches evaluate a blank region the answer of which depends on
+     * the position only where the rule is read (`WatchAnchor.Options.paged`): a cell not read yet
+     * has no answer and judges as no match until its tile is delivered. Right for a rule read a
+     * window at a time - a format, painted where it is on screen - and not for one whose every
+     * answer is wanted at once.
+     * @internal
+     */
+    protected _pagesWatches(): boolean;
+    /**
+     * Whether every formula watch of this rule holds its answer at a cell of the area at
+     * `areaIndex`, asking for the cell where one does not (see `FormulaHost.request`).
+     * @internal
+     */
+    protected _requestWatchedCell(areaIndex: number, row: number, column: number): boolean;
     /** @internal */
     protected abstract _fromJSON(json: JSON | undefined, options?: ITransaction.OperationOptions): void;
     /** @internal */
@@ -64,7 +86,7 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
      * cluster: one calc pass notifies each rule it intersects, and a burst of deliveries would
      * otherwise start a burst of evaluations for the newest one to win. Coalescing on a microtask
      * rather than a commit hook is deliberate: the calc-results path notifies AFTER its transaction
-     * commits (`trigger: 'calc'`), so a commit hook never sees the most frequent trigger.
+     * commits (a `'data'` event with no commit), so a commit hook never sees the most frequent trigger.
      *
      * Two same-tick marks widen to the whole rule rather than accumulating a range list — the
      * subclasses evaluate per whole range anyway, and a rule's ranges are small.
@@ -309,9 +331,13 @@ export declare class AreaResultCollector {
  */
 interface WatchEntry {
     remove: IListener.Remove;
+    /** The areas the watch was registered over, as an address: a rule reshaped since asks again. */
+    areas: string;
     values: (IRange | null)[];
     /** Resolvers waiting on an area's first delivery — a LIST: passes overlap, and each has its own. */
     pending: (((values: IRange | null) => void)[])[];
+    /** Each area's host, once registered: what a paged watch is asked for cells through. */
+    hosts: (FormulaHost | undefined)[];
 }
 /**
  * Tables are designed to be instantiated as both standalone and anchored items that represent a table of data on a sheet.

package/types/src/condition/ICondition.d.ts

@@ -389,9 +389,10 @@ export declare namespace ICondition {
          */
         cellColor?: boolean;
         /**
-         * If filtered then the id.
+         * The format to match: its fill when {@link ICondition.ColorOption.cellColor} is `true`,
+         * otherwise its font color.
          */
-        styleId?: number;
+        style?: ICellStyle.Properties;
     }
     /**
      * Types of time-periods.

package/types/src/conditionalFormat/ConditionalFormat.d.ts

@@ -4,7 +4,7 @@ import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { ICellStyle, IStyleCollection } from '../style';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { ISparseGrid, ISpatialMap } from '../collections';
 import { ICalculation } from '../calculation';
 import { BlankResolver } from '../condition/_ConditionUtils';
@@ -61,12 +61,18 @@ export declare class ConditionalFormat extends AnchoredConditional<State, ICondi
     protected _initialize(options: ConditionalFormat.ConstructorOptions): void;
     /** @internal */
     protected _getType(): string;
+    /**
+     * A format is read where it is painted, so a whole-column rule whose answer depends on the row
+     * (`ISODD(ROW())`) is evaluated a window at a time rather than a million cells at once.
+     * @internal
+     */
+    protected _pagesWatches(): boolean;
     /** @internal */
     protected _getActionDescription(action: 'delete' | 'initialize' | 'updateListener'): string | null;
     /** @internal */
     protected _getDefaultState(options: ConditionalFormat.ConstructorOptions): Readonly<State>;
     /** @internal */
-    protected _processValueUpdates(_range?: ICellRange | null): void;
+    protected _processValueUpdates(_range?: ICellRange | null): Promise<void>;
     /**
      * Resolves every stop to the number it stands for, in the order they were authored.
      *
@@ -168,7 +174,7 @@ export declare class ConditionalFormat extends AnchoredConditional<State, ICondi
 }
 export declare namespace ConditionalFormat {
     interface ConstructorOptions extends AnchoredConditional.ConstructorOptions<IConditionalFormat.JSON> {
-        sheet?: ISheet;
+        sheet?: IWorksheet;
     }
 }
 interface State extends AnchoredConditional.State {