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

package/types/src/wasm/_fontsWasm.d.ts

@@ -0,0 +1,7 @@
+import { WasmBindgenExports } from '@sheetxl/utils';
+import * as glue from '../.generated/wasm/fonts.js';
+/** The binding's exports, once instantiated. */
+export type FontsWasmExports = WasmBindgenExports<typeof glue>;
+/** The binding's exports, instantiated and ready to call. */
+export declare const wasm: FontsWasmExports;
+//# sourceMappingURL=_fontsWasm.d.ts.map

package/types/src/wasm/_sdkWasm.d.ts

@@ -1,5 +1,5 @@
 import { WasmBindgenExports } from '@sheetxl/utils';
-import * as glue from '../../wasm/sdk.js';
+import * as glue from '../.generated/wasm/sdk.js';
 /** The binding's exports, once instantiated. */
 export type SdkWasmExports = WasmBindgenExports<typeof glue>;
 /** The binding's exports, instantiated and ready to call. */

package/types/src/wasm/fontsWasm.d.ts

@@ -0,0 +1,32 @@
+import { FontsWasmExports } from './_fontsWasm';
+export type { FontsWasmExports } from './_fontsWasm';
+/**
+ * Reads font files: the Rust that opens a font's bytes and writes its measures tables, compiled to
+ * WebAssembly.
+ *
+ * @remarks
+ * Lazy on every platform, Node included, and never prefetched: only adding a font needs it
+ * (`sheetxl fonts add`, a font a user gives the browser), and its binary is ten times the sdk's
+ * own. Internal to the sdk.
+ *
+ * @example
+ * ```ts
+ * const { FontFile } = await FontsWasm.load();
+ * const file = new FontFile(bytes);
+ * const tables = file.capture(0, file.identity(0).family, 6, 120);
+ * file.free();
+ * ```
+ */
+export declare const FontsWasm: {
+    /**
+     * Loads and instantiates the WebAssembly, or returns it if it is already loaded.
+     *
+     * @remarks
+     * Concurrent calls share one attempt; a failed attempt is retried by the next call. Rejects with
+     * a `LazyLoadError`.
+     */
+    load: () => Promise<FontsWasmExports>;
+    /** The exports if the WebAssembly has loaded, otherwise `undefined`. */
+    peek: () => FontsWasmExports | undefined;
+};
+//# sourceMappingURL=fontsWasm.d.ts.map

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

@@ -1,2 +1,3 @@
 export * from './sdkWasm';
+export * from './fontsWasm';
 //# sourceMappingURL=index.d.ts.map

package/types/src/wasm/loader.browser.d.ts

@@ -0,0 +1,9 @@
+import { SdkWasmExports } from './_sdkWasm';
+/**
+ * Loads and instantiates the WebAssembly, or returns it if it is already loaded. Concurrent calls
+ * share one attempt; a failed attempt is retried by the next call. Rejects with a `LazyLoadError`.
+ */
+export declare const load: () => Promise<SdkWasmExports>;
+/** The exports if the WebAssembly has loaded, otherwise `undefined`. */
+export declare const peek: () => SdkWasmExports | undefined;
+//# sourceMappingURL=loader.browser.d.ts.map

package/types/src/wasm/loader.node.d.ts

@@ -0,0 +1,9 @@
+import { WasmBindgenExports } from '@sheetxl/utils';
+import * as glue from '../.generated/wasm/sdk.js';
+type SdkWasmExports = WasmBindgenExports<typeof glue>;
+/** The exports, ready: resolved at once. */
+export declare const load: () => Promise<SdkWasmExports>;
+/** The exports, always loaded here. */
+export declare const peek: () => SdkWasmExports | undefined;
+export {};
+//# sourceMappingURL=loader.node.d.ts.map

package/types/src/wasm/sdkWasm.d.ts

