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

package/types/src/calculation/state/CalcNode.d.ts

@@ -40,31 +40,58 @@ export interface CalcNode {
     cachedValue: Scalar | IRange | undefined;
     pendingPromise: Promise<any> | null;
     /**
-     * Indicates if the pending is in the pending spatial (to avoid lookup)
+     * The demand evaluation's result — finalized for the cell, or a pending promise — which
+     * `doEvaluate` consumes in place of an `evaluateAt` of its own. Cleared once consumed.
+     * Meaningful only while `CalcState.Circular` is set.
      */
-    pending: boolean;
+    demandValue: any;
     /**
-     * Indicates the pending is waiting on a precedent to resolve.
+     * Identifies the cycle a `CycleRole.Member` belongs to (and the one a `CycleRole.Downstream`
+     * node read). `0` for none. Slices that share a node share an id. Reset every mark phase.
      */
-    pendingPrecedents: boolean;
+    cycleGroup: number;
     /**
-     * Indicates the pending is full filled and waiting for the next cycle to resolve.
+     * For a `CycleRole.Member`: the member this one READ that continues the cycle — the next step
+     * of the walk `ICircularReference.getPath` answers. A cycle of one points at itself. Written
+     * from the `Circular` slice (whose stack order is the read order) and rewritten whenever the
+     * cycle is detected again; stale otherwise, so a walk checks each step is still a live member.
      */
-    pendingResolved: boolean;
+    cycleNext: CalcNode | null;
     /**
-     * Set when the topological sort could not order this node — it is part of a reference cycle, or
-     * downstream of one. Reset for every affected node at the start of each mark phase, so like
-     * `inDegree` it only describes the CURRENT cycle.
-     *
-     * @remarks
-     * Deliberately not folded into {@link state}: `state` carries the Skip/Pending transitions that
-     * `doEvaluate` reads and rewrites mid-pass, and this has to survive being set BEFORE that runs.
+     * The cycle the sheet's circular index currently shows this cell in (`0` none) — what the last
+     * commit wrote, so the next can write the delta. Persists across passes, unlike
+     * {@link cycleGroup}; the role it shows is the `CalcState.ShownRoleMask` field of {@link state}.
+     */
+    shownGroup: number;
+    /**
+     * Position of this node in the last FULLY-ORDERED plan that stamped it (CALC-PERFORMANCE-PLAN.md
+     * §1.2). Meaningful only when {@link planId} and {@link planEpoch} match the executor's current
+     * plan id and the container's static epoch; `-1` until first stamped.
+     */
+    orderIndex: number;
+    /**
+     * Id of the Kahn pass that stamped {@link orderIndex}; `0` = never stamped. Stamps from
+     * different passes are NOT mutually comparable — the fast path requires every affected node to
+     * carry the executor's `_lastPlanId`.
+     */
+    planId: number;
+    /** The container's `staticEpoch` when {@link orderIndex} was stamped; stale under a newer epoch. */
+    planEpoch: number;
+    /**
+     * The container's `precedentEpoch` when {@link dependents} was last computed
+     * (CALC-PERFORMANCE-PLAN.md §1.3). Discovery reuses the cached array while this matches;
+     * `0` = never computed.
      */
-    circular: boolean;
+    dependentsEpoch: number;
     /**
-     * The state is a bit mask with transient states.
-     * The CalcNode is reused across cycles and cloned records for performance.
-     * To ensure that it is correct the cycleId id must be consulted.
+     * Bit mask, laid out by `CalcState`: the pending flags, `Skip`, `Circular`, and the
+     * `DemandState`/`CycleRole` fields of the current pass.
+     *
+     * @remarks
+     * The node is reused across passes, so a per-pass bit is only meaningful when {@link cycleId}
+     * and {@link markId} say the node is in the current pass; the mark phase resets them
+     * (`CalcState.PassMask`) as it visits each affected node. `Skip` and the shown role outlive a
+     * pass on purpose.
      */
     state: number;
 }

package/types/src/calculation/state/CalcState.d.ts

