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

package/types/src/primitives/PrimitiveUtils.d.ts

@@ -150,7 +150,7 @@ isDirect: boolean, errors?: 'reject' | 'accept' | null): IRange | any[][] | Form
  * evaluated argument; see `isDirectArg` in `TypedFunction`.
  *
  * Two things it is NOT, both measured (`probe-direct-vs-literal.ps1`, pinned in
- * `functions2/coercion/DIRECT-VS-MEMBER.json`):
+ * `__tests__/functions/coercion/DIRECT-VS-MEMBER.json`):
  *
  * - **Not literalness.** `{1,TRUE}` and `A1:A2` behave IDENTICALLY (members of both are filtered),
  *   and the COMPUTED `A2>0` behaves like a typed `TRUE`. A container being a literal or a
@@ -171,28 +171,56 @@ export declare function addCoercedValue(context: IFormulaContext, coercedArr: Fi
 allowError: boolean, flatten: boolean, // indicates we should flatten
 errors?: 'reject' | 'accept' | null, // effective error policy (TypedFunction resolves the default)
 noMemberFilter?: boolean): FormulaError.Known | void;
+/**
+ * The depth-0 half of {@link addCoercedValue} for a SCALAR slot: `value` is already a single
+ * value — a typed or computed scalar, a blank, an error, rich data, or the member a one-cell
+ * reference was dereferenced to — never a container or coords. Same rules, same order, same
+ * verdicts as the general path, which still serves everything else; this exists so the common
+ * call (a number at a number slot) pays for no container questions.
+ *
+ * `isDirect` is the argument's own directness (a dereferenced cell is NOT direct): it gates the
+ * quoted-boolean parse, and nothing else — a scalar slot has no members, so the dereferenced
+ * value coerces with the direct rules exactly as it does in the general path (`ABS(A1)` is 1 for
+ * A1=TRUE).
+ */
+export declare function addCoercedScalar(context: IFormulaContext, coercedArr: FixedPackedArray, value: any, isDirect: boolean, scalarType: ScalarType | null, allowError: boolean, errors: 'reject' | 'accept' | null): FormulaError.Known | void;
 /**
  * Minimal validation used from the return value of functions.
  */
 /**
- * Makes a raw JS double look like an Excel one. Excel arithmetic has neither Infinity nor
- * subnormals, and this is the single rule that enforces both. Measured against Excel 16.0
- * (formula-tests: probe-num-overflow.ps1, probe-boundaries.ps1, probe-api-nonfinite.ps1):
- *
- * * ANY non-finite value is #NUM! — NaN and ±Infinity alike. `9E+307*2`, `9E+307+9E+307` and
- *   `9E+307/0.1` all report `ERROR.TYPE` 6, and a raw NaN or ±Infinity written through the
- *   Value2 API lands as #NUM! too. Infinity does NOT mean #DIV/0!: Excel never derives that
- *   error from a float, it raises it deliberately before dividing. Functions say so themselves
- *   by returning `FormulaError.BuiltIn.Div0`.
- * * a magnitude below the smallest NORMAL double flushes to ZERO, which also folds -0 to 0.
- *   `1E-300*2.224E-8` is 0 while `1E-300*2.226E-8` survives, and the flush lands before the next
- *   operator reads it — `=1/(1E-300*1E-100)` is #DIV/0!, not a huge number. The API agrees:
- *   writing `Double.Epsilon` reads back 0.
- *
- * Excel applies this at EVERY boundary, so SheetXL does too — `minCoerce` for a calculated
- * result, and the cell-write path for a value handed in through the API.
+ * Makes a raw JS double look like an Excel one: ANY non-finite value is #NUM! — NaN and
+ * ±Infinity alike. `9E+307*2`, `9E+307+9E+307` and `9E+307/0.1` all report `ERROR.TYPE` 6, and a
+ * raw NaN or ±Infinity written through the Value2 API lands as #NUM! too. Infinity does NOT mean
+ * #DIV/0!: Excel never derives that error from a float, it raises it deliberately before
+ * dividing. Functions say so themselves by returning `FormulaError.BuiltIn.Div0`.
+ *
+ * Measured against Excel 16.0 (formula-tests: probe-num-overflow.ps1, probe-boundaries.ps1,
+ * probe-api-nonfinite.ps1). This rule applies at every boundary; the SUBNORMAL rule does not —
+ * see {@link flushSubnormal}.
  */
 export declare function normalizeNumber(value: number): number | FormulaError.Known;
