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

package/types/src/pivot/PivotCache.d.ts

@@ -0,0 +1,34 @@
+import { IResource } from '../resource';
+import { IEmbeddedPart } from '../io';
+import { AbstractMovableContent } from '../movable/AbstractMovableContent';
+import { IPivotTable } from './IPivotTable';
+/**
+ * A pivot cache as the workbook holds it: the part it was read from, and its source held in the
+ * calculation engine so it follows the cells it names.
+ *
+ * @remarks
+ * The cache is workbook-level and shared by every table on it. Its `<cacheSource>
+ * <worksheetSource ref sheet>` is the one thing in the part that names cells; it is held through
+ * the seam of the sheet it names ({@link _hold}), once the sheets exist, and restated in place by
+ * {@link getXML}. A source that is a defined name or an external book holds nothing and is
+ * written as read.
+ * @internal
+ */
+export declare class PivotCache {
+    readonly cacheId: number;
+    readonly part: IEmbeddedPart | null;
+    /** The source as the engine holds it; `null` while nothing is held. */
+    private _source;
+    constructor(cacheId: number, part: IEmbeddedPart | null);
+    /**
+     * Holds the source through the sheet it names. Asked once the sheets exist; a source naming no
+     * sheet of the workbook is left as read.
+     *
+     * @param resolve The seam of the sheet with that name, or `null` when there is none.
+     */
+    _hold(resolve: (sheetName: string) => AbstractMovableContent.AddWatch | null): void;
+    /** The part's markup, its source restated where the engine has moved it. */
+    getXML(): string | null;
+    toJSON(toResourceId?: (resource: IResource) => number | null): IPivotTable.CacheJSON;
+}
+//# sourceMappingURL=PivotCache.d.ts.map

package/types/src/pivot/PivotTable.d.ts

@@ -0,0 +1,61 @@
+import { IRange } from '@sheetxl/primitives';
+import { IResource } from '../resource';
+import { ISheet } from '../sheet';
+import { Anchored } from '../anchored/Anchored';
+import { AbstractAnchored } from '../anchored/AbstractAnchored';
+import { IEmbeddedPart } from '../io';
+import { IPivotTable } from './IPivotTable';
+interface State extends AbstractAnchored.State {
+    anchorCoords: IRange.Coords;
+    cacheId: number;
+    name: string | null;
+}
+/**
+ * Implementation for {@link IPivotTable}: the part it was read from, anchored on the sheet at its
+ * `<location ref>`.
+ *
+ * @remarks
+ * The location is where the table SITS, so it is the anchor, as a table's range is, and the
+ * sheet's anchored map moves it with structural edits inside their commit. The table rules on
+ * those edits as a table does ({@link _processContainerShift}), with Excel's rule: an edit before
+ * it moves it whole, one taking every cell of it deletes it, anything that would move part of it
+ * is refused. {@link getXML} restates the anchor into the part; the rest of the part is as read.
+ */
+export declare class PivotTable extends AbstractAnchored<State, IPivotTable.Events> implements IPivotTable {
+    protected _sheet: ISheet;
+    protected _part: IEmbeddedPart | null;
+    /** The location as the part spells it. While the anchor still says the same, the part is as read. */
+    private _ref;
+    constructor(options: PivotTable.ConstructorOptions);
+    protected _initialize(options: PivotTable.ConstructorOptions): void;
+    /** {@inheritDoc IPivotTable.getName} */
+    getName(): string;
+    /** {@inheritDoc IPivotTable.getSheet} */
+    getSheet(): ISheet;
+    /** {@inheritDoc IPivotTable.getXML} */
+    getXML(): string | null;
+    /** {@inheritDoc IPivotTable.getCacheId} */
+    getCacheId(): number;
+    /** {@inheritDoc IPivotTable.toJSON} */
+    toJSON(toResourceId?: (resource: IResource) => number | null): IPivotTable.JSON | null;
+    /**
+     * Excel's rule, from `pivot-probes/probe-pivot-structural.ps1` (2026-10-15): the table moves
+     * whole or goes whole. A shift that would split it or change its extent - a row or column cut
+     * through it, an insert inside it, a shift of some of its columns - is refused with Excel's own
+     * refusal, as a user error, before anything of the edit commits.
+     * @internal
+     */
+    protected _processContainerShift(options: Anchored.ShiftOptions): IRange.Coords | null | void;
+    /** @internal */
+    protected _getActionDescription(action: 'delete' | 'initialize' | 'updateListener'): string | null;
+    /** {@inheritDoc IPivotTable.isIPivotTable} */
+    get isIPivotTable(): true;
+}
+export declare namespace PivotTable {
+    interface ConstructorOptions extends Anchored.ConstructorOptions<IPivotTable.JSON> {
+        sheet: ISheet;
+        fromResourceId?: (resourceId: number) => IResource;
+    }
+}
+export {};
+//# sourceMappingURL=PivotTable.d.ts.map