@@ -1,11 +1,14 @@
 import { SdkWasmExports } from './_sdkWasm';
 export type { SdkWasmExports } from './_sdkWasm';
 /**
- * `@sheetxl/sdk`'s Rust code, compiled to WebAssembly, loaded on first use.
+ * `@sheetxl/sdk`'s Rust code, compiled to WebAssembly.
  *
  * @remarks
- * Nothing is downloaded or compiled until {@link SdkWasm.load} is called. One module serves the
- * browser and Node. Internal to the sdk: the measurer and the wrapper call it; nothing outside the
+ * How it arrives is the platform's: in a browser a lazy chunk that nothing downloads until
+ * {@link SdkWasm.load} is called; in Node an instantiation as the sdk loads, so {@link SdkWasm.peek}
+ * answers before any synchronous code runs (the `@sheetxl/sdk/wasm/loader` conditional export,
+ * `loader.node.ts` for `node` and `default`, `loader.browser.ts` for `browser`, read only here,
+ * like `license/runtime`). Internal to the sdk: the text engine calls it; nothing outside the
  * package does, so it is not exported from the index.
  *
  * @example

package/types/src/workbook/IWorkbook.d.ts

@@ -1,13 +1,15 @@
-import { Scalar, IRange, IRangeStats, IRuntime, LocaleProfileOverrides } from '@sheetxl/primitives';
+import { Scalar, IRange, IRangeStats, IRichType, IRuntime, LocaleProfileOverrides } from '@sheetxl/primitives';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
 import { IResourceCollection, IResource } from '../resource';
+import { IFetcher } from '../fetch';
 import { IStringCollection } from '../string';
+import { IRichDataCollection } from '../richData';
 import { ICalculation } from '../calculation';
 import { IFontCollection } from '../font';
 import { IScript, IModule, IModuleCollection } from '../scripting';
 import { ICell } from '../cell';
-import { ICellRange, ICellRanges } from '../cellRange';
+import { ICellRange, ICellRanges, ICellRegions } from '../cellRange';
 import { ICommentCollection } from '../comment';
 import { IPerson, IPersonCollection } from '../person';
 import { INamedCollection } from '../named';
@@ -15,57 +17,120 @@ import { IExternalBook, IExternalBookCollection } from '../externalBook';
 import { IPivotTable, IPivotTableCollection } from '../pivot';
 import { ITheme } from '../theme';
 import { IStyleCollection } from '../style';
-import { ISheet, ISheetCollection, ICellContainerOptions } from '../sheet';
+import { ISheet, IOpaqueSheet, IWorksheet, IWorksheetCollection, ICellContainerOptions } from '../sheet';
 import { IWorkbookView } from '../workbookView';
 import { IWorkbookProtection } from '../workbookProtection';
+import { IDocumentProperties } from '../documentProperties';
 import { IWorkbookIO } from '../io';
 /**
- * An `IWorkbook` represents a collection of {@link ISheet | sheets}, along with shared resources.
+ * An `IWorkbook` represents a collection of {@link IWorksheet | sheets}, along with shared resources.
  *
  * This interface provides methods for accessing its elements and event handling.
  *
  * @remarks
- * Most interactions with a {@link IWorkbook | workbook} or {@link ISheet | sheet} are done through a
+ * Most interactions with a {@link IWorkbook | workbook} or {@link IWorksheet | sheet} are done through a
  * {@link ICellRange | workbook range}.
  *
  * @see
- * * {@link getRange} - For interacting with cell values and formatting on a single {@link ISheet | sheet}.
- * * {@link getSheets} - For managing {@link ISheet | sheet}.
+ * * {@link getRange} - For interacting with cell values and formatting on a single {@link IWorksheet | sheet}.
+ * * {@link getWorksheets} - For managing {@link IWorksheet | sheet}.
  * * {@link getNames} - For managing items with defined names.
  */
 export interface IWorkbook extends ITransaction.ITransactional, IListener.ISource<IWorkbook, IWorkbook.IListeners> {
     /**
-     * Returns the collection of sheets within the workbook.
+     * Returns every sheet in tab order, of every kind: worksheets, chart sheets, macro sheets and
+     * dialog sheets.
+     *
+     * @param options Which sheets to return; by default the visible ones.
+     *
+     * @remarks
+     * Use {@link getWorksheets} for the grids alone.
+     */
+    getSheets(options?: IWorkbook.GetSheetsOptions): ISheet[];
+    /**
+     * Returns the sheet of any kind with the given name, or the selected sheet when no name is
+     * given.
+     *
+     * @param name The name of the sheet, ignoring case.
+     *
+     * @remarks
+     * Throws when there is no sheet with that name. Use {@link getWorksheet} when the sheet must be a
+     * grid.
+     */
+    getSheet(name?: string): ISheet;
+    /**
+     * Returns the active tab, whatever its kind.
+     *
+     * @remarks
+     * Use {@link getSelectedWorksheet} for the active grid.
      */
-    getSheets(): ISheetCollection;
+    getSelectedSheet(): ISheet;
+    /**
+     * Returns the collection of worksheets within the workbook.
+     *
+     * @remarks
+     * Only the grids. Use {@link getSheets} for every tab, chart sheets included.
+     */
+    getWorksheets(): IWorksheetCollection;
     /**
      * Adds a new sheet to the workbook.
      *
      * @remarks
-     * This is a convenience method that wraps `{@link ISheetCollection.add}`.
+     * This is a convenience method that wraps `{@link IWorksheetCollection.add}`.
      */
-    addSheet(options?: ISheetCollection.AddOptions | string | number): ISheet;
+    addWorksheet(options?: IWorksheetCollection.AddOptions | string | number): IWorksheet;
     /**
-     * Returns the sheet at the given offset.
+     * Returns the worksheet at the given offset among the worksheets.
      *
-     * @param index A 0-based index of the sheet.
+     * @param index A 0-based index into the worksheets with the given visibility. Sheets of other
+     * kinds are not counted, so this is not the tab position ({@link ISheet.getIndex}).
      * @param visibility The visibility of the sheet.
      */
-    getSheetAt(index: number, visibility?: ISheet.Visibility): ISheet;
+    getWorksheetAt(index: number, visibility?: ISheet.Visibility): IWorksheet;
     /**
-     * Returns the sheet for the given name, or the selected sheet when no name is given.
+     * Returns the worksheet for the given name, or the selected worksheet when no name is given.
      *
      * @param name The name of the sheet. Omit for the selected sheet — "the sheet", unqualified,
-     * is the one the user (or agent) is looking at. `getSelectedSheet` remains the explicit form.
+     * is the one the user (or agent) is looking at. `getSelectedWorksheet` remains the explicit form.
      * @param visibility The visibility of the sheet.
+     *
+     * @remarks
+     * Throws when the sheet is not a worksheet: a chart sheet, say, or the selected tab when that is
+     * not a worksheet. Use {@link getSheet} for any kind.
      */
-    getSheet(name?: string, visibility?: ISheet.Visibility): ISheet;
+    getWorksheet(name?: string, visibility?: ISheet.Visibility): IWorksheet;
     /**
-     * Returns the currently active sheet within the workbook.
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getWorksheetAt}.
+     * @hidden
      */
-    getSelectedSheet(): ISheet;
+    getWorksheet(index: number, visibility?: ISheet.Visibility): IWorksheet;
     /**
-     * Returns the currently active sheet index within the workbook.
+     * Returns the active worksheet, or `null` when the active tab is not a worksheet.
+     *
+     * @remarks
+     * A chart sheet (or a macro or dialog sheet) can be the active tab, and then there is no active
+     * worksheet: like VBA's `ActiveCell`, this is `null` rather than some other worksheet.
+     * {@link getSelectedSheet} returns the active tab whatever its kind.
+     */
+    getSelectedWorksheet(): IWorksheet | null;
+    /**
+     * Exists to have api parity with Google Apps Script.
+     *
+     * @deprecated Use {@link getSelectedWorksheet}.
+     * @hidden
+     */
+    getActiveSheet(): IWorksheet | null;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getSelectedWorksheet}.
+     * @hidden
+     */
+    getActiveWorksheet(): IWorksheet | null;
+    /**
+     * Returns the position of the active tab among the visible sheets of every kind.
      */
     getSelectedSheetIndex(): number;
     /**
@@ -116,7 +181,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * default `'throw'` policy treats one as a fault when aggregating.
      *
      * @remarks
-     * The workbook form of {@link ISheet.getStats}: every sheet's used range contributes,
+     * The workbook form of {@link IWorksheet.getStats}: every sheet's used range contributes,
      * including hidden and very-hidden sheets — visibility is a display concern, not a data
      * one. A workbook with no used cells returns empty statistics (`getSize() === 0`),
      * never `null`.
@@ -127,16 +192,40 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * {@link ICellRange.getStats}
      */
     getStats(options?: ICellRange.GetStatsOptions): IRangeStats;
