@sheetxl/sdk 0.8.0-beta.12 → 0.8.0-beta.13

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

@@ -36,46 +36,9 @@ export declare function maxGetEntireCoords(): IRange.Coords;
  */
 export declare const typeFromJsValue: (jsV: InteropScalar, checkDate?: boolean) => ScalarType;
 export declare function valueTypeToString(type: IFunction.ValueTypeJSON): string;
-/**
- * The largest magnitude Excel will PARSE from text or a formula literal — the biggest
- * 15-significant-digit value below 1E+308. Measured (formula-tests/probe-boundaries.ps1):
- * `=9.99999999999999E+307` commits, `=1.00000000000000E+308` is refused outright.
- *
- * An ENTRY rule only. Computed results are bounded by the double, not by this — `8.9E+307*2`
- * = 1.78E+308 is far past it and Excel keeps, compares and round-trips the value happily.
- */
 export declare const EXCEL_MAX_NUMBER = 9.99999999999999e+307;
-/**
- * Renders a number the way Excel coerces one to TEXT (`&`, CONCAT, `LEFT(1/3,5)`, ...).
- *
- * This is NOT display "General" (that one is column-width-aware and caps at ~11 digits —
- * `numfmt` implements it). Coercion General, measured against Excel 16.0
- * (`spreadsheetbench/formula-tests/probe-general-coercion.ps1`):
- *
- * 1. round to 15 significant digits, trim trailing fraction zeros (`0.1+0.2` → `0.3`,
- *    `2^0.5` → `1.4142135623731`);
- * 2. write the plain decimal expansion if it fits in 20 characters, sign excluded
- *    (`1/3*1E-3` → `0.000333333333333333` at exactly 20; `2^60` → `1152921504606850000`,
- *    integers pad with zeros);
- * 3. otherwise scientific with a two-digit-minimum exponent (`1E+20`, `3.33333333333333E-05` —
- *    note `-99999999999999900000` is still decimal, but `1E+20` is not);
- * 4. the DECIMAL SEPARATOR is the workbook locale's (`probe-general-locale.ps1`: `="" & 1.5`
- *    is `1,5` once Excel's decimal separator is `,`). Only that one separator moves —
- *    coercion never groups, so `1234.5` is `1234,5` and never `1.234,5`.
- *
- * This cannot route to `numfmt`: its `General` is the display one, its 11-character budget is
- * not configurable (there is no precision option on `FormatOptions`), and "15 significant
- * digits capped at 20 characters" is not expressible as an ECMA-376 pattern either —
- * `0.##############` counts decimal PLACES, not significant digits.
- *
- * Formula modules reach this as `IFormulaContext.toText`, which is the only entry point that
- * also handles non-numbers; this is the number-only form the coercion paths use.
- *
- * @param value The number to render.
- * @param runtime Supplies the locale profile. `IRuntime.getLocaleProfile` is the single
- * authority for separators — never derive one independently.
- */
 export declare function formatNumberGeneral(value: number, runtime: IRuntime): string;
