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

package/types/src/cellRange/ICellRange.d.ts

@@ -4,24 +4,26 @@ import { ITypes } from '../type';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 import { IHyperlink } from '../hyperlink';
-import { IComment } from '../comment';
+import { IRichText } from '../text';
+import { IComment, ICommentCollection } from '../comment';
 import { ISort } from '../sort';
 import { ICondition } from '../condition';
 import { IAutoFill } from '../autoFill';
-import { IStyle } from '../style';
+import { ICellStyle } from '../style';
 import { ICalculation } from '../calculation';
 import { ITable, ITableCollection } from '../table';
 import { IMovable, IMovableCollection } from '../movable';
 import { IDataValidation, IDataValidationCollection } from '../dataValidation';
 import { IConditionalFormat } from '../conditionalFormat/IConditionalFormat';
 import { IConditionalFormatCollection } from '../conditionalFormat/IConditionalFormatCollection';
-import { ISheet } from '../sheet';
+import { IProtectedRange, IProtectedRangeCollection } from '../protectedRange';
+import { IWorksheet } from '../sheet';
 import { ICell } from '../cell';
 import { ICellRanges } from './ICellRanges';
 import { ICellRegions } from './ICellRegion';
 import { ICellHeaderRange } from './ICellHeaderRange';
 /**
- * A {@link ICellRange} represents a rectangular collection of {@link ICell} within an {@link ISheet}.
+ * A {@link ICellRange} represents a rectangular collection of {@link ICell} within an {@link IWorksheet}.
  *
  * **Naming Conventions:** Methods usually adhere to the following conventions except
  * when adhering to a idiomatic existing conventions of Typescript (for example `size` or 'length'):
@@ -66,6 +68,18 @@ export interface ICellRange {
      * * @returns An array of 'IRange.Coords` that contain merges.
      */
     getMerges(): IRange.Coords[];
+    /**
+     * Returns the unlocked ranges (Excel's *Allow Edit Ranges*) that overlap the range.
+     *
+     * @param options The filters of {@link IProtectedRangeCollection.getItems} without `address` —
+     * this range is the address.
+     *
+     * @remarks
+     * See {@link getConditionalFormats} for the overlap and one-entry-per-item rules, which are the
+     * same for every ranged item lookup. A cell can also be unlocked by its style
+     * (`ICellStyle.getProtection()`); {@link ICell.isEditAllowed} answers for both.
+     */
+    getUnlocked(options?: ICellRange.GetItemsOptions<IProtectedRangeCollection.GetItemsOptions>): IProtectedRange[];
     /**
      * Returns the {@link IConditionalFormat}s that overlap the range.
      *
@@ -77,7 +91,7 @@ export interface ICellRange {
      * pass `fullyContained` for the stricter question.
      *
      * The items are the sheet's — this is a scoped view of
-     * `getSheet().getConditionalFormats()`, not a copy — and each appears **once**, however many of
+     * `getWorksheet().getConditionalFormats()`, not a copy — and each appears **once**, however many of
      * its ranges the query hit. The range only says *which* items; ask an item where it lives with
      * {@link IConditionalFormat.getRanges}.
      */
@@ -96,6 +110,17 @@ export interface ICellRange {
      * same for every ranged item lookup.
      */
     getDataValidations(options?: ICellRange.GetItemsOptions<IDataValidationCollection.GetItemsOptions>): IDataValidation[];
+    /**
+     * Returns the {@link IComment}s on cells within the range.
+     *
+     * @param options The filters of {@link ICommentCollection.getItems} without `address` — this
+     * range is the address.
+     *
+     * @remarks
+     * The items are the sheet's — a scoped view of `getWorksheet().getComments()`, not a copy. A
+     * comment is on one cell, so each appears once, in reading order.
+     */
+    getComments(options?: ICellRange.GetItemsOptions<ICommentCollection.GetItemsOptions>): IComment[];
     /**
      * Returns the {@link ITable}s that overlap the range.
      *
@@ -127,6 +152,15 @@ export interface ICellRange {
      * {@link ICellRange.getCells}
      */
     getCell(address?: ICell.Address): ICell;
+    /**
+     * Exists to have api parity with Office Scripts: `row` and `column` are 0-based offsets from the
+     * range's top left.
+     *
+     * @deprecated Use {@link getCell}`('B3')`, or `getCell({ rowIndex, colIndex })` with sheet
+     * coordinates.
+     * @hidden
+     */
+    getCell(row: number, column: number): ICell;
     /**
      * Return a 2D array of {@link ICell | cells} in the shape of the range.
      *
@@ -147,6 +181,24 @@ export interface ICellRange {
      * {@link ICellRange.getValues}
      */
     getValue(): Scalar;
+    /**
+     * Returns the top left cell's value as displayed, with its number format applied.
+     *
+     * @remarks
+     * The same as `getCell().getText(options)`.
+     *
+     * @see
+     * {@link ICell.getText}
+     */
+    getText(options?: ICell.GetTextOptions): string;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getCells}`()` and each cell's `getText()`, or {@link getText} for the
+     * top left cell.
+     * @hidden
+     */
+    getTexts(): string[][];
     /**
      * Returns the value for the top left `InteropScalar`.
      *
@@ -164,7 +216,20 @@ export interface ICellRange {
      * When querying the style the values will always be for the top left. However the
      * set values work for the entire range.
      */
-    getStyle(): IStyle;
+    getStyle(): ICellStyle;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getStyle}.
+     * @hidden
+     */
+    getFormat(): ICellStyle;
+    /**
+     * @deprecated Use {@link getStyle}`().update(style)`, or a setter on the style:
+     * `getStyle().getFont().setBold(true)`.
+     * @hidden
+     */
+    setStyle(style: ICellStyle.Update, options?: ICellStyle.UpdateOptions): this;
     /**
      * Returns the formula for the range.
      *
@@ -173,30 +238,90 @@ export interface ICellRange {
      * @remarks
      * When querying the formula this will always be for the top left. However the
      * set values work for the entire range.
+     *
+     * Returns the formula object, or `null` for a cell without one. For formula text across the
+     * whole range use {@link ICellRange.getFormulas}, which reads `''` for cells without a formula.
      */
     getFormula(address?: ICell.Address): ICalculation.IFormula;
+    /**
+     * Returns the formula text of every cell in the range.
+     *
+     * @returns A row-major 2D array in the shape of the range.
+     *
+     * @remarks
+     * - Each formula reads as entered, with its leading `=` (`'=SUM(A1:A3)'`), so the result can be
+     *   passed straight back to {@link ICellRange.setFormulas}.
+     * - A cell without a formula reads as an empty string `''`, not `null`. This differs from
+     *   {@link ICell.getFormulaText} and {@link ICellRange.getFormula}, which return `null`.
+     * - Throws if the range holds more than `10000` cells, like {@link ICellRange.getValues}.
+     *
+     * @see {@link ICellRange.getFormula}
+     */
+    getFormulas(): string[][];
+    /**
+     * Returns the number format of the top-left cell.
+     *
+     * @remarks
+     * Reads the top-left cell, the same contract as {@link ICellRange.getValue} and
+     * {@link ICellRange.getStyle}. A cell without an authored format reads `'General'`.
+     *
+     * @see {@link ICellStyle.getNumberFormat}
+     */
+    getNumberFormat(): string;
+    /**
+     * Returns the number format of every cell in the range.
+     *
+     * @returns A row-major 2D array in the shape of the range.
+     *
+     * @remarks
+     * - A cell without an authored format reads `'General'`.
+     * - Throws if the range holds more than `10000` cells, like {@link ICellRange.getValues}.
+     *
+     * @see {@link ICellStyle.getNumberFormat}
+     */
+    getNumberFormats(): string[][];
+    /**
+     * Sets one number format on every cell in the range.
+     *
+     * @param numFmt The format code, or `null` to clear it.
+     *
+     * @see {@link ICellStyle.setNumberFormat}
+     */
+    setNumberFormat(numFmt: string | null, options?: ICellStyle.UpdateOptions): this;
+    /**
+     * Sets the number format of each cell in the range.
+     *
+     * @param formats Format codes in row-major order.
+     *
+     * @remarks
+     * An array smaller than the range writes only the cells it covers, as {@link ICellRange.setValues} does.
+     *
+     * @see {@link ICellRange.setNumberFormat}
+     */
+    setNumberFormats(formats: readonly string[][], options?: ICellRange.UpdateCellsOptions): this;
     /**
      * Parses a formula expression and returns a *transient* formula object anchored at this range's
      * top-left cell.
      *
      * @param expression The formula expression to parse.
+     * @param options Optional parse options; the expression is storage text unless `target` is `'display'`.
      *
      * @remarks
      * The anchored convenience form: equivalent to
-     * `getSheet().createFormula(expression, topLeftCoords)`, where the anchor is this
+     * `getWorksheet().createFormula(expression, topLeftCoords)`, where the anchor is this
      * range's top-left cell. Nothing is committed — the formula is not registered in the workbook
      * or the dependency graph.
      *
-     * Two behaviors follow from the sheet form (see {@link ISheet.createFormula}):
+     * Two behaviors follow from the sheet form (see {@link IWorksheet.createFormula}):
      *
      * - A bare reference (`A2`) resolves against THIS range's sheet, never the selected one.
      * - Relative references resolve **relative to the anchor cell**, so the expression reads
      *   exactly as it would if it were authored here.
      *
-     * @see {@link ISheet.createFormula}
+     * @see {@link IWorksheet.createFormula}
      * @see {@link ICalculation.createFormula}
      */
