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

package/types/scripting.d.ts

@@ -51,11 +51,11 @@ declare global {
      * if (range.hasError()) return range.firstError();
      * ```
      *
-     * placed before its own validation where Excel's error outranks it (`LARGE(range-with-#N/A, 0)`
+     * placed before its own validation where the member's error outranks it (`LARGE(range-with-#N/A, 0)`
      * is `#N/A`, not `#NUM!`). Aggregators and consumers say it; reshapers and lookups, whose members
      * pass through or are never read, need no line at all. Where a function takes several ranges the
      * lines run in ARGUMENT order — the whole of argument N before N+1, row-major within — which is
-     * Excel's which-error-wins order, and a function that pairs its ranges (the paired
+     * the which-error-wins order, and a function that pairs its ranges (the paired
      * statistics) orders its own scan the way it pairs.
      *
      * > *A bare error propagates unless your function opts in to seeing it; the members of a range
@@ -918,8 +918,8 @@ declare global {
      * asks each group's kind for the group: where its bars, points, slices or whatever it draws go.
      *
      * @beta The context a kind is given speaks the layout's frame units today: points from the frame's
-     * origin, as the layout works in them (DESIGN-CHART §4), with `at` and `px` to convert. It will
-     * speak px, as {@link ChartLayout} does, before the contract is settled.
+     * origin, as the layout works in them, with `at` and `px` to convert. This may change to px, as
+     * {@link ChartLayout} uses, while the API is in beta.
      *
      * `coordinates` says what the chrome lays out for the kind: `cartesian`, a pair of axes
      * (category and value, or a scatter's two value axes) whose scales are fit to what
@@ -1081,7 +1081,7 @@ declare global {
             xOfValue(scale: ValueScale, axis: ResolvedChart.Axis, value: number): number;
             /** The series layout every kind states: id, name, values, slots, fill, stroke and trendlines. */
             base(series: ResolvedChart.Series): Omit<ChartLayout.SeriesLayout, 'marker'>;
-            /** A line or area group's up/down bars, high-low lines and drop lines (DESIGN-CHART §4.7). */
+            /** A line or area group's up/down bars, high-low lines and drop lines. */
             analysisLines(scale: ValueScale, tops: (number | null)[][], baseValue: number): Pick<ChartLayout.LineGroupLayout, 'upDownBars' | 'hiLowLines' | 'dropLines'>;
             /** Lines in the frame cut to the plot, in px. */
             segments(lines: Pt[][]): ChartLayout.Segment[];
@@ -1124,7 +1124,7 @@ declare global {
      * The kinds of chart group, by group type: the built-ins, and any a host registers.
      *
      * @remarks
-     * The built-in kinds register when the chart module loads (with the first chart, DESIGN-CHART §7),
+     * The built-in kinds register when the chart module loads (with the first chart),
      * so before that {@link get} answers `undefined` for `'bar'`; a host's kind registered under a
      * built-in type keeps its place when they do. A registration is a call, never a side effect of an
      * import: the package declares no side effects, so a bundler drops a module imported only for one.
@@ -2708,30 +2708,6 @@ declare global {
         }
     }
 
-    /**
-     * Stacked cell-text layout — Excel's "Vertical Text" (`textRotation="255"`).
-     *
-     * Stacked text is not rotated. Every glyph stays upright and occupies one SLOT of the font's line
-     * pitch, glyphs advancing downward in a column. Measured against Excel (hidden-COM probes, see
-     * `VERTICAL-TEXT-PLAN.md`):
-     *
-     * 1. Columns come from explicit line breaks — one column per line, left → right in reading order —
-     *    and, when the cell wraps, from breaking a column that would exceed the content height: greedy
-     *    at spaces (the space at a break is consumed), per glyph inside a word longer than the capacity.
-     *    It is the horizontal wrap rule transposed. An unwrapped cell keeps one column; a line break
-     *    there is a blank slot.
-     * 2. Leading and trailing spaces of a column are measured but never painted (see
-     *    {@link layoutColumns}); inner spaces are blank slots.
-     * 3. Each column is aligned on its own by the vertical alignment (Top / Center / Bottom; Justify
-     *    and Distributed behave as Top and Center — nothing is spread). The horizontal alignment places
-     *    the group of columns; the caller resolves General (Excel centers it). Columns are one pitch
-     *    wide and glyphs center in them.
-     * 4. Nothing overflows: the footprint clips to the cell on both axes.
-     *
-     * All output is pure geometry, renderer-agnostic: a DOM renderer maps each column to a box of
-     * `pitch` line-height with one glyph per line; a canvas renderer paints each glyph centered in
-     * its slot.
-     */
     /**
      * One stacked column.
      */
@@ -2765,7 +2741,7 @@ declare global {
      * as `IModule.JSON` in the SDK. Produced by `ScriptCompiler.compile` (Node, which returns
      * it inside a {@link CompileResult} alongside diagnostics) and executed compiler-free via
      * `loadCompiledModule`. Compile diagnostics are NOT part of this artifact — they live on
-     * {@link CompileResult}. See `private-assets/design/SXLM-FORMAT.md` for the normative reference.
+     * {@link CompileResult}.
      */
     export interface CompiledModule {
         /**
@@ -2985,7 +2961,7 @@ declare global {
      * of {@link IChart} works, `getLayout` lays it out at a size, and `@sheetxl/react`'s `ChartElement`
      * draws it. Its writes are not undoable: it has no transaction store.
      *
-     * The chart's code is loaded with the first chart, so this is asynchronous (DESIGN-CHART §7).
+     * The chart's code is loaded with the first chart, so this is asynchronous.
      */
     export function createChart(json: IChart.JSON, options?: CreateChartOptions): Promise<IChart>;
 
@@ -3343,7 +3319,7 @@ declare global {
      *
      * @remarks
      * This is the form Excel's own formula bar shows for a book it cannot see, which is the state every
-     * book is in until a resolver opens one (DESIGN-EXTERNAL-LINKS §4B). The caller quotes it —
+     * book is in until a resolver opens one. The caller quotes it —
      * `sheetNameToString` does, since a path carries separators no sheet name may.
      *
      * The directory is the first source that carries one: a book Excel recorded by a RELATIVE path
@@ -3509,8 +3485,8 @@ declare global {
      * Both are the same mechanism at different granularity — the marshaller picks the unit from the
      * element type — and a blank drops out of either. The scalar case is the common one; the range case
      * exists because a reference UNION is a single argument holding several areas: a parameter that does
-     * not declare `Flatten` refuses one outright (`#VALUE!` — `TRANSPOSE((A1:A3,C1:C3))` in Excel), and a
-     * body that declares it answers for the union itself, in one line, the way Excel's own do:
+     * not declare `Flatten` refuses one outright (`#VALUE!` — `TRANSPOSE((A1:A3,C1:C3))`), and a
+     * body that declares it answers for the union itself, in one line, the way the built-ins do:
      * `AREAS` counts the areas, `SUM` adds them, `ROWS` answers `#REF!` to more than one, the lookups
      * `#N/A`.
      *
@@ -3669,7 +3645,7 @@ declare global {
      *
      *  SpillErrorScalarSubType | "Unknown" | "Collision" | "IndeterminateSize" | "WorksheetEdge" | "OutOfMemoryWhileCalc" | "Table" | "MergedCell"
      * # Office 2023
-     * 10. #CONNECT! This occurs when a data type is used that is not currently supported in this version of Excel.
+     * 10. #CONNECT! This occurs when a data type is used that is not currently supported.
      * 11. #BLOCKED! Indicates that an action or feature is blocked, possibly due to security settings, protected view, or other restrictions. Often related to online features, external links, or macros.
      * 12. #UNKNOWN! May be returned in the case of a protected workbook.
      * 13. #FIELD! Invalid field name for a data type.
@@ -6881,6 +6857,11 @@ declare global {
         isTopLeft(): boolean;
         /**
          * Returns the range of the cell if it is a spill cell.
+         *
+         * @remarks
+         * For a blocked spill (a {@link getSpillKind | kind} of `error`, the anchor shows `#SPILL!`) this
+         * is the range it would take. It holds none of those cells: their values are whatever is in the
+         * way. Spills can overlap, and one that is not blocked is returned ahead of one that is.
          */
         getSpill(): ICellRange | null;
         /**
@@ -7560,26 +7541,11 @@ declare global {
          * cell with none authored has the Normal style's. `majority` and `of` are evidence, not a
          * gate: a convention held by 3 of 5 cells is reported as such.
          *
-         * **Rank** says which finding to read first. It is not a confidence. For a run finding it is
-         * `weight × (1 / thickness) × (flanks / max(2, thickness)) × (1 − corroboration)`, where
-         * `weight` is the layer's and `corroboration` is the weight of the corroborating layers over the
-         * weight of every layer that could have corroborated. The layer weights are formula shape `1`,
-         * kind `0.6`, number format `0.5`, formula or typed value `0.4`, font `0.3`, fill `0.1`,
-         * alignment `0.05`. Every other check ranks at a fixed weight: `repeatedReference` and
-         * `lookupShape` `1`, `approximateMatch` and `externalReference` `0.9`, `formulaRange` and
-         * `degenerateCall` `0.8`, `emptyCellReference` and `sumIncludesSubtotal` `0.6`,
-         * `keyLabelMismatch` and `linkLabelMismatch` `0.4`, `unlockedFormula` and `signVsSiblings` `0.1`,
-         * `numberStoredAsText` `0.05`. A `styleRole` finding ranks at the role's weight (`link` `0.6`,
-         * `reference` `0.4`, `input` `0.3`, `computed` `0.2`) times `majority / of`. A
-         * `misalignedReference` finding ranks at `0.8` times its target's share: `lineItem` `1`,
-         * `outsideBlocks` `0.5`, `closingRow` and `absolute` `0.25`.
-         *
-         * A run or `styleRole` finding's rank is then divided by the number of times the same finding
-         * (the same check and evidence) occurs in the workbook: a finding repeated across a model is the
-         * author's style, and the one that occurs once is the exception to read first. So a finding's
-         * rank can change when another sheet changes. The weights are measured on the SpreadsheetBench
-         * v2 Debugging goldens and move as other measurements arrive. Regions of the `anomalies` feature
-         * list highest rank first, and so do a cell's findings, in check order within an equal rank.
+         * **Rank** says which finding to read first. It is not a confidence, and it is relative to the
+         * workbook: a finding repeated across a model is the author's style, and the one that occurs
+         * once is the exception to read first. So a finding's rank can change when another sheet
+         * changes. Regions of the `anomalies` feature list highest rank first, and so do a cell's
+         * findings, in check order within an equal rank.
          *
          * **Literals and twins.** `literalMatchesInput` reads the numbers typed into a formula against
          * the typed numbers no formula reads: a reference replaced by its value is what left the input
@@ -7589,16 +7555,12 @@ declare global {
          * when both are a calendar period, a power of ten or a small count. Every side of a divergence is
          * listed, since two wrong rows can outvote the right one.
          *
-         * `literalMatchesInput` ranks at `0.8 / matches`. A `twinBlockDivergence` finding ranks at `0.8`
-         * times the share of the twins on the other side, `twins / (twins + this side's count)`, halved
-         * for a sign: signs differ between line items by design, so a sign divergence is read when asked
-         * for by check. `scaleOutlier` ranks at `0.8`.
+         * A sign divergence ranks low: signs differ between line items by design, so it is read when
+         * asked for by check.
          *
          * `constantFrequency` reports every constant a formula types, the common ones too, with how many
-         * places in the workbook type it (`uses`) and of how many constant uses (`of`). It ranks at
-         * `0.1 / uses × of / (of + 10)`: the rarer the constant, the higher, and a constant on a workbook
-         * that types few has little to be rare against. A finding's `uses` and `of` change when another
-         * sheet changes.
+         * places in the workbook type it (`uses`) and of how many constant uses (`of`). The rarer the
+         * constant, the higher it ranks. A finding's `uses` and `of` change when another sheet changes.
          *
          * A label's position is absolute (`R12C3`), since it stays put whichever cell of a region reads
          * it; its text is the one read at the region's first cell.
@@ -9377,7 +9339,7 @@ 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.
+         * // Or name the kind of defect and let the ranking decide.
          * sheet.getAnomalies({ focus: 'unitMismatch', limit: 25 });
          * ```
          *
@@ -9983,10 +9945,13 @@ declare global {
          *
          * This method is a more scalable alternative to `getValues` or `getCells` for large or sparse ranges,
          * as it:
-         * 1. Skips empty values by default.
+         * 1. Skips empty values by default, however much of the range is styled.
          * 2. Avoids creating large arrays.
          * 3. Allows for early termination.
-      
+         *
+         * To reach blank cells that have a feature, such as a fill or a hyperlink, name it in
+         * {@link ICellRange.IteratorOptions.features}.
+         *
          * @param callback A function that will be called for each non-empty cell in the range. The callback receives:
          *   - `value`: The `Scalar` at the current cell.
          *   - `context`: A `IteratorContext` object providing additional information and utilities for the cell.
@@ -10750,8 +10715,8 @@ declare global {
              *
              * @remarks
              * The same lens {@link ICellRange.getCounts} and {@link ICellRange.getRegions} take, and it
-             * costs no extra scan: the range is split at the hidden runs first (off the header run
-             * structure, no per-cell probe) and the resulting pieces are measured as ONE population.
+             * costs no extra scan: the range is split at the hidden runs first and the resulting pieces
+             * are measured as ONE population.
              *
              * Optionally an {@link IRange.Axis} to skip on one axis only.
              */
@@ -11291,7 +11256,8 @@ declare global {
              */
             readonly Role: "role";
             /**
-             * Direct date-category number format — `yyyy-mm-dd`, `mm/dd/yyyy`, and the like.
+             * A date-category number format, given directly or by a named style — `yyyy-mm-dd`,
+             * `mm/dd/yyyy`, and the like.
              *
              * @remarks
              * A formatting predicate, not a value kind: a blank cell or a text cell formatted this way
@@ -11335,7 +11301,11 @@ declare global {
             readonly Fill: "fill";
             /** Direct borders. */
             readonly Borders: "borders";
-            /** Direct number format. Region payloads carry the format string and its category. */
+            /**
+             * A number format given directly or by a named style, not one left at Normal's. Region payloads
+             * carry the format string and its category, so a block with `0%` set directly and one with the
+             * `Percent` style are one region.
+             */
             readonly NumberFormat: "numberFormat";
             /** Direct alignment. */
             readonly Alignment: "alignment";
@@ -11352,7 +11322,7 @@ declare global {
             readonly Table: "table";
             /** Auto-table membership. */
             readonly AutoTable: "autoTable";
-            /** Has a hyperlink. */
+            /** Has a hyperlink. Regions group by what the link says, so the same link set twice is one region. */
             readonly Hyperlink: "hyperlink";
             /**
              * Ignores one or more of Excel's error checks. Regions group by the set of checks ignored.
@@ -11506,8 +11476,8 @@ declare global {
             checks?: readonly ICell.ErrorCheck[];
             /**
              * The kind of defect being looked for, or several: regions are ordered by how often findings
-             * like theirs have been that kind of defect, measured on audited models, and by rank where
-             * that is equal. With `checks` too, the named checks still list first and `focus` orders
+             * like theirs have been that kind of defect in audited models, and by rank where that is
+             * equal. With `checks` too, the named checks still list first and `focus` orders
              * within each. An unknown name throws.
              *
              * @defaultValue none — by rank
@@ -11603,9 +11573,12 @@ declare global {
             /**
              * The features the iteration resolves and visits.
              *
-             * @defaultValue all features
+             * @defaultValue all features are resolved, and only the cells with values are visited
              *
              * @remarks
+             * Naming a feature also visits the blank cells that have it: `features: 'hyperlink'` reaches a
+             * link on an empty cell, and `features: 'fill'` every cell of a filled column.
+             *
              * Two effects, both wins for a caller that does not need everything:
              * - The iterator only materializes the requested features' state onto the context — an
              *   excluded feature is never even looked up.
@@ -12565,6 +12538,10 @@ declare global {
         /**
          * Measure the text using the styling properties
          *
+         * @remarks
+         * The vertical metrics are a cell's line: `lineHeight` is the height of a row sized to one
+         * line of this text, which leaves room around the font's ascent and descent as Excel does.
+         *
          * @param text The text to measure.
          * @param size Size @defaultValue 'to the cell font.size'
          * @param family Family @defaultValue 'to the cell font.family'
@@ -17223,8 +17200,8 @@ declare global {
             /**
              * The text a cell SHOWS: under a filter the displayed text, so `$1` is a cell holding 1 under
              * `$0`; under a format or a validation, where nothing is shown at evaluation, the value's own
-             * text. Type text. Excel's filter `equal` and its values list compare this way
-             * (DESIGN-FILTER §3.2, MODEL-CONDITIONS §4); `equalTo` under no selector is value equality.
+             * text. Type text. Excel's filter `equal` and its values list compare this way;
+             * `equalTo` under no selector is value equality.
              */
             readonly Display: "display";
             readonly Number: "number";
@@ -19997,8 +19974,7 @@ declare global {
      *
      * @remarks
      * Excel's external link is not a live reference — it is the cache plus enough to go re-fetch the
-     * source. See the design doc for the full model:
-     * `private-assets/design/calc/DESIGN-EXTERNAL-LINKS.md`.
+     * source.
      *
      * Two members read as "which book is this", and they answer different questions:
      *
@@ -20058,8 +20034,8 @@ declare global {
          *
          * @remarks
          * **Sparse.** A cell the cache does not hold — and a sheet it holds nothing for — reads as a
-         * BLANK cell, which is what Excel computes with the source closed (design doc §6 items 1/2).
-         * Values only — no format, no style, no comment; a cached date is a plain serial (§2.5).
+         * BLANK cell, which is what Excel computes with the source closed. Values only — no format, no
+         * style, no comment; a cached date is a plain serial.
          *
          * @param sheetIndex Position in {@link getSheetNames}, matching the XML's `sheetId` (0-based).
          */
@@ -20081,8 +20057,8 @@ declare global {
          * (`[Budget.xlsx]Sheet1`) once a resolver holds it.
          *
          * @remarks
-         * A readout of the book's state, not a preference — see DESIGN-EXTERNAL-LINKS §4B. Until phase E
-         * there is no resolver, so this is always the closed form. The caller quotes it.
+         * A readout of the book's state, not a preference: without a resolver this is always the closed
+         * form. The caller quotes it.
          *
          * @param sheetName Omitted for the book-scoped `[1]!Name` form.
          */
@@ -20127,8 +20103,8 @@ declare global {
          * @remarks
          * Needs a resolver (`ICellContainerOptions.externalBookResolver`, given when the workbook is
          * built); without one every book is `'unavailable'` and nothing changes, which is the state a
-         * workbook is in until a host supplies one (DESIGN-EXTERNAL-LINKS §4D). A replaced cache is one undoable step, and every formula
-         * citing the book reads the new values. A resolver that throws leaves the cache as it was and
+         * workbook is in until a host supplies one. A replaced cache is one undoable step, and every
+         * formula citing the book reads the new values. A resolver that throws leaves the cache as it was and
          * marks each cached sheet `refreshError`, as Excel records a refresh it could not complete.
          */
         refresh(): Promise<IExternalBook.RefreshResult>;
@@ -20158,8 +20134,8 @@ declare global {
              * the book is opened from, `absoluteUrl` its 2021 cloud-URL companion.
              *
              * @remarks
-             * Not derivable from {@link type} — the two can carry the SAME relationship type (measured on
-             * task 40234, where a relative and an absolute `externalLinkPath` sit on one part). Absent for
+             * Not derivable from {@link type} — the two can carry the SAME relationship type (a relative
+             * and an absolute `externalLinkPath` can sit on one part). Absent for
              * an entry nothing points at, which is a real shape too: an `xlPathMissing` or
              * `externalLinkLongPath` rel rides along on the part without being referenced from it.
              */
@@ -20198,10 +20174,10 @@ declare global {
          * Opens a book's source and answers its current contents, or declines.
          *
          * @remarks
-         * DESIGN-EXTERNAL-LINKS §4D: the default one (phase E) is `WorkbookIO.read` with
+         * A resolver for a workbook file should read it with `WorkbookIO.read` and
          * `calcOnLoad: 'none'`, taking the source's own cached values and never evaluating it — that is
-         * what Excel's cache holds, and it keeps A-cites-B-cites-C from becoming a crawl. An extension
-         * point for a source that is not a workbook file. WHETHER a source may be opened at all — an
+         * what Excel's cache holds, and it keeps A-cites-B-cites-C from becoming a crawl. A source that
+         * is not a workbook file can be resolved too. WHETHER a source may be opened at all — an
          * untrusted file naming an arbitrary path or URL — is the host's decision, made before this is
          * asked; a resolver never fetches on its own initiative, only on {@link IExternalBook.refresh}.
          */
@@ -20219,7 +20195,7 @@ declare global {
             /**
              * 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).
+             * values-only cache).
              */
             data: Tuple.GridTuple<Scalar.JSON>;
         }
@@ -20361,7 +20337,8 @@ declare global {
          * 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` does for a URL it cannot reach. In a browser the default handlers reject with a
+         * `FormulaError.Blocked` when the site responded but does not allow web pages to read it.
          */
         fetch(input: string, init?: RequestInit): Promise<Response>;
         /**
@@ -21502,9 +21479,8 @@ declare global {
             readonly strikeThickness?: number;
             readonly italicAngle?: number;
             /**
-             * The line pitch in px — what a line of this font advances by, and the height of a row sized
-             * to it: `ascent + descent + 2` (Excel's standard row height for the font; the 2 is the
-             * gridline gutter above and below the font box). Includes {@link lineGap}.
+             * The line pitch in px — what a line of this text advances by: {@link ascent} plus
+             * {@link descent} plus {@link lineGap}.
              */
             readonly lineHeight: number;
             /**
@@ -21512,6 +21488,7 @@ declare global {
              * paints the line as a box (a CSS line box) puts the alphabetic baseline.
              */
             readonly baseline: number;
+            /** The leading in px: the room in {@link lineHeight} beyond the ascent and descent. */
             readonly lineGap: number;
             /**
              * The font's ascent above the baseline in whole px at the measured size — GDI's `tmAscent`,
@@ -21527,9 +21504,8 @@ declare global {
          *
          * @remarks
          * Advances are per em and vertical metrics follow GDI, so a table measures as Excel does: a
-         * shipped face measures GDI's hinted whole pixels and sizes rows as Excel autofits them. Tables
-         * are built by the collection from the shipped files or the platform; they are read here, never
-         * made or changed.
+         * shipped face measures GDI's hinted whole pixels. Tables are built by the collection from the
+         * shipped files or the platform; they are read here, never made or changed.
          */
         interface AdvanceTable {
             /** The family the table measures, as a style names it. */
@@ -21539,8 +21515,12 @@ declare global {
             readonly italic: boolean;
             /** Whether widths are GDI's hinted whole pixels. */
             readonly isHinted: boolean;
-            /** Whether row heights are Excel's own captured ones. */
-            readonly hasRows: boolean;
+            /**
+             * The height of a line per em by the font's typo metrics (ascent less descent plus line gap),
+             * for a font that asks for them; `null` otherwise. DirectWrite lays a line out this tall, so
+             * Excel's charts do.
+             */
+            readonly typoLine: number | null;
             /** The number of characters with an advance. */
             readonly size: number;
             /** The advance of `codepoint` per em, or `undefined` when the table has none. */
@@ -21552,7 +21532,10 @@ declare global {
              * super/subscript scale, then `letterSpacing` between characters.
              */
             width(text: string, px: number, options?: AdvanceTable.WidthOptions): number;
-            /** The face's whole-px vertical metrics at `px` pixels per em. */
+            /**
+             * The face's whole-px vertical metrics at `px` pixels per em: GDI's ascent and descent, and a
+             * line as tall as the font's own metrics ask.
+             */
             metrics(px: number): Metrics;
             /**
              * The underline at `px`: its center's offset above the baseline (negative below) and its
@@ -21681,6 +21664,23 @@ declare global {
          * ```
          */
         function captureTables(bytes: Uint8Array, options?: CaptureOptions): Promise<CapturedFace[]>;
+        /**
+         * The CSS `font-family` value that paints `family`: the family, then the fonts that stand in for
+         * it where it is not installed, then `fallbacks`, each followed by its own stand-ins.
+         *
+         * A stand-in is the family `family` is measured by and that family's open metric-compatible
+         * twins, so text painted on a machine without the original still fits its measurement.
+         *
+         * @param family The family as a style names it.
+         * @param fallbacks Families or CSS generic names to try after it.
+         *
+         * @example
+         * ```ts
+         * IFont.toCSSFontFamily('Calibri', ['sans-serif']); // 'Calibri, Carlito, sans-serif'
+         * IFont.toCSSFontFamily('Aptos Narrow', ['sans-serif']); // '"Aptos Narrow", "Intos Narrow", Calibri, Carlito, sans-serif'
+         * ```
+         */
+        function toCSSFontFamily(family: string, fallbacks?: readonly string[] | null): string;
         /**
          * Provides a font-family fallback based on the PANOSE hex string.
          *
@@ -22316,8 +22316,8 @@ declare global {
          * A union `(A1:A5,B1:B2)` reaches a {@link IFunction.ParameterTypeJSON.reportType} slot as one
          * `IRange` per area. Functions that answer over it do so because they walk MEMBERS and a union
          * simply has more of them — `LARGE((DA1:DA5,DK1:DK2),2)` is the second largest of all seven
-         * cells. This is that walk, and it is a helper rather than a marshalling step on purpose: Excel
-         * flattens in exactly the same place, a shared reducer its bodies opt into, which is why the
+         * cells. This is that walk, and it is a helper rather than a marshalling step on purpose:
+         * flattening is a shared reducer the bodies opt into, which is why the
          * same union is flattened by `LARGE`, refused by `SUMPRODUCT` and answered `#REF!` by `ROWS`.
          *
          * The result is a single column in area order, row-major within each area. SHAPE IS NOT
@@ -22366,7 +22366,7 @@ declare global {
          */
         getColumn(): number;
         /**
-         * Whether the call being evaluated is in Excel's VALUE mode, where a multi-cell reference at a
+         * Whether the call being evaluated is in VALUE mode, where a multi-cell reference at a
          * slot that reads ONE value is implicitly intersected with the formula's cell (the `@` rule);
          * `false` is ARRAY mode, where such a slot reads the reference's first cell.
          *
@@ -22405,7 +22405,7 @@ declare global {
          * A few arguments honor only their top-left corner and are re-sized to the shape of the range
          * that drives them — `SUMIF`'s `sum_range`, `LOOKUP`'s `result_vector`. The window can therefore
          * run off the bottom or right of the grid: `SUMIF(A1:A5,">0",A1048574)` asks for five rows
-         * starting three from the end. Excel reads the part that fits and treats the rest as blank, which
+         * starting three from the end. The part that fits is read and the rest is blank, which
          * is what this returns; positions past the clamp read as `undefined` from `getValueAt`.
          *
          * @param anchor The coords of the argument as written; only its top-left corner is honored.
@@ -22809,12 +22809,11 @@ declare global {
          *   want the raw carry above — `DATEDIF("2020-01-31","2020-03-01","md")` is `-1`
          *   because Jan 31 rolls into March. `EDATE`/`EOMONTH` want the opposite and CLAMP to
          *   the target month's length, so they pre-clamp before calling here. One conversion,
-         *   two opposite rules, both matching Excel. Baking either one in breaks the other.
+         *   two opposite rules. Baking either one in breaks the other.
          * * **Results may legitimately leave the calendar.** `YEARFRAC` basis 1 anchors a year
          *   length on January 1 of `laterYear + 1`, which at the top of the calendar is
-         *   `10000-01-01`; Excel answers `1.9972602739726026` for
-         *   `YEARFRAC(DATE(9998,1,1),DATE(9999,12,31),1)` rather than `#NUM!`. A range check
-         *   here would break it.
+         *   `10000-01-01`; `YEARFRAC(DATE(9998,1,1),DATE(9999,12,31),1)` is
+         *   `1.9972602739726026`, not `#NUM!`. A range check here would break it.
          * * **The 16-bit argument limits are per-function.** `DATE`'s month errors outside
          *   `[-32767, 32766]` while its day saturates to `32767`, and `TIME` errors outside
          *   `[0, 32767]` on every argument — same magic number, three different rules.
@@ -22822,8 +22821,8 @@ declare global {
          * Note the asymmetry with {@link getDateParts}, which DOES throw `#NUM!` outside the
          * calendar because it answers a user-facing question. An internal intermediate that
          * steps one day past the end must therefore not be round-tripped through it; compute
-         * on the fields instead. That mistake made `YEARFRAC(DATE(9999,1,1),DATE(9999,12,31),0)`
-         * `#NUM!` where Excel says `1`.
+         * on the fields instead, or `YEARFRAC(DATE(9999,1,1),DATE(9999,12,31),0)` becomes `#NUM!`
+         * rather than `1`.
          */
         getSerialDate(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millis?: number): number;
         /**
@@ -22839,8 +22838,8 @@ declare global {
          *
          * @remarks
          * Argument REFLECTION, for the one thing a declaration cannot say: what happened at *this* call.
-         * It exists to serve Excel's declared `any`, which means "no contract, the body decides" — every
-         * other Excel type maps onto a type we already have and the marshaller handles it.
+         * It exists to serve a declared `any`, which means "no contract, the body decides" — every
+         * other declared type maps onto a type we already have and the marshaller handles it.
          *
          * The returned view is valid ONLY while the body that asked for it is running. Views are pooled
          * by dispatch depth, so retaining one across an `await`, a callback, or a nested evaluation hands
@@ -22859,7 +22858,7 @@ declare global {
          * 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`).
+         * (`IDeferContext.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
@@ -22871,14 +22870,15 @@ declare global {
          * 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.
+         * The executor runs after the recalculation, outside any cell, so the ambient `FormulaContext`
+         * is not its own: it reads the workbook through `ctx.getFormulaContext()`. Whatever the body
+         * knows about its cell goes in the payload.
          *
          * @example
          * ```typescript
          * function fetchAll(
          *   calls: readonly IFormulaContext.DeferredCall<string>[],
-         *   ctx: IFormulaContext.IBatchContext
+         *   ctx: IFormulaContext.IDeferContext
          * ): void {
          *   for (const call of calls) {
          *     ctx.fetch(call.payload as string)
@@ -22933,7 +22933,7 @@ declare global {
              * then `range` is returned as it is, hidden rows included.
              *
              * @remarks
-             * This is `SUBTOTAL` 1-11 (Excel: they "include manually hidden rows", which is what an
+             * This is `SUBTOTAL` 1-11 (they include manually hidden rows, which is what an
              * unfiltered sheet reads as). `SUBTOTAL` 101-111 and `AGGREGATE` leave it off and skip
              * always.
              * @defaultValue false
@@ -23062,7 +23062,7 @@ declare global {
          * 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>;
+        type DeferExecutor<T = any> = (calls: readonly DeferredCall<T>[], ctx: IDeferContext) => void | Promise<void>;
         /**
          * One call made by {@link IFormulaContext.defer}, as its executor receives it.
          *
@@ -23074,7 +23074,7 @@ declare global {
             /** What the function passed to `defer`. */
             readonly payload: unknown;
             /** Settles the call with its result. */
-            resolve(value: T): void;
+            resolve(value: T, options?: DeferredCall.ResolveOptions): 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. */
@@ -23085,10 +23085,29 @@ declare global {
              */
             readonly cancelled: boolean;
         }
+        namespace DeferredCall {
+            /**
+             * Options for {@link DeferredCall.resolve}.
+             */
+            interface ResolveOptions {
+                /**
+                 * Whether the blanks of an array result stay blank when it spills. Omitted, they read as
+                 * `0`, as any spilled array's blanks do.
+                 *
+                 * @remarks
+                 * For data whose empty fields mean "nothing here", such as an imported file. The result
+                 * keeps them while a formula passes it on as it is (`IF(c, result, …)`). A function that
+                 * answers element by element builds a new array, whose blanks read as `0`
+                 * (`IFERROR(result, …)`, `result & ""`).
+                 * @defaultValue false
+                 */
+                keepBlanks?: boolean;
+            }
+        }
         /**
          * What an executor is given beside its calls.
          */
-        interface IBatchContext {
+        interface IDeferContext {
             /** A random number in `[0, 1)` from the calculation's source, which a test can seed. */
             getRandom(): number;
             /**
@@ -23096,6 +23115,35 @@ declare global {
              * here (maps, numbers, strings, buffers), not connections or sockets.
              */
             getState<S>(init: () => S): S;
+            /**
+             * Groups `calls` by payload and runs `answer` once per distinct payload with every call that
+             * asked it: one request per question, however many cells asked.
+             *
+             * @param calls The calls to group, usually every call the executor was handed.
+             * @param answer Settles one group. When it throws, or the promise it returns rejects, the
+             * group's calls it has not settled fail with that error; the other groups are not affected.
+             * @returns Resolves once every group has been answered. It never rejects.
+             *
+             * @remarks
+             * Payloads are equal as `defer` compares them: the same primitive, or plain objects or arrays
+             * whose own values are the same one level deep. Groups are answered concurrently, in the
+             * order their first call appears.
+             *
+             * @example
+             * ```typescript
+             * async function fetchQuotes(
+             *   calls: readonly IFormulaContext.DeferredCall<number>[],
+             *   ctx: IFormulaContext.IDeferContext
+             * ): Promise<void> {
+             *   await ctx.byPayload(calls, async (ticker: string, group) => {
+             *     const response = await ctx.fetch(`https://api.example.com/quote/${ticker}`);
+             *     const price: number = (await response.json()).price;
+             *     for (const call of group) call.resolve(price);
+             *   });
+             * }
+             * ```
+             */
+            byPayload<T = any, P = unknown>(calls: readonly DeferredCall<T>[], answer: (payload: P, group: readonly DeferredCall<T>[]) => void | Promise<void>): Promise<void>;
             /**
              * 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.
@@ -23116,8 +23164,44 @@ declare global {
              * 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.
+             *
+             * Rejects when the URL cannot be reached, with a `FormulaError.Blocked` when the site responded
+             * but the browser would not let the page read it.
              */
             fetch(input: string, init?: RequestInit): Promise<Response>;
+            /**
+             * The formula context of the workbook being calculated, with no cell: its parsing, text,
+             * comparison and dates, read with the workbook's locale and date system.
+             *
+             * @remarks
+             * Valid for as long as the executor runs, across every `await`. The ambient `FormulaContext`
+             * is not: it belongs to the cell being evaluated, and an executor runs after that evaluation
+             * ends. What needs a cell (`getRow`, `getReference`, `getValueAt`, `defer`, `markVolatile`,
+             * `formatResults`, `getRandom`) throws here; {@link getRandom} is the executor's own.
+             */
+            getFormulaContext(): IFormulaContext;
+            /**
+             * Reads delimited text (CSV, TSV) into rows of values, each field read the way the workbook
+             * reads typed entry: numbers, dates, booleans and error labels become values, anything else
+             * stays text, and an empty field is blank.
+             *
+             * @param text The delimited text.
+             * @param options How the text is split.
+             * @returns The rows, padded with blanks to the widest row.
+             */
+            parseText(text: string, options?: IDeferContext.ParseTextOptions): Promise<Scalar[][]>;
+        }
+        namespace IDeferContext {
+            /**
+             * Options for {@link IDeferContext.parseText}.
+             */
+            interface ParseTextOptions {
+                /**
+                 * The character between fields.
+                 * @defaultValue `','`
+                 */
+                delimiter?: string;
+            }
         }
     }
 
@@ -23425,7 +23509,7 @@ declare global {
              *
              * @remarks
              * STATIC, and read from the formula text at compile time: it is true of the call whether or
-             * not the call runs, which is what a lazy argument (and Excel) requires.
+             * not the call runs, which is what a lazy argument requires.
              *
              * @see {@link ReturnTypeJSON.volatile}
              */
@@ -23464,7 +23548,7 @@ declare global {
              * @remarks
              * Only meaningful for a VARIADIC function; a fixed parameter list is already its own maximum.
              * The number is the whole CALL's argument count, prefix and optional suffix included, and it
-             * is refused where Excel refuses it — at entry, before evaluation.
+             * is refused at entry, before evaluation.
              *
              * @see {@link Repeating}
              */
@@ -23766,8 +23850,8 @@ declare global {
              * Generated from the `NoLift<T>` marker.
              *
              * @remarks
-             * Per parameter, because Excel is: `NETWORKDAYS.INTL` refuses a reference at its date slots
-             * and lifts one at `weekend`. An ARRAY at the slot still lifts, a one-cell reference is an
+             * Per parameter, because Excel's built-ins differ by slot: `NETWORKDAYS.INTL` refuses a
+             * reference at its date slots and lifts one at `weekend`. An ARRAY at the slot still lifts, a one-cell reference is an
              * ordinary argument, and a repeating slot absorbs a container as members, so the marker only
              * ever applies to a non-repeating scalar parameter.
              */
@@ -23807,7 +23891,7 @@ declare global {
              * union is the range arm, handed over whole. The slot never lifts.
              *
              * @remarks
-             * Excel reads a one-cell argument at some array slots as THE ARGUMENT rather than as a
+             * Some array slots read a one-cell argument as THE ARGUMENT rather than as a
              * one-cell container: `SORT(<#N/A cell>,1,1,<#DIV/0! cell>)` is `#N/A` where
              * `TAKE(<#N/A cell>,<#DIV/0! cell>)` is `#DIV/0!`. The engine's default
              * for a range slot is TAKE's; this flag is SORT's. {@link scalar} and {@link range} each carry
@@ -23874,7 +23958,7 @@ declare global {
              *
              * @remarks
              * 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
+             * that is where volatility is decided: `=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.
              *
@@ -23897,11 +23981,10 @@ declare global {
              * parameter. Omitted at the default of 255.
              *
              * @remarks
-             * Excel keeps one such number per NAME and compares it against the whole call's argument
-             * count in its front end, so a call past it is refused AT ENTRY rather than answered — which
-             * is why the cap lives on the declaration and not in a body. It is not derivable from the
-             * shape: `STDEV` takes 255 arguments and `STDEV.S`, the same function under its dotted name,
-             * takes 254.
+             * The cap is one number per NAME, compared against the whole call's argument count, so a call
+             * past it is refused AT ENTRY rather than answered — which is why the cap lives on the
+             * declaration and not in a body. It is not derivable from the shape: in Excel `STDEV` takes 255
+             * arguments and `STDEV.S`, the same function under its dotted name, takes 254.
              *
              * @defaultValue 255
              */
@@ -24038,9 +24121,8 @@ declare global {
      * - What was the value BEFORE the parameter's type coerced it?
      * - Was that empty slot an omission, or a blank cell the caller pointed at?
      *
-     * Excel has behaviors that turn on exactly those questions, and they cluster at the
-     * parameters Excel declares `any` — where there is nothing to express as a type, because Excel
-     * declined to express one. `CUMIPMT` refuses a boolean at every slot while `FV` coerces one at
+     * Some functions have behaviors that turn on exactly those questions, and they cluster at
+     * parameters declared `any` — where there is nothing to express as a type. `CUMIPMT` refuses a boolean at every slot while `FV` coerces one at
      * every slot; the difference is not the values, it is that `CUMIPMT`'s slots are `any` and its
      * body decides.
      *
@@ -24165,7 +24247,7 @@ declare global {
          */
         getKindAt(index: number): ValueKind;
         /**
-         * True when the argument at `index` is DIRECT — Excel's "typed into the list of arguments":
+         * True when the argument at `index` is DIRECT — typed into the list of arguments:
          * the evaluated value IS a value, not a container or a callable.
          *
          * @param index The PARAMETER index — the position in the body's own signature.
@@ -29205,6 +29287,51 @@ declare global {
          * ```
          */
         setShapeType(shapeType: IGeometry.Preset | string, options?: ITransaction.OperationOptions): this;
+        /**
+         * Returns the shape's outline at a size, for drawing the picture cropped to its shape.
+         *
+         * @param width The frame's width in pixels. Defaults to the movable's.
+         * @param height The frame's height in pixels. Defaults to the movable's.
+         * @returns `null` for a preset this SDK does not know, or for a picture with no movable and no size.
+         */
+        getGeometry(width?: number, height?: number): Promise<IGeometry | null>;
+        /**
+         * Returns the part of the image shown, as percentages of the image's size inset from each edge.
+         *
+         * @remarks
+         * An edge not cropped is absent, so an uncropped picture answers `{}`. A negative inset shows empty
+         * space beyond that edge of the image, which is how a picture fits inside a frame of another shape.
+         */
+        getCrop(): IFill.RectInsets;
+        /**
+         * Sets the part of the image shown. The frame stays as it is, so the part shown is stretched over
+         * it; to keep the image's scale, change the frame with {@link IMovable.setBounds} as well.
+         *
+         * @param crop Percentages of the image's size, inset from each edge; `null` shows the whole image.
+         * @throws ExpectedError when the insets leave nothing to show.
+         *
+         * @example
+         * ```ts
+         * picture.setCrop({ left: 10, right: 10 });
+         * ```
+         */
+        setCrop(crop: IFill.RectInsets | null, options?: ITransaction.OperationOptions): this;
+        /**
+         * Returns the hyperlink a click on the picture follows, or `null` for none.
+         */
+        getHyperlink(): IHyperlink | null;
+        /**
+         * Sets the hyperlink a click on the picture follows.
+         *
+         * @param hyperlink An address, the link's properties, or `null` to remove it. An address takes the
+         * form a cell's does: a url, or `#Sheet1!A1` for a location in this workbook.
+         *
+         * @example
+         * ```ts
+         * picture.setHyperlink('https://www.sheetxl.com');
+         * ```
+         */
+        setHyperlink(hyperlink: IHyperlink.Update, options?: ITransaction.OperationOptions): this;
         /**
          * What the picture's frame draws with: the fill behind the image and the border around it.
          * A picture has no theme style, so each is only what the picture states; by default neither
@@ -30260,7 +30387,7 @@ declare global {
          * @remarks
          * Errors INSIDE a range are the body's to judge: the engine hands a valid range over whole and
          * never looks inside, so a function whose answer depends on every member says so with this
-         * line, placed before its own validation where Excel's error outranks it. A reshaper or a
+         * line, placed before its own validation where the member's error outranks it. A reshaper or a
          * lookup, whose members pass through or are never read, needs no line at all.
          */
         firstError(): FormulaError.Known | null;
@@ -30273,7 +30400,7 @@ declare global {
          * @remarks
          * `options.axis` is the TRAVERSAL order feeding the ordinal, not the orientation of the result:
          * the result is always Nx1, and a row is `flatten().transpose()`. The default is row-major,
-         * which is the order Excel pairs two range operands in.
+         * which is the order two range operands pair in.
          *
          * `options.type` carries a read type onto the result, so a member the type filters out becomes
          * a HOLE at its ordinal rather than compacting the column. That is what lets two operands be
@@ -30922,7 +31049,7 @@ declare global {
              *
              * - By default, `broadcast()` follows strict alignment rules like NumPy and will
              *   throw an error if the input ranges cannot be broadcasted together.
-             * - When `misalignValue` is provided, `broadcast()` will instead mimic Excel behavior:
+             * - When `misalignValue` is provided, `broadcast()` will instead follow Excel's behavior:
              *   - It finds the **largest valid intersection** of the ranges.
              *   - It expands the result to the **union of both range sizes**.
              *   - Any cells that do not have valid corresponding values from the inputs
@@ -30980,7 +31107,7 @@ declare global {
              *
              * @remarks
              * Off, a dimension of 1 is a short dimension like any other and pads `misalignValue` past
-             * its one position: Excel's `MAP` rule, where a 1-row array is not stretched.
+             * its one position: the `MAP` rule, where a 1-row array is not stretched.
              */
             tile?: boolean;
             /**
@@ -31665,7 +31792,7 @@ declare global {
          */
         getAggregates(options?: IRange.IteratorOptions): Readonly<IRangeStats.Aggregates>;
         /**
-         * Returns the sum as Excel's `SUM` reports it — {@link getAggregates}'s `sum` with Excel's
+         * Returns the sum as `SUM` reports it — {@link getAggregates}'s `sum` with Excel's
          * cancellation-to-zero rule applied.
          *
          * @param total A total the caller accumulated across SEVERAL stats instances. Omit for a
@@ -31676,7 +31803,7 @@ declare global {
          * @remarks
          * Collapses a total to exactly zero when it lands at least 50 binary exponents below the
          * operands that produced it, so `SUM(0.1,0.2,-0.3)` is `0` rather than `5.55111512312578E-17`.
-         * Use this wherever you mean "the number Excel's SUM would show" — a status bar, a report
+         * Use this wherever you mean "the number SUM shows" — a status bar, a report
          * total, a formula. Use `getAggregates().sum` where you mean the true total of the data.
          *
          * The two genuinely differ, and neither is a rounding of the other:
@@ -31686,12 +31813,12 @@ declare global {
          *   and `PERCENTOF`, and to NOTHING else — `SUMIF`, `SUMPRODUCT`, `SERIESSUM`, `DSUM`, the
          *   `SUMX2MY2` family and every binary operator all keep the residue over the same values.
          *   That is why this is a method you call and not a change to `getAggregates`.
-         * - `AVERAGE` divides THIS, not the raw sum: snapping the mean instead is measurably wrong.
+         * - `AVERAGE` divides THIS, not the raw sum: snapping the mean instead is wrong.
          *
          * It is also cheap when it does not fire: a bound derived from `min`/`max` rejects any
          * ordinary total without re-reading the range.
          *
-         * **Multiple ranges.** Excel evaluates the rule on the *final* accumulation step, so a total
+         * **Multiple ranges.** The rule applies on the *final* accumulation step, so a total
          * spanning several ranges must be judged against the range holding the LAST value — pass the
          * running total as `total` and call this on that range. (Snapping each range separately gets
          * `SUM(A1:A3,0)` and `SUM(A1:A1,A2:A2,A3:A3)` wrong in opposite directions.) A composite
@@ -31840,7 +31967,7 @@ declare global {
          * Sorting requires materializing the full numeric population (O(n log n), one allocation).
          * Unlike `Aggregates`, sorted views are **not composable across sub-ranges**.
          *
-         * Covers the following Excel functions (all share one sort per coords per calc cycle):
+         * Covers the following functions (all share one sort per coords per calc cycle):
          * - `LARGE`, `SMALL`
          * - `MEDIAN`, `PERCENTILE`, `PERCENTILE.INC`, `PERCENTILE.EXC`
          * - `QUARTILE`, `QUARTILE.INC`, `QUARTILE.EXC`  (q1 = k=0.25, q3 = k=0.75)
@@ -31905,7 +32032,7 @@ declare global {
              * one outside the population is not found.
              * @param exclusive If true, uses exclusive formula (0 and 1 are excluded).
              * @param significance Number of DECIMAL PLACES to TRUNCATE the result to — despite what
-             * Excel's own help calls the argument, it is not significant digits and it does not round.
+             * Excel's help calls the argument, it is not significant digits and it does not round.
              * Truncated toward zero first (1.9 places means 1), and must be at least 1. Omit it for the
              * exact untruncated rank, which is also the only form that cannot fail.
              * @returns The percent rank of x; `null` if x is not found or there are no numbers in range.
@@ -41154,7 +41281,7 @@ declare global {
              * write path both actually ask, use {@link isEncrypted}.
              *
              * Never the password: origins are rendered into logs and REPL output, and ride events and
-             * progress callbacks, so a secret has no business here (see `PROTECTION-DESIGN.md` §5f).
+             * progress callbacks, so a secret has no business here.
              *
              * Use it to show a lock affordance, and to recognise that writing plaintext over it would be a
              * downgrade — {@link IWorkbookIO.WriteOptions.password} makes that refusal explicit.
@@ -41560,8 +41687,8 @@ declare global {
              * - `'auto'` — cached values are trusted; the load pass evaluates a formula cell with no
              *   cached value (a repair — Excel always stores one) and refreshes volatiles. Everything is
              *   recalculated only when Excel would recalculate on open: the file sets `fullCalcOnLoad`,
-             *   or for xlsx its `calcId` is missing or older than the Excel build this library is
-             *   verified against. (What this library writes carries one: the source file's, else that
+             *   or for xlsx its `calcId` is missing or older than the Excel build this library
+             *   targets. (What this library writes carries one: the source file's, else that
              *   build's.) To take the file's values as they are whatever it says — as openpyxl does —
              *   pass `'none'`; to always recalculate, `'full'`.
              * - `'full'` — everything is recalculated, whatever the file says.
@@ -43230,7 +43357,7 @@ declare global {
         /**
          * The events that carry a {@link ChangeEvent}: what {@link ChangeEvent.getKind} names.
          */
-        type ChangeEventKey = 'onDataChange' | 'onStyleChange' | 'onLayoutChange' | 'onMergesChange' | 'onSpillsChange';
+        type ChangeEventKey = 'onDataChange' | 'onStyleChange' | 'onMergesChange' | 'onSpillsChange';
         /**
          * What a change event announces: where the change landed and what wrote it.
          *
@@ -43470,11 +43597,8 @@ declare global {
              * for "cell geometry moved".
              * * This can be be due to row/column sizes changes or changing the max rows columns.
              * * Zoom and viewport do not change the underlying layout.
-             *
-             * @param source The sheet.
-             * @param event The whole sheet: sizes are announced by the headers, which do not say where.
              */
-            onLayoutChange?(source: IWorksheet, event: IWorksheet.ChangeEvent): void;
+            onLayoutChange?(source: IWorksheet): void;
             /**
              * Called when which rows are hidden has changed.
              */
@@ -45310,7 +45434,8 @@ declare global {
          */
         setLicenseKey(licenseKey: string, force?: boolean): Promise<LicenseDetails>;
         /**
-         * Return the current license details.
+         * Return the current license details. Prints nothing: the license notice is printed when the
+         * engine starts under the license (see {@link assertUsable}).
          */
         getDetails(): Promise<LicenseDetails>;
         /**
@@ -46566,14 +46691,6 @@ declare global {
         constructor(message: string, options?: ErrorOptions);
     }
 
-    /**
-     * The statistics a box and whisker draws for one set of values, as Excel computes them (measured
-     * 2026-10-22, `probe-chart-2016-types.ps1` B01-B13 and `probe-chart-2016-types-reopen.ps1` B05-B07;
-     * DESIGN-CHART §4.17): quartiles by Excel's exclusive (`QUARTILE.EXC`) or inclusive
-     * (`QUARTILE.INC`) method, the median the same either way; whiskers to the furthest values within
-     * 1.5 interquartile ranges of the box, and the values beyond them outliers (B09: 60 beyond a box of
-     * 15..25).
-     */
     export type QuartileMethod = 'inclusive' | 'exclusive';
 
     /**
@@ -47009,12 +47126,12 @@ declare global {
      * omitted when there is a single repetition. `SORTBY`'s legal arities are 2 and 1+2n and nothing
      * else — `SORTBY(array, by1)` is legal, `SORTBY(array, by1, o1, by2)` is not. It is not a general
      * "the final element of the final group may be omitted" rule; that rule would accept a formula
-     * Excel refuses. An optional slot anywhere else in the group is a compiler error.
+     * that must be refused. An optional slot anywhere else in the group is a compiler error.
      *
      * ### The maximum, `Max`
      *
-     * The second type argument is the largest number of arguments the WHOLE CALL accepts, which is
-     * how Excel states it: one number per NAME, compared against the call's total argument count and
+     * The second type argument is the largest number of arguments the WHOLE CALL accepts: one
+     * number per NAME, compared against the call's total argument count and
      * refused at entry (`Excess_function_arguments`), never a count of this parameter's own share.
      * `SWITCH`'s 254 therefore covers its `expression` and its trailing `default` as well as the
      * pairs, and `CHOOSEROWS`' covers its `array`.
@@ -47076,8 +47193,8 @@ declare global {
      * what can arrive and {@link IFunctionArguments.getAreaCountAt} answers the union question the
      * kind cannot — a plain reference is one area, a union is more.
      *
-     * Its use is meant to stay countable: a slot earns it with a rule Excel actually shows, never
-     * with a guess.
+     * Its use is meant to stay countable: a slot earns it with a concrete behavior that needs it,
+     * never speculatively.
      *
      * @example
      * ```ts
@@ -47272,7 +47389,6 @@ declare global {
             /** Box and whisker groups: what of each box is drawn, and the line it is drawn with. */
             box?: BoxOptions;
         }
-        /** How a box and whisker series draws its boxes (DESIGN-CHART §4.17). */
         interface BoxOptions {
             quartileMethod: QuartileMethod;
             /** An x at each box's mean. */
@@ -47399,11 +47515,6 @@ declare global {
                 bannerFill: IFill.JSON | null;
             };
         }
-        /**
-         * How a histogram's values were counted (DESIGN-CHART §4.16): each series' `values` are its
-         * counts by bin and its `categories` the bins' labels; a pareto's are its sums by category,
-         * largest first, with a line of the running share on an axis of its own.
-         */
         interface Histogram {
             /** The first series' bins, each with the indexes of its `raw` values. */
             bins: HistogramBin[];
@@ -47707,7 +47818,7 @@ declare global {
      * This is what makes a miss impossible by construction for a served root: one fetch of this file and
      * the resolver knows exactly which packages and files the root holds, so it never has to ask for a
      * file that is not there. A root without one (a hand-assembled folder) still works — the resolver
-     * falls back to probing, exactly as before this file existed.
+     * falls back to probing.
      */
     export interface ResourceRootIndex {
         /** Every file under the root, `path` relative to it (e.g. `locales/@sheetxl/sdk/de/ui.msg.json`). */
@@ -47766,6 +47877,12 @@ declare global {
          * Display only: the value still reads as nothing to calculation.
          */
         function toDisplayText(value: IRichData): string | null;
+        /**
+         * The text that stands for `value` as a whole, as in the formula bar: its display text
+         * ({@link toDisplayText}), else the label its kind was given in parentheses, `(Image)`, else
+         * `(Rich Object)`.
+         */
+        function toPlaceholderText(value: IRichData): string;
         /**
          * 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
@@ -47886,8 +48003,8 @@ declare global {
          */
         const MAX_SIGNIFICANT_DIGITS = 15;
         /**
-         * Applies Excel's entry rule to numeric text: every significand digit past the
-         * 15th becomes `0`, so the text parses to the double Excel would store.
+         * Applies the 15-digit entry rule to numeric text: every significand digit past the
+         * 15th becomes `0`, so the text parses to the double a cell stores.
          *
          * @param text Numeric text in any accepted form — signed, grouped, percent,
          * currency-affixed, or scientific. The scan is locale-blind: only digit
@@ -47901,6 +48018,30 @@ declare global {
          * truncation, not rounding: `1234567890.123456789` stores `…345`, never `…346`.
          */
         function truncateNumberText(text: string): string;
+        /**
+         * The smallest magnitude a stored number can have: the smallest normal double. A smaller one is
+         * stored as `0`.
+         */
+        const MIN_NUMBER = 2.2250738585072014e-308;
+        /**
+         * Applies the stored-number floor to a number entering a workbook — typed, parsed from text, written
+         * through the API or loaded from a file: a magnitude below {@link MIN_NUMBER} becomes `0`.
+         */
+        function flushSubnormal(value: number): number;
+        /**
+         * Whether numeric text is inside the range accepted as a number, judged from the text as
+         * written rather than the double it parses to.
+         *
+         * @param text Numeric text in any accepted form, as {@link truncateNumberText} takes it. Only
+         * digits, `decimal` and an exponent marker are read.
+         * @param decimal The decimal separator `text` is written with.
+         * @returns `false` when the leading significant digit sits outside `1E-309` … `1E+307`
+         * (`1E-310`, `0.00001E-305`, `1E+308`); for a zero mantissa, when its scale — exponent less
+         * fraction digits — is outside ±308 (`0E-309`, `0.0E-308` and `0E+309`, but not `0E-308`,
+         * `000E-308` or `0.0E+309`). Text out of range is not a number: a formula literal will not
+         * commit, `VALUE` is `#VALUE!` and typed entry stays text.
+         */
+        function isNumberTextInRange(text: string, decimal?: string): boolean;
         /**
          * Encodings of `ScalarType` for persistence.
          */
@@ -48162,8 +48303,7 @@ declare global {
      *
      * @remarks
      * A Windows path becomes a `file:///` URI with forward slashes and percent-encoding, a UNC path a
-     * `file://server/share/…` one, and a URL or a bare relative name is kept verbatim — the three
-     * target shapes measured in the corpus (DESIGN-EXTERNAL-LINKS §2.2).
+     * `file://server/share/…` one, and a URL or a bare relative name is kept verbatim.
      */
     export function sourceEntryFromPath(path: string): IExternalBook.SourceEntry;
 
@@ -48356,16 +48496,6 @@ declare global {
         visitTextFrame?: (frame: ITextFrame) => Partial<ITextFrame> | void;
     }
 
-    /**
-     * Excel's date axis (measured 2026-10-17, `probe-chart-dates.ps1` and `probe-chart-dates-units.ps1`,
-     * DESIGN-CHART §4.2). Dates are serials, in the 1900 or 1904 system; lengths are points.
-     *
-     * @remarks
-     * A date axis has one slot per base unit (a day, a month or a year) from its first date, snapped to
-     * the start of its unit, to its last; each point is drawn in the slot of its date, so a gap in the
-     * dates is a gap on the axis and two points of one date share a slot. Labels are drawn on the
-     * major ticks only, from the first slot on, in the axis's number format.
-     */
     export type TimeUnit = 'days' | 'months' | 'years';
 
     /**
@@ -48489,14 +48619,6 @@ declare global {
         superscript?: boolean;
     }
 
-    /**
-     * Excel's trendlines: the fits, their R², the moving average, and the label's equation.
-     *
-     * @remarks
-     * Measured against Excel 16.0 (DESIGN-CHART §4.5, `probe-chart-trendlines.ps1`): every coefficient
-     * of the nine types on a line chart and a scatter, a set intercept, and a sweep of numbers through
-     * the label's General format.
-     */
     export type TrendlineType = 'exp' | 'linear' | 'log' | 'movingAvg' | 'poly' | 'power';
 
     /**
@@ -49002,7 +49124,7 @@ declare global {
      *
      * @remarks
      * A value's kind and its extent are different axes: `{10}`, `A1` and a bare `10` all reach a
-     * range-typed parameter as a 1x1 container, yet Excel separates them:
+     * range-typed parameter as a 1x1 container, yet they are distinct:
      * `VLOOKUP(10,10,1,TRUE)` is `#N/A` while `VLOOKUP(10,{10},1,TRUE)` is 10, and `TYPE` answers
      * 1 vs 64. The kind is what the CALLER supplied; the extent is merely its size.
      *
@@ -49011,7 +49133,7 @@ declare global {
      * argument can be: a reference, a non-reference array, a callable, and no argument at all. As an
      * argument kind, {@link ScalarType.Null} means a BLANK value.
      *
-     * The names and values are ours. The numeric codes Excel's `TYPE` function answers are a
+     * The names and values are ours. The numeric codes the `TYPE` function answers are a
      * PROJECTION of this kind (see `TYPE`'s implementation), not the kind itself.
      *
      * @see {@link IFunctionArguments.getKindAt}
@@ -49103,7 +49225,7 @@ declare global {
          * Compiles Excel wildcard text into a regex.
          *
          * @param anchor Where the pattern has to line up: `true` for the WHOLE string, `'start'` for a
-         * PREFIX, `false` for anywhere in it. Excel matches a whole cell, so every lookup and criteria
+         * PREFIX, `false` for anywhere in it. A criterion matches a whole cell, so every lookup and criteria
          * caller anchors; `SEARCH`, which looks for a substring, does not; and a `D` function's criteria
          * table is the prefix form — `DSUM` with the criterion `appl` takes the row whose value is
          * `Apple`, where `COUNTIF` with the same criterion takes none.