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

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

@@ -139,36 +139,8 @@ export interface IContextContainer {
      * Returns the grid for a given gridId. This is used to get other grids when calculating.
      */
     getGrid(gridId: string): CalcGridBackend | null;
-    /**
-     * Runs a request against the engine's state, landing what it writes under the snapshot it
-     * names (DESIGN-CALC-SERVICE §13.13: the engine keeps its own history keyed by the model's
-     * ids).
-     *
-     * @param landingId The engine commit the request lands in: the model's commit for a root
-     * transaction, its savepoint for a nested one, or `undefined` for a request naming no snapshot
-     * (a caller with no model), which is applied as it is.
-     * @param action The request; its writes land together.
-     */
     landRequest<R>(landingId: string | undefined, action: () => R): R;
-    /**
-     * Sends a grid request through the service's channel (DESIGN-CALC-SERVICE §4, §7.2).
-     *
-     * @param gridId The grid the request is for.
-     * @param landingId The engine commit a request applied now lands in - see {@link landRequest}.
-     * @param request The request, as data.
-     *
-     * @remarks
-     * On a `Running` engine the request is applied at once and lands under `landingId`. While the
-     * engine is `Starting` it is held, in send order, and applied once the engine is up, behind the
-     * seeds; one whose snapshot the model has undone by then is dropped. On an `Off` engine nothing
-     * is recorded and the request resolves with nothing: a later start is seeded from the model.
-     */
     sendRequest(gridId: string, landingId: string | undefined, request: CalcRequest): Promise<ICalcGrid.Results>;
-    /**
-     * What images a grid's records for the model (DESIGN-CALC-SERVICE §8): the model's symbol
-     * map, the grid as home scope, its bounds, the reader's locale. The facade's, read where a
-     * response crosses to the model.
-     */
     getImager(gridId: string): FormulaImager;
     /**
      * Records the regions a request touched on the commit it is landing in, so a revert knows what
@@ -348,38 +320,7 @@ export interface IContextContainer {
      * recover which is which from the coords.
      */
     addDynamicPrecedent(calcNode: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind): void;
-    /**
-     * The results of a what-if data table, for the `TABLE` node being evaluated (the scope's node):
-     * its affected cells re-evaluated under each substitution, nothing written
-     * (DESIGN-DATA-TABLES §4.3). Only during a pass.
-     */
     evaluateWhatIf(table: WhatIfTable): Scalar[][];
-    /**
-     * Queues an action to run at the engine's next safe point, and schedules that point.
-     *
-     * @remarks
-     * Safe means two things, and they are why this exists rather than calling inline: the engine can
-     * actually do the work (the compiler is loaded, grids are populated), and the synchronous work
-     * that queued the action has finished — a `setInputs` run re-entrantly during an active commit is
-     * what produced the intermittent `OutOfOrderError` in the value builder.
-     *
-     * No guard is required. Queuing schedules its own drain, so an action queued here always runs:
-     * while `Starting` it is held for `start()`'s drain, inside a drain it joins the pass already
-     * running, and on a settled engine a microtask drain is posted for it.
-     *
-     * It did require one, and was called `whenStarting` for that reason — the queue was pumped only
-     * as a side effect of `start`/`ready`/`calculate`, so an action queued on a settled engine waited
-     * for a calculation that might never come and was dropped rather than delayed. Callers written
-     * against that rule (guarding on {@link isLoading} or a `Starting` status) remain correct; the
-     * guard is now redundant, not wrong.
-     *
-     * What a caller does owe: the action must be safe to run at an arbitrary microtask boundary, not
-     * only from inside a calculation.
-     *
-     * For the engine's own deferrals (wiring a name, recompiling its dependents), which stay
-     * backend-side. A grid request is never queued here: it goes through {@link sendRequest}, as
-     * data, so the channel can hold it (DESIGN-CALC-SERVICE §6.2).
-     */
     whenSafe(action: () => Promise<unknown>): void;
     /**
      * `true` while the engine is either `Starting` or inside a pending-action drain — at any drain
@@ -401,8 +342,11 @@ export interface IContextContainer {
      * so dependents pick up the change. A recompile, not a dirty-mark, on purpose: a definition
      * change requires dependents to re-derive their precedents (`setInputs`), which `markDirty` does
      * not do. Where a re-evaluation suffices, use {@link invalidateNamed} instead.
+     *
+     * @param loaded The name's definition has not changed: its body is the one the file holds, only
+     * now compiled. A formula still as it was loaded re-derives its precedents and keeps its value.
      */
-    recompileNamed(nameId: string): void;
+    recompileNamed(nameId: string, loaded?: boolean): void;
     /**
      * Marks every formula that references `nameId` — directly or through another name — dirty, so it
      * re-evaluates against the name's current definition.

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

@@ -0,0 +1,5 @@
+/** @internal */
+export declare const markKeepBlanks: (result: object) => void;
+/** @internal */
+export declare const isKeepBlanks: (result: object) => boolean;
+//# sourceMappingURL=_KeepBlanks.d.ts.map

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

@@ -3,48 +3,51 @@ import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
 import { IGrid, ISparseGrid, Tuple, IListLike } from '../../collections';
 import { ReferenceErrorIndex } from '../../primitives/ReferenceRange';
 /**
- * The calc grid's committed values with the pass's UNCOMMITTED results laid over them.
+ * The batch's cells: every result of a pass goes in here and most are read straight back out, so
+ * this is an open-addressed table on (row, col) rather than a `Map`.
  *
  * @remarks
- * The executor batches results and commits them in one write (`writeCalcs`); a reference built
- * during the pass used to force that commit whenever it could see a batched cell. On a row-chained
- * sheet (`SUM($K$51:K#)` on every row) that was a commit per row — thousands of small persistent
- * writes into the same long runs. This grid serves those reads from the batch instead, so the
- * executor commits every N results and the writes are few and contiguous.
- *
- * It is a SUBSTITUTION view: iteration walks the committed runs and swaps in the pending value
- * where one exists. That only describes a cell the committed grid already holds; a result for a
- * cell with no committed run under it (a formula's first result — new after load, entry, paste)
- * cannot be shown this way, so such a push marks the overlay `uncovered` and the next ITERATION
- * over the pending box commits first (`_coverFor`), which is exactly the old behavior; a point
- * read is answered by the map and never commits. A steady-state recalc never trips it. Reads
- * outside the batch's bounding box never touch the map.
- *
- * Operations that materialize or write go through a commit first and then the committed grid —
- * the safe fallback for anything a substitution cannot answer (`getValues`, `copyTo`, `clone`,
- * every write). `cloneEmpty` needs no values.
- *
- * It is also the error index of references built over it ({@link ReferenceErrorIndex}): the
- * committed index plus a scan of the pending map, taken only while the batch holds an error.
- *
- * A second layer holds DEMAND results (DESIGN-CIRCULAR-CALC.md §4.6): what demand evaluation and
- * the iteration sweeps compute ahead of the plan. It is not part of the batch — a commit leaves it
- * alone — and an entry lives until the plan takes its node ({@link takeDemand}), which then pushes
- * the same value to the batch. A sweep rewrites its members many times, and every rewrite is a map
- * write, not a persistent one. Substitution still needs a committed run under the cell, so the
- * first result for a cell with nothing under it is written through as well; every later one is
- * substituted.
+ * Consecutive rows of a column take consecutive slots, which is the order a filled block runs in,
+ * so a chain probes once per cell. A commit empties it, so it is never much larger than a batch. A
+ * value of `undefined` means no entry; a blank is held as `null`.
  */
+declare class PendingCells {
+    size: number;
+    private _keys;
+    private _values;
+    /** The occupied slots in the order they were filled. */
+    private _order;
+    private _mask;
+    /** The slot holding the cell, or the empty one it would take. The table is never full. */
+    private _slotOf;
+    get(row: number, col: number): Scalar | undefined;
+    /** @returns What the cell held, or `undefined` for a new one. */
+    set(row: number, col: number, value: Scalar): Scalar | undefined;
+    clear(): void;
+    /** Whether a cell added at or after position `from` of the fill order has nothing in `grid`. */
+    anyAbsentFrom(from: number, grid: ISparseGrid<Scalar>): boolean;
+    /** Whether an error is held inside the rectangle. */
+    hasErrorIn(rowStart: number, colStart: number, rowEnd: number, colEnd: number): boolean;
+    private _grow;
+}
 export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, ReferenceErrorIndex {
     protected readonly _inner: ISparseGrid<Scalar>;
     protected readonly _committed: ReferenceErrorIndex;
     protected readonly _flush: () => void;
     protected readonly _isColumn: boolean;
-    protected _pending: Map<number, Scalar>;
+    protected _pending: PendingCells;
+    /** Results pushed before anything read through here: counted, and not in {@link _pending}. */
+    protected _unobserved: number;
+    /** A read has landed in the pending box this pass, so results are held in {@link _pending}. */
+    observed: boolean;
     /** Pending values that are errors — the pending scan in {@link hasErrorIn} runs only while > 0. */
     protected _errors: number;
     /** A pending cell has no committed run under it; substitution cannot show it. */
     protected _uncovered: boolean;
+    /** The pending cells {@link _uncovered} has answered for. Only an iteration asks, so a push does not look. */
+    protected _coverChecked: number;
+    /** Where the copy {@link _substituteRun} last made starts. */
+    protected _substitutedFrom: number;
     protected _rowStart: number;
     protected _rowEnd: number;
     protected _colStart: number;
@@ -89,6 +92,8 @@ export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, Referenc
     protected _growAny(row: number, col: number): void;
     /** Rebuilds the union box from the two layers' own. */
     protected _resetAny(): void;
+    /** From here on results are held in the map; what was pushed before it is committed now. */
+    observe(): void;
     /** Does a rectangle overlap the bounding box of the cells either layer holds? */
     intersects(rowStart: number, colStart: number, rowEnd: number, colEnd: number): boolean;
     /** Does a rectangle overlap the pending (batch) cells' bounding box? */
@@ -104,7 +109,7 @@ export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, Referenc
      */
     protected _writeDemandIn(bounds: Partial<RangeCoords> | null | undefined): void;
     /** The cell's value in either layer (they never share a cell), or `undefined`. */
-    protected _layered(key: number): Scalar | undefined;
+    protected _layered(row: number, col: number): Scalar | undefined;
     /**
      * Before an ITERATION over `bounds`: commits when a pending cell substitution cannot show
      * (`uncovered`) lies inside them. A point read never needs this — the map answers it — and
@@ -118,8 +123,15 @@ export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, Referenc
     protected _inBounds(row: number, col: number): boolean;
     /** Nothing in either layer: every read is the committed grid's. */
     protected _isEmpty(): boolean;
-    /** The run with pending values swapped in, or the run itself when none fall inside it. */
-    protected _substituteRun(major: number, minorFrom: number, run: IListLike<Scalar>): IListLike<Scalar>;
+    /**
+     * The part of a run a read asked for with pending values swapped in, or the run itself when none
+     * fall inside that part. A copy starts at {@link _substitutedFrom}.
+     *
+     * @remarks
+     * A stored run can be a whole column, so a copy is never wider than the read: a short range over
+     * a long run costs what the range costs.
+     */
+    protected _substituteRun(major: number, minorFrom: number, run: IListLike<Scalar>, readFrom: number, readTo: number): IListLike<Scalar>;
     /** {@inheritDoc IGrid.getValueAt} */
     getValueAt(row: number, column: number): Scalar;
     /** {@inheritDoc ISparseGrid.getRuns} */
@@ -166,4 +178,5 @@ export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, Referenc
  * @internal
  */
 export declare function _scanHasError(grid: ISparseGrid<Scalar>, coords: IRange.Coords): boolean;
+export {};
 //# sourceMappingURL=_PendingOverlayGrid.d.ts.map

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

@@ -2,20 +2,6 @@ import { IRange, Scalar } from '@sheetxl/primitives';
 import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
 import { Tuple, IGrid, ISparseGrid, IListLike } from '../../collections';
 import { ReferenceErrorIndex } from '../../primitives/ReferenceRange';
-/**
- * A grid's values with a what-if substitution laid over them (DESIGN-DATA-TABLES §4.3): the input
- * cells a `TABLE` puts axis values into, and the results of the cells it re-evaluates under them.
- * A point read and an iteration answer from the map first and the grid underneath otherwise (the
- * pass's pending overlay during a pass), as `PendingOverlayGrid` does; nothing here is ever written
- * through, so the committed values, the formula blocks and the model are untouched and there is
- * nothing to restore. Dropped when the table is done.
- *
- * @remarks
- * Also the error index of the references built over it ({@link ReferenceErrorIndex}): the
- * underlying index plus a scan of the map, taken only while the map holds an error.
- *
- * Every write of the grid interface is refused: a what-if evaluation reads.
- */
 export declare class WhatIfLayer implements ISparseGrid<Scalar>, ReferenceErrorIndex {
     protected readonly _inner: ISparseGrid<Scalar>;
     protected readonly _committed: ReferenceErrorIndex;

package/types/src/calculation/symbol/ExternalSheetSymbols.d.ts

@@ -1,16 +1,6 @@
 import { IExternalBookCollection, ExternalScopeParts } from '../../externalBook';
 import { ExternalBookCollection } from '../../externalBook/ExternalBookCollection';
 import { SheetSymbolHandle } from './SheetSymbolProvider';
-/**
- * The stable-id prefix that marks a sheet symbol as living in an external book.
- *
- * @remarks
- * `ext:<bookId>` is the book-scoped form (`[1]!Name`); `ext:<bookId>:<sheetIndex>` adds a sheet, and
- * `ext:<bookId>:<first>:<last>` is a 3-D span across the book's sheets (`[1]Alpha:Data Sheet`). The
- * prefix is the test every consumer uses — "is this scope external" is a `startsWith`, which is why
- * external books needed no new {@link SymbolType} and no new branch in the twenty-odd places that
- * ask the Sheet provider (DESIGN-EXTERNAL-LINKS §4B).
- */
 export declare const EXTERNAL_ID_PREFIX = "ext:";
 /** Is this stable id an external sheet or book? */
 export declare const isExternalSymbolId: (stableId: string | null | undefined) => boolean;
@@ -41,39 +31,7 @@ export interface ExternalBookMinter {
     /** Records `sheetName` on an existing book — answers the sheet's index. */
     addSheet(bookId: string, sheetName: string): number;
 }
-/**
- * Binds a sheet scope that names an external book, or `null` if it names none of this workbook's.
- *
- * @remarks
- * Every spelling a book answers to binds to the SAME id, so the storage form (`[1]Sheet1`), the
- * closed display form (`C:\dir\[Book.xlsx]Sheet1`) and the open one (`[Book.xlsx]Sheet1`) are three
- * ways of writing one symbol — which is the invariant that lets a handle's `toString()` be fed
- * straight back to `bind` (see {@link SheetSymbolProvider}).
- *
- * A position that does not exist (`[7]` of three books) answers `null`: the typed image is kept
- * verbatim, the reference is `#REF!`, and the writer warns. A file name matching more than one book
- * answers `null` too — the citation is genuinely ambiguous and `[n]` is the only spelling that is
- * not — unless the typed directory picks one of them out.
- *
- * A 3-D span (`[1]Alpha:Data Sheet`) binds to one id with its sheets in the book's own order, so
- * `[1]Data Sheet:Alpha` is the same symbol; both sheets must be listed.
- *
- * With a `minter`, a file name no book carries MINTS one (DESIGN-EXTERNAL-LINKS §4C): typing
- * `'C:\dir\[Book.xlsx]Sheet1'!A1` creates the link, cache empty, exactly as Excel does when it cannot
- * see the source. A sheet a known book does not list is recorded on it the same way. A `[n]` is never
- * minted — a position is a citation of something that exists, and a directory that differs from a
- * same-named book's is a different book, not a respelling of it. A span never mints either.
- */
 export declare function bindExternalScope(books: ExternalBookCollection | null | undefined, displayName: string, minter?: ExternalBookMinter | null, withinBook?: string | null): string | null;
-/**
- * Resolves an `ext:` stable id to a sheet handle, or `null` if the book has since been removed.
- *
- * @remarks
- * `toString()` is the projection DESIGN-EXTERNAL-LINKS §4B describes: `[n]Sheet1` by default — the
- * form a formula is STORED as, read off the book's current position — and the book's display name
- * when the caller asks for one. Both bind back. A span spells both sheets after one book prefix
- * (`[1]Alpha:Data Sheet`), as Excel writes it.
- */
 export declare function resolveExternalSymbol(books: ExternalBookCollection | null | undefined, stableId: string, display: boolean): SheetSymbolHandle | null;
 /** The `AddOptions` a minted book starts from: the typed directory and file, the typed sheet. */
 export declare function mintedBookOptions(parts: ExternalScopeParts): IExternalBookCollection.AddOptions;

package/types/src/calculation/symbol/ISymbolRegistry.d.ts

@@ -19,12 +19,6 @@ export interface SheetCtx {
      * (`'C:\dir\[Book.xlsx]Sheet1'`). A local sheet has one name and ignores this.
      */
     display?: boolean;
-    /**
-     * Bind is AUTHORING: a scope that names an external book this workbook has none of may create
-     * one (`'C:\dir\[Book.xlsx]Sheet1'` typed into a cell is how a link is made — DESIGN-EXTERNAL-LINKS
-     * §5 step 13). Off by default, and off for an editing compile, so a keystroke mints nothing; a
-     * local sheet is never minted.
-     */
     mint?: boolean;
     /**
      * The formula being linked belongs to an external BOOK — a cached defined name's body — so a

package/types/src/calculation/symbol/SheetSymbolProvider.d.ts

@@ -1,17 +1,5 @@
 import { IRange } from '@sheetxl/primitives';
 import { ISymbolProvider, SymbolHandle } from './ISymbolRegistry';
-/**
- * Strict provider for sheet symbols.
- *
- * @remarks
- * An EXTERNAL sheet is a sheet symbol too. A scope this workbook has no sheet for, and which names
- * a book (`[1]Sheet1`, `C:\dir\[Book.xlsx]Sheet1`), falls through to `_getExternal` rather than to a
- * `SymbolType` of its own — the twenty-odd consumers of a scope all ask this provider, and teaching
- * one provider a second spelling touches none of them (DESIGN-EXTERNAL-LINKS §4B).
- *
- * So is a 3-D span (`Alpha:Gamma`, PLAN-3D-REFS §2.1): one symbol naming its two endpoint sheets,
- * `<firstId>:<lastId>`, with the endpoints in tab order.
- */
 export declare class SheetSymbolProvider implements ISymbolProvider {
     private readonly _getId;
     private readonly _getById;

package/types/src/calculation/symbol/SymbolRegistry.d.ts

@@ -16,15 +16,6 @@ export declare class SymbolRegistry implements ISymbolRegistry {
     /** @inheritdoc ISymbolRegistry.resolve */
     resolve(type: SymbolType, stableId: string, ctx?: Record<string, unknown>): SymbolHandle | null;
 }
-/**
- * A registry that answers some symbol types from providers of its own and every other from a base.
- *
- * @remarks
- * The model's symbol map (DESIGN-CALC-SERVICE §8) is this over the engine's: the types the engine
- * keeps a copy of resolve through the model's live items here, while the rest resolve through the
- * engine's providers. Registering a provider registers it on the base, so a provider that arrives
- * late (the functions, once their module loads) is seen by both.
- */
 export declare class OverlaidSymbolRegistry implements ISymbolRegistry {
     private readonly _base;
     private readonly _overrides;

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

@@ -1,11 +1,3 @@
-/**
- * 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';

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

@@ -298,6 +298,11 @@ export interface ICell {
     isTopLeft(): boolean;
     /**
      * Returns the range of the cell if it is a spill cell.
+     *
+     * @remarks
+     * For a blocked spill (a {@link getSpillKind | kind} of `error`, the anchor shows `#SPILL!`) this
+     * is the range it would take. It holds none of those cells: their values are whatever is in the
+     * way. Spills can overlap, and one that is not blocked is returned ahead of one that is.
      */
     getSpill(): ICellRange | null;
     /**
@@ -976,26 +981,11 @@ export declare namespace ICell {
      * 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.
+     * **Rank** says which finding to read first. It is not a confidence, and it is relative to 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. Regions of the `anomalies` feature list highest rank first, and so do a cell's
+     * findings, in check order within an equal rank.
      *
      * **Literals and twins.** `literalMatchesInput` reads the numbers typed into a formula against
      * the typed numbers no formula reads: a reference replaced by its value is what left the input
@@ -1005,16 +995,12 @@ export declare namespace ICell {
      * when both are a calendar period, a power of ten or a small count. Every side of a divergence is
      * listed, since two wrong rows can outvote the right one.
      *
-     * `literalMatchesInput` ranks at `0.8 / matches`. A `twinBlockDivergence` finding ranks at `0.8`
-     * times the share of the twins on the other side, `twins / (twins + this side's count)`, halved
-     * for a sign: signs differ between line items by design, so a sign divergence is read when asked
-     * for by check. `scaleOutlier` ranks at `0.8`.
+     * A sign divergence ranks low: signs differ between line items by design, so it is read when
+     * asked for by check.
      *
      * `constantFrequency` reports every constant a formula types, the common ones too, with how many
-     * places in the workbook type it (`uses`) and of how many constant uses (`of`). It ranks at
-     * `0.1 / uses × of / (of + 10)`: the rarer the constant, the higher, and a constant on a workbook
-     * that types few has little to be rare against. A finding's `uses` and `of` change when another
-     * sheet changes.
+     * places in the workbook type it (`uses`) and of how many constant uses (`of`). The rarer the
+     * constant, the higher it ranks. A finding's `uses` and `of` change when another sheet changes.
      *
      * 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.

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

@@ -811,7 +811,7 @@ export interface ICellRange {
      * // 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 });
-     * // Or name the kind of defect and let the measured order decide.
+     * // Or name the kind of defect and let the ranking decide.
      * sheet.getAnomalies({ focus: 'unitMismatch', limit: 25 });
      * ```
      *
@@ -1417,10 +1417,13 @@ export interface ICellRange {
      *
      * This method is a more scalable alternative to `getValues` or `getCells` for large or sparse ranges,
      * as it:
-     * 1. Skips empty values by default.
+     * 1. Skips empty values by default, however much of the range is styled.
      * 2. Avoids creating large arrays.
      * 3. Allows for early termination.
-  
+     *
+     * To reach blank cells that have a feature, such as a fill or a hyperlink, name it in
+     * {@link ICellRange.IteratorOptions.features}.
+     *
      * @param callback A function that will be called for each non-empty cell in the range. The callback receives:
      *   - `value`: The `Scalar` at the current cell.
      *   - `context`: A `IteratorContext` object providing additional information and utilities for the cell.
@@ -2209,8 +2212,8 @@ export declare namespace ICellRange {
          *
          * @remarks
          * The same lens {@link ICellRange.getCounts} and {@link ICellRange.getRegions} take, and it
-         * costs no extra scan: the range is split at the hidden runs first (off the header run
-         * structure, no per-cell probe) and the resulting pieces are measured as ONE population.
+         * costs no extra scan: the range is split at the hidden runs first and the resulting pieces
+         * are measured as ONE population.
          *
          * Optionally an {@link IRange.Axis} to skip on one axis only.
          */
@@ -2750,7 +2753,8 @@ export declare namespace ICellRange {
          */
         readonly Role: "role";
         /**
-         * Direct date-category number format — `yyyy-mm-dd`, `mm/dd/yyyy`, and the like.
+         * A date-category number format, given directly or by a named style — `yyyy-mm-dd`,
+         * `mm/dd/yyyy`, and the like.
          *
          * @remarks
          * A formatting predicate, not a value kind: a blank cell or a text cell formatted this way
@@ -2794,7 +2798,11 @@ export declare namespace ICellRange {
         readonly Fill: "fill";
         /** Direct borders. */
         readonly Borders: "borders";
-        /** Direct number format. Region payloads carry the format string and its category. */
+        /**
+         * A number format given directly or by a named style, not one left at Normal's. Region payloads
+         * carry the format string and its category, so a block with `0%` set directly and one with the
+         * `Percent` style are one region.
+         */
         readonly NumberFormat: "numberFormat";
         /** Direct alignment. */
         readonly Alignment: "alignment";
@@ -2811,7 +2819,7 @@ export declare namespace ICellRange {
         readonly Table: "table";
         /** Auto-table membership. */
         readonly AutoTable: "autoTable";
-        /** Has a hyperlink. */
+        /** Has a hyperlink. Regions group by what the link says, so the same link set twice is one region. */
         readonly Hyperlink: "hyperlink";
         /**
          * Ignores one or more of Excel's error checks. Regions group by the set of checks ignored.
@@ -2965,8 +2973,8 @@ export declare namespace ICellRange {
         checks?: readonly ICell.ErrorCheck[];
         /**
          * The kind of defect being looked for, or several: regions are ordered by how often findings
-         * like theirs have been that kind of defect, measured on audited models, and by rank where
-         * that is equal. With `checks` too, the named checks still list first and `focus` orders
+         * like theirs have been that kind of defect in audited models, and by rank where that is
+         * equal. With `checks` too, the named checks still list first and `focus` orders
          * within each. An unknown name throws.
          *
          * @defaultValue none — by rank
@@ -3062,9 +3070,12 @@ export declare namespace ICellRange {
         /**
          * The features the iteration resolves and visits.
          *
-         * @defaultValue all features
+         * @defaultValue all features are resolved, and only the cells with values are visited
          *
          * @remarks
+         * Naming a feature also visits the blank cells that have it: `features: 'hyperlink'` reaches a
+         * link on an empty cell, and `features: 'fill'` every cell of a filled column.
+         *
          * Two effects, both wins for a caller that does not need everything:
          * - The iterator only materializes the requested features' state onto the context — an
          *   excluded feature is never even looked up.

package/types/src/chart/Chart.d.ts

@@ -194,12 +194,6 @@ export declare class Chart extends AbstractMovableContent<State, IChart.JSON, IC
     private _readCells;
     /** A cell as its text: a number formatted by its own cell's format, the rest as Excel shows it. */
     private _cellText;
-    /**
-     * What the chart's cells hold now, for resolve (DESIGN-CHART §3.3): values, categories, names
-     * and the first cell's number format are read from the cells the engine's formulas name, in the
-     * order Excel reads a range (column by column, {@link inReadOrder}). Where the cells cannot be
-     * read, the model's cache answers.
-     */
     private _dataReader;
     /** How many listeners want `onLayoutChange`. */
     private _layoutListeners;
@@ -232,10 +226,6 @@ export declare class Chart extends AbstractMovableContent<State, IChart.JSON, IC
     private _syncDataListeners;
     /** {@inheritDoc ITransaction.ITransactional.close} */
     close(): void;
-    /**
-     * The cache `reference` holds when read now, as Excel writes it (DESIGN-CHART §3.3, measured
-     * 2026-10-16), or `null` where its cells cannot be read and the cache it has stands.
-     */
     private _cacheOf;
     /**
      * A multi-level category cache: one level per column, the innermost (the last) first, each
@@ -250,12 +240,6 @@ export declare class Chart extends AbstractMovableContent<State, IChart.JSON, IC
     /** {@inheritDoc IChart.isIChart} */
     get isIChart(): true;
 }
-/**
- * A number as Excel writes it into a chart cache (measured 2026-10-16, `probe-chart-values.ps1`
- * W3): its shortest digits when 15 or fewer say it, else 17; in exponent form (`1E-3`, `1E+16`)
- * below 0.01 and from 10^16 up. Excel sometimes writes 17 digits where fewer say the same number
- * (`1.0000000000000001E-5`); either reads back as the same number.
- */
 export declare const cacheNumberText: (value: number) => string;
 /**
  * Interfaces for creating `Chart` items.