-    createFormula(expression: string): ICalculation.IFormula;
+    createFormula(expression: string, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
     /**
      * Returns the intersection of the current range and the specified range.
      *
@@ -242,6 +367,20 @@ export interface ICellRange {
      * @returns `ICellRange` at the repositioned range.
      */
     getEntireRows(shift?: boolean, options?: ICellRange.GetRangeOptions): this;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getEntireRows}.
+     * @hidden
+     */
+    getEntireRow(): this;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getEntireColumns}.
+     * @hidden
+     */
+    getEntireColumn(): this;
     /**
      * Returns a range that includes the current range up to a content edge boundary.
      *
@@ -486,6 +625,27 @@ export interface ICellRange {
      * merges.
      */
     getDefaultSortCriteria(axis?: IRange.Axis, cell?: ICell.Address): ISort.DefaultSortCriteria | null;
+    /**
+     * Returns the fill this range implies — which cells it would read, which it would cover, the
+     * fill types that can be offered for it, and the one to open on.
+     *
+     * @param direction Which way the series runs. Defaults to the range's own shape: a single row
+     * runs `Right`, anything else runs `Down` — or, with a `destination`, to the way it extends.
+     * @param destination Fill the range as it is to here — the fill handle's drag. The template is
+     * then the WHOLE range, blanks included, rather than its leading run, and `destination` must
+     * extend it on exactly one edge as {@link autoFill} requires.
+     * @returns `IAutoFill.DefaultCriteria`, or `null` where there is nowhere to fill: the range is
+     * one cell deep along `direction`, or `destination` does not extend it — which is also how a
+     * surface learns that a direction is not on offer at all.
+     * @throws `Error` If `destination` does not share three edges with the range, or `direction` is
+     * not the way it extends.
+     *
+     * @remarks
+     * Useful for displaying options to the ui — a Series dialog, or a fill menu deciding what to
+     * grey. Nothing is filled and nothing is committed; see {@link autoFill} to run one, and
+     * {@link AutoFill.toFillOptions} for the options a chosen {@link IAutoFill.Preset} amounts to.
+     */
+    getDefaultAutoFillCriteria(direction?: IRange.Direction, destination?: ICellRange.Address): IAutoFill.DefaultCriteria | null;
     /**
      * Returns the ranges immediately referenced by the formulas in this range.
      *
@@ -494,39 +654,39 @@ export interface ICellRange {
      * rather than a fan-out — the calculation graph is indexed by range, so the cell form is this
      * one over a 1×1.
      *
-     * - Returns `null` when there are none.
+     * - Resolves `null` when there are none; see {@link ICell.getDirectPrecedents} for when it resolves.
      * - **Not filtered against the range itself.** A block containing both a formula and its input
      *   lists that input; "what does this block read" and "what does it read from outside" are
      *   different questions, and the second is {@link getDifferences} away.
      */
-    getDirectPrecedents(): ICellRanges | null;
+    getDirectPrecedents(): Promise<ICellRanges | null>;
     /**
      * Returns the cells that directly reference any cell in this range.
      *
      * @remarks
      * The range form of {@link ICell.getDirectDependents} — the immediate consumers of anything
-     * this range produces. Returns `null` when there are none.
+     * this range produces. Resolves `null` when there are none.
      */
-    getDirectDependents(): ICellRanges | null;
+    getDirectDependents(): Promise<ICellRanges | null>;
     /**
      * Returns all ranges contributing to this range's values, through the full calculation chain.
      *
      * @remarks
      * The range form of {@link ICell.getPrecedents}: a recursive walk upstream to the root data
-     * sources. Returns `null` when there are none.
+     * sources. Resolves `null` when there are none.
      *
      * **Reach for this before editing.** The precedents of a block are what its values depend on,
      * so they are what a change to it can be wrong about.
      */
-    getPrecedents(): ICellRanges | null;
+    getPrecedents(): Promise<ICellRanges | null>;
     /**
      * Returns all cells eventually affected by this range, through the full calculation chain.
      *
      * @remarks
      * The range form of {@link ICell.getDependents}: a recursive walk downstream giving the total
-     * blast radius of a write here. Returns `null` when there are none.
+     * blast radius of a write here. Resolves `null` when there are none.
      */
-    getDependents(): ICellRanges | null;
+    getDependents(): Promise<ICellRanges | null>;
     /**
      * Returns the statistics for the range.
      *
@@ -541,12 +701,6 @@ export interface ICellRange {
      * indexes) — they do not overlap.
      */
     getStats(options?: ICellRange.GetStatsOptions): IRangeStats;
-    /**
-     * Returns a count for of values.
-     *
-     * @deprecated Use `getStats`.
-     */
-    getCount(): number;
     /**
      * Returns per-feature cell counts for the range.
      *
@@ -559,6 +713,8 @@ export interface ICellRange {
      *
      * - Every public {@link ICellRange.Feature} appears as a key; features not requested, or not
      *   present, are an explicit `0` — the shape is stable and self-describing, never `null`.
+     *   `anomalies` is the exception: it is derived on read, so it is counted, and its key
+     *   present, only when requested by name.
      * - Each feature is counted **independently**. `getCounts([Fill, Border])` is two numbers,
      *   not the count of their refined intersection — the refined count *is* `getRegions`.
      * - Counts are cells, never regions: a region count would either disagree with the partition
@@ -595,19 +751,47 @@ export interface ICellRange {
      *   feature-bearing side of the partition.
      * - **Nothing is computed until the result is iterated or counted.** The returned
      *   {@link ICellRegions} is a lazily backed handle, so building the query costs nothing.
-     * - **`Contentful` regions are maximal rectangles.** Every other feature's stored blocks stand
-     *   for a payload two adjacent blocks can disagree about — a fill's color, a formula's
-     *   expression — so distinct blocks stay distinct or the region stops being uniform. Occupancy
-     *   is a boolean: any two occupied rectangles agree, so its blocks carry no information and are
-     *   coalesced. A solid `A1:D4` is one region, not the four column strips it is stored as.
-     *   Refinement is unaffected — `[Contentful, Fill]` still partitions by fill and still excludes
-     *   unoccupied cells.
+     * - **Regions follow the payload, not how it was written.** A solid `A1:D4` is one
+     *   `Contentful` region, and a number format applied in three strokes (or loaded from a file
+     *   that stored it in pieces) is one `NumberFormat` region. The same holds for `Fill` and the
+     *   other content-style features (`Font`, `Alignment`, `Protection`), and each of those splits
+     *   only on its own part: a bold column inside a uniform number format does not split the
+     *   `NumberFormat` region. `Borders` is the exception — a border's edges belong to the block
+     *   it was applied to, so two equal boxes side by side are two regions. Refinement is
+     *   unaffected — `[Contentful, Fill]` still partitions by fill and still excludes unoccupied
+     *   cells.
      * - Every {@link Feature} partitions — there is no throwing member left. `DateFormat` splits by
      *   format string, the same way `Fill` splits by color; `Error` splits by error value, backed
      *   by the reconciled error index. Scalar kinds (`String`/`Number`/`Boolean`) are not in this
      *   vocabulary at all — see {@link Feature}'s own remarks for where they went.
      */
     getRegions(features?: ICellRange.Feature | readonly ICellRange.Feature[], options?: ICellRange.GetRegionsOptions): ICellRegions;
