@sheetxl/sdk 0.7.28-beta.3 → 0.7.28-beta.4

package/types/src/calculation/grid/ICalcGrid.d.ts

@@ -5,7 +5,7 @@ import { IListener } from '../../listener';
 import { IHistory } from '../../history';
 import { ISpatialQuery, ISpatialMap, ISparseGrid, Tuple } from '../../collections';
 import { IFormulaBlock } from '../formula';
-import { ContentfulSpatialValue, SpillEntry } from '../spatial';
+import { ContentfulSpatialValue, SpillEntry, CircularEntry } from '../spatial';
 import { ReferenceCoords, NamedReference } from '../Types';
 import { ICalculation } from '../ICalculation';
 /**
@@ -311,6 +311,14 @@ export declare namespace ICalcGrid {
          * These are guaranteed to not overlap.
          */
         pendingUpdates?: ISpatialMap.Entry<boolean>[];
+        /**
+         * Cells that entered or left a reference cycle (or the set downstream of one). A `null`
+         * value is a removal.
+         *
+         * @remarks
+         * These are guaranteed to not overlap.
+         */
+        circularUpdates?: ISpatialMap.Entry<CircularEntry | null>[];
     }
     /**
      * Returns from `ICalcGrid.beginUpdates()`.
@@ -324,13 +332,16 @@ export declare namespace ICalcGrid {
         spillSpatial: ISpatialMap<SpillEntry>;
         errorSpatial: ISpatialMap<string>;
         pendingSpatial: ISpatialMap<boolean>;
+        circularSpatial: ISpatialMap<CircularEntry>;
         contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
         notifyValues: ISpatialMap;
         notifySpillsInsert: ISpatialMap.Entry<SpillEntry>[];
         notifySpillsRemove: IRange.Coords[];
         notifyFormats: ISpatialMap;
         notifyPending: ISpatialMap<boolean>;
+        notifyCircular: ISpatialMap<CircularEntry | false>;
         pendingConflating: ISpatialMap.IConflatingEntries<boolean> | null;
+        circularConflating: ISpatialMap.IConflatingEntries<CircularEntry | false> | null;
         errorRemovesConflating: ISpatialMap.IConflatingEntries<null> | null;
         errorInsertsConflating: ISpatialMap.IConflatingEntries<string> | null;
         formatsConflating: ISpatialMap.IConflatingEntries | null;

package/types/src/calculation/spatial/CircularEntry.d.ts

@@ -0,0 +1,18 @@
+import { ICalculation } from '../ICalculation';
+/**
+ * What a sheet's circular index says about a cell (DESIGN-CIRCULAR-CALC.md §7.2): which
+ * reference cycle it belongs to, and whether it is in the cycle or merely downstream of it.
+ *
+ * @remarks
+ * The value stays what it is (`0`, Excel's answer with iterative calculation off); this is
+ * metadata beside it, the way `SpillEntry` marks a spill zone. Entries are interned per
+ * `(cycle, kind)` by the executor, so equal payloads are the same object and adjacent cells of
+ * one cycle coalesce into one region — and a region's payload IS the cycle, no id to look up.
+ */
+export interface CircularEntry {
+    /** The cycle; one live object per cycle, shared by every cell in it or downstream of it. */
+    readonly cycle: ICalculation.ICircularReference;
+    /** In the cycle, or a reader of it (transitively). Both evaluate to `0`. */
+    readonly kind: 'member' | 'downstream';
+}
+//# sourceMappingURL=CircularEntry.d.ts.map

package/types/src/calculation/spatial/index.d.ts

@@ -1,4 +1,5 @@
 export * from './SpillEntry';
+export * from './CircularEntry';
 export * from './ContentfulSpatialValue';
 export * from './FormulaSpatialValue';
 export * from './PrecedentSpatialValue';

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

@@ -40,31 +40,38 @@ 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}.
      */
-    circular: boolean;
+    shownGroup: 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

@@ -5,6 +5,7 @@ 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 */

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

@@ -2191,11 +2191,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.

package/types/src/dataValidation/IDataValidationCollection.d.ts

@@ -1,6 +1,6 @@
-import { ITransaction } from '../transaction';
 import { ICollection } from '../type';
 import { ICellRange, ICellRanges } from '../cellRange';