package/types/src/pivot/PivotTableCollection.d.ts

@@ -0,0 +1,25 @@
+import { AbstractCollection } from '../type';
+import { IPivotTable } from './IPivotTable';
+import { IPivotTableCollection } from './IPivotTableCollection';
+/**
+ * Implementation for {@link IPivotTableCollection}.
+ *
+ * @remarks
+ * A front over storage held elsewhere — the sheet's own tables, or a walk over every sheet's for
+ * the workbook — so the same class serves both. Nothing edits a pivot table yet, so there is
+ * nothing to announce.
+ */
+export declare class PivotTableCollection extends AbstractCollection<IPivotTable> implements IPivotTableCollection {
+    private _getItemsDelegate;
+    /**
+     * @param getItems Returns the tables, as an array the caller may keep.
+     */
+    constructor(getItems: () => IPivotTable[]);
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(): IPivotTable[];
+    /** {@inheritDoc IPivotTableCollection.getByName} */
+    getByName(name: string): IPivotTable | null;
+    /** {@inheritDoc IPivotTableCollection.isIPivotTableCollection} */
+    get isIPivotTableCollection(): true;
+}
+//# sourceMappingURL=PivotTableCollection.d.ts.map

package/types/src/pivot/_PivotXml.d.ts

@@ -0,0 +1,24 @@
+import { IRange } from '@sheetxl/primitives';
+import { IPivotTable } from './IPivotTable';
+/** Character data as the markup spells it, decoded. */
+export declare function decodeXml(text: string): string;
+/** `text` as an attribute value spells it. */
+export declare function encodeXml(text: string): string;
+/**
+ * A plain A1 reference as the part spells it (`B3`, `A1:A7`, relative) made absolute, which is how
+ * it is held: a relative endpoint in a body that has no position is left where it is written,
+ * and these name fixed cells.
+ */
+export declare function absoluteA1(ref: string): string;
+/** The held text back in the part's spelling: relative. */
+export declare function relativeA1(ref: string): string;
+/**
+ * The cells a pivot table's part says it is laid out on (`<location ref>`), as coords on its own
+ * sheet, or `null` when the part states none it can be anchored at.
+ */
+export declare function locationCoordsOf(json: IPivotTable.JSON | undefined): IRange.Coords | null;
+/** `attribute` of the first `element` in `xml`, decoded, or `null` when either is absent. */
+export declare function readAttribute(xml: string, element: string, attribute: string): string | null;
+/** `xml` with `attribute` of the first `element` restated as `value`; unchanged when either is absent. */
+export declare function writeAttribute(xml: string, element: string, attribute: string, value: string): string;
+//# sourceMappingURL=_PivotXml.d.ts.map

package/types/src/pivot/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @hidden
+ */
+export * from './IPivotTable';
+export * from './IPivotTableCollection';
+//# sourceMappingURL=index.d.ts.map

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

