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

package/types/src/picture/IPicture.d.ts

@@ -60,6 +60,51 @@ export interface IPicture extends IModel, IMovable.IContent {
      * ```
      */
     setShapeType(shapeType: IGeometry.Preset | string, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the shape's outline at a size, for drawing the picture cropped to its shape.
+     *
+     * @param width The frame's width in pixels. Defaults to the movable's.
+     * @param height The frame's height in pixels. Defaults to the movable's.
+     * @returns `null` for a preset this SDK does not know, or for a picture with no movable and no size.
+     */
+    getGeometry(width?: number, height?: number): Promise<IGeometry | null>;
+    /**
+     * Returns the part of the image shown, as percentages of the image's size inset from each edge.
+     *
+     * @remarks
+     * An edge not cropped is absent, so an uncropped picture answers `{}`. A negative inset shows empty
+     * space beyond that edge of the image, which is how a picture fits inside a frame of another shape.
+     */
+    getCrop(): IFill.RectInsets;
+    /**
+     * Sets the part of the image shown. The frame stays as it is, so the part shown is stretched over
+     * it; to keep the image's scale, change the frame with {@link IMovable.setBounds} as well.
+     *
+     * @param crop Percentages of the image's size, inset from each edge; `null` shows the whole image.
+     * @throws ExpectedError when the insets leave nothing to show.
+     *
+     * @example
+     * ```ts
+     * picture.setCrop({ left: 10, right: 10 });
+     * ```
+     */
+    setCrop(crop: IFill.RectInsets | null, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the hyperlink a click on the picture follows, or `null` for none.
+     */
+    getHyperlink(): IHyperlink | null;
+    /**
+     * Sets the hyperlink a click on the picture follows.
+     *
+     * @param hyperlink An address, the link's properties, or `null` to remove it. An address takes the
+     * form a cell's does: a url, or `#Sheet1!A1` for a location in this workbook.
+     *
+     * @example
+     * ```ts
+     * picture.setHyperlink('https://www.sheetxl.com');
+     * ```
+     */
+    setHyperlink(hyperlink: IHyperlink.Update, options?: ITransaction.OperationOptions): this;
     /**
      * What the picture's frame draws with: the fill behind the image and the border around it.
      * A picture has no theme style, so each is only what the picture states; by default neither

package/types/src/picture/Picture.d.ts

@@ -1,6 +1,8 @@
 import { ITransaction } from '../transaction';
 import { IResource, IResourceCollection } from '../resource';
 import { IAnchored } from '../anchored';
+import { IFill } from '../fill';
+import { IHyperlink } from '../hyperlink';
 import { IMovable } from '../movable/IMovable';
 import { AbstractMovableContent } from '../movable/AbstractMovableContent';
 import { IGeometry, IShapeStyle } from '../shape';
@@ -32,6 +34,16 @@ export declare class Picture extends AbstractMovableContent<State, IPicture.JSON
     getShapeType(): string;
     /** {@inheritDoc IPicture.setShapeType} */
     setShapeType(shapeType: IGeometry.Preset | string, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPicture.getGeometry} */
+    getGeometry(width?: number, height?: number): Promise<IGeometry | null>;
+    /** {@inheritDoc IPicture.getCrop} */
+    getCrop(): IFill.RectInsets;
+    /** {@inheritDoc IPicture.setCrop} */
+    setCrop(crop: IFill.RectInsets | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPicture.getHyperlink} */
+    getHyperlink(): IHyperlink | null;
+    /** {@inheritDoc IPicture.setHyperlink} */
+    setHyperlink(hyperlink: IHyperlink.Update, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc IPicture.getStyle} */
     getStyle(): IShapeStyle;
     /** Writes what the picture states of its fill and border: a key `undefined` is removed. */

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

@@ -38,13 +38,6 @@ export declare class PivotTable extends AbstractAnchored<State, IPivotTable.Even
     getCacheId(): number;
     /** {@inheritDoc IPivotTable.toJSON} */
     toJSON(toResourceId?: (resource: IResource) => number | null): IPivotTable.JSON | null;
-    /**
-     * Excel's rule, from `pivot-probes/probe-pivot-structural.ps1` (2026-10-15): the table moves
-     * whole or goes whole. A shift that would split it or change its extent - a row or column cut
-     * through it, an insert inside it, a shift of some of its columns - is refused with Excel's own
-     * refusal, as a user error, before anything of the edit commits.
-     * @internal
-     */
     protected _processContainerShift(options: Anchored.ShiftOptions): IRange.Coords | null | void;
     /** @internal */
     protected _getActionDescription(action: 'delete' | 'initialize' | 'updateListener'): string | null;

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

@@ -0,0 +1,46 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+/**
+ * Whether any holder has been made in this process: what gates the value layer's reads (a range,
+ * the stats walks), which cannot ask a backend. Until the first `defer`, they pay nothing.
+ */
+export declare const holdersMade: () => boolean;
+/**
+ * How many times a call's latest has moved in this process. A settle writes nothing into a grid,
+ * so a cache keyed on a run that holds holders is stamped with this and stands only while it holds.
+ */
+export declare const settleCount: () => number;
+/** Records that a call's latest moved. */
+export declare const noteSettle: () => void;
+export declare class AsyncValue<C extends AsyncValue.Call = AsyncValue.Call> {
+    /**
+     * What the formula calculated, from its calls' initials. A range for an evaluation that
+     * spilled: that holder rides the spill's entry, never a cell, and no cell reads it.
+     */
+    readonly value: Scalar | IRange;
+    /** The calls the formula made, by ordinal. */
+    readonly calls: readonly C[];
+    /** The formula's root is its only call: the cell reads as that call's latest once it has one. */
+    readonly direct: boolean;
+    constructor(value: Scalar | IRange, calls: readonly C[], direct: boolean);
+    /** The brand every recognizing site reads. */
+    get isAsyncValue(): true;
+}
+export declare namespace AsyncValue {
+    /** What a holder reads of a call. */
+    interface Call {
+        /** The most recent result; `undefined` until one arrives. */
+        readonly latest: unknown;
+    }
+}
+/** Whether `value` is an {@link AsyncValue}. */
+export declare const isAsyncValue: (value: unknown) => value is AsyncValue;
+/**
+ * `value` as a reader sees it: a holder reads as its root call's latest when `direct` and the call
+ * has one, else as what the formula calculated. Anything else is itself.
+ *
+ * @remarks
+ * A blank latest reads as `0`, as a formula's blank result is stored (`finalizeValue`): the
+ * latest is the cell's value and was never finalized.
+ */
+export declare const readAsync: <T = Scalar>(value: T) => T | Scalar | IRange;
+//# sourceMappingURL=AsyncValue.d.ts.map

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

@@ -12,6 +12,11 @@ export interface IResource extends JSONSerializableAsync<IResource.JSON> {
      * An optional name for the resource.
      */
     getName(): string | null;
+    /**
+     * The URL the bytes were fetched from, when the resource is a picture the workbook keeps for it
+     * (an `IMAGE` source): a fetch of that URL answers from these bytes. `null` otherwise.
+     */
+    getFetchedFrom(): string | null;
     /**
      * For saving to json resources.
      */
@@ -113,6 +118,10 @@ export declare namespace IResource {
          * This is optional but if provided then resource lookup will use this as a cache key.
          */
         name?: string;
+        /**
+         * The URL the embedded bytes were fetched from: the workbook keeps them as that URL's picture.
+         */
+        fetchedFrom?: string;
     }
 }
 //# sourceMappingURL=IResource.d.ts.map

package/types/src/resource/IResourceCollection.d.ts

@@ -52,6 +52,10 @@ export declare namespace IResourceCollection {
          * This is optional and purely for human consumption and is not used by the system.
          */
         name?: string;
+        /**
+         * The URL the bytes were fetched from, for a picture the workbook keeps for it.
+         */
+        fetchedFrom?: string;
     }
     /**
      * A type that represents the various ways to provide a resource source.

package/types/src/resource/Resource.d.ts

@@ -2,6 +2,7 @@ import { IResource } from './IResource';
 import { IResourceCollection } from './IResourceCollection';
 export declare class Resource implements IResource {
     private _name;
+    private _fetchedFrom;
     private _refs;
     private _listeners;
     private _isClosed;
@@ -17,6 +18,7 @@ export declare class Resource implements IResource {
     protected _resolveArrayBuffer(): Promise<ArrayBuffer>;
     /** {@inheritDoc IResource.getName} */
     getName(): string | null;
+    getFetchedFrom(): string | null;
     /** {@inheritDoc IResource.toJSONAsync} */
     toJSONAsync(): Promise<IResource.JSON>;
     /** {@inheritDoc IResource.toBuffer} */

package/types/src/resource/_AddResource.d.ts

@@ -0,0 +1,13 @@
+import { IResource } from './IResource';
+import { IResourceCollection } from './IResourceCollection';
+/**
+ * Adds bytes to `resources` as a resource. With `fetchedFrom` the resource is the collection's copy
+ * of that URL, so adding the URL again answers the one already there. With no collection, a
+ * resource of no workbook.
+ *
+ * @internal
+ */
+export declare const addResource: (resources: IResourceCollection | null, buffer: ArrayBuffer, options?: {
+    fetchedFrom?: string;
+}) => IResource;
+//# sourceMappingURL=_AddResource.d.ts.map