+    /**
+     * Returns the regions of the `anomalies` feature across every sheet, in reading order.
+     *
+     * @example
+     * ```ts
+     * wb.getAnomalies({ checks: ['linkLabelMismatch', 'styleRole'], limit: 25 });
+     * ```
+     *
+     * @remarks
+     * The workbook form of {@link ICellRange.getAnomalies}: every sheet contributes, hidden and
+     * very hidden included, in one order, and each region's address names its sheet. The listing
+     * spans sheets, so its {@link ICellRegions.getRange} is the selected sheet's; each region is
+     * clipped against its own sheet.
+     */
+    getAnomalies(options?: ICellRange.GetAnomaliesOptions): ICellRegions;
     /**
      * Returns a range of cells for the current selection.
+     *
+     * @remarks
+     * Throws when the active tab is not a worksheet.
      */
     getSelectedRange(options?: ICellRange.GetRangeOptions): ICellRange;
     /**
      * Returns ranges of cells for the current selection.
+     *
+     * @remarks
+     * Throws when the active tab is not a worksheet.
      */
     getSelectedRanges(options?: ICellRange.GetRangeOptions): ICellRanges;
     /**
      * Returns the selected cell.
+     *
+     * @remarks
+     * Throws when the active tab is not a worksheet.
      */
     getSelectedCell(): ICell;
     /**
@@ -159,14 +248,16 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      */
     replace(cells: Iterator<ICell>, replace: ICell.Update | ((original: ICell) => ICell.Update), options?: IWorkbook.ReplaceOptions): IWorkbook.ReplaceResults;
     /**
-     * Returns the next sheet in the sheets collection. If the last one it will return the first.
+     * Returns the next visible sheet, of any kind, after the given tab position. If the last one it
+     * will return the first.
      *
      * @remarks
      * If there is only 1 sheet this will return the current sheet.
      */
     getNextSheet(index: number): ISheet;
     /**
-     * Returns the previous sheet in the sheets collection. If the first one it will return the last.
+     * Returns the previous visible sheet, of any kind, before the given tab position. If the first
+     * one it will return the last.
      *
      * @remarks
      * If there is only 1 sheet this will return the current sheet.
@@ -202,6 +293,34 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the current shared resources.
      */
     getResources(): IResourceCollection;