@@ -1,28 +1,91 @@
+/**
+ * The bit layout of `CalcNode.state`: single-bit flags in the low byte, then three 2-bit fields.
+ *
+ * @remarks
+ * Every bit is independent, so a phase touches only its own: the mark phase clears
+ * {@link PassMask} (what the last pass decided), `doEvaluate` consumes {@link Skip}, and the
+ * promise path flips the pending bits — none of them assigns the whole word.
+ *
+ * The 2-bit fields hold a {@link DemandState} and two {@link CycleRole}s. Their values are
+ * pre-shifted into place, so a read is `(state & Mask) === Value` and a write is
+ * `state = (state & ~Mask) | Value`. The `ShownRole` field sits two bits above `CycleRole`, so
+ * copying the role the pass decided into what the sheet shows is `(state & CycleRoleMask) << 2`.
+ */
 export declare const CalcState: {
+    /** Nothing set. */
+    readonly Idle: 0;
     /**
-     * The default state.
+     * Evaluate-once guard for a dynamic dependency (a dynamic precedent or a spill output) that
+     * caused a recalc: the next pass skips the node instead of re-evaluating it.
      */
-    readonly Active: 0;
+    readonly Skip: number;
+    /** Reserved. */
+    readonly Removed: number;
+    /** The node is in the pending spatial (the user has been given a pending status). */
+    readonly Pending: number;
+    /** A precedent evaluated to a pending value this pass, so the node keeps its cached value. */
+    readonly PendingPrecedents: number;
+    /** The node's promise resolved; the result waits in `cachedValue` for the next pass. */
+    readonly PendingResolved: number;
     /**
-     * Causing a recalc due to a dynamic dependency. This is either a
-     * dynamic precedent or a spill output.
+     * The topological sort could not order the node this pass — it is in a reference cycle, or
+     * downstream of one — so it was (or will be) evaluated by demand and `doEvaluate` takes its
+     * `demandValue` in place of an `evaluateAt`.
      */
-    readonly Skip: 1;
-    readonly Removed: 2;
+    readonly Circular: number;
     /**
-     * The calc node is pending and waiting for a precedent to resolve.
-     * This is used to indicate that the user has been given a pending status.
+     * A `Waiting` node the evaluation in progress has read under iterative calculation — it is in
+     * the executor's hit list already, so a second read of it in the same evaluation adds nothing.
+     * Cleared when the list is consumed.
      */
-    readonly Pending: 3;
+    readonly IterHit: number;
+    /** Field: the {@link DemandState}. */
+    readonly DemandMask: number;
+    /** Field: the {@link CycleRole} this pass decided. */
+    readonly CycleRoleMask: number;
+    /** Field: the {@link CycleRole} the sheet's circular index currently shows (persists). */
+    readonly ShownRoleMask: number;
     /**
-     * The calc node is pending and waiting for a precedent to resolve.
-     * This is used for dynamic dependencies that are not yet resolved.
+     * In the executor's circular roster for the pass in progress. Outside {@link PassMask} on
+     * purpose: the roster outlives the re-marks a pass makes while it re-dirties, so the executor
+     * clears this when it empties the roster.
      */
-    readonly PendingPrecedents: 4;
+    readonly Rostered: number;
+    /** What the mark phase resets: everything a single pass decides. `Skip` and the shown role survive. */
+    readonly PassMask: number;
+};
+/**
+ * Where a node the topological sort could not order stands in the demand evaluation
+ * (DESIGN-CIRCULAR-CALC.md §4.3). Meaningful only while `CalcState.Circular` is set for the
+ * current pass. Values sit in the `CalcState.DemandMask` field.
+ */
+export declare const DemandState: {
+    /** Not yet evaluated; a read of it suspends the reader so it can go first. */
+    readonly Unevaluated: 0;
+    /** On the in-progress stack; a read of it is a reference cycle. */
+    readonly Waiting: number;
+    /** Evaluated (or written `0` as a cycle member); reads see its value. */
+    readonly Done: number;
+    /**
+     * Evaluated on the ordered path but not yet committed — its value is in the pending batch, so a
+     * lazy read of the grid would still see the previous one. Reads treat it as {@link Unevaluated}
+     * until the batch is flushed, which makes it {@link Done}.
+     */
+    readonly Evaluated: number;
+};
+/**
+ * How a node relates to a reference cycle, decided by the demand evaluation's reads. Values sit
+ * in the `CalcState.CycleRoleMask` field.
+ */
+export declare const CycleRole: {
+    /** Not in a cycle and reads none — an unorderable node that simply computed. */
+    readonly None: 0;
+    /** Named by a `Circular` read: its evaluation needed its own value. Writes `0`. */
+    readonly Member: number;
     /**
-     * The calc node is pending and waiting for a precedent to resolve.
-     * This is used for dynamic dependencies that are not yet resolved.
+     * Read a member (transitively). Writes `0` too — Excel gives every cell downstream of a cycle
+     * `0`, not a value computed from the members' `0` (design §2.1: `=A1+100` is `0`).
      */
-    readonly PendingResolved: 5;
+    readonly Downstream: number;
 };
 //# sourceMappingURL=CalcState.d.ts.map