+export declare function formatNumberLiteral(value: number, decimal?: string): string;
 /**
  * Renders any scalar the way Excel coerces one to TEXT — the full
  * {@link IFormulaContext.toText} rule, of which {@link formatNumberGeneral} is the number
@@ -135,38 +98,6 @@ noMemberFilter?: boolean): void | FormulaError.Known;
 export declare function convertTo2D(context: IFormulaContext, currentArg: any, // IRange or coords
 rangeType: string | null, scalarType: ScalarType | null, // the scalar preference. If not specified no coercion will occur.
 isDirect: boolean, errors?: 'reject' | 'accept' | null): IRange | any[][] | FormulaError.Known;
-/**
- * This will coerce a value and add it to the coercedArr. This is used in the argument coercion of typed functions.
- *
- * CoercedValues behave in special ways
- *
- * 1. If a value is *direct* (a scalar, whether typed or computed) it always coerces to the type.
- * 2. If a value is a MEMBER of an array or a reference
- *   a. It ignores everything except like values and errors
- * 3. We then coerce to Ranges.
- *
- * `isDirect` is Excel's "the argument itself" vs "a member of a container" distinction —
- * `SUM(1,TRUE)` is `2` but `SUM({1,TRUE})` is `1`. Callers derive it from the runtime shape of the
- * evaluated argument; see `isDirectArg` in `TypedFunction`.
- *
- * Two things it is NOT, both measured (`probe-direct-vs-literal.ps1`, pinned in
- * `__tests__/functions/coercion/DIRECT-VS-MEMBER.json`):
- *
- * - **Not literalness.** `{1,TRUE}` and `A1:A2` behave IDENTICALLY (members of both are filtered),
- *   and the COMPUTED `A2>0` behaves like a typed `TRUE`. A container being a literal or a
- *   reference changes nothing anywhere in the matrix.
- * - **Not a property of the argument alone.** Membership requires a slot that CONSUMES members:
- *   a scalar parameter takes one value, so a single-cell reference reaching it is dereferenced and
- *   IS the argument (`ABS(A1)` and `MONTH(A1)` are 1 with A1=TRUE, while `SUM(A1)` is 0). Hence
- *   `isMember` below is `!isDirect && flatten`, not `!isDirect`.
- *
- * The two halves at an aggregating slot: DIRECT arguments are COERCED (and a bad one errors —
- * `SUM(1,"7e")` is `#VALUE!`), MEMBERS are TYPE-FILTERED (skipped silently, never coerced —
- * `SUM({1,"7","7e","TRUE",TRUE})` is `1`).
- *
- * Some Built-in excel functions behave differently. When this occurs
- * the use an argument type of Scalar (no coerce) and manage themselves
- */
 export declare function addCoercedValue(context: IFormulaContext, coercedArr: FixedPackedArray | Scalar[], currentArg: any, isDirect: boolean, rangeType: 'p' | 'r' | 'm' | null, scalarType: ScalarType | null, // the scalar preference. If not specified then no coercion will occur.
 allowError: boolean, flatten: boolean, // indicates we should flatten
 errors?: 'reject' | 'accept' | null, // effective error policy (TypedFunction resolves the default)
@@ -187,39 +118,7 @@ export declare function addCoercedScalar(context: IFormulaContext, coercedArr: F
 /**
  * Minimal validation used from the return value of functions.
  */
-/**
- * Makes a raw JS double look like an Excel one: ANY non-finite value is #NUM! — NaN and
- * ±Infinity alike. `9E+307*2`, `9E+307+9E+307` and `9E+307/0.1` all report `ERROR.TYPE` 6, and a
- * raw NaN or ±Infinity written through the Value2 API lands as #NUM! too. Infinity does NOT mean
- * #DIV/0!: Excel never derives that error from a float, it raises it deliberately before
- * dividing. Functions say so themselves by returning `FormulaError.BuiltIn.Div0`.
- *
- * Measured against Excel 16.0 (formula-tests: probe-num-overflow.ps1, probe-boundaries.ps1,
- * probe-api-nonfinite.ps1). This rule applies at every boundary; the SUBNORMAL rule does not —
- * see {@link flushSubnormal}.
- */
 export declare function normalizeNumber(value: number): number | FormulaError.Known;
-/**
- * Zeroes a magnitude below the smallest NORMAL double, which also folds -0 to 0.
- *
- * "Excel has no subnormals" is true of its ARITHMETIC and of its write path, and false of its
- * function results — so this is a rule three callers apply deliberately rather than one the
- * boundary applies to everything (measured 2026-08-30,
- * `fn-battery/mathTrig/adhoc-subnormal-store`):
- *
- * * MULTIPLICATION, DIVISION and EXPONENTIATION flush. `1E-300*2.224E-8` is 0 while
- *   `1E-300*2.226E-8` survives, `2^-1022/2` is 0, and the flush lands before the next operator
- *   reads it — `=1/(1E-300*1E-100)` is #DIV/0!, not a huge number.
- * * ADDITION and SUBTRACTION do NOT. With `Z1` holding 5E-324, `Z1+0`, `-Z1` and `Z1+Z1` all
- *   keep the value, and `Z1*1` is 0.
- * * A FUNCTION RESULT does not either, and it survives the cell it is stored in: `EXP(-745)` is
- *   5E-324 and `EXP(-745)*1E300` is 4.94E-24. SUM, MIN, ABS, IF, INDEX and ROUND all pass it
- *   through. EXP reaches zero only below -745.1332, the true IEEE underflow.
- * * The API WRITE path flushes: `Double.Epsilon` set through `Value2` reads back 0.
- * * The BOOLEAN reading flushes, and so does `SWITCH`'s comparison — both are tests against zero
- *   (`IF(EXP(-745),…)` takes the false branch and `SWITCH(EXP(-745),0,…)` matches), which the
- *   comparison OPERATORS do not do: `EXP(-745)=0` is FALSE.
- */
 export declare function flushSubnormal(value: number): number;
 export declare function minCoerce(value: any, context?: IFormulaContext | null, type?: string): any;
 /**
@@ -281,14 +180,6 @@ export declare const BooleanCoerceTypes: readonly InteropScalarType[];
  * `date` has to coerce from number, or every date function over a range matches nothing at all.
  */
 export declare const DateCoerceTypes: readonly InteropScalarType[];
-/**
- * What a `null` read accepts. Coercing TO `null` asks for each value's empty equivalent — `0`,
- * `''`, `false` — which is exactly what the branch in {@link createCoerceScalarFn} already
- * implemented, and which was unreachable for the same reason `date`'s was (CALC-ISSUES §14 H2).
- *
- * Not reachable from a declaration — `TypedFunction` normalizes a `null` scalar param to "no
- * type" — so this serves a direct `toType(ScalarType.Null)` caller.
- */
 export declare const NullCoerceTypes: readonly InteropScalarType[];
 export declare const AllScalarTypes: readonly InteropScalarType[];
 //# sourceMappingURL=PrimitiveUtils.d.ts.map

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

@@ -18,29 +18,6 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     protected _localRangeStats: IRangeStats | null;
     /** The `options` {@link _localRangeStats} was built for — the memo's key. See `getStats`. */
     protected _localRangeStatsOptions: IRange.IteratorOptions | undefined;
-    /**
-     * What a cell the grid does not store reads as - `null` for an ordinary range.
-     *
-     * @remarks
-     * A grid can hold only part of its range's answer: a watch body's blank region shares one value
-     * that the engine keeps on the block rather than writing per cell (PLAN-WATCHES-BLANK-AWARE
-     * §4c), so within that body "absent" means "the shared answer", never "empty". A range with a
-     * non-null empty value is therefore DENSE: `getValueAt` answers it for every absent cell, and
-     * the iterators visit those cells whether or not `includeEmpty` was asked, since they are
-     * content. A STORED empty (`null`) is still empty.
-     *
-     * It is also how an elementwise operation carries its answer for the blank cells: `map`,
-     * `broadcast` and `zip` walk what their operands STORE, answer the absent region once, and
-     * hand that answer to the result here rather than writing it as a run per line — so the next
-     * operator finds the blank region again and a whole-column chain stays O(stored + runs)
-     * (CALC-PERFORMANCE §5). `fillEmpty` over the whole range sets it the same way.
-     *
-     * Every reader agrees on it: the iterators and `getValueAt` above; a transform over the same
-     * grid carries it (`slice`, `toType`, `clone`); one that derives a grid either writes every
-     * position or writes it out first (`_materializeEmpty` — `resize`, `tile`, a partial `fill`);
-     * and a reader that goes to the grid rather than through the range (the stats walk, the calc
-     * grid's write of a result, a sheet write) reads the written-out grid.
-     */
     protected _absentValue: Scalar;
     constructor(runtime: IRuntime, values: ISparseGrid<Scalar>, coords: IRange.Coords | null, optionsIterator?: IRange.IteratorOptions | null, isLiteral?: boolean, isDirectScalar?: boolean, absentValue?: Scalar);
     /** @inheritdoc IRange.argsort */
@@ -238,29 +215,6 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
      * Returns self but accounts for literal status.
      */
     protected _self(): this;
-    /**
-     * Returns this range with its read type dropped, or `this` when there is nothing to drop.
-     *
-     * @remarks
-     * For a range whose values are no longer the ones the type described — see `map`. `coerce` goes
-     * with it: it is inert without a `type` (both `_entries` and `_coerceValue` gate on one), and
-     * leaving it behind would let the SOURCE's coercion rules apply to a later `toType` on values
-     * the source never held.
-     *
-     * **The contract, so this stays consistent.** A read type is a claim about the values a range
-     * HOLDS. It survives exactly as long as those values do:
-     *
-     * | operation | type | why |
-     * | --- | --- | --- |
-     * | `map` · `broadcast` · `zip` | **dropped** | a callback produced new values; the range cannot know what they are. A caller that DOES know retypes after — `TypedFunction` does, from the declared return type. |
-     * | `filter` · `slice` · `sort` · `resize` | **kept** | selection and rearrangement only. Every surviving member is one the source already held, so the claim is still true — a filtered `number` range is still a `number` range. |
-     * | `replace` · `fillEmpty` · `fill` · `mask` | **kept** | substitution with CALLER-supplied values. Kept deliberately (these are overwhelmingly used to write same-typed values), but it is the one row that is a judgement rather than a consequence: a caller that substitutes a differently-typed value re-reads it through the old type. Unaudited; no instance found.
-     *
-     * Note this is NOT "any operation returning a range drops its type" — only the three that run
-     * a callback do. Getting that wrong in either direction is a silent value bug: dropping too
-     * eagerly loses `MONTH`'s number-ness, keeping too eagerly is CALC-ISSUES item 36
-     * (`SUMPRODUCT(--ISNUMBER(SEARCH(...)))` → 0).
-     */
     protected _untyped(): this;
     /** This range's options without its skips: for a result whose cells are laid out anew. */
     protected _optionsFresh(): Omit<IRange.IteratorOptions, 'axis'> & {
@@ -308,20 +262,6 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     /** @inheritdoc IRange.isIRange */
     get isIRange(): true;
 }
-/**
- * A `Range` whose `getCoords()`/shape is unchanged, but whose `getStats()` is rescoped to
- * `visibleCoords` — used by `condition/_ConditionUtils.ts` so `AverageOperator`/`TopNOperator`
- * get correct order-dependent Top N / Average semantics under a running filter mask
- * (`condition/DESIGN-FILTER.md` §2), via `RangeStats.toLocalCoords`.
- *
- * Lives here (rather than in `condition/`, where it's used) so `extends Range` is resolved by
- * plain source order within this file, not cross-module import order: `condition/` sits deep in
- * an import cycle that reaches back into `primitives/` through `PrimitiveUtils.ts` →
- * `sheet/_SheetUtils.ts` → … → `condition/Condition.ts`, and a top-level `extends Range` declared
- * in `condition/` can execute before that cycle has finished defining `Range`
- * (`ReferenceError: Cannot access 'Range' before initialization` — reproduced 2026-08-18 by
- * running the actual bundle; see git history).
- */
 export declare class _VisibleScopedRange extends Range {
     protected _visibleCoords: readonly IRange.Coords[];
     constructor(runtime: IRuntime, values: ISparseGrid<Scalar>, coords: IRange.Coords, visibleCoords: readonly IRange.Coords[]);

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

@@ -1,110 +1,4 @@
 import { Scalar, LocaleProfile } from '@sheetxl/primitives';
-/**
- * Excel's comparison rule for {@link Scalar} values, as one total order.
- *
- * @remarks
- * This is the rule behind `=`, `<>`, `<`, `<=`, `>`, `>=`, behind the criteria comparisons in
- * `COUNTIF`/`SUMIF`/`DSUM`, and behind `SORT`/`SORTBY`/`IRange.argsort`.
- *
- * ### Not public API
- *
- * `@sheetxl/primitives` declares the rule as `IFormulaContext.compare` and stubs it with a basic
- * ordering; THIS is the Excel one, and it is deliberately not exported from the package barrel.
- * Callers -- including `@sheetxl/formulas`, which sits BELOW this package and cannot import it at
- * all -- reach it by way of the calculation context they are handed, which is what binds the rule
- * to the workbook's locale. Only `CalculationContext` and the sort collators call in here directly;
- * anything reading the global `FormulaContext` singleton outside an installed scope gets the basic
- * ordering instead, which is a bug at the call site.
- *
- * ### Cross-type: rank, never coerce
- *
- * Excel does not coerce across types to compare; it ranks them, so **every** number is less than
- * **every** text, and every text is less than every logical:
- *
- * > `number` &lt; `text` &lt; `FALSE` &lt; `TRUE`
- *
- * Hence `=1<"0"` is `TRUE` and `="9">TRUE` is `FALSE`. Errors sort last here so the order stays
- * total. The OPERATORS never reach that case -- an error operand propagates before any comparison
- * happens -- but a criteria does: `COUNTIF(A1:A9,">=#N/A")` counts the `#N/A` rows, and the code
- * order below is Excel's, #NULL! &lt; #DIV/0! &lt; #VALUE! &lt; #REF! &lt; #NAME? &lt; #NUM! &lt;
- * #N/A (measured, `formula-tests/probe-criteria-empty-operand2.ps1`).
- *
- * A criteria does NOT rank across types the way an operator does, though: it only considers values
- * of the operand's own type, so `COUNTIF` with `"<TRUE"` counts no number even though `=1<TRUE` is
- * `TRUE`. That partition lives in `Criteria`, not here.
- *
- * ### Blank
- *
- * A blank cell takes the *other* operand's type -- `0`, `""`, or `FALSE` -- so `=A1=0`, `=A1=""`
- * and `=A1=FALSE` are all `TRUE` for an empty `A1`. Blank against blank is equal. (This is why
- * `ISBLANK` exists: no comparison can distinguish a blank from those three values.)
- *
- * ### Numbers
- *
- * Equal when they agree to 15 SIGNIFICANT digits -- the same clamp Excel uses for display, which
- * is what makes `=(0.1+0.2)=0.3` report `TRUE` while `=1E-12=2E-12` reports `FALSE`. Being
- * relative matters at both ends: `=2^60=1152921504606850000` is `TRUE` even though subtracting
- * them gives `-3072`. Excel forgives float noise at the COMPARISON, never in the arithmetic.
- *
- * ### Text
- *
- * Case-INSENSITIVE (`="PM"="pm"` is `TRUE`; `EXACT` is the case-sensitive form) and COLLATED in
- * the workbook locale, so `="a"<"B"` is `TRUE` and `="ä"<"z"` is `TRUE`. Accents and punctuation
- * are real differences: `="a"="ä"` and `="co-op"="coop"` are both `FALSE`.
- *
- * Case is folded OUT of the operands and the collator then runs at FULL strength, rather than the
- * collator being weakened to `sensitivity: 'accent'`. The two are not the same: in ICU, case, WIDTH
- * and KANA are all tertiary differences, so a strength low enough to ignore case also ties
- * fullwidth `Ａ` with `A` -- which Excel does not (`probe-text-equality-nls.ps1`). Folding case
- * separately is the only way to ignore one tertiary difference and keep the others.
- *
- * The case toggle is therefore what a caller's `sensitivity` selects: `accent`/`base` fold, and
- * `variant`/`case` do not. That is the user-facing switch the **sort** feature exposes
- * (`Sort.CaseSensitiveOptions` / `LocaleProfile.collator`); the word sort below, the expansions,
- * and the collation locale are shared either way. Sort does use a different TYPE order (errors and
- * blanks last, blanks last even descending).
- *
- * ### Expansions
- *
- * A closed set of characters compares EQUAL to a letter sequence -- `="straße"="strasse"` and
- * `="æ"="ae"` are both `TRUE`, and so are the ligatures and the LJ/NJ/DZ digraphs. This is Windows
- * NLS behavior that ICU does not reproduce at any strength: at `accent` these are all unequal, and
- * at `base`, where they do fold, accents fold away with them. They are therefore rewritten before
- * collating, by `foldForCompare` in `./TextFold` -- which is also where the measured membership is
- * documented, and which `UNIQUE` shares for the hashing side of the same rule.
- *
- * ### Word sort
- *
- * On top of the collator, Excel applies the "word sort" its Sort dialog documents -- and, measured,
- * the operators apply it too. Dashes and apostrophes do not count when ordering; they only break a
- * tie, where the string carrying them sorts LAST:
- *
- * > `"coop"` &lt; `"co-op"` &lt; `"cop"`
- *
- * A plain collator gives `"co-op" < "coop"` instead (`-` outranks `o`), which is the bug this
- * exists to avoid. Equality is untouched -- the tiebreak never returns 0 for distinct strings, so
- * `="co-op"="coop"` stays `FALSE`. Other punctuation is ordinary and still sorts before letters
- * (`="a_b"<"ab"` is `TRUE`), which is why the collator stays non-ignorable.
- *
- * The ignorable set is the one Excel 16.0 actually uses, not a Unicode category -- notably U+2019
- * (the "smart" apostrophe Word autocorrects to) is NOT in it, while U+02BC is. See
- * `formula-tests/probe-wordsort.ps1`.
- *
- * ### Punctuation
- *
- * Every other mark is ordered by {@link _compareOrdered} rather than by the collator, because ICU
- * and Windows NLS disagree about punctuation almost completely -- 191 of 741 measured pairs invert.
- * `="*"<"?"` is `TRUE` in Excel and `FALSE` from a bare collator. Three classes, code-point order
- * inside each: ordinary punctuation, then `+ < = >`, then digits and letters (where ICU is already
- * right and still decides). See that function for what is measured and what is generalized.
- *
- * ### Determinism
- *
- * Collation is ICU data and varies by host. The locale is always the workbook's persisted tag,
- * never the ambient host locale (passing `undefined` to `localeCompare` is a bug -- it reads the
- * host). Note that a `small-icu` Node build carries `en-US` only and will silently collate a
- * `de-DE` workbook as English; ship `full-icu` for non-English workbooks.
- */
 export declare const ScalarCollation: {
     /**
      * The fixed `Intl.Collator` options for Excel's text comparison.

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

@@ -112,25 +112,6 @@ export declare const EmptyAggregates: Readonly<IRangeStats.Aggregates>;
  * 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, 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
- * layouts). Coerces exactly as the aggregate scan does, so `AVERAGEA`'s text-counts-as-zero
- * agrees here and a trailing text cell defeats the cancellation snap just as a trailing `0`
- * does.
- *
- * Returns `undefined` when the query holds no numbers.
- *
- * @remarks
- * Deliberately NOT part of `AggResults` and NOT segment-cached. Row-major "last" is a position
- * comparison, and segments merge in GRID-axis order, so carrying it through the cache would mean
- * tracking `(row, col)` per value in `_doAggregateValue` — a cost on the hottest loop in the
- * engine, paid by every caller, to serve a rule that fires only on catastrophic cancellation.
- * Instead this is a separate scan behind {@link mayCancel}'s gate, which rejects any ordinary
- * total using `min`/`max` the aggregates already carry. A forward scan tracking the maximum
- * `(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, skipOrigin?: IRange.CellCoords): number | undefined;
 /**
  * Resolves an iterator's `coerce` option into the callable pair the scans use.

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

@@ -165,12 +165,6 @@ export declare class PageLayout implements IPageLayout {
     _getBreaks(axis: IRange.Axis): readonly IPageLayout.BreakJSON[];
     /** @internal */
     _setBreaks(axis: IRange.Axis, breaks: IPageLayout.BreakJSON[], options?: ITransaction.OperationOptions): this;
-    /**
-     * Moves the breaks as rows (or columns) `start` to `end` are inserted or deleted: a break at or
-     * after an insert moves with it, a break before a deleted row goes with it, and a break past a
-     * delete moves back. Excel's behavior (`scripts/openpy-parity/probe-print-setup.ps1`).
-     * @internal
-     */
     _shiftBreaks(axis: IRange.Axis, start: number, end: number, isInsert: boolean): void;
     /** The manual breaks on an axis. */
     protected _getPageBreaks(axis: IRange.Axis): IPageLayout.IPageBreak[];

package/types/src/reference/ReferenceUtils.d.ts

@@ -64,14 +64,16 @@ export declare function shiftReferenceAxis(start: number, end: number, shiftStar
  * @param immuneEnd `true` if the end endpoint must not move.
  */
 export declare function moveReferenceAxis(start: number, end: number, moveBy: number, immuneStart?: boolean, immuneEnd?: boolean): [start: number, end: number];
+export declare function edgeMoveReferenceAxis(start: number, end: number, cutStart: number, cutEnd: number, moveBy: number, toOtherSheet: boolean): [start: number, end: number] | null;
 /**
  * Whether a cut of `from` carries `reference` with it.
  *
  * @remarks
  * Excel's test, and the graph's: a reference moves only when the cut rectangle FULLY ENCLOSES it.
  * Cut A1:C3 and `=SUM(A1:B2)` follows to the destination; `=SUM(A1:C5)` reaches outside the cut
- * and so is left exactly where it is, pointing at cells that are now empty. There is no partial
- * answer and no split - a reference that is only half carried would name two different rectangles.
+ * and so is not carried. A reference that is only half carried would name two different rectangles;
+ * the one partial answer is a cut of its EDGE, which moves that edge alone
+ * ({@link edgeMoveReferenceAxis}).
  *
  * A formula BLOCK asks a longer version of this question, because each of its cells has a
  * reference of its own and all of them have to be enclosed; see `movePrecedents`.

package/types/src/richData/RichDataRegistry.d.ts

@@ -50,6 +50,12 @@ export declare namespace RichDataRegistry {
      * Display only: the value still reads as nothing to calculation.
      */
     function toDisplayText(value: IRichData): string | null;
+    /**
+     * The text that stands for `value` as a whole, as in the formula bar: its display text
+     * ({@link toDisplayText}), else the label its kind was given in parentheses, `(Image)`, else
+     * `(Rich Object)`.
+     */
+    function toPlaceholderText(value: IRichData): string;
     /**
      * The `ScalarType` `value` lays out as in a cell: its primitive's when it has one (a hyperlink
      * named by a number is a number); `String` when it reads as nothing but shows text (an entity's

package/types/src/scripting/TypedFunction.d.ts

@@ -1,11 +1,5 @@
 import { ScalarType, FormulaError, IRange, IFunction, IFormulaContext } from '@sheetxl/primitives';
 import { FixedPackedArray } from '../primitives/PrimitiveUtils';
-/**
- * The per-call shape of a declaration that carries a repeating group, resolved from the ARGUMENT
- * COUNT alone (`Repeating<T>`; DESIGN-REPEATING §2). Excel is measured never to disambiguate by type —
- * `SORTBY(array, by1, by2, o2)` is refused where a type-directed parse would have read argument 2
- * as `by_array2` — so the arithmetic is the whole rule.
- */
 /**
  * What `_exec` needs to know about ONE parameter position, decided once per declaration (and
  * once per expanded {@link RepeatPlan}) rather than on every call: the normalized value types,
@@ -56,14 +50,6 @@ interface ParamSpec {
      * `#VALUE!`. Today that is the multi-area union; the body reads it through `getArgs`.
      */
     reportType: boolean;
-    /**
-     * `ReportType<NoLift<T>>` (either order): a multi-cell REFERENCE at this scalar slot neither
-     * lifts (`NoLift`) nor refuses (`ReportType`), it is handed to the body WHOLE, as one
-     * `IReferenceRange`; an array still lifts. Excel's `Boolean|Range` slot shape, no `Array` bit:
-     * LINEST/LOGEST `const`/`stats`, TREND/GROWTH `const` (DESIGN-LIFT-AND-DEMAND §1). One flag
-     * because the coercion loop and both lift walks ask the same question, and a slot carrying only
-     * one of the two markers changes nothing here.
-     */
     wholeReference: boolean;
     /** The effective policy and its `allowError` half — static per declaration. */
     policy: 'reject' | 'accept' | null;
@@ -139,15 +125,6 @@ export declare class TypedFunction implements IFunction {
     };
     protected _lc: boolean;
     protected _rlc: boolean;
-    /**
-     * Some parameter declares `NoLift<T>` — a multi-cell REFERENCE at that non-repeating scalar
-     * slot is `#VALUE!` rather than a broadcast, per parameter as Excel needs
-     * (`NETWORKDAYS.INTL` refuses a reference at its date slots and lifts at `weekend`,
-     * CALC-ISSUES 31; DESIGN-FUNCTION-ARGUMENTS §2.3, §6). A declaration bit and not a body
-     * concern, because the body never runs: without it the lift runs instead and answers one
-     * result per cell, so there is nothing for a body-facing API to express. Precomputed so the
-     * common call pays one boolean.
-     */
     protected _nl: boolean;
     /** Whether ANY parameter (or repeating slot) is `Lazy` — the guard on the wrapping below. */
     protected _lz: boolean;
@@ -170,16 +147,6 @@ export declare class TypedFunction implements IFunction {
      * through the parameter's coercion.
      */
     protected _rs: ScalarType | null;
-    /**
-     * The reference half of the declared RETURN KIND pair (DESIGN-DECLARATION-SURFACE §3.1): may
-     * this call answer a REFERENCE? True for a declared `IReferenceRange` return (`r:'p'` —
-     * OFFSET/INDIRECT/XLOOKUP/TAKE/DROP) and for an UNTYPED return (`any` — the pass-through
-     * selectors IF/IFS/SWITCH/CHOOSE/INDEX, and any UDF that declares nothing). False for every
-     * provable value — a declared scalar (`'*'` included: IFERROR) or a ranged array producer.
-     *
-     * Read at the call exit (a value-declared function's reference result is demoted to its VALUE)
-     * and at the `*`-slot union pass-through.
-     */
     protected _rref: boolean;
     /**
      * The declared result kind is a SCALAR member of {@link ValueKind} — `ROW(A1)` is the number 3
@@ -195,15 +162,6 @@ export declare class TypedFunction implements IFunction {
     protected _ps: ParamSpec[];
     /** Index of the repeating-group parameter, or `-1`. */
     protected _gi: number;
-    /**
-     * Index of the one parameter that consumes a VARIABLE number of arguments — a repeating group or
-     * a trailing rest — or `-1`.
-     *
-     * `getArgs()` indexes by PARAMETER (DESIGN-FUNCTION-ARGUMENTS §3.3) and this is the single place
-     * parameter numbering and argument numbering part company, so it is resolved once here rather
-     * than re-derived per call. `_gi` cannot serve: it covers `Repeating<T>` only, and a plain rest
-     * parameter is the same thing to a body asking which parameter its argument landed in.
-     */
     protected _va: number;
     /** The declaration's `volatile`, read once: what the call frame carries for `defer`. */
     protected _vol: boolean;
@@ -214,28 +172,6 @@ export declare class TypedFunction implements IFunction {
     constructor(json: IFunction.DeclarationJSON, fn: (...args: any) => any, getContext: () => IFormulaContext | null | undefined, desc?: IFunction.DescriptorJSON | ((locale?: string) => Promise<IFunction.DescriptorJSON>) | null, builtIn?: boolean);
     /** @inheritdoc IFunction.execute */
     execute<R = any>(...args: any[]): R;
-    /**
-     * Resolves this call's {@link RepeatPlan} from the argument count, or `null` when the count is
-     * one the declaration refuses.
-     *
-     * `n = (argc − prefix − suffix) / period` and a non-zero remainder is an error, with ONE
-     * exception: a group whose last slot is optional also accepts `period − 1` variable arguments,
-     * which is `n = 1` with that slot omitted. Those two rules produce SORTBY's measured arities
-     * exactly — 2 and 1+2n, with 4 refused (probe rows H7/H10).
-     *
-     * A trailing suffix may be OPTIONAL, so `suffix` is solved for alongside `n` rather than fixed.
-     * SWITCH is the case: `prefix 1, period 2, one optional suffix` yields argument parity as the
-     * whole rule — odd is pairs alone, even is pairs plus a default — and refuses argc 2, because
-     * dropping the suffix still leaves the group owing its one repetition. That matches Excel row
-     * for row (probe-switch-arity.ps1: 3/4/5/6 legal, 1 and 2 refused). The group's minimum stays
-     * 1 regardless of the suffix; nothing here ever resolves `n = 0`.
-     *
-     * Period 1 ends at one rest-marked slot instead — see {@link RepeatPlan.params}.
-     *
-     * Must stay in step with `CompilerUtils.resolveRepeat`, its COMPILE-TIME twin. That one decides
-     * `#PARSE!` and the per-argument binding, so a rule added only here is simply never reached: the
-     * formula is refused before it ever executes.
-     */
     protected _plan(argsLength: number): RepeatPlan | null;
     /**
      * Folds the flat, per-argument-position values back into the shape the BODY declares: the group
@@ -260,53 +196,8 @@ export declare class TypedFunction implements IFunction {
      * writes anything into it.
      */
     protected _exec<R = any>(argsEval: any[], argsLength: number): R;
-    /**
-     * `NoLift<T>`: is a multi-cell REFERENCE sitting at a non-repeating scalar parameter marked to
-     * refuse one? (DESIGN-FUNCTION-ARGUMENTS §2.3, §2.7 rule 3.)
-     *
-     * Three qualifications, each measured rather than assumed
-     * (`fn-battery/adhoc-container-at-slot{,2}`, Excel 16.0 build 20326):
-     *
-     * - **A REFERENCE, not an array.** `MROUND({3,4,5},5)` spills where `MROUND(A1:A3,5)` is
-     *   `#VALUE!`, so an array at the same slot still lifts. That is the whole reason this reads the
-     *   argument's shape rather than trusting the parameter: the engine hands a reference over as
-     *   COORDS and an array as an `IRange`.
-     * - **MULTI-CELL.** A 1×1 reference collapses to its member and is an ordinary argument
-     *   (`EFFECT(J1,4)` over a text cell is `0.0824…`).
-     * - **NON-REPEATING.** A repeating scalar slot ABSORBS a container as members whatever the
-     *   function's heritage — `GCD(C1:C3)` is 4, `MULTINOMIAL(A1:A3)` is 27720 — and those were the
-     *   rows that could have broken the rule and did not. Period-1 groups marshal through the rest
-     *   branch and are already excluded by `rest`; period 2+ expand to per-argument entries, so the
-     *   group's span is skipped explicitly.
-     *
-     * A multi-AREA union `(A1:A3,C1:C5)` arrives as an ARRAY of areas and is not treated as a
-     * reference here — unmeasured at these slots, and inventing a verdict for it would be the kind
-     * of unification §2.0 warns about.
-     */
     protected _refusesReferenceLift(params: IFunction.ParameterTypeJSON[] | null | undefined, paramLength: number, argsEval: any[], argsLength: number, plan: RepeatPlan | null): boolean;
-    /**
-     * The consumer half of the lift (CALC-ISSUES item 22 change 2). Each `refLifts` entry is a
-     * reference-only (r:'p') argument holding a producer lift's preserved per-element results.
-     * The function runs once per output cell through {@link _exec} — a full re-invocation, so
-     * every other argument re-coerces and the body re-runs per element (measured:
-     * `SUBTOTAL(9,OFFSET(A1,{0;1},0,1,1),B1:B2)` = 31|32 — the plain range is consumed WHOLE in
-     * each call). Shape rules are the scalar lift's: output dims = max over entries, dim-1 tiles,
-     * a shorter dim pads `#N/A` (probe-lift-member-coercion.ps1: 2×1 beside 1×2 → 2×2).
-     *
-     * An element that is not a reference (a plain value in a reference-only position) is not
-     * special-cased: the per-element coercion answers exactly as it would for the unlifted call
-     * (item 23b's `#PARSE!`), which becomes that member of the output.
-     */
     protected _refLift<R>(context: IFormulaContext, argsEval: any[], argsLength: number, refLifts: RefLiftEntry[], firstCell?: boolean): R;
-    /**
-     * @hidden
-     * Vends a NEW instance whose evaluation context comes from `getContext` — the public-API
-     * scope vend behind `IFunctionCollection.getByName(name, { sheet })` (CALC-ISSUES item 35).
-     * The registry instance is what the ENGINE holds and its evaluation path stays
-     * allocation-free; a vended instance additionally owns a private fast-path slot the engine
-     * never loads, so callers may hold it across awaits (or re-enter it) without racing the
-     * engine's synchronous argument hand-off.
-     */
     _withContext(getContext: () => IFormulaContext | null | undefined): TypedFunction;
     /** @inheritdoc IFunction.getName */
     getName(): string;

package/types/src/sheet/IWorksheet.d.ts

@@ -784,7 +784,7 @@ export declare namespace IWorksheet {
     /**
      * The events that carry a {@link ChangeEvent}: what {@link ChangeEvent.getKind} names.
      */
-    type ChangeEventKey = 'onDataChange' | 'onStyleChange' | 'onLayoutChange' | 'onMergesChange' | 'onSpillsChange';
+    type ChangeEventKey = 'onDataChange' | 'onStyleChange' | 'onMergesChange' | 'onSpillsChange';
     /**
      * What a change event announces: where the change landed and what wrote it.
      *
@@ -1024,11 +1024,8 @@ export declare namespace IWorksheet {
          * for "cell geometry moved".
          * * This can be be due to row/column sizes changes or changing the max rows columns.
          * * Zoom and viewport do not change the underlying layout.
-         *
-         * @param source The sheet.
-         * @param event The whole sheet: sizes are announced by the headers, which do not say where.
          */
-        onLayoutChange?(source: IWorksheet, event: IWorksheet.ChangeEvent): void;
+        onLayoutChange?(source: IWorksheet): void;
         /**
          * Called when which rows are hidden has changed.
          */

package/types/src/sheet/NamedCellRange.d.ts

@@ -4,27 +4,6 @@ import { INamedFormulasCollection } from '../calculation/INamedFormulasCollectio
 import { NamedRange } from './NamedRange';
 import { IWorksheetInternal } from './Worksheet';
 import { SheetRangeOptions } from './SheetRange';
-/**
- * A defined name as a NODE in the calculation graph — an `INamedRange` whose coords are the
- * name's ANCHOR (its defining cell), not a target.
- *
- * @remarks
- * This is how a name rides inside an ordinary `ICellRanges` graph answer next to plain cell
- * ranges: the brand (`isINamedRange`) carries the identity, the coords carry the anchor, and the
- * four graph methods answer the NAME question rather than the cell question at those coords
- * (DESIGN-NAMED-FORMULAS.md §4). Contrast {@link NamedRange}, which `getRange('Revenue')` returns
- * over the name's *target* — same brand, different referent, and only this one exists for a value
- * name (`Doubled = Base*2`), which has no target at all.
- *
- * The anchor matters to precedents (relative references in the body resolve from it) and is only
- * a label for dependents (the symbol index is global). Lead with the name when displaying one —
- * two names authored from the same active cell share an anchor address, and the name is the fact.
- *
- * Built from a {@link NamedNodeInfo} — plain data — and answers its five name questions by
- * resolving the id against the collection when asked. It does NOT capture the name object: a name
- * can be redefined or deleted while a graph answer is still held, and re-resolving means the
- * answer follows the definition rather than a snapshot of it. A name that is gone answers `null`.
- */
 export declare class NamedCellRange extends NamedRange {
     private readonly _info;
     private readonly _namedFormulas;

package/types/src/sheet/SheetCell.d.ts

@@ -223,6 +223,12 @@ export declare class SheetCell implements ICell {
     getWorksheet(): IWorksheet;
     /** {@inheritDoc ICell.select} */
     select(options?: ITypes.SelectOptions): Promise<boolean>;
+    /**
+     * Follows an address as this cell's sheet follows a link: what a link beside the cells (a picture's)
+     * opens with.
+     * @internal
+     */
+    _openAddress(address: string, options: ITypes.SelectOptions | null, target?: string, features?: string): Promise<boolean>;
     /** {@inheritDoc ICell.getColumn} */
     getColumn(): ITable.IColumn | null;
     /** {@inheritDoc ICell.getTable} */
@@ -371,8 +377,8 @@ export declare class SheetCell implements ICell {
     /** {@inheritDoc ICell.getSpillKind} */
     getSpillKind(): ITypes.FormulaArrayKind | null;
     /**
-     * The spill entry this cell answers for: the first live one, else a blocked one so the UI can
-     * still show the range it would have taken.
+     * The spill entry this cell answers for: a live one, else a blocked one, so the UI can show the
+     * range it would have taken. Where blocked ones overlap, the one anchored here, else the first.
      */
     protected _getSpillEntry(): SpillEntry | null;
     /** {@inheritDoc ICell.isSpillOverflow} */