+/**
+ * Zeroes a magnitude below the smallest NORMAL double, which also folds -0 to 0.
+ *
+ * "Excel has no subnormals" is true of its ARITHMETIC and of its write path, and false of its
+ * function results — so this is a rule three callers apply deliberately rather than one the
+ * boundary applies to everything (measured 2026-08-30,
+ * `fn-battery/mathTrig/adhoc-subnormal-store`):
+ *
+ * * MULTIPLICATION, DIVISION and EXPONENTIATION flush. `1E-300*2.224E-8` is 0 while
+ *   `1E-300*2.226E-8` survives, `2^-1022/2` is 0, and the flush lands before the next operator
+ *   reads it — `=1/(1E-300*1E-100)` is #DIV/0!, not a huge number.
+ * * ADDITION and SUBTRACTION do NOT. With `Z1` holding 5E-324, `Z1+0`, `-Z1` and `Z1+Z1` all
+ *   keep the value, and `Z1*1` is 0.
+ * * A FUNCTION RESULT does not either, and it survives the cell it is stored in: `EXP(-745)` is
+ *   5E-324 and `EXP(-745)*1E300` is 4.94E-24. SUM, MIN, ABS, IF, INDEX and ROUND all pass it
+ *   through. EXP reaches zero only below -745.1332, the true IEEE underflow.
+ * * The API WRITE path flushes: `Double.Epsilon` set through `Value2` reads back 0.
+ * * The BOOLEAN reading flushes, and so does `SWITCH`'s comparison — both are tests against zero
+ *   (`IF(EXP(-745),…)` takes the false branch and `SWITCH(EXP(-745),0,…)` matches), which the
+ *   comparison OPERATORS do not do: `EXP(-745)=0` is FALSE.
+ */
+export declare function flushSubnormal(value: number): number;
 export declare function minCoerce(value: any, context?: IFormulaContext | null, type?: string): any;
 /**
  * Loads a (possibly nested) array literal into a sparse grid and returns the pieces a `Range`
@@ -219,8 +247,12 @@ export interface FixedPackedArray<T = any> {
 /**
  * V8 Optimization
  *
- * Is seems the new Array(length) because it uses holey arrays.
- * Push causes reallocation a bunch times.
+ * Builds an array that V8 keeps in `PACKED_ELEMENTS`, every slot set to `value`.
+ *
+ * A bare `new Array(length)` is holey, and each read from a holey array pays a
+ * hole check (~35% on a linear scan). Both branches here produce the same map;
+ * they differ only in how fast they build, and the threshold is the point where
+ * the per-call cost of `fill` stops dominating the per-element cost of `push`.
  *
  * This should be only used for reusable arrays where they are long lived
  * and need to be fast (and not resized (much)).
@@ -229,6 +261,11 @@ export declare function createPackedArray<T = any>(length: number, value?: T): T
 /**
  * Create a packed array but with undefined values.
  *
+ * `undefined` here is a real element in every slot, not a hole; the array is
+ * packed exactly as {@link createPackedArray} is. Kept separate rather than
+ * delegating because passing `undefined` as an argument would take the
+ * `value=null` default.
+ *
  * @see createPackedArray
  */
 export declare function createEmptyPackedArray<T = any>(length: number): T[];

package/types/src/primitives/Range.d.ts

@@ -18,21 +18,37 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     protected _localRangeStats: IRangeStats | null;
     /** The `options` {@link _localRangeStats} was built for — the memo's key. See `getStats`. */
     protected _localRangeStatsOptions: IRange.IteratorOptions | undefined;
