@sheetxl/sdk 0.7.28-beta.3 → 0.8.0-beta.1

package/types/scripting.d.ts

@@ -639,6 +639,65 @@ declare global {
         }
     }
 
+    /**
+     * Family aliases: one name an author writes that expands to several {@link CompatFeatures}.
+     *
+     * @remarks
+     * Excel's Analysis-ToolPak heritage is ONE measured rule with two halves that act on disjoint
+     * parameter kinds — `noReferenceLift` at a non-repeating scalar slot, `noMemberFilter` at a
+     * repeating one — so every function in the family carries the same two bits and `@compat atp`
+     * says so in one word. The alias is expanded by the linter; only the atomic features are ever
+     * stored, so `@compat atp` and `@compat noReferenceLift noMemberFilter` emit the same declaration.
+     * The atomic names stay available for the day a function measures as disagreeing on one half.
+     */
+    export const CompatAliases: Readonly<Record<string, readonly CompatFeature[]>>;
+
+    /**
+     * One of the {@link CompatFeatures} names.
+     */
+    export type CompatFeature = keyof typeof CompatFeatures;
+
+    /**
+     * The behaviors `@compat` can turn on, and what each one does.
+     *
+     * @remarks
+     * A feature earns a place here only if the BODY cannot do it — the decision happens before the
+     * body runs, or instead of running it. Everything a body can decide for itself belongs in the
+     * body, where `FormulaContext.getArgs()` and `Omittable` already reach.
+     *
+     * Function-level until a measurement forces otherwise: `noReferenceLift` is per-function in
+     * Excel, and no function is known whose parameters disagree.
+     *
+     * @see {@link https://www.sheetxl.com/docs/guides/concepts/udf | UDF authoring guide}
+     */
+    export const CompatFeatures: {
+        /**
+         * A multi-cell REFERENCE at a non-repeating scalar parameter is `#VALUE!` rather than a
+         * broadcast.
+         *
+         * Excel's Analysis-ToolPak family answers `CUMIPMT(G1:G2,120,100000,13,24,0)` with `#VALUE!`
+         * where the native `ROUND(B1:B3,3)` spills three results. A multi-cell reference has no way to
+         * become a scalar there, because these functions never intersect. An ARRAY at the same slot
+         * still lifts (`MROUND({3,4,5},5)` spills), so the refusal is about references specifically,
+         * and a REPEATING slot absorbs a container as members either way (`GCD(C1:C3)` is 4) — so this
+         * never applies to one.
+         */
+        readonly noReferenceLift: "A multi-cell reference at a non-repeating scalar parameter is #VALUE! rather than a broadcast.";
+        /**
+         * Members of a REPEATING scalar parameter are coerced rather than filtered: numeric text
+         * parses, a blank inside a multi-cell range reads 0, and a boolean or non-numeric text member
+         * is `#VALUE!` for the whole call.
+         *
+         * The native family FILTERS — `SUM({1,"8",TRUE})` is 1, the text and the boolean skipped, and a
+         * blank cell contributes nothing. Excel's Analysis-ToolPak family coerces instead:
+         * `GCD({6,"8",12})` is 2, `GCD({6,TRUE,12})` is `#VALUE!`, `LCM(6,A1:A2)` over two blank cells
+         * is 0. A direct argument follows the same rule (`GCD(6,TRUE,12)` is `#VALUE!` where
+         * `SUM(6,TRUE,12)` is 19), and a one-cell blank reference or an omitted argument is still
+         * skipped — it never became a member.
+         */
+        readonly noMemberFilter: "Members of a repeating scalar parameter are coerced rather than filtered; one that cannot be is #VALUE!.";
+    };
+
     /**
      * A compiled collection of functions — the serialized form of one module.
      *
@@ -1707,6 +1766,32 @@ declare global {
             readonly TwoCell: "twoCell";
         };
         type Type = typeof Type[keyof typeof Type];
+        /**
+         * Options shared by the collections that add anchored items — conditional formats, data
+         * validations, protected ranges.
+         */
+        interface AddOptions extends ITransaction.OperationOptions {
+            /**
+             * Position in the collection. `0` is first — for a conditional format, the highest priority.
+             *
+             * @defaultValue 0 — a new item goes first, as in Excel.
+             */
+            index?: number;
+            /**
+             * Redefine the item already at `index` instead of inserting, when it is anchored to exactly
+             * the same ranges (discontiguous ranges compare area by area, in authored order).
+             *
+             * @defaultValue false
+             *
+             * @remarks
+             * Only the item at `index` is considered, as in Excel. What counts as the same item is per
+             * collection: a data validation or protected range matches on ranges alone; a conditional
+             * format only redefines a scale rule (data bar, color scale, icon set) of the same kind —
+             * a style rule always inserts, since several may apply to one cell, whereas a second scale
+             * of one kind on the same ranges could never render.
+             */
+            replaceExisting?: boolean;
+        }
     }
 
     /**
@@ -2192,6 +2277,63 @@ declare global {
          * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
          */
         evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+        /**
+         * When the engine recalculates on its own — Excel's Calculation Options.
+         *
+         * @remarks
+         * In {@link ICalculation.CalculationMode.Automatic} every commit that dirties a formula
+         * schedules a pass. In {@link ICalculation.CalculationMode.Manual} an edit only marks its
+         * dependents out of date ({@link isCalculationRequired}) and nothing is recalculated — volatile
+         * functions (`NOW`, `RAND`) stop re-rolling too — until {@link calculate}: Excel's F9 (every
+         * sheet), Shift+F9 (`scope`) and Ctrl+Alt+F9 (`full`). {@link ready} resolves at once in manual
+         * mode; a caller that wants current values calls {@link calculate}.
+         *
+         * @defaultValue {@link ICalculation.CalculationMode.Automatic}
+         */
+        getCalculationMode(): ICalculation.CalculationMode;
+        /**
+         * Sets the calculation mode.
+         *
+         * @remarks
+         * Leaving manual mode recalculates whatever is out of date, as Excel does.
+         * {@link ICalculation.CalculationMode.AutomaticExceptTables} is accepted for parity with the
+         * file format and Office Scripts; this engine has no what-if data tables, so it recalculates
+         * exactly as `Automatic` does.
+         */
+        setCalculationMode(mode: ICalculation.CalculationMode): this;
+        /**
+         * Whether any formula is out of date — Excel's `Calculate` indicator in the status bar.
+         *
+         * @remarks
+         * Meaningful in manual mode, where edits accumulate until {@link calculate}. In automatic
+         * mode it is `true` only between an edit and the pass it schedules.
+         */
+        isCalculationRequired(): boolean;
+        /**
+         * How a reference cycle is resolved — Excel's "Enable iterative calculation" and its limits.
+         *
+         * @see {@link ICalculation.IterativeCalculation}
+         */
+        getIterativeCalculation(): ICalculation.IterativeCalculation;
+        /**
+         * Enables, disables or configures iterative calculation.
+         *
+         * @param options `true`/`false` toggles `enabled` alone; an object updates the fields given and
+         * keeps the rest.
+         *
+         * @remarks
+         * Every cell in a cycle is recalculated when this changes: turning iteration on resolves the
+         * cycles the workbook shows as unresolved, turning it off writes `0` to them again.
+         */
+        setIterativeCalculation(options: boolean | Partial<ICalculation.IterativeCalculation>): this;
+        /**
+         * The calculation settings as JSON — what an xlsx carries in `calcPr`.
+         *
+         * @remarks
+         * Sparse: a setting at its default is omitted. Settings a file carried that this engine does
+         * not act on (`calcOnSave`, `fullCalcOnLoad`, `fullPrecision`, …) are kept and written back.
+         */
+        toJSON(): ICalculation.JSON;
         /**
          * Add Listeners.
          *
@@ -2221,6 +2363,87 @@ declare global {
          * tokenizer, the AST, a formula input — is ever handed an expression of unbounded size.
          */
         const MAX_EXPRESSION_LENGTH = 8192;
