@sheetxl/primitives 0.8.0-beta.1 → 0.8.0-beta.10

package/types/src/IFunctionArguments.d.ts

@@ -1,6 +1,8 @@
 import { Scalar } from './Scalar';
+import { ValueKind } from './ValueKind';
 import { IRange } from './IRange';
 import { Lambda } from './Lambda';
+import { IFunction } from './IFunction';
 /**
  * The current call's arguments, as the body sees them — argument **reflection**.
  *
@@ -13,7 +15,7 @@ import { Lambda } from './Lambda';
  * - 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
+ * 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
  * every slot; the difference is not the values, it is that `CUMIPMT`'s slots are `any` and its
@@ -23,8 +25,8 @@ import { Lambda } from './Lambda';
  *
  * | question | answers |
  * | --- | --- |
- * | *what was supplied* | {@link getLength}, {@link isOmittedAt} |
- * | *what it is* | {@link getRawAt} |
+ * | *what was supplied* | {@link getLength}, {@link getKindAt} |
+ * | *what it is* | {@link getRawAt}, {@link getKindAt} |
  *
  * 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,
@@ -40,7 +42,7 @@ import { Lambda } from './Lambda';
  * ```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
+ *   if (args.getKindAt(0) === ValueKind.Omitted) return FormulaError.BuiltIn.NA; // `CUMIPMT(,120,…)`
  *   const asNumber = FormulaContext.parseAsNumber(args.getRawAt(0) as Scalar);  // TRUE is #VALUE!
  *   // …
  * }
@@ -88,6 +90,10 @@ export interface IFunctionArguments {
      * 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.
+     *
+     * A reference UNION (`(A1:A3,C1:C3)`) is an array too — one `IReferenceRange` per area — which
+     * is how a body whose slot took the areas apart can still tell one argument's union from two
+     * arguments (`SUMPRODUCT` refuses the first and accepts the second).
      */
     getRawAt(index: number): IFunctionArguments.RawArg | IFunctionArguments.RawArg[];
     /**
@@ -106,22 +112,86 @@ export interface IFunctionArguments {
      */
     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)`.
+     * The KIND of the argument at `index` — the total discriminator over {@link getRawAt}'s value.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
      *
      * @remarks
-     * There are THREE positions, not two, and Excel answers each differently:
+     * Every raw argument is exactly one of a closed set of kinds ({@link ValueKind}), and this
+     * answers without materializing anything — a reference stays coords underneath. The scalar
+     * kinds ARE `ScalarType` values, so `getKindAt(i) === ScalarType.Boolean` reads naturally.
+     *
+     * Under a lift this reports THIS invocation's value, like {@link getRawAt} — except the
+     * {@link ValueKind.Omitted} answer, which is a fact about the CALL (the caller wrote an empty
+     * comma) and does not change per broadcast position. At a REPEATING parameter it answers for
+     * the group's FIRST argument; per-argument kinds are one level down —
+     * `getRepeatingArgsAt(i).getKindAt(j)`.
      *
-     * | form | position | Excel |
+     * There are THREE argument positions:
+     *
+     * | form | position | answer |
      * | --- | --- | --- |
-     * | `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 |
+     * | `CUMIPMT(0.01,120,100000,13,24)` | never wrote a 6th | `Omitted` here — the POSITION fact is {@link getLength} (`index >= getLength()`), not a kind |
+     * | `CUMIPMT(,120,100000,13,24,0)` | the empty comma | {@link ValueKind.Omitted} |
+     * | `CUMIPMT(…,E1)`, E1 blank | a blank CELL | {@link ValueKind.Reference} — blankness is the cell's value, not the argument |
+     *
+     * The kind is the argument's own and it survives what it passes through:
+     * `VLOOKUP(10,10,1,TRUE)` is `#N/A` where `VLOOKUP(10,{10},1,TRUE)` is 10 — scalar vs 1x1
+     * array; `TYPE(IF(TRUE,10))` is 1 where `TYPE(IF(TRUE,{10}))` is 64 — a selector carries the
+     * kind through in both directions.
+     */
+    getKindAt(index: number): ValueKind;
+    /**
+     * True when the argument at `index` is DIRECT — Excel's "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.
+     *
+     * @remarks
+     * The derived predicate over {@link getKindAt}: true exactly when the kind is one of the
+     * `ScalarType` members. A blank (`ScalarType.Null`) IS a value and is direct; an omitted
+     * argument, a reference, an array and a callable are not. Directness is what the
+     * direct-vs-member coercion rules key on (`SUM(1,TRUE)` is 2 where `SUM({1,TRUE})` is 1), so
+     * a body speaking that vocabulary can ask in it.
+     */
+    isDirectAt(index: number): boolean;
+    /**
+     * How many AREAS the argument at `index` covers — 1 for an ordinary reference, more for a
+     * union (`(A1:A5,B1:B2)`), and 0 for anything that is not a reference at all.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * {@link getKindAt} deliberately cannot answer this: a union IS a reference and reports
+     * {@link ValueKind.Reference}, the same as `A1:A5`. This is the question a body asks when the
+     * union is the thing it must decide about, and the three possible answers all come from asking
+     * it — flatten every area, refuse, or `#REF!`.
+     *
+     * Only a {@link IFunction.ParameterTypeJSON.reportType} slot can see a union at all; at every
+     * other slot the marshaller has already answered `#VALUE!`.
+     */
+    getAreaCountAt(index: number): number;
+    /**
+     * The functions the argument at `index` holds, in row-major order — or `null` unless it holds
+     * nothing but functions.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * A formula can pass a function as a value: `LAMBDA(x, x * 2)`, or a built-in by name, as `SUM`
+     * is in `BYROW(A1:C3, SUM)`. A `Lambda` parameter takes ONE such value. This is for an untyped
+     * parameter that also takes an ARRAY of them, as `HSTACK(SUM, AVERAGE)` makes.
+     *
+     * The argument's shape is its own: {@link getKindAt} is `Lambda` for one function and `Array`
+     * for several, and {@link getRawAt} is that array. A function value IS an {@link IFunction}: a
+     * built-in by name answers as the registry's function does, and a `LAMBDA` is one whose
+     * {@link IFunction.isLambda} is `true`. A body whose untyped parameter holds the value reads the
+     * functions from it directly; this is reflection, for when the declaration does not hand it over.
      *
-     * 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.
+     * Nothing is collected until every member has proved to be a function, so a data range given by
+     * mistake costs one member.
      */