-    constructor(runtime: IRuntime, values: ISparseGrid<Scalar>, coords: IRange.Coords | null, optionsIterator?: IRange.IteratorOptions | null, isLiteral?: boolean, isDirectScalar?: boolean);
+    /**
+     * What a cell the grid does not store reads as - `null` for an ordinary range.
+     *
+     * @remarks
+     * A grid can hold only part of its range's answer: a watch body's blank region shares one value
+     * that the engine keeps on the block rather than writing per cell (PLAN-WATCHES-BLANK-AWARE
+     * §4c), so within that body "absent" means "the shared answer", never "empty". A range with a
+     * non-null empty value is therefore DENSE: `getValueAt` answers it for every absent cell, and
+     * the iterators visit those cells whether or not `includeEmpty` was asked, since they are
+     * content. A STORED empty (`null`) is still empty.
+     *
+     * It is also how an elementwise operation carries its answer for the blank cells: `map`,
+     * `broadcast` and `zip` walk what their operands STORE, answer the absent region once, and
+     * hand that answer to the result here rather than writing it as a run per line — so the next
+     * operator finds the blank region again and a whole-column chain stays O(stored + runs)
+     * (CALC-PERFORMANCE §5). `fillEmpty` over the whole range sets it the same way.
+     *
+     * Every reader agrees on it: the iterators and `getValueAt` above; a transform over the same
+     * grid carries it (`slice`, `toType`, `clone`); one that derives a grid either writes every
+     * position or writes it out first (`_materializeEmpty` — `resize`, `tile`, a partial `fill`);
+     * and a reader that goes to the grid rather than through the range (the stats walk, the calc
+     * grid's write of a result, a sheet write) reads the written-out grid.
+     */
+    protected _absentValue: Scalar;
+    constructor(runtime: IRuntime, values: ISparseGrid<Scalar>, coords: IRange.Coords | null, optionsIterator?: IRange.IteratorOptions | null, isLiteral?: boolean, isDirectScalar?: boolean, absentValue?: Scalar);
     /** @inheritdoc IRange.argsort */
     argsort(keyRanges?: IRange | IRange[], orders?: number | number[], axis?: IRange.Axis): number[];
     /** @inheritdoc IRange.uniqueIndices */
     uniqueIndices(axis?: IRange.Axis, exactlyOnce?: boolean): number[];
     /** @inheritdoc IRange.broadcast */
     broadcast<TS extends Scalar = T>(other: IRange | TS, callbackFn: (a: TS, b: TS, coords: IRange.CellCoords, range: IRange<T>) => TS, options?: IRange.BroadcastOptions): this;
-    /**
-     * {@link broadcast} against a scalar operand: this range's OWN entries, with every empty position
-     * written as a run of one computed value. See the call site for why the general path cannot.
-     *
-     * @remarks
-     * Reached only for a coord-blind callback, so the single empty call carries the origin coords.
-     */
-    private _broadcastScalar;
     /** @inheritdoc IRange.choose */
     choose<TS extends Scalar = T>(from: (IRange<TS> | TS)[], selectFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => MaybeError<number>, options?: IRange.ValuesOptions): this;
     /** @inheritdoc IRange.clear */
@@ -55,12 +71,34 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     fill(value: Scalar, coords?: Partial<IRange.Coords>): this;
     /** @inheritdoc IRange.fillEmpty */
     fillEmpty(value: Scalar, coords?: Partial<IRange.Coords>): this;
+    /**
+     * Writes `value` at every absent position of `absCoords` as runs — the stored form of
+     * {@link fillEmpty}, for the case the absent value cannot express (a partial fill), and of
+     * {@link _materializeEmpty}.
+     * The result reads its grid alone (no empty value).
+     */
+    protected _fillAbsent(value: Scalar, absCoords: IRange.Coords): this;
+    /**
+     * This range with its empty value WRITTEN — every absent cell stored as runs of it — for a
+     * reader that goes to the grid rather than through the range: the stats walk, the calc grid's
+     * write of a result, a sheet write. `this` when there is nothing to write.
+     * @internal
+     */
+    _materializeEmpty(): this;
     /** @inheritdoc IRange.filter */
     filter<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean, options?: IRange.IteratorOptions): this;
+    /** @inheritdoc IRange.firstError */
+    firstError(): FormulaError.Known | null;
     /** @inheritdoc IRange.flatten */
     flatten(options?: IRange.IteratorOptions): this;
     /** @inheritdoc IRange.getValuesFlat */
     getValuesFlat<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
+    /** @inheritdoc IRange.indexOf */
+    indexOf(value: Scalar, options?: IRange.IndexOfOptions): number;
+    /**
+     * The row-major walk behind {@link indexOf}, for the reads the run index cannot answer.
+     */
+    protected _indexOfScan(value: Scalar, reverse: boolean): number;
     /** @inheritdoc IRange.forEach */
     forEach<TS extends Scalar = T, B = any>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => {
         break: B;
@@ -76,6 +114,8 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     };
     /** @inheritdoc IRange.getStats */
     getStats(options?: IRange.IteratorOptions): IRangeStats;
+    /** The stats without the typed-read fault — what `hasError()` and the fault itself read. */
+    protected _getStats(options?: IRange.IteratorOptions): IRangeStats;
     /** @inheritdoc IRange.hasError */
     hasError(): boolean;
     /** {@inheritDoc IRange.getType} */
@@ -85,7 +125,15 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     /** @inheritdoc IRange.getValues */
     getValues<TS extends Scalar = T>(options?: IRange.GetValuesOptions): TS[][];
     /** @inheritdoc IRange.map */