+        /**
+         * A reference cycle — the answer to "why is this cell `0`".
+         *
+         * @remarks
+         * A cell is in a cycle when calculating it opens its own value, directly or through other cells
+         * — `=A1+1` in A1, `=OFFSET(A1,0,0)` in A1, `=SUMIF(B1,C1,A1)` in A1 while B1 matches C1. With
+         * iterative calculation off (the default, and Excel's) every cell in a cycle, and every cell
+         * downstream of one, evaluates to `0`; nothing on the value says why. This does.
+         *
+         * Reached from a cell — {@link ICell.getCircularReference} answers it for members and for
+         * downstream cells alike — and carried by the `ICellRange.Feature.Circular` regions, so a
+         * range, a sheet or the workbook is asked the way any other error is asked:
+         * `getCounts(Feature.Circular)` for how many, `getRegions(Feature.Circular)` for which, with
+         * this object as each region's payload. There is no list of cycles on the calculation: nobody
+         * starts from the cycle; they start from a cell or a range and want to know more.
+         *
+         * Live, not a snapshot: it reads the engine's cycle table on every call and drops members whose
+         * formula has since been edited away, so a stale handle answers `getMemberCount() === 0`.
+         * Persists until the last member is edited away.
+         */
+        interface ICircularReference {
+            /**
+             * The cell named for the cycle, the way Excel's status bar names one
+             * (`Worksheet.CircularReference` likewise answers a single cell): the first member in
+             * row-major order. `scope` is the sheet name, or `null` when the member lives in a named
+             * formula's body rather than on a sheet.
+             */
+            getRepresentative(): IRange.CellCoords | null;
+            /**
+             * Every cell IN the cycle, in row-major order, `scope` set to the sheet name. Small — a cycle
+             * is the cells that read each other, not everything that reads them (that is
+             * {@link getDownstreamCount}).
+             */
+            getMembers(): readonly IRange.CellCoords[];
+            /** How many cells are IN the cycle, the representative included. */
+            getMemberCount(): number;
+            /** How many cells read the cycle (transitively) and evaluate to `0` because of it. */
+            getDownstreamCount(): number;
+            /**
+             * Whether `coords` is IN the cycle, as opposed to downstream of it. A cell that reads a
+             * member's `0` answers `false` here but still resolves this cycle from
+             * {@link ICell.getCircularReference} — the tooltip for it says "reads a circular reference
+             * at A1", not "is one".
+             */
+            isMember(coords: IRange.CellCoords): boolean;
+            /**
+             * The cycle as a walk of reads from `from` back to itself — each cell reads the next, and
+             * the last reads the first. A cycle has no start, so it is told from the cell that asks:
+             * with `A1 = B1+1` and `B1 = A1+1`, asked from A1 it is `[A1, B1]` (A1 → B1 → A1), asked
+             * from B1 it is `[B1, A1]`. A cycle of one is `[A1]`.
+             *
+             * @remarks
+             * Exact, not inferred from formula text: it is the order the engine found the cycle in,
+             * which is the order the reads happened — a dynamic read (`INDIRECT`, `OFFSET`) is a step
+             * like any other. Interlocking cycles share members; the walk follows the read that closed
+             * the cycle `from` was found in, so it is ONE loop through that cell, not every member
+             * ({@link getMembers} is every member).
+             *
+             * Empty when `from` is not a live member — a downstream cell asks from
+             * {@link getRepresentative}.
+             */
+            getPath(from: IRange.CellCoords): readonly IRange.CellCoords[];
+            /**
+             * Whether iterative calculation was on when the cycle was last evaluated. When `false` the
+             * cycle is unresolved and every member and downstream cell is `0`; the iteration answers
+             * below are then meaningless (`0` sweeps, no change).
+             */
+            isIterative(): boolean;
+            /**
+             * Whether iterative calculation settled it: every member moved by less than the workbook's
+             * `maxIterateChange` in the last sweep. Always `false` with iteration off.
+             */
+            isConverged(): boolean;
+            /** How many sweeps the last evaluation ran — up to the workbook's `maxIterations`. */
+            getIterationCount(): number;
+            /**
+             * The largest change any member made in the last sweep — what stopped the iteration when
+             * {@link isConverged}, what it never got under when not. `0` with iteration off.
+             */
+            getLastChange(): number;
+        }
         /**
          * Represents a formula that can be evaluated.
          */