-    isOmittedAt(index: number): boolean;
+    getFunctionsAt(index: number): readonly IFunction[] | null;
 }
 /**
  * {@inheritDoc IFunctionArguments}
@@ -136,7 +206,8 @@ export declare 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.
+     * `undefined` is an OMITTED or ABSENT argument; `null` is a blank, which is a value. A reference
+     * union is delivered as `RawArg[]` — one reference per area (see {@link IFunctionArguments.getRawAt}).
      */
     type RawArg = Scalar | IRange | Lambda | undefined;
 }

package/types/src/IRange.d.ts

@@ -69,11 +69,16 @@ export interface IRange<T extends Scalar = Scalar> {
     uniqueIndices(axis?: IRange.Axis, exactlyOnce?: boolean): number[];
     /**
      * Applies a callback function to elements from this range and another range or a scalar,
-     * using NumPy-style broadcasting.
+     * using Excel's broadcasting rules. This is the two-operand special case of {@link zip}:
+     * `a.broadcast(b, f)` is `a.zip([b], ([x, y]) => f(x, y))`.
      *
-     * **Broadcasting Rules:**
-     * - If `other` is a scalar, it is broadcasted to match the shape of this range.
-     * - If `other` is a range, both ranges must have the same length.
+     * **Broadcasting Rules** (the same as {@link zip}):
+     * - A scalar or a 1×1 range fills any shape: (1×1) + (3×4) → (3×4)
+     * - Same shapes pair position by position: (3×4) + (3×4) → (3×4)
+     * - A dimension of 1 tiles across the other operand's: (3×1) + (3×4) → (3×4)
+     * - Incompatible shapes (neither equal nor 1) throw, unless `misalignValue` is set, in which
+     *   case the result is the union shape and every position outside the intersection holds
+     *   `misalignValue`. Here the pad is a RESULT; in {@link zip} it is an ARGUMENT.
      *
      * @param other The other range or scalar to broadcast with.
      * @param callbackFn The function to apply to corresponding elements.
@@ -82,11 +87,10 @@ export interface IRange<T extends Scalar = Scalar> {
      * @returns A new range with the broadcasted results.
      *
      * @remarks
-     * Broadcasting rules (NumPy-style):
-     * - Scalar broadcasts to any shape: (1×1) + (3×4) → (3×4)
-     * - Same shapes work: (3×4) + (3×4) → (3×4)
-     * - Trailing dimensions of 1 broadcast: (3×1) + (3×4) → (3×4)
-     * - Incompatible shapes error: (3×4) + (2×3) → Error (unless misalignValue set)
+     * Iteration is sparse: the positions visited are the union of both operands' stored cells. A
+     * position empty on both sides has one answer, and a callback that reads only its two values
+     * (`callbackFn.length === 2`) receives that answer computed ONCE and written as runs; a callback
+     * that asks for `coords` or `range` is called per position instead.
      */
     broadcast<TS extends Scalar = T>(other: IRange | TS, callbackFn: (a: TS, b: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.BroadcastOptions): this;
     /**
@@ -243,6 +247,18 @@ export interface IRange<T extends Scalar = Scalar> {
      * If the callback returns an error this will propagate the error as the value with the error.
      */
     filter<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => MaybeError<boolean>, options?: IRange.TraversalAxis | IRange.IteratorOptions): this;
+    /**
+     * The first error member in row-major order, or `null` when there is none — the identity that
+     * propagates when a body refuses a range with an error inside it:
+     * `if (range.hasError()) return range.firstError();`.
+     *
+     * @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
+     * lookup, whose members pass through or are never read, needs no line at all.
+     */
+    firstError(): FormulaError.Known | null;
     /**
      * Linearizes the range into a single column by flattened ordinal — the member at ordinal `i`
      * lands at row `i`, column 0.
@@ -353,6 +369,20 @@ export interface IRange<T extends Scalar = Scalar> {
      * `flatten` keeps them as holes in a range.
      */
     getValuesFlat<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
+    /**
+     * Returns the position of the first member equal to `value`, or `-1` when there is none.
+     *
+     * @param value The value to find.
+     * @param options {@link IRange.IndexOfOptions}
+     *
+     * @remarks
+     * Equality is the `=` operator's: text is case-insensitive, and no value matches one of another
+     * type (`1` does not match `"1"`, nor `TRUE` `1`). Empty members, errors and rich data are never
+     * a match. The position is the offset along a row or column vector, and the row-major offset
+     * within a larger range. This is `MATCH(value, range, 0)` less one, and a range read by many
+     * lookups is indexed once rather than scanned per call.
+     */
+    indexOf(value: Scalar, options?: IRange.IndexOfOptions): number;
     /**
      * Returns the number of columns of the range.
      */
@@ -372,7 +402,7 @@ export interface IRange<T extends Scalar = Scalar> {
      * outputs and `map` cannot know what type they are. Use {@link IRange.toType} on the result if
      * you do know. (`options.type` still applies to the values handed TO the callback.)
      */
-    map<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.IteratorOptions): this;
+    map<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.MapOptions): this;
     /**
      * Returns a new range where each cell is replaced with the value from `ifTrues`
      * where the corresponding `conditions` value is strictly `true`.
@@ -629,40 +659,54 @@ export interface IRange<T extends Scalar = Scalar> {
      */
     values<TS extends Scalar = T>(options?: IRange.IteratorOptions): IterableIterator<TS>;
     /**
-     * Iterates over this range and one or more other ranges or scalars in lockstep,
-     * calling the provided function with the broadcast-resolved values at each position,
-     * and returns a new range containing the results.
+     * Aligns this range with any number of other ranges or scalars under Excel's broadcasting
+     * rules, calls `callbackFn` with the aligned values at each position, and returns the results as
+     * a new range of the broadcast shape. This is the N-ary form of {@link broadcast}, and the numpy
+     * idiom "align once, apply the kernel, never index"
+     * (`np.frompyfunc(f, n, 1)(*np.broadcast_arrays(...))`).
+     *
+     * **Broadcasting Rules** (Excel's; {@link broadcast} shares them):
+     * - A scalar or a 1×1 range FILLS: it is the same value at every position.
+     * - A dimension of 1 TILES across the largest extent in that dimension (`tile`, default on).
+     * - A shorter dimension PADS: past its extent the operand contributes `misalignValue`
+     *   (default `#N/A`). The pad is an ARGUMENT, reaching the callback in that operand's slot for
+     *   the callback to decide what it means; it is not a result written around the callback.
+     * - The output is `max(rows)` × `max(cols)` over the operands, anchored at this range's origin.
+     *
+     * **Iteration is sparse.** The positions visited are the UNION of the operands' stored cells
+     * after broadcast mapping; an operand with no cell at a visited position contributes its empty
+     * value (`null`, or the empty of `type`). Where EVERY shaped operand is blank the answer depends
+     * only on which operands are padded there, so those positions form REGIONS of equal padding,
+     * one per combination of operand extents, and `blankRegions` says how they are answered:
+     * `'each'` (default) calls the callback per position with its coordinates; `'once'` calls it once
+     * per region (the pandas `SparseArray` rule: the kernel runs once on `fill_value` and per stored
+     * entry otherwise) — the unpadded region's answer is what the result's empty positions read as,
+     * a padded region is written as runs. A region call carries `coords` of
+     * `{ rowIndex: -1, colIndex: -1 }`: it answers for many positions and no one of them. Under
+     * `'once'` a stretch of stored positions holding one value across every operand is one call too.
+     * An operand's own empty positions read as its empty value (a `fillEmpty`, an earlier
+     * elementwise result) and are never visited one by one.
+     *
+     * @param others Additional ranges or scalar values to align with this range, in argument order.
+     * @param callbackFn Called at each position with the aligned values (`values[0]` is this
+     *   range's, `values[i + 1]` is `others[i]`'s), the position relative to the output, and this
+     *   range. Returns the output value for that position. `values` is ONE buffer reused across
+     *   calls (the ufunc inner-loop rule): read it, do not retain it.
+     * @param options {@link IRange.ZipOptions}. `type` reads EVERY operand's members, and the
+     *   empty, through that type; it defaults to this range's own type, as {@link broadcast} does.
+     *   Pass `type: null` to read every operand raw.
+     * @returns A new, untyped range of the broadcast shape (the values are the callback's, so this
+     *   range's type does not describe them).
      *
-     * Broadcast semantics follow Excel conventions:
-     * - A 1×1 scalar or range broadcasts to fill any shape.
-     * - A 1×N or N×1 range broadcasts to fill the missing dimension.
-     * - Ranges with incompatible shapes produce a `#VALUE!` error.
-     *
-     * @param others Additional ranges or scalar values to zip with this range.
-     * @param callbackFn Called at each position with the broadcast-resolved values from
-     *   all ranges (`values[0]` is from `this`, `values[1]` onward are from `others`),
-     *   the current cell coordinates, and the original range. Returns the output value
-     *   for that position.
-     * @param options {@link IRange.IteratorOptions}
-     * @returns A new range of the same shape as the broadcast result.
+     * @example
+     * // A 3×1 beside a 1×3 is 3×3: rows tile from the first, columns from the second.
+     * const sums = a.zip([b, 10], ([x, y, k]) => (x as number) + (y as number) + (k as number));
      */