package/types/src/calculation/state/CalculationContext.d.ts

@@ -1,10 +1,11 @@
-import { IRange, ScalarType, FormulaError, Scalar, IReferenceRange, IFunction, IFormulaContext, IRuntime } from '@sheetxl/primitives';
+import { IRange, ScalarType, FormulaError, Scalar, IReferenceRange, IFunction, IFormulaContext, IFunctionArguments, IRuntime } from '@sheetxl/primitives';
 import { FunctionProvider } from '@sheetxl/scripting';
 import { ITransaction } from '../../transaction';
 import { IFunctionCollection } from '../../scripting';
 import { Tuple } from '../../collections';
 import { IContextContainer } from './IContextContainer';
 import { CalcScope } from './CalcScope';
+import { ReadHook } from './_ReadObservedGrid';
 export declare class CalculationContext implements IFormulaContext {
     protected _instanceScope: any;
     protected _runtime: IRuntime;
@@ -14,9 +15,39 @@ export declare class CalculationContext implements IFormulaContext {
     protected _axis: IRange.Axis;
     protected _coerceToNumber: (value: Scalar, fromType: ScalarType, options?: IFormulaContext.ParseNumberOptions) => Scalar;
     protected _functionProviders?: readonly FunctionProvider[];
+    /**
+     * Receives every value read while armed; `null` on the ordinary path.
+     *
+     * @remarks
+     * Two paths read the grid on a formula's behalf and both report here: a reference built by
+     * {@link _toReference} (its grid is wrapped in a {@link ReadObservedGrid}) and the direct
+     * single-cell read {@link getValueAt} falls back to. Constructing a reference is not a read.
+     */
+    protected _onRead: ReadHook | null;
+    /**
+     * Receives the reads of references built on the DYNAMIC branch of {@link getReference} — the
+     * result of `OFFSET`/`INDIRECT`/`INDEX` — when {@link _onRead} is not armed. The executor arms
+     * it for the length of an ordinary pass so that a dynamic read landing on the evaluating cell
+     * is seen (DESIGN-CIRCULAR-CALC.md §5); `null` outside a pass.
+     */
+    protected _dynamicRead: ReadHook | null;
     constructor(container: IContextContainer, axis?: IRange.Axis, functionProviders?: readonly FunctionProvider[]);
     /** @hidden */
     _setInstanceScope(instanceScope: any): void;
+    /**
+     * @hidden
+     * Arms (or, with `null`, disarms) the read hook. While armed, every reference this context
+     * builds observes its reads and every direct cell read is reported — the funnel a demand
+     * evaluation decides circularity through. The ordinary evaluation path leaves it `null` and
+     * builds references exactly as before.
+     */
+    _setReadHook(hook: ReadHook | null): void;
+    /**
+     * @hidden
+     * Arms (or, with `null`, disarms) the hook dynamic-branch references report to while no read
+     * hook is armed. See {@link _dynamicRead}.
+     */
+    _setDynamicReadHook(hook: ReadHook | null): void;
     /**
      * @hidden
      *
@@ -100,6 +131,14 @@ export declare class CalculationContext implements IFormulaContext {
      * A caller that reads a WINDOW rather than returning a reference - `SUMIF`'s `sum_range`,
      * `LOOKUP`'s `result_vector`, both anchor-plus-length - goes through
      * {@link getResizedReference} instead: Excel reads the part that fits rather than failing.
+     *
+     * This is the one place a reference is built on a formula's behalf, so it is where the read
+     * hook attaches: while {@link _onRead} is armed the reference is built over a
+     * {@link ReadObservedGrid} and every value it (or a view derived from it) opens is reported.
+     * Unarmed, a static reference's grid is used as is — the ordinary path pays nothing, not even a
+     * branch per read — while a `dynamic` one (the result of `OFFSET`/`INDIRECT`/`INDEX`, the rare
+     * path) reports to {@link _dynamicRead} when that is armed: a dynamic read that lands on the
+     * evaluating cell is a cycle on any path (design §5).
      */
     private _toReference;
     /** @inheritdoc IFormulaContext.getAddress */
@@ -119,6 +158,8 @@ export declare class CalculationContext implements IFormulaContext {
     toText(value: Scalar | undefined): string;
     /** @inheritdoc IFormulaContext.getRuntime */
     getRuntime(): IRuntime;
+    /** @inheritdoc IFormulaContext.getArgs */
+    getArgs(): IFunctionArguments;
     get [Symbol.toStringTag](): string;
     toString(): string;
 }

package/types/src/calculation/state/IContextContainer.d.ts

@@ -156,6 +156,37 @@ export interface IContextContainer {
      * still carry, and the "already visited this cycle" guards would skip their re-evaluation.
      */
     getCycleId(): number;
+    /**
+     * The graph-version counters the executor's plan caches key on (CALC-PERFORMANCE-PLAN.md §1.1).
+     *
+     * `staticEpoch` advances whenever the static edges may have changed — formula block
+     * register/unregister/edit, structural shift, sheet add/remove, undo/redo state swap — and
+     * governs order-stamp validity. `precedentEpoch` advances whenever `staticEpoch` does, plus on
+     * dynamic-precedent commits (spill/INDIRECT watchers), and governs `CalcNode.dependents`
+     * validity. The split is load-bearing: a dynamic commit changes who is affected, never the
+     * static topological constraints, so a sheet with a spill keeps a valid order cache.
+     *
+     * READING is what synchronizes: the implementation compares the identities of the spatial maps
+     * it last saw and advances the counters when a clone-then-swap happened (edits, shifts, undo/
+     * redo, pass-end dynamic commits all publish fresh maps). Sites that mutate the CURRENT maps in
+     * place — `CalcGrid.fromJSON` loads, an un-cloned `shift` — must call {@link bumpCalcEpochs}
+     * explicitly, because no identity changes there.
+     *
+     * Both counters are monotonic and deliberately NOT transactional, for the same reason as
+     * {@link getCycleId}: they are compared against stamps on plain mutable graph objects that
+     * undo/redo never rewinds, so rewinding a counter would re-validate stale stamps.
+     */
+    getCalcEpochs(): {
+        staticEpoch: number;
+        precedentEpoch: number;
+    };
+    /**
+     * Advances the epoch counters for an IN-PLACE mutation of the current spatial maps — the paths
+     * identity comparison in {@link getCalcEpochs} cannot see. `includeStatic: true` advances both
+     * counters (a formula/structure change); `false` advances only `precedentEpoch` (a
+     * dynamic-precedent-only change).
+     */
+    bumpCalcEpochs(includeStatic: boolean): void;
     /**
      * Returns the committed or in-progress scalar values for the given grid.
      *

package/types/src/calculation/state/_ReadObservedGrid.d.ts

@@ -0,0 +1,90 @@
+import { Scalar } from '@sheetxl/primitives';
+import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
+import { IGrid, ISparseGrid, Tuple } from '../../collections';
+/**
+ * Receives every value read a formula makes while a read hook is armed.
+ *
+ * @remarks
+ * A single-cell read reports a 1x1 rectangle; a block read (iteration, runs, bounded tuples)
+ * reports the rectangle it was asked for — the cells it *may* open — because a sparse iterator
+ * cannot tell an empty cell from a formula cell whose value is not there yet, and the second is
+ * exactly the read a cycle check must see. Coordinates are absolute and closed.
+ *
+ * The hook may throw; the throw propagates through the reading function up to the evaluation
+ * that armed it. Nothing is reported for constructing a reference, for its coords or size, or for
+ * a copy made to hold derived values.
+ */
+export type ReadHook = (gridId: string, rowStart: number, colStart: number, rowEnd: number, colEnd: number) => void;
+/**
+ * An `ISparseGrid` that reports every value access on an inner grid to a {@link ReadHook}.
+ *
+ * @remarks
+ * Every `ReferenceRange` a formula receives reads its cells through the grid it was built over
+ * and never touches the sheet directly, so wrapping that grid observes every value read the
+ * reference makes — through any `Range` view derived from it, since views share the grid.
+ *
+ * `clone`/`cloneEmpty` hand back the inner grid's copy UNWRAPPED. A `Range` operation clones
+ * its grid only as scratch space for a derived result (`fill`, `map`, a scalar broadcast) and
+ * overwrites what it later reads back; the coordinates in such a copy no longer name sheet
+ * cells (a broadcast writes its scalar at (0,0)), so reporting them would invent reads of A1.
+ *
+ * Writes are delegated verbatim; nothing on a reference's path writes to its grid.
+ */
+export declare class ReadObservedGrid implements ISparseGrid<Scalar> {
+    /**
+     * Number of wrappers constructed since module load.
+     *
+     * @remarks
+     * A pass that Kahn orders builds none; tests pin that the ordinary path stays unwrapped.
+     */
+    static created: number;
+    protected readonly _inner: ISparseGrid<Scalar>;
+    protected readonly _gridId: string;
+    protected readonly _onRead: ReadHook;
+    constructor(inner: ISparseGrid<Scalar>, gridId: string, onRead: ReadHook);
+    /** The grid being observed. */
+    getInner(): ISparseGrid<Scalar>;
+    /**
+     * Reports a block read. Missing sides of a partial bound are taken from the grid's maximum
+     * extent, then from its data extent; a grid with neither has nothing to read.
+     */
+    protected _reportBounds(bounds: Partial<RangeCoords> | null | undefined): void;
+    /** {@inheritDoc IGrid.getValueAt} */
+    getValueAt(row: number, column: number): Scalar;
+    /** {@inheritDoc ISparseGrid.getRuns} */
+    getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator<Scalar>;
+    /** {@inheritDoc IGrid.entries} */
+    entries(options?: IGrid.IteratorOptions): IGrid.EntryIterator<Scalar>;
+    /** {@inheritDoc IGrid.values} */
+    values(options?: IGrid.IteratorOptions): IGrid.ValueIterator;
+    /** {@inheritDoc IGrid.keys} */
+    keys(options?: IGrid.IteratorOptions): IGrid.KeyIterator;
+    /** {@inheritDoc IGrid.getValues} */
+    getValues(coords?: RangeCoords): Tuple.BoundedTuples<Scalar> | null;
+    /** {@inheritDoc IGrid.copyTo} */
+    copyTo(destination: IGrid, topLeft: CellCoords, from: RangeCoords): void;
+    /** {@inheritDoc IGrid.getAxis} */
+    getAxis(): RangeAxis;
+    /** {@inheritDoc IGrid.getCount} */
+    getCount(): number;
+    /** {@inheritDoc IGrid.getCoords} */
+    getCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.getMaxCoords} */
+    getMaxCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.clone} */
+    clone(cloneKey?: any): this;
+    /** {@inheritDoc IGrid.cloneEmpty} */
+    cloneEmpty(cloneKey?: any): this;
+    /** {@inheritDoc IGrid.setValues} */
+    setValues(values: Tuple.GridTuple<Scalar>): this;
+    /** {@inheritDoc IGrid.setValueAt} */
+    setValueAt(row: number, column: number, value: Scalar): void;
+    /** {@inheritDoc IGrid.delete} */
+    delete(coords: RangeCoords | null): boolean;
+    /** {@inheritDoc IGrid.clear} */
+    clear(): void;
+    /** {@inheritDoc IGrid.shift} */
+    shift(coords: RangeCoords, direction: Direction): boolean;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=_ReadObservedGrid.d.ts.map

package/types/src/cell/ICell.d.ts

@@ -124,12 +124,28 @@ export interface ICell {
      *
      * @remarks
      * Warnings differ from errors in that they may alter the display of the cell's value or type.
+     * A cell in a reference cycle, or downstream of one, carries one here — the text form of
+     * {@link getCircularReference}: the walk from this cell around the cycle and back
+     * ("Circular reference: A1 → B1 → A1"), or "Reads a circular reference at A1".
      */
     getWarnings(): readonly string[];
     /**
      * Retrieves any errors attached to the cell.
      */
     getErrors(): readonly string[];
+    /**
+     * The reference cycle this cell is in, or downstream of — or `null` when it is neither.
+     *
+     * @remarks
+     * Evaluated state, beside the value: a cell in a cycle, and every cell that reads one, is `0`
+     * (Excel, iterative calculation off), and this is the only thing that says why. Ask the cycle
+     * whether this cell is a member or a reader ({@link ICalculation.ICircularReference.isMember})
+     * and, under iterative calculation, whether it converged.
+     *
+     * The range-level view is `ICellRange.Feature.Circular` — `getCounts` for how many cells,
+     * `getRegions` for which, each region carrying this same object as its payload.
+     */
+    getCircularReference(): ICalculation.ICircularReference | null;
     /**
      * Returns the style information applied to the cell.
      *

package/types/src/cellRange/ICellRange.d.ts

@@ -1,5 +1,5 @@
 import { FormulaError, IRange, Scalar, InteropScalar, IRangeStats } from '@sheetxl/primitives';
-import { Bounds, ReferenceableClipboard } from '@sheetxl/utils';
+import { Bounds, Size, ReferenceableClipboard } from '@sheetxl/utils';
 import { ITypes } from '../type';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
@@ -1102,6 +1102,22 @@ export interface ICellRange {
      * Returns the absolute bounds for the range.
      */
     getBounds(): Bounds;
+    /**
+     * The size this range's content needs — what {@link getBounds} would report if the range had
+     * been {@link autoFit}. A pure query: nothing is measured onto the model and nothing is committed.
+     *
+     * @param options Measurement options. Default `{ axes: IRange.AxisSelection.Both }`.
+     *
+     * @remarks
+     * - The width is the sum of the per-column best fits and the height the sum of the per-row best
+     *   fits, so a single-column range answers "how wide must this list be" directly.
+     * - An axis left out of {@link BestFitOptions.axes} reports its current size.
+     * - Only the range's own content is measured, so the answer never depends on cells outside it.
+     *   (`autoFit` also scans outside the range, to prove a shrink is safe.)
+     * - Sheet protection is not consulted: reading a size cannot violate it, and a protected sheet
+     *   answers the same as an unprotected one.
+     */
+    getBestFit(options?: ICellRange.BestFitOptions): Size;
     /**
      * Indicates if the range is readonly only.
      *
@@ -1613,9 +1629,9 @@ export declare namespace ICellRange {
         includeMergeOverflow?: boolean;
     }
     /**
-     * Options for {@link ICellRange.autoFit}.
+     * Options for {@link ICellRange.getBestFit} — measurement only.
      */
-    interface AutoFitOptions extends ITransaction.OperationOptions {
+    interface BestFitOptions {
         /**
          * Best fit using the minimum amount of space required.
          *
@@ -1626,21 +1642,6 @@ export declare namespace ICellRange {
          * For example allowing numbers to round or use scientific notation.
          */
         minContent?: boolean;
-        /**
-         * Restricts autoFit to only grow, never shrink.
-         *
-         * @defaultValue false - adjust in both directions.
-         *
-         * @remarks
-         * This is useful when adjusting fonts and wan the columns to resize but not the rows.
-         */
-        expandOnly?: boolean | IRange.Axis;
-        /**
-         * If this is set to `true` then any headers that have custom sizes will be ignored.
-         *
-         * @defaultValue false
-         */
-        skipCustomSize?: boolean;
         /**
          * The axes to autoFit.
          *
@@ -1662,6 +1663,26 @@ export declare namespace ICellRange {
          */
         formulaView?: boolean;
     }
+    /**
+     * Options for {@link ICellRange.autoFit}.
+     */
+    interface AutoFitOptions extends BestFitOptions, ITransaction.OperationOptions {
+        /**
+         * Restricts autoFit to only grow, never shrink.
+         *
+         * @defaultValue false - adjust in both directions.
+         *
+         * @remarks
+         * This is useful when adjusting fonts and wan the columns to resize but not the rows.
+         */
+        expandOnly?: boolean | IRange.Axis;
+        /**
+         * If this is set to `true` then any headers that have custom sizes will be ignored.
+         *
+         * @defaultValue false
+         */
+        skipCustomSize?: boolean;
+    }
     /**
      * Options for {@link ICellRanges.getFlattened}.
      */
@@ -2191,11 +2212,20 @@ export declare namespace ICellRange {
         /** Cells inside a dynamic-array spill zone. Writing into one is a real failure mode. */
         readonly Spills: "spills";
         /**
-         * Evaluated state: cells whose calculation itself failed — mostly circular references.
-         * Distinct from {@link Feature.Error}: `#DIV/0!` is a successfully calculated error VALUE
-         * (the `Error` kind); `CalcError` is the engine failing to evaluate at all.
+         * Evaluated state: cells whose calculation itself failed. Distinct from
+         * {@link Feature.Error}: `#DIV/0!` is a successfully calculated error VALUE (the `Error`
+         * kind); `CalcError` is the engine failing to evaluate at all. A reference cycle is not a
+         * failure — its cells evaluate, to `0` — and is {@link Feature.Circular}.
          */
         readonly CalcError: "calcError";
+        /**
+         * Evaluated state: cells in a reference cycle, or downstream of one. Both evaluate to `0`
+         * (Excel, iterative calculation off) with nothing else to show for it — this is the marker.
+         * Regions group by cycle and by kind (`member` | `downstream`), so a block that reads one bad
+         * cell is ONE region, and each region's payload is the cycle itself
+         * (`ICalculation.ICircularReference` — members, counts, whether iteration settled it).
+         */
+        readonly Circular: "circular";
         /** Direct fill. */
         readonly Fill: "fill";
         /** Direct borders. */

package/types/src/condition/AnchoredConditional.d.ts

@@ -163,21 +163,41 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
     protected _rebaseConditionFormulas(json: any, from: IRange.CellCoords, to: IRange.CellCoords): boolean | null;
     /**
      * The extend half of a paste: fold the pasted `ranges` into THIS live rule — coalescing
-     * into clean rectangles where the union is exact — rather than minting a duplicate.
+     * into one clean rectangle — rather than minting a duplicate.
      *
      * @param ranges The pasted images of the rule's marked areas (already tiled/clipped).
      * @param jsonAtMark `JSON.stringify` of the rule's `toJSON()` at mark time.
-     * @returns `false` when this rule can no longer absorb the paste — deleted, or its
-     * definition changed since the mark — and the caller must clone instead.
+     * @returns `false` when this rule cannot absorb the paste — deleted, its definition changed
+     * since the mark, or the union would move the anchor — and the caller must clone instead.
      *
      * @remarks
      * Merging is provenance-keyed: only THE rule the areas were copied from extends, which is
-     * what keeps manually authored duplicates separate. When coalescing would move the anchor
-     * cell (first range's top-left), formulas rebase ({@link _rebaseAnchorFormulas}); if the
-     * rebase refuses, the new cells append as separate areas so the anchor stays put.
+     * what keeps manually authored duplicates separate.
+     *
+     * On top of provenance, a paste merges only when the union is a single rectangle whose
+     * top-left is still the rule's anchor. That is Excel's rule (desktop and online alike): a
+     * paste flush below or to the right of the applies-to merges into it, while one above, to
+     * the left, or with a gap mints a separate rule at top priority. The shape of it is that
+     * PASTE NEVER MOVES THE ANCHOR — growing down or right leaves the stored formula's frame
+     * alone, whereas growing up or left forces a rebase, which Excel is only willing to do for
+     * autofill. Hence fill merges in all four directions and paste in two.
      * @internal
      */
     _extendPastedRanges(ranges: readonly IRange.Coords[], jsonAtMark: string): boolean;
+    /**
+     * Re-anchors a freshly pasted CLONE, whose formulas still carry the SOURCE rule's frame, to
+     * its own anchor — the shift Excel applies when a copied rule lands as a new rule (copying
+     * `F5:F10`/`G5>5` to `F20` stores `G20>5`).
+     *
+     * The shift is source-anchor to clone-anchor; the hop through the copied cell cancels, since
+     * relative offsets are preserved by both halves of it.
+     *
+     * A rebase that cannot survive the move leaves the formulas as authored — the wrong frame,
+     * but live, which beats a rule of `#REF!`. Excel never hits this: it wraps modulo the sheet
+     * instead, the same divergence the io layer converts across.
+     * @internal
+     */
+    _rebaseClonedAnchor(anchorFrom: IRange.Coords): void;
     /**
      * The geometry half of {@link _extendPastedRanges}, shared with autofill (which needs no
      * liveness or definition guards — the rule was read live inside the fill's transaction):

package/types/src/conditionalFormat/ConditionalFormat.d.ts

@@ -134,7 +134,14 @@ export declare class ConditionalFormat extends AnchoredConditional<State, Commit
     /** @internal */
     protected _createSpatial(coords: IRange.Coords): ISpatialMap.IUpdatableValue;
     /** {@inheritDoc IConditionalFormat.update} */
-    update(properties: IConditionalFormat.Modifiers, options?: ITransaction.OperationOptions): this;
+    update(properties: IConditionalFormat.Modifiers | IConditionalFormat, options?: ITransaction.OperationOptions): this;
+    /**
+     * The modifiers that make one rule's definition another's: every mutually-exclusive key is
+     * named, so the target's old shape (`scale` vs `condition`+`style`) is cleared rather than
+     * merged with.
+     * @internal
+     */
+    static replaceModifiers(json: IConditionalFormat.JSON | null): IConditionalFormat.Modifiers;
     /** {@inheritDoc IConditionalFormat.toJSON} */
     toJSON(): IConditionalFormat.JSON | null;
     /** @internal */

package/types/src/conditionalFormat/IConditionalFormat.d.ts

@@ -123,8 +123,11 @@ export interface IConditionalFormat extends IAnchored, ICondition.Stateful, IPro
      * Only the keys named are touched. An explicit `null` **clears** a key — required when switching
      * a rule between its two shapes, since `condition`+`style` and `scale` are mutually exclusive
      * (setting one side also clears the other unless the caller named both).
+     *
+     * Passing another rule takes its whole definition — every key, cleared where the other rule
+     * has none — so the shape switches with it. The anchor is not part of it.
      */
-    update(properties: IConditionalFormat.Modifiers, options?: ITransaction.OperationOptions): this;
+    update(properties: IConditionalFormat.Modifiers | IConditionalFormat, options?: ITransaction.OperationOptions): this;
     /**
      * Returns a snapshot of the conditional that can be used for copying and archiving.
      */

package/types/src/conditionalFormat/IConditionalFormatCollection.d.ts

@@ -1,7 +1,7 @@
 import { ICellRange, ICellRanges } from '../cellRange';
 import { ICollection } from '../type';
+import { IAnchored } from '../anchored';
 import { IConditionalFormat } from './IConditionalFormat';
-import { ITransaction } from '../transaction';
 /**
  * Holds a collection of {@link IConditionalFormat}s.
  */
@@ -38,8 +38,12 @@ export interface IConditionalFormatCollection extends ICollection<IConditionalFo
 export declare namespace IConditionalFormatCollection {
     /**
      * Options for adding a {@link IConditionalFormat}.
+     *
+     * @remarks
+     * `replaceExisting` redefines the rule at `index` only when it is a scale rule of the same
+     * kind on exactly the same ranges — see {@link IAnchored.AddOptions.replaceExisting}.
      */
-    interface AddOptions extends IConditionalFormat.Properties, ITransaction.OperationOptions {
+    interface AddOptions extends IConditionalFormat.Properties, IAnchored.AddOptions {
     }
     /**
      * Options for searching for {@link IConditionalFormat}s.