+    /**
+     * The fetcher the workbook reaches outside itself with: the handlers per URL scheme a host
+     * registered, given as {@link IWorkbook.ConstructorOptions.fetcher}.
+     */
+    getFetcher(): IFetcher;
+    /**
+     * Fetches as the workbook does, with the standard `fetch` signature: what `IMAGE`, a web
+     * service function, and a renderer drawing a picture use.
+     *
+     * @remarks
+     * A resource with a `fetchedFrom` is the workbook's copy of that URL, and answers a fetch of it
+     * without a request. Anything else goes to {@link getFetcher}. The fetch saves nothing itself: a
+     * successful answer to a plain GET that is not a picture is cached until the workbook closes and
+     * answers later fetches of that URL. A response whose bytes are a picture says what they are,
+     * whatever the server called them. Plain GETs of one URL in flight together share one request;
+     * aborting one caller's signal does not stop it for the others. `cache: 'reload'` skips all of
+     * these and asks the source.
+     *
+     * The workbook saves a resource while a value holds it: `IMAGE` adds the picture it fetched for
+     * its values. A picture of the host's own goes in a cell the same way, under a URL the host mints:
+     *
+     * ```ts
+     * const source = `resource:${crypto.randomUUID()}`;
+     * const resource = workbook.getResources().add({ source: { buffer: bytes }, fetchedFrom: source });
+     * workbook.getRange('A1').setValue({ type: 'image', data: { source, resource } });
+     * ```
+     */
+    fetch(input: string, init?: RequestInit): Promise<Response>;
     /**
      * Returns the current shared resources.
      */