-    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;
+    /**
+     * {@link map} over what the grid stores: one call per stored member, one per run holding one
+     * value, and under `once` one for the absent region — whose answer is the result's empty value,
+     * so the next consumer finds the blank region again (CALC-PERFORMANCE §5). A member the
+     * callback empties (`null`) and a blank region it answers cannot share the one absent state,
+     * so in that one case the region's answer is written out as runs.
+     */
+    private _mapRuns;
     /** @inheritdoc IRange.mask */
     mask<TS extends Scalar = T>(conditions: IRange | TS, isTrues?: IRange | TS, options?: IRange.MaskOptions): this;
     /** @inheritdoc IRange.alignValues */
@@ -135,17 +183,25 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     /** @inheritdoc IRange.values */
     values<T extends Scalar = Scalar>(options?: IRange.IteratorOptions): IterableIterator<T>;
     /** @inheritdoc IRange.zip */
-    zip(others: (IRange | Scalar)[], callbackFn: (values: Scalar[], coords: IRange.CellCoords, range: IRange<T>) => Scalar, options?: IRange.IteratorOptions): this;
-    /** {@inheritDoc IRange.isLiteral} */
-    isLiteral(): boolean;
-    /** Not on IRange — the boxed-bare-scalar flag; see `_isDirectScalar`. */
-    isDirectScalar(): boolean;
-    /** {@inheritDoc IRange.isScalar} */
-    isScalar(): boolean;
+    zip(others: (IRange | Scalar)[], callbackFn: (values: Scalar[], coords: IRange.CellCoords, range: IRange<T>) => Scalar, options?: IRange.ZipOptions): this;
+    /**
+     * The array-constant flag (`_isLiteral`), for the ENGINE only — the coercion alias that makes
+     * a typed `{…}` direct for a slot's coercion. Excel's runtime has no literal kind (a typed and
+     * a computed array are both `Array`), so a function body never reads it: bodies ask
+     * `FormulaContext.getArgs().getKindAt`, and the reference-vs-array question is
+     * `isIReferenceRange`.
+     * @internal
+     */
+    _isLiteralArray(): boolean;
+    /**
+     * The boxed-bare-scalar flag (`_isDirectScalar`), for the ENGINE only — the box is call-local
+     * plumbing (born at a slot, unboxed at the call exit) and a function body never reads it:
+     * bodies ask `FormulaContext.getArgs().getKindAt`.
+     * @internal
+     */
+    _isDirectScalarBox(): boolean;
     /** {@inheritDoc IRange.isEmpty} */
     isEmpty(): boolean;
-    /** {@inheritDoc IRange.isVector} */
-    isVector(): boolean;
     /** @inheritdoc IRange.size */
     get size(): number;
     /** {@inheritDoc IRange[Symbol.iterator]} */
@@ -159,6 +215,17 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     protected _entries(options?: IRange.IteratorOptions & {
         reuseResult?: boolean;
     }): IGrid.EntryIterator<Scalar>;
+    /**
+     * The read `_entries` applies to one member under `options` - the typed coercion, its error
+     * policy, what an absent cell reads as - as a function, so a walk over runs (`RunHead`) reads a
+     * member exactly as the entry iterator would. Only a TYPED read (`options.type`) coerces; a raw
+     * read hands the member back, and an absent one (`undefined` in) as the empty value.
+     *
+     * @returns The value the member reads as, or `undefined` when the read DROPS it: a typed read
+     * filters what it cannot coerce - the declaration that the type is strict, so an aggregate
+     * ignores stray text the way Excel does - unless `includeEmpty` keeps it as an empty.
+     */
+    protected _memberReader(options: IRange.IteratorOptions | undefined, includeEmpty: boolean): (fromValue: Scalar | undefined) => Scalar | undefined;
     /**
      * Finds an absolute intersection given a relative coord.
      */
@@ -192,11 +259,22 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
      */
     protected _untyped(): this;
     protected _createBuilder(axis?: IRange.Axis): Tuple.IBuilder;
