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

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>;
@@ -9,20 +9,48 @@ export declare class RangeStats implements IRangeStats {
     protected _iteratorOptions?: IRange.IteratorOptions;
     protected _segmentCache: AggSegmentCache;
     protected _ZoneSizeMinor: number;
+    /**
+     * The first row and column of the range whose options these are, which its `processRowSkip` /
+     * `processColumnSkip` count from; `undefined` when the options skip nothing.
+     */
+    protected _skipOrigin: IRange.CellCoords | undefined;
     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);
+    constructor(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords?: readonly (IRange.Coords | null)[], options?: IRange.IteratorOptions, segmentCache?: AggSegmentCache, zoneSizeMinor?: number, skipOrigin?: IRange.CellCoords);
+    /**
+     * 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;
+    /**
+     * 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;
     /** @inheritdoc IRangeStats.getCount */
     getCount(): number;
     /** @inheritdoc IRangeStats.getAggregates */

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

@@ -1,14 +1,58 @@
 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;
+    /** @inheritdoc Range.clone */
+    clone(options?: IRange.IteratorOptions, isLiteral?: boolean, isDirectScalar?: boolean): 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/environment.browser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The runtime location - the current page url in the browser.
+ */
+export declare function getLocation(): string;
+/**
+ * The OS platform, used by the `INFO("system")` formula.
+ */
+export declare function getOS(): string;
+//# sourceMappingURL=environment.browser.d.ts.map

package/types/src/primitives/environment.node.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The runtime location - the current working directory in node.
+ */
+export declare function getLocation(): string;
+/**
+ * The OS platform, used by the `INFO("system")` formula. `process.platform` is available
+ * synchronously without importing `os`.
+ */
+export declare function getOS(): string;
+//# sourceMappingURL=environment.node.d.ts.map

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