@@ -2899,8 +3122,16 @@ declare global {
             /**
              * Called when the calculation has been updated and
              * a calculation has not been started.
+             *
+             * @remarks
+             * In manual mode this is every edit that leaves a formula out of date — see
+             * {@link ICalculation.isCalculationRequired}.
              */
             onStale?(source: ICalculation): void;
+            /**
+             * Called when the calculation mode or the iterative-calculation settings change.
+             */
+            onOptionsChange?(source: ICalculation): void;
             /**
              * Called when a calculation is starting.
              */
@@ -2984,6 +3215,38 @@ declare global {
             readonly AutomaticExceptTables: "automaticExceptTables";
         };
         type CalculationMode = typeof CalculationMode[keyof typeof CalculationMode];
+        /**
+         * Iterative calculation — Excel's "Enable iterative calculation" with its two limits.
+         *
+         * @remarks
+         * With it off a reference cycle evaluates to `0` and is reported as unresolved. With it on the
+         * cells of the cycle are re-evaluated in turn, each read seeing the latest value, until no cell
+         * moved by {@link maxChange} or {@link maxIterations} sweeps ran — and the results persist into
+         * the next recalculation, which re-runs every cycle the way it re-runs `NOW()`: `=A1+1` in A1 is
+         * a counter that advances by `maxIterations` per recalc. A cycle that stops on the sweep cap is
+         * still reported ({@link ICircularReference.isConverged}); a converged one is not.
+         *
+         * Office Scripts calls the count `maxIteration`; the file format `iterateCount` / `iterateDelta`.
+         */
+        interface IterativeCalculation {
+            /**
+             * @defaultValue `false`
+             */
+            enabled: boolean;
+            /**
+             * The most sweeps one recalculation runs over a cycle.
+             *
+             * @defaultValue `100`
+             */
+            maxIterations: number;
+            /**
+             * Sweeps stop early once every cell in the cycle moved by less than this. A non-numeric
+             * change (text, error) never counts as settled.
+             *
+             * @defaultValue `0.001`
+             */
+            maxChange: number;
+        }
         /**
          * Represents the status of a calculation result
          */
@@ -3246,12 +3509,28 @@ declare global {
          *
          * @remarks
          * Warnings differ from errors in that they may alter the display of the cell's value or type.
+         * A cell in a reference cycle, or downstream of one, carries one here — the text form of
+         * {@link getCircularReference}: the walk from this cell around the cycle and back
+         * ("Circular reference: A1 → B1 → A1"), or "Reads a circular reference at A1".
          */
         getWarnings(): readonly string[];
         /**
          * Retrieves any errors attached to the cell.
          */
         getErrors(): readonly string[];
+        /**
+         * The reference cycle this cell is in, or downstream of — or `null` when it is neither.
+         *
+         * @remarks
+         * Evaluated state, beside the value: a cell in a cycle, and every cell that reads one, is `0`
+         * (Excel, iterative calculation off), and this is the only thing that says why. Ask the cycle
+         * whether this cell is a member or a reader ({@link ICalculation.ICircularReference.isMember})
+         * and, under iterative calculation, whether it converged.
+         *
+         * The range-level view is `ICellRange.Feature.Circular` — `getCounts` for how many cells,
+         * `getRegions` for which, each region carrying this same object as its payload.
+         */
+        getCircularReference(): ICalculation.ICircularReference | null;
         /**
          * Returns the style information applied to the cell.
          *
@@ -5550,6 +5829,22 @@ declare global {
          * Returns the absolute bounds for the range.
          */
         getBounds(): Bounds;
+        /**
+         * The size this range's content needs — what {@link getBounds} would report if the range had
+         * been {@link autoFit}. A pure query: nothing is measured onto the model and nothing is committed.
+         *
+         * @param options Measurement options. Default `{ axes: IRange.AxisSelection.Both }`.
+         *
+         * @remarks
+         * - The width is the sum of the per-column best fits and the height the sum of the per-row best
+         *   fits, so a single-column range answers "how wide must this list be" directly.
+         * - An axis left out of {@link BestFitOptions.axes} reports its current size.
+         * - Only the range's own content is measured, so the answer never depends on cells outside it.
+         *   (`autoFit` also scans outside the range, to prove a shrink is safe.)
+         * - Sheet protection is not consulted: reading a size cannot violate it, and a protected sheet
+         *   answers the same as an unprotected one.
+         */
+        getBestFit(options?: ICellRange.BestFitOptions): Size;
         /**
          * Indicates if the range is readonly only.
          *
@@ -6036,9 +6331,9 @@ declare global {
             includeMergeOverflow?: boolean;
         }
         /**
-         * Options for {@link ICellRange.autoFit}.
+         * Options for {@link ICellRange.getBestFit} — measurement only.
          */
-        interface AutoFitOptions extends ITransaction.OperationOptions {
+        interface BestFitOptions {
             /**
              * Best fit using the minimum amount of space required.
              *
@@ -6049,21 +6344,6 @@ declare global {
              * For example allowing numbers to round or use scientific notation.
              */
             minContent?: boolean;
-            /**
-             * Restricts autoFit to only grow, never shrink.
-             *
-             * @defaultValue false - adjust in both directions.
-             *
-             * @remarks
-             * This is useful when adjusting fonts and wan the columns to resize but not the rows.
-             */
-            expandOnly?: boolean | IRange.Axis;
-            /**
-             * If this is set to `true` then any headers that have custom sizes will be ignored.
-             *
-             * @defaultValue false
-             */
-            skipCustomSize?: boolean;
             /**
              * The axes to autoFit.
              *
@@ -6085,6 +6365,26 @@ declare global {
              */
             formulaView?: boolean;
         }
+        /**
+         * Options for {@link ICellRange.autoFit}.
+         */
+        interface AutoFitOptions extends BestFitOptions, ITransaction.OperationOptions {
+            /**
+             * Restricts autoFit to only grow, never shrink.
+             *
+             * @defaultValue false - adjust in both directions.
+             *
+             * @remarks
+             * This is useful when adjusting fonts and wan the columns to resize but not the rows.
+             */
+            expandOnly?: boolean | IRange.Axis;
+            /**
+             * If this is set to `true` then any headers that have custom sizes will be ignored.
+             *
+             * @defaultValue false
+             */
+            skipCustomSize?: boolean;
+        }
         /**
          * Options for {@link ICellRanges.getFlattened}.
          */
@@ -6614,11 +6914,20 @@ declare global {
             /** Cells inside a dynamic-array spill zone. Writing into one is a real failure mode. */
             readonly Spills: "spills";
             /**
-             * Evaluated state: cells whose calculation itself failed — mostly circular references.
-             * Distinct from {@link Feature.Error}: `#DIV/0!` is a successfully calculated error VALUE
-             * (the `Error` kind); `CalcError` is the engine failing to evaluate at all.
+             * Evaluated state: cells whose calculation itself failed. Distinct from
+             * {@link Feature.Error}: `#DIV/0!` is a successfully calculated error VALUE (the `Error`
+             * kind); `CalcError` is the engine failing to evaluate at all. A reference cycle is not a
+             * failure — its cells evaluate, to `0` — and is {@link Feature.Circular}.
              */
             readonly CalcError: "calcError";
+            /**
+             * 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.
+             * Regions group by cycle and by kind (`member` | `downstream`), so a block that reads one bad
+             * cell is ONE region, and each region's payload is the cycle itself
+             * (`ICalculation.ICircularReference` — members, counts, whether iteration settled it).
+             */
+            readonly Circular: "circular";
             /** Direct fill. */
             readonly Fill: "fill";
             /** Direct borders. */
@@ -9908,8 +10217,11 @@ declare global {
          * Only the keys named are touched. An explicit `null` **clears** a key — required when switching
          * a rule between its two shapes, since `condition`+`style` and `scale` are mutually exclusive
          * (setting one side also clears the other unless the caller named both).
+         *
+         * Passing another rule takes its whole definition — every key, cleared where the other rule
+         * has none — so the shape switches with it. The anchor is not part of it.
          */
-        update(properties: IConditionalFormat.Modifiers, options?: ITransaction.OperationOptions): this;
+        update(properties: IConditionalFormat.Modifiers | IConditionalFormat, options?: ITransaction.OperationOptions): this;
         /**
          * Returns a snapshot of the conditional that can be used for copying and archiving.
          */
@@ -10339,8 +10651,12 @@ declare global {
     export namespace IConditionalFormatCollection {
         /**
          * Options for adding a {@link IConditionalFormat}.
+         *
+         * @remarks
+         * `replaceExisting` redefines the rule at `index` only when it is a scale rule of the same
+         * kind on exactly the same ranges — see {@link IAnchored.AddOptions.replaceExisting}.
          */
-        interface AddOptions extends IConditionalFormat.Properties, ITransaction.OperationOptions {
+        interface AddOptions extends IConditionalFormat.Properties, IAnchored.AddOptions {
         }
         /**
          * Options for searching for {@link IConditionalFormat}s.
@@ -10724,8 +11040,12 @@ declare global {
     export namespace IDataValidationCollection {
         /**
          * Options for adding a data validation to the collection.
+         *
+         * @remarks
+         * `replaceExisting` redefines the validation at `index` when it covers exactly the same ranges —
+         * see {@link IAnchored.AddOptions.replaceExisting}.
          */
-        interface AddOptions extends IDataValidation.Properties, ITransaction.OperationOptions {
+        interface AddOptions extends IDataValidation.Properties, IAnchored.AddOptions {
         }
         interface GetItemsOptions {
             /**
@@ -12260,6 +12580,7 @@ declare global {
      * | Category | Key methods |
      * |---|---|
      * | Evaluation lifecycle | `markVolatile`, `getRow`, `getColumn`, `getEntireCoords` |
+     * | Argument reflection | `getArgs` |
      * | Output hints | `formatResults` |
      * | Range construction | `createRange`, `filterHidden` |
      * | Dynamic references | `getReference`, `getValueAt`, `getFormulaAt`, `getSpillAt` |
@@ -12714,6 +13035,22 @@ declare global {
          * Mostly for diagnostics; the built-in `INFO` function is built on it.
          */
         getRuntime(): IRuntime;
+        /**
+         * The current call's arguments — how many the caller supplied, in which positions, of what kind,
+         * and what each value was BEFORE coercion.
+         *
+         * @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.
+         *
+         * 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
+         * you another call's arguments.
+         *
+         * @throws If called outside a function dispatch — there are no arguments to reflect on.
+         */
+        getArgs(): IFunctionArguments;
     }
 
     /**
@@ -13375,9 +13712,164 @@ declare global {
              * @defaultValue false
              */
             cancelable?: boolean;
+            /**
+             * Named engine behaviors this function opts into, from the `@compat` doc tag.
+             *
+             * @remarks
+             * Canonical spellings, deduplicated and in declaration order; a family alias the author wrote
+             * (`@compat atp`) has already been expanded to its atomic features. An unknown name never
+             * reaches here — the linter fails the build on one, deliberately: a compatibility rule that
+             * silently no-ops is the worst failure available, because the fixtures keep passing and the
+             * behavior is simply absent.
+             *
+             * @see {@link CompatFeatures}
+             * @see {@link CompatAliases}
+             */
+            compat?: CompatFeature[];
         }
     }
 
+    /**
+     * The current call's arguments, as the body sees them — argument **reflection**.
+     *
+     * @remarks
+     * A declaration answers "what does this parameter mean?", and the marshaller coerces every
+     * argument to it. That is right for the overwhelming majority of parameters. What it cannot answer
+     * is anything about *this particular call*:
+     *
+     * - What did the caller write there — a value, a cell, an array, nothing at all?
+     * - 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 measured 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
+     * every slot; the difference is not the values, it is that `CUMIPMT`'s slots are `any` and its
+     * body decides.
+     *
+     * It is REFLECTION and nothing else — two questions, and no third:
+     *
+     * | question | answers |
+     * | --- | --- |
+     * | *what was supplied* | {@link getLength}, {@link isOmittedAt} |
+     * | *what it is* | {@link getRawAt} |
+     *
+     * Coercion is deliberately absent. A body that wants a number calls
+     * {@link IFormulaContext.parseAsNumber} on the value this hands it — that already takes a value,
+     * already propagates an incoming error with its identity, and already answers `#VALUE!` for a
+     * boolean, which IS the rule an `any` slot needs. There is no coercion an index can do that a
+     * value cannot.
+     *
+     * Obtained from `FormulaContext.getArgs()`, and valid ONLY while the body that asked for it is
+     * running. A body must not retain it across an `await`, a callback, or a nested evaluation — the
+     * views are pooled by dispatch depth, so the one at your depth is handed to the next call at that
+     * depth.
+     *
+     * ```typescript
+     * export function CUMIPMT(rate: Scalar, nper: Scalar): number {
+     *   const args = FormulaContext.getArgs();
+     *   if (args.isOmittedAt(0)) return FormulaError.BuiltIn.NA;     // `CUMIPMT(,120,…)` is #N/A
+     *   const asNumber = FormulaContext.parseAsNumber(args.getRawAt(0) as Scalar);  // TRUE is #VALUE!
+     *   // …
+     * }
+     * ```
+     *
+     * @see {@link IFormulaContext.getArgs}
+     */
+    export interface IFunctionArguments {
+        /**
+         * How many PARAMETERS the caller supplied.
+         *
+         * @remarks
+         * Indexing throughout matches the BODY's own signature, never the raw call positions
+         * (see {@link getRawAt}). `index >= getLength()` is an ABSENT argument — one the caller never
+         * wrote, whose own JS initializer supplied the value. That is a different thing from an OMITTED
+         * one; see {@link isOmittedAt}.
+         */
+        getLength(): number;
+        /**
+         * This invocation's value at `index`, uncoerced.
+         *
+         * @param index The PARAMETER index — the position in the body's own signature.
+         *
+         * @remarks
+         * A `Scalar` means the argument IS a value; an {@link IRange} means a container whose members
+         * the body reads itself (a reference materializes on demand); a {@link Lambda} means a callable.
+         *
+         * At a REPEATING parameter (`Repeating<T>`, or a rest parameter) this is the ARRAY of that
+         * group's values — one entry per argument the caller wrote — and {@link getRepeatingArgsAt} is the
+         * per-argument view of the same thing. Indexing by parameter rather than by call position is
+         * what lets a body ask its questions in the vocabulary it declared:
+         *
+         * ```typescript
+         * // IFS(condition: Repeating<[logicalTest: boolean, logicalTrue: AcceptError<any>]>)
+         * args.getRawAt(0);                       // [test1, value1, test2, value2, …]
+         * args.getRepeatingArgsAt(0).getRawAt(0);     // test1
+         * ```
+         *
+         * **Under a lift** the call broadcasts and the body runs once per output cell; this reports the
+         * value for THIS invocation — the member at the current broadcast position for a lifted argument,
+         * the whole argument for one that is not lifting. That is what every identified caller wants: a
+         * body checking for a boolean must see the member, not the array around it.
+         *
+         * One boundary is worth knowing: under a lift at a parameter that declares a CONCRETE scalar
+         * type, the member has already been converted by that declaration, so the raw and coerced answers
+         * coincide there. At the `Scalar` slots this interface exists for, nothing coerces and the value
+         * is the member exactly as the caller's range holds it.
+         */
+        getRawAt(index: number): IFunctionArguments.RawArg | IFunctionArguments.RawArg[];
+        /**
+         * A nested view over one REPEATING parameter's arguments, so a body can ask the same questions
+         * one level down — `getRepeatingArgsAt(0).isOmittedAt(1)`.
+         *
+         * @param index The PARAMETER index of the repeating group (or rest parameter).
+         *
+         * @remarks
+         * The nested view is FLAT over the group's arguments: a period-2 group repeated three times reads
+         * as six, in call order. That is where "which one was omitted" has an answer at all — the group
+         * as a whole cannot be omitted, only one of its arguments can.
+         *
+         * At a non-repeating parameter this returns an EMPTY view (`getLength()` of 0) rather than
+         * throwing, so a body that folds over its groups needs no special case.
+         */
+        getRepeatingArgsAt(index: number): IFunctionArguments;
+        /**
+         * True for an OMITTED argument — one the caller supplied EMPTY, as the trailing comma of
+         * `CUMIPMT(,120,100000,13,24,0)`.
+         *
+         * @remarks
+         * There are THREE positions, not two, and Excel answers each differently:
+         *
+         * | form | position | Excel |
+         * | --- | --- | --- |
+         * | `CUMIPMT(0.01,120,100000,13,24)` | ABSENT | refused at entry |
+         * | `CUMIPMT(,120,100000,13,24,0)` | **OMITTED** | `#N/A` |
+         * | `CUMIPMT(0.01,120,100000,13,24,E1)`, E1 blank | a blank CELL | the ordinary answer |
+         *
+         * This separates the middle row from the other two. ABSENT is `index >= getLength()`; a blank
+         * cell is an ordinary value the caller pointed at and is not omitted.
+         */
+        isOmittedAt(index: number): boolean;
+    }
+
+    /**
+     * {@inheritDoc IFunctionArguments}
+     *
+     * @see
+     * ### **Interface**
+     *
+     * {@link IFunctionArguments}
+     */
+    export namespace IFunctionArguments {
+        /**
+         * One argument as the caller wrote it — a value, a container, a callable, or nothing.
+         *
+         * @remarks
+         * `undefined` is an OMITTED or ABSENT argument; `null` is a blank, which is a value.
+         */
+        type RawArg = Scalar | IRange | Lambda | undefined;
+    }
+
     /**
      * Collections of {@link IFunction}.
      */
@@ -14021,7 +14513,9 @@ declare global {
          * @remarks
          * This has no counterpart in Excel; it is ours and applies to links opened in a browser.
          *
-         * @defaultValue `_self` for a location within this workbook, otherwise `_blank`.
+         * @defaultValue `_self` for a location within this workbook or a `mailto:`/`tel:`/`sms:`
+         * address (handled by another application, so there is nothing to show in a new tab),
+         * otherwise `_blank`.
          */
         getTarget(): string;
         /**
@@ -16363,8 +16857,13 @@ declare global {
     export namespace IProtectedRangeCollection {
         /**
          * Options for adding an {@link IProtectedRange}.
+         *
+         * @remarks
+         * `replaceExisting` redefines the entry at `index` when it covers exactly the same ranges; the
+         * entry keeps its name unless a free one is supplied — see
+         * {@link IAnchored.AddOptions.replaceExisting}.
          */
-        interface AddOptions extends IProtectedRange.Properties, ITransaction.OperationOptions {
+        interface AddOptions extends IProtectedRange.Properties, IAnchored.AddOptions {
         }
         /**
          * Options for searching for {@link IProtectedRange}s.
@@ -16805,11 +17304,28 @@ declare global {
          */
         filter<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => MaybeError<boolean>, options?: IRange.TraversalAxis | IRange.IteratorOptions): this;
         /**
-         * Returns the values as an array of values.
+         * Linearizes the range into a single column by flattened ordinal — the member at ordinal `i`
+         * lands at row `i`, column 0.
          *
          * @param options {@link IRange.IteratorOptions}
+         *
+         * @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.
+         *
+         * `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
+         * paired position by position — see {@link alignValues}.
+         *
+         * `options.includeEmpty` has no meaning here and is ignored: a range is inherently sparse, so
+         * an empty position is simply absent. Sparsity is preserved and nothing is materialized.
+         *
+         * Equivalent to `reshape(rows * columns, 1)`, which is where the ordinal rule is stated.
+         *
+         * @see {@link getValuesFlat} for the same linearization as a JS array.
          */
-        flatten<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
+        flatten(options?: IRange.IteratorOptions): this;
         /**
          * Iterates over the cells within the range, applying the provided callback function to each cell.
          *
@@ -16887,6 +17403,16 @@ declare global {
          * @param options {@link IRange.ValueOptions}
          */
         getValueAt<TS extends Scalar = T>(rowIndex: number, colIndex: number, options?: IRange.ValueOptions): TS;
+        /**
+         * Returns the members as a flat JS array.
+         *
+         * @param options {@link IRange.IteratorOptions}
+         *
+         * @remarks
+         * The array form of {@link flatten}. Skips empty members unless `includeEmpty` is set, where
+         * `flatten` keeps them as holes in a range.
+         */
+        getValuesFlat<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
         /**
          * Returns the number of columns of the range.
          */
@@ -22094,6 +22620,11 @@ declare global {
             readonly Quarters5: "5Quarters";
             readonly Rating5: "5Rating";
             readonly Boxes5: "5Boxes";
+            /**
+             * Not a set to apply — the x14 name Excel writes for a band whose custom icon is
+             * "No Cell Icon" (`iconSet="NoIcons" iconId="0"`). It holds zero icons.
+             */
+            readonly NoIcons: "NoIcons";
         };
         type IconSet = typeof IconSet[keyof typeof IconSet];
     }
@@ -27899,6 +28430,11 @@ declare global {
         getCpuCount(): number;
         getMemory(): number;
         isEval(): boolean;
+        /**
+         * `true` when the licensed product may run `feature` without the license watermark: a valid
+         * license with no exceptions, or an evaluation on localhost / in a dev build. An evaluation on
+         * any other host answers `false` so the watermark shows.
+         */
         isValidFor: (feature: string) => boolean;
         getDeveloperCount(): number;
         getType(): string;
@@ -28306,6 +28842,7 @@ declare global {
         c?: boolean;
         p?: MinifiedParameter[];
         r?: MinifiedValue;
+        x?: CompatFeature[];
     }
 
     export type MinifiedDeclarations = {
@@ -29216,6 +29753,28 @@ declare global {
      */
     export type Repeating<T> = T[];
 
+    /**
+     * Resolves a `@compat` feature name, CASE-INSENSITIVELY, to its canonical spelling.
+     *
+     * @param name The name as the author wrote it.
+     * @returns The canonical name, or `null` when no feature goes by it.
+     *
+     * @remarks
+     * Authors write `@compat noReferenceLift`; `@Compat NOREFERENCELIFT` means the same thing. Only
+     * the canonical spelling is ever stored, so the declaration a build emits does not depend on how
+     * the tag was typed.
+     */
+    export function resolveCompatFeature(name: string): CompatFeature | null;
+
+    /**
+     * Resolves a `@compat` name — a feature or a family alias — CASE-INSENSITIVELY, to the canonical
+     * features it turns on.
+     *
+     * @param name The name as the author wrote it.
+     * @returns The canonical features, or `null` when no feature or alias goes by that name.
+     */
+    export function resolveCompatFeatures(name: string): readonly CompatFeature[] | null;
+
     /**
      * Flatten a locale's declared `inherit` into a concrete lookup order, most-specific first.
      *