+    /**
+     * Returns the regions of the `anomalies` feature in reading order: the named checks first, then
+     * the rest, each by rank.
+     *
+     * @param options {@link ICellRange.GetAnomaliesOptions}
+     *
+     * @example
+     * ```ts
+     * // Hunting an embedded hardcode: read its checks' findings first, 25 regions at a time.
+     * sheet.getAnomalies({ checks: ['hardcodeInRun', 'styleRole'], limit: 25 });
+     * sheet.getAnomalies({ checks: ['hardcodeInRun', 'styleRole'], limit: 25, offset: 25 });
+     * ```
+     *
+     * @remarks
+     * The regions are the ones {@link getRegions | getRegions('anomalies')} returns, with the same
+     * findings and ranks ({@link ICell.Anomaly}); only the order and the window differ. A region
+     * whose findings include the first named check lists first, highest rank of that check first;
+     * then the second check's; then every region no named check fires on, by its highest rank. A
+     * region two named checks fire on lists once, under the first. An ignored check
+     * ({@link setErrorIgnored}) is not there to list.
+     *
+     * `offset` and `limit` page through that one order, so successive windows neither skip nor
+     * repeat a region; a window shorter than `limit` is the last. `getRegions('anomalies').getCount()`
+     * is the length of the whole list.
+     */
+    getAnomalies(options?: ICellRange.GetAnomaliesOptions): ICellRegions;
     /**
      * Returns a 2D array of {@link Scalar | values} in the shape of the range.
      *
@@ -636,8 +820,8 @@ export interface ICellRange {
      * @remarks
      * - `null` values will clear the corresponding cells.
      * - `undefined` values will be ignored, leaving the existing cell values unchanged.
-     * - If an array is passed the values will be in row-major order and will repeat if the range is larger than the array
-     * - If a single value is passed in it will repeat the entire range.
+     * - The array is row-major. An array smaller than the range writes only the cells it covers.
+     * - A single value is {@link setValue}, which fills the range with it.
      */
     setValues(values: ICellRange.ValuesUpdate, options?: ICellRange.SetValuesOptions): this;
     /**
@@ -660,7 +844,7 @@ export interface ICellRange {
      * @see
      * {@link ICellRange.setValues}
      */
-    setValue(value: ICellRange.ValuesUpdateOrCallback, options?: ICellRange.SetValuesOptions): this;
+    setValue(value: ICellRange.ScalarUpdateOrCallback, options?: ICellRange.SetValuesOptions): this;
     /**
      * Set the formula for a range.
      *
@@ -668,11 +852,24 @@ export interface ICellRange {
      * @returns The current `ICellRange`.
      *
      * @remarks
-     * Identical behavior to setValue. Exists for ergonomics
+     * Identical behavior to setValue. Exists for ergonomics.
+     *
      * @see
      * {@link ICellRange.setValue}
      */
-    setFormula(value: ICellRange.ValuesUpdateOrCallback, options?: ICellRange.SetValuesOptions): this;
+    setFormula(value: ICellRange.ScalarUpdateOrCallback, options?: ICellRange.SetValuesOptions): this;
+    /**
+     * Sets the formula of each cell in the range.
+     *
+     * @param formulas Formula text in row-major order, each with a leading `=`.
+     *
+     * @remarks
+     * The same write as {@link ICellRange.setValues}: text with a leading `=` is entered as a
+     * formula, and an array smaller than the range writes only the cells it covers.
+     *
+     * @see {@link ICellRange.getFormulas}
+     */
+    setFormulas(formulas: readonly string[][], options?: ICellRange.SetValuesOptions): this;
     /**
      * Re-evaluates and formulas within the range.
      *
@@ -718,10 +915,68 @@ export interface ICellRange {
      * @returns The current `ICellRange`.
      */
     autoFit(options?: ICellRange.AutoFitOptions): this;
+    /**
+     * Groups the rows or columns of the range: each one moves one outline level deeper.
+     *
+     * @param axis Whether to group the rows or the columns. When omitted, entire rows group the rows,
+     * entire columns group the columns, and any other range groups both.
+     * @returns The current `ICellRange`.
+     * @throws `Error` If a row or column in the range is already at the deepest level, `7`. Nothing is
+     * grouped.
+     *
+     * @see {@link IWorksheet.getOutline}
+     */
+    group(axis?: IRange.Axis, options?: ITransaction.OperationOptions): this;
+    /**
+     * Ungroups the rows or columns of the range: each grouped one moves one outline level out.
+     * Rows or columns that are not grouped are left alone.
+     *
+     * @param axis Whether to ungroup the rows or the columns. When omitted, chosen as for
+     * {@link group}.
+     * @returns The current `ICellRange`.
+     */
+    ungroup(axis?: IRange.Axis, options?: ITransaction.OperationOptions): this;
+    /**
+     * Expands the groups the range selects: those whose summary row or column is in the range or,
+     * when there are none, the innermost groups the range meets.
+     *
+     * @param axis Whether to expand row groups or column groups. Inferred when the range is entire
+     * rows or entire columns; required otherwise.
+     * @returns The current `ICellRange`.
+     * @throws `Error` If the axis is not given and cannot be inferred.
+     *
+     * @remarks
+     * Groups nested inside that are collapsed stay collapsed.
+     */
+    showGroupDetails(axis?: IRange.Axis, options?: ITransaction.OperationOptions): this;
+    /**
+     * Collapses the groups the range selects, chosen as for {@link showGroupDetails}: their details are
+     * hidden.
+     *
+     * @param axis Whether to collapse row groups or column groups. Inferred as for
+     * {@link showGroupDetails}.
+     * @returns The current `ICellRange`.
+     * @throws `Error` If the axis is not given and cannot be inferred.
+     */
+    hideGroupDetails(axis?: IRange.Axis, options?: ITransaction.OperationOptions): this;
+    /**
+     * Removes the outline levels from the rows and columns of the range. Hidden rows and columns
+     * stay hidden.
+     *
+     * @param axes Which levels to remove. Default `IRange.AxisSelection.Both`.
+     * @returns The current `ICellRange`.
+     *
+     * @remarks
+     * The counterpart of Excel's `Range.ClearOutline`: both axes over the range's rows and columns,
+     * so entire rows also clear every column's levels unless `axes` names the rows, and a single
+     * cell clears the whole sheet. To outline a sheet from its formulas see
+     * {@link IOutline.autoOutline}.
+     */
+    clearGroups(axes?: IRange.AxisSelection, options?: ITransaction.OperationOptions): this;
     /**
      * Clear the range.
      *
-     * @param applyTo The type of content to clear. Default `ICell.Content.Values`
+     * @param applyTo The type of content to clear. Defaults to all`
      * @returns The current `ICellRange`.
      */
     clear(applyTo?: ICell.Content, options?: ITransaction.OperationOptions): this;