+import { IAnchored } from '../anchored';
 import { IDataValidation } from './IDataValidation';
 /**
  * Holds a collection of {@link IDataValidation}s.
@@ -38,8 +38,12 @@ export interface IDataValidationCollection extends ICollection<IDataValidation>
 export declare namespace IDataValidationCollection {
     /**
      * Options for adding a data validation to the collection.
+     *
+     * @remarks
+     * `replaceExisting` redefines the validation at `index` when it covers exactly the same ranges —
+     * see {@link IAnchored.AddOptions.replaceExisting}.
      */
-    interface AddOptions extends IDataValidation.Properties, ITransaction.OperationOptions {
+    interface AddOptions extends IDataValidation.Properties, IAnchored.AddOptions {
     }
     interface GetItemsOptions {
         /**

package/types/src/hyperlink/IHyperlink.d.ts

@@ -49,7 +49,9 @@ export interface IHyperlink {
      * @remarks
      * This has no counterpart in Excel; it is ours and applies to links opened in a browser.
      *
-     * @defaultValue `_self` for a location within this workbook, otherwise `_blank`.
+     * @defaultValue `_self` for a location within this workbook or a `mailto:`/`tel:`/`sms:`
+     * address (handled by another application, so there is nothing to show in a new tab),
+     * otherwise `_blank`.
      */
     getTarget(): string;
     /**

package/types/src/hyperlink/_Hyperlink.d.ts

@@ -1,5 +1,11 @@
 import { ITypes } from '../type';
 import { IHyperlink } from './IHyperlink';
+/**
+ * `true` for an address the browser hands to another application (`mailto:`, `tel:`, `sms:`)
+ * rather than rendering.
+ * @internal
+ */
+export declare const isHandlerScheme: (address: string) => boolean;
 export declare class Hyperlink implements IHyperlink {
     protected _t: () => string;
     protected _p: IHyperlink.Properties;

package/types/src/lib/utils/utils.browser.d.ts

@@ -1,6 +1,11 @@
 import { HostDetails } from './_Utils';
 import { LicenseDetails } from '../../license';
 export declare function getHostDetails(): Promise<HostDetails>;
+/**
+ * Only the loopback host is a dev environment. A dev *build* served on any other host (a LAN IP,
+ * a tunnel) is checked exactly like production: license domains apply and an evaluation shows
+ * the watermark.
+ */
 export declare function isDevEnv(): Promise<boolean>;
 /**
  * The runtime location - the current page url in the browser.

package/types/src/license/LicenseDetails.d.ts

@@ -8,6 +8,11 @@ export interface LicenseDetails {
     getCpuCount(): number;
     getMemory(): number;
     isEval(): boolean;
+    /**
+     * `true` when the licensed product may run `feature` without the license watermark: a valid
+     * license with no exceptions, or an evaluation on localhost / in a dev build. An evaluation on
+     * any other host answers `false` so the watermark shows.
+     */
     isValidFor: (feature: string) => boolean;
     getDeveloperCount(): number;
     getType(): string;

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

@@ -0,0 +1,20 @@
+/**
+ * Base of the control-flow signals the calculation engine throws THROUGH a formula's evaluation.
+ *
+ * @remarks
+ * A demand evaluation (a cell the topological sort could not order) reads its precedents lazily;
+ * a read that lands on a cell not yet calculated suspends the formula so that cell can go first,
+ * and a read that lands on a cell already suspended is a reference cycle. Both are raised from
+ * inside the read and unwind the whole evaluation to the executor, which is the only catcher
+ * that knows what to do with them.
+ *
+ * Every catch site on the evaluation path that turns an arbitrary throw into a `#VALUE!` — a
+ * function call, a lambda body, a lift over range members, the commit-site dereference — must
+ * let a signal pass: {@link isCalcSignal}. A signal is not an error and never becomes a value.
+ */
+export declare class CalcSignal {
+    readonly isCalcSignal: true;
+}
+/** `true` for a {@link CalcSignal} — a throw that must be rethrown, never turned into a value. */
+export declare const isCalcSignal: (e: unknown) => e is CalcSignal;
+//# sourceMappingURL=CalcSignal.d.ts.map