-    protected _applyBuilder(values: ISparseGrid<Scalar>, builder: Tuple.IBuilder, clone?: boolean): ISparseGrid<Scalar>;
-    protected _cloneFromBuilder(builder: Tuple.IBuilder | undefined, deletes?: ISpatialMap.IConflatingEntries | null): this;
+    /**
+     * Writes `region` into `values`: its clears first, unless `fresh` (a grid that stores nothing
+     * there), then its tuples.
+     */
+    protected _applyRegion(values: ISparseGrid<Scalar>, region: Tuple.Region | null, fresh: boolean): void;
+    /**
+     * @param absentValue What the result's absent cells read as. Defaults to this range's own: the
+     * result is this grid written into, so what it lacked it still lacks. A caller whose writes
+     * changed that says so (`map`; `_fillAbsent`, which wrote it out).
+     */
+    protected _cloneFromBuilder(builder: Tuple.IBuilder | undefined, deletes?: ISpatialMap.IConflatingEntries | null, fresh?: boolean, absentValue?: Scalar): this;
+    /** {@link _cloneFromBuilder} from a built region, whose clears are applied with the deletes. */
+    protected _cloneFromRegion(region: Tuple.Region | null, deletes?: ISpatialMap.IConflatingEntries | null, fresh?: boolean, absentValue?: Scalar): this;
     protected _coerceValue<TS extends Scalar>(fromValue: Scalar, toType: ScalarType, options?: IRange.ValueOptions, fromType?: ScalarType): TS;
     protected _mergeIterators<T = Scalar>(that: Range, callbackFn?: (a: T, b: T, coords: IRange.CellCoords, range: IRange) => T, options?: IRange.IteratorOptions): Tuple.IBuilder;
-    protected _newRange(values: ISparseGrid<Scalar>, coords: IRange.Coords | null, optionsIterator?: IRange.IteratorOptions | null, isLiteral?: boolean, isDirectScalar?: boolean): this;
+    protected _newRange(values: ISparseGrid<Scalar>, coords: IRange.Coords | null, optionsIterator?: IRange.IteratorOptions | null, isLiteral?: boolean, isDirectScalar?: boolean, absentValue?: Scalar): this;
     /** @inheritdoc IRange.isIRange */
     get isIRange(): true;
 }
@@ -217,7 +295,7 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
 export declare class _VisibleScopedRange extends Range {
     protected _visibleCoords: readonly IRange.Coords[];
     constructor(runtime: IRuntime, values: ISparseGrid<Scalar>, coords: IRange.Coords, visibleCoords: readonly IRange.Coords[]);
-    /** {@inheritDoc IRange.getStats} */
-    getStats(options?: IRange.IteratorOptions): IRangeStats;
+    /** The rescoped stats; `getStats` (the typed-read fault) is inherited and reads through here. */
+    protected _getStats(options?: IRange.IteratorOptions): IRangeStats;
 }
 //# sourceMappingURL=Range.d.ts.map

package/types/src/primitives/RangeStats.d.ts

@@ -1,6 +1,6 @@
 import { ScalarType, IRange, IRuntime, IRangeStats, Scalar } from '@sheetxl/primitives';
 import { ISparseGrid } from '../collections';
