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

package/types/src/calculation/grid/_CellValueRun.d.ts

@@ -0,0 +1,21 @@
+import { Scalar } from '@sheetxl/primitives';
+import { IListLike, IReadableList } from '../../collections';
+/**
+ * The run a result is stored as in a grid of CELL values: the engine's value grid, and the range
+ * an `evaluate()` call answers with.
+ *
+ * @remarks
+ * A cell holds a scalar: a number, text, a boolean, a blank, an error or rich data. Anything else
+ * an evaluation can produce, such as a function value (`=HSTACK(SUM,A1:A2)`, a `LAMBDA` left
+ * unconsumed), is calculation-private, and the cell's verdict on it is `#CALC!`, the one a
+ * top-level result gets (`FormulaBlock.finalizeValue`). Applying it where the run is MADE means
+ * every reader of the grid (the sheet, a spill, a saved file, the renderer) sees `#CALC!` without
+ * knowing what it stood for, and nothing private leaves the engine.
+ *
+ * A typed run never holds an object and is wrapped as it is; a repeating run is looked at once per
+ * period; a run made of other runs (a referenced column: its cells, then a blank stretch to the
+ * sheet's end) is looked at per leaf by the same rules; any other run is classified once, which is
+ * what storing it typed costs anyway.
+ */
+export declare const createCellValueRun: (values: IListLike<Scalar> | Scalar[]) => IReadableList<Scalar>;
+//# sourceMappingURL=_CellValueRun.d.ts.map

package/types/src/calculation/spatial/FormulaSpatialValue.d.ts

@@ -89,6 +89,11 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
      * Deliberately NOT "is a named body". Anything holding a formula at a synthetic anchor wants the
      * same treatment, and the shift code should not have to know what a name is.
      *
+     * A calculation pass never evaluates such a block: its anchor is no cell, so there is nothing
+     * to write an answer to, and whatever reads the body runs it inline at its own position. It is
+     * evaluated on demand only (`ICalcGrid.evaluateAt`), and `isVolatileAt` answers for it from the
+     * formula text alone, there being nothing a pass registered (`CalcGridBackend._isVolatileNow`).
+     *
      * Required at construction rather than defaulted: the block is immutable and re-minted on every
      * reference rewrite, so an unthreaded copy would silently revert to `false` on the first
      * `setReferenceAt` — which is exactly what a shift performs.
@@ -175,11 +180,20 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
     setBlankShared(blank: readonly IRange.Coords[] | null): void;
     /**
      * The pass refused to share the representative's answer for a reason the text hides — a
-     * position read, a draw, a computed reference (`CalcScope.perCellRead`). Those are facts of the
+     * position read the formula's variants cannot rule out, a draw, a computed reference
+     * (`CalcScope.perCellRead`, `CalcScope.positionRead`). Those are facts of the
      * formula, so the block keeps per-cell evaluation for good rather than paying one wasted
      * representative evaluation and a second plan iteration every pass.
      */
     blankRefused: boolean;
+    /**
+     * The representative's answer depends on the position and the block's grid is paged
+     * (`CalcGridBackend.ConstructorOptions.paged`): the blank region is not shared but evaluated
+     * inside the tiles the grid's owner asks for ({@link getDemandedBlank}), and holds nothing
+     * elsewhere. A fact of the formula like {@link blankRefused}, so it is kept; the block stays
+     * sparse and has no representative.
+     */
+    blankPaged: boolean;
     /**
      * The cycle whose representative could not stand for the region for a reason that may not
      * recur — a range result, a cycle role, a promise: the block is evaluated per cell for the rest
@@ -292,6 +306,11 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
      * ahead of this — so the region only ever answers for cells nothing was written to.
      */
     getBlankRegion(): FormulaSpatialValue.BlankRegion | null;
+    /**
+     * The cells of the last collection's blank region inside the tiles the grid's owner reads now
+     * (`CalcGridBackend.getDemanded`): what a paged block evaluates beyond its touched cells.
+     */
+    getDemandedBlank(): IRange.Coords[];
     /**
      * What a cell of `coords` that the grid does not store reads as: the blank region's shared
      * value when a region is shared and `coords` lie inside the block, `null` otherwise.
@@ -409,10 +428,14 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
     getReferencedSymbolIds(): string[];
     /** {@inheritDoc IFormulaBlock.hasTotals} */
     hasTotals(): boolean;