@@ -736,15 +991,46 @@ export interface ICellRange {
      */
     setHyperlink(hyperlink: IHyperlink.Update, options?: ITransaction.OperationOptions): this;
     /**
-     * Update the comments for the range.
+     * Sets the text of every cell in the range as formatted runs.
+     *
+     * @param runs The runs, or plain text for one run. A run's font records what it sets over the
+     * cell's font: `{ text: 'Bold', font: { bold: true } }` then `{ text: ' plain' }`.
+     * @returns The current `ICellRange`.
+     *
+     * @remarks
+     * The value becomes a `RichText`: text to calculation (`LEN`, `&`, `TYPE()` 2) and formatting
+     * to the renderer, carried whole by a reference. A later `setValue` replaces it, runs and all,
+     * as any value write does. Read it with {@link ICell.getRichText}.
+     */
+    setRichText(runs: IRichText.Update, options?: ITransaction.OperationOptions): this;
+    /**
+     * Ignores, or stops ignoring, one of Excel's error checks over the range: the green triangle's
+     * **Ignore Error**.
      *
-     * @param comments Comment properties
+     * @param check The check.
+     * @param ignored `false` to show the check's indicator again. Defaults to `true`.
      * @returns The current `ICellRange`.
      *
      * @remarks
-     * **NOT FINISHED**
+     * SheetXL does not run the checks yet; the setting is kept for Excel. It follows the cells through
+     * inserts and deletes, is not copied, and is dropped from a cell that is written or cleared, as
+     * in Excel. Read it with {@link ICell.isErrorIgnored}; find it with {@link getRegions} and
+     * {@link Feature.IgnoredErrors}.
      */
-    setComments(comments: IComment.Properties, options?: ITransaction.OperationOptions): this;
+    setErrorIgnored(check: ICell.ErrorCheck, ignored?: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Sets or clears the comment on the range's first cell.
+     *
+     * @param comments Comment modifiers, a plain string as the content, or `null` to remove.
+     * @returns The current `ICellRange`.
+     *
+     * @remarks
+     * A comment is on one cell, so a value goes on the range's top-left cell — updating the comment
+     * there if it has one, adding one otherwise — while `null` clears every comment within the
+     * range. The comment itself is the richer surface: `getWorksheet().getComments()` to add, and
+     * {@link ICell.getComments} to reach the one on a cell.
+     */
+    setComments(comments: IComment.Update, options?: ITransaction.OperationOptions): this;
     /**
      * Merges all cells within the selection ranges.
      *
@@ -873,7 +1159,7 @@ export interface ICellRange {
      * @param options If a boolean then this indicates if headers are present.
      *
      * @remarks
-     * This behaves similarly to {@link ISheet.getTables.add} but uses the current range
+     * This behaves similarly to {@link IWorksheet.getTables.add} but uses the current range
      */
     addTable(options?: ITableCollection.AddOptions | boolean): ITable;
     /**
@@ -908,6 +1194,24 @@ export interface ICellRange {
      * * Will return `null` if nothing was inserted or the source doesn't have a range.
      */
     insertFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.InsertFromOptions): Promise<this | null>;
+    /**
+     * Whether {@link insertFrom} would go through, asked without performing it.
+     *
+     * @param source The source that would be inserted - the same argument `insertFrom` takes.
+     * @param options The same options `insertFrom` would be given; `axis` and `isCut` both change the
+     *   answer, so pass the ones the real call will use.
+     * @returns `false` when `insertFrom` would refuse, `true` otherwise.
+     *
+     * @remarks
+     * A drop can be refused for reasons the caller cannot see: a cut whose gap the insert would only
+     * half close, a merge the shift would tear or land inside of, a table it would split. This answers
+     * the same question `insertFrom` asks itself before it commits, which is what lets an interactive
+     * drag show a drop as refused BEFORE the user commits to it, rather than reporting an error after.
+     *
+     * It reports only what can be known up front. A refusal raised deeper in the operation (protection,
+     * or content pushed off the end of the sheet) still surfaces as a thrown error.
+     */
+    canInsertFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.InsertFromOptions): boolean;
     /**
      * Copies (or cuts) data and formatting from a specified source to the current range.
      *
@@ -933,12 +1237,17 @@ export interface ICellRange {
     /**
      * Perform a set of operations as a batch.
      *
-     * @param callback Function to perform the operations.
+     * @param callback Function to perform the operations. Handed the commit being written and
+     * `range`, this range bound to the batch.
      * @param options Description of the operation or additional options. This will be used for tracking undo/redo and history. @defaultValue 'Range Update'
      * @template R - The callback return type.
      * @returns The result of the callback.
+     *
+     * @remarks
+     * Work through `range` rather than this one: what is reached through it is part of the batch, as
+     * for {@link IWorkbook.doBatch}.
      */
-    doBatch<R>(callback: (commit: ITransaction.ICommit) => Promise<R> | R, options?: string | ITransaction.OperationOptions): Promise<R> | R;
+    doBatch<R>(callback: (commit: ITransaction.ICommit, range: this) => Promise<R> | R, options?: string | ITransaction.OperationOptions): Promise<R> | R;
     /**
      * Creates a `SparseBuilder` for efficiently updating sparsely populated cells in a streaming low memory way.
      *
@@ -1018,11 +1327,17 @@ export interface ICellRange {
      * caller did not ask. To watch a formula belonging to a multi-area rule, fill it first — or use
      * {@link ICellRanges.addWatch}, which does that for every area.
      *
-     * Known limits, both from watching the formula's *written* references: a range discovered at
-     * evaluation time (`INDIRECT`, `OFFSET`) is not watched, and a volatile formula (`NOW`, `RAND`)
-     * has nothing to watch at all. Neither re-fires.
+     * The formula is held by the calculation engine like a formula in a cell: its references follow
+     * row and column inserts and deletes, a reference to deleted cells reads `#REF!`, and undo
+     * restores it. A range the formula discovers at evaluation time (`INDIRECT`, `OFFSET`) is watched
+     * too. A volatile formula (`NOW`, `RAND`) re-evaluates with the engine's pass and does not re-fire
+     * on its own.
+     *
+     * With {@link ICellRange.WatchOptions.arrayFirstCell} each cell is evaluated the way a
+     * conditional-format or data-validation rule evaluates its formula: as an array-entered formula
+     * whose extent is that one cell.
      */
-    addWatch(formula: ICalculation.IFormula | string, callback: ICellRange.WatchCallback): IListener.Remove;
+    addWatch(formula: ICalculation.IFormula | string, callback: ICellRange.WatchCallback, options?: ICellRange.WatchOptions): IListener.Remove;
     /**
      * Returns an iterator that allows you to iterate over the individual values within the range.
      *
@@ -1072,11 +1387,17 @@ export interface ICellRange {
      */
     isContentful(features?: ICellRange.Feature | readonly ICellRange.Feature[]): boolean;
     /**
-     * Returns `true` if the range represents the entire rows.
+     * Returns `true` if the range is entire rows, such as `2:4`: it spans every column of the sheet.
+     *
+     * @remarks
+     * The counterpart of Office Scripts' `isEntireRow`.
      */
     isEntireRows(): boolean;
     /**
-     * Returns `true` if the range represents the entire columns.
+     * Returns `true` if the range is entire columns, such as `B:D`: it spans every row of the sheet.
+     *
+     * @remarks
+     * The counterpart of Office Scripts' `isEntireColumn`.
      */
     isEntireColumns(): boolean;
     /**
@@ -1134,6 +1455,11 @@ export interface ICellRange {
      * @param r1c1 If unspecified returns the environment's default.
      */
     getAddress(r1c1?: boolean): string;
+    /**
+     * @deprecated Use {@link getAddress}.
+     * @hidden
+     */
+    getA1(): string;
     /**
      * Returns the column start.
      */
@@ -1162,7 +1488,7 @@ export interface ICellRange {
      * Checks if the ranges is empty, meaning it has no values or formatting.
      *
      * @remarks
-     * Convenience ```getUsedRange() !== null``` or `getCount() === 0`.
+     * Convenience ```getUsedRange() === null```.
      *
      * @see
      * {@link ICellRange.getUsedRange}
@@ -1171,7 +1497,7 @@ export interface ICellRange {
     /**
      * Returns the Sheet.
      */
-    getSheet(): ISheet;
+    getWorksheet(): IWorksheet;
     /**
      * The IRange.Coords.
      */
@@ -1229,10 +1555,16 @@ export interface INamedRange extends ICellRange {
 export declare namespace ICellRange {
     /**
      * This is either:
-     * 1. A string that can be parsed into a CellRange (e.g. 'A1:B2') or a named range.
+     * 1. A string that can be parsed into a CellRange (e.g. 'A1:B2'), a named range, or a
+     *    structured reference (e.g. `'Sales[[#Headers],[Qty]]'`).
      * 2. Another ICellRange
      * 3. An IRange
      * 4. Partial IRange.FixableCoords
+     *
+     * @remarks
+     * A structured reference is read from the active cell: one without a table name (`'[Qty]'`)
+     * refers to the table at the active cell, and `@` (`'Sales[@Qty]'`) to the active cell's row.
+     * References into another workbook are not supported.
      */
     type Address = string | ICellRange | IRange | Readonly<Partial<IRange.FixableCoords>> | ICell.Address | FormulaError.Ref;
     /**
@@ -1258,13 +1590,13 @@ export declare namespace ICellRange {
      */
     type Update = ICell.Update | readonly ICell.Update[][];
     /**
-     * A union of either a Scalar and 2D array of Scalars or an IRange.
+     * A 2D array of scalars or an IRange. A single value is a {@link ScalarUpdateOrCallback}.
      */
-    type ValuesUpdate = InteropScalarUpdate | IRange | readonly InteropScalarUpdate[][];
+    type ValuesUpdate = IRange | readonly InteropScalarUpdate[][];
     /**
-     * Allows for Values to be set via a callback.
+     * A single value, or a callback that yields one per cell.
      */
-    type ValuesUpdateOrCallback<T = Scalar> = ValuesUpdate | ((row: number, column: number) => T | null);
+    type ScalarUpdateOrCallback<T = Scalar> = InteropScalarUpdate | ((row: number, column: number) => T | null);
     /**
      * The read options a range carries.
      *
@@ -1294,6 +1626,20 @@ export declare namespace ICellRange {
          * while leaving hidden columns in place.
          */
         ignoreHidden?: boolean | IRange.Axis;
+        /**
+         * Skip cells that only hold a spilled value - the members of a dynamic array's spill.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * A spilled value is not a cell's own content: it belongs to the formula at the spill's anchor,
+         * which is NOT skipped. Writing over a spilled cell loses nothing - the spill is blocked and its
+         * anchor reports `#SPILL!` - so this is the lens for "would writing here overwrite anything?".
+         * A blocked spill occupies only its anchor, so the cells it would have taken are never skipped.
+         *
+         * Honored by the aggregates: {@link ICellRange.isContentful} and {@link ICellRange.getCounts}.
+         */
+        ignoreSpilled?: boolean;
         /**
          * The features reads through this range resolve and report.
          *
@@ -1322,10 +1668,71 @@ export declare namespace ICellRange {
      * dropped because the range **is** the address — a second one would be a contradictory scope.
      */
     type GetItemsOptions<T> = Omit<T, 'address'>;
+    /**
+     * Options shared by every operation on a range.
+     *
+     * @remarks
+     * `autoSelect` and `autoFit` are *directives*: they name something to do once the operation
+     * completes rather than a change the operation makes. Both are resolved once, for the whole
+     * operation, and neither adds an undo entry of its own - a batch that sets values and fits
+     * the columns is one undo step that puts both back.
+     */
+    interface OperationOptions extends ITransaction.OperationOptions {
+        /**
+         * Select the affected range once the operation completes.
+         *
+         * @defaultValue `false` - the selection is left alone.
+         *
+         * @remarks
+         * The selection is applied once, after the whole operation - within a batch, the last
+         * operation to ask for one wins. It is applied only if the selection is still where it was
+         * when the operation began: a user who moved while it ran keeps where they went.
+         *
+         * Pass it for an edit the user made. A script that passes neither this nor
+         * {@link autoSelectRestore} never moves the user, whether it runs, is undone or is redone.
+         */
+        autoSelect?: boolean | ICellRange.SelectOptions;
+        /**
+         * Select the affected range when the operation is undone or redone.
+         *
+         * @defaultValue {@link autoSelect}
+         *
+         * @remarks
+         * An undo lands where the operation began - for most operations the range they affected, for
+         * an auto-fill the template it was dragged from - and a redo where it left the user. Within a
+         * batch an undo lands where the first operation to ask says, a redo where the last one does.
+         *
+         * For an edit made from where the user already is, pass this without {@link autoSelect}: a
+         * value typed into a cell of a selected block leaves the block selected, and undoing it
+         * selects the cell.
+         */
+        autoSelectRestore?: boolean | ICellRange.SelectOptions;
+        /**
+         * Fit the affected columns and rows to their content once the operation completes.
+         *
+         * @defaultValue the rows only, as Excel sizes them: a row with no custom height fits its
+         * content (growing or shrinking); a custom height and every column width are left alone.
+         *
+         * @remarks
+         * The fit runs once, as the last write of the operation, so it measures the finished
+         * content and its sizes belong to the same undo entry - one undo puts both the content
+         * and the sizes back.
+         *
+         * Pass `false` to leave every size alone. Pass `true` to fit as the UI does - rows and columns:
+    ```
+    {
+      skipCustomSize: true,
+      expandOnly: 'column', // columns only grow; rows fit exactly
+      minContent: true
+    }
+    ```
+         */
+        autoFit?: boolean | ICellRange.AutoFitOptions;
+    }
     /**
      * Options for adding an auto table to a range.
      */
-    interface AddAutoTableOptions extends ITransaction.OperationOptions {
+    interface AddAutoTableOptions extends ICellRange.OperationOptions {
         /**
          * Include sort options.
          */
@@ -1340,9 +1747,9 @@ export declare namespace ICellRange {
         replaceExisting?: boolean;
     }
     /**
-     * Options for `ICellRange.delete`.
+     * Options for `ICellRange.insert`.
      */
-    interface InsertOptions extends ITransaction.OperationOptions {
+    interface InsertOptions extends ICellRange.OperationOptions {
         /**
          * The direction in which to shift existing cells.
          *
@@ -1367,11 +1774,17 @@ export declare namespace ICellRange {
          * @defaultValue `false` (classic shift-cells)
          */
         span?: boolean;
+        /**
+         * Fit the inserted rows and columns to their content once the insert completes.
+         *
+         * @defaultValue `false` - inserted rows and columns take the default size.
+         */
+        autoFit?: boolean | ICellRange.AutoFitOptions;
     }
     /**
      * Options for `ICellRange.delete`.
      */
-    interface DeleteOptions extends ITransaction.OperationOptions {
+    interface DeleteOptions extends ICellRange.OperationOptions {
         /**
          * The direction in which to shift existing cells.
          *
@@ -1389,6 +1802,12 @@ export declare namespace ICellRange {
          * @defaultValue `false` (classic shift-cells)
          */
         span?: boolean;
+        /**
+         * Fit the rows and columns the remaining cells shift into once the delete completes.
+         *
+         * @defaultValue `false` - a delete moves rows and columns with the sizes they have.
+         */
+        autoFit?: boolean | ICellRange.AutoFitOptions;
     }
     /**
      * Options for configuring range coordinate reference types.
@@ -1474,8 +1893,9 @@ export declare namespace ICellRange {
          * @defaultValue false
          *
          * @remarks
-         * If `true` then tables and sheet boundaries will be ignored mimicking the behavior
-         * of 'Ctrl+Shift+*'.
+         * If `true`, the region is the contiguous block of content around the range (Excel's
+         * 'Ctrl+Shift+*' current region): tables are not treated as regions of their own, and a range
+         * with no content nearby returns itself rather than the entire sheet.
          */
         contentOnly?: boolean;
     }
@@ -1491,7 +1911,7 @@ export declare namespace ICellRange {
     /**
      * Options for {@link ICellRange.ISnapshot.copyTo}.
      */
-    interface CopyOptions extends ITransaction.OperationOptions, ReferenceableClipboard.CopyOptions {
+    interface CopyOptions extends ICellRange.OperationOptions, ReferenceableClipboard.CopyOptions {
         /**
          * When pasting from a smaller range to a larger range copy will repeat or 'wallpaper' the
          * source values.
@@ -1546,7 +1966,7 @@ export declare namespace ICellRange {
     /**
      * Options for {@link ICellRange.setValues}.
      */
-    interface SetValuesOptions extends ITransaction.OperationOptions {
+    interface SetValuesOptions extends ICellRange.OperationOptions {
         /**
          * By default setValue will attempt to parse text values into a native type.
          * This can be disabled or customized using the parseText flag.
@@ -1562,21 +1982,6 @@ export declare namespace ICellRange {
          * Both {@link SetValuesOptions} and {@link GetValuesOptions} allow for {@link IRange.Axis}s.
          */
         axis?: IRange.Axis;
-        /**
-         * Convenience method that calls autoFit after the setValues.
-         * @defaultValue `none` - No autofit.
-         *
-         * @remarks
-         * If set to `true` then autoFit will mimic the UI with the following options:
-    ```
-    {
-      skipCustomSize: true,
-      expandOnly: true,
-      minContent: true
-    }
-    ```
-         */
-        autoFit?: boolean | ICellRange.AutoFitOptions;
         /**
          * Skip the bounds check when setting values.
          *
@@ -1587,6 +1992,43 @@ export declare namespace ICellRange {
          * size requires processing the entire dataset.
          */
         skipBoundsCheck?: boolean;
+        /**
+         * Enter a single formula as an array formula (Excel's Ctrl+Shift+Enter) over the whole range.
+         *
+         * @defaultValue `false`
+         *
+         * @remarks
+         * The range is the block's extent and the formula sits at its top-left; the result is fitted
+         * to the extent rather than spilling from it - a dimension of 1 broadcasts, a longer one is
+         * clipped, a shorter one is padded with `#N/A` - and the block never resizes. Its cells can
+         * only be changed as a whole: overwriting, clearing, or inserting/deleting through part of a
+         * block is refused ("You can't change part of an array"); rewriting it through this option
+         * with the same range replaces it.
+         *
+         * Only meaningful for {@link ICellRange.setFormula} with one formula.
+         */
+        arrayFixed?: boolean;
+        /**
+         * Give each entered formula the number format of the first cell it reads that has one, or
+         * failing that the format its result carries, once it has been calculated.
+         *
+         * @defaultValue `false` - the cell keeps the format it has.
+         *
+         * @remarks
+         * What typing a formula into a cell does: `=A1*2` shows currency when `A1` does, `=NOW()`
+         * shows a date, `=DATE(2024,1,15)` a short date. A cell the formula reads ranks ahead of a
+         * function's format (`=A1+TODAY()` is currency when `A1` is); references are taken in the
+         * order written, a range stands for its top-left cell, and a reference a function only
+         * points at (`=ROW(A1)`, `=OFFSET(A1,0,0)`) does not count. The format becomes the cell's
+         * own, exactly as if set by hand, so it stays when the formula is replaced by a value and is
+         * part of the same undo entry as the formula. A format the cell already had wins.
+         *
+         * Only the formulas this operation enters are formatted, and only when they are first
+         * compiled and calculated - a later recalculation of the same cell changes nothing, and
+         * neither does formatting a cell it reads. Pair with {@link OperationOptions.autoFit} to also
+         * widen a column the formatted result no longer fits.
+         */
+        autoFormat?: boolean;
     }
     /**
      * Options for {@link ICellRange.getValues}.
@@ -1651,7 +2093,7 @@ export declare namespace ICellRange {
         /**
          * Fit to what **formula view** displays rather than to the rendered values.
          *
-         * @defaultValue the sheet view's {@link ISheetView.isShowFormulas}
+         * @defaultValue the sheet view's {@link IWorksheetView.isShowFormulas}
          *
          * @remarks
          * In formula view a cell with a formula shows `=` + its formula text, and every other cell
@@ -1729,7 +2171,7 @@ export declare namespace ICellRange {
     /**
      * Options for {@link ICellRange.autoFill}.
      */
-    interface AutoFillOptions extends ITransaction.OperationOptions {
+    interface AutoFillOptions extends ICellRange.OperationOptions {
         /**
          * Provide custom fillers.
          *
@@ -1743,11 +2185,21 @@ export declare namespace ICellRange {
          */
         fillerOptions?: IAutoFill.Options;
         /**
-         * If `true` then will only copy values and not formatting.
+         * Which part of the cells the fill carries — the same selector {@link CopyOptions.type} takes.
          *
-         * @defaultValue false (unless starting within a table)
+         * @defaultValue Everything: values, formulas and formatting.
+         *
+         * @remarks
+         * * {@link ICell.Content.Formats} is Excel's *Fill Formatting Only*: the template's formatting
+         *   (styles, number formats, merges, conditional formats and validations) is tiled into the
+         *   destination and the values already there are left alone. The `filler` is not consulted.
+         * * {@link ICell.Content.Values} is *Fill Without Formatting*: the series is written and the
+         *   destination keeps its own formatting — a date series lands as plain serials in a cell that
+         *   has no date format of its own.
+         * * On a shrinking destination the vacated cells lose only the selected part.
+         * * Any other member throws — a fill has no notion of copying just hyperlinks or comments.
          */
-        contentsOnly?: boolean;
+        type?: ICell.Content;
         /**
          * Compute the fill but commit nothing — the returned range is a projection of the result.
          *
@@ -1874,7 +2326,7 @@ export declare namespace ICellRange {
     /**
      * Options for {@link ICellRange.textToColumns}.
      */
-    interface TextToColumnsOptions extends ITransaction.OperationOptions {
+    interface TextToColumnsOptions extends ICellRange.OperationOptions {
         /**
          * The character used to split the text.
          *
@@ -1940,7 +2392,7 @@ export declare namespace ICellRange {
     /**
      * Options for {@link ICellRange.removeDuplicates}.
      */
-    interface RemoveDuplicatesOptions extends ITransaction.OperationOptions {
+    interface RemoveDuplicatesOptions extends ICellRange.OperationOptions {
         /**
          * Indicates if the range has a header row.
          *
@@ -2082,17 +2534,34 @@ export declare namespace ICellRange {
      * Represents an immutable reference to an `ICellRange`, capturing its content and metadata.
      * It may include complex objects such as tables, movables, images, listeners, or other items.
      *
-     * `ISnapshot` can be provided to `ICellRange.copyFrom``.
+     * `ISnapshot` can be provided to `ICellRange.copyFrom`.
      */
     interface ISnapshot<T = any, J = any> {
+        /**
+         * Does the asynchronous work a paste needs, before {@link copyTo} is called.
+         *
+         * @remarks
+         * `ICellRange.copyFrom` calls this first, outside any transaction, and then `copyTo` inside
+         * the paste's transaction. Anything that has to wait - loading a kind of content, decoding an
+         * image - is done here, so that `copyTo` can complete synchronously. A snapshot with nothing
+         * to wait for leaves this out, or returns `void`; the paste then runs to its commit in the
+         * caller's synchronous extent.
+         *
+         * @param destination The `ICellRange` the snapshot will be copied to, as the caller gave it.
+         */
+        prepare?(destination: ICellRange, options?: ICellRange.CopyOptions): Promise<void> | void;
         /**
          * Copies the snapshot to the specified range.
          *
+         * @remarks
+         * The copy is made inside the paste's transaction, so it completes synchronously; anything
+         * that has to wait belongs in {@link prepare}.
+         *
          * @param destination The destination `ICellRange` where the snapshot will be copied.
          *
-         * @returns A promise that resolves when the copy is complete, or `void` if no asynchronous operation is required.
+         * @returns The coordinates the copy covered, or `null` when it placed no cells.
          */
-        copyTo(destination: ICellRange, options?: ICellRange.CopyOptions): Promise<IRange.Coords | null> | IRange.Coords | null;
+        copyTo(destination: ICellRange, options?: ICellRange.CopyOptions): IRange.Coords | null;
         /**
          * Return the options used when creating.
          * @remarks
@@ -2170,12 +2639,12 @@ export declare namespace ICellRange {
      * over the content-style map). `Notes` joins when the backing is implemented; a feature that
      * silently reports nothing is worse than a missing one.
      *
-     * `String`/`Number`/`Boolean` are deliberately absent, even though they are real `ScalarType`
-     * values. This vocabulary is for things with a spatial identity — a fill, a formula, an
-     * occupied cell — and a scalar kind has none: it is read straight off the value, which is
+     * `String`/`Number`/`Boolean` are deliberately absent as separate members, even though they are
+     * real `ScalarType` values. "How many numbers" is a count read straight off the values, which is
      * exactly the one pass `IRangeStats.getTypedCounts()` already makes, richer (it composes with
-     * aggregates and frequencies for free, in the same call). `getCounts`/`getRegions`/
-     * `isContentful` were never the right vocabulary for "how many numbers" — `range.getStats()` is.
+     * aggregates and frequencies for free, in the same call) — `range.getStats()` is the vocabulary
+     * for that. *Where* the numbers are is a partition, and that is the one {@link Feature.Kind}
+     * answers: a typed row inside a block of text is a region of its own.
      *
      * `Error` stays, for a reason unrelated to the above: it has real spatial identity of its own
      * (the reconciled error view) and partitions like any stored feature — it was never in the same
@@ -2193,6 +2662,34 @@ export declare namespace ICellRange {
          * Occupancy — splits on blank/non-blank, Excel `CurrentRegion` semantics.
          */
         readonly Contentful: "contentful";
+        /**
+         * What a cell holds: a number, a date, text, text that would enter as a number, a boolean, an
+         * error or rich data. A formula cell is the kind of its result.
+         *
+         * @remarks
+         * Regions group by kind, so a column of numbers with one text cell in it is three regions. A
+         * date is a number under a date or time format (the cell's `getInteropType()` is `date`).
+         * Text that a typed entry would read as a number (`'123`, a number imported as text) is a kind
+         * of its own, apart from other text: it is Excel's number stored as text. The anchor's
+         * `getInteropType()` names the kind of every other region.
+         *
+         * Derived from the values on first read and cached until the sheet changes.
+         */
+        readonly Kind: "kind";
+        /**
+         * A cell's job in the model ({@link ICell.Role}): a typed `label` or `input`, a `link` to
+         * another sheet, a `reference` on this sheet, a `computed` cell or an `output`, from what the
+         * cell reads and who reads it. The anchor's {@link ICell.getRole} is the payload.
+         *
+         * @remarks
+         * The kind layer refined by the formulas: a column of typed numbers a model reads is one
+         * `input` region, the links beside it another. Crossed with a format (`['role', 'font']`) it is
+         * the census a color convention is judged by, and what the `styleRole` check reads.
+         *
+         * Derived on first read (the formulas parsed once) and cached until the sheet changes, so
+         * {@link ICellRange.getCounts} counts it only when asked for by name, like `anomalies`.
+         */
+        readonly Role: "role";
         /**
          * Direct date-category number format — `yyyy-mm-dd`, `mm/dd/yyyy`, and the like.
          *
@@ -2229,13 +2726,18 @@ export declare namespace ICellRange {
         /** Direct fill. */
         readonly Fill: "fill";
         /** Direct borders. */
-        readonly Border: "border";
+        readonly Borders: "borders";
         /** Direct number format. Region payloads carry the format string and its category. */
         readonly NumberFormat: "numberFormat";
         /** Direct alignment. */
         readonly Alignment: "alignment";
         /** Direct font. */
         readonly Font: "font";
+        /**
+         * Direct cell protection format (`ICellStyle.getProtection()`): always unlocked, show formulas.
+         * A cell with none of its own reads its named style's, then Normal's.
+         */
+        readonly Protection: "protection";
         /** Merged spans. */
         readonly Merge: "merge";
         /** Table membership. */
@@ -2244,14 +2746,55 @@ export declare namespace ICellRange {
         readonly AutoTable: "autoTable";
         /** Has a hyperlink. */
         readonly Hyperlink: "hyperlink";
+        /**
+         * Ignores one or more of Excel's error checks. Regions group by the set of checks ignored.
+         * @see {@link ICellRange.setErrorIgnored}
+         */
+        readonly IgnoredErrors: "ignoredErrors";
         /** Has comments. */
         readonly Comments: "comments";
-        /** Explicitly unlocked cells — *can I write here* is a precondition, not a detail. */
+        /**
+         * Unlocked cells — covered by an unlocked range, or with an always-unlocked style. *Can I write
+         * here* is a precondition, not a detail.
+         */
         readonly Unlock: "unlock";
         /** Cells under conditional-format rules. */
         readonly Conditionals: "conditionals";
         /** Cells under data-validation rules. */
         readonly DataValidations: "dataValidations";
+        /**
+         * Cells where an error check fires — what breaks the pattern around it. Regions group by the
+         * check and its evidence, so a filled row that breaks the same way is one region; the anchor
+         * cell's {@link ICell.getAnomalies} is the payload.
+         *
+         * @remarks
+         * Excel's background error checks, run over this vocabulary's own partitions rather than cell
+         * by cell: a formula region whose neighbors on both sides agree with each other and not with
+         * it (`formula`), a range that stops one number short (`formulaRange`), text that reads as a
+         * number (`numberStoredAsText`), a reference to an empty cell (`emptyCellReference`), a
+         * formula left unlocked (`unlockedFormula`). The first of these is one rule SheetXL runs on
+         * other layers too: a typed value in a run of formulas (`hardcodeInRun`), and an authored
+         * format that breaks the run around it (`styleBreak`); and a format part paired with the
+         * cell's role, a link left black where links are green (`styleRole`). Then SheetXL's own, read from what a
+         * formula says: a cell counted twice in one sum (`repeatedReference`), an aggregate of one cell
+         * or of typed numbers (`degenerateCall`), a sum holding its own subtotal (`sumIncludesSubtotal`),
+         * a total that also adds a cell outside its block (`misalignedReference`),
+         * a nearest-key lookup (`approximateMatch`), lookup arrays that do not line up (`lookupShape`),
+         * a reference outside the workbook (`externalReference`); and from labels: a link whose target
+         * row is labeled otherwise (`linkLabelMismatch`), a lookup key that is not the row's or
+         * column's label (`keyLabelMismatch`), a link with the other sign from its siblings
+         * (`signVsSiblings`). An ignored check ({@link ICellRange.setErrorIgnored}) does not fire.
+         *
+         * Regions list highest rank first ({@link ICell.Anomaly.rank}), unless an `axis` is asked for.
+         *
+         * The checks that read a formula need the calculation engine to have loaded its parser, and
+         * those that read its references need it to have compiled the formula; with the engine off
+         * they do not fire.
+         *
+         * Derived on first read and cached until the sheet changes, so {@link ICellRange.getCounts}
+         * counts it only when asked for by name; otherwise its key is absent, never `0`.
+         */
+        readonly Anomalies: "anomalies";
     };
     type Feature = typeof Feature[keyof typeof Feature];
     /**
@@ -2261,9 +2804,17 @@ export declare namespace ICellRange {
      * Total, not partial — every public {@link ICellRange.Feature} is present, absent features
      * as explicit zeros. A zero is a fact about the range; a missing key would be ambiguous.
      *
+     * The exceptions are `anomalies` and `role`: each is derived, not stored, so it is present only
+     * when it was requested by name. A count that was never taken is absent rather than a `0` that
+     * would read as "nothing fires here".
+     *
      * The brand is non-enumerable: `Object.keys`/`entries` yield exactly the feature keys.
      */
-    interface Counts extends Readonly<Record<ICellRange.Feature, number>> {
+    interface Counts extends Readonly<Record<Exclude<ICellRange.Feature, typeof Feature.Anomalies | typeof Feature.Role>, number>> {
+        /** Present only when `anomalies` was requested by name; see {@link Feature.Anomalies}. */
+        readonly anomalies?: number;
+        /** Present only when `role` was requested by name; see {@link Feature.Role}. */
+        readonly role?: number;
         /**
          * For runtime type checking.
          */
@@ -2296,6 +2847,29 @@ export declare namespace ICellRange {
          */
         containment?: 'intersects' | 'fullyContained';
     }
+    /**
+     * Options for {@link ICellRange.getAnomalies}.
+     */
+    interface GetAnomaliesOptions {
+        /**
+         * The checks to list first, in this order of priority; an unknown name throws.
+         *
+         * @defaultValue none — every region by rank
+         */
+        checks?: readonly ICell.ErrorCheck[];
+        /**
+         * At most this many regions.
+         *
+         * @defaultValue every region
+         */
+        limit?: number;
+        /**
+         * Regions to skip first, so `{ limit: 25, offset: 25 }` is the window after `{ limit: 25 }`.
+         *
+         * @defaultValue 0
+         */
+        offset?: number;
+    }
     interface ScrollIntoViewOptions extends globalThis.ScrollIntoViewOptions {
         /**
          * If provided then will only scroll in the provided axis.
@@ -2437,10 +3011,13 @@ export declare namespace ICellRange {
     }
     interface Event {
         /**
-         * The source of the event. This will be a readonly range.
+         * The range that was listened to, where it is now.
          *
          * @remarks
-         * This may change shape due to insert/delete/move of cells or sheets.
+         * After a `'address'` or `'restore'` event this is the range at its new address or extent: rows
+         * or columns inserted or deleted around it, or an undo that moved it back. The range
+         * `addListener` was called on keeps the address it was made with, so this is where to read
+         * the range from.
          */
         getSource<T = ICellRange | ICellRanges>(): T;
         /**
@@ -2450,10 +3027,6 @@ export declare namespace ICellRange {
          * This is different than the source range as that is the entire range area that was listened to.
          */
         getFrom(): ICellRanges;
-        /**
-         * Used for moves. Represents the new location of the data that has changed.
-         */
-        getTo?(): ICellRange;
         /**
          * Returns a list of updates that occurred during the event. This is only available for data change events and will be `null` for address or restore events.
          */
@@ -2464,7 +3037,10 @@ export declare namespace ICellRange {
          * * `'data'`: Data within the range has changed.
          *   The range's address and dimensions remain the same.
          * * `'address'`: The range's *address* or *dimensions* have changed. This
-         *   occurs due to row/column insertions, deletions, or move operations.
+         *   occurs due to row/column insertions, deletions, or move operations — and, for a
+         *   sheet-qualified range (one from {@link IWorkbook.getRange}, or a sheet's range naming
+         *   another sheet), when the sheet it names is renamed. A bare range on its own sheet has no
+         *   qualifier, so a rename is not a change to it.
          * * `'restore'`: The range has been restored to a different revision
          *   (undo/redo). The 'restore' trigger is not available for transactional listeners.
          */
@@ -2526,44 +3102,75 @@ export declare namespace ICellRange {
     interface WatchCallback {
         (values: IRange): void;
     }
+    /**
+     * Options for {@link ICellRange.addWatch}.
+     */
+    interface WatchOptions {
+        /**
+         * Evaluate each cell of the range as an array-entered formula whose extent is that one cell.
+         *
+         * @remarks
+         * This is how a conditional-format or data-validation formula is evaluated. Nothing
+         * implicitly intersects — a range reads as the whole array wherever it appears — and each
+         * cell keeps the top-left value of its own result, the way an array-entered formula fits its
+         * result to its extent. So `$J$1:$J$9="x"` answers `J1="x"` in every cell, while
+         * `SUM(IF($J$1:$J$9="x",1,0))>1` still sums the whole array. A relative range moves with the
+         * cell, so `$J1:$J9="x"` answers each row's own `J` cell.
+         *
+         * By default a cell whose result is an array spills, as a formula filled across the range
+         * would.
+         *
+         * @defaultValue `false`
+         */
+        arrayFirstCell?: boolean;
+    }
     /**
      * Options to control which events trigger a listener. By default, all
      * event types will trigger the listener. Setting any of these options to
      * `true` will *prevent* the listener from being called for that event type.
      */
     interface ListenerOptions {
-        /**
-         * The actual range can also change due to insert/removes or delete of a sheet.
-         * Setting absoluteCoords to `true` will ignore shifts in the range.
-         *
-         * @defaultValue false
-         */
-        ignoreShifts?: boolean;
         /**
          * If `true`, the listener will *not* be called when the range's
-         * address changes (due to row/column insert/delete, or moves)
+         * address changes (due to row/column insert/delete, moves, or a rename of
+         * the sheet a qualified range names)
          *
          * @defaultValue false
          */
         ignoreAddressChanges?: boolean;
         /**
-        * If `true`, the listener will be treated as *transactional*. This has
-        * a few implications:
-        *
-        * 1. **Synchronous Execution:** The listener will be called *synchronously*
-        *    as part of the same transaction that triggered the event.  Any
-        *    side-effects of the listener will be included in the transaction's
-        *    commit history.
-        * 2. **No 'restore' Events:** Transactional listeners will *never* receive
-        *    'restore' events. They are only concerned with changes within the
-        *    current transaction.
-        *
-        * If `false` (the default), the listener will be called *asynchronously*
-        * after the transaction is complete. The listener's side-effects will
-        * *not* be part of the transaction's commit history.
-        *
-        * @defaultValue false
-        */
+         * Whether the listener takes part in the operations that change its range.
+         *
+         * @defaultValue `true` when the listener is added through a range reached through the object a
+         * batch hands its callback ({@link IWorkbook.doBatch}, {@link IWorksheet.doBatch},
+         * {@link doBatch}), and `false` otherwise.
+         *
+         * @remarks
+         * A transactional listener (a participant):
+         * * added through a batch, is told as each operation of that batch is made, before the
+         *   operation returns, with what that operation changed. It is not told again when the batch
+         *   lands;
+         * * added any other way, is told once at the end of each operation, before it is committed;
+         * * writes into the same commit as the change it was told of, so one undo takes back both;
+         * * is never told of an undo or a redo, and is removed by undoing the operation that added it.
+         *   If its batch fails, it is told nothing more and goes with the batch.
+         *
+         * A non-transactional listener (an observer) is told once, after the operation has landed,
+         * with everything the operation changed in its range, and not at all if the operation is
+         * rolled back. What it writes is an operation of its own. It is told of an undo or a redo
+         * (`'restore'`), and it survives them.
+         *
+         * @example
+         * ```ts
+         * await workbook.doBatch(async (_commit, wb) => {
+         *   const total = wb.getSelectedWorksheet()!.getRange('B1');
+         *   const input = wb.getSelectedWorksheet()!.getRange('A1');
+         *   input.addListener(() => total.setValue((input.getValue() as number) * 2)); // a participant
+         *   input.setValue(21);
+         *   total.getValue(); // 42
+         * });
+         * ```
+         */
         transactional?: boolean;
         /**
          * If `true`, the listener will *not* be called when the data