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

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

@@ -72,14 +72,15 @@ export interface ICellRanges {
      * This is Excel's `Ctrl+Enter` fill: the same scalar is written to all selected cells — across every
      * discontiguous range — as a single {@link ICellRanges.doBatch} operation (one undo step). A formula
      * string (e.g. `"=A1+1"`) is coerced and its relative references adjust per cell, exactly as
-     * {@link ICellRange.setValue} does within one range.
+     * {@link ICellRange.setValue} does within one range. It takes what that does: a `Date`, or a rich
+     * value's JSON (`{ type, data }`), which each cell makes into its own value.
      *
      * Only the scalar-broadcast form exists (no `setValues`): a 2D shape has no coherent meaning spread
      * across discontiguous ranges of differing sizes.
      * @see
      * {@link ICellRange.setValue}
      */
-    setValue(value: ICellRange.ScalarUpdate, options?: ICellRange.SetValuesOptions): this;
+    setValue(value: ICellRange.InteropScalarUpdate, options?: ICellRange.SetValuesOptions): this;
     /**
      * {@inheritDoc ICellRange.merge}
      */
@@ -335,7 +336,7 @@ export interface ICellRanges {
     /**
      * {@inheritDoc ICellRange.addListener}
      */
-    addListener(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
+    addListener(listener: ICellRange.Listener<ICellRanges>, options?: ICellRange.ListenerOptions): IListener.Remove;
     /**
      * {@link ICellRange.addWatch} across every area, as ONE expression authored at a shared origin.
      *

package/types/src/chart/layout/ChartLayout.d.ts

@@ -24,7 +24,11 @@ export interface ChartLayout {
     width: number;
     height: number;
     chartArea: {
-        fill: IFill.JSON | null;
+        /**
+         * `undefined` where the chart states no fill: the chart area is the background of where it is
+         * drawn (Excel draws it in the theme's background color).
+         */
+        fill: IFill.JSON | null | undefined;
         border: IStroke.JSON | null;
         /** The radius of the chart area's corners, measured along the border's path; 0 for square corners. */
         cornerRadius: number;

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

@@ -45,6 +45,16 @@ export declare const formatValue: (formatCode: string, value: number, date1904:
  * 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;
+/**
+ * The label positions Excel offers a classic group's type, `null` for a 2016 or custom type
+ * (measured 2026-10-24 through `DataLabels.Position`): every bar position on a clustered bar, none
+ * outside a stacked one, around the point on a line, stock, scatter or bubble, the end positions and
+ * best fit on a pie; none on an area, a doughnut, a radar, a surface, or a 3-D bar, line or area.
+ * Excel refuses a file that states any other `dLblPos` for the type.
+ */
+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;
     };

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/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.

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

@@ -1,6 +1,5 @@
-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`.
@@ -226,11 +225,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).
          */
-        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,47 @@
+/**
+ * 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.
+     */
+    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
+ * `IBatchContext.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

package/types/src/fill/PaintUtils.d.ts

@@ -8,8 +8,10 @@ export type ColorToCSS = (color: string) => string | null;
 /**
  * A color as concrete CSS: `#RRGGBB`, or `rgba(r,g,b,a)` when it is not opaque. Never a theme
  * reference, a CSS variable or `light-dark()`.
+ *
+ * @param darkMode The color as a dark grid draws it (`IColor.toRGBA(true)`).
  */
-export declare function toConcreteCSS(color: IColor): string;
+export declare function toConcreteCSS(color: IColor, darkMode?: boolean): string;
 /**
  * A fill with each of its colors drawn through `css`: a solid fill's color, a gradient's stops, a
  * pattern's foreground and background. What it does not color (an image, the gradient's geometry,

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

@@ -57,8 +57,18 @@ export interface IHyperlink {
     getTarget(): string;
     /**
      * Removes the link from the cell it is attached to. The cell's text stays.
+     *
+     * @throws When the link is read-only ({@link isReadOnly}).
      */
     delete(options?: ITransaction.OperationOptions): void;
+    /**
+     * Whether the link can only be followed: it is not edited or removed as a link.
+     *
+     * @remarks
+     * A link that is the cell's value (a `HYPERLINK()` result) is read-only; it changes with its
+     * formula.
+     */
+    isReadOnly(): boolean;
     /**
      * For runtime type checking.
      */

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

@@ -12,7 +12,10 @@ export declare class Hyperlink implements IHyperlink {
     protected _p: IHyperlink.Properties;
     protected _r: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>;
     protected _d: ((options?: ITransaction.OperationOptions) => void) | undefined;
-    constructor(textToDisplay: () => string, resolver: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>, json: IHyperlink.JSON, remover?: (options?: ITransaction.OperationOptions) => void);
+    protected _readOnly: boolean;
+    constructor(textToDisplay: () => string, resolver: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>, json: IHyperlink.JSON, remover?: (options?: ITransaction.OperationOptions) => void, readOnly?: boolean);
+    /** {@inheritDoc IHyperlink.isReadOnly} */
+    isReadOnly(): boolean;
     /** {@inheritDoc IHyperlink.delete} */
     delete(options?: ITransaction.OperationOptions): void;
     /** {@inheritDoc IHyperlink.open} */

package/types/src/index.d.ts

@@ -28,12 +28,12 @@ export * from './hyperlink';
 export * from './numFmt';
 export * from './style';
 export * from './resource';
+export * from './fetch';
 export * from './string';
 export * from './richData';
 export * from './anchored';
 export * from './chart';
 export * from './pivot';
-export * from './dataTable';
 export * from './picture';
 export * from './shape';
 export * from './group';
@@ -51,6 +51,7 @@ export * from './externalBook';
 export * from './dataValidation';
 export * from './conditionalFormat';
 export * from './protectedRange';
+export * from './cellControl';
 export * from './slicer';
 export * from './table';
 export { Table } from './table/Table';

package/types/src/named/INamedCollection.d.ts

@@ -78,6 +78,25 @@ export interface INamedCollection extends ICollection<INamed> {
      * take the first.
      */
     getByRanges(ranges: ICellRanges.Address, options?: INamedCollection.GetByRangesOptions): string[];
+    /**
+     * Deletes the defined names nothing reads, as one operation.
+     *
+     * @param options `hiddenOnly` limits it to names flagged hidden; `dryRun` counts without deleting.
+     * @returns How many names were deleted, or with `dryRun`, would be.
+     * @throws `Error` if the names are read-only (a protected workbook structure) and this is not a dry run.
+     *
+     * @remarks
+     * A name is read when a cell formula, a conditional format, a data validation, a chart or another
+     * name refers to it — the readers `ICalculation.INamedFormula.getDependents` reports. A name
+     * that a kept name's definition mentions is kept too, whether or not anything reads that one.
+     * Only defined names are considered; a table is named by the table it belongs to. Excel's built-in
+     * names (`_xlnm.Print_Area`, `_xlnm.Print_Titles`, `_xlnm._FilterDatabase`) are read by the sheet
+     * itself, not by formulas, and are never removed.
+     *
+     * One operation, so one undo puts every name back. Asked of a sheet's collection
+     * (`IWorksheet.getNames()`), only the names scoped to that sheet are considered.
+     */
+    removeUnused(options?: INamedCollection.RemoveUnusedOptions): Promise<number>;
     /**
      * Lookup a named range with a given name.
      *
@@ -216,6 +235,23 @@ export declare namespace INamedCollection {
          */
         includeHidden?: boolean;
     }
+    /**
+     * Options for {@link INamedCollection.removeUnused}.
+     */
+    interface RemoveUnusedOptions {
+        /**
+         * Only names flagged hidden — the ones a user cannot see to delete.
+         *
+         * @defaultValue false
+         */
+        hiddenOnly?: boolean;
+        /**
+         * Count the names that would be deleted, and delete none.
+         *
+         * @defaultValue false
+         */
+        dryRun?: boolean;
+    }
     /**
      * Options for {@link INamedCollection.getByRanges}.
      *

package/types/src/named/NamedCollection.d.ts

@@ -143,6 +143,14 @@ export declare class NamedCollection extends AbstractCollection<INamed, INamedCo
      * {@link _scopedTo}.
      */
     addFormula(name: string, expression: string, replaceExisting?: boolean): INamed;
+    /** {@inheritDoc INamedCollection.removeUnused} */
+    removeUnused(options?: INamedCollection.RemoveUnusedOptions): Promise<number>;
+    /**
+     * {@link removeUnused}, limited to one scope — see {@link _scopedTo}.
+     *
+     * @param scope The sheet whose names are considered; `undefined` for every scope.
+     */
+    _removeUnused(options: INamedCollection.RemoveUnusedOptions | undefined, scope: string | undefined): Promise<number>;
     /** {@link addFormula}, against an explicit `scope` — see {@link _scopedTo}. */
     _addFormula(name: string, expression: string, replaceExisting?: boolean, scope?: string | null): INamed;
     /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
@@ -249,6 +257,16 @@ export declare namespace NamedCollection {
          * nothing to prepare and leaves it undefined.
          */
         prepareRanges?(items: readonly INamed[]): void;
+        /**
+         * Backs {@link INamedCollection.removeUnused} for the source that owns defined names.
+         *
+         * @remarks
+         * `scope`, when given, is the sheet whose own names are considered (a sheet's collection);
+         * `undefined` considers every scope.
+         */
+        removeUnused?(options: INamedCollection.RemoveUnusedOptions & {
+            scope?: string;
+        }): Promise<number>;
     }
     /**
      * What {@link Source.add} needs to define a name.

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

@@ -0,0 +1,58 @@
+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;
+/**
+ * What a cell holds when its formula's evaluation deferred (DESIGN-ASYNC §4.4): the node's
+ * `cachedValue` and the engine grid's value at the cell. Immutable; what moves is the call, which
+ * holds the latest. Each deferring evaluation makes a new one.
+ *
+ * @remarks
+ * Seen only by the formula block and the engine. Every other reader reads it through
+ * {@link readAsync}: the push into a dependent's input, a range read of the engine grid, and the
+ * copy of results to the model, which never receives one.
+ *
+ * The calls are the calculation layer's; all a read needs of one is its latest.
+ */
+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/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