+    /** {@inheritDoc IFormulaBlock.hasVolatile} */
+    hasVolatile(): boolean;
     /** {@inheritDoc IFormulaBlock.isBlankCacheable} */
     isBlankCacheable(arrayMode?: boolean): boolean;
     /** {@inheritDoc IFormulaBlock.demandFirstCell} */
     demandFirstCell(): void;
+    /** {@inheritDoc IFormulaBlock.getPositionVariants} */
+    getPositionVariants(): IFormulaBlock[] | null;
     /** @inheritdoc IFormulaBlock.isReferenceOnly */
     isReferenceOnly(): boolean;
     /** {@inheritDoc IFormulaBlock.isEquals} */
@@ -439,10 +462,12 @@ export declare namespace FormulaSpatialValue {
     }
     /** See {@link FormulaSpatialValue.getBlankRegion}. */
     interface BlankRegion {
-        /** The representative's finalized scalar. */
+        /** The representative's finalized scalar; `undefined` for a paged region. */
         readonly value: Scalar | undefined;
         /** The blank rectangles, in the block's own grid coordinates. */
         readonly rects: readonly IRange.Coords[];
+        /** See {@link FormulaSpatialValue.blankPaged}. */
+        readonly paged?: boolean;
     }
 }
 //# sourceMappingURL=FormulaSpatialValue.d.ts.map

package/types/src/calculation/state/CalcScope.d.ts