@@ -37,8 +37,52 @@ export type AggResults = {
 export type AggSegmentCache = {
     coerce: unknown;
     byRun: WeakMap<IListLike<Scalar>, AggResults[]>;
+    /**
+     * The segments of a walk that SKIPS cells (`IRange.IteratorOptions.processRowSkip`), by the
+     * skip and the origin it counts from: a segment's content then depends on which cells the skip
+     * leaves out, and a caller that keeps one skip (the engine's, per hidden set) keeps its zones.
+     */
+    bySkip: WeakMap<SkipProcessor, Map<number, WeakMap<IListLike<Scalar>, AggResults[]>>>;
 };
 export declare const createAggSegmentCache: () => AggSegmentCache;
+/** A skip as `IRange.IteratorOptions.processRowSkip` gives one: the index to read at or past `index`. */
+export type SkipProcessor = (index: number, reverse?: boolean) => number;
+/**
+ * A skip a walk honors, on one axis of the grid: the range's callback, which counts from the
+ * range's origin on that axis, asked with a grid index less that origin.
+ */
+export interface WalkSkip {
+    readonly skip: SkipProcessor;
+    readonly origin: number;
+}
+/** The skips of a walk, by the grid's axes. */
+export interface WalkSkips {
+    /** The skip along the grid's major axis: a run it skips is left out whole. */
+    readonly major: WalkSkip | null;
+    /** The skip along the grid's minor axis: the cells of a run it skips. */
+    readonly minor: WalkSkip | null;
+}
+/**
+ * The skips `options` ask for, by the grid's axes; `null` when it asks for none.
+ *
+ * @param origin The range's first row and column on the grid, which its callbacks count from.
+ */
+export declare function resolveSkips(options: IRange.IteratorOptions | undefined, isColumn: boolean, origin: IRange.CellCoords | undefined): WalkSkips | null;
+/** Whether the skip leaves out the grid index. */
+export declare const isSkipped: (skip: WalkSkip, index: number) => boolean;
+/**
+ * The grid index to read at or past `index` (at or before, when `reverse`): `index` itself when
+ * the skip reads it. A walk moves straight to it, so a hidden block costs one call, not one per
+ * cell.
+ */
+export declare const nextRead: (skip: WalkSkip, index: number, reverse?: boolean) => number;
+/**
+ * How many cells of `coords` a read under `options` takes in: the population blanks are counted
+ * from. A skipped cell is outside it, so it is never a blank.
+ *
+ * @param origin As {@link resolveSkips}.
+ */
+export declare function countReadCells(options: IRange.IteratorOptions | undefined, coords: IRange.Coords, origin: IRange.CellCoords | undefined): number;
 export declare const resolveAggSegmentCache: (grid: ISparseGrid<Scalar>, inherit?: AggSegmentCache) => AggSegmentCache;
 /**
  * The default minor zone size for segment caching.
@@ -61,13 +105,13 @@ export declare const EmptyAggregates: Readonly<IRangeStats.Aggregates>;
  *
  * @remarks
  * Results are built using a segment cache keyed by run identity (`segmentsByRun`).
- * The cache is shared across all coord shapes that derive from the same root `RangeStats`
- * instance (via `toLocalCoords`), so segment aggregates computed for one shape are reused
- * by any other shape that overlaps the same run segments.
+ * The cache is grid-scoped (see `resolveAggSegmentCache`), so segment aggregates computed for
+ * one coord shape are reused by any other shape over the same grid lineage that overlaps the
+ * same run segments.
  *
  * Returns `null` when the grid is empty.
  */
-export declare function iterateAndCollectStats(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords: readonly (IRange.Coords | null)[], optionsIterator: IRange.IteratorOptions | undefined, segmentCache: AggSegmentCache, zoneSizeMinor: number): AggResults | null;
+export declare function iterateAndCollectStats(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords: readonly (IRange.Coords | null)[], optionsIterator: IRange.IteratorOptions | undefined, segmentCache: AggSegmentCache, zoneSizeMinor: number, skipOrigin?: IRange.CellCoords): AggResults | null;
 /**
  * The value Excel added LAST — the final numeric member in ROW-major order, which is the
  * traversal Excel's accumulators use (measured: `probe-sum-cancel-order.ps1`, two mirrored 2-D
@@ -87,7 +131,7 @@ export declare function iterateAndCollectStats(runtime: IRuntime, grid: ISparseG
  * `(row, col)` is used rather than reverse iteration because the grid's run iterator has no
  * reverse, and this way the result is independent of the grid's axis.
  */
-export declare function findLastNumber(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords: readonly (IRange.Coords | null)[], optionsIterator: IRange.IteratorOptions | undefined): number | undefined;
+export declare function findLastNumber(runtime: IRuntime, grid: ISparseGrid<Scalar>, range: IRange | null, localCoords: readonly (IRange.Coords | null)[], optionsIterator: IRange.IteratorOptions | undefined, skipOrigin?: IRange.CellCoords): number | undefined;
 /**
  * Resolves an iterator's `coerce` option into the callable pair the scans use.
  *
@@ -106,14 +150,4 @@ export declare function resolveCoerce(runtime: IRuntime, optionsIterator: IRange
  * Computes derived fields (average, variance, stdDev) and normalizes missing-number fields to null.
  */
 export declare function buildAggregates(raw: AggResults | null): Readonly<IRangeStats.Aggregates>;
-/**
- * Calculates an optimal zone size for a given grid minor dimension.
- *
- * @remarks
- * Strategy: target ~128 segments per full column/row to balance cache granularity
- * (smaller = better reuse for small queries) vs. iteration overhead (fewer = faster
- * full-column scans). Result is rounded up to the nearest power of 2 and clamped to
- * [256, 16384].
- */
-export declare function calculateZoneSize(maxMinorDimension: number): number;
 //# sourceMappingURL=AggregateStats.d.ts.map

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

@@ -40,4 +40,17 @@ export declare const mayCancel: (sum: number, largestMag: number) => boolean;
  * `SUM(1E-20)` → `1E-20`.
  */
 export declare const snapCancelledSum: (sum: number, lastNumber: number | undefined) => number;
+/**
+ * The rule itself, for one addition whose left operand is known: `result` is `0` when it lands
+ * at least 50 binary exponents below `accBefore`.
+ *
+ * @param result The sum (or difference) just computed.
+ * @param accBefore What was already accumulated — the left operand of a root `+`/`-`.
+ *
+ * @remarks
+ * A binary `+`/`-` is the one-step case of the sum rule: `=H4+H9` (`1 + -(1-2^-50)`) is `0`
+ * while `=H9+H4` keeps `8.88178419700125E-16`, the same order dependence as `SUM`. A non-finite
+ * result is never a cancellation (see {@link mayCancel}).
+ */
+export declare const snapCancelled: (result: number, accBefore: number) => number;
 //# sourceMappingURL=Cancellation.d.ts.map

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.
@@ -70,7 +79,7 @@ export declare class FrequencyStats implements IRangeStats.IFrequency {
      * (a custom `filterFn` restricts the population in a way nothing else already counts) and the
      * scan's own `visitedCount` is used — exact when not truncated, an undercount when truncated.
      */
-    static fromGrid(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, options: IRangeStats.GetFrequenciesOptions | undefined, defaultCompareFn: (a: Scalar, b: Scalar) => number, blankCount: number, totalCount: number | undefined): FrequencyStats;
+    static fromGrid(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, options: IRangeStats.GetFrequenciesOptions | undefined, defaultCompareFn: (a: Scalar, b: Scalar) => number, blankCount: number, totalCount: number | undefined, skipOrigin?: IRange.CellCoords): FrequencyStats;
     /**
      * Builds an instance directly from an already-merged group map — used by
      * {@link CompositeRangeStats}, which merges its children's own (already-scanned) frequencies

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/Ranked.d.ts

@@ -10,7 +10,7 @@ import { ISparseGrid } from '../../collections';
  * `includeBlanks` is handled separately: one synthetic `null` candidate is offered per blank
  * cell, capped at `limit` offers (any beyond that can never displace a kept member).
  */
-export declare function collectRanked(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, options: IRangeStats.GetRankedOptions | undefined, defaultCompareFn: (a: Scalar, b: Scalar) => number): readonly Scalar[];
+export declare function collectRanked(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, options: IRangeStats.GetRankedOptions | undefined, defaultCompareFn: (a: Scalar, b: Scalar) => number, skipOrigin?: IRange.CellCoords): readonly Scalar[];
 /**
  * Merges each child's own top-`limit` into the composite's true top-`limit`.
  *

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

@@ -22,11 +22,13 @@ export declare class SortedNumbers implements IRangeStats.ISortedNumbers {
      * Collects the numeric values within `localCoords` from the grid and returns an instance
      * over them (sorted ascending).
      */
-    static fromGrid(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined): SortedNumbers;
+    static fromGrid(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, skipOrigin?: IRange.CellCoords): SortedNumbers;
     /** @inheritdoc IRangeStats.ISortedNumbers.getLarge */
     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 */
@@ -43,6 +45,6 @@ export declare class SortedNumbers implements IRangeStats.ISortedNumbers {
      * Collects all numeric values from the range coords and returns them sorted ascending.
      * Called at most once per instance lifetime (result is cached on `_sortedNumbers`).
      */
-    protected static _collectNumbers(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined): readonly number[];
+    protected static _collectNumbers(grid: ISparseGrid, localCoords: readonly (IRange.Coords | null)[], iteratorOptions: IRange.IteratorOptions | undefined, skipOrigin?: IRange.CellCoords): readonly number[];
 }
 //# sourceMappingURL=SortedNumbers.d.ts.map

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

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

@@ -1,21 +1,32 @@
 import { ICellRanges } from '../cellRange';
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
 import { IProtectedRangeCollection } from './IProtectedRangeCollection';
 import { IProtectedRange } from './IProtectedRange';
-export declare class ProtectedRangeCollection implements IProtectedRangeCollection {
+/**
+ * Implementation for {@link IProtectedRangeCollection}.
+ *
+ * @remarks
+ * A front over the sheet's own protected-range state — the sheet keeps the store and the
+ * events, this class keeps the API. `onCollectionChange` is the sheet's
+ * `onProtectedRangesChange`, forwarded with this collection as the source.
+ */
+export declare class ProtectedRangeCollection extends AbstractCollection<IProtectedRange, IProtectedRangeCollection.GetItemsOptions> implements IProtectedRangeCollection {
     private _add;
     private _get;
     private _getByName;
     private _createItem;
-    constructor(add: (address: ICellRanges.Address | IProtectedRange, options?: IProtectedRangeCollection.AddOptions) => IProtectedRange, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IProtectedRange[], getByName: (name: string) => IProtectedRange | null, createItem: (template?: IProtectedRange | null) => IProtectedRange);
+    private _addListeners;
+    constructor(add: (address: ICellRanges.Address | IProtectedRange, options?: IProtectedRangeCollection.AddOptions) => IProtectedRange, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IProtectedRange[], getByName: (name: string) => IProtectedRange | null, createItem: (template?: IProtectedRange | null) => IProtectedRange, addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove);
     /** {@inheritDoc IProtectedRangeCollection.add} */
     add(address: ICellRanges.Address | IProtectedRange, options?: IProtectedRangeCollection.AddOptions): IProtectedRange;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<IProtectedRange>;
-    /** {@inheritDoc IProtectedRangeCollection.getItems} */
-    getItems(options?: IProtectedRangeCollection.GetItemsOptions): IProtectedRange[];
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IProtectedRangeCollection.GetItemsOptions): IProtectedRange[];
     /** {@inheritDoc IProtectedRangeCollection.createItem} */
     createItem(template?: IProtectedRange | null): IProtectedRange;
-    /** {@inheritDoc IProtectedRangeCollection.getCount} */
-    getCount(): number;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IProtectedRangeCollection.isIProtectedRangeCollection} */
+    get isIProtectedRangeCollection(): true;
 }
 //# sourceMappingURL=ProtectedRangeCollection.d.ts.map

package/types/src/protection/DefaultProtection.d.ts

@@ -1,9 +1,11 @@
 import { IListener } from '../listener';
 import { IProtection } from './IProtection';
 import { ListenerEmitter } from '../listener/ListenerEmitter';
-export declare class DefaultProtection<T, P extends IProtection.Properties, J extends IProtection.JSON> implements IProtection<T, P, J> {
+export declare abstract class DefaultProtection<T, P extends IProtection.Properties, J extends IProtection.JSON> implements IProtection<T, P, J> {
     protected _emitter: ListenerEmitter<this, IProtection.IListeners>;
     protected _isPaused: boolean;
+    /** Not protected, but keeping `_properties` for the next lock. Saved as {@link _getAllowedKey}. */
+    protected _isDisabled: boolean;
     protected _password: Partial<IProtection.EncryptedPassword> | null;
     protected _identities: IProtection.IdentityProvider[] | null;
     protected _properties: Partial<P> | null;
@@ -21,6 +23,8 @@ export declare class DefaultProtection<T, P extends IProtection.Properties, J ex
     pause(password?: string): Promise<IProtection<T, P, J>>;
     /** {@inheritDoc IProtection.resume} */
     resume(): IProtection<T, P, J>;
+    /** {@inheritDoc IProtection.setProperties} */
+    setProperties(properties: Partial<P>): Promise<IProtection<T, P, J>>;
     /** {@inheritDoc IProtection.isPaused} */
     isPaused(): boolean;
     /** {@inheritDoc IProtection.isLocked} */
@@ -35,9 +39,16 @@ export declare class DefaultProtection<T, P extends IProtection.Properties, J ex
     /** {@inheritDoc IListener.ISource.addListeners} */
     addListeners(listeners: IProtection.IListeners, options?: IListener.Options): IListener.Remove;
     fromJSON(json?: J): void;
+    /**
+     * The JSON key that says the whole object stays allowed: unprotected, keeping its options. Named
+     * for the object (`sheet`, `workbook`), like the allowances beside it.
+     */
+    protected abstract _getAllowedKey(): string;
     protected _fromJSON(_json: J | null): void;
     protected _toJSON(json: Partial<J>): Partial<J>;
     /** {@inheritDoc IWorkbookProtection.toJSON} */
     toJSON(): J | null;
+    /** {@inheritDoc IProtection.isIProtection} */
+    get isIProtection(): true;
 }
 //# sourceMappingURL=DefaultProtection.d.ts.map

package/types/src/protection/IProtection.d.ts

@@ -8,13 +8,15 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      * Locks the object (workbook or sheet or range) with the specified options and password.
      *
      * @param password The password required to unlock the object.
-     * @param properties The properties to allow to remain unlocked.
+     * @param properties The properties to allow to remain unlocked. Omitted, the options the object
+     * already carries are used (see {@link unlock} and {@link setProperties}).
      * @param algorithm The algorithm for encrypting the password.
      * @param spinCount The spin count for encrypting the password.
      * @returns The `IProtection` instance for method chaining.
      *
      * @remarks
      * By default all properties are locked but you can specify which properties to remain unlocked.
+     * Throws when the object is already protected, paused included.
      */
     lock(properties?: Partial<P>, password?: string, algorithm?: string, spinCount?: number): Promise<IProtection<T, P, J>>;
     /**
@@ -24,9 +26,31 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      * @returns The `IProtection` instance for method chaining.
      *
      * @remarks
-     * If the correct password is provided, protection is removed from the object.
+     * If the correct password is provided, protection is removed from the object and the password is
+     * cleared. The options are kept, and saved, so a later {@link lock} with no properties protects
+     * the same way again.
      */
     unlock(password?: string): Promise<IProtection<T, P, J>>;
+    /**
+     * Replaces the options of an unprotected or paused object. On a paused object they apply when it
+     * resumes; on an unprotected one, when it is next locked.
+     *
+     * @param properties The properties to allow to remain unlocked.
+     * @returns The `IProtection` instance for method chaining.
+     *
+     * @remarks
+     * Throws while the object is locked: unprotect or {@link pause} first. Neither asks for the
+     * password here, since an unprotected object has none and a pause already asked for it.
+     */
+    setProperties(properties: Partial<P>): Promise<IProtection<T, P, J>>;
+    /**
+     * The object's options, kept while it is unlocked; `null` when it has none.
+     *
+     * @remarks
+     * A property names what stays **allowed** while locked - it is not a list of what is forbidden.
+     * Whether the options are in force is {@link isLocked}.
+     */
+    getProperties(): Partial<P> | null;
     /**
      * Temporarily disables protection with the provided password.
      *
@@ -36,6 +60,14 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      * @remarks
      * This method allows temporarily pausing protection without permanently unlocking the object.
      * Use {@link resume} to restore protection.
+     *
+     * Not a shortcut for {@link unlock}, even on a lock without a password: unlocking is a document
+     * change (the file saves unprotected, and the password is gone), whereas a pause
+     * keeps the whole configuration - password, options, and any session access already granted to
+     * an {@link IProtectedRange} - and {@link resume} restores it exactly. The password is required
+     * only when one is set. Throws when the object is not locked.
+     *
+     * The paused state is session-only and is never serialized.
      */
     pause(password?: string): Promise<IProtection<T, P, J>>;
     /**
@@ -91,6 +123,8 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      */
     addListeners(listeners: IProtection.IListeners, options?: IListener.Options): IListener.Remove;
     toJSON(): IProtection.JSON | null;
+    /** For runtime type checking. */
+    readonly isIProtection: true;
 }
 /**
  * {@inheritDoc IProtection}