@@ -210,6 +329,62 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the current shared resources.
      */
     getTransactions(): ITransaction.IStore;
+    /**
+     * Performs a set of operations as one: one commit, one undo step, one round of events.
+     *
+     * @param callback Performs the operations. Handed the commit being written and `workbook`,
+     * this workbook bound to the batch.
+     * @param options Description of the operation or additional options. Used for undo/redo and
+     * history.
+     *
+     * @remarks
+     * Work through `workbook` rather than this one. Everything reached through it - sheets, ranges,
+     * tables - is part of the batch, and a listener added through it takes part in the batch by
+     * default ({@link IListener.Options.transactional}). A range listener added through it hears each
+     * operation as it is made, rather than once when the batch lands, and what it writes joins the
+     * batch ({@link ICellRange.ListenerOptions.transactional}). A listener added any other way, while
+     * the batch is open, is outside it.
+     *
+     * The objects reached through `workbook` are not `===` to the ones reached through this workbook,
+     * though the same object always compares equal to itself. They can be passed to any method of
+     * either.
+     *
+     * A batch that performs no writes is elided: the commit id is unchanged, no events fire, and
+     * nothing is added to the undo stack or commit log.
+     *
+     * @example
+     * ```ts
+     * await workbook.doBatch(async (_commit, wb) => {
+     *   const cell = wb.getSelectedWorksheet()!.getRange('A1');
+     *   cell.addListener(() => console.log('A1 changed'));
+     *   cell.setValue(1); // logs 'A1 changed' before the next line runs
+     * });
+     * ```
+     */
+    doBatch<R = any>(callback: (commit: ITransaction.ICommit, workbook: this) => R | Promise<R>, options?: string | ITransaction.OperationOptions): R | Promise<R>;
+    /**
+     * What a commit wrote: the {@link IWorksheet.ChangeEvent}s it announced, one for each sheet and
+     * {@link IWorksheet.ChangeEvent.getKind | kind} (data, formatting, merges, spills).
+     *
+     * @param commitId The commit to describe. Omit for the current one.
+     * @returns Empty for a commit that changed no cells (a view, a name, a chart).
+     *
+     * @remarks
+     * The same events the sheets announced when the commit landed, read afterwards: the
+     * previous commit is its parent, and an undo is reported as the commit it moved to, so
+     * {@link IWorksheet.ChangeEvent.isUndo} is always `false` here.
+     *
+     * @throws If the store no longer has the commit.
+     *
+     * @example
+     * ```ts
+     * for (const change of wb.getChanges()) {
+     *   if (change.getKind() !== 'onDataChange') continue; // values and formulas, not formatting
+     *   console.log(change.getSheet().getName(), change.getRanges()?.toString());
+     * }
+     * ```
+     */
+    getChanges(commitId?: string): IWorksheet.ChangeEvent[];
     /**
      * Get the current theme.
      */
@@ -337,16 +512,20 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the protection object for the workbook.
      */
     getProtection(): IWorkbookProtection;