-import { SortedNumbers, AggSegmentCache } from './stats';
+import { SortedNumbers, AggSegmentCache, AggResults } from './stats';
 export declare class RangeStats implements IRangeStats {
     protected _runtime: IRuntime;
     protected _grid: ISparseGrid<Scalar>;
@@ -12,18 +12,41 @@ export declare class RangeStats implements IRangeStats {
     protected _sortedNumbers: SortedNumbers | undefined;
     protected _aggregates: IRangeStats.Aggregates | undefined;
     protected _typedCounts: Readonly<Record<ScalarType, number>> | undefined;
+    /**
+     * The raw results of the ONE walk this instance has done, whichever consumer asked first.
+     * `count`, `typed` and the numeric aggregates are all recorded by the same pass and none of
+     * them depends on `onError` (the segment cache's own contract — only `coerce` changes content),
+     * so the typed counts a reject scan asks for and the aggregates the body then asks for come
+     * from a single scan instead of two. A partial-zone range (a `SUM($K$51:K#)` running total)
+     * never caches at the segment level, so without this every such call scanned twice.
+     * Two-state: `undefined` = not walked yet, `null` = walked, the grid was empty.
+     */
+    protected _raw: AggResults | null | undefined;
     protected _frequencies: Readonly<IRangeStats.IFrequency> | undefined;
     protected _ranked: readonly Scalar[] | undefined;
     protected _lastNumber: number | null | undefined;
     constructor(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords?: readonly (IRange.Coords | null)[], options?: IRange.IteratorOptions, segmentCache?: AggSegmentCache, zoneSizeMinor?: number);
+    /**
+     * The values grid this instance measures. Its owner re-points the cache when the map is
+     * replaced, which a clone of the map is.
+     */
+    getGrid(): ISparseGrid<Scalar>;
     clone(grid?: ISparseGrid<Scalar>, localCoords?: readonly (IRange.Coords | null)[]): this;
     clear(): void;
     /** Lazily resolved, then held for this instance's lifetime like the other per-instance results. */
     protected _getLastNumber(): number | undefined;
     toLocalCoords(coords: IRange.Coords | readonly IRange.Coords[], iteratorOptions?: IRange.IteratorOptions): IRangeStats;
+    /** @inheritdoc IRangeStats.getCoords */
+    getCoords(): IRange.Coords | null;
     /** @inheritdoc IRangeStats.getSize */
     getSize(): number;
     /** @inheritdoc IRangeStats.getCount */
+    /**
+     * The instance's one walk (see `_raw`), taken with errors as population — the contract of
+     * every consumer that counts. Reused by the aggregate path when the instance's own error
+     * policy has no side effect to replay.
+     */
+    protected _walk(): AggResults | null;
     getCount(): number;
     /** @inheritdoc IRangeStats.getAggregates */
     getAggregates(options?: IRange.IteratorOptions): Readonly<IRangeStats.Aggregates>;

package/types/src/primitives/ReferenceRange.d.ts

@@ -1,14 +1,56 @@
 import { Scalar, ScalarType, IReferenceRange, IRange, IRuntime } from '@sheetxl/primitives';
 import { ISparseGrid } from '../collections';
 import { Range } from './Range';
+/**
+ * Answers "is there an error value within these coords" for the grid a reference reads, from an
+ * index rather than a scan. The calculation grid maintains one at every write; a reference built
+ * over any other grid has none and scans.
+ */
+export interface ReferenceErrorIndex {
+    hasErrorIn(coords: IRange.Coords): boolean;
+}
+/** @internal */
+export declare function _setReferenceErrorIndexAssert(enabled: boolean): void;
 export declare class ReferenceRange extends Range implements IReferenceRange {
     protected _getEntireCoords: () => IRange.Coords;
     protected _resolveScope: (scope: string) => string | undefined;
+    /** The grid's error index, when the reference reads a grid that keeps one. */
+    protected _errorIndex: ReferenceErrorIndex | null;
+    /**
+     * Told when a body reads this reference's POSITION (`getCoords`). A reference's values are a
+     * property of what it points at; its address is a property of which cell is asking, so a
+     * formula that reads it (`ROW(A13)`, `CELL("address",A13)`) cannot share its answer with another
+     * cell — see `CalcScope.perCellRead`. Set by the context that builds the reference; a view
+     * (`slice`, `toType`) carries it.
+     */
+    protected _onCoordsRead: (() => void) | null;
     constructor(runtime: IRuntime, values: ISparseGrid<Scalar>, coords: IRange.Coords, options: IRange.ValueOptions | null | undefined, getEntireCoords: (() => IRange.Coords) | undefined, resolveScope: (scope: string) => string | undefined);
     /** @inheritdoc IReferenceRange.getCoords */
     getCoords(): Readonly<IRange.Coords>;
     /** @inheritdoc IReferenceRange.isIReferenceRange */
     get isIReferenceRange(): true;
+    /**
+     * @internal
+     * Attaches the error index of the grid this reference reads. Set by the context that builds
+     * the reference; a typed view (`toType`) carries it.
+     */
+    _setErrorIndex(index: ReferenceErrorIndex | null): void;
+    /**
+     * @internal
+     * Attaches the hook a position read reports to — see {@link _onCoordsRead}.
+     */
+    _setCoordsReadHook(hook: (() => void) | null): void;
+    /** @inheritdoc IRange.hasError */
+    hasError(): boolean;
+    /** @inheritdoc IRange.slice */
+    slice(coords: Partial<IRange.Coords>): this;
+    /**
+     * @internal
+     * The reference DEMOTED to its values: a plain `Range` over the same grid and coords, with no
+     * reference identity. The call-exit applies this to a VALUE-declared function's reference
+     * result (IFERROR/IFNA's surviving branch — ISREF of it is FALSE, measured; TypedFunction §3.1).
+     */
+    _toValueRange(): IRange;
     /** @inheritdoc IRange.toType */
     toType(type: ScalarType | IRange.ValueOptions): this;
     protected _validateCoords(coords: Partial<IRange.Coords>): void;

package/types/src/primitives/Runtime.d.ts

@@ -17,12 +17,23 @@ export interface RuntimeOptions {
      */
     getLocaleOverrides?: () => LocaleProfileOverrides | null;
     /**
-     * Returns now as a long date time.
+     * The clock behind {@link IRuntime.getNow}, as epoch milliseconds — not a serial date.
      *
      * @remarks
-     * This is not a serial date here.
+     * Pinning it makes `NOW` and `TODAY` reproducible. A workbook that builds its own runtime pins
+     * this to the current commit's timestamp, so supplying a runtime without one hands those
+     * functions the wall clock instead.
      */
     getNow?: () => number;
+    /**
+     * The value behind {@link IRuntime.getRandom}, drawn once per calculation pass — `Math.random`
+     * unless a host pins it.
+     *
+     * @remarks
+     * Pinning it makes every draw in the workbook reproducible. Like a pinned clock it is a
+     * whole-run choice: collaborators who do not pin the same value do not draw the same values.
+     */
+    getRandom?: () => number;
 }
 export declare const defaultLocale: () => string;
 export declare const languageLocale: () => string | null;
@@ -37,6 +48,8 @@ export declare class Runtime implements IRuntime {
     getLocale(): string;
     /** @inheritdoc IRuntime.getNow */
     getNow(): number;
+    /** @inheritdoc IRuntime.getRandom */
+    getRandom(): number;
     /** @inheritdoc IRuntime.getLocaleProfile */
     getLocaleProfile(): LocaleProfile;
     /** @inheritdoc IRuntime.isDate1904 */

package/types/src/primitives/stats/FrequencyStats.d.ts

@@ -7,6 +7,13 @@ import { ISparseGrid } from '../../collections';
 export interface FrequencyGroup {
     readonly value: Scalar;
     count: number;
+    /** Bounding box of the occurrences, in grid coordinates; absent when not tracked (merged, blank). */
+    extent?: {
+        rowStart: number;
+        colStart: number;
+        rowEnd: number;
+        colEnd: number;
+    };
 }
 /**
  * Implements {@link IRangeStats.IFrequency}.
@@ -53,6 +60,8 @@ export declare class FrequencyStats implements IRangeStats.IFrequency {
     getTotalCount(): number;
     /** @inheritdoc IRangeStats.IFrequency.isTruncated */
     isTruncated(): boolean;
+    /** @inheritdoc IRangeStats.IFrequency.getExtent */
+    getExtent(value: Scalar): IRange.Coords | null;
     private _getValueOrderAscending;
     /**
      * Collects distinct-value frequencies from a grid and returns an instance over them.

package/types/src/primitives/stats/LookupIndex.d.ts

@@ -0,0 +1,46 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { IListLike, ISparseGrid } from '../../collections';
+/**
+ * An exact-match index over a grid's stored runs, keyed by run identity.
+ *
+ * @remarks
+ * Behind `IRange.indexOf`, and through it `MATCH(…, 0)`, `VLOOKUP(…, FALSE)` and the exact modes
+ * of `XLOOKUP`/`XMATCH`: the shape where one table is read by thousands of lookup cells. Each
+ * stored run is walked once into a map from member key to positions, and the map lives exactly as
+ * long as the run object. Every write REPLACES the runs it touches (`segmentCopyOnWrite.test.ts`),
+ * so a changed run is a miss whose map collects with it, while untouched runs — and every grid
+ * clone and sub-range that shares them — stay warm. Nothing is keyed on the grid, the range or the
+ * pass: none of those is stable across the calls that share a table.
+ *
+ * The key is the hashing side of the `=` rule, the one `UNIQUE` dedupes with: a number as itself,
+ * text through {@link toCompareKey}, a logical as itself. A `Map` keeps the three apart, so `1`,
+ * `"1"` and `TRUE` never collide. Blank, error and rich-data members are never candidates and are
+ * not indexed. Numbers match exactly, as the lookup family compares them; text carries the fold
+ * but not a locale's collation tailorings, the same deviation `UNIQUE` accepts.
+ */
+type Key = number | string | boolean;
+/**
+ * The key a member hashes under, or `undefined` for a member that is never a match.
+ */
+export declare function lookupKey(value: Scalar): Key | undefined;
+/**
+ * The position of `value` along a vector that lies on the grid's own axis, or -1.
+ *
+ * @param values The grid the vector reads.
+ * @param coords One column of a column-oriented grid, or one row of a row-oriented one.
+ * @param isColumn Whether the vector is a column.
+ * @param value The value to find; one {@link lookupKey} answers for.
+ * @param reverse Answer the last position rather than the first.
+ *
+ * @remarks
+ * Runs are asked untrimmed (`overflowRun`), so a run that leaves the vector keeps its identity
+ * and its map: `A2:A100` and `A1:A100` are served by the same index, clipped by position.
+ */
+export declare function indexOfInRuns(values: ISparseGrid<Scalar>, coords: IRange.Coords, isColumn: boolean, value: Scalar, reverse: boolean): number;
+/**
+ * @internal
+ * Whether `run` carries an index. For tests of the cache's lifetime.
+ */
+export declare function isRunIndexed(run: IListLike<Scalar>): boolean;
+export {};
+//# sourceMappingURL=LookupIndex.d.ts.map

package/types/src/primitives/stats/SortedNumbers.d.ts

@@ -27,6 +27,8 @@ export declare class SortedNumbers implements IRangeStats.ISortedNumbers {
     getLarge(k: number): number | null;
     /** @inheritdoc IRangeStats.ISortedNumbers.getSmall */
     getSmall(k: number): number | null;
+    /** Whether a rank names a place at all: `1 <= k <= n`, judged before any truncation. */
+    private _inRank;
     /** @inheritdoc IRangeStats.ISortedNumbers.getPercentile */
     getPercentile(k: number, exclusive?: boolean): number | null;
     /** @inheritdoc IRangeStats.ISortedNumbers.getRankOf */

package/types/src/primitives/stats/index.d.ts

@@ -4,4 +4,5 @@ export * from './FrequencyStats';
 export * from './Ranked';
 export * from './ScalarOrder';
 export * from './SortedNumbers';
+export * from './LookupIndex';
 //# sourceMappingURL=index.d.ts.map

package/types/src/print/IPrint.d.ts

@@ -204,28 +204,6 @@ export declare namespace IPrint {
          */
         verticalCentered?: boolean;
     }
-    /**
-     * Interface for outline properties used in print, such as
-     * the summary position and style application.
-     */
-    interface OutlineProperties {
-        /**
-         * Whether to apply styles to outline symbols.
-         */
-        applyStyles?: boolean;
-        /**
-         * Whether to display outline symbols in the print.
-         */
-        showOutlineSymbols?: boolean;
-        /**
-         * Whether the summary rows are displayed below the details.
-         */
-        summaryBelow?: boolean;
-        /**
-         * Whether the summary columns are displayed to the right of the details.
-         */
-        summaryRight?: boolean;
-    }
     type Break = IRange.JSONReference<{
         man?: boolean;
         pt?: boolean;

package/types/src/protectedRange/IProtectedRange.d.ts

@@ -120,6 +120,10 @@ export interface IProtectedRange extends IAnchored {
      * stack, and resets when the workbook is reopened — the same shape as
      * {@link IProtection.isPaused}. This is what lets the write path consult it synchronously; a
      * password check is async and cannot be awaited per cell.
+     *
+     * It lasts for one protection period: unprotecting the sheet revokes it (protecting again asks
+     * for the password afresh), while a {@link IProtection.pause} keeps it. Changing the password
+     * revokes it too.
      */
     isUnlocked(): boolean;
     /**

package/types/src/protectedRange/IProtectedRangeCollection.d.ts

@@ -30,6 +30,8 @@ export interface IProtectedRangeCollection extends ICollection<IProtectedRange>
      * @param template A template to use for the temporary item.
      */
     createItem(template?: IProtectedRange): IProtectedRange;
+    /** For runtime type checking. */
+    readonly isIProtectedRangeCollection: true;
 }
 /**
  * {@inheritDoc IProtectedRangeCollection}

package/types/src/protectedRange/ProtectedRange.d.ts

@@ -13,7 +13,7 @@ import { IProtectedRange } from './IProtectedRange';
  * Extends {@link AbstractAnchored} directly rather than `AnchoredConditional`: a protected range
  * has no condition and does not depend on cell values, so it never subscribes to range events.
  */
-export declare class ProtectedRange extends AbstractAnchored<State, CommitView, IProtectedRange.Events> implements IProtectedRange {
+export declare class ProtectedRange extends AbstractAnchored<State, IProtectedRange.Events> implements IProtectedRange {
     /**
      * Session edit access — set by {@link unlock}, cleared by {@link relock}.
      *
@@ -94,8 +94,5 @@ interface State extends AbstractAnchored.State {
     securityDescriptor: string | null;
     password: Partial<IProtection.EncryptedPassword> | null;
 }
-/** @internal */
-interface CommitView extends AbstractAnchored.CommitView {
-}
 export {};
 //# sourceMappingURL=ProtectedRange.d.ts.map