-    zip(others: (IRange | Scalar)[], callbackFn: (values: Scalar[], coords: IRange.CellCoords, range: IRange<T>) => Scalar, options?: IRange.IteratorOptions): this;
+    zip(others: (IRange | Scalar)[], callbackFn: (values: Scalar[], coords: IRange.CellCoords, range: IRange<T>) => Scalar, options?: IRange.ZipOptions): this;
     /**
      * Returns a string representation of the range.
      */
     toString(): string;
-    /**
-     * Returns `true` if the range is a literal range from a parameter.
-     */
-    isLiteral(): boolean;
-    /**
-     * Returns `true` if the range is a scalar.
-     */
-    isScalar(): boolean;
-    /**
-     * Returns `true` if the range is a vector (1D) either row or column.
-     */
-    isVector(): boolean;
     /**
      * Returns `true` if the range is empty.
      */
@@ -695,6 +739,17 @@ export declare namespace IRange {
     /**
      * Options for controlling iteration behavior.
      */
+    /**
+     * Options for {@link IRange.indexOf}.
+     */
+    interface IndexOfOptions {
+        /**
+         * Search from the last member back, answering the last match.
+         *
+         * @defaultValue `false`
+         */
+        reverse?: boolean;
+    }
     interface IteratorOptions extends IRange.ValueOptions {
         /**
          * The direction of the iteration.
@@ -732,6 +787,24 @@ export declare namespace IRange {
          * If passing a large bound care must be taken.
          */
         includeEmpty?: boolean;
+        /**
+         * Skips rows of the range: given the next row that would be read, answers the row to read
+         * instead - the same row when it is read, or the next one that is (the previous, when
+         * `reverse`).
+         *
+         * @param index The 0-based row about to be read.
+         * @param reverse Whether the read runs from the last row back.
+         * @returns The row to read, at or past `index`.
+         *
+         * @remarks
+         * A skipped cell is not visited, reads as empty and is left out of the statistics; the shape
+         * of the range is unchanged. `SUBTOTAL` reads a range this way when it skips hidden rows.
+         */
+        processRowSkip?: (index: number, reverse?: boolean) => number;
+        /**
+         * Skips columns of the range, as {@link processRowSkip} skips rows.
+         */
+        processColumnSkip?: (index: number, reverse?: boolean) => number;
         /**
          * Useful for callback functions that want a this.
          */
@@ -848,6 +921,8 @@ export declare namespace IRange {
          *   - It expands the result to the **union of both range sizes**.
          *   - Any cells that do not have valid corresponding values from the inputs
          *     will be filled with `misalignValue` instead of causing an error.
+         * - `zip()`, `mask()` and `choose()` always pad and default it to `#N/A`; in `zip()` the pad
+         *   is delivered to the callback as that operand's value rather than written as the result.
          *
          * @example
          * // Throws an error if A and B are not naturally broadcast-compatible
@@ -869,6 +944,53 @@ export declare namespace IRange {
          */
         otherType?: ScalarType;
     }
+    /**
+     * Options for {@link IRange.map}.
+     */
+    interface MapOptions extends IRange.IteratorOptions {
+        /**
+         * How the positions the range does not store are answered.
+         *
+         * @defaultValue `'each'`
+         *
+         * @remarks
+         * `'each'` is the sparse walk: an empty position is not visited (or, with `includeEmpty`,
+         * visited with its coordinates). `'once'` calls the callback a single time for every empty
+         * position, with `coords` of `{ rowIndex: -1, colIndex: -1 }` and the value an empty reads
+         * as, and every one of them takes that answer — the {@link IRange.zip} rule. Under `'once'` a
+         * stretch of stored positions holding one value is also one call; a callback that reads only
+         * its value gets that on its own (it cannot tell), and one that reads `coords` opts in here.
+         */
+        blankRegions?: 'each' | 'once';
+    }
+    /**
+     * Options for {@link IRange.zip}.
+     */
+    interface ZipOptions extends IRange.ValuesOptions {
+        /**
+         * Whether a dimension of 1 tiles across the largest extent in that dimension.
+         *
+         * @defaultValue `true`
+         *
+         * @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.
+         */
+        tile?: boolean;
+        /**
+         * How the positions where EVERY shaped operand is blank are answered.
+         *
+         * @defaultValue `'each'`
+         *
+         * @remarks
+         * Such positions form regions of equal padding (see {@link IRange.zip}). `'each'` visits every
+         * one with its coordinates; `'once'` calls the callback a single time per region, with
+         * `coords` of `{ rowIndex: -1, colIndex: -1 }`, and writes the region as runs. An explicit
+         * option rather than a callback-arity gate, so a callback that reads `coords` for the positions
+         * it IS given can still have the blanks answered in one call.
+         */
+        blankRegions?: 'each' | 'once';
+    }
     /**
      * Options used during masking.
      */
@@ -1016,6 +1138,15 @@ export declare namespace IRange {
         rowEnd: number;
         /**
          * An optional identifier for the 2D space these coordinates are relative to.
+         *
+         * @remarks
+         * `scope` was added after the coords reuse/scratch patterns were established, so it is the
+         * field a reused object is most likely to carry STALE. The contract: a function that writes
+         * its result into a caller-supplied reuse object must write `scope` unconditionally —
+         * `null` when the result is unscoped, never left over from the previous occupant
+         * (a leaked scope silently re-targets the coords at another sheet's grid). Writing it
+         * conditionally is only safe on a freshly created object. Geometry-only helpers that
+         * never read or write `scope` (CoordUtils) are exempt; their scope-aware wrappers own it.
          */
         scope?: string | null;
     }
@@ -1033,6 +1164,7 @@ export declare namespace IRange {
         rowIndex: number;
         /**
          * An optional identifier for the 2D space these coordinates are relative to.
+         * See the remark on {@link Coords.scope} for the reuse-object contract.
          */
         scope?: string | null;
     }

package/types/src/IRangeStats.d.ts

@@ -19,6 +19,20 @@ import { FormulaError } from './FormulaError';
  * 5. Quick introspection without triggering a full range scan
  */
 export interface IRangeStats {
+    /**
+     * Returns the bounding box of the cells these stats cover, in the coordinates of the scanned
+     * grid.
+     *
+     * @returns The smallest rectangle containing every covered coordinate, or `null` when the
+     * stats cover nothing.
+     *
+     * @remarks
+     * Stats over several areas (a multi-area range, or a composite over several ranges) return the
+     * union box, which can include cells outside every area — and a composite's children may sit
+     * on different sheets, so its box is a shape, not an address. `getSize()` is the exact cell
+     * count; this is where those cells are.
+     */
+    getCoords(): IRange.Coords | null;
     /**
      * Returns the total number of cells in the range, including empty cells.
      *
@@ -146,7 +160,8 @@ export interface IRangeStats {
      *
      * - Every requested type (all types when omitted) is present with an explicit count —
      *   a `0` is a fact about the range, a missing key would be ambiguous.
-     * - Blanks report under {@link ScalarType.Null}: total cells minus non-empty values.
+     * - Blanks report under {@link ScalarType.Null}: total cells minus non-empty values. A cell the
+     *   range skips ({@link IRange.IteratorOptions.processRowSkip}) is not a blank; it is not counted.
      * - Never throws on error values — errors are population here, not faults — regardless of
      *   the `onError` iterator policy the stats were created with.
      */
@@ -242,7 +257,9 @@ export declare namespace IRangeStats {
         /**
          * Returns the k-th largest numeric value (1-based).
          *
-         * @param k The rank of the value to return, where 1 is the largest value. Must be a positive integer.
+         * @param k The rank of the value to return, where 1 is the largest value. A fractional rank
+         *          becomes a 0-based index before it truncates — over five values `k = 2.5` is the
+         *          THIRD largest, not the second.
          * @returns `null` if k is out of range.
          *
          * @remarks
@@ -252,7 +269,8 @@ export declare namespace IRangeStats {
         /**
          * Returns the k-th smallest numeric value (1-based).
          *
-         * @param k The rank of the value to return, where 1 is the smallest value. Must be a positive integer.
+         * @param k The rank of the value to return, where 1 is the smallest value. A fractional rank
+         *          becomes a 0-based index before it truncates.
          * @returns `null` if k is out of range.
          *
          * @remarks
@@ -434,6 +452,19 @@ export declare namespace IRangeStats {
          * This is a convenience method (visitedCount < totalCount)
          */
         isTruncated(): boolean;
+        /**
+         * Returns the bounding box of a value's occurrences, in the coordinates of the scanned grid.
+         *
+         * @param value The value to look up
+         * @returns The smallest rectangle containing every occurrence, or `null` when the value was
+         * not found, is blank, or the frequencies were merged from several ranges (no single grid).
+         *
+         * @remarks
+         * Tracked by the same scan that counts, so it costs nothing extra. A box whose cell count
+         * equals {@link getFrequency} is a contiguous block — the value lives in exactly that
+         * rectangle; a larger box means the occurrences are scattered within it.
+         */
+        getExtent(value: Scalar): IRange.Coords | null;
     }
     /**
      * Options for finding top values in a range.

package/types/src/IRuntime.d.ts

@@ -54,9 +54,32 @@ export interface IRuntime {
      */
     getOS(): string;
     /**
-     * Returns the current timestamp as a serialized number.
+     * Returns the clock this runtime reads, as epoch milliseconds.
+     *
+     * @remarks
+     * A workbook's own runtime answers the current commit's timestamp, so every cell of a
+     * calculation pass agrees and collaborators on that commit agree with each other. A runtime
+     * built by a host answers whatever that host supplied — a pinned clock makes `NOW` and `TODAY`
+     * reproducible, and an unpinned one is the wall clock, which advances between reads.
      */
     getNow: () => number;
+    /**
+     * Returns a random number in `[0, 1)` — one per calculation pass, as {@link getNow} is one
+     * clock reading per pass.
+     *
+     * @remarks
+     * This is not a cell's value. Each cell's draw is derived from this one, its position and which
+     * draw it is within that cell, so cells that do not depend on each other — which the engine is
+     * free to evaluate in any order — get the values their positions earn rather than the values
+     * their turn earned.
+     *
+     * Pinning it therefore pins `RAND`, `RANDBETWEEN` and `RANDARRAY`, exactly as pinning
+     * {@link getNow} pins `NOW` and `TODAY`. Left alone it is `Math.random`, drawn afresh each pass,
+     * so volatiles move on every recalculation.
+     *
+     * Values reproduce within one release, not across releases.
+     */
+    getRandom: () => number;
     /**
      * Returns the current user or `null` if no user information is provided.
      */

package/types/src/Lazy.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Declares a parameter the engine may hand over UNEVALUATED — the argument's subtree is not run
+ * before the call, and it runs only if this call's answer needs it.
+ *
+ * @remarks
+ * An argument that is a bare reference has always been cheap to ignore: it resolves into a
+ * register and a body that never reads it never dereferences it. An argument that is an
+ * EXPRESSION is not — `IF(FALSE,B1+1,1)` evaluates `B1+1` before `IF` runs, so the untaken branch
+ * opens `B1` anyway. That is a correctness difference and not a cost one: a read is what decides
+ * a circular reference and what registers a volatile, so an arm nobody takes can report a cycle
+ * the sheet does not have.
+ *
+ * The marker is what closes it, and it is a CONTRACT rather than an inference. Nothing in
+ * JavaScript intercepts a plain parameter read, so a body holding a deferred value is only safe
+ * while it never touches it — which the declaration has to say out loud:
+ *
+ * ```ts
+ * export function IF(
+ *   logicalTest: boolean,
+ *   valueIfTrue: Lazy<AcceptError<any>>,
+ *   valueIfFalse: Lazy<AcceptError<any>, false>
+ * ): any {
+ *   return logicalTest ? valueIfTrue : valueIfFalse;
+ * }
+ * ```
+ *
+ * The parameter is ALWAYS an {@link ILazy} handle and never a union with the bare value, so the
+ * body has two things it may do with it and the type says which is which:
+ *
+ * - **return it unread**, which is what every branch-selecting function does. The engine
+ *   recognizes its own handle coming back as the call's result and evaluates that subtree then.
+ * - **read it** with {@link ILazy.getValue}, which forces the subtree in place. Synchronous only:
+ *   the engine is mid-formula there and has no way to wait, so an ASYNC subtree at a forced
+ *   handle is an error rather than a wrong answer.
+ *
+ * Only the RESULT positions are marked. A condition, an index and a case value are eager, which
+ * is what keeps `AND(FALSE,A1)` a circular reference: laziness is a property of what the function
+ * READS, not of the syntax around it.
+ *
+ * The engine may DECLINE to defer at any time and hand the body a handle that is already full —
+ * an absent argument, an async subtree, a lift that needs every arm anyway. `getValue()` then
+ * returns the value it was built with. The author cannot tell the two apart and must not try.
+ *
+ * @typeParam T - what the argument evaluates to; the marker is otherwise transparent.
+ * @typeParam V - what an ABSENT argument means, as a literal. It replaces the `= false`
+ *   initializer an ordinary parameter would carry, which cannot typecheck against a handle;
+ *   declaring it makes the parameter optional and the engine supplies the value, so the body
+ *   still sees nothing but a handle.
+ *
+ * @see {@link IFunction.ParameterTypeJSON.lazy}
+ */
+export type Lazy<T, V = never> = ILazy<T | V>;
+/**
+ * The handle a {@link Lazy} parameter receives: an argument's subtree, anchored at the calling
+ * cell, that has either not been evaluated yet or has been evaluated already.
+ *
+ * @remarks
+ * The brand exists for the same reason {@link Lambda}'s does — the value-layer sites (coercion,
+ * the operators, a range's typed read, a cell's final value) RECOGNIZE a handle and refuse it, so
+ * that one can never reach a grid, a spill or a named-formula result. A handle is only ever a
+ * live call's argument.
+ */
+export interface ILazy<T = any> {
+    /** The brand itself — the property every recognizing site reads. */
+    readonly isLazy: true;
+    /**
+     * Evaluates the argument and answers its value, forcing the subtree where the engine deferred
+     * it and answering the value it already has where it declined to.
+     *
+     * Forced at most once: a second call answers the same value.
+     */
+    getValue(): T;
+}
+/** `true` for a deferred-argument handle — see {@link ILazy}. */
+export declare const isLazyValue: (value: unknown) => value is ILazy;
+//# sourceMappingURL=Lazy.d.ts.map