+    /**
+     * The workbook's document properties: author, title, company and the like.
+     */
+    getProperties(): IDocumentProperties;
     /**
      * The workbook's VBA code name — conventionally `ThisWorkbook` — or `null` if it has none.
      *
      * @defaultValue null
      *
      * @remarks
-     * The workbook-level counterpart to {@link ISheet.getCodeName}: the identifier VBA binds the
+     * The workbook-level counterpart to {@link IWorksheet.getCodeName}: the identifier VBA binds the
      * workbook's own document module through, where workbook event handlers such as `Workbook_Open`
      * live. Like a sheet's, it is carried from the file and **read-only** — see
-     * {@link ISheet.getCodeName} for why SheetXL never mints one.
+     * {@link IWorksheet.getCodeName} for why SheetXL never mints one.
      */
     getCodeName(): string | null;
     /**
@@ -356,7 +535,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * @remarks
      * The name-manager view: what EXISTS, not what any one sheet can see. A global name and a
      * sheet-scoped name that share a name are two items here and both are returned; ask
-     * {@link ISheet.getNames} for the one a formula on that sheet would resolve to.
+     * {@link IWorksheet.getNames} for the one a formula on that sheet would resolve to.
      */
     getNames(): INamedCollection;
     /**
@@ -374,7 +553,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the pivot tables on every sheet, in sheet order.
      *
      * @remarks
-     * A view over each sheet's {@link ISheet.getPivotTables}; `getByName` searches them all.
+     * A view over each sheet's {@link IWorksheet.getPivotTables}; `getByName` searches them all.
      * Read-only for now: each table is carried as it was read and written back unchanged.
      */
     getPivotTables(): IPivotTableCollection;
@@ -382,7 +561,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the comments and notes on every sheet, in sheet order.
      *
      * @remarks
-     * A view over each sheet's {@link ISheet.getComments}; `getById` and `getByReplyId` search
+     * A view over each sheet's {@link IWorksheet.getComments}; `getById` and `getByReplyId` search
      * them all. A comment is added on a sheet's collection.
      */
     getComments(): ICommentCollection;
@@ -431,7 +610,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * @remarks
      * This is a convenience method for `getCalculation().createFormula(expression, coords, options)`.
      * A bare reference (`A2`) resolves against the active cell's sheet; use
-     * {@link ISheet.createFormula} to anchor against a specific sheet.
+     * {@link IWorksheet.createFormula} to anchor against a specific sheet.
      *
      * @see {@link ICalculation.createFormula}
      */
@@ -456,6 +635,23 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      *   it has not been started.
      */
     whenCalculationReady(): Promise<ICalculation.Status>;
+    /**
+     * Returns when every font the workbook measures with has loaded and every autofit that was
+     * taken with a stand-in meanwhile has been taken again.
+     *
+     * @remarks
+     * Measuring never waits: a style naming a face not yet loaded measures with a related or
+     * built-in one and the lookup starts the load, the way a browser paints with a fallback until
+     * a web font arrives. This is the point after which sizes are final. Fonts are shared, so this
+     * also waits for faces other workbooks started loading; a load that fails leaves its stand-in
+     * and still settles.
+     */
+    whenFontsReady(): Promise<void>;
+    /**
+     * Returns when the workbook is settled: {@link whenCalculationReady} and {@link whenFontsReady}
+     * both hold.
+     */
+    whenReady(): Promise<void>;
     /**
      * Returns any user defined functions stored with the workbook.
      */
@@ -464,7 +660,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the modules this workbook owns.
      *
      * @remarks
-     * The workbook half of {@link ISheet.getModules}, and the same collection
+     * The workbook half of {@link IWorksheet.getModules}, and the same collection
      * `getScripts().getModules()` answers with — modules belong to the model, whereas
      * {@link IScript} is what runs them.
      *
@@ -481,7 +677,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      *
      * @param options Options to control the JSON output.
      */
-    toJSON(options?: ISheet.ToJSONOptions): Promise<IWorkbook.JSON>;
+    toJSON(options?: IWorksheet.ToJSONOptions): Promise<IWorkbook.JSON>;
     /**
      * Returns any custom workbook options that are provided in constructor.
      */
