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

package/types/src/chart/resolve/_Resolve.d.ts

@@ -15,12 +15,6 @@ export interface ChartTheme {
 }
 /** The theme of a workbook's styles. */
 export declare function chartThemeOf(styles: IStyleCollection): ChartTheme;
-/**
- * What the cells a chart plots hold now, asked for each reference of the model (DESIGN-CHART
- * §3.3). Each read answers `null` where the cells cannot be read - the reference is not one plain
- * range of this workbook, its cells are deleted, or the chart is outside a workbook - and the
- * reference's cache answers then.
- */
 export interface ChartDataReader {
     /** The numbers the reference names, by point; `null` is a blank. */
     values(reference: ChartModel.DataReference): (number | null)[] | null;
@@ -38,13 +32,10 @@ export interface ChartDataReader {
 }
 /** Formats `value` in `formatCode` the way cells are formatted. */
 export declare const formatValue: (formatCode: string, value: number, date1904: boolean) => string;
-/**
- * Where a type puts its data labels when they state no position (measured 2026-10-17,
- * `probe-chart-labels.ps1` D01-D15; Excel states no `dLblPos` for these): outside the end of a
- * clustered bar, the center of a stacked bar, an area or a doughnut's slice, right of a line's or a
- * scatter's point, best fit on a pie. A bubble's and a radar's are believed.
- */
 export declare const defaultLabelPosition: (group: Pick<ChartModel.Group, "type" | "grouping">) => ResolvedChart.LabelPosition;
+export declare const labelPositionsOf: (group: Pick<ChartModel.Group, "type" | "grouping" | "is3D">) => readonly ResolvedChart.LabelPosition[] | null;
+/** Where a group's labels sit: the stated position where the type offers it, else the type's default. */
+export declare const labelPositionOf: (group: Pick<ChartModel.Group, "type" | "grouping" | "is3D">, stated: ResolvedChart.LabelPosition | undefined) => ResolvedChart.LabelPosition;
 /** A series' automatic color, `#RRGGBB`: what it is drawn in where it states no color (the legacy style's, S3). */
 export declare function automaticSeriesColor(model: ChartModel.ChartSpace, theme: ChartTheme, idx: number): string;
 export declare function resolveChart(model: ChartModel.ChartSpace, theme: ChartTheme, data?: ChartDataReader | null): ResolvedChart;

package/types/src/chart/resolve/_ResolvedChart.d.ts

@@ -20,9 +20,12 @@ export interface ResolvedChart {
     chartEx?: boolean;
     /** The chart's own text font: what text with no font of its own is drawn in. */
     font: ResolvedChart.Font;
-    /** `cornerRadius` in points: 0 for square corners. */
+    /**
+     * `fill` is `undefined` where the chart states none: it is drawn in the background of where it is
+     * drawn. `cornerRadius` in points: 0 for square corners.
+     */
     chartArea: {
-        fill: IFill.JSON | null;
+        fill: IFill.JSON | null | undefined;
         border: ResolvedChart.Stroke | null;
         cornerRadius: number;
     };
@@ -183,7 +186,6 @@ export declare namespace ResolvedChart {
         /** Box and whisker groups: what of each box is drawn, and the line it is drawn with. */
         box?: BoxOptions;
     }
-    /** How a box and whisker series draws its boxes (DESIGN-CHART §4.17). */
     interface BoxOptions {
         quartileMethod: QuartileMethod;
         /** An x at each box's mean. */
@@ -310,11 +312,6 @@ export declare namespace ResolvedChart {
             bannerFill: IFill.JSON | null;
         };
     }
-    /**
-     * How a histogram's values were counted (DESIGN-CHART §4.16): each series' `values` are its
-     * counts by bin and its `categories` the bins' labels; a pareto's are its sums by category,
-     * largest first, with a line of the running share on an axis of its own.
-     */
     interface Histogram {
         /** The first series' bins, each with the indexes of its `raw` values. */
         bins: HistogramBin[];

package/types/src/collections/ISparseGrid.d.ts

@@ -43,8 +43,8 @@ export declare namespace ISparseGrid {
      */
     type RunIteratorResult<T = any> = IteratorResult<ISparseGrid.RunEntry<T>>;
     /**
-     * Run Iterator extends {@link IReadableList.IteratorOptions} but removes support for
-     * processSkip and downcasts reuseResult.
+     * Options for {@link ISparseGrid.getRuns}. Runs always follow the grid's own axis, in order;
+     * there is no reverse or skip.
      */
     interface RunIteratorOptions {
         /**
@@ -65,6 +65,15 @@ export declare namespace ISparseGrid {
          * This is used as a performance optimization for iterators that are reading gaps. (fillEmpty)
          */
         overflowRun?: boolean;
+        /**
+         * Returns the same iterator result from every `next`, with its entry rewritten.
+         *
+         * `true` reuses one result per iterator; an object reuses that object. This avoids an
+         * allocation per run, but a result must be read before the next call to `next`.
+         *
+         * @defaultValue false
+         */
+        reuseResult?: boolean | ISparseGrid.RunIteratorResult<any>;
     }
 }
 //# sourceMappingURL=ISparseGrid.d.ts.map

package/types/src/collections/MixedTypedArrayList.d.ts

@@ -2,8 +2,8 @@ import { IList, IListLike } from './IList';
 /**
  * An immutable run of mixed scalar values in ONE `ArrayBuffer` or `SharedArrayBuffer`.
  *
- * Numbers, booleans and blanks are stored natively; strings and errors as `int32` ids that a
- * {@link MixedTypedArrayList.Codec} resolves. The buffer is the whole list: another thread that
+ * Numbers, booleans and blanks are stored natively; strings, errors and rich values as `int32`
+ * ids that a {@link MixedTypedArrayList.Codec} resolves. The buffer is the whole list: another thread that
  * receives its {@link MixedTypedArrayList.Handle} (and has the same codec) reads it without a copy.
  *
  * @remarks
@@ -150,6 +150,12 @@ export declare namespace MixedTypedArrayList {
         encodeError(value: T): number;
         /** The error for a code. */
         decodeError(code: number): T;
+        /** Whether `value` is a rich value {@link encodeRich} stores. Omitted, none is. */
+        isRich?(value: object): boolean;
+        /** The id of a rich value. */
+        encodeRich?(value: T): number;
+        /** The rich value an id names. */
+        decodeRich?(id: number): T;
     }
     /**
      * What rebuilds a list over its buffer. Passes through `structuredClone` and `postMessage`.

package/types/src/collections/SparseGrid.d.ts

@@ -1,4 +1,4 @@
-import { CellCoords, Direction, RangeAxis, RangeCoords } from '@sheetxl/utils';
+import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
 import { Tuple } from './Tuple';
 import { IReadableList } from './IReadableList';
 import { IGrid } from './IGrid';
@@ -20,13 +20,7 @@ export declare class SparseGrid<T = any> implements ISparseGrid<T> {
     private _isShared;
     private _createRun;
     constructor(options?: SparseGrid.ConstructorOptions);
-    /**
-     * Returns an IterableIterator over all the runs in the sparse grid.
-     * Each run is a contiguous list of values in the grid.
-     *
-     * @returns An iterator that yields [majorIndex, minorIndex, IReadableList] entries
-     */
-    /** {@inheritDoc ISparseGrid.getMaxCoords} */
+    /** {@inheritDoc ISparseGrid.getRuns} */
     getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator<T>;
     /** {@inheritDoc IGrid.getAxis} */
     getAxis(): RangeAxis;
@@ -36,6 +30,7 @@ export declare class SparseGrid<T = any> implements ISparseGrid<T> {
     values(options?: IGrid.IteratorOptions): IGrid.ValueIterator;
     /** {@inheritDoc IGrid.keys} */
     keys(options?: IGrid.IteratorOptions): IGrid.KeyIterator;
+    private _entriesPrivateResult;
     private _updateMajorSpan;
     /** {@inheritDoc IGrid.setValues} */
     setValues(values: Tuple.GridTuple<T>): this;

package/types/src/collections/_GridUtils.d.ts

@@ -267,15 +267,5 @@ export declare function translateTupleBounds<T = any>(boundedTuples: Tuple.Regio
  * * Allows for reusable ranges.
  */
 export declare function createConflatingRangeValue<T = any>(isColumn?: boolean, canMerge?: (a: T, b: T, isColumn: boolean) => T | undefined, combine?: (previous: T, next: T) => T): ISpatialMap.IConflatingEntries<T>;
-/**
- * A grid's runs as grid tuples, in the grid's own axis: one major tuple per major that holds a
- * run, the runs shared by reference.
- *
- * @remarks
- * This is the seam the values half of a seed crosses (DESIGN-CALC-SERVICE §6.6): what a grid
- * holds becomes the tuples another grid is loaded from. Runs are immutable lists, so sharing them
- * is what the load already does when it hands one set of tuples to the sheet and its grid.
- * @internal
- */
 export declare function gridToTuples<T = Scalar>(grid: ISparseGrid<T>): Tuple.GridTuple<T>;
 //# sourceMappingURL=_GridUtils.d.ts.map

package/types/src/comment/_NoteBox.d.ts

@@ -3,21 +3,6 @@ import { Bounds } from '@sheetxl/utils';
 import { IMovable } from '../movable';
 import { IWorksheet } from '../sheet';
 import { Movable } from '../movable/Movable';
-/**
- * Where a note's box goes when nothing has moved it, and how a note stores where its box is.
- *
- * @remarks
- * The default is Excel's, probed with hidden COM on a 96-DPI machine (2026-09-30): a 144×79 px
- * box hung 15 px right of its cell and 10 px above its top, flipped to the other side when it
- * would pass the sheet's last column or row. A note on a merged cell hangs beside the merge
- * (probed 2026-10-20). It is pixel geometry first and the cells those
- * pixels fall on second, so tall, narrow and hidden rows and columns need no rule of their own.
- *
- * A note stores its box's anchor with the cells counted from the note's own, so a note copied
- * to another cell keeps its box beside it. The box itself is an ordinary movable anchored to the
- * sheet's cells; these functions convert between the two.
- * @internal
- */
 /** The width of a default box, in pixels. */
 export declare const NOTE_DEFAULT_WIDTH = 144;
 /** The height of a default box, in pixels. */

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

@@ -16,7 +16,7 @@ import * as _ConditionUtils from '../condition/_ConditionUtils';
  * Implementation of {@link IDataValidation}.
  */
 export declare abstract class AnchoredConditional<STATE extends AnchoredConditional.State, EVENTS extends ICondition.Events = ICondition.Events, JSON = any> extends AbstractAnchored<STATE, EVENTS> implements IAnchored, ITransaction.ITransactional, IListener.ISource<IAnchored> {
-    protected _rangeListener: ICellRange.Listener | null;
+    protected _rangeListener: ICellRange.Listener<ICellRanges> | null;
     protected _getValueGrid: () => ISparseGrid<Scalar>;
     /**
      * One registered watch per formula the condition asked for, keyed by the formula: its remove, and
@@ -86,7 +86,7 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
      * cluster: one calc pass notifies each rule it intersects, and a burst of deliveries would
      * otherwise start a burst of evaluations for the newest one to win. Coalescing on a microtask
      * rather than a commit hook is deliberate: the calc-results path notifies AFTER its transaction
-     * commits (`trigger: 'calc'`), so a commit hook never sees the most frequent trigger.
+     * commits (a `'data'` event with no commit), so a commit hook never sees the most frequent trigger.
      *
      * Two same-tick marks widen to the whole rule rather than accumulating a range list — the
      * subclasses evaluate per whole range anyway, and a rule's ranges are small.
@@ -222,29 +222,7 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
      * @internal
      */
     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 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 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.
-     *
-     * 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;
+    _extendPastedRanges(ranges: readonly IRange.Coords[], jsonAtMark: string, isCut?: boolean): 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

package/types/src/condition/BuiltInOperators/AbstractOperator.d.ts

@@ -40,58 +40,9 @@ export declare abstract class AbstractOperator<P> implements ICondition.IOperato
     getDescription(): string | null;
     /** {@inheritDoc ICondition.doBatch} */
     doBatch(keys: Set<any>, param: P, ctx: ICondition.IContext): MaybePromise<IRange<boolean> | null>;
-    /**
-     * Resolves a comparison operand that may be formula-valued — an {@link ICalculation.IFormula}, or
-     * a string param with a leading `=` — into a per-cell {@link OperandReader}.
-     *
-     * @returns The reader, or `null` when the operand is a formula with nothing to read (no engine,
-     * an empty expression) — the caller returns a `null` predicate and the condition is inert
-     * rather than throwing.
-     *
-     * @remarks
-     * A literal operand costs nothing: the reader is a constant. A formula operand is declared
-     * through {@link ICondition.IContext.watchFormula}, so a long-lived owner keeps it fresh and a
-     * one-shot evaluation answers it on the spot. Values arrive as a block anchored at
-     * `ctx.getCoords()`: an absolute operand broadcasts and a relative one varies per cell on the
-     * same code path.
-     *
-     * A per-cell value that is an ERROR is returned as the error — comparisons must treat it as
-     * no-match, never a throw — and warns once per predicate build. A reference operand reads its
-     * top-left: Excel does NOT implicitly intersect here (`$E$5:$F$6>10` tested `E5` for every cell;
-     * measured 2026-08-21), which is the watch's `arrayFirstCell` evaluation.
-     */
     protected _resolveOperand(param: Scalar | ICalculation.IFormula | undefined, ctx: ICondition.IContext): Promise<OperandReader | null>;
-    /**
-     * Whether a comparison operand has not been given: absent, or blank text.
-     *
-     * @remarks
-     * A comparison missing an operand is inert, never a comparison against 0. Excel reads a rule
-     * whose `<formula>` is absent or empty that way — a validation flags nothing, a format paints
-     * nothing (measured, `probe-dv-operands` and `probe-cf-operands`) — and its dialogs refuse to
-     * author one.
-     */
     protected _isMissingOperand(param: Scalar | ICalculation.IFormula | undefined): boolean;
-    /**
-     * The first problem with a comparison operand under `lhsSelector`, as a message key, or `null`.
-     *
-     * @param allowEmptyText Whether `''` is an operand (equal to empty text) rather than one not given.
-     *
-     * @remarks
-     * The rules Excel's dialogs refuse on (measured, `probe-dv-operands`): an operand is required; a
-     * whole-number rule takes an integer, a text-length rule a non-negative integer, a date a serial
-     * from 0, a time a serial in [0, 1); text where a number belongs is refused; a formula must parse.
-     * With no selector (a format's Cell Value rule) any scalar is an operand — Excel accepts text there.
-     */
     protected _validateOperand(param: Scalar | ICalculation.IFormula | undefined, lhsSelector: ICondition.ISelector | null | undefined, allowEmptyText?: boolean): string | null;
-    /**
-     * The shared predicate shape of the ordered comparisons (`greaterThan` … `before`): resolve the
-     * operand (formula or literal — see {@link _resolveOperand}), then compare per cell. An ERROR
-     * operand never matches; a `null` return means the operand is missing
-     * ({@link _isMissingOperand}) or could not resolve, and the condition is inert.
-     *
-     * An empty cell arrives as `null` and compares as 0, which is how Excel judges one (measured,
-     * `probe-dv-blank`).
-     */
     protected _createComparePredicate(param: Scalar | ICalculation.IFormula | undefined, ctx: ICondition.IContext, compare: (value: number, operand: number) => boolean): Promise<ICondition.Predicate | null>;
     /**
      * An operand as a rule's text reads it: a date or time serial as the date or time it is,

package/types/src/condition/BuiltinSelectors/DisplaySelector.d.ts

@@ -2,16 +2,6 @@ import { Scalar } from '@sheetxl/primitives';
 import { MaybePromise } from '@sheetxl/utils';
 import { ICondition } from '../ICondition';
 import { BaseSelector } from './BaseSelector';
-/**
- * DisplaySelector:
- *
- * The text a cell shows. Every cell is in its domain; the reading is the displayed text under a
- * filter (`$1` for a cell holding 1 under `$0`), and the value's own text under a format or a
- * validation, where nothing is shown at evaluation. Excel's filter `equal` and its values list
- * compare this way (DESIGN-FILTER §3.2, P10), which is where the xlsx reader sets it. The text
- * family (contains, starts with) stays under no selector: Excel's reads the raw text of a text
- * cell and never a number's display.
- */
 export declare class DisplaySelector extends BaseSelector<string, Scalar> {
     constructor();
     /** {@inheritDoc ICondition.ISelector.createTransformer} */

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

@@ -172,8 +172,8 @@ export declare namespace ICondition {
         /**
          * The text a cell SHOWS: under a filter the displayed text, so `$1` is a cell holding 1 under
          * `$0`; under a format or a validation, where nothing is shown at evaluation, the value's own
-         * text. Type text. Excel's filter `equal` and its values list compare this way
-         * (DESIGN-FILTER §3.2, MODEL-CONDITIONS §4); `equalTo` under no selector is value equality.
+         * text. Type text. Excel's filter `equal` and its values list compare this way;
+         * `equalTo` under no selector is value equality.
          */
         readonly Display: "display";
         readonly Number: "number";

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

@@ -152,30 +152,13 @@ export declare class UnresolvedCondition<P = any> implements ICondition<P> {
  * of an exception that costs the caller the entire rule.
  */
 export declare function fromJSON<P = any>(json: ICondition.JSON<P> | null | undefined): ICondition<P> | null;
-/**
- * A combinator's reading of a value through a child's selector, as the driver reads one for the
- * root: the transformer gates and projects a value, and a blank (`null`, which reaches a
- * predicate only with Ignore Blank off) is read by no selector. It passes on as it is, for the
- * operator to judge as Excel judges an empty cell (0 under a number rule, "" under a text one;
- * P7, DESIGN-DV §5). Display in particular must not turn it into the empty text it shows.
- */
 export declare function readThroughSelector(transformer: ICondition.Transformer<any, any> | null | undefined, value: Scalar, ctx: ICondition.IContext): Scalar | typeof ICondition.NotApplicable;
 /**
  * The condition's answer for the BLANK cells of a range, asked per cell — lazily, by the caller,
  * for the cells it actually reads. Blank cells are never visited by the engine.
  */
 export type BlankResolver = (rowIndex: number, colIndex: number) => boolean;
-/**
- * Whether a value is blank by Excel's AutoFilter rule (`LEN(TRIM(x))=0`, DESIGN-FILTER.md §3.3):
- * nothing, an empty string, or a string of only U+0020 spaces. A tab, a non-breaking space, `0`
- * and an error are values.
- */
 export declare function isBlankValue(value: Scalar): boolean;
-/**
- * The calc engine's blank: an empty cell, or the `""` a formula returns (`=A1=""` is TRUE for
- * both). A string of spaces is a string. The filter's rule for a value-shaped level
- * (DESIGN-FILTER §3.3); {@link isBlankValue} is the display rule.
- */
 export declare function isBlankByValue(value: Scalar): boolean;
 /** Whether a selector, by name or instance, is {@link ICondition.BuiltInSelectorNames.Display}. */
 export declare function isDisplaySelector(selector: unknown): boolean;
@@ -275,18 +258,6 @@ export interface DoRunRangeConditionsOptions extends ICondition.RangeOptions {
  * Shared by `ICellRange.filter` and `ITable.filter`, so a bare input means the same to both.
  */
 export declare function normalizeFilterInput(condition: ICondition.Input | ICondition.RangeOptions | null | undefined): ICondition.RangeOptions;
-/**
- * Evaluates `conditions[]` in array order against the row (or column) axis, ANDing each condition
- * into a running visibility mask — Excel's own AutoFilter model (DESIGN-FILTER.md §2): a dynamic
- * condition (Average, Top N) only ever sees the rows/columns still visible under the mask
- * accumulated by the conditions *before* it. Each condition carries its column (or row) via
- * `IndexedProperties.index`, defaulting to its position in `conditions[]` when omitted — mirrors
- * `ISort.Options.index ?? level`.
- *
- * @remarks
- * Backs `ICellRange.filter` / `ITable.filter` (`_SheetFilterUtils.doFilter`). Data Validation and
- * Conditional Formatting keep using the single-condition {@link evalConditions}.
- */
 export declare function evalRangeConditions(options: DoRunRangeConditionsOptions): Promise<void>;
 export interface DoRunConditionsOptions extends ICondition.RangeOptions {
     runtime: IRuntime;
@@ -330,15 +301,6 @@ export interface DoRunConditionsOptions extends ICondition.RangeOptions {
      * FALSE in others, and the formula's own block evaluation already holds each one.
      */
     onBlank?: (resolve: BlankResolver) => void;
-    /**
-     * Whether a stored value that is blank by Excel's AutoFilter rule ({@link isBlankValue}: a
-     * `""` result, a string of only spaces) is answered as the blank cell it shows as, never shown
-     * to the selector or the operator. Conditional Formatting sets it (`containsBlanks` is
-     * `LEN(TRIM(x))=0`); Data Validation does not, since there a blank is an empty cell and a
-     * `""` result is judged (DESIGN-DV §5). The filter driver decides per level: a display-shaped
-     * one ({@link isDisplayShaped}) takes this rule, any other the calc engine's, where only `""`
-     * is blank (DESIGN-FILTER §3.3).
-     */
     spacesAreBlank?: boolean;
 }
 //# sourceMappingURL=_ConditionUtils.d.ts.map

package/types/src/externalBook/ExternalBookCollection.d.ts

@@ -111,24 +111,9 @@ export declare class ExternalBookCollection extends AbstractCollection<IExternal
     _refresh(bookId: string): Promise<IExternalBook.RefreshResult>;
     /** Excel's record of a refresh that could not complete: `refreshError` on each cached sheet. */
     protected _markRefreshError(bookId: string): void;
-    /**
-     * The value pass in front of a removal: every cell block that cites the book becomes its current
-     * values — the WHOLE formula, as Excel does, not only the external operand.
-     *
-     * @remarks
-     * A dependent that is a NAME (its scope is the name's virtual grid, not a sheet) is left as it
-     * is. Its citation then images as `#REF!` once the slot goes, which is one of the three outcomes
-     * DESIGN-EXTERNAL-LINKS §6 item 8 lists for Excel; the measurement that picks between them has
-     * not been taken, and a name has no computed value to write back until phase D in any case.
-     */
     protected _breakDependents(book: IExternalBook): void;
     /** @internal Backs {@link IExternalBook.getDependents}; empty without an engine to ask. */
     _getDependents(bookId: string): readonly IRange.Coords[];
-    /**
-     * @internal
-     * Records a sheet name a formula cited on a book that did not list it — the authoring half of
-     * the bind rule (DESIGN-EXTERNAL-LINKS §5 step 13). Returns the sheet's index in the book.
-     */
     _addSheetName(bookId: string, sheetName: string): number;
     toJSON(): (IExternalBook.JSON | null)[] | null;
     /** {@inheritDoc IListener.ISource.addListeners} */

package/types/src/externalBook/ExternalBookName.d.ts

@@ -48,7 +48,7 @@ export declare function externalBookFileName(book: IExternalBook): string;
  *
  * @remarks
  * This is the form Excel's own formula bar shows for a book it cannot see, which is the state every
- * book is in until a resolver opens one (DESIGN-EXTERNAL-LINKS §4B). The caller quotes it —
+ * book is in until a resolver opens one. The caller quotes it —
  * `sheetNameToString` does, since a path carries separators no sheet name may.
  *
  * The directory is the first source that carries one: a book Excel recorded by a RELATIVE path
@@ -70,8 +70,7 @@ export declare const EXTERNAL_LINK_PATH_REL_TYPE = "http://schemas.openxmlformat
  *
  * @remarks
  * A Windows path becomes a `file:///` URI with forward slashes and percent-encoding, a UNC path a
- * `file://server/share/…` one, and a URL or a bare relative name is kept verbatim — the three
- * target shapes measured in the corpus (DESIGN-EXTERNAL-LINKS §2.2).
+ * `file://server/share/…` one, and a URL or a bare relative name is kept verbatim.
  */
 export declare function sourceEntryFromPath(path: string): IExternalBook.SourceEntry;
 /**

package/types/src/externalBook/IExternalBook.d.ts

@@ -1,14 +1,12 @@
-import { IRange } from '@sheetxl/primitives';
+import { IRange, Scalar } from '@sheetxl/primitives';
 import { Tuple } from '../collections';
-import { ICell } from '../cell';
 import { ITransaction } from '../transaction';
 /**
  * A cached snapshot of another workbook, referenced from a formula as `[n]Sheet1!$A$1`.
  *
  * @remarks
  * Excel's external link is not a live reference — it is the cache plus enough to go re-fetch the
- * source. See the design doc for the full model:
- * `private-assets/design/calc/DESIGN-EXTERNAL-LINKS.md`.
+ * source.
  *
  * Two members read as "which book is this", and they answer different questions:
  *
@@ -68,8 +66,8 @@ export interface IExternalBook {
      *
      * @remarks
      * **Sparse.** A cell the cache does not hold — and a sheet it holds nothing for — reads as a
-     * BLANK cell, which is what Excel computes with the source closed (design doc §6 items 1/2).
-     * Values only — no format, no style, no comment; a cached date is a plain serial (§2.5).
+     * BLANK cell, which is what Excel computes with the source closed. Values only — no format, no
+     * style, no comment; a cached date is a plain serial.
      *
      * @param sheetIndex Position in {@link getSheetNames}, matching the XML's `sheetId` (0-based).
      */
@@ -91,8 +89,8 @@ export interface IExternalBook {
      * (`[Budget.xlsx]Sheet1`) once a resolver holds it.
      *
      * @remarks
-     * A readout of the book's state, not a preference — see DESIGN-EXTERNAL-LINKS §4B. Until phase E
-     * there is no resolver, so this is always the closed form. The caller quotes it.
+     * A readout of the book's state, not a preference: without a resolver this is always the closed
+     * form. The caller quotes it.
      *
      * @param sheetName Omitted for the book-scoped `[1]!Name` form.
      */
@@ -137,8 +135,8 @@ export interface IExternalBook {
      * @remarks
      * Needs a resolver (`ICellContainerOptions.externalBookResolver`, given when the workbook is
      * built); without one every book is `'unavailable'` and nothing changes, which is the state a
-     * workbook is in until a host supplies one (DESIGN-EXTERNAL-LINKS §4D). A replaced cache is one undoable step, and every formula
-     * citing the book reads the new values. A resolver that throws leaves the cache as it was and
+     * workbook is in until a host supplies one. A replaced cache is one undoable step, and every
+     * formula citing the book reads the new values. A resolver that throws leaves the cache as it was and
      * marks each cached sheet `refreshError`, as Excel records a refresh it could not complete.
      */
     refresh(): Promise<IExternalBook.RefreshResult>;
@@ -167,8 +165,8 @@ export declare namespace IExternalBook {
          * the book is opened from, `absoluteUrl` its 2021 cloud-URL companion.
          *
          * @remarks
-         * Not derivable from {@link type} — the two can carry the SAME relationship type (measured on
-         * task 40234, where a relative and an absolute `externalLinkPath` sit on one part). Absent for
+         * Not derivable from {@link type} — the two can carry the SAME relationship type (a relative
+         * and an absolute `externalLinkPath` can sit on one part). Absent for
          * an entry nothing points at, which is a real shape too: an `xlPathMissing` or
          * `externalLinkLongPath` rel rides along on the part without being referenced from it.
          */
@@ -207,10 +205,10 @@ export declare namespace IExternalBook {
      * Opens a book's source and answers its current contents, or declines.
      *
      * @remarks
-     * DESIGN-EXTERNAL-LINKS §4D: the default one (phase E) is `WorkbookIO.read` with
+     * A resolver for a workbook file should read it with `WorkbookIO.read` and
      * `calcOnLoad: 'none'`, taking the source's own cached values and never evaluating it — that is
-     * what Excel's cache holds, and it keeps A-cites-B-cites-C from becoming a crawl. An extension
-     * point for a source that is not a workbook file. WHETHER a source may be opened at all — an
+     * what Excel's cache holds, and it keeps A-cites-B-cites-C from becoming a crawl. A source that
+     * is not a workbook file can be resolved too. WHETHER a source may be opened at all — an
      * untrusted file naming an arbitrary path or URL — is the host's decision, made before this is
      * asked; a resolver never fetches on its own initiative, only on {@link IExternalBook.refresh}.
      */
@@ -226,11 +224,11 @@ export declare namespace IExternalBook {
         /** `<sheetData refreshError="1">` — Excel could not refresh this sheet's cache last time it tried. */
         refreshError?: boolean;
         /**
-         * Sparse cell values — the same encoding `IWorksheet.JSON.data` uses (`ICell.JSON` is already just
+         * Sparse cell values — the same encoding `IWorksheet.JSON.data` uses (`Scalar.JSON` is already just
          * the value+type pair; style/formula live in sibling fields there, none of which apply to a
-         * values-only cache — design doc §2.5).
+         * values-only cache).
          */
-        data: Tuple.GridTuple<ICell.JSON>;
+        data: Tuple.GridTuple<Scalar.JSON>;
     }
     interface JSON {
         /**

package/types/src/fetch/Fetcher.d.ts

@@ -0,0 +1,15 @@
+import { IFetcher } from './IFetcher';
+/**
+ * The default {@link IFetcher}: `http:` and `https:` through the global `fetch`, and whatever
+ * else is registered.
+ */
+export declare class Fetcher implements IFetcher {
+    private readonly _handlers;
+    /** {@inheritDoc IFetcher.fetch} */
+    fetch(input: string, init?: RequestInit): Promise<Response>;
+    /** {@inheritDoc IFetcher.register} */
+    register(scheme: string, handler: IFetcher.Handler): () => void;
+    /** {@inheritDoc IFetcher.isIFetcher} */
+    get isIFetcher(): true;
+}
+//# sourceMappingURL=Fetcher.d.ts.map

package/types/src/fetch/IFetcher.d.ts

@@ -0,0 +1,48 @@
+/**
+ * How a workbook reaches what lives outside it: the picture an `IMAGE` names, a web service's
+ * answer. A handler per URL scheme; a host registers its own to add authentication, or to serve a
+ * scheme of its own.
+ *
+ * @remarks
+ * Each workbook has one, given as `IWorkbook.ConstructorOptions.fetcher`, or a default that
+ * answers `http:` and `https:` with the global `fetch`.
+ *
+ * @example
+ * ```typescript
+ * const fetcher = new Fetcher();
+ * fetcher.register('https', (url, init) => fetch(url, {
+ *   ...init,
+ *   headers: { ...init?.headers, Authorization: `Bearer ${token}` }
+ * }));
+ * const workbook = new Workbook({ fetcher });
+ * ```
+ */
+export interface IFetcher {
+    /**
+     * Fetches `input` with the handler registered for its scheme. A URL without a scheme goes to
+     * the `https` handler.
+     *
+     * @returns The response; rejects with a `TypeError` when no handler serves the scheme, as
+     * `fetch` does for a URL it cannot reach. In a browser the default handlers reject with a
+     * `FormulaError.Blocked` when the site responded but does not allow web pages to read it.
+     */
+    fetch(input: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Serves a URL scheme with `handler`, replacing the handler it had.
+     *
+     * @param scheme The scheme, with or without its colon: `'https'`, `'resource:'`.
+     * @returns A function that removes the registration.
+     */
+    register(scheme: string, handler: IFetcher.Handler): () => void;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIFetcher: true;
+}
+export declare namespace IFetcher {
+    /**
+     * Answers a fetch for one scheme, with the signature of the standard `fetch`.
+     */
+    type Handler = (url: string, init?: RequestInit) => Promise<Response>;
+}
+//# sourceMappingURL=IFetcher.d.ts.map

package/types/src/fetch/_WorkbookFetch.d.ts

@@ -0,0 +1,43 @@
+import { IResource } from '../resource/IResource';
+import { IResourceCollection } from '../resource/IResourceCollection';
+import { IFetcher } from './IFetcher';
+/**
+ * A workbook's fetch: its {@link IFetcher}, in front of the workbook's resources. A resource that
+ * says where it was fetched from is the workbook's copy of that URL, and a fetch of the URL answers
+ * from it without a request. Any other successful answer that is not a picture is cached while the
+ * workbook is open and never saved. Plain GETs of one URL in flight together share one request. A
+ * response whose bytes are a picture says what they are, whatever the server called them.
+ *
+ * It saves nothing itself: what holds a picture adds it as a resource (`IMAGE` through
+ * `IDeferContext.addResource`), and the workbook saves a resource while a value holds it.
+ *
+ * @internal
+ */
+export declare class WorkbookFetch {
+    private readonly _resources;
+    private readonly _fetcher;
+    private readonly _kept;
+    /** Answers that are not pictures, by URL: a cache for the session, not saved. */
+    private readonly _cached;
+    private readonly _inFlight;
+    constructor(resources: IResourceCollection, fetcher: IFetcher);
+    /** The fetcher behind this: what the host registered. */
+    getFetcher(): IFetcher;
+    /** {@inheritDoc IWorkbook.fetch} */
+    fetch(input: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Keeps every resource that says where it was fetched from as that URL's picture: what a file
+     * carried. Called once the workbook's resources are loaded.
+     */
+    adopt(resources: readonly IResource[]): void;
+    /**
+     * Keeps `resource` as the bytes of `uri`. A fetch of `uri` answers from it without asking the
+     * fetcher.
+     */
+    keep(uri: string, resource: IResource): void;
+    /** A resource added under `uri` since the last load, kept now that it is asked for. */
+    private _findHeld;
+    private _fromKept;
+    private _request;
+}
+//# sourceMappingURL=_WorkbookFetch.d.ts.map

package/types/src/fetch/index.d.ts

@@ -0,0 +1,3 @@
+export * from './IFetcher';
+export * from './Fetcher';
+//# sourceMappingURL=index.d.ts.map