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

package/types/scripting.d.ts

@@ -862,6 +862,26 @@ declare global {
         params?: Record<string, string | number>;
     }
 
+    /**
+     * The control types a cell control can have, by type.
+     *
+     * @remarks
+     * The built-in types are registered before the registry is first used; a host registers its own
+     * the same way. A type nobody has registered still loads and saves, and accepts no value, so its
+     * cells draw as text.
+     */
+    export namespace CellControlRegistry {
+        /**
+         * Registers a kind. A kind registered again under the same type replaces the earlier one,
+         * a built-in included.
+         */
+        function register(kind: ICellControlKind): void;
+        /** The kind registered for `type`, or `null`. */
+        function get(type: string): ICellControlKind | null;
+        /** The registered types. */
+        function getTypes(): string[];
+    }
+
     /**
      * The coordinates of a cell in a 2D space.
      */
@@ -1157,7 +1177,11 @@ declare global {
         width: number;
         height: number;
         chartArea: {
-            fill: IFill.JSON | null;
+            /**
+             * `undefined` where the chart states no fill: the chart area is the background of where it is
+             * drawn (Excel draws it in the theme's background color).
+             */
+            fill: IFill.JSON | null | undefined;
             border: IStroke.JSON | null;
             /** The radius of the chart area's corners, measured along the border's path; 0 for square corners. */
             cornerRadius: number;
@@ -2634,6 +2658,11 @@ declare global {
         }
     }
 
+    /**
+     * Excel's checkbox: draws a boolean or a blank cell, in place of its text.
+     */
+    export const CheckboxKind: ICellControlKind;
+
     export const ClipboardUtils: {
         readBlobFromClipboard: (clipboard: Clipboard | null, mimeType: string) => Promise<Blob | null>;
         readStringFromClipboard: (clipboard: Clipboard | null, mimeType?: string) => Promise<string>;
@@ -4992,7 +5021,9 @@ declare global {
          * @returns A promise that will be resolved when the calculation is completed.
          *
          * @remarks
-         * For async functions this will return before they are completed.
+         * For async functions this will return before they are completed. An async function is called
+         * again unless its call is still running; what it fetches is answered
+         * from the workbook's cache unless {@link ICalculation.CalculateOptions.external} is set.
          */
         calculate(options?: boolean | ICalculation.CalculateOptions): Promise<ICalculation.Status>;
         /**
@@ -5011,7 +5042,7 @@ declare global {
         /**
          * Resolves once the engine is running and idle: its calculation state is
          * {@link ICalculation.CalculationState.Done}, or {@link ICalculation.CalculationState.Pending} in
-         * manual mode.
+         * manual mode (and, under `AutomaticExceptTables`, with only data tables out of date).
          *
          * @remarks
          * * After it, every answer the engine owes has landed: a formula written before it reads as
@@ -5019,14 +5050,46 @@ declare global {
          * * Manual mode does not wait for a recalculation nobody has asked for; call {@link calculate}.
          * * Waits for what consumers derive from the results too ({@link waitUntil}): a conditional
          *   format reads as painted after it, including one a read just asked to evaluate.
-         * * A streaming or async function's result in flight is not waited for: its cell reads as the
-         *   current value until the result arrives.
+         * * An async function's result in flight is not waited for: its cell reads as what the
+         *   function returned until the result arrives.
          * * Starts the engine if it is {@link ICalculation.Status.Off}. An engine in
          *   {@link ICalculation.Status.Error} is not started; {@link start} tries again.
          *
          * @param options Pass `{ full: true }` to recalculate every grid rather than only the dirty ones.
          */
         ready(options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+        /**
+         * How many async function calls are waiting for an answer.
+         */
+        getPendingCount(): number;
+        /**
+         * Resolves once no async function call is pending ({@link getPendingCount} is `0`) and every
+         * answer has been calculated into the workbook — Excel's `CalculateUntilAsyncQueriesDone`.
+         *
+         * @param options `timeout` in milliseconds; 30 seconds when absent.
+         * @returns `true` when nothing is pending; `false` when the timeout came first.
+         *
+         * @remarks
+         * * An answer that makes a formula ask a new question (one call's answer is another's input)
+         *   is waited for too.
+         * * {@link ready} is the engine's own readiness and does not wait for answers.
+         */
+        whenPendingDone(options?: {
+            timeout?: number;
+        }): Promise<boolean>;
+        /**
+         * Stops waiting for async function calls — Excel's *Cancel Refresh*: each pending
+         * call the options cover is closed, and the function is told (its `onCancel`).
+         *
+         * @param options Which calls; every call when absent.
+         * @returns A promise that resolves once the cells have been recalculated.
+         *
+         * @remarks
+         * * A cell keeps what it showed — its last answer, or the value its function returned while it
+         *   waited — and is no longer pending. An answer that arrives later is dropped.
+         * * A recalculation of a cancelled cell calls its function again.
+         */
+        cancelAsync(options?: ICalculation.CancelOptions): Promise<ICalculation.Status>;
         /**
          * Counts `work` that a consumer derives from the engine's results as calculation in flight
          * until it settles: {@link ready} waits for it, and {@link getCalculationState} reads
@@ -6016,6 +6079,14 @@ declare global {
              * Use {@link ICalculation.FormulaToken.evalIndex} to discover valid indices.
              */
             evalIndex?: number;
+            /**
+             * How long to wait, in milliseconds, for the answers of async functions the formula calls:
+             * the evaluation resolves once each has answered, and
+             * answers a `#TIMEOUT!` error naming the call it waited on when the time runs out.
+             *
+             * @defaultValue `30000`
+             */
+            timeout?: number;
             /**
              * Temporary range of values to use for this evaluation.
              *
@@ -6148,6 +6219,15 @@ declare global {
              * Called when the calculation state has changed - see {@link ICalculation.getCalculationState}.
              */
             onCalculationStateChange?(source: ICalculation): void;
+            /**
+             * Called when the number of async function calls waiting for an answer may have changed — see
+             * {@link ICalculation.getPendingCount}.
+             *
+             * @remarks
+             * Called when calls are made, when answers are applied, and on a cancel or a stop: answers
+             * arriving together are one call.
+             */
+            onPendingChange?(source: ICalculation): void;
             /**
              * Called when a calculation is completed.
              */
@@ -6216,7 +6296,8 @@ declare global {
             readonly Calculating: "calculating";
             /**
              * Changes have been made that need a recalculation, and none will run until one is asked for:
-             * manual mode between an edit and {@link ICalculation.calculate}.
+             * manual mode between an edit and {@link ICalculation.calculate}, or the `TABLE` data tables an
+             * edit left out of date under `AutomaticExceptTables`.
              */
             readonly Pending: "pending";
         };
@@ -6287,14 +6368,16 @@ declare global {
              */
             readonly Stale: "stale";
             /**
-             * The value is being calculated asynchronously, typically because the function used returned a Promise.
-             * All dependent values will also be in the Pending state. If the promise returns an error or times out, the value will be an error value.
+             * The cell's own function asked for its result later (`FormulaContext.defer`) and it has not
+             * arrived: the cell shows what the function returned meanwhile, and its dependents calculate
+             * from that and read as {@link Waiting}. A failed call answers an error value.
              */
             readonly Pending: "pending";
             /**
-             * The value is up-to-date, but the underlying data source is streaming live updates.
+             * The value was calculated from a pending value — a precedent whose function has not answered —
+             * and will be calculated again when it does.
              */
-            readonly Streaming: "streaming";
+            readonly Waiting: "waiting";
         };
         type ResultStatus = typeof ResultStatus[keyof typeof ResultStatus];
         /**
@@ -6332,6 +6415,39 @@ declare global {
              * live in other sheets, and a named formula's body lives in a virtual grid of its own.
              */
             scope?: string;
+            /**
+             * If `true`, what the calculation reads from outside the workbook is read from the source
+             * again rather than from the workbook's cache — Excel's *Data › Refresh All*: what the async
+             * functions it calls fetch, and, for a calculation that is neither {@link range} nor
+             * {@link scope}, every external book (`IExternalBookCollection.refreshAll`).
+             *
+             * @remarks
+             * * Which functions are called is the calculation's own choice, as without it: pass
+             *   {@link full} for every formula. A call still running is left be.
+             * * The calculation resolves without waiting for the new answers or the external books.
+             *
+             * @example Refresh All
+             * ```ts
+             * await workbook.getCalculation().calculate({ full: true, external: true });
+             * ```
+             *
+             * @defaultValue `false`
+             */
+            external?: boolean;
+        }
+        /**
+         * Options for {@link ICalculation.cancelAsync}.
+         */
+        interface CancelOptions {
+            /**
+             * Only the calls of the formulas in this range are cancelled.
+             */
+            range?: ICellRange.Address;
+            /**
+             * Only the calls of the formulas on this sheet, by name, are cancelled. Ignored when
+             * {@link range} is set.
+             */
+            scope?: string;
         }
         interface JSON {
             /**
@@ -6611,10 +6727,16 @@ declare global {
          */
         getRole(): ICell.Role | null;
         /**
-         * Returns the hyperlink assigned to the cell.
+         * Returns the cell's link: the hyperlink set on the cell, else the link its value is.
          *
          * @remarks
-         * Returns `null` if no hyperlink is set.
+         * Returns `null` when the cell has neither.
+         *
+         * A `HYPERLINK()` result (a {@link Hyperlink} value with an address) is returned as a link with
+         * {@link IHyperlink.isReadOnly} `true`; it is not removed or edited as a link, it changes with
+         * its formula. A hyperlink set on the cell wins when the cell has both. Excel's
+         * `Range.Hyperlinks` and Office Scripts' `Range.getHyperlink()` return nothing for a
+         * `HYPERLINK()` cell.
          */
         getHyperlink(): IHyperlink | null;
         /**
@@ -6831,6 +6953,14 @@ declare global {
          * only lays out text does not need to read this at all.
          */
         getConditionalDecorations(): Readonly<IConditionalFormat.Decorations>;
+        /**
+         * Returns the cell's control, such as a checkbox, or `null` when it has none.
+         *
+         * @remarks
+         * A control draws only a value it accepts: ask `getControl()?.isAccepted(getValue())`. A
+         * checkbox cell holding `2` has a control and draws `2`.
+         */
+        getControl(): ICellControl | null;
         /**
          * If the cell is in a table this will return it.
          */
@@ -7186,40 +7316,10 @@ declare global {
              */
             anchorBounds: Bounds;
         }
-        /**
-         * Encodings of ScalarType for persistence
-         */
-        type JSONScalarType = 'n' | 's' | 'b' | 'e' | 'r' | 'z';
-        /**
-         * A value encoded as a number with an associated type.
-         */
-        interface JSONTypedValue {
-            t: JSONScalarType;
-            /**
-             * 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.
          */
         type Coords = IRange.CellCoords;
-        /**
-         * JSON values types that have their type embedded in the
-         * 'format'.
-         *
-         * @remarks
-         * A string value is the string id in the `IStringsCollection`.
-         */
-        type JSONUnTypedValue = number | boolean | string;
-        /**
-         * For persisting a single Cell value and type.
-         *
-         * @remarks
-         * Styling and other advanced properties are stored as ranges.
-         */
-        type JSON = JSONUnTypedValue | JSONTypedValue;
         /**
          * Represents the types of content that can be associated with a cell or range.
          *
@@ -7373,12 +7473,22 @@ declare global {
             readonly LookupShape: "lookupShape";
             /** A reference to another workbook, a deleted reference, or a function a converter could not name. */
             readonly ExternalReference: "externalReference";
+            /** A formula that is only an error value, such as `=#DIV/0!`: what a converter leaves when it drops a formula. */
+            readonly ErrorConstant: "errorConstant";
             /** 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";
+            /** A number typed into a formula that equals a typed number on the sheet no formula reads. */
+            readonly LiteralMatchesInput: "literalMatchesInput";
+            /** A formula that differs from its twins on the sheet, the formulas of the same shape, in a typed number. */
+            readonly TwinBlockDivergence: "twinBlockDivergence";
+            /** A typed number an order of magnitude or more off the numbers typed in its format on the sheet. */
+            readonly ScaleOutlier: "scaleOutlier";
+            /** A constant typed into a formula — a number, a string or a boolean — and how often the workbook types it. */
+            readonly ConstantFrequency: "constantFrequency";
         };
         type ErrorCheck = typeof ErrorCheck[keyof typeof ErrorCheck];
         /**
@@ -7409,9 +7519,14 @@ declare global {
          * | `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'` |
+         * | `errorConstant` | `error`, the error the formula is; `dataTable`, the anchor of a data table that spills less than the block it heads, and `extent`, the rectangle the two cover |
          * | `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 |
+         * | `literalMatchesInput` | `literal`, the number as the formula types it; `inputAt`, the nearest typed number of that value no formula reads; `label` / `labelAt`, that input's label, when it has one; `matches`, the places the value is typed unread |
+         * | `twinBlockDivergence` | `part` (`'literal'` / `'sign'`); for a literal, `literal` and `expected`, this formula's number and its twins'; for a sign, `term` of `terms`, the term that differs, `references`, how many the shape holds, and `sign`, how this formula adds it; `twins`, how many formulas carry the other side; `twinAt`, one of them |
+         * | `scaleOutlier` | `format` (`'percent'`); `times`, the power of ten the value is off by; `typical`, the median of the sheet's typed numbers in that format; `of`, how many there are |
+         * | `constantFrequency` | `kind` (`'number'`, `'string'`, `'boolean'`); `value`, a number without its sign; `uses`, the places in the workbook that type it; `of`, the workbook's constant uses |
          *
          * **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
@@ -7466,6 +7581,25 @@ declare global {
          * 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.
          *
+         * **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
+         * unread. Small counts, calendar periods and powers of ten never fire. `twinBlockDivergence`
+         * reads formulas of the same shape once references, literals and signs are set aside: twins that
+         * divide by `12` and by `365`, or one that adds a term the others take away. Literals compare only
+         * 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`.
+         *
+         * `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.
+         *
          * 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.
          */
@@ -7503,6 +7637,11 @@ declare global {
          * Option to provide shared strings.
          */
         strings?: IStringCollection;
+        /**
+         * Option to provide shared rich values, the store cells hold rich data in by id, as they hold
+         * strings in {@link strings}.
+         */
+        richData?: IRichDataCollection;
         /**
          * Option to provide a shared StyleCollection. If not provided then a new StyleCollection with default theming will be used.
          */
@@ -7616,6 +7755,189 @@ declare global {
         type CalcOnLoad = 'auto' | 'full' | 'none';
     }
 
+    /**
+     * A control drawn in the cells of a range, such as a checkbox.
+     *
+     * @remarks
+     * A cell control decorates the cell's value; it never holds one. A checkbox draws `TRUE` as
+     * checked and `FALSE` or blank as unchecked, and a click writes the boolean into the cell, where
+     * formulas read it as any other value. Excel's model is the same: the checkbox is a cell
+     * *format*, and *Clear Formats* removes it while the value stays.
+     *
+     * * A cell has at most one control. One control covers any number of cells, and its ranges
+     *   shift, split, copy and fill with them.
+     * * A control draws only the values its type accepts ({@link isAccepted}). Any other value draws
+     *   as plain text: a checkbox over `2` or `"true"` draws `2` or `true`, as in Excel.
+     * * Most code never needs this interface: {@link ICellRange.setControl} and
+     *   {@link ICellRange.getControls} stand in for Office Scripts' `Range.setControl` /
+     *   `getControl`.
+     */
+    export interface ICellControl extends IAnchored {
+        /**
+         * The control's type, such as `'checkbox'`.
+         *
+         * @remarks
+         * A type nobody has registered (`CellControlRegistry`) is kept and saved as it was read; it
+         * accepts no value, so its cells draw as text.
+         */
+        getType(): string;
+        /**
+         * Returns the first range the control covers.
+         *
+         * @remarks
+         * See {@link IAnchored.getRanges} for all of them. To change where a control is, use
+         * {@link ICellRange.setControl}.
+         */
+        getRange(): ICellRange;
+        /**
+         * Whether the control draws a cell holding `value`.
+         *
+         * @remarks
+         * A checkbox accepts a boolean or a blank cell. A value it does not accept draws as the cell
+         * would without the control.
+         */
+        isAccepted(value: Scalar): boolean;
+        /**
+         * Add Listeners.
+         *
+         * @see
+         * {@link IListener.ISource.addListeners}
+         */
+        addListeners(listeners: ICellControl.IListeners, options?: IListener.Options): IListener.Remove;
+        /**
+         * The control as JSON: its `type` and any properties of that type.
+         */
+        toJSON(): ICellControl.JSON;
+        /**
+         * For runtime type checking.
+         */
+        readonly isICellControl: true;
+    }
+
+    /**
+     * {@inheritDoc ICellControl}
+     * @see
+     * ### **Interface**
+     *
+     * {@link ICellControl}
+     *
+     * **Additional Interfaces**
+     * * {@link ICellControlCollection}
+     */
+    export namespace ICellControl {
+        /**
+         * A control as JSON: its `type`, and any properties that type defines.
+         *
+         * @remarks
+         * Office Scripts' `CellControl`: `{ type: 'checkbox' }`. A checkbox has no other properties.
+         * Office Scripts' `EmptyCellControl` is `null` here.
+         */
+        interface JSON {
+            /**
+             * The control's type, such as `'checkbox'`.
+             */
+            type: string;
+            /**
+             * Properties of the type.
+             */
+            [property: string]: unknown;
+        }
+        /**
+         * IListener for {@link ICellControl} events.
+         */
+        interface Events extends IAnchored.Events<ICellControl> {
+        }
+        interface IListeners extends IListener.Callbacks<ICellControl, ICellControl.Events> {
+        }
+    }
+
+    /**
+     * Holds a sheet's {@link ICellControl}s.
+     *
+     * @remarks
+     * Most code reaches controls through the range instead: {@link ICellRange.setControl} puts a
+     * control on cells and {@link ICellRange.getControls} reads it back. The collection is for listing
+     * every control, as a task pane does.
+     */
+    export interface ICellControlCollection extends ICollection<ICellControl> {
+        /**
+         * Puts a control on the cells of `address`, replacing their controls, and returns it.
+         *
+         * @param address The address of the cells. May name several discontiguous ranges.
+         * @param control The control, such as `{ type: 'checkbox' }`.
+         *
+         * @remarks
+         * The same write as {@link ICellRange.setControl}, over any address. A cell has at most one
+         * control, so the cells leave whatever control they had, and join a control of the same
+         * definition when the sheet already has one.
+         */
+        add(address: ICellRanges.Address, control: ICellControl.JSON, options?: ITransaction.OperationOptions): ICellControl;
+        /**
+         * Returns items that match the filter criteria.
+         *
+         * If no filter criteria is provided, all items will be returned.
+         *
+         * @param options {@link ICellControlCollection.GetItemsOptions}
+         */
+        getItems(options?: ICellControlCollection.GetItemsOptions): ICellControl[];
+        /** For runtime type checking. */
+        readonly isICellControlCollection: true;
+    }
+
+    /**
+     * {@inheritDoc ICellControlCollection}
+     * @see
+     * ### **Interface**
+     *
+     * {@link ICellControlCollection}
+     */
+    export namespace ICellControlCollection {
+        /**
+         * Options for searching for {@link ICellControl}s.
+         */
+        interface GetItemsOptions extends ICollection.GetItemsOptions {
+            /**
+             * If provided, the search will be limited to items that intersect the range.
+             */
+            address?: ICellRange.Address;
+            /**
+             * Indicate if items that are in hidden headers or marked as hidden should be returned.
+             *
+             * @defaultValue false
+             */
+            ignoreHidden?: boolean;
+            /**
+             * Only return items that are completely contained with the search bounds.
+             *
+             * @defaultValue false
+             */
+            fullyContained?: boolean;
+        }
+    }
+
+    /**
+     * What a control type does to the cells it covers: which values it draws.
+     *
+     * @remarks
+     * The SDK half of a control type. How it looks and how it responds to the pointer and keys belong
+     * to the UI, which registers its own renderer under the same `type`.
+     */
+    export interface ICellControlKind {
+        /**
+         * The type this kind is registered under, such as `'checkbox'`.
+         */
+        readonly type: string;
+        /**
+         * The kind's name where a UI lists the kinds that can be inserted, such as `'Rating'`. Plain
+         * text; the built-in checkbox takes its name from the command catalog instead.
+         */
+        readonly label?: string;
+        /**
+         * Whether the control draws a cell holding `value`. Any other value draws as text.
+         */
+        accepts(value: Scalar): boolean;
+    }
+
     /**
      * A logic label for an entire span of cells in either direction.
      */
@@ -8341,6 +8663,39 @@ declare global {
          * {@link IConditionalFormat.getRanges}.
          */
         getConditionalFormats(options?: ICellRange.GetItemsOptions<IConditionalFormatCollection.GetItemsOptions>): IConditionalFormat[];
+        /**
+         * Returns the {@link ICellControl}s on cells within the range, such as checkboxes.
+         *
+         * @param options The filters of {@link ICellControlCollection.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 has at most one control; ask a cell for its own with
+         * {@link ICell.getControl}.
+         *
+         * Office Scripts' `Range.getControl()` answers one `CellControl` for the whole range; here
+         * `getControls()[0]?.getType()` reads a single cell's, and `toJSON()` gives the
+         * `{ type: 'checkbox' }` shape. A control is about the cell, not its value: a checkbox cell
+         * holding `2` still has one, though it draws `2` ({@link ICellControl.isAccepted}). A type
+         * SheetXL does not know answers with its own name, where Excel answers `unknown`.
+         */
+        getControls(options?: ICellRange.GetItemsOptions<ICellControlCollection.GetItemsOptions>): ICellControl[];
+        /**
+         * Puts `control` on every cell of the range, replacing the control each had; `null` removes
+         * them.
+         *
+         * @param control The control, such as `{ type: 'checkbox' }`, or `null`.
+         *
+         * @remarks
+         * Office Scripts' `Range.setControl`, with `null` for its `{ type: 'empty' }`. A cell has at most
+         * one control. The values stay as they are: a checkbox draws `TRUE` as checked and `FALSE` or a
+         * blank cell as unchecked, and any other value as text.
+         *
+         * A control is a format: refused on a protected sheet unless formatting cells is allowed, removed
+         * by {@link clear} of formats, and carried by a paste of formats.
+         */
+        setControl(control: ICellControl.JSON | null, options?: ITransaction.OperationOptions): this;
         /**
          * Returns the {@link IDataValidation}s that overlap the range.
          *
@@ -9013,7 +9368,7 @@ declare global {
         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.
+         * the rest, each by the named focus or by rank.
          *
          * @param options {@link ICellRange.GetAnomaliesOptions}
          *
@@ -9022,6 +9377,8 @@ declare global {
          * // 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.
+         * sheet.getAnomalies({ focus: 'unitMismatch', limit: 25 });
          * ```
          *
          * @remarks
@@ -9032,6 +9389,13 @@ declare global {
          * region two named checks fire on lists once, under the first. An ignored check
          * ({@link setErrorIgnored}) is not there to list.
          *
+         * `focus` names the kind of defect being looked for ({@link ICellRange.AnomalyFocus}). Each
+         * finding then weighs as the share of findings like it — the same check, the same kind of
+         * evidence, about as often repeated in the listing — that were that kind of defect in audited
+         * models, and a region lists by its best finding, by rank where that is equal. Several kinds
+         * merge into one order by the best of them. It reorders; it neither adds nor drops a region, and
+         * the findings' own ranks are unchanged.
+         *
          * `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.
@@ -9534,12 +9898,23 @@ declare global {
          */
         select(options?: ICellRange.SelectOptions): Promise<this>;
         /**
-         * Add a listener to the range.
+         * Listen for changes at this range: its cells written, recalculated or undone, and the range
+         * itself moved by rows or columns inserted or deleted around it.
          *
-         * @returns A callback to remove. {@link IListener.Remove}
+         * @returns A callback that removes the listener. {@link IListener.Remove}
          *
          * @remarks
-         * If the range becomes invalid through a delete this will auto remove.
+         * The listener is handed an {@link ICellRange.Event} whose source is the listened range where
+         * it is now. Which events it hears, how it follows inserts and deletes, and whether it takes
+         * part in the change or observes it afterwards are {@link ICellRange.ListenerOptions}.
+         *
+         * @example
+         * ```ts
+         * const remove = sheet.getRange('A1:C3').addListener((event) => {
+         *   if (event.getTrigger() === 'data') console.log('changed:', event.getRanges()!.getAddress());
+         *   else console.log('now at:', event.getSource().getAddress());
+         * });
+         * ```
          */
         addListener(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
         /**
@@ -9796,15 +10171,20 @@ declare global {
          */
         type ScalarUpdate = Scalar | null | undefined;
         /**
-         * Represents an update to a cell's value in JavaScript, allowing `Date` and `null`.
+         * Represents an update to a cell's value in JavaScript, allowing `Date`, a rich value's JSON
+         * and `null`.
          *
          * @remarks
          * This type allows for updating a cell's value, including `Date` for convenience.
          * As with `ScalarUpdate`, `null` can be used to clear the cell's value.
          *
+         * A rich value may be given as its JSON (`{ type, data }`, what {@link IRichData.toJSON}
+         * returns); it is made by the kind registered for `type`, and an unregistered type is kept
+         * as it was given.
+         *
          * * See {@link InteropScalar} for more details on JavaScript scalar values.
          */
-        type InteropScalarUpdate = InteropScalar | null | undefined;
+        type InteropScalarUpdate = InteropScalar | IRichData.JSON | null | undefined;
         /**
          * Single or 2D.
          */
@@ -10935,6 +11315,14 @@ declare global {
              * failure — its cells evaluate, to `0` — and is {@link Feature.Circular}.
              */
             readonly CalcError: "calcError";
+            /**
+             * Evaluated state: cells whose result has not settled. Regions group by status — a cell whose
+             * own function has not answered yet ({@link ICalculation.ResultStatus.Pending}), or one
+             * calculated from such a value and calculated again when it arrives
+             * ({@link ICalculation.ResultStatus.Waiting}). The anchor's `getCalculationStatus()` is the
+             * payload. Empty once every answer has landed.
+             */
+            readonly CalcStatus: "calcStatus";
             /**
              * Evaluated state: cells in a reference cycle, or downstream of one. Both evaluate to `0`
              * (Excel, iterative calculation off) with nothing else to show for it — this is the marker.
@@ -10982,6 +11370,14 @@ declare global {
             readonly Conditionals: "conditionals";
             /** Cells under data-validation rules. */
             readonly DataValidations: "dataValidations";
+            /**
+             * Cells under a cell control ({@link ICellRange.setControl}). Regions group by the control's
+             * definition (its type and properties), so adjacent checkboxes set in two strokes are one
+             * region and a checkbox beside a rating are two; the anchor cell's {@link ICell.getControl} is
+             * the payload. Whether a cell draws its control depends on its value, which is a `Kind`
+             * question: ask for both to split a column of checkboxes from the text cells among them.
+             */
+            readonly CellControl: "cellControl";
             /**
              * 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
@@ -11003,7 +11399,11 @@ declare global {
              * 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.
+             * (`signVsSiblings`); and from the numbers: a typed number in a formula equal to an input
+             * nothing reads (`literalMatchesInput`), twin formulas that differ in a unit literal or a sign
+             * (`twinBlockDivergence`), a percent typed as a whole number (`scaleOutlier`), every constant a
+             * formula types with how often the workbook types it (`constantFrequency`). An ignored check
+             * ({@link ICellRange.setErrorIgnored}) does not fire.
              *
              * Regions list highest rank first ({@link ICell.Anomaly.rank}), unless an `axis` is asked for.
              *
@@ -11067,6 +11467,33 @@ declare global {
              */
             containment?: 'intersects' | 'fullyContained';
         }
+        /**
+         * A kind of defect a reader is looking for, which {@link ICellRange.getAnomalies} can order its
+         * findings by ({@link GetAnomaliesOptions.focus}).
+         */
+        const AnomalyFocus: {
+            /** A cell or a subtotal counted twice in a sum. */
+            readonly DoubleCounting: "doubleCounting";
+            /** A typed number where a reference belongs. */
+            readonly EmbeddedHardcode: "embeddedHardcode";
+            /** A cell whose font color is not its role's (inputs, links, calculations). */
+            readonly ColorCoding: "colorCoding";
+            /** An average over the wrong cells. */
+            readonly Average: "average";
+            /** A link to another sheet that reads the wrong row or column. */
+            readonly CrossSheetReference: "crossSheetReference";
+            /** A term added that should be taken away, or the reverse. */
+            readonly SignConvention: "signConvention";
+            /** A lookup that matches approximately, or reads arrays that do not line up. */
+            readonly Lookup: "lookup";
+            /** A reference relative where it should be absolute, or the reverse. */
+            readonly ReferenceAnchoring: "referenceAnchoring";
+            /** A value in the wrong unit: a monthly figure in a daily formula, a percent typed as a whole number. */
+            readonly UnitMismatch: "unitMismatch";
+            /** Rows deleted from a model, which leaves references shifted and `#REF!`. */
+            readonly DeletedRows: "deletedRows";
+        };
+        type AnomalyFocus = typeof AnomalyFocus[keyof typeof AnomalyFocus];
         /**
          * Options for {@link ICellRange.getAnomalies}.
          */
@@ -11077,6 +11504,15 @@ declare global {
              * @defaultValue none — every region by rank
              */
             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
+             * within each. An unknown name throws.
+             *
+             * @defaultValue none — by rank
+             */
+            focus?: AnomalyFocus | readonly AnomalyFocus[];
             /**
              * At most this many regions.
              *
@@ -11229,85 +11665,101 @@ declare global {
              */
             injectReferences?: IRange.JSONReference<any>[][];
         }
-        interface Event {
+        /**
+         * What a range listener is told. See {@link ICellRange.addListener}.
+         *
+         * @typeParam S The source the listener registered on: an `ICellRange` from
+         * {@link ICellRange.addListener}, an `ICellRanges` from {@link ICellRanges.addListener}.
+         */
+        interface Event<S extends ICellRange | ICellRanges = ICellRange> {
             /**
              * The range that was listened to, where it is now.
              *
              * @remarks
-             * After a `'address'` or `'restore'` event this is the range at its new address or extent: rows
+             * After an `'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.
+             *
+             * A range whose cells were deleted is invalid ({@link ICellRange.isInvalid}) and spells
+             * `#REF!`; one restored to a revision from before the listener was added is invalid and
+             * spells `#N/A`.
              */
-            getSource<T = ICellRange | ICellRanges>(): T;
+            getSource(): S;
             /**
-             * This is the range of data that has been changed.
+             * The cells that changed within the source, for a `'data'` event; `null` for any other.
              *
              * @remarks
-             * This is different than the source range as that is the entire range area that was listened to.
+             * A batch is one change: every range of it that reached the listener arrives in one event.
              */
-            getFrom(): ICellRanges;
+            getRanges(): ICellRanges | null;
             /**
-             * 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.
+             * Where the source was before an `'address'` event moved it; `null` for any other event, and
+             * for a sheet rename, which moves no cells.
+             *
+             * @remarks
+             * An address rather than a range, because the cells at it now are other cells.
              */
+            getPreviousAddress(): string | null;
             /**
-             * Indicates the type of change that triggered the event.
+             * What happened to the range.
              *
              * @remarks
-             * * `'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 — 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.
+             * * `'data'`: Cells within the range changed: written, recalculated, or undone. The range's
+             *   address and extent are as they were. {@link getCommit} is `null` for a recalculation,
+             *   which belongs to no commit; {@link isUndo} tells an undo from a write.
+             * * `'address'`: The range's address or extent changed: rows or columns inserted or deleted,
+             *   cells moved, its cells deleted (the source spells `#REF!`), or, for a sheet-qualified
+             *   range (one from {@link IWorkbook.getRange}, or a sheet's range naming another sheet), a
+             *   rename of the sheet it names. A bare range on its own sheet has no qualifier, so a rename
+             *   is not a change to it. A listener anchored {@link IAnchored.Type.Absolute} never moves and
+             *   never has one.
+             * * `'restore'`: The workbook was restored to a revision from before the listener was added,
+             *   so the range is not in it (the source spells `#N/A`). Never delivered to a transactional
+             *   listener.
              */
-            readonly trigger2?: 'data' | 'address' | 'restore';
-            readonly trigger: string;
+            getTrigger(): Event.Trigger;
             /**
-             * Indicates if the event is being fired from an undo event.
+             * `true` when the change is an undo. A redo is not an undo: it is told as the forward change
+             * was.
              */
-            readonly isUndo?: boolean;
+            isUndo(): boolean;
             /**
-             * Returns the transaction Id if the event is occurring in a transaction otherwise `null`.
+             * The commit that made the change, or `null` when none did: a recalculation landing.
              *
-             * @see
-             * {@link ListenerOptions.getTransactionId}
+             * @remarks
+             * A transactional listener is told before the commit is sealed, so this is the commit it is
+             * writing into ({@link ListenerOptions.transactional}).
              */
-            getTransactionId(): string | null;
+            getCommit(): ITransaction.ICommit | null;
             /**
-             * Indicates if the event is being fired due to a cell value change.
-             *
-             * @see
-             * {@link ListenerOptions.ignoreDataChanges}
+             * The trigger and the source, for logging.
              */
-            readonly isDataChange?: boolean;
+            toString(): string;
             /**
-             * To string the event.
+             * When the event was made, in milliseconds since the epoch.
              */
-            toString(): string;
+            getTimeStamp(): number;
+        }
+        namespace Event {
             /**
-             * The timestamp of the event.
+             * What happened to a listened range. See {@link ICellRange.Event.getTrigger}.
              */
-            readonly timeStamp: number;
+            type Trigger = 'data' | 'address' | 'restore';
         }
         /**
-         * Represents a listen for a range. The listener will be called when the range's
-         * data, address, or restore state changes, subject to the provided options.
+         * Called with what changed at a listened range. See {@link ICellRange.addListener}.
          *
-         * @remarks
-         * If the range is deleted (rows/columns removed), the trigger will be `'address'`
-         * `trigger` of `'address'` and `getRange().getError()`
-         * returning `"#REF!"`.
+         * @typeParam S The source the listener registered on; see {@link ICellRange.Event}.
          *
-         * If the ranges is restored to a revision *before* the listener was
-         * added, the listener will receive event with a `trigger` of `'restore'`
-         * and `getRange().getError()` returning `"#N/A"`.
+         * @remarks
+         * Read the range from {@link Event.getSource}, which is where the listened cells are now. It is
+         * invalid ({@link ICellRange.isInvalid}) when the cells were deleted (`#REF!`) or the workbook
+         * was restored to a revision from before the listener was added (`#N/A`); the listener stays
+         * registered through both, and hears the range come back.
          */
-        interface Listener {
-            (event: ICellRange.Event): void;
+        interface Listener<S extends ICellRange | ICellRanges = ICellRange> {
+            (event: ICellRange.Event<S>): void;
         }
         /**
          * Receives a watch's results — one value per cell of the watched range, read with LOCAL
@@ -11353,11 +11805,28 @@ declare global {
             /**
              * If `true`, the listener will *not* be called when the range's
              * address changes (due to row/column insert/delete, moves, or a rename of
-             * the sheet a qualified range names)
+             * the sheet a qualified range names). The range still follows its cells; see {@link anchor}
+             * for a range that should not.
              *
              * @defaultValue false
              */
             ignoreAddressChanges?: boolean;
+            /**
+             * How the listened range follows rows and columns inserted or deleted around it.
+             *
+             * @defaultValue {@link IAnchored.Type.TwoCell}
+             *
+             * @remarks
+             * * `TwoCell`: the range follows its cells, as a formula reference does. An insert above it
+             *   moves it down, a delete inside it shrinks it, and deleting all of its cells makes it
+             *   `#REF!`. Each move is an `'address'` event.
+             * * `OneCell`: the top-left follows its cell and the extent is kept, as a picture anchored to
+             *   one cell. Deleting the top-left cell leaves the range where it is.
+             * * `Absolute`: the range never moves. It names the same addresses whatever is inserted or
+             *   deleted, so it never has an `'address'` event. This is what a view listening to the rows
+             *   it shows wants: the cells on screen, not the cells that were there when it subscribed.
+             */
+            anchor?: IAnchored.Type;
             /**
              * Whether the listener takes part in the operations that change its range.
              *
@@ -11485,14 +11954,15 @@ declare global {
          * This is Excel's `Ctrl+Enter` fill: the same scalar is written to all selected cells — across every
          * discontiguous range — as a single {@link ICellRanges.doBatch} operation (one undo step). A formula
          * string (e.g. `"=A1+1"`) is coerced and its relative references adjust per cell, exactly as
-         * {@link ICellRange.setValue} does within one range.
+         * {@link ICellRange.setValue} does within one range. It takes what that does: a `Date`, or a rich
+         * value's JSON (`{ type, data }`), which each cell makes into its own value.
          *
          * Only the scalar-broadcast form exists (no `setValues`): a 2D shape has no coherent meaning spread
          * across discontiguous ranges of differing sizes.
          * @see
          * {@link ICellRange.setValue}
          */
-        setValue(value: ICellRange.ScalarUpdate, options?: ICellRange.SetValuesOptions): this;
+        setValue(value: ICellRange.InteropScalarUpdate, options?: ICellRange.SetValuesOptions): this;
         /**
          * {@inheritDoc ICellRange.merge}
          */
@@ -11748,7 +12218,7 @@ declare global {
         /**
          * {@inheritDoc ICellRange.addListener}
          */
-        addListener(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
+        addListener(listener: ICellRange.Listener<ICellRanges>, options?: ICellRange.ListenerOptions): IListener.Remove;
         /**
          * {@link ICellRange.addWatch} across every area, as ONE expression authored at a shared origin.
          *
@@ -18371,120 +18841,6 @@ declare global {
         }
     }
 
-    /**
-     * A what-if data table (Excel's **What-If Analysis > Data Table**): a block of result cells, each
-     * the table's formula evaluated with its row and column values put in the input cells.
-     *
-     * @remarks
-     * The table is carried, not calculated: its results are the values the file held, and nothing
-     * recalculates them. Excel recalculates it when it opens the file (when the calculation mode and
-     * {@link IDataTable.JSON.calculateAlways} allow).
-     *
-     * The anchor is the result cells; the formula, the row values above them and the column values to
-     * their left are ordinary cells. As in Excel, an edit to part of the results is refused, and one
-     * that clears or deletes all of them deletes the table.
-     */
-    export interface IDataTable extends IAnchored {
-        toJSON(): IDataTable.JSON | null;
-        /**
-         * Returns the result cells.
-         *
-         * @remarks
-         * An insert or delete before them moves them, one taking all of them deletes the table
-         * ({@link IAnchored.isDeleted}), and one that would move part of them is refused.
-         */
-        getRange(options?: ICellRange.GetRangeOptions): ICellRange;
-        /**
-         * Returns the input cell the row values are put in, as an A1 address on this sheet, or `null`
-         * when the table has none (a one-input table down a column).
-         *
-         * @remarks
-         * Follows the cell through inserts, deletes and moves. Once the cell is deleted this is the last
-         * address it had, and {@link isRowInputDeleted} is `true`.
-         */
-        getRowInput(): string | null;
-        /**
-         * Returns the input cell the column values are put in, as an A1 address on this sheet, or `null`
-         * when the table has none (a one-input table along a row).
-         *
-         * @remarks
-         * Follows the cell as {@link getRowInput} does.
-         */
-        getColumnInput(): string | null;
-        /**
-         * Returns whether the row input cell was deleted. The table's results are then `#REF!` in Excel.
-         */
-        isRowInputDeleted(): boolean;
-        /**
-         * Returns whether the column input cell was deleted.
-         */
-        isColumnInputDeleted(): boolean;
-        /** For runtime type checking. */
-        readonly isIDataTable: true;
-    }
-
-    export namespace IDataTable {
-        /**
-         * JSON representation of a data table.
-         *
-         * @remarks
-         * A table has a row input, a column input, or both (a two-input table).
-         */
-        interface JSON {
-            /**
-             * The result cells, as an A1 range.
-             */
-            ref: string;
-            /**
-             * The input cell the row values are put in, as an A1 address on the same sheet.
-             */
-            rowInput?: string;
-            /**
-             * The input cell the column values are put in, as an A1 address on the same sheet.
-             */
-            columnInput?: string;
-            /**
-             * Whether the row input cell was deleted; {@link rowInput} is then its last address.
-             */
-            rowInputDeleted?: boolean;
-            /**
-             * Whether the column input cell was deleted; {@link columnInput} is then its last address.
-             */
-            columnInputDeleted?: boolean;
-            /**
-             * Whether Excel recalculates the table when it opens the file. Without it, Excel shows the
-             * results as saved until something recalculates the table.
-             *
-             * @remarks
-             * Kept as read until the workbook's cell data is edited, on any sheet. Then it is set on every
-             * table, because nothing here recalculates the results and they may no longer be right. It stays
-             * set when the edit is undone.
-             */
-            calculateAlways?: boolean;
-        }
-        /**
-         * `Events` for {@link IDataTable}.
-         */
-        interface Events extends IAnchored.Events<IDataTable> {
-        }
-    }
-
-    /**
-     * Holds a sheet's {@link IDataTable | data tables}.
-     *
-     * @remarks
-     * Read-only for now: a table is carried as it was read and written back. Creating one and
-     * calculating it wait on the engine evaluating `TABLE`.
-     */
-    export interface IDataTableCollection extends ICollection<IDataTable> {
-        /**
-         * Returns the data tables, in the order they were read.
-         */
-        getItems(options?: ICollection.GetItemsOptions): IDataTable[];
-        /** For runtime type checking. */
-        readonly isIDataTableCollection: true;
-    }
-
     /**
      * A data validation: a rule that a cell's value must satisfy, over one or more ranges of a sheet,
      * with the prompt shown when the cell is selected and the alert for a value that fails.
@@ -19861,11 +20217,11 @@ declare global {
             /** `<sheetData refreshError="1">` — Excel could not refresh this sheet's cache last time it tried. */
             refreshError?: boolean;
             /**
-             * Sparse cell values — the same encoding `IWorksheet.JSON.data` uses (`ICell.JSON` is already just
+             * Sparse cell values — the same encoding `IWorksheet.JSON.data` uses (`Scalar.JSON` is already just
              * the value+type pair; style/formula live in sibling fields there, none of which apply to a
              * values-only cache — design doc §2.5).
              */
-            data: Tuple.GridTuple<ICell.JSON>;
+            data: Tuple.GridTuple<Scalar.JSON>;
         }
         interface JSON {
             /**
@@ -19980,6 +20336,54 @@ declare global {
         }
     }
 
+    /**
+     * How a workbook reaches what lives outside it: the picture an `IMAGE` names, a web service's
+     * answer. A handler per URL scheme; a host registers its own to add authentication, or to serve a
+     * scheme of its own.
+     *
+     * @remarks
+     * Each workbook has one, given as `IWorkbook.ConstructorOptions.fetcher`, or a default that
+     * answers `http:` and `https:` with the global `fetch`.
+     *
+     * @example
+     * ```typescript
+     * const fetcher = new Fetcher();
+     * fetcher.register('https', (url, init) => fetch(url, {
+     *   ...init,
+     *   headers: { ...init?.headers, Authorization: `Bearer ${token}` }
+     * }));
+     * const workbook = new Workbook({ fetcher });
+     * ```
+     */
+    export interface IFetcher {
+        /**
+         * Fetches `input` with the handler registered for its scheme. A URL without a scheme goes to
+         * the `https` handler.
+         *
+         * @returns The response; rejects with a `TypeError` when no handler serves the scheme, as
+         * `fetch` does for a URL it cannot reach.
+         */
+        fetch(input: string, init?: RequestInit): Promise<Response>;
+        /**
+         * Serves a URL scheme with `handler`, replacing the handler it had.
+         *
+         * @param scheme The scheme, with or without its colon: `'https'`, `'resource:'`.
+         * @returns A function that removes the registration.
+         */
+        register(scheme: string, handler: IFetcher.Handler): () => void;
+        /**
+         * For runtime type checking.
+         */
+        readonly isIFetcher: true;
+    }
+
+    export namespace IFetcher {
+        /**
+         * Answers a fetch for one scheme, with the signature of the standard `fetch`.
+         */
+        type Handler = (url: string, init?: RequestInit) => Promise<Response>;
+    }
+
     /**
      * Defines how an area or shape is filled with color or a pattern.
      */
@@ -21875,6 +22279,7 @@ declare global {
      * | Category | Key methods |
      * |---|---|
      * | Evaluation lifecycle | `markVolatile`, `getRow`, `getColumn`, `getEntireCoords`, `getRandom` |
+     * | Answering later | `defer` |
      * | Argument reflection | `getArgs` |
      * | Output hints | `formatResults` |
      * | Range construction | `createRange`, `flattenAreas`, `filterHidden` |
@@ -22444,6 +22849,64 @@ declare global {
          * @throws If called outside a function dispatch — there are no arguments to reflect on.
          */
         getArgs(): IFunctionArguments;
+        /**
+         * Answers this call later: hands `executor` a call to settle, and leaves the cell showing what
+         * the function returns now.
+         *
+         * @param executor Runs once at the end of the recalculation with every call made against it.
+         * Pass a module-level function by name: calls join one batch when they name the same function.
+         * @param payload Everything the executor needs to answer this call, and how a later evaluation
+         * recognizes it: while the call is still waiting, a recalculation with
+         * an equal payload leaves it be rather than asking again. Once it has stopped, a recalculation
+         * calls the function again; what it fetched is answered from the workbook's cache
+         * (`IBatchContext.fetch`).
+         * @returns The last answer this call gave for the same question, when the function is being
+         * called again (a recalculation); `undefined` on a first call or a changed question. Return it
+         * to keep showing it until the new answer arrives, or return something else to show that the
+         * cell is waiting.
+         *
+         * @remarks
+         * The function still returns a value: what this call answers until its result arrives (nothing
+         * returned reads as blank), and it is what every formula over the cell calculates
+         * from meanwhile: return `#BUSY!` when they should wait as an error, or text such as
+         * `'Fetching…'` when that is what they should show.
+         *
+         * The executor runs after the recalculation, outside any cell; read nothing from the formula
+         * context there. Whatever the body knows goes in the payload.
+         *
+         * @example
+         * ```typescript
+         * function fetchAll(
+         *   calls: readonly IFormulaContext.DeferredCall<string>[],
+         *   ctx: IFormulaContext.IBatchContext
+         * ): void {
+         *   for (const call of calls) {
+         *     ctx.fetch(call.payload as string)
+         *       .then((response) => response.text())
+         *       .then((text) => call.resolve(text), (error) => call.reject(error));
+         *   }
+         * }
+         *
+         * export function FETCHTEXT(url: string): string {
+         *   FormulaContext.defer(fetchAll, url);
+         *   return 'Fetching…';
+         * }
+         * ```
+         */
+        defer(executor: IFormulaContext.DeferExecutor, payload?: unknown): unknown;
+        /**
+         * A rich value of a registered type, made from its data as the type's JSON holds it, for the
+         * workbook being calculated.
+         *
+         * @param type The name of the value's kind (`'hyperlink'`): what its `getKind().getName()`
+         * will answer.
+         * @param data The value's data, as its JSON's `data`.
+         *
+         * @remarks
+         * A type nobody has registered still makes a value: one that carries the data and reads as
+         * nothing.
+         */
+        createRichData(type: string, data?: any): IRichData;
     }
 
     /**
@@ -22595,6 +23058,67 @@ declare global {
              */
             readonly dow: number;
         }
+        /**
+         * Answers the calls made by {@link IFormulaContext.defer} against it. Invoked once at the end of
+         * a recalculation with every such call; how many requests that becomes is the executor's choice.
+         */
+        type DeferExecutor<T = any> = (calls: readonly DeferredCall<T>[], ctx: IBatchContext) => void | Promise<void>;
+        /**
+         * One call made by {@link IFormulaContext.defer}, as its executor receives it.
+         *
+         * @remarks
+         * Settle each call itself, never by its position in a response. An executor that returns a
+         * promise which rejects fails every call it has not settled.
+         */
+        interface DeferredCall<T = any> {
+            /** What the function passed to `defer`. */
+            readonly payload: unknown;
+            /** Settles the call with its result. */
+            resolve(value: T): void;
+            /** Settles the call with an error: a `FormulaError` as itself, anything else as `#VALUE!`. */
+            reject(error: unknown): void;
+            /** Runs `fn` when the result is no longer wanted. */
+            onCancel(fn: () => void): void;
+            /**
+             * Whether the result is no longer wanted. Only an executor that holds calls to settle later
+             * needs it; a result for a cancelled call is dropped.
+             */
+            readonly cancelled: boolean;
+        }
+        /**
+         * What an executor is given beside its calls.
+         */
+        interface IBatchContext {
+            /** A random number in `[0, 1)` from the calculation's source, which a test can seed. */
+            getRandom(): number;
+            /**
+             * State kept for this executor across recalculations, made by `init` on first ask. Keep data
+             * here (maps, numbers, strings, buffers), not connections or sockets.
+             */
+            getState<S>(init: () => S): S;
+            /**
+             * A rich value of a registered type, for the workbook being calculated: what
+             * {@link IFormulaContext.createRichData} makes inside a cell, made here for a call's result.
+             */
+            createRichData(type: string, data?: any): IRichData;
+            /**
+             * Adds bytes to the workbook being calculated as a resource (an `IResource`), for a rich value
+             * to hold: pass it in {@link createRichData}'s data. The workbook saves it while a value holds
+             * it. With `fetchedFrom` it is the workbook's copy of that URL: {@link fetch} answers the URL
+             * from it, and adding the same URL again answers the resource already added.
+             */
+            addResource(buffer: ArrayBuffer, options?: {
+                fetchedFrom?: string;
+            }): object;
+            /**
+             * Fetches through the workbook being calculated: the standard `fetch`, answered by the
+             * fetchers the host registered for the URL's scheme, with the host's authentication. An
+             * answer the workbook already has for the URL (a picture it keeps, or anything fetched while
+             * it is open) answers from the workbook, and two calls for one URL share one request. In an
+             * external calculation (*Refresh All*) it goes to the source.
+             */
+            fetch(input: string, init?: RequestInit): Promise<Response>;
+        }
     }
 
     /**
@@ -22881,11 +23405,9 @@ declare global {
             getMembers(): readonly IFunction.IEnumMember[];
         }
         /**
-         * Describes the runtime return behavior of a function, including modifiers like
-         * async resolution, streaming data, or volatility.
+         * Describes the runtime return behavior of a function, including modifiers like volatility.
          *
          * @remarks
-         * All return type modifiers are mutually exclusive.
          * If none are specified, The value will be returned with no special behavior.
          */
         interface IReturnType extends IValueType {
@@ -22897,19 +23419,6 @@ declare global {
              * @see {@link ReturnTypeJSON.kind}
              */
             getKind(): ValueKind | null;
-            /**
-             * Indicates the return value is a Promise or Promise-like (i.e., async).
-             * The system will mark the result as pending and re-trigger evaluation once resolved.
-             *
-             * Can be combined with any scalar, array, or range return type.
-             */
-            isAsync(): boolean;
-            /**
-             * Indicates whether the function produces a continuous stream of output (e.g., real-time data).
-             *
-             * @defaultValue `false`
-             */
-            isStreaming(): boolean;
             /**
              * True when the result can change with nothing dirty, so a cell naming this function
              * recalculates on every pass — the `Volatile<T>` marker.
@@ -23335,8 +23844,7 @@ declare global {
             members: [name: string, value: number | string, deprecated?: string | true][];
         }
         /**
-         * Describes the runtime return behavior of a function, including modifiers like
-         * async resolution, streaming data, or volatility.
+         * Describes the runtime return behavior of a function, including modifiers like volatility.
          *
          * @remarks
          * If none are specified, The value will be returned with no special behavior.
@@ -23360,19 +23868,6 @@ declare global {
              * is a scalar is its member value downstream.
              */
             kind?: ValueKind;
-            /**
-             * Indicates the return value is a Promise or Promise-like (i.e., async).
-             * The system will mark the result as pending and re-trigger evaluation once resolved.
-             *
-             * Can be combined with any scalar, array, or range return type.
-             */
-            async?: boolean;
-            /**
-             * Indicates whether the function produces a continuous stream of output (e.g., real-time data).
-             *
-             * @defaultValue `false`
-             */
-            stream?: boolean;
             /**
              * The result can change with nothing dirty — a cell naming this function recalculates on
              * every pass. Generated from the `Volatile<T>` marker.
@@ -23381,8 +23876,7 @@ declare global {
              * Collected at COMPILE time from the formula text (`CompiledFormula.hasVolatile`), because
              * that is where Excel decides it: `=IF(TRUE,1,RAND())` recalculates on every idle pass though
              * no branch selects the arm, and with lazy arguments the call never happens for the engine to
-             * observe. Sits beside {@link async} and {@link stream} because all three are about WHEN a
-             * result arrives rather than what it is.
+             * observe.
              *
              * @see {@link Volatile}
              */
@@ -24953,8 +25447,18 @@ declare global {
         getTarget(): string;
         /**
          * Removes the link from the cell it is attached to. The cell's text stays.
+         *
+         * @throws When the link is read-only ({@link isReadOnly}).
          */
         delete(options?: ITransaction.OperationOptions): void;
+        /**
+         * Whether the link can only be followed: it is not edited or removed as a link.
+         *
+         * @remarks
+         * A link that is the cell's value (a `HYPERLINK()` result) is read-only; it changes with its
+         * formula.
+         */
+        isReadOnly(): boolean;
         /**
          * For runtime type checking.
          */
@@ -26994,6 +27498,25 @@ declare global {
          * take the first.
          */
         getByRanges(ranges: ICellRanges.Address, options?: INamedCollection.GetByRangesOptions): string[];
+        /**
+         * Deletes the defined names nothing reads, as one operation.
+         *
+         * @param options `hiddenOnly` limits it to names flagged hidden; `dryRun` counts without deleting.
+         * @returns How many names were deleted, or with `dryRun`, would be.
+         * @throws `Error` if the names are read-only (a protected workbook structure) and this is not a dry run.
+         *
+         * @remarks
+         * A name is read when a cell formula, a conditional format, a data validation, a chart or another
+         * name refers to it — the readers `ICalculation.INamedFormula.getDependents` reports. A name
+         * that a kept name's definition mentions is kept too, whether or not anything reads that one.
+         * Only defined names are considered; a table is named by the table it belongs to. Excel's built-in
+         * names (`_xlnm.Print_Area`, `_xlnm.Print_Titles`, `_xlnm._FilterDatabase`) are read by the sheet
+         * itself, not by formulas, and are never removed.
+         *
+         * One operation, so one undo puts every name back. Asked of a sheet's collection
+         * (`IWorksheet.getNames()`), only the names scoped to that sheet are considered.
+         */
+        removeUnused(options?: INamedCollection.RemoveUnusedOptions): Promise<number>;
         /**
          * Lookup a named range with a given name.
          *
@@ -27133,6 +27656,23 @@ declare global {
              */
             includeHidden?: boolean;
         }
+        /**
+         * Options for {@link INamedCollection.removeUnused}.
+         */
+        interface RemoveUnusedOptions {
+            /**
+             * Only names flagged hidden — the ones a user cannot see to delete.
+             *
+             * @defaultValue false
+             */
+            hiddenOnly?: boolean;
+            /**
+             * Count the names that would be deleted, and delete none.
+             *
+             * @defaultValue false
+             */
+            dryRun?: boolean;
+        }
         /**
          * Options for {@link INamedCollection.getByRanges}.
          *
@@ -31613,6 +32153,11 @@ declare global {
          * An optional name for the resource.
          */
         getName(): string | null;
+        /**
+         * The URL the bytes were fetched from, when the resource is a picture the workbook keeps for it
+         * (an `IMAGE` source): a fetch of that URL answers from these bytes. `null` otherwise.
+         */
+        getFetchedFrom(): string | null;
         /**
          * For saving to json resources.
          */
@@ -31715,6 +32260,10 @@ declare global {
              * This is optional but if provided then resource lookup will use this as a cache key.
              */
             name?: string;
+            /**
+             * The URL the embedded bytes were fetched from: the workbook keeps them as that URL's picture.
+             */
+            fetchedFrom?: string;
         }
     }
 
@@ -31770,6 +32319,10 @@ declare global {
              * This is optional and purely for human consumption and is not used by the system.
              */
             name?: string;
+            /**
+             * The URL the bytes were fetched from, for a picture the workbook keeps for it.
+             */
+            fetchedFrom?: string;
         }
         /**
          * A type that represents the various ways to provide a resource source.
@@ -31825,14 +32378,20 @@ declare global {
      */
     export interface IRichData {
         /**
-         * Reference to either a known typename or a JSON Type Definition.
-         * * {@link https://jsontypedef.com/}
+         * The value's kind: the properties it has and how they show. Every value of a kind returns the
+         * same instance.
          */
-        getType(): string;
+        getKind(): IRichType;
         /**
          * @param name The name of the property to retrieve.
          */
         getProperty(name: string): Scalar;
+        /**
+         * How the property `name` shows on this value: the value's own presentation where it differs
+         * from its kind's (a price in another currency), else the kind's ({@link IRichType.Property.meta}).
+         * `null`, or the method absent, for none.
+         */
+        getPropertyMeta?(name: string): IRichMeta | null;
         /**
          * The text shown for this value where nothing renders it: a client with no renderer for the
          * kind, a log, a placeholder. A rich text shows its text; an image a short description.
@@ -31844,23 +32403,26 @@ declare global {
         toString(): string;
         /**
          * The primitive this value reads as wherever one is consumed: `LEN`, `&`, `+`, comparison,
-         * `ISTEXT`, `TYPE()`, sort, filter, find. A rich text reads as its text; an image reads as
-         * nothing (`null`, or the method absent), and is `#VALUE!` wherever a primitive is needed.
+         * `ISTEXT`, `TYPE()`, sort, filter, find. A rich text reads as its text; an error that carries
+         * more than its code reads as that error; an image reads as nothing (`null`, or the method
+         * absent), and is `#VALUE!` wherever a primitive is needed.
          *
          * @remarks
-         * The ordinary rules then apply to the primitive (text-to-number coercion, collation), so a
-         * value adds no coercions of its own.
+         * The ordinary rules then apply to the primitive (text-to-number coercion, collation, error
+         * propagation), so a value adds no coercions of its own.
          */
-        toPrimitive?(): number | string | boolean | null;
+        toPrimitive?(): Exclude<Scalar, IRichData>;
         /**
          * The items this value unpacks to where a range or array is accepted (a list); `null`, or the
          * method absent, for a value that is one value.
          */
         toArray?(): Scalar[][] | null;
         /**
-         * Indicates this is an IRichData type.
+         * The value as JSON, which its kind makes it again from. A value that holds a resource (a
+         * picture's bytes) names it by the id `toResourceId` answers, and the file saves the resource;
+         * without `toResourceId` it names none.
          */
-        toJSON?(): IRichData.JSON | Promise<IRichData.JSON>;
+        toJSON?(toResourceId?: IRichData.ToResourceId): IRichData.JSON | Promise<IRichData.JSON>;
         /**
          * For runtime type checking.
          */
@@ -31868,31 +32430,224 @@ declare global {
     }
 
     export namespace IRichData {
+        /**
+         * The id a file being saved gives a resource a value holds (an `IResource`); `null` when the
+         * file does not save it.
+         */
+        type ToResourceId = (resource: any) => number | null;
         interface JSON {
+            /** The name of the value's kind ({@link IRichType.getName}). */
             type: string;
+            /** The value's own data, as its kind reads it. */
             data?: any;
+            /**
+             * Presentation for the properties where this value differs from its kind, by property name.
+             */
+            meta?: {
+                readonly [property: string]: IRichMeta;
+            };
         }
     }
 
     /**
-     * A registered kind of rich data: its name, and how a value of it is made from its JSON.
+     * The rich values a workbook's cells hold, interned: a cell run stores a rich value as its id here,
+     * as it stores a string as its id in the string collection.
      *
      * @remarks
-     * A value's `getType()` is the kind's `name`. What a value reads as where a primitive or an array
-     * is consumed is the value's own answer ({@link IRichData.toPrimitive}, {@link IRichData.toArray}),
-     * as `toString()` is; the kind only makes values.
+     * Equal values share one id (equal JSON; a resource counts by identity), so recalculating a
+     * formula that makes a new but equal value adds nothing. Values are not removed: a save writes only
+     * the ones a cell holds.
+     */
+    export interface IRichDataCollection extends ICollection<IRichData> {
+        /**
+         * The id of `value`, added when no equal value is here.
+         *
+         * @param value A rich value. Never an error: an error is stored by its code.
+         */
+        add(value: IRichData): number;
+        /**
+         * The value for an id, or `null` if not found.
+         *
+         * @param id The id {@link add} answered.
+         */
+        getById(id: number): IRichData | null;
+        /**
+         * Starts saving or loading the rich values cells name. Scopes begun while one is open share its
+         * ids, so a workbook and its sheets agree on them.
+         */
+        beginPersist(): IRichDataCollection.IPersistScope;
+        /** For runtime type checking. */
+        readonly isIRichDataCollection: true;
+    }
+
+    /**
+     * {@inheritDoc IRichDataCollection}
+     * @see
+     * ### **Interface**
      *
-     * Register a kind with {@link RichDataRegistry.register}.
+     * {@link IRichDataCollection}
      */
-    export interface IRichDataKind<T extends IRichData = IRichData> {
+    export namespace IRichDataCollection {
+        /** A saved rich value: its kind's JSON. */
+        type JSON = IRichData.JSON;
         /**
-         * The kind's name, the `type` of its values and their JSON.
+         * One save or load of the rich values cells name. Ids are positions in the saved table, not the
+         * collection's own.
          */
-        readonly name: string;
+        interface IPersistScope {
+            /** The saved id of `value`, added to the table when new. */
+            add(value: IRichData): number;
+            /** The value a loaded id names, or `null`. */
+            at(id: number): IRichData | null;
+            /**
+             * Loads a saved table: each entry made by its kind, its ids then answered by {@link at}.
+             *
+             * @param ctx What the values are made for: the workbook's resources, and the file's resource ids.
+             * @param kinds The kinds saved with the table ({@link toKindsJSON}), made before the values
+             * that name them.
+             */
+            fromJSON(json: readonly JSON[] | undefined, ctx: IRichDataKind.Context, kinds?: readonly IRichType.JSON[]): void;
+            /**
+             * The table, in id order.
+             *
+             * @param toResourceId The saved id of a resource a value holds.
+             */
+            toJSONAsync(toResourceId?: IRichData.ToResourceId): Promise<JSON[]>;
+            /**
+             * The kinds the table's values name, nested values included, that are not registered in code
+             * and so are saved with it.
+             */
+            toKindsJSON(): IRichType.JSON[];
+            /** Ends the scope. The last to end lets the table go. */
+            endPersist(): void;
+        }
+    }
+
+    /**
+     * A registered kind of rich data: the {@link IRichType} its values return from `getKind()`, and how
+     * a value of it is made from its JSON.
+     *
+     * @remarks
+     * What a value reads as where a primitive or an array is consumed is the value's own answer
+     * ({@link IRichData.toPrimitive}, {@link IRichData.toArray}), as `toString()` is; the kind
+     * describes values and makes them.
+     *
+     * Make one with {@link IRichDataKind.create}; register it with {@link RichDataRegistry.register}.
+     */
+    export interface IRichDataKind<T extends IRichData = IRichData> extends IRichType {
         /**
          * A value from its JSON, as {@link IRichData.toJSON} wrote it.
+         *
+         * @param ctx What the value is being made for. Every value is made here, whether it is loaded,
+         * written with `setValue`, or returned by a function. `{ type }` alone asks for the kind's
+         * default value, which is what a UI inserts.
+         */
+        fromJSON(json: IRichData.JSON, ctx: IRichDataKind.Context): T;
+    }
+
+    export namespace IRichDataKind {
+        /**
+         * What a kind can reach while making a value.
          */
-        fromJSON(json: IRichData.JSON): T;
+        interface Context {
+            /**
+             * Binary resources (image bytes) by id, the store pictures use. `null` when the value is
+             * made outside a workbook, as an external link's cached values are.
+             */
+            readonly resources: IResourceCollection | null;
+            /**
+             * The string table the value's cells share. `null` outside a workbook.
+             */
+            readonly strings: IStringCollection | null;
+            /**
+             * The resource a value's JSON names by id, while a file is being read: the id
+             * `IRichData.toJSON`'s `toResourceId` gave it. `null` for an id the file does not hold, and
+             * always outside a read.
+             */
+            fromResourceId?(id: number): IResource | null;
+        }
+        /** A context with nothing to reach: a value made outside any workbook. */
+        const DetachedContext: Context;
+        /** What {@link create} makes a kind from. */
+        interface Definition<T extends IRichData = IRichData> {
+            /** {@inheritDoc IRichType.getName} */
+            name: string;
+            /** {@inheritDoc IRichType.getLabel} */
+            label?: string;
+            /** {@inheritDoc IRichType.getProperties} */
+            properties?: readonly IRichType.Property[];
+            /** {@inheritDoc IRichType.getDisplayProperty} */
+            displayProperty?: string | null;
+            /** {@inheritDoc IRichType.getMeta} */
+            meta?: IRichMeta | null;
+            /** {@inheritDoc IRichDataKind.fromJSON} */
+            fromJSON(json: IRichData.JSON, ctx: Context): T;
+        }
+        /** A kind from its definition. The kind is immutable. */
+        function create<T extends IRichData>(definition: Definition<T>): IRichDataKind<T>;
+    }
+
+    /**
+     * How a rich value, or one of its properties, is presented: the number format and caption of a
+     * property, where it is offered, its sources; a kind's card, icon and provider.
+     *
+     * @remarks
+     * Presentation only, never a value. A kind gives each of its properties a default; a value gives
+     * one only for a property where it differs (a price in another currency).
+     */
+    export interface IRichMeta {
+        /** The number format a number property shows in. */
+        readonly numberFormat?: string;
+        /** A short caption shown beside the property, such as its unit or the year of its data. */
+        readonly sublabel?: string;
+        /** Where the property is not offered. Each omitted entry is `false`. */
+        readonly excludeFrom?: IRichMeta.ExcludeFrom;
+        /** Where the property's data comes from and under what license. */
+        readonly attribution?: readonly IRichMeta.Attribution[];
+        /** A kind's card. */
+        readonly card?: IRichMeta.Card;
+        /** A kind's icon, by name. */
+        readonly icon?: string;
+        /** Who provides a kind's data. */
+        readonly provider?: IRichMeta.Provider;
+    }
+
+    export namespace IRichMeta {
+        /** Where a property is not offered. */
+        interface ExcludeFrom {
+            /** Not shown on the card. */
+            readonly cardView?: boolean;
+            /** Not offered after `A1.` in a formula. */
+            readonly dotNotation?: boolean;
+            /** Not offered by formula autocomplete. */
+            readonly autoComplete?: boolean;
+            /** A change to the property is not a change to the value. */
+            readonly calcCompare?: boolean;
+        }
+        /** One source of a property's data. */
+        interface Attribution {
+            readonly sourceText?: string;
+            readonly sourceAddress?: string;
+            readonly licenseText?: string;
+            readonly licenseAddress?: string;
+        }
+        /** A kind's card: which properties it shows, and how. */
+        interface Card {
+            /** The properties shown, in order. Omitted, the kind's order. */
+            readonly order?: readonly string[];
+            /** The property shown as the title. */
+            readonly title?: string;
+            /** The property shown under the title. */
+            readonly subTitle?: string;
+            /** The image property shown at the top. */
+            readonly mainImage?: string;
+        }
+        /** Who provides a kind's data. */
+        interface Provider {
+            readonly description?: string;
+            readonly logoSourceAddress?: string;
+            readonly logoTargetAddress?: string;
+        }
     }
 
     /**
@@ -31944,6 +32699,84 @@ declare global {
         } | readonly RunUpdate[] | string;
     }
 
+    /**
+     * The kind of a rich value: its class. A kind is a static set of typed property definitions, and
+     * every value of a kind shares the one `IRichType` its {@link IRichData.getKind} returns.
+     *
+     * @remarks
+     * For introspection: a renderer, a card, a formula editor offering `A1.` completions, or a
+     * function reading a field asks the value's kind which properties it has. What a value reads as
+     * where a primitive is consumed is the value's own answer ({@link IRichData.toPrimitive}).
+     */
+    export interface IRichType {
+        /**
+         * The kind's name: what a value's JSON names as its `type`.
+         */
+        getName(): string;
+        /**
+         * The name a UI shows for the kind, such as in a list of what can be inserted. The name when the
+         * kind has no label of its own.
+         */
+        getLabel(): string;
+        /**
+         * The kind's properties, in the order the kind declares them.
+         */
+        getProperties(): readonly IRichType.Property[];
+        /**
+         * The property `name`, or `null` when the kind has none by that name.
+         */
+        getProperty(name: string): IRichType.Property | null;
+        /**
+         * The property whose value is the text a cell shows for a value of this kind, or `null` when
+         * the kind shows none (an image).
+         */
+        getDisplayProperty(): string | null;
+        /**
+         * The kind's own presentation (a card, an icon, a provider), or `null` for none.
+         */
+        getMeta(): IRichMeta | null;
+    }
+
+    export namespace IRichType {
+        /**
+         * What a property holds.
+         *
+         * @remarks
+         * `rich` is another rich value (a capital city, an image); `array` is an array value; `resource`
+         * is a workbook resource such as a picture's bytes.
+         */
+        type ValueType = 'number' | 'integer' | 'string' | 'boolean' | 'error' | 'rich' | 'array' | 'resource';
+        /**
+         * One property a kind declares.
+         */
+        interface Property {
+            /** The property's name. */
+            readonly name: string;
+            /** What it holds. */
+            readonly valueType: ValueType;
+            /** What it reads as on a value that holds none. Omitted, `null`. */
+            readonly defaultValue?: Scalar;
+            /** How the property shows, unless a value says otherwise. */
+            readonly meta?: IRichMeta;
+        }
+        /**
+         * A kind saved with the workbook whose values name it: one that is not registered in code, such
+         * as a kind read from a file.
+         */
+        interface JSON {
+            /** {@inheritDoc IRichType.getName} */
+            name: string;
+            /** {@inheritDoc IRichType.getLabel} */
+            label?: string;
+            /** {@inheritDoc IRichType.getProperties} */
+            properties?: readonly Property[];
+            /** {@inheritDoc IRichType.getDisplayProperty} */
+            displayProperty?: string | null;
+            /** {@inheritDoc IRichType.getMeta} */
+            meta?: IRichMeta;
+        }
+    }
+
     /**
      * Describes the host environment the calculation engine is running in.
      *
@@ -39082,6 +39915,34 @@ declare global {
          * Returns the current shared resources.
          */
         getResources(): IResourceCollection;
+        /**
+         * The fetcher the workbook reaches outside itself with: the handlers per URL scheme a host
+         * registered, given as {@link IWorkbook.ConstructorOptions.fetcher}.
+         */
+        getFetcher(): IFetcher;
+        /**
+         * Fetches as the workbook does, with the standard `fetch` signature: what `IMAGE`, a web
+         * service function, and a renderer drawing a picture use.
+         *
+         * @remarks
+         * A resource with a `fetchedFrom` is the workbook's copy of that URL, and answers a fetch of it
+         * without a request. Anything else goes to {@link getFetcher}. The fetch saves nothing itself: a
+         * successful answer to a plain GET that is not a picture is cached until the workbook closes and
+         * answers later fetches of that URL. A response whose bytes are a picture says what they are,
+         * whatever the server called them. Plain GETs of one URL in flight together share one request;
+         * aborting one caller's signal does not stop it for the others. `cache: 'reload'` skips all of
+         * these and asks the source.
+         *
+         * The workbook saves a resource while a value holds it: `IMAGE` adds the picture it fetched for
+         * its values. A picture of the host's own goes in a cell the same way, under a URL the host mints:
+         *
+         * ```ts
+         * const source = `resource:${crypto.randomUUID()}`;
+         * const resource = workbook.getResources().add({ source: { buffer: bytes }, fetchedFrom: source });
+         * workbook.getRange('A1').setValue({ type: 'image', data: { source, resource } });
+         * ```
+         */
+        fetch(input: string, init?: RequestInit): Promise<Response>;
         /**
          * Returns the current shared resources.
          */
@@ -39705,6 +40566,10 @@ declare global {
             styles?: IStyleCollection.JSON;
             resources?: IResource.JSON[];
             strings?: string[];
+            /** The rich values cells name by id (`{ t: 'r', v: id }`). */
+            richData?: IRichDataCollection.JSON[];
+            /** The kinds {@link richData} names that are not registered in code (a kind read from a file). */
+            richTypes?: IRichType.JSON[];
             /**
              * The people the workbook knows.
              *
@@ -39825,6 +40690,11 @@ declare global {
              * A theme for the workbook.
              */
             theme?: ITheme;
+            /**
+             * How the workbook reaches outside itself: the handlers per URL scheme, with the host's
+             * authentication. Omitted, a {@link Fetcher} for `http:` and `https:`.
+             */
+            fetcher?: IFetcher;
             /**
              * Load from JSON.
              */
@@ -41796,6 +42666,14 @@ declare global {
          * {@link IWorksheetProtection.isLocked} is true.
          */
         getProtectedRanges(): IProtectedRangeCollection;
+        /**
+         * Returns the cell controls on this sheet, such as checkboxes.
+         *
+         * @remarks
+         * Every entry, in drawing order. To put a control on cells or read what is there, use
+         * {@link ICellRange.setControl} and {@link ICellRange.getControls}.
+         */
+        getCellControls(): ICellControlCollection;
         /**
          * Returns the comments and notes on this sheet.
          *
@@ -42253,14 +43131,6 @@ declare global {
          * workbook's {@link IWorkbook.getPivotTables} walks every sheet's.
          */
         getPivotTables(): IPivotTableCollection;
-        /**
-         * Returns the what-if data tables on this sheet, in the order they were read.
-         *
-         * @remarks
-         * Read-only for now: each table is carried as it was read, its results as the file held them.
-         * As in Excel, an edit to part of a table's results is refused.
-         */
-        getDataTables(): IDataTableCollection;
         /**
          * Set the picture interface for the entire sheet.
          * @param picture The picture interface to set for the sheet, or null to remove it.
@@ -42553,6 +43423,13 @@ declare global {
              * Always accompanied by the coarse {@link onProtectionChange}.
              */
             onProtectedRangesChange?(source: IWorksheet): void;
+            /**
+             * Called when a cell control is added, removed, re-anchored or reordered.
+             *
+             * @remarks
+             * Always accompanied by the coarse {@link onStyleChange}: a control is a format.
+             */
+            onCellControlsChange?(source: IWorksheet): void;
             /**
              * Called when a comment is added, removed, edited, resolved, replied to or re-anchored.
              *
@@ -42917,7 +43794,7 @@ declare global {
          * JSON representation of an `IWorksheet` used for serialization and deserialization.
          */
         interface JSON extends ISheet.JSON {
-            data?: Tuple.GridTuple<ICell.JSON>;
+            data?: Tuple.GridTuple<Scalar.JSON>;
             formulas?: IRange.JSONReferenceTuple<string>[];
             /**
              * The extent occupied by an array formula, and which of the three
@@ -42954,6 +43831,10 @@ declare global {
             styles?: IStyleCollection.JSON;
             resources?: IResource.JSON[];
             strings?: string[];
+            /** The rich values cells name by id (`{ t: 'r', v: id }`), when the sheet owns its own. */
+            richData?: IRichDataCollection.JSON[];
+            /** The kinds {@link richData} names that are not registered in code (a kind read from a file). */
+            richTypes?: IRichType.JSON[];
             /**
              * Modules owned by this sheet, keyed by module name.
              *
@@ -42995,6 +43876,7 @@ declare global {
              */
             validationSettings?: IDataValidationCollection.Settings;
             protectedRanges?: IRange.JSONReference<IProtectedRange.JSON>[];
+            cellControls?: IRange.JSONReference<ICellControl.JSON>[];
             movables?: IMovable.JSON[];
             /**
              * The sheet's VBA code name. Absent when it has none.
@@ -43052,12 +43934,6 @@ declare global {
              * @see {@link IWorksheet.getPivotTables}
              */
             pivotTables?: IPivotTable.JSON[];
-            /**
-             * The sheet's what-if data tables.
-             *
-             * @see {@link IWorksheet.getDataTables}
-             */
-            dataTables?: IDataTable.JSON[];
             /**
              * The cells where Excel's error checks are ignored (the green triangle's **Ignore Error**):
              * each reference's value is the set of checks its cells ignore.
@@ -46229,9 +47105,12 @@ declare global {
         chartEx?: boolean;
         /** The chart's own text font: what text with no font of its own is drawn in. */
         font: ResolvedChart.Font;
-        /** `cornerRadius` in points: 0 for square corners. */
+        /**
+         * `fill` is `undefined` where the chart states none: it is drawn in the background of where it is
+         * drawn. `cornerRadius` in points: 0 for square corners.
+         */
         chartArea: {
-            fill: IFill.JSON | null;
+            fill: IFill.JSON | null | undefined;
             border: ResolvedChart.Stroke | null;
             cornerRadius: number;
         };
@@ -46838,7 +47717,7 @@ declare global {
     }
 
     /**
-     * The kinds of rich data a cell can hold, by name.
+     * The kinds of rich data a cell can hold, by type.
      *
      * @remarks
      * A value is made from its JSON by looking its `type` up here; what a value reads as where a
@@ -46849,27 +47728,54 @@ declare global {
      */
     export namespace RichDataRegistry {
         /**
-         * Registers a kind. A kind registered again under the same name replaces the earlier one.
+         * Registers a kind. A kind registered again under the same name replaces the earlier one,
+         * a built-in included.
          */
         function register(kind: IRichDataKind<any>): void;
-        /** The kind registered as `name`, or `null`. */
-        function get(name: string): IRichDataKind | null;
-        /** The kind of `value`, or `null` when its type is not registered. */
+        /**
+         * The kind named `type`: registered, or defined ({@link RichRecord.defineKind}); `null` when
+         * there is none.
+         */
+        function get(type: string): IRichDataKind | null;
+        /** The kind of `value`, registered or defined, or `null` when it is neither. */
         function kindOf(value: IRichData): IRichDataKind | null;
-        /** The registered names. */
-        function getNames(): string[];
+        /** The names of the registered kinds. */
+        function getTypes(): string[];
         /**
          * A value from its JSON: the registered kind's, or an {@link Unmodeled} one carrying the JSON.
+         *
+         * @param ctx What the value is made for; omitted, a value made outside any workbook.
          */
-        function fromJSON(json: IRichData.JSON): IRichData;
+        function fromJSON(json: IRichData.JSON, ctx?: IRichDataKind.Context): IRichData;
+        /**
+         * Whether `value` is the JSON of a rich value (`{ type, data? }`), as `setValue` accepts it
+         * in place of the value.
+         */
+        function isJSON(value: unknown): value is IRichData.JSON;
         /**
          * What `value` reads as where a primitive is consumed ({@link IRichData.toPrimitive}), or
          * `undefined` when it reads as nothing.
          */
-        function toPrimitive(value: IRichData): number | string | boolean | undefined;
+        function toPrimitive(value: IRichData): Exclude<Scalar, IRichData | null> | undefined;
         /**
-         * The `ScalarType` of what `value` reads as: `String`, `Number` or `Boolean` for a kind with a
-         * primitive, `RichData` otherwise.
+         * The text `value` shows in a cell when it reads as no primitive: the value of its kind's
+         * display property ({@link IRichType.getDisplayProperty}), or `null` when the kind names none or
+         * the value holds no text there.
+         *
+         * @remarks
+         * Display only: the value still reads as nothing to calculation.
+         */
+        function toDisplayText(value: IRichData): string | null;
+        /**
+         * The `ScalarType` `value` lays out as in a cell: its primitive's when it has one (a hyperlink
+         * named by a number is a number); `String` when it reads as nothing but shows text (an entity's
+         * display string), so it aligns left and spills into empty neighbors; `RichData` when it shows
+         * no text (a picture).
+         */
+        function layoutTypeOf(value: IRichData): ScalarType;
+        /**
+         * The `ScalarType` of what `value` reads as: `String`, `Number`, `Boolean` or `Error` for a
+         * kind with a primitive, `RichData` otherwise.
          */
         function primitiveTypeOf(value: IRichData): ScalarType;
         /**
@@ -46878,12 +47784,16 @@ declare global {
          */
         function toArray(value: IRichData): Scalar[][] | null;
         /**
-         * A value whose type nobody has registered: it carries its JSON as it was read and reads as
+         * A value whose kind nobody has registered: it carries its JSON as it was read and reads as
          * nothing, so a workbook that holds one saves it unchanged.
+         *
+         * @remarks
+         * Its kind is made from what it holds: named by its JSON's `type`, with a property for each
+         * entry of its data.
          */
         class Unmodeled implements IRichData {
             constructor(json: IRichData.JSON);
-            getType(): string;
+            getKind(): IRichType;
             getProperty(name: string): Scalar;
             toString(): string;
             toJSON(): IRichData.JSON;
@@ -46991,6 +47901,33 @@ declare global {
          * truncation, not rounding: `1234567890.123456789` stores `…345`, never `…346`.
          */
         function truncateNumberText(text: string): string;
+        /**
+         * Encodings of `ScalarType` for persistence.
+         */
+        type JSONType = 'n' | 's' | 'b' | 'e' | 'r' | 'z';
+        /**
+         * A value encoded as a number with an associated type.
+         */
+        interface JSONTypedValue {
+            t: JSONType;
+            /**
+             * 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;
+        }
+        /**
+         * JSON values whose type is implied by their JavaScript type.
+         *
+         * @remarks
+         * What a string means is up to the container: a worksheet stores the id of the string in its
+         * strings collection, while an external link cache stores the string itself.
+         */
+        type JSONUnTypedValue = number | boolean | string;
+        /**
+         * For persisting a single scalar value and its type.
+         */
+        type JSON = JSONUnTypedValue | JSONTypedValue;
     }
 
     /**