@@ -24,6 +24,8 @@ export declare class CompositeRangeStats implements IRangeStats {
     protected _typedCounts: Readonly<Record<ScalarType, number>> | undefined;
     protected _frequencies: Readonly<IRangeStats.IFrequency> | undefined;
     constructor(children: readonly IRangeStats[]);
+    /** @inheritdoc IRangeStats.getCoords */
+    getCoords(): IRange.Coords | null;
     /** @inheritdoc IRangeStats.getSize */
     getSize(): number;
     /** @inheritdoc IRangeStats.getCount */

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

@@ -30,6 +30,6 @@ export declare const Criteria: {
      * Parse criteria and return a predicate function for testing values against it.
      * Each operator gets its own closure, avoiding repeated branching on every call.
      */
-    createEvaluator: (context: IFormulaContext, criteria: Scalar) => IFormulaContext.CriteriaEvaluator;
+    createEvaluator: (context: IFormulaContext, criteria: Scalar, options?: IFormulaContext.CriteriaOptions) => IFormulaContext.CriteriaEvaluator;
 };
 //# sourceMappingURL=Criteria.d.ts.map

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

@@ -0,0 +1,65 @@
+import { IFormulaContext, IRange, Scalar } from '@sheetxl/primitives';
+/**
+ * Builds the column a group's members come back in: `size` rows, with `values[i]` at `rows[i]`
+ * and every other row blank.
+ */
+export type GroupingColumnFactory = (size: number, rows: ArrayLike<number>, values: ArrayLike<Scalar>, count: number) => IRange;
+/**
+ * Records grouped by key — see {@link IFormulaContext.createGrouping}.
+ *
+ * @remarks
+ * ### Not public API
+ *
+ * Reached as `IFormulaContext.createGrouping`, the same arrangement `Criteria` has.
+ *
+ * ### Shape of the work
+ *
+ * Every key column is read once, by its non-blank entries, into one small id per record. A record
+ * the entries never reached is blank in that column, so a whole-column key over a short table
+ * costs the table, not the column. The ids then assign each kept record a group, and a counting
+ * sort numbers each record within its group.
+ *
+ * A value column is bucketed the same way the first time it is asked for, so a group's members are
+ * one bucket rather than a scan of the column. Blank members are not stored at all: the member
+ * column is created at the group's size and only the non-blank rows are written.
+ */
+export declare class Grouping implements IFormulaContext.Grouping {
+    private readonly _createColumn;
+    private readonly _recordCount;
+    /** Per record, its group, or -1 when the filter left it out. */
+    private readonly _groupOf;
+    /** Per group, the number of records. */
+    private readonly _sizes;
+    /** Per group, its key (first record's spelling). */
+    private readonly _keys;
+    /** Records kept, in record order — `null` when every record is kept. */
+    private readonly _kept;
+    /** Kept records ordered by group, record order within each group. */
+    private readonly _order;
+    /** Per group, where its records start in `_order`. */
+    private readonly _offsets;
+    /** Per record, its place within its group. */
+    private readonly _rankInGroup;
+    /** Per group, its first record. */
+    private readonly _firstRecord;
+    private readonly _buckets;
+    constructor(keys: IRange, createColumn: GroupingColumnFactory, options?: IFormulaContext.GroupingOptions);
+    /** @inheritdoc IFormulaContext.Grouping.getRecordCount */
+    getRecordCount(): number;
+    /** @inheritdoc IFormulaContext.Grouping.getGroupCount */
+    getGroupCount(): number;
+    /** @inheritdoc IFormulaContext.Grouping.getSize */
+    getSize(group: number): number;
+    /** @inheritdoc IFormulaContext.Grouping.getKeys */
+    getKeys(group: number): readonly Scalar[];
+    /** @inheritdoc IFormulaContext.Grouping.getGroup */
+    getGroup(record: number): number;
+    /** @inheritdoc IFormulaContext.Grouping.getFirstRecord */
+    getFirstRecord(group: number): number;
+    /** @inheritdoc IFormulaContext.Grouping.getMembers */
+    getMembers(values: IRange, groups?: readonly number[]): IRange;
+    /** The records of some groups, ascending. */
+    private _recordsOf;
+    private _getBuckets;
+}
+//# sourceMappingURL=Grouping.d.ts.map

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

@@ -0,0 +1,26 @@
+import { IFunction } from '@sheetxl/primitives';
+import { LambdaCallable } from '../calculation/formula/LambdaValue';
+/**
+ * The brand a function value carries — what `LAMBDA(…)` evaluates to (`LambdaValue`) and what a
+ * bare function name eta-reduces to (`FunctionValue`).
+ *
+ * @remarks
+ * A function value IS an {@link IFunction}: a body whose untyped (`any`) parameter receives one — or
+ * an array of them, `HSTACK(SUM, AVERAGE)` — calls it like any other function (`GROUPBY`'s `fn`).
+ * A lambda-typed parameter instead receives a plain callable (`Lambda`). The brand exists so that
+ * the value-layer sites — coercion, the operators, a range's typed read — can RECOGNIZE a function
+ * value and refuse it without importing the calculation layer — the same structural pattern, and for
+ * the same reason, as `CalcSignal`.
+ *
+ * The brand is `isFunctionValue`, not `isLambda`: {@link IFunction.isLambda} is a method, and an
+ * eta-reduced built-in is a function value whose `isLambda()` is `false`.
+ */
+export interface ILambdaValue extends IFunction {
+    /** The brand itself — the property every recognizing site reads. */
+    readonly isFunctionValue: true;
+    /** Marshals the value into the callable a lambda-typed parameter receives. */
+    makeCallable(): LambdaCallable;
+}
+/** `true` for a function value — see {@link ILambdaValue}. */
+export declare const isLambdaValue: (value: unknown) => value is ILambdaValue;
+//# sourceMappingURL=LambdaBrand.d.ts.map

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,26 +18,46 @@ 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 */
     clear(): this;
-    /** @inheritdoc IRange.clone */
+    /**
+     * @inheritdoc IRange.clone
+     * @param options Read options for the clone, over this range's own: a `processRowSkip` here is
+     * a clone that reads without those rows.
+     */
     clone(options?: IRange.IteratorOptions, isLiteral?: boolean, isDirectScalar?: boolean): this;
     /** @inheritdoc IRange.compute */
     compute(fn: (range: IRange) => IRange): this;
@@ -55,12 +75,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 +118,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 +129,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 +187,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 +219,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.
      */
@@ -191,12 +262,49 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
      * (`SUMPRODUCT(--ISNUMBER(SEARCH(...)))` → 0).
      */
     protected _untyped(): this;
+    /** This range's options without its skips: for a result whose cells are laid out anew. */
+    protected _optionsFresh(): Omit<IRange.IteratorOptions, 'axis'> & {
+        axis?: IRange.Axis;
+    };
+    /**
+     * This range's options for a result over the same grid at `coords`: its skips count from this
+     * range's origin and cover its shape, so a result whose origin moved (a slice) asks them with
+     * the difference, and one that grew (a resize) asks them for the cells it had and leaves the
+     * rest alone. `null` coords - a result laid out anew - carry no skip.
+     *
+     * @remarks
+     * The rule the skips follow: a result whose cells sit where this range's do (a slice, a fill, a
+     * resize, a map) keeps them, since it is written over a copy of this grid and the cells the skip
+     * left alone still hold what the source does; one laid out anew (`empty()`, a compaction, a
+     * reflow) drops them ({@link _optionsFresh}).
+     */
+    protected _optionsAt(coords: IRange.Coords | null): Omit<IRange.IteratorOptions, 'axis'> & {
+        axis?: IRange.Axis;
+    };
+    /** Whether this range's own options skip anything. */
+    protected _hasSkips(): boolean;
+    /**
+     * Iterator options with their skips asked in the GRID's indexes rather than this range's: what
+     * the grid's own iterators take. The options themselves when they skip nothing.
+     */
+    protected _skipsOnGrid<O extends IRange.IteratorOptions>(options: O): O;
     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 +325,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