@@ -690,9 +886,24 @@ export declare namespace IWorkbook {
         last: ICell | null;
     }
     /**
-     * Used for persisting metadata about a `ISheet`.
+     * Options for {@link IWorkbook.getSheets}.
      */
-    interface SheetRefJSON {
+    interface GetSheetsOptions {
+        /**
+         * The least visible sheets to include: `Hidden` includes the hidden sheets, `VeryHidden` every
+         * sheet.
+         *
+         * @defaultValue ISheet.Visibility.Visible
+         */
+        visibility?: ISheet.Visibility;
+    }
+    /**
+     * Used for persisting an {@link ISheet}: its tab, and its body as {@link SheetRefJSON.kind} says.
+     *
+     * @typeParam T The body: {@link IWorksheet.JSON} for a worksheet, {@link IOpaqueSheet.JSON} for
+     * the other kinds.
+     */
+    interface SheetRefJSON<T extends ISheet.JSON = IWorksheet.JSON | IOpaqueSheet.JSON> {
         /**
          * A unique name for the sheet.
          */
@@ -714,9 +925,15 @@ export declare namespace IWorkbook {
          */
         visibility?: ISheet.Visibility;
         /**
-         * The actual sheet.
+         * What the sheet holds, and so what {@link sheet} is.
+         *
+         * @defaultValue ISheet.Kind.Worksheet
          */
-        sheet?: ISheet.JSON;
+        kind?: ISheet.Kind;
+        /**
+         * The sheet's body.
+         */
+        sheet?: T;
     }
     /**
      * JSON representation of an `IWorkbook` used for serialization and deserialization.
@@ -726,6 +943,10 @@ export declare namespace IWorkbook {
         styles?: IStyleCollection.JSON;
         resources?: IResource.JSON[];
         strings?: string[];
+        /** The rich values cells name by id (`{ t: 'r', v: id }`). */
+        richData?: IRichDataCollection.JSON[];
+        /** The kinds {@link richData} names that are not registered in code (a kind read from a file). */
+        richTypes?: IRichType.JSON[];
         /**
          * The people the workbook knows.
          *
@@ -766,6 +987,10 @@ export declare namespace IWorkbook {
         modules?: Record<string, IModule.JSON>;
         calc?: ICalculation.JSON;
         protection?: IWorkbookProtection.JSON;
+        /**
+         * @see {@link IWorkbook.getProperties}
+         */
+        properties?: IDocumentProperties.JSON;
         date1904?: boolean;
         /**
          * The workbook's VBA code name. Absent when it has none.
@@ -792,12 +1017,12 @@ export declare namespace IWorkbook {
     /**
      * Callback to allow for custom `ISheets`. The Workbook provides a default implementation.
      */
-    interface CreateSheetCallback {
+    interface CreateWorksheetCallback {
         (
         /**
          * Options used for creating the Sheet instance.
          */
-        options: ISheet.ConstructorOptions, 
+        options: IWorksheet.ConstructorOptions, 
         /**
          * The name of the new  sheet.
          */
@@ -809,7 +1034,7 @@ export declare namespace IWorkbook {
         /**
          * @defaultValue ISheet.Visibility.Visible
          */
-        visibility: ISheet.Visibility): ISheet;
+        visibility: ISheet.Visibility): IWorksheet;
     }
     /**
      * Options available when creating an IWorkbook.
@@ -818,7 +1043,7 @@ export declare namespace IWorkbook {
         /**
          * Hook to allow for custom sheet creation.
          */
-        createSheetCallback?: CreateSheetCallback;
+        createWorksheetCallback?: CreateWorksheetCallback;
         /**
          * Returns a human readable sheet name given a 0-based index.
          *
@@ -842,6 +1067,11 @@ export declare namespace IWorkbook {
          * A theme for the workbook.
          */
         theme?: ITheme;
+        /**
+         * How the workbook reaches outside itself: the handlers per URL scheme, with the host's
+         * authentication. Omitted, a {@link Fetcher} for `http:` and `https:`.
+         */
+        fetcher?: IFetcher;
         /**
          * Load from JSON.
          */