@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

package/types/src/io/IWorkbookIO.d.ts

@@ -0,0 +1,1322 @@
+import { FetchArgs, Base64Args, ITaskProgress, MaybePromise } from '@sheetxl/utils';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { IWorkbook } from '../workbook';
+/**
+ * Interface for workbook input/output operations across multiple source types and formats.
+ *
+ * @remarks
+ * This interface provides a flexible I/O system with **two independent dimensions**:
+ *
+ * ### **Source Type** (Where/How data is stored)
+ * The physical location or container of the workbook data:
+ * - **File**: Local file system files (`File` objects)
+ * - **Blob**: Binary data blobs (from canvas, clipboard, etc.)
+ * - **URL/Fetch**: Remote resources fetched via HTTP/HTTPS
+ * - **ArrayBuffer**: Raw binary data in memory
+ * - **Base64**: Base64-encoded strings
+ * - **Stream**: Streaming data (`ReadableStream`)
+ *
+ * ### **Format Type** (How data is encoded)
+ * The encoding/file format of the workbook data:
+ * - **sxl**: SheetXL format
+ * - **xlsx**: Excel 2007+ format (Office Open XML)
+ * - **csv**: Comma-separated values
+ * - **xml**: Excel 2003 XML format
+ * - And other registered formats
+ *
+ * ### How They Work Together
+ * Any **source type** can contain any **format type**. For example:
+ * - A `File` could contain `sxl`, `xlsx`, `csv` data
+ * - A `URL` could point to an `sxl`, `xlsx`, or `csv` file
+ * - An `ArrayBuffer` could hold `sxl`, `xlsx`, or `csv` data
+ *
+ * The system automatically detects the format type from:
+ * - File extensions (`.xlsx`, `.csv`, etc.)
+ * - MIME types (`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`)
+ * - Content sniffing (examining the actual data)
+ *
+ * @example
+ * ```typescript
+ * // Example 1: File source with xlsx format
+ * const wb = await WorkbookIO.read({ source: fileObject }); // Auto-detects .xlsx
+ *
+ * // Example 2: URL source with csv format
+ * const wb = await WorkbookIO.read({ source: 'https://example.com/data.csv' });
+ *
+ * // Example 3: ArrayBuffer source with explicit format
+ * const wb = await WorkbookIO.read({
+ *   source: arrayBuffer,
+ *   format: 'xlsx' // Format can't be auto-detected or forced
+ * });
+ * ```
+ */
+export interface IWorkbookIO extends IListener.ISource<IWorkbookIO, IWorkbookIO.Events>, ITransaction.ICommitSource {
+    /**
+     * Reads a workbook from any source type with automatic format detection.
+     *
+     * @param sourceOrOptions Configuration specifying the source and optional format. Can also be passed
+     *   directly as a `string` (URL, path, or data URI) as a shorthand for `{ source: string }`. Omit
+     *   the source entirely to let the active {@link IWorkbookIO.IBackingStore} resolve one (e.g. an
+     *   open picker in the browser).
+     *
+     * @returns A promise resolving to the decoded {@link IWorkbook}, or `null` if no source was
+     *   resolved (e.g. the user cancelled an open picker). All read metadata — path, display name,
+     *   resource type (format), size — lives on the workbook's {@link IWorkbook.getOrigin | origin}
+     *   handle; there is no separate details object.
+     *
+     * @throws {Error} When the source type cannot be detected or accessed
+     * @throws {Error} When no appropriate format handler is available for the detected format
+     * @throws {Error} When the read operation fails (corrupt file, network error, etc.)
+     *
+     * @remarks
+     * ## Source Type Automatic-Detection
+     * The method automatically determines the **source type** (where data comes from):
+     *
+     * | Input Pattern | Detected Source Type | Example |
+     * |--------------|---------------------|---------|
+     * | `{ base64: "..." }` | Base64 string | `{ base64: "iVBORw0K..." }` |
+     * | `{ input: "..." }` | Fetch/URL | `{ input: "https://api.example.com" }` |
+     * | String starting with `data:` | Base64 data URI | `"data:application/json;base64,..."` |
+     * | String starting with `http://` or `https://` | Remote URL | `"https://example.com/file.xlsx"` |
+     * | String starting with `/`, `./`, `../` | Relative/absolute path | `"./data/workbook.csv"` |
+     * | Other strings | Treated as URL/path | `"workbook.xlsx"` |
+     * | `File` object | Browser File API | `<input type="file">` result |
+     * | `Blob` object | Binary data blob | Canvas, clipboard, etc. |
+     * | `ArrayBuffer` or TypedArray | Binary buffer | Raw bytes in memory |
+     * | `ReadableStream` | Streaming data | Converted to buffer first |
+     * | `Promise<T>` | Async source | Resolved, then re-detected |
+     * | `() => T` | Lazy source | Invoked, then re-detected |
+     *
+     * ## Format Type Automatic-Detection
+     * The method automatically determines the **format type** (how data is encoded):
+     * 1. **File extension** from source name (`.sxl`, `.xlsx`, `.csv`)
+     * 2. **MIME type** from HTTP response headers
+     * 3. **Content inspection** by examining magic bytes/signatures
+     * 4. **Explicit format** via `options.format`
+     *
+     * @example
+     * ```typescript
+     * // Auto-detect everything from a File object
+     * const wb = await WorkbookIO.read({ source: fileInput.files[0] });
+     * console.log(wb!.getName(), wb!.getOrigin().getPath());
+     *
+     * // Fetch from URL (auto-detects format from extension or Content-Type)
+     * const wb = await WorkbookIO.read({
+     *   source: 'https://example.com/spreadsheet.xlsx'
+     * });
+     *
+     * // ArrayBuffer with explicit format (can't be auto-detected)
+     * const wb = await WorkbookIO.read({
+     *   source: sxlArrayBuffer,
+     *   format: 'sxl'
+     * });
+     *
+     * // Lazy loading with progress callback
+     * const wb = await WorkbookIO.read({
+     *   source: async () => await fetch('/api/workbook').then(r => r.arrayBuffer()),
+     *   progress: (amount) => console.log(`${amount}%:`)
+     * });
+     * ```
+     */
+    read<T extends IWorkbookIO.ReadOptions = IWorkbookIO.ReadOptions>(sourceOrOptions?: string | IWorkbookIO.Origin | T): Promise<IWorkbook | null>;
+    /**
+     * Resolves an address (a path or URL) to an {@link IWorkbookIO.Origin} handle. No I/O is
+     * performed.
+     *
+     * @param pathOrUrl The path or URL to resolve.
+     *
+     * @remarks
+     * The canonical way to mint a handle for {@link IWorkbookIO.read} / {@link IWorkbookIO.write};
+     * the string shorthands on those methods are sugar over this. The handle binds to the *active*
+     * {@link IWorkbookIO.IBackingStore} at mint time.
+     */
+    getOrigin(pathOrUrl: string): IWorkbookIO.Origin;
+    /**
+     * Writes a workbook via the configured {@link IWorkbookIO.IBackingStore}: a **Save** (no
+     * target — write back to the workbook's own {@link IWorkbook.getOrigin | origin}) or an
+     * **Export** (an explicit target — write a copy; the workbook's origin is untouched).
+     *
+     * @param workbook The workbook instance to write.
+     * @param target An explicit destination — a file name/path or an {@link IWorkbookIO.Origin} —
+     *   for an **export**. Omit (or pass options in its place) for a **save**.
+     * @param options Encoding options (format, progress).
+     *
+     * @returns A promise resolving to the {@link IWorkbookIO.Origin} handle actually written — the
+     *   workbook's own origin for a save, the target handle for an export, updated with the written
+     *   size — or `null` if the operation was cancelled (e.g. the user dismissed a save dialog).
+     *
+     * @remarks
+     * **Save** (`write(workbook)`): the destination is the workbook's origin. A bound, writable
+     * origin is re-saved silently. An unbound or read-only origin makes the store resolve a
+     * destination (a save dialog in the browser; an error in bare Node) — and on success the IO
+     * layer **fills that origin in place**, so the next save is silent. The rule: *the store fills
+     * in a handle it resolved itself; it never overrides a handle the caller supplied.*
+     *
+     * **Export** (`write(workbook, target)`): writes a copy to the target. The workbook's origin —
+     * its identity — is never touched, and the export does **not** mark the workbook clean
+     * ({@link IWorkbookIO.addCommitListener} fires for saves only). Re-targeting a workbook ("Save
+     * As") is {@link IWorkbookIO.writeAs} — the explicit rebind verb.
+     *
+     * Replacing the store (via {@link IWorkbookIO.setBackingStore}) redirects writing entirely — e.g.
+     * a VSCode extension posting bytes to the editor host, or a CLI prompting in the terminal.
+     *
+     * ### **Format Type** Auto-Detection
+     * If `options.format` is not provided, it is inferred from the destination's extension (the
+     * explicit target, else the workbook's origin). There is no implicit default.
+     *
+     * @example
+     * ```typescript
+     * // Save — back to the workbook's origin (or resolve a destination if it has none).
+     * const details = await workbookIO.write(workbook);
+     *
+     * // Export — a copy to an explicit destination; the origin is untouched.
+     * const details = await workbookIO.write(workbook, 'copy.xlsx');
+     *
+     * // Export in a specific format.
+     * const details = await workbookIO.write(workbook, 'report.csv', { format: 'csv' });
+     * ```
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API | File System Access API}
+     */
+    write<T extends IWorkbookIO.WriteOptions = IWorkbookIO.WriteOptions>(workbook: IWorkbook, target?: string | IWorkbookIO.Origin | T, options?: T): Promise<IWorkbookIO.Origin | null>;
+    /**
+     * Save As: re-target the workbook's identity to `target`, then save. On success the workbook's
+     * {@link IWorkbook.getOrigin | origin} (and so its display name) follows the new destination; on
+     * cancel/failure the origin is restored — identity unchanged.
+     *
+     * @param workbook The workbook instance to re-target and save.
+     * @param target The new destination — a file name/path or an {@link IWorkbookIO.Origin}.
+     * @param options Encoding options (format, progress) plus
+     *   {@link IWorkbookIO.WriteAsOptions.prompt} — re-targeting is this verb, *asking the user* is
+     *   that option.
+     *
+     * @returns A promise resolving to the workbook's (re-targeted) {@link IWorkbookIO.Origin}, or
+     *   `null` if the operation was cancelled.
+     *
+     * @remarks
+     * This is the **explicit rebind verb** — the one origin re-target {@link IWorkbookIO.write} never
+     * performs. It composes re-target + save so the whole flow stays coherent: the store resolves /
+     * persists against the workbook's own (re-targeted) handle — keeping platform session state (e.g.
+     * a browser file handle cache) keyed to the one live handle — and the save path marks the
+     * workbook clean via {@link IWorkbookIO.addCommitListener}. Handle mutation authority sits in the
+     * IO/store layer (the same layer that fills a resolved destination in), which is why this lives
+     * here and not on the model or a wrapper object.
+     *
+     * "Write a copy without moving the identity" is {@link IWorkbookIO.write} with a target (an
+     * export), not this.
+     */
+    writeAs<T extends IWorkbookIO.WriteAsOptions = IWorkbookIO.WriteAsOptions>(workbook: IWorkbook, target: string | IWorkbookIO.Origin, options?: T): Promise<IWorkbookIO.Origin | null>;
+    /**
+     * Writes a workbook to an ArrayBuffer in the specified format.
+     *
+     * @param workbook The workbook instance to write
+     * @param options Write configuration including format type and encoding options
+     *
+     * @returns A promise resolving to an ArrayBuffer containing the encoded workbook data
+     *
+     * @remarks
+     * This method produces raw binary data in the **format type** you specify (sxl, xlsx, csv, etc.).
+     * The **source type** is always ArrayBuffer - use this for:
+     * - In-memory operations
+     * - Custom upload logic
+     * - Further processing before saving
+     *
+     * ## Format Type Auto-Detection
+     * - Specify via `options.format` (e.g., `'sxl'`, `'xlsx'`, `'csv'`)
+     * - If not provided, defaults to the first registered write format
+     *
+     * @example
+     * ```typescript
+     * // Write as Excel format
+     * const buffer: ArrayBufferLike = await workbookIO.writeArrayBuffer(workbook, {
+     *   format: 'xlsx'
+     * });
+     *
+     * // Write as CSV
+     * const csvBuffer: ArrayBufferLike = await workbookIO.writeArrayBuffer(workbook, {
+     *   format: 'csv'
+     * });
+     *
+     * // Upload to server
+     * const buffer: ArrayBufferLike = await workbookIO.writeArrayBuffer(workbook, { format: 'xlsx' });
+     * await fetch('/api/upload', {
+     *   method: 'POST',
+     *   body: buffer
+     * });
+     * ```
+     */
+    writeArrayBuffer<T extends IWorkbookIO.WriteOptions = IWorkbookIO.WriteOptions>(workbook: IWorkbook, options?: T): Promise<ArrayBufferLike>;
+    /**
+     * Overrides the {@link IWorkbookIO.IBackingStore} used by {@link IWorkbookIO.write} (and,
+     * in future, reads).
+     *
+     * @param store A backing store that owns persistence, or `null` to restore the built-in
+     *   platform store.
+     *
+     * @remarks
+     * Use this to redirect where workbooks are persisted — for example a VSCode extension that
+     * posts bytes to the editor host, or a server/cloud store. The store receives a
+     * {@link IWorkbookIO.WriteRequest} (with a helper to encode the workbook) and returns the
+     * written {@link IWorkbookIO.Origin} handle, or `null` to signal cancellation.
+     *
+     * @example
+     * ```typescript
+     * // Route every write through a host (e.g. a VSCode extension).
+     * workbookIO.setBackingStore({
+     *   async write({ format, origin, encode }) {
+     *     const bytes = await encode();
+     *     await host.writeActiveDocument(bytes);
+     *     return { format, origin, size: bytes.byteLength };
+     *   }
+     * });
+     * ```
+     */
+    setBackingStore(store: IWorkbookIO.IBackingStore | null): void;
+    /**
+     * The active {@link IWorkbookIO.IBackingStore} — the override set via
+     * {@link IWorkbookIO.setBackingStore}, or the built-in platform store.
+     */
+    getBackingStore(): IWorkbookIO.IBackingStore;
+    /**
+     * Whether the active {@link IWorkbookIO.IBackingStore} can persist workbooks (implements `write`).
+     *
+     * @remarks
+     * Reflects the active store's *own* capability — a UI-capability probe (e.g. enable Save), not a
+     * guarantee about a particular {@link IWorkbookIO.write} call. Use to gate save affordances.
+     */
+    canWrite(): boolean;
+    /**
+     * Whether the active {@link IWorkbookIO.IBackingStore} provides its own `read` (interactive source
+     * acquisition).
+     *
+     * @remarks
+     * Reflects the active store's *own* capability — not the platform read fallback. A write-only
+     * override reports `false` even though {@link IWorkbookIO.read} of in-hand bytes still works via
+     * the fallback. Use to gate open / drag-drop affordances (and to release their shortcuts).
+     */
+    canRead(): boolean;
+    /**
+     * Returns available read format types (encoding formats that can be read).
+     *
+     * @param options Optional filters to narrow down the format types
+     * @returns Array of format type definitions that can decode workbook data
+     *
+     * @remarks
+     * Returns **format types** (encoding formats like sxl, xlsx, csv), not source types.
+     * Each format type includes:
+     * - File extensions it supports (e.g., `['.xlsx', '.xlsm']`)
+     * - MIME type (e.g., `'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'`)
+     * - Handler function for decoding that format
+     *
+     * These format types work with **any source type** (File, URL, ArrayBuffer, etc.).
+     *
+     * @example
+     * ```typescript
+     * // Get all available read formats
+     * const allFormats = workbookIO.getReadFormats();
+     * console.log(allFormats.map(f => f.key)); // ['sxl', 'xlsx', 'csv', ...]
+     *
+     * // Find format by file extension
+     * const csvFormat = workbookIO.getReadFormats({ ext: '.csv' });
+     *
+     * // Find format by MIME type
+     * const xlsxFormat = workbookIO.getReadFormats({
+     *   mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+     * });
+     * ```
+     */
+    getReadFormats(options?: IWorkbookIO.GetFormatsOptions): Promise<IWorkbookIO.FormatType[]>;
+    /**
+     * Returns available write format types (encoding formats that can be written).
+     *
+     * @param options Optional filters to narrow down the format types.
+     * @returns Array of format type definitions that can encode workbook data
+     *
+     * @remarks
+     * Returns **format types** (encoding formats like sxl, xlsx, csv), not source types.
+     * Each format type includes:
+     * - File extension it produces (e.g., `'.xlsx'`)
+     * - MIME type (e.g., `'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'`)
+     * - Handler function for encoding that format
+     *
+     * The encoded data can then be written to **any source type** (File, ArrayBuffer, etc.).
+     *
+     * @example
+     * ```typescript
+     * // Get all available write formats
+     * const allFormats = workbookIO.getWriteFormats();
+     * console.log(allFormats.map(f => f.key)); // ['sxl', 'xlsx', 'csv', ...]
+     *
+     * // Find format by extension
+     * const xlsxFormat = workbookIO.getWriteFormats({ ext: '.xlsx' });
+     *
+     * // Build a file type picker for UI
+     * const formats = workbookIO.getWriteFormats();
+     * const fileTypes = formats.map(f => ({
+     *   description: f.description,
+     *   accept: { [f.mimeType]: [f.ext] }
+     * }));
+     * ```
+     */
+    getWriteFormats(options?: IWorkbookIO.GetFormatsOptions): Promise<IWorkbookIO.FormatType[]>;
+    /**
+     * Adds a new read format type to the I/O system.
+     */
+    install(plugin: IWorkbookIO.Plugin): Promise<void>;
+    /**
+     * Subscribe to ambient I/O lifecycle events ({@link IWorkbookIO.Events.onRead | onRead},
+     * {@link IWorkbookIO.Events.onWrite | onWrite}).
+     *
+     * @remarks
+     * These fire on the (shared) I/O service for *every* workbook it reads or writes, so a listener
+     * filters on {@link IWorkbookIO.IOEvent.workbook} for the one it cares about. Useful for UI
+     * (busy/recent-files), telemetry, and dirty-tracking — bridge `onWrite` to
+     * {@link TransactionSaveStateManager.markSaved} using {@link IWorkbookIO.WriteEvent.commitId}.
+     */
+    addListeners(listeners: IWorkbookIO.Listeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * Subscribe to commits that were persisted.
+     * See {@link ITransaction.ICommitSource.addCommitListener}.
+     *
+     * @remarks
+     * Fires after a successful **save** — a {@link IWorkbookIO.write} with no explicit target — with
+     * the commit captured at encode time. It does NOT fire for an explicit-target export ("Save a
+     * Copy" must not mark the document clean), a cancelled write, or
+     * {@link IWorkbookIO.writeArrayBuffer} (a raw encode). Pass this directly to a
+     * {@link TransactionSaveStateManager} to track a workbook's dirty state with no extra wiring.
+     */
+    addCommitListener(listener: ITransaction.ICommitSource.IListeners): IListener.Remove;
+}
+export declare namespace IWorkbookIO {
+    /**
+     * A light virtual file handle: where a workbook maps to — its path, display name, format, and
+     * whether it can be written back to. The IO analog of a `Uri` / `FileSystemFileHandle`.
+     *
+     * @remarks
+     * Minted and owned by the IO/store layer, never by the workbook model — but every workbook holds
+     * a stable, *read-only* reference to one (see {@link IWorkbook.getOrigin}), like the DOM's
+     * `document.URL`. The origin **object** is mutable in place by its owner (a save that resolves a
+     * destination fills an unbound origin; a store rename moves it), firing `onChange` so holders
+     * follow; the workbook's *reference* to it never changes.
+     *
+     * An **unbound** origin (`getPath()` returns `null`) belongs to an in-memory workbook with no
+     * destination yet. A **read-only** origin (`canWrite()` is `false`) is real provenance that cannot
+     * be silently re-saved — a fetched URL, a dropped file without a writable handle — signalling
+     * callers to resolve a destination ("Save As") instead.
+     */
+    interface Origin extends IListener.ISource<Origin, Origin.IListeners> {
+        /**
+         * The display name (without extension), e.g. `'report'` — derived from the
+         * {@link getPath | path} when not set explicitly — or `null` for an unbound, unnamed origin.
+         * Display fallbacks (e.g. a localized "Untitled") are a UI concern.
+         */
+        getName(): string | null;
+        /**
+         * The full path or URL, e.g. `'./out/report.xlsx'` or `'https://host/report.xlsx'`, or `null`
+         * for an unbound (in-memory) origin.
+         */
+        getPath(): string | null;
+        /**
+         * The resolved format key (e.g. `'xlsx'`), or `null` if unknown. Derived from the
+         * {@link getPath | path} extension when not set explicitly.
+         *
+         * @remarks
+         * The handle's **resource type** — the analog of a `File.type` / `Content-Type`: most file
+         * systems make the type part of the handle, and so does this one. The full
+         * {@link IWorkbookIO.FormatType} (description, extensions, mime) is a
+         * `getReadFormats({ search: key })` / `getWriteFormats({ search: key })` lookup away.
+         */
+        getFormat(): string | null;
+        /**
+         * The {@link getPath | path}'s file extension, lower-cased and without the dot (e.g. `'xlsx'`),
+         * or `null` when the origin is unbound or its path has no extension.
+         *
+         * @remarks
+         * The handle's **physical** type, as distinct from {@link getFormat}'s semantic one: a format
+         * key (`'SheetXL'`) is not a file extension (`'sxl'`), and one is not derivable from the other
+         * without the registry. Use this wherever a file *name* is being built (a suggested name, a
+         * download name); use `getFormat()` to resolve a handler.
+         */
+        getExtension(): string | null;
+        /**
+         * The {@link IWorkbookIO.EncryptionType | encryption envelope} this source is wrapped in (e.g.
+         * `'offcrypto'`), or `null` when it is plaintext.
+         *
+         * @remarks
+         * The scheme actually **on disk** — discovered when the source is read, recorded when it is
+         * written, and `null` until then. For "is or *will be* encrypted", which is what chrome and the
+         * write path both actually ask, use {@link isEncrypted}.
+         *
+         * Never the password: origins are rendered into logs and REPL output, and ride events and
+         * progress callbacks, so a secret has no business here (see `PROTECTION-DESIGN.md` §5f).
+         *
+         * Use it to show a lock affordance, and to recognise that writing plaintext over it would be a
+         * downgrade — {@link IWorkbookIO.WriteOptions.password} makes that refusal explicit.
+         *
+         * Unrelated to sheet/workbook *protection*, which is a hash gate stored in the model.
+         */
+        getEncryption(): string | null;
+        /**
+         * Whether this source is encrypted, or **would be** if written now.
+         *
+         * @remarks
+         * `true` when the source was read as encrypted, was written encrypted, or has had a password
+         * set via {@link setPassword} that no save has applied yet. That last case is why this exists
+         * separately from {@link getEncryption}, which reports the scheme actually on disk and is `null`
+         * until a save happens.
+         *
+         * This is the question chrome asks (show a lock?) and the question a write asks (would writing
+         * plaintext be a downgrade?).
+         */
+        isEncrypted(): boolean;
+        /**
+         * Sets — or clears, with `null` — the password this source is encrypted with, for this session.
+         *
+         * @remarks
+         * **Set-only.** There is no getter on this interface: a password can be handed in and cleared,
+         * never read back. A UI collects one and passes it here; keeping a copy buys nothing and only
+         * widens the exposure. (The IO layer reads it through a privileged channel on the concrete
+         * `WorkbookOrigin`, the same way it mutates the rest of the handle.)
+         *
+         * Non-privileged, exactly like {@link setName}: both record what the *next* write should do,
+         * and neither is on disk until it happens. Clearing with `null` is the "remove password" verb
+         * and is carried into that write.
+         *
+         * The password lives and dies with the handle — nothing survives the session, and a closed
+         * workbook takes it with it.
+         */
+        setPassword(password: string | null): void;
+        /**
+         * The last-known size of the source in bytes, or `null` if unknown — a stat-style property
+         * (the analog of `FileSystemFileHandle.getFile().size`), updated by the IO/store layer on
+         * each read/write of this handle.
+         */
+        getSize(): number | null;
+        /**
+         * Whether this source can be written back to (a silent re-save). A read-only source (e.g. a
+         * fetched URL) returns `false`, signalling callers to prompt for a destination ("Save As").
+         */
+        canWrite(): boolean;
+        /**
+         * Set the display name (a label, without extension). Fires `onChange` (and, through the
+         * workbook, `onNameChange`).
+         *
+         * @remarks
+         * Renaming the *label* is not privileged — it feeds display and the suggested file name of the
+         * next destination-resolving save, nothing else. The path/`canWrite` (real identity) remain
+         * owned by the IO/store layer. A rename is not a model edit and never enters the undo stack.
+         */
+        setName(name: string | null): void;
+    }
+    namespace Origin {
+        /**
+         * IListener interface for {@link IWorkbookIO.Origin} events.
+         */
+        interface Events {
+            /**
+             * Called when the origin changes in place (e.g. a save to a new location or a rename).
+             */
+            onChange?(source: Origin): void;
+        }
+        interface IListeners extends IListener.Callbacks<Origin, Origin.Events> {
+        }
+    }
+    /**
+     * Common fields shared by all ambient I/O events.
+     */
+    interface IOEvent {
+        /**
+         * The workbook that was read or written. A listener filters on this to react to a specific
+         * workbook (the service is shared across all of them).
+         */
+        workbook: IWorkbook;
+        /**
+         * The {@link IWorkbookIO.Origin} handle the operation actually used — the workbook's own
+         * origin for a read or a save; the (distinct) target handle for an export.
+         *
+         * @remarks
+         * Uniform across read and write, so an ambient listener (e.g. recent-files) can track "the
+         * handle just touched" without branching on the event kind.
+         */
+        origin: IWorkbookIO.Origin;
+    }
+    /**
+     * Fired after a workbook has been successfully read.
+     */
+    interface ReadEvent extends IOEvent {
+    }
+    /**
+     * Fired after a workbook has been successfully written via {@link IWorkbookIO.write}.
+     *
+     * @remarks
+     * Not fired by {@link IWorkbookIO.writeArrayBuffer} (a raw encode, used for exports / uploads) or
+     * by a cancelled write.
+     */
+    interface WriteEvent extends IOEvent {
+        /**
+         * The workbook's transaction commit id at the moment its bytes were *encoded*.
+         *
+         * @remarks
+         * An opaque token identifying the persisted state. Pass it to
+         * {@link TransactionSaveStateManager.markSaved} so the workbook is marked clean as of exactly
+         * that state — edits made during the (async) write correctly remain unsaved.
+         */
+        commitId: string | null;
+        /**
+         * `true` when the write was a **save** (to the workbook's own origin); `false` for an
+         * explicit-target **export** (a copy). Only saves mark the workbook clean — see
+         * {@link IWorkbookIO.addCommitListener}.
+         */
+        save: boolean;
+    }
+    /**
+     * Ambient I/O lifecycle events. See {@link IWorkbookIO.addListeners}.
+     */
+    interface Events {
+        /**
+         * Called after a workbook is successfully read.
+         */
+        onRead?(source: IWorkbookIO, event: IWorkbookIO.ReadEvent): void;
+        /**
+         * Called after a workbook is successfully written via {@link IWorkbookIO.write}.
+         */
+        onWrite?(source: IWorkbookIO, event: IWorkbookIO.WriteEvent): void;
+    }
+    interface Listeners extends IListener.Callbacks<IWorkbookIO, IWorkbookIO.Events> {
+    }
+    /**
+     * Union type representing all possible io source types.
+     *
+     * @remarks
+     * This type encompasses all the different ways data can be provided
+     * for import operations, from simple strings to complex stream objects.
+     */
+    type IOSource = string | File | Blob | ArrayBufferLike | Uint8Array<ArrayBufferLike> | ReadableStream<Uint8Array> | FetchArgs | Base64Args;
+    /**
+     * Union type representing all possible input sources for workbook imports.
+     *
+     * @remarks
+     * This type is used to define the source of data for importing workbooks,
+     * allowing for various formats such as URLs, files, and raw binary data.
+     */
+    interface FormatType {
+        /**
+         * The key used to identify the type of import.
+         *
+         * @remarks
+         * Must be unique across all format types.
+         */
+        key: string;
+        /**
+         * A human readable name for the format, as shown in a Save As type dropdown.
+         *
+         * @remarks
+         * This is a file-type NOUN PHRASE — `'<Family> <DocumentKind>'`, plus an optional `'(Variant)'`
+         * — not a brand and not an adjective: `'Excel Workbook'`, `'SheetXL Workbook'`,
+         * `'SheetXL Workbook (JSON)'`, `'Comma Separated Values'`. It goes verbatim into the native file
+         * picker's type list (the browser appends `(*.ext)` itself), so a bare brand (`'SheetXL'`) reads
+         * as a vendor rather than a file type, and a bare adjective (`'Comma Delimited'`) never says
+         * delimited *what*.
+         *
+         * A variant belongs in PARENTHESES when it is a noun (`'(JSON)'`), and before the document kind
+         * only when it is a true adjective (`'Excel Binary Workbook'`) — `'SheetXL JSON Workbook'`
+         * stacks three nouns with no grammatical joint. Excel ships the parenthesized-and-then-extension
+         * form itself: `'CSV (Comma delimited) (*.csv)'`.
+         *
+         * It is also substituted into sentences such as "Save as {description}", which is the other
+         * reason it must stand alone as a noun.
+         */
+        description?: string;
+        /**
+         * The mime type of the import.
+         */
+        mimeType: string;
+        /**
+         * Tags that are used by the UI.
+         */
+        tags?: string[];
+        /**
+         * A format for users who go looking: real and fully supported, but not *featured*.
+         *
+         * @remarks
+         * It earns no entry of its own in curated chrome — the Save As menu, which is a short list of
+         * the formats most people want — while staying available everywhere the COMPLETE set is
+         * offered: the native picker's "save as type" dropdown, a `--format` argument, and
+         * {@link IWorkbookIO.getWriteFormats} itself. Nothing about reading or writing it is
+         * special-cased; only its prominence is.
+         *
+         * This is a *demotion*, not a hiding: a format nobody may write does not belong in the registry
+         * at all. Use it where a menu entry would cost more attention than it earns — `'SheetXL
+         * Workbook (JSON)'` next to `'SheetXL Workbook'`, whose difference (pretty-printed and
+         * uncompressed) matters to a developer and to no one else.
+         *
+         * @defaultValue false
+         */
+        advanced?: boolean;
+        /**
+         * The file extensions that this type of supports.
+         */
+        exts: string[];
+    }
+    /**
+     * A **registration-side** encryption envelope: a container that wraps a workbook's encoded bytes
+     * in an encrypted form, independent of what format those bytes are in.
+     *
+     * @remarks
+     * Encryption sits **above** the format handlers, not inside them: an envelope carries opaque
+     * bytes, so one implementation serves every registered format (and every format registered
+     * later) rather than each plugin growing its own crypto. {@link IWorkbookIO.read} detects an
+     * envelope on the acquired bytes and unwraps them before the format handler ever sees them;
+     * {@link IWorkbookIO.write} wraps the handler's output on the way out.
+     *
+     * Registered like a format ({@link Registry.registerEncryption}) so the code ships with the
+     * plugin that implements it — a host that installs no such plugin simply reports encrypted files
+     * as unsupported instead of failing to parse them.
+     */
+    interface EncryptionType {
+        /**
+         * Unique identifier for this envelope (e.g. `'offcrypto'`).
+         */
+        key: string;
+        /**
+         * A description of the envelope, for error messages and UI.
+         */
+        description?: string;
+        /**
+         * Whether these bytes are wrapped in this envelope. Must be cheap (a magic-number/header
+         * check) and precise — a container shared with unencrypted files (e.g. CFB, which is also
+         * legacy `.xls`) has to inspect enough to be sure.
+         */
+        detect(bytes: ArrayBufferLike): boolean | Promise<boolean>;
+        /**
+         * Unwraps the envelope, returning the plaintext bytes.
+         *
+         * @throws {InvalidPasswordError} When the password does not open the envelope — callers
+         *   re-prompt on this specific error, so it must not be reported as a generic failure.
+         */
+        decode(bytes: ArrayBufferLike, password: string): Promise<ArrayBufferLike>;
+        /**
+         * Wraps plaintext bytes in the envelope.
+         */
+        encode(bytes: ArrayBufferLike, password: string): Promise<ArrayBufferLike>;
+    }
+    /**
+     * The context passed to {@link ReadOptions.onPassword}.
+     */
+    interface PasswordRequest {
+        /**
+         * The handle being opened — use its name in the prompt.
+         */
+        origin: IWorkbookIO.Origin;
+        /**
+         * The envelope that was detected (e.g. `'offcrypto'`).
+         */
+        encryption: string;
+        /**
+         * Tries a password **without ending the prompt**, so a dialog can report "incorrect password"
+         * in place and let the user try again.
+         *
+         * @returns `true` if the password opens the source.
+         *
+         * @throws Anything other than a wrong password (a malformed container, an unsupported scheme) —
+         *   those are not retryable and should surface to the user as errors.
+         *
+         * @remarks
+         * Calling this is optional but strongly preferred: **the caller owns the retry loop**, and this
+         * is what lets it stay in one dialog instead of closing and reopening one per attempt. A prompt
+         * that returns a password without validating it is still honored — it simply gets one attempt.
+         *
+         * Work is not repeated: a password that validated here is not decrypted a second time when the
+         * prompt resolves. Expect the call to take a noticeable moment (the derivation is deliberately
+         * expensive) and show a busy affordance rather than freezing the dialog.
+         */
+        validate(password: string): Promise<boolean>;
+    }
+    /**
+     * A **registration-side** read format: the consumer-facing {@link FormatType} chrome plus the
+     * decode handler. Used by plugins / the registry only — the handler is never part of the
+     * consumption surface ({@link IWorkbookIO.getReadFormats} returns plain {@link FormatType}s).
+     */
+    interface ReadFormatType extends FormatType {
+        /**
+         * The handler function for importing a workbook from this format.
+         */
+        handler: ReadHandler;
+    }
+    /**
+     * A **registration-side** write format: the consumer-facing {@link FormatType} chrome plus the
+     * encode handler. Used by plugins / the registry only — the handler is never part of the
+     * consumption surface ({@link IWorkbookIO.getWriteFormats} returns plain {@link FormatType}s).
+     */
+    interface WriteFormatType extends FormatType {
+        /**
+         * The handler function for exporting a workbook to this format.
+         */
+        handler: WriteHandler;
+    }
+    /**
+     * Options for reading and creating a workbook from various sources.
+     */
+    interface ReadOptions {
+        /**
+         * The io source for reading. Can be a direct value, Promise, or function.
+         *
+         * @remarks
+         * Omit (or pass `null`) to let the active {@link IWorkbookIO.IBackingStore} resolve a source
+         * itself — for example a browser open picker. {@link IWorkbookIO.read} then resolves to `null`
+         * if nothing was opened (e.g. the user cancelled).
+         */
+        source?: MaybePromise<IOSource> | (() => MaybePromise<IOSource>) | null;
+        /**
+         * Indicate the the workbook should be read-only.
+         *
+         * @remarks
+         * This is a shortcut to createWorkbookOptions.readonly = true
+         * If it is set in the createWorkbookOptions it will override this value.
+         */
+        readonly?: boolean;
+        /**
+         * Read the workbook for calculation only, trading visual formatting for a faster, lighter read.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * Use this when you need the data — values, formulas, and number formats — but not how it looks:
+         * headless calculation, server-side processing, data extraction. Calculated results are always
+         * correct; purely visual formatting (fonts, fills, borders, charts, images, …) may be skipped to
+         * save time and memory.
+         */
+        calcOnly?: boolean;
+        /**
+         * Provide options to the workbook constructor.
+         */
+        createWorkbookOptions?: IWorkbook.ConstructorOptions;
+        /**
+         * Optional file type hint (extension, MIME type, or import key).
+         *
+         * Used for type detection when it cannot be inferred from the source.
+         * Examples: 'xlsx', 'csv', 'application/json', 'Excel'
+         */
+        format?: string;
+        /**
+         * Password for an encrypted source.
+         *
+         * @remarks
+         * Applies to **file encryption** (Excel's "password to open") — confidentiality of the bytes —
+         * and is handled by the IO layer for every format, not by any one format handler. It is
+         * unrelated to sheet/workbook *protection*, which is a hash-based UI gate stored in the model.
+         *
+         * Ignored when the source is not encrypted. Prefer {@link onPassword} for interactive callers:
+         * it can re-prompt when a password is rejected.
+         */
+        password?: string;
+        /**
+         * Called **once** when the source is encrypted and no usable password is in hand.
+         *
+         * @param request The handle being opened, plus {@link PasswordRequest.validate} for trying a
+         *   password without ending the prompt.
+         *
+         * @returns The accepted password, or `null` to cancel — {@link IWorkbookIO.read} then resolves
+         *   to `null`, exactly as a dismissed open picker does.
+         *
+         * @remarks
+         * **The caller owns the retry loop.** Use `request.validate(password)` to test a password and
+         * keep prompting on `false`; return the password once it is accepted, or `null` when the user
+         * gives up. The IO layer does not re-invoke this, so a dialog opens once and stays open —
+         * rather than being torn down and rebuilt per attempt, which is visible as flicker.
+         *
+         * A caller that skips `validate` and returns a password directly gets exactly one attempt, and
+         * a wrong one raises `InvalidPasswordError`. That is the right shape for a non-interactive
+         * caller (a script, a server), which has nothing to re-prompt.
+         */
+        onPassword?(request: IWorkbookIO.PasswordRequest): MaybePromise<string | null>;
+        /**
+         * Optional progress callback for long running imports.
+         */
+        progress?: ITaskProgress<IWorkbookIO.Origin>;
+        /**
+         * Allows for different constructor arguments depending on the type of format detected.
+         *
+         * @remarks
+         * This will overwrite the options with the createWorkbookOptions provided.
+         */
+        typedCreateWorkbookOptions?: Record<string, IWorkbook.ConstructorOptions>;
+    }
+    /**
+     * Options for writing and exporting a workbook — purely *how* to write (encoding concerns).
+     *
+     * @remarks
+     * The destination is not an option: it is the `target` parameter of {@link IWorkbookIO.write}
+     * (an export), or the workbook's own {@link IWorkbook.getOrigin | origin} when no target is
+     * given (a save). See `IO-DESIGN.md`.
+     */
+    interface WriteOptions {
+        /**
+         * Optional file type hint (extension, MIME type, or export key).
+         *
+         * Used for type detection when it cannot be inferred from the destination.
+         * Examples: 'xlsx', 'csv', 'application/json', 'Excel'
+         */
+        format?: string;
+        /**
+         * What to do about **file encryption** — a deliberate three-state field:
+         *
+         * | Value | Meaning |
+         * |---|---|
+         * | *omitted* | Keep the destination's current encryption |
+         * | `string` | Encrypt with this password |
+         * | `null` | Write plaintext **explicitly** — the "remove password" verb |
+         *
+         * @remarks
+         * Omitting it is *not* "write plaintext": re-saving an encrypted workbook must not quietly
+         * produce an unencrypted file, which is a security downgrade caused by a keystroke. When the
+         * destination is encrypted and no password is available, {@link IWorkbookIO.write} throws
+         * `PasswordRequiredError` rather than guessing. Removing encryption is possible, but has to be
+         * *said* — that is what `null` is for.
+         *
+         * Unrelated to sheet/workbook *protection*, which is model state and travels in the file.
+         */
+        password?: string | null;
+        /**
+         * Optional progress callback for long running writes.
+         */
+        progress?: ITaskProgress<IWorkbookIO.Origin>;
+    }
+    /**
+     * Options for {@link IWorkbookIO.writeAs} — everything a write takes, plus the one thing only a
+     * *reorigin* can mean.
+     */
+    interface WriteAsOptions extends WriteOptions {
+        /**
+         * Force the store to **resolve a destination** even when the workbook's handle is already bound
+         * and writable — the "Save **As**" *interaction*.
+         *
+         * @remarks
+         * Without this a store persists silently to a handle it holds (see
+         * {@link IWorkbookIO.IBackingStore.write}), which is exactly right for Save and exactly wrong
+         * for a Save As the user asked for: re-targeting the origin to a name that happens to match the
+         * handle it already had would overwrite the original with no dialog at all.
+         *
+         * It is opt-in rather than implied by the verb, because {@link IWorkbookIO.writeAs} means
+         * *reorigin*, not *ask*: a script or host that named a real destination
+         * (`writeAs(wb, 'out/report.xlsx')`) wants it written, not a picker. Only the caller knows which
+         * of the two it is doing.
+         *
+         * "Resolve a destination" is the store's own affair — the native save picker in the browser.
+         * A store with no way to ask (a browser without the File System Access API, whose only write
+         * path is a download) simply writes; there is nothing to force.
+         *
+         * @defaultValue false
+         */
+        prompt?: boolean;
+    }
+    /**
+     * A destination (and, optionally, source) for persisting workbooks — for example the local
+     * file system, a browser download, a VSCode host, or a cloud service.
+     *
+     * @remarks
+     * The active store is used by {@link IWorkbookIO.write} and can be replaced via
+     * {@link IWorkbookIO.setBackingStore}. A store is conceptually stateless from the caller's
+     * point of view; any session state it keeps (such as a browser `FileSystemFileHandle` for
+     * silent re-save) is a private implementation detail and never appears in these types.
+     */
+    interface IBackingStore {
+        /**
+         * Persists the workbook described by the request.
+         *
+         * @returns The written {@link IWorkbookIO.Origin} handle (normally `request.origin`, updated
+         *   in place), or `null` if cancelled.
+         *
+         * @remarks
+         * Optional. A read-only store omits it; {@link IWorkbookIO.canWrite} then reports `false` and
+         * {@link IWorkbookIO.write} throws. A store must implement at least one of `read` / `write`.
+         */
+        write?(request: WriteRequest): Promise<IWorkbookIO.Origin | null>;
+        /**
+         * Acquires bytes for a workbook and decodes them (via {@link ReadRequest.decode}).
+         *
+         * @returns The decoded workbook, or `null` if the store could not produce one (e.g. the user
+         *   cancelled an open picker, or the store does not recognize the source).
+         *
+         * @remarks
+         * Optional. {@link IWorkbookIO.read} uses the active store's `read` when present, and otherwise
+         * falls back to the built-in platform store — so a store that only overrides `write` still gets
+         * the default read behavior.
+         */
+        read?(request: ReadRequest): Promise<IWorkbook | null>;
+    }
+    /**
+     * The request passed to {@link IWorkbookIO.IBackingStore.write}.
+     *
+     * @remarks
+     * The store receives the destination as an {@link IWorkbookIO.Origin} handle — never a
+     * fileName-vs-provenance ambiguity. Its contract:
+     * - **bound + writable** origin → persist to it silently (no dialog), *unless* {@link prompt}.
+     * - **unbound or read-only** origin, or {@link prompt} → resolve a destination itself (a save
+     *   picker in the browser; an error in bare Node), using {@link suggestedName} for any
+     *   prompt/default, and **update the handle in place** to the resolved destination (the store
+     *   fills in a handle it resolved itself; it never overrides one that was already bound and
+     *   writable).
+     *
+     * The store returns this same handle (updated in place — including the written `size`).
+     */
+    interface WriteRequest {
+        /**
+         * The workbook being written.
+         */
+        workbook: IWorkbook;
+        /**
+         * The resolved write format (consumer chrome — encoding runs through {@link encode}).
+         */
+        format: FormatType;
+        /**
+         * The destination handle: the workbook's own origin for a save, or a minted one for an
+         * explicit-target export. May be unbound (`getPath()` `null`) — see the store contract above.
+         */
+        origin: IWorkbookIO.Origin;
+        /**
+         * A suggested file name (with extension) for any destination prompt or default.
+         */
+        suggestedName: string;
+        /**
+         * Resolve a destination even when {@link origin} is bound and writable — see
+         * {@link WriteAsOptions.prompt}, whose value this carries. A store that cannot ask ignores it.
+         */
+        prompt?: boolean;
+        /**
+         * Encodes the workbook to bytes using the resolved format, or an alternate format key.
+         *
+         * @remarks
+         * Call this **after** resolving the destination (e.g. once a Save picker / permission prompt has
+         * returned). The first invocation also fires the caller's {@link ITaskProgress.onStart}, so
+         * encoding before the prompt resolves would show progress UI on top of the dialog. A store that
+         * is cancelled should return without calling `encode`, so `onStart` never fires for it.
+         */
+        encode: (format?: string) => Promise<ArrayBufferLike>;
+    }
+    /**
+     * The request passed to {@link IWorkbookIO.IBackingStore.read}.
+     *
+     * @remarks
+     * A store's job is **source acquisition** — turn `source` (or, when it is `null`, a location it
+     * resolves itself, e.g. an open picker) into bytes — and then call {@link ReadRequest.decode},
+     * which handles format detection and workbook construction. This mirrors how
+     * {@link WriteRequest.encode} keeps format concerns out of the store.
+     */
+    interface ReadRequest {
+        /**
+         * The source to read from, or `null` for the store to resolve a location itself.
+         */
+        source: ReadOptions['source'] | null;
+        /**
+         * The read options (format hint, name, createWorkbookOptions, progress, etc.).
+         */
+        options: Omit<ReadOptions, 'source'>;
+        /**
+         * Decodes acquired bytes into a workbook: resolves the format, unwraps any encryption envelope
+         * (prompting via {@link ReadOptions.onPassword}), mints the origin handle (which the workbook
+         * carries), runs the handler, and reports progress. The store supplies what it knows about the
+         * source via {@link ReadInfo}.
+         *
+         * @returns The decoded workbook, or `null` if the caller cancelled a password prompt — a store
+         *   should return that `null` onward, the same as it would for a dismissed picker.
+         */
+        decode(bytes: ArrayBufferLike, info?: ReadInfo): Promise<IWorkbook | null>;
+    }
+    /**
+     * What a {@link IWorkbookIO.IBackingStore} knows about an acquired source, passed to
+     * {@link ReadRequest.decode}.
+     */
+    interface ReadInfo {
+        /**
+         * Explicit format hint (extension, MIME type, or key), if any.
+         */
+        format?: string;
+        /**
+         * File extension derived from the source name, used for format detection.
+         */
+        ext?: string;
+        /**
+         * The source's display name (without path), if known.
+         */
+        name?: string;
+        /**
+         * The source's absolute path or URL, if known — recorded as the workbook's origin.
+         */
+        absolutePath?: string;
+        /**
+         * The source size in bytes, if known.
+         */
+        size?: number;
+        /**
+         * The detected source type (e.g. `'file'`, `'fetch'`), used for a fallback display name.
+         */
+        sourceType?: string;
+        /**
+         * Whether the acquired source can be written back to (a silent re-save). Only the store knows —
+         * e.g. a local fs path can (Node), a browser `File` can only when the store holds a writable
+         * handle for it. Defaults to `false` when omitted; seeds the minted origin's
+         * {@link IWorkbookIO.Origin.canWrite}.
+         */
+        canWrite?: boolean;
+    }
+    /**
+     * For reading from an array into an IWorkbook.
+     *
+     * @param arrayBuffer The array buffer containing the workbook data.
+     * @param options Optional options for loading the workbook, such as format type and workbook options.
+     * @returns A promise that resolves to an IWorkbook instance.
+     */
+    type ReadHandler = (arrayBuffer: ArrayBuffer, options?: Omit<IWorkbookIO.ReadOptions, 'source'>) => Promise<IWorkbook>;
+    /**
+     * Export for writing to an array from an IWorkbook
+     *
+     * @param workbook The workbook instance to export.
+     * @param options Optional options for saving the workbook, such as compression and whitespace formatting.
+     * @returns A promise that resolves to an array buffer representing the workbook
+     */
+    type WriteHandler = (workbook: IWorkbook, options?: Omit<IWorkbookIO.WriteOptions, 'source'>) => Promise<ArrayBufferLike>;
+    /**
+     * Options for filtering and searching format types.
+     *
+     * @remarks
+     * All options are combined using **AND logic**. A format must match all specified criteria to be included.
+     *
+     * ## Search vs Filters
+     *
+     * ### `search` - Case-insensitive partial match (OR across fields)
+     * Searches across multiple fields (key, extensions, MIME type, tags, description) and includes
+     * formats where **ANY** field contains the search term.
+     *
+     * ### Other options - Exact filters (AND across options)
+     * All other options are exact filters that must match precisely. A format must satisfy
+     * **ALL** specified filters to be included.
+     *
+     * @example
+     * ```typescript
+     * // Search: Find formats containing "excel" anywhere
+     * getFormats({ search: 'excel' }); // Matches xlsx (in description), xml (in tags), etc.
+     *
+     * // Filter: Get only xlsx format
+     * getFormats({ ext: '.xlsx' }); // Exact match on extension
+     *
+     * // Combined: Search for "excel" AND spreadsheet tag
+     * getFormats({ search: 'excel', tags: 'spreadsheet' });
+     *
+     * // Multiple filters: xlsx extension AND spreadsheet tag
+     * getFormats({ ext: '.xlsx', tags: 'spreadsheet' });
+     * ```
+     */
+    interface GetFormatsOptions {
+        /**
+         * Case-insensitive partial search across multiple fields.
+         *
+         * @remarks
+         * Searches in: key, file extensions, MIME type, tags, and description.
+         * Returns formats where **ANY** field contains the search term (OR logic).
+         *
+         * Use this for user-facing search boxes or fuzzy matching.
+         *
+         * @example
+         * ```typescript
+         * // Find all Excel-related formats
+         * getFormats({ search: 'excel' });
+         *
+         * // Find formats with "xml" anywhere
+         * getFormats({ search: 'xml' });
+         * ```
+         */
+        search?: string;
+        /**
+         * Filter by exact file extension (e.g., `'.xlsx'`, `'.csv'`).
+         *
+         * @remarks
+         * - Include the dot prefix
+         * - Case-insensitive exact match
+         * - Use this when you know the exact extension you want
+         *
+         * @example
+         * ```typescript
+         * // Get only XLSX formats
+         * getFormats({ ext: '.xlsx' });
+         * ```
+         */
+        ext?: string;
+        /**
+         * Filter by exact MIME type (e.g., `'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'`).
+         *
+         * @remarks
+         * - Case-sensitive exact match
+         * - Useful for matching HTTP Content-Type headers
+         *
+         * @example
+         * ```typescript
+         * // Get format by MIME type
+         * getFormats({ mimeType: 'text/csv' });
+         * ```
+         */
+        mimeType?: string;
+        /**
+         * Filter by exact format key.
+         *
+         * @remarks
+         * - Case-insensitive exact match
+         * - The key is the unique identifier for each format (e.g., 'xlsx', 'csv', 'sxl')
+         * - Use this when you need to find a specific format by its identifier
+         *
+         * @example
+         * ```typescript
+         * // Get the XLSX format
+         * getFormats({ key: 'xlsx' });
+         * ```
+         */
+        key?: string;
+        /**
+         * Filter by exact tags (e.g., `'spreadsheet'`, `'text'`).
+         *
+         * @remarks
+         * - Exact string match (case-sensitive)
+         * - If multiple tags are needed, pass an array
+         * - Returns formats that have **ALL** specified tags (AND logic)
+         *
+         * @example
+         * ```typescript
+         * // Get formats tagged as 'spreadsheet'
+         * getFormats({ tags: 'spreadsheet' });
+         *
+         * // Get formats with both 'spreadsheet' and 'binary' tags
+         * getFormats({ tags: ['spreadsheet', 'binary'] });
+         * ```
+         */
+        tags?: string | string[];
+    }
+    interface Registry {
+        /**
+         * Registers a new read format type or replaces an existing one.
+         *
+         * @param format The format type definition containing decoder logic.
+         *
+         * @remarks
+         * Use this to add support for new workbook encoding formats (not source types).
+         * If a format with the same `key` already exists, it will be replaced.
+         *
+         * This allows you to:
+         * - Add custom format types (e.g., proprietary formats)
+         * - Override built-in format handlers
+         * - Extend format support for your application
+         *
+         * The registered format will work with **all source types** automatically.
+         *
+         * @example
+         * ```typescript
+         * // Register a custom XML-based format
+         * workbookIO.registerReadFormat({
+         *   key: 'custom-xml',
+         *   description: 'Custom XML Workbook Format',
+         *   mimeType: 'application/x-custom-workbook+xml',
+         *   exts: ['.cwb', '.cxml'],
+         *   tags: ['xml', 'custom'],
+         *   handler: async (buffer, options) => {
+         *     // Decode buffer into IWorkbook
+         *     const xmlString = new TextDecoder().decode(buffer);
+         *     return parseCustomXML(xmlString);
+         *   }
+         * });
+         *
+         * // Now any source type can use this format
+         * await workbookIO.read({ source: 'data.cwb' }); // Auto-detected
+         * await workbookIO.read({ source: fileObject, format: 'custom-xml' });
+         * ```
+         */
+        registerReadFormat(format: IWorkbookIO.ReadFormatType): Promise<void>;
+        /**
+         * Registers a new write format type or replaces an existing one.
+         *
+         * @param format The format type definition containing encoder logic.
+         *
+         * @remarks
+         * Use this to add support for new workbook encoding formats (not source types).
+         * If a format with the same `key` already exists, it will be replaced.
+         *
+         * This allows you to:
+         * - Add custom format types (e.g., proprietary formats)
+         * - Override built-in format handlers
+         * - Extend format support for your application
+         *
+         * The registered format can then be written to **any source type** (File, ArrayBuffer, etc.).
+         *
+         * @example
+         * ```typescript
+         * // Register a custom JSON-based format
+         * workbookIO.registerWriteFormat({
+         *   key: 'custom-json',
+         *   description: 'Custom JSON Workbook Format',
+         *   mimeType: 'application/json',
+         *   ext: '.cjson',
+         *   tags: ['json', 'custom'],
+         *   handler: async (workbook, options) => {
+         *     // Encode workbook into ArrayBuffer
+         *     const jsonString = JSON.stringify(customSerialize(workbook));
+         *     return new TextEncoder().encode(jsonString).buffer;
+         *   }
+         * });
+         *
+         * // Use with any write method
+         * await workbookIO.write(workbook, { fileName: 'report.cjson' });
+         * const buffer = await workbookIO.writeArrayBuffer(workbook, { format: 'custom-json' });
+         * ```
+         */
+        registerWriteFormat(format: IWorkbookIO.WriteFormatType): Promise<void>;
+        /**
+         * Registers an encryption envelope, or replaces an existing one with the same `key`.
+         *
+         * @param encryption The envelope definition (detect / decode / encode).
+         *
+         * @remarks
+         * An envelope is **format-independent** — it wraps whatever bytes a format handler produced —
+         * so registering one enables password support for every registered format at once. See
+         * {@link IWorkbookIO.EncryptionType}.
+         *
+         * @example
+         * ```typescript
+         * registry.registerEncryption({
+         *   key: 'offcrypto',
+         *   description: 'Office Document Encryption',
+         *   detect: (bytes) => isEncryptedOfficeContainer(bytes),
+         *   decode: (bytes, password) => decryptOffCrypto(bytes, password),
+         *   encode: (bytes, password) => encryptOffCrypto(bytes, password)
+         * });
+         * ```
+         */
+        registerEncryption(encryption: IWorkbookIO.EncryptionType): Promise<void>;
+    }
+    /**
+     * Interface for format plugins that can be installed into the workbook I/O system.
+     */
+    interface Plugin {
+        /**
+         * The name of the plugin.
+         */
+        name: string;
+        /**
+         * The version of the plugin.
+         */
+        version?: string;
+        /**
+         * The description of the plugin.
+         */
+        description?: string;
+        /**
+         * The author of the plugin.
+         */
+        author?: string;
+        /**
+         * Function to register the new io types into a given IWorkbookIO instance.
+         *
+         * @param registry The IWorkbookIO registry to install the plugin into.
+         */
+        register: (registry: IWorkbookIO.Registry) => Promise<void> | void;
+    }
+}
+//# sourceMappingURL=IWorkbookIO.d.ts.map