@@ -43,14 +43,23 @@ export interface CalcScope {
     firstCell: boolean;
     /**
      * Set when the evaluation read something that is PER CELL rather than a property of its inputs
-     * — a random draw (`IFormulaContext.getRandom`), a position (`getRow`, `getColumn`, `getFormulaAt`,
-     * `getSheetIndex`, a reference's `getCoords`), or a reference it computed (a dynamic precedent)
-     * — so its answer cannot stand in for another cell's even when the two cells' inputs are
-     * identical. Cleared by whoever evaluates a cell as the representative of a block's blank
-     * region and read at its finalize (PLAN-WATCHES-BLANK-AWARE §4); a cell evaluated on its own
-     * behalf never reads it.
+     * — a random draw (`IFormulaContext.getRandom`), another cell's formula or sheet
+     * (`getFormulaAt`, `getSheetIndex`), or a reference it computed (a dynamic precedent) — so its
+     * answer cannot stand in for another cell's even when the two cells' inputs are identical.
+     * Cleared by whoever evaluates a cell as the representative of a block's blank region and read
+     * at its finalize (PLAN-WATCHES-BLANK-AWARE §4); a cell evaluated on its own behalf never
+     * reads it.
      */
     perCellRead: boolean;
+    /**
+     * Set when the evaluation read its own POSITION — `getRow`, `getColumn`, its own address, a
+     * reference's `getCoords`. Per cell like {@link perCellRead}, but a position is the one per-cell
+     * input whose effect the representative can rule out: when every position read sits under a
+     * boolean test the result does not depend on (`AND(ISODD(ROW()),$A1<>"")` over a blank `A`),
+     * the answer is still shared (`IFormulaBlock.getPositionVariants`). Cleared and read alongside
+     * {@link perCellRead}.
+     */
+    positionRead: boolean;
     /**
      * How many draws (`IFormulaContext.getRandom`) this evaluation has taken, from `0`.
      *

package/types/src/calculation/state/CalcState.d.ts

@@ -33,6 +33,16 @@ export declare const CalcState: {
      * `demandValue` in place of an `evaluateAt`.
      */
     readonly Circular: number;
+    /**
+     * The node's last evaluation found it volatile: the formula names a volatile function
+     * (`IFormulaContext.markVolatile`, which the compiled `hasVolatile` spends), it read cells its
+     * text does not name (a dynamic precedent of kind `Reference`: `OFFSET`, `INDIRECT`), or it is
+     * a member of an iterated cycle. Cleared when an evaluation of the node starts, so it answers
+     * for the last one; persists across passes that skip the node. What `isVolatileAt` reports —
+     * the executor's volatile SET is the pass's own worklist, rebuilt every pass, and is not read
+     * for the answer.
+     */
+    readonly Volatile: number;
     /**
      * A `Waiting` node — or a finished member of a cycle that is still open — the evaluation in
      * progress has read under iterative calculation: it is in

package/types/src/calculation/state/CalculationContext.d.ts

@@ -37,8 +37,8 @@ export declare class CalculationContext implements IFormulaContext {
      */
     protected _dynamicRead: ReadHook | null;
     /**
-     * Marks the evaluation in progress as having read something PER CELL — a position — so its
-     * answer cannot stand in for another cell's (`CalcScope.perCellRead`). One closure for the
+     * Marks the evaluation in progress as having read its position, so its answer stands in for
+     * another cell's only where the position cannot matter (`CalcScope.positionRead`). One closure for the
      * context's lifetime: every reference it builds is handed this for its `getCoords`, and the
      * context's own position accessors call it directly.
      */

package/types/src/calculation/state/IContextContainer.d.ts

@@ -56,6 +56,11 @@ export interface IContextContainer {
     getSheetSpanIds?: (scopeId: string) => string[] | null;
     /** Every sheet's grid id in tab order, hidden sheets included. */
     getSheetIds?: () => readonly string[];
+    /**
+     * Whether a sheet in the tab order has no grid: a chart, macro or dialog sheet. Such a sheet counts
+     * in a span's members and gives no values; it cannot be a span's endpoint.
+     */
+    isGridless?: (sheetId: string) => boolean;
     getScope(): CalcScope;
     getRuntime(): IRuntime;
     /**
@@ -162,6 +167,13 @@ export interface IContextContainer {
      * objects, copy-on-write per request.
      */
     setGridMaps(gridId: string, maps: object): void;
+    /**
+     * The clone key the requests of the batch being applied share (`ISpatialMap.clone`'s), while a
+     * held batch or a collecting batch of grids applies; `null` otherwise. The batch is one engine
+     * operation, so a map one of its requests cloned is the one the next writes into, rather than a
+     * copy per request.
+     */
+    getHeldCloneKey?(): string | null;
     /**
      * The model has restored itself to `commitId` (an undo, a redo): restore the engine's history
      * to it, once, and answer the regions of `gridId` that changed between the two snapshots. A

package/types/src/calculation/toolkit/FormulaLiteralReader.d.ts

@@ -0,0 +1,4 @@
+import { Scalar } from '@sheetxl/primitives';
+/** {@link parseFormulaLiteral}, with the toolkit loaded. */
+export declare function readFormulaLiteral(text: string): Scalar | undefined;
+//# sourceMappingURL=FormulaLiteralReader.d.ts.map

package/types/src/calculation/toolkit/FormulaTextParser.d.ts

@@ -0,0 +1,10 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICalculation } from '../ICalculation';
+import { FormulaText } from '../FormulaText';
+/** {@link FormulaText.parse}, with the toolkit loaded. */
+export declare function parse(text: string, options?: FormulaText.ParseOptions): ICalculation.FormulaNode | null;
+/** {@link FormulaText.transform}, with the toolkit loaded. */
+export declare function transform(root: ICalculation.FormulaNode, transform: ICalculation.FormulaTransform): ICalculation.FormulaNode;
+/** {@link FormulaText.imager}, with the toolkit loaded. */
+export declare function imager(root: ICalculation.FormulaNode, options?: Omit<FormulaText.ImageOptions, 'at'>): (at?: IRange.CellCoords) => string;
+//# sourceMappingURL=FormulaTextParser.d.ts.map

package/types/src/calculation/toolkit/FunctionDeclarationTable.d.ts

@@ -0,0 +1,4 @@
+import { FunctionDeclarations } from '../functions/FunctionDeclarations';
+/** A built-in function's declaration, or `null` when no built-in has that name. Not case sensitive. */
+export declare function getFunctionDeclaration(name: string): FunctionDeclarations.Declared | null;
+//# sourceMappingURL=FunctionDeclarationTable.d.ts.map

package/types/src/calculation/toolkit/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The formula toolkit's code: the parser, the printer, the literal reader and the built-in
+ * declarations, behind `FormulaText`, `parseFormulaLiteral` and `FunctionDeclarations`.
+ *
+ * @remarks
+ * Loaded by `FormulaText.load()` and by a calculation's start, never carried from import
+ * (DESIGN-CALC-SERVICE §13.25). Only `_FormulaToolkit` imports it.
+ */
+export { parse, transform, imager } from './FormulaTextParser';
+export { readFormulaLiteral } from './FormulaLiteralReader';
+export { getFunctionDeclaration } from './FunctionDeclarationTable';
+//# sourceMappingURL=index.d.ts.map

package/types/src/cell/ICell.d.ts

@@ -1,7 +1,7 @@
-import { Scalar, ScalarType, InteropScalarType, InteropScalar, IRange } from '@sheetxl/primitives';
+import { Scalar, ScalarType, InteropScalarType, InteropScalar, IRange, IRichData } from '@sheetxl/primitives';
 import { Size, Rectangle, Bounds } from '@sheetxl/utils';
 import { ITypes } from '../type';
-import { ITextFrame, TextRotation, TextStacked } from '../text';
+import { ITextFrame, TextRotation, TextStacked, IRichText } from '../text';
 import { NumberFormat } from '../numFmt';
 import { ITable } from '../table';
 import { IDataValidation } from '../dataValidation';
@@ -11,7 +11,7 @@ import { IComment } from '../comment';
 import { ICellStyle } from '../style';
 import { ICellRanges, ICellRange } from '../cellRange';
 import { ICalculation } from '../calculation';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { ICellProtection } from './ICellProtection';
 /**
  * A single unit of data and meta data within an `ICellRange`, located at a specific row and column.
@@ -113,6 +113,35 @@ export interface ICell {
      * Resolves `null` if the cell has no dependents.
      */
     getDependents(): Promise<ICellRanges | null>;
+    /**
+     * Returns whether the cell ignores one of Excel's error checks.
+     *
+     * @param check The check.
+     * @see {@link ICellRange.setErrorIgnored}
+     */
+    isErrorIgnored(check: ICell.ErrorCheck): boolean;
+    /**
+     * Returns the error checks that fire at the cell, each with its evidence.
+     *
+     * @remarks
+     * The payload of the `anomalies` feature at this cell ({@link ICellRange.Feature}): a cell of a
+     * `getRegions('anomalies')` region reads its region's findings here. A check the cell ignores
+     * ({@link isErrorIgnored}) does not fire. Empty when nothing fires.
+     *
+     * Derived on first read and cached until the sheet changes; it costs nothing before that.
+     */
+    getAnomalies(): readonly ICell.Anomaly[];
+    /**
+     * Returns the cell's role: its job in the model, from what it reads and who reads it.
+     *
+     * @remarks
+     * The payload of the `role` feature at this cell ({@link ICellRange.Feature.Role}); see
+     * {@link ICell.Role} for the six roles. `null` for an empty cell, and for a formula before the
+     * calculation engine has loaded its parser.
+     *
+     * Derived on first read and cached until the sheet changes; it costs nothing before that.
+     */
+    getRole(): ICell.Role | null;
     /**
      * Returns the hyperlink assigned to the cell.
      *
@@ -120,12 +149,21 @@ export interface ICell {
      * Returns `null` if no hyperlink is set.
      */
     getHyperlink(): IHyperlink | null;
+    /**
+     * The cell's text as formatted runs, or `null` when the text has one font throughout.
+     *
+     * @remarks
+     * Each run's font is the whole font the run shows in: the cell's font with what the run sets
+     * over it. The value itself (`getValue()`) is a `RichText`, whose runs record only what they
+     * set. Set with {@link ICellRange.setRichText}.
+     */
+    getRichText(): IRichText.JSON | null;
     /**
      * Returns the comment on the cell, or `null` if there is none.
      *
      * @remarks
      * One per cell — the thread's root, with its replies, or a note. The sheet's
-     * {@link ISheet.getComments} is where one is added.
+     * {@link IWorksheet.getComments} is where one is added.
      */
     getComments(): IComment | null;
     /**
@@ -178,6 +216,11 @@ export interface ICell {
      * Returns the cell's value as a formatted string, applying any number formatting.
      */
     getText(options?: ICell.GetTextOptions): string;
+    /**
+     * @deprecated Use {@link getText}.
+     * @hidden
+     */
+    getFormattedValue(): string;
     /**
      * Returns the cell's value as a string with additional number format details.
      *
@@ -386,6 +429,11 @@ export interface ICell {
      * @param r1c1 If unspecified defaults to the environment's default format.
      */
     getAddress(r1c1?: boolean): string;
+    /**
+     * @deprecated Use {@link getAddress}.
+     * @hidden
+     */
+    getA1(): string;
     /**
      * Selects the current cell.
      * @returns An async boolean indicating the cell was selected.
@@ -394,7 +442,7 @@ export interface ICell {
     /**
      * Returns the Sheet.
      */
-    getSheet(): ISheet;
+    getWorksheet(): IWorksheet;
     /**
      * For runtime type checking.
      */
@@ -522,7 +570,7 @@ export declare namespace ICell {
         comments?: IComment.Update;
     }
     /**
-     * Options for {@link ICell.createCell} and {@link ISheet.createCell}.
+     * Options for {@link ICell.createCell} and {@link IWorksheet.createCell}.
      */
     interface CreateCellOptions {
         /**
@@ -678,7 +726,11 @@ export declare namespace ICell {
      */
     interface JSONTypedValue {
         t: JSONScalarType;
-        v: number;
+        /**
+         * The number, string id, error code or boolean flag; for `'r'`, the rich data's own JSON
+         * (`IRichData.JSON`), which its registered kind reads back.
+         */
+        v: number | IRichData.JSON;
     }
     /**
      * Reexports the `IRange.CellCoords` type for use in cell coordinates.
@@ -759,5 +811,202 @@ export declare namespace ICell {
         readonly DataValidations: "dataValidations";
     };
     type Content = typeof Content[keyof typeof Content];
+    /**
+     * A cell's job in the model, read from two facts: what the cell reads and who reads it.
+     *
+     * @remarks
+     * A typed cell is a `label` when nothing reads it and an `input` when something does. A formula
+     * is a `link` when it is one cell of another sheet (negated or scaled at most, or a reference
+     * built with `INDIRECT`), a `reference` when it is one cell of this sheet (negated at most),
+     * else `computed` where something reads it and `output` where nothing does. "Who reads it" is
+     * the sheet's own formulas, so a cell only another sheet reads is a `label` or an `output`.
+     *
+     * A finance model's color convention (inputs blue, links green, calculations black) is a
+     * statement about this layer, which is what the `styleRole` check reads
+     * ({@link ICell.ErrorCheck}).
+     */
+    const Role: {
+        /** A typed value nothing on the sheet reads. */
+        readonly Label: "label";
+        /** A typed value a formula reads. */
+        readonly Input: "input";
+        /** One cell of another sheet. */
+        readonly Link: "link";
+        /** One cell of this sheet. */
+        readonly Reference: "reference";
+        /** An expression something reads. */
+        readonly Computed: "computed";
+        /** An expression nothing on the sheet reads. */
+        readonly Output: "output";
+    };
+    type Role = typeof Role[keyof typeof Role];
+    /**
+     * One of Excel's background error checks (**Formulas > Error Checking**), by the name the file
+     * stores it under, or one of SheetXL's own. A cell can be told to ignore a check
+     * ({@link ICellRange.setErrorIgnored}); Excel then draws no error indicator on it for that rule.
+     *
+     * @remarks
+     * The checks SheetXL runs fire through {@link ICell.getAnomalies} and the `anomalies` feature;
+     * an ignored check does not fire. Ignores follow their cells through inserts and deletes, are
+     * never copied, and leave a cell that is written or cleared, as in Excel.
+     */
+    const ErrorCheck: {
+        /** A formula that evaluates to an error value. */
+        readonly EvaluatesToError: "evalError";
+        /** A year written as two digits in text. */
+        readonly TextDate: "twoDigitTextYear";
+        /** A number stored as text. */
+        readonly NumberAsText: "numberStoredAsText";
+        /** A formula inconsistent with the formulas around it. */
+        readonly InconsistentFormula: "formula";
+        /** A formula that omits cells adjacent to the range it refers to. */
+        readonly OmittedCells: "formulaRange";
+        /** A formula in an unlocked cell. */
+        readonly UnlockedFormula: "unlockedFormula";
+        /** A formula that refers to empty cells. */
+        readonly EmptyCellReference: "emptyCellReference";
+        /** A value that fails the cell's list data validation. */
+        readonly ListDataValidation: "listDataValidation";
+        /** A formula inconsistent with its table's calculated column. */
+        readonly InconsistentListFormula: "calculatedColumn";
+        /**
+         * A typed value in a run of formulas: the cells on both sides of it, along a row or a column,
+         * are formulas. SheetXL's own; not written to an xlsx file's ignored errors.
+         */
+        readonly HardcodeInRun: "hardcodeInRun";
+        /**
+         * An authored format (font, fill, number format, alignment) that breaks the run around it:
+         * the cells on both sides carry one format, and this cell another. SheetXL's own; not
+         * written to an xlsx file's ignored errors.
+         */
+        readonly StyleBreak: "styleBreak";
+        /**
+         * A format part paired with the cell's role: a link to another sheet, a reference on this
+         * sheet or a calculation whose font color is other than most of its role on the sheet have,
+         * and is one the workbook writes some role in. SheetXL's own; not written to an xlsx file's
+         * ignored errors.
+         */
+        readonly StyleRole: "styleRole";
+        /** A cell or range counted twice in one sum. */
+        readonly RepeatedReference: "repeatedReference";
+        /** An aggregate over one cell, or over typed numbers only. */
+        readonly DegenerateCall: "degenerateCall";
+        /** A sum whose range holds a subtotal of its own cells, or a ratio. */
+        readonly SumIncludesSubtotal: "sumIncludesSubtotal";
+        /**
+         * A total, or the first line of a block, that sums its block and also adds a cell outside it:
+         * another block's line item, another block's total, or an absolute reference.
+         */
+        readonly MisalignedReference: "misalignedReference";
+        /** A lookup that matches the nearest key rather than the key. */
+        readonly ApproximateMatch: "approximateMatch";
+        /** A lookup whose result array and lookup vector do not line up. */
+        readonly LookupShape: "lookupShape";
+        /** A reference to another workbook, a deleted reference, or a function a converter could not name. */
+        readonly ExternalReference: "externalReference";
+        /** A link to another sheet whose target row is labeled other than its own row. */
+        readonly LinkLabelMismatch: "linkLabelMismatch";
+        /** A lookup keyed by a typed string that labels neither the formula's row nor its column. */
+        readonly KeyLabelMismatch: "keyLabelMismatch";
+        /** A link read with the other sign from the sheet's other links into the same row. */
+        readonly SignVsSiblings: "signVsSiblings";
+    };
+    type ErrorCheck = typeof ErrorCheck[keyof typeof ErrorCheck];
+    /**
+     * One error check firing at a cell: the check, and the facts that make it fire.
+     *
+     * @remarks
+     * Evidence, never a verdict: what the cell breaks and where, so the reader can judge it. A
+     * pattern break is sometimes the right cell in a wrong run. There is no confidence.
+     *
+     * The evidence a cell's finding carries is the same for every cell of a filled run that breaks
+     * the same way, so a row of breaks is one region of the `anomalies` feature. Positions are
+     * therefore relative to the cell, in R1C1 (`R[-1]C` is the cell above).
+     *
+     * | check | evidence |
+     * | --- | --- |
+     * | `formula` | `axis` (`'row'` / `'column'`) the run lies along; `expected`, the R1C1 formula both neighbors share; `thickness`, the cells across the break (Excel flags only `1`); `flanks`, how far the run goes on each side; `corroborated` |
+     * | `formulaRange` | `reference`, the range the formula reads; `omitted`, the typed number just past its end |
+     * | `numberStoredAsText` | none — the cell's own text is the fact |
+     * | `emptyCellReference` | `reference`, the reference that reads an empty cell |
+     * | `unlockedFormula` | none |
+     * | `hardcodeInRun` | `axis`, `expected` (`'formula'`), `thickness`, `flanks`, `corroborated` |
+     * | `styleBreak` | `layer` (`'font'`, `'fill'`, `'numberFormat'`, `'alignment'`); `axis`; `expected`, the format both sides share; `actual`, this cell's; `thickness`, `flanks`, `corroborated` |
+     * | `styleRole` | `part` (`'fontColor'`); `role` (`'link'`, `'reference'`, `'computed'`, `'input'`); `expected`, the color most cells of that role on the sheet have; `actual`, this cell's; `majority`, how many cells of the role have `expected`; `of`, how many cells the role has on the sheet |
+     * | `repeatedReference` | `reference`, the reference counted again; `overlaps`, the one it falls inside when the two are not the same |
+     * | `degenerateCall` | `function`; `reference`, the one cell aggregated, or `literals`, the typed numbers |
+     * | `sumIncludesSubtotal` | `reference`, the range summed; `subtotal` or `ratio`, the cell inside it that is one |
+     * | `misalignedReference` | `term`, the reference outside the block; `block`, the rows (or columns) of the cell's own block that the formula sums; `landsAt`, the block the term lands in, when it lands in one; `targetRole`, what the term reads: `'lineItem'` (a line of another block), `'closingRow'` (another block's last line, a subtotal), `'outsideBlocks'` (no block) or `'absolute'` (a fixed reference, a rate or an assumption) |
+     * | `approximateMatch` | `function`; `matchType`, `'1'`, `'-1'`, `'TRUE'` or `'omitted'` |
+     * | `lookupShape` | `array`, the range the result is read from; `vector`, the range the key is found in |
+     * | `externalReference` | `kind` (`'workbook'`, `'deleted'`, `'udf'`); `reference`, or `function` for a `'udf'` |
+     * | `linkLabelMismatch` | `label` / `labelAt`, the cell's row label; `target` / `targetAt`, the label of the row it links to |
+     * | `keyLabelMismatch` | `function`; `key`; `rowLabel` / `rowLabelAt` and `columnLabel` / `columnLabelAt`, where found |
+     * | `signVsSiblings` | `reference`; `sign` (`'negative'` / `'positive'`); `siblings`, how many links into that row read the other sign; `siblingAt`, one of them |
+     *
+     * **Runs.** `formula`, `hardcodeInRun` and `styleBreak` are one rule over different layers of
+     * the sheet: a region thin against the run it sits in. The cells on both sides agree with each
+     * other and not with it, and the run goes on at least two cells each side and at least as far as
+     * the region is thick (`flanks`), so a block as large as its surroundings is a section, not a
+     * break. A single cell between two that agree is kept too, with `flanks: 1`. A format compares
+     * as authored on the cell: none (`'normal'`), one equal to the Normal style's
+     * (`'authored-normal'`), or the authored properties as JSON.
+     *
+     * `corroborated` lists the other layers that change at both of the region's edges too: formula
+     * shape (`'formulaShape'`), formula or typed value (`'hasFormula'`), the value's kind (`'kind'`),
+     * and the format layers. A lone change, corroborated by nothing, is the stronger candidate; a
+     * row that differs on many layers (a total under its line items) is usually structure.
+     *
+     * **Blocks.** `misalignedReference` reads a formula against the block it closes or opens: the
+     * lines (rows, or columns for a row-wise total) holding content in the formula's own columns,
+     * between blank lines that span them. It fires on a sum that adds the block's own cells and
+     * also, with the same sign, a cell off the block's lines: `=SUM(K51:K53)+J46` in K54. A term on
+     * the block's lines in another column (a prior period) and a term taken away are not reported,
+     * nor is a sum of other blocks' totals that reads nothing of its own block. A running total that
+     * adds the previous block's total is reported as `closingRow`, ranked low.
+     *
+     * **Roles.** A cell's role ({@link ICell.Role}, the `role` feature) is its job, from what it
+     * reads and who reads it. `styleRole` pairs a format part with the role, for links, references, computed cells and inputs
+     * beside a label: the color most cells of a role have on the
+     * sheet is the role's, and a link, reference or computed cell in another color fires when that
+     * color is one the workbook writes some role in, on any sheet (a link left black where links
+     * are green and calculations black), never when it is decorative (white, red, a section's text
+     * color). A label never fires, and an input fires only beside a label: a typed number inside a
+     * data block reads like the data around it. Colors are the authored font color as `#RRGGBB`; a
+     * cell with none authored has the Normal style's. `majority` and `of` are evidence, not a
+     * gate: a convention held by 3 of 5 cells is reported as such.
+     *
+     * **Rank** says which finding to read first. It is not a confidence. For a run finding it is
+     * `weight × (1 / thickness) × (flanks / max(2, thickness)) × (1 − corroboration)`, where
+     * `weight` is the layer's and `corroboration` is the weight of the corroborating layers over the
+     * weight of every layer that could have corroborated. The layer weights are formula shape `1`,
+     * kind `0.6`, number format `0.5`, formula or typed value `0.4`, font `0.3`, fill `0.1`,
+     * alignment `0.05`. Every other check ranks at a fixed weight: `repeatedReference` and
+     * `lookupShape` `1`, `approximateMatch` and `externalReference` `0.9`, `formulaRange` and
+     * `degenerateCall` `0.8`, `emptyCellReference` and `sumIncludesSubtotal` `0.6`,
+     * `keyLabelMismatch` and `linkLabelMismatch` `0.4`, `unlockedFormula` and `signVsSiblings` `0.1`,
+     * `numberStoredAsText` `0.05`. A `styleRole` finding ranks at the role's weight (`link` `0.6`,
+     * `reference` `0.4`, `input` `0.3`, `computed` `0.2`) times `majority / of`. A
+     * `misalignedReference` finding ranks at `0.8` times its target's share: `lineItem` `1`,
+     * `outsideBlocks` `0.5`, `closingRow` and `absolute` `0.25`.
+     *
+     * A run or `styleRole` finding's rank is then divided by the number of times the same finding
+     * (the same check and evidence) occurs in the workbook: a finding repeated across a model is the
+     * author's style, and the one that occurs once is the exception to read first. So a finding's
+     * rank can change when another sheet changes. The weights are measured on the SpreadsheetBench
+     * v2 Debugging goldens and move as other measurements arrive. Regions of the `anomalies` feature
+     * list highest rank first, and so do a cell's findings, in check order within an equal rank.
+     *
+     * A label's position is absolute (`R12C3`), since it stays put whichever cell of a region reads
+     * it; its text is the one read at the region's first cell.
+     */
+    interface Anomaly {
+        /** The check that fires. */
+        readonly check: ErrorCheck;
+        /** The facts it fires on. */
+        readonly evidence: Readonly<Record<string, string | number | readonly string[]>>;
+        /** Which finding to read first, highest first; see the remarks. */
+        readonly rank: number;
+    }
 }
 //# sourceMappingURL=ICell.d.ts.map

package/types/src/cell/ICellHeader.d.ts

@@ -62,6 +62,11 @@ export interface ICellHeader {
      * @see `IOutline`
      */
     getOutlineLevel(): number;
+    /**
+     * Whether the column's width was last set by fitting it to its content. Setting the width any
+     * other way clears it, as in Excel. Always `false` for a row.
+     */
+    isBestFit(): boolean;
     /**
      * For runtime introspection.
      */
@@ -152,13 +157,9 @@ export declare namespace ICellHeader {
          */
         cl?: boolean;
         /**
-         * Style id
-         *
-         * @remarks
-         * * The style id is only available for export for backward compatible `ISheet.ToJSONOptions.includeHeaderStyles` is set.
-         * * This flag is ignored during loading.
+         * Best fit. The column's width was last set by fitting it to its content.
          */
-        s?: number;
+        bf?: boolean;
     }
 }
 //# sourceMappingURL=ICellHeader.d.ts.map

package/types/src/cell/ICellProtection.d.ts

@@ -32,7 +32,7 @@ export interface ICellProtection {
      *
      * @remarks
      * * An exception, like {@link isAlwaysUnlocked}: a formula shows when the sheet
-     *   (`ISheetProtection.isShowFormulasAllowed`) or the cell allows it, so this only matters while
+     *   (`IWorksheetProtection.isShowFormulasAllowed`) or the cell allows it, so this only matters while
      *   the sheet hides them.
      * * A hidden formula reads as no formula ({@link ICell.getFormula} is `null`), but it still
      *   calculates and is still saved with the workbook. It is a view rule, not secrecy.

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

@@ -103,6 +103,11 @@ export interface ICellHeaderRange {
      * {@inheritDoc ICellRange.getAddress}
      */
     getAddress(r1c1?: boolean): string;
+    /**
+     * @deprecated Use {@link getAddress}.
+     * @hidden
+     */
+    getA1(): string;
     /**
      * Returns the address as a string.
      */
@@ -160,14 +165,6 @@ export declare namespace ICellHeaderRange {
          * @defaultValue false
         */
         includeSizes?: boolean;
-        /**
-         * Include headers that have custom styling.
-         *
-         * @defaultValue false
-         *
-         * @deprecated We are removing styles from headers (but will need in sheet for backward compatibility with Excel)
-         */
-        includeStyles?: boolean;
         /**
          * When scanning skip cells that are hidden via headers.
          *
@@ -271,7 +268,7 @@ export declare namespace ICellHeaderRange {
         /**
          * Called when the item is copied to a new header range.
          */
-        copyTo(range: ICellHeaderRange, options?: ICellHeaderRange.CopyOptions): Promise<RunCoords> | RunCoords;
+        copyTo(range: ICellHeaderRange, options?: ICellHeaderRange.CopyOptions): RunCoords;
         /**
          * The RunCoords that bounds the current item.
          */

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

@@ -74,6 +74,11 @@ export interface ICellHeaderRanges {
      * {@inheritDoc ICellHeaderRange.getAddress}
      */
     getAddress(r1c1?: boolean): string;
+    /**
+     * @deprecated Use {@link getAddress}.
+     * @hidden
+     */
+    getA1(): string;
     /**
      * {@inheritDoc ICellHeaderRange.toString}
      */