@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.2

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

@@ -16,6 +16,28 @@ export declare abstract class AbstractBackingStore implements IWorkbookIO.IBacki
     abstract write(request: IWorkbookIO.WriteRequest): Promise<IWorkbookIO.Origin | null>;
     /** @inheritdoc IWorkbookIO.IBackingStore.read */
     read(request: IWorkbookIO.ReadRequest): Promise<IWorkbook | null>;
+    /**
+     * The origin of an open workbook that saves back to the file being read, or `null`.
+     *
+     * @remarks
+     * Whether two sources are the same file is store knowledge — two stores never share a file. The
+     * base compares paths with {@link findOpenPath}; a store whose sources are handles rather than
+     * paths (the browser) overrides this.
+     */
+    protected findOpenOrigin(_acquired: any, info: IWorkbookIO.ReadInfo): Promise<IWorkbookIO.Origin | null>;
+    /**
+     * The origin of an open workbook that saves back to `path`, other than `except`, or `null`. Only a
+     * writable origin counts: a read-only one (a URL, a copy) never writes the file.
+     */
+    protected findOpenPath(path: string, except?: IWorkbookIO.Origin): IWorkbookIO.Origin | null;
+    /** Whether two paths name the same file. Exact by default; a store knows its file system's rules. */
+    protected isSamePath(a: string, b: string): boolean;
+    /**
+     * Reads a writable file handle (for example a browser `FileSystemFileHandle` from an open picker
+     * or a drop) into its `File`, or returns `null` when the source is not one. A source read this way
+     * mints a writable origin. The base implementation recognizes no handles.
+     */
+    protected fileFromHandle(_source: any): Promise<File | null>;
     /**
      * Resolves a source when {@link AbstractBackingStore.read} is called without one — for example
      * a browser open picker. The base implementation resolves nothing.
@@ -23,7 +45,8 @@ export declare abstract class AbstractBackingStore implements IWorkbookIO.IBacki
     protected resolveSource(_request: IWorkbookIO.ReadRequest): Promise<any>;
     /**
      * Hook invoked after a workbook has been read, so a subclass can associate session state with
-     * it (e.g. cache an opened file handle for silent save-back). The base implementation is a no-op.
+     * it (e.g. cache an opened file handle for silent save-back). `source` is the source as acquired —
+     * the handle itself, not the `File` read from it. The base implementation is a no-op.
      */
     protected onWorkbookRead(_workbook: IWorkbook, _source: any): Promise<void>;
     /**

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

@@ -27,7 +27,7 @@ export declare class ArrayBackingStore implements IWorkbookIO.IBackingStore {
      */
     get buffer(): ArrayBufferLike | null;
     /** @inheritdoc IWorkbookIO.IBackingStore.write */
-    write(request: IWorkbookIO.WriteRequest): Promise<IWorkbookIO.Origin>;
+    write(request: IWorkbookIO.WriteRequest): Promise<IWorkbookIO.Origin | null>;
     /** @inheritdoc IWorkbookIO.IBackingStore.read */
     read(request: IWorkbookIO.ReadRequest): Promise<IWorkbook | null>;
 }

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

@@ -0,0 +1,20 @@
+import { IResource } from '../resource';
+import { IEmbeddedPart } from './IEmbeddedPart';
+/**
+ * Reading and writing an {@link IEmbeddedPart} tree, shared by every model that carries one.
+ *
+ * @internal
+ */
+export declare namespace EmbeddedPart {
+    /**
+     * A carried part with its content resolved back to the resource holding it.
+     *
+     * @remarks
+     * A part whose content no longer resolves is carried without it rather than dropped: the markup
+     * that references it is still there, and dropping the part would leave that reference dangling,
+     * which is the one failure this whole subtree exists to prevent.
+     */
+    const fromJSON: (json: IEmbeddedPart.JSON | undefined, fromResourceId?: (resourceId: number) => IResource) => IEmbeddedPart | null;
+    const toJSON: (part: IEmbeddedPart | null, toResourceId?: (resource: IResource) => number | null) => IEmbeddedPart.JSON | null;
+}
+//# sourceMappingURL=EmbeddedPart.d.ts.map

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

@@ -0,0 +1,63 @@
+import { IResource } from '../resource';
+/**
+ * A document part carried on the model, together with the parts its own markup references.
+ *
+ * @remarks
+ * Some of what a spreadsheet contains is not one part but a small tree of them. A chart's markup
+ * names a style definition, a color definition, the shapes drawn on top of it, sometimes a whole
+ * embedded workbook holding its data; a form control names the part describing what kind of control
+ * it is. Each is named by relationship id, so a reference that does not come back makes the
+ * document unreadable rather than merely plainer. The whole subtree is carried rather than an
+ * enumerated few of it, which is what makes that impossible: nothing referenced can be missing,
+ * whether or not this version knows what it was for.
+ *
+ * The same shape describes every level, `id` and `type` being the edge from the part that
+ * references it.
+ */
+export interface IEmbeddedPart {
+    /** The relationship id the referencing markup cites this part by. */
+    id: string;
+    /** The relationship type URI. */
+    type: string;
+    /**
+     * The markup, for a part that has any.
+     *
+     * @remarks
+     * Opaque: held as it was read and replayed unchanged, since what it describes has no model yet.
+     */
+    xml?: string;
+    /** The content, for a part that is not markup — an embedded workbook, an image. */
+    resource?: IResource;
+    /**
+     * The content type.
+     *
+     * @remarks
+     * Carried because it cannot be derived: `style1.xml` and `colors1.xml` are both `.xml` and are
+     * different types, and a reader that gets this wrong is handed a part it cannot interpret.
+     */
+    contentType?: string;
+    /** What the part was called where it was read from, so it can be called that again. */
+    name?: string;
+    /** The parts this one's markup references. */
+    parts?: IEmbeddedPart[];
+}
+/**
+ * {@inheritDoc IEmbeddedPart}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IEmbeddedPart}
+ */
+export declare namespace IEmbeddedPart {
+    /** {@link IEmbeddedPart} as JSON — its content by {@link IResource} id. */
+    interface JSON {
+        id: string;
+        type: string;
+        xml?: string;
+        resId?: number;
+        contentType?: string;
+        name?: string;
+        parts?: JSON[];
+    }
+}
+//# sourceMappingURL=IEmbeddedPart.d.ts.map

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

@@ -2,6 +2,7 @@ import { FetchArgs, Base64Args, ITaskProgress, MaybePromise } from '@sheetxl/uti
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 import { IWorkbook } from '../workbook';
+import { ICellContainerOptions } from '../sheet';
 /**
  * Interface for workbook input/output operations across multiple source types and formats.
  *
@@ -387,6 +388,8 @@ export interface IWorkbookIO extends IListener.ISource<IWorkbookIO, IWorkbookIO.
      * {@link TransactionSaveStateManager} to track a workbook's dirty state with no extra wiring.
      */
     addCommitListener(listener: ITransaction.ICommitSource.IListeners): IListener.Remove;
+    /** For runtime type checking. */
+    readonly isIWorkbookIO: true;
 }
 export declare namespace IWorkbookIO {
     /**
@@ -394,11 +397,13 @@ export declare namespace IWorkbookIO {
      * 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.
+     * Minted and owned by the IO/store layer, never by the workbook model. An origin names **one**
+     * file for its whole life: its path and format never change. What can change in place is what is
+     * known about that file (its size, whether it is encrypted, its display label), firing `onChange`.
+     *
+     * *Which* origin a workbook lives in can change: a save that resolves a new destination (a first
+     * save, a Save As) moves the workbook to a new origin, and the one it left keeps naming its own
+     * file — see {@link IWorkbook.getOrigin}. An origin backs one open workbook at a time.
      *
      * 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
@@ -493,6 +498,16 @@ export declare namespace IWorkbookIO {
          * each read/write of this handle.
          */
         getSize(): number | null;
+        /**
+         * When the file was last modified, in milliseconds since the epoch, or `null` if unknown — a
+         * stat-style property like {@link getSize} (the analog of `File.lastModified`), recorded when
+         * the file is read and updated when it is written.
+         *
+         * @remarks
+         * What the store last saw, not a live check: comparing it with the file's current time is how a
+         * host notices the file changed on disk since it was opened.
+         */
+        getLastModified(): 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").
@@ -522,6 +537,39 @@ export declare namespace IWorkbookIO {
         interface IListeners extends IListener.Callbacks<Origin, Origin.Events> {
         }
     }
+    /**
+     * Supplies a workbook's current {@link IWorkbookIO.Origin} — the file it lives in now.
+     *
+     * @remarks
+     * An origin names one file for its whole life; which file a *workbook* lives in changes when a
+     * save resolves a new destination (a first save, a Save As). The workbook reads its origin
+     * through this and follows `onOriginChange`, so the same workbook moves to the new file while
+     * the origin it held keeps naming the old one.
+     *
+     * Read-only by design: the workbook consumes it and never sets it. Whoever implements it decides
+     * when it moves. The default implementation (`WorkbookOriginProvider`) is moved by the IO layer
+     * after a successful save; a host with its own save flow can pass its own implementation through
+     * `IWorkbook.ConstructorOptions.origin` and move it on {@link IWorkbookIO.Events.onWrite}.
+     */
+    interface OriginProvider extends IListener.ISource<OriginProvider, OriginProvider.IListeners> {
+        /**
+         * The origin the workbook lives in now. Always present; unbound for a never-saved workbook.
+         */
+        getOrigin(): Origin;
+    }
+    namespace OriginProvider {
+        /**
+         * IListener interface for {@link IWorkbookIO.OriginProvider} events.
+         */
+        interface Events {
+            /**
+             * Called when the provider supplies a different origin.
+             */
+            onOriginChange?(source: OriginProvider): void;
+        }
+        interface IListeners extends IListener.Callbacks<OriginProvider, OriginProvider.Events> {
+        }
+    }
     /**
      * Common fields shared by all ambient I/O events.
      */
@@ -532,8 +580,10 @@ export declare namespace IWorkbookIO {
          */
         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.
+         * The {@link IWorkbookIO.Origin} handle the operation actually used — the file read, or the file
+         * written: the workbook's own origin for a plain save, a new one for a save that resolved a
+         * destination (a first save, a Save As), the target for an export. Its format is the one read or
+         * written.
          *
          * @remarks
          * Uniform across read and write, so an ambient listener (e.g. recent-files) can track "the
@@ -776,6 +826,18 @@ export declare namespace IWorkbookIO {
          * If it is set in the createWorkbookOptions it will override this value.
          */
         readonly?: boolean;
+        /**
+         * Open the source as a copy: the workbook gets its own read-only origin for the same path, so it
+         * never saves back over the original — its first save asks where.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * A file is saved back by one open workbook at a time, so opening a file that is already open
+         * gives a copy without asking. Set this to get one regardless. Writing over a file another open
+         * workbook saves back to is refused.
+         */
+        asCopy?: boolean;
         /**
          * Read the workbook for calculation only, trading visual formatting for a faster, lighter read.
          *
@@ -788,6 +850,29 @@ export declare namespace IWorkbookIO {
          * save time and memory.
          */
         calcOnly?: boolean;
+        /**
+         * What loading is allowed to calculate — {@link ICellContainerOptions.calcOnLoad},
+         * with the format handler translating what the FILE says into it.
+         *
+         * @defaultValue `'auto'`
+         *
+         * @remarks
+         * - `'auto'` — cached values are trusted; the load pass evaluates a formula cell with no
+         *   cached value (a repair — Excel always stores one) and refreshes volatiles. Everything is
+         *   recalculated only when Excel would recalculate on open: the file sets `fullCalcOnLoad`,
+         *   or for xlsx its `calcId` is missing or older than the Excel build this library is
+         *   verified against. (What this library writes carries one: the source file's, else that
+         *   build's.) To take the file's values as they are whatever it says — as openpyxl does —
+         *   pass `'none'`; to always recalculate, `'full'`.
+         * - `'full'` — everything is recalculated, whatever the file says.
+         * - `'none'` — the calculation engine is not started. Nothing is compiled or calculated, and
+         *   a save writes values and formulas exactly as they were read — the pure IO pass. The
+         *   first mutation, or an explicit {@link ICalculation.calculate} /
+         *   {@link IWorkbook.whenCalculationReady}, starts the engine.
+         *
+         * An explicit `createWorkbookOptions.calcOnLoad` wins over the translation.
+         */
+        calcOnLoad?: ICellContainerOptions.CalcOnLoad;
         /**
          * Provide options to the workbook constructor.
          */
@@ -857,6 +942,10 @@ export declare namespace IWorkbookIO {
          *
          * Used for type detection when it cannot be inferred from the destination.
          * Examples: 'xlsx', 'csv', 'application/json', 'Excel'
+         *
+         * @remarks
+         * A destination whose extension already names a different format is an error, not an
+         * override: changing a file's type means writing to a new name (see {@link IWorkbookIO.writeAs}).
          */
         format?: string;
         /**
@@ -880,8 +969,72 @@ export declare namespace IWorkbookIO {
         password?: string | null;
         /**
          * Optional progress callback for long running writes.
+         *
+         * @remarks
+         * Its `onWarning` receives each write warning (a feature the format cannot hold) once the format
+         * handler has finished, already deduplicated. It is a log channel; the decision to proceed is
+         * {@link onWarnings}.
          */
         progress?: ITaskProgress<IWorkbookIO.Origin>;
+        /**
+         * Decides whether a write that would lose something goes ahead.
+         *
+         * @remarks
+         * Called at most **once** per write, after the format handler has produced the bytes and before
+         * the store persists them, and only when the handler raised a warning that an earlier write to
+         * the same file did not already let through this session — a repeat save of the same lossy
+         * workbook does not ask again. The event carries every warning, deduplicated, so a host shows
+         * one dialog listing them rather than one per finding.
+         *
+         * Returning `false` cancels the write — {@link IWorkbookIO.write} then resolves to `null`, like
+         * a dismissed save dialog — but only when {@link WriteWarningsEvent.canCancel} is `true`. A
+         * prompted write (a Save As, a first save, a download) always proceeds, because the destination
+         * the user just chose has nothing in it to protect and a browser save picker has already created
+         * the file: an empty file there is worse than a lossy one. The workbook still holds everything
+         * that was not written, so the recovery is to save a copy in a format that can hold it.
+         *
+         * Omitted, every write proceeds and the warnings are reported through `progress.onWarning` only.
+         */
+        onWarnings?: (event: IWorkbookIO.WriteWarningsEvent) => boolean | void | Promise<boolean | void>;
+    }
+    /**
+     * One thing a format handler could not write faithfully.
+     */
+    interface WriteWarning {
+        /**
+         * What was not written, or was written degraded.
+         */
+        message: string;
+        /**
+         * Locates the finding — for xlsx, the path of the package part (`/xl/worksheets/sheet2.xml`).
+         */
+        context?: any;
+    }
+    /**
+     * What {@link WriteOptions.onWarnings} is asked to decide on.
+     */
+    interface WriteWarningsEvent extends IOEvent {
+        /**
+         * Every warning the write raised, deduplicated, in the order they were first raised.
+         */
+        warnings: WriteWarning[];
+        /**
+         * `true` for a save (the workbook will be marked clean), `false` for an export copy.
+         *
+         * @remarks
+         * Not the same as `origin === workbook.getOrigin()`: a save that resolved a new destination (a
+         * first save, a Save As) moves the workbook to `origin` only once the write succeeds.
+         */
+        save: boolean;
+        /**
+         * Whether returning `false` will cancel the write.
+         *
+         * @remarks
+         * `true` only for a silent re-save to a bound, writable destination — the one case where the
+         * bytes would replace a file that may hold what is about to be lost. See
+         * {@link WriteOptions.onWarnings} for why a prompted write cannot be cancelled.
+         */
+        canCancel: boolean;
     }
     /**
      * Options for {@link IWorkbookIO.writeAs} — everything a write takes, plus the one thing only a
@@ -925,8 +1078,8 @@ export declare namespace IWorkbookIO {
         /**
          * Persists the workbook described by the request.
          *
-         * @returns The written {@link IWorkbookIO.Origin} handle (normally `request.origin`, updated
-         *   in place), or `null` if cancelled.
+         * @returns The {@link IWorkbookIO.Origin} actually written — `request.origin` when the store
+         *   persisted to it, a new origin when it resolved a destination — or `null` if cancelled.
          *
          * @remarks
          * Optional. A read-only store omits it; {@link IWorkbookIO.canWrite} then reports `false` and
@@ -953,13 +1106,14 @@ export declare namespace IWorkbookIO {
      * 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}.
+     *   Update its stat state (the written `size`) and return it.
      * - **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`).
+     *   picker in the browser; a suggested name in Node), using {@link suggestedName} for any
+     *   prompt/default, and **mint a new origin** for it — passing that origin to {@link encode} —
+     *   then return the new origin. The request's origin is never changed: it keeps naming its own
+     *   file. For a save, the IO layer then moves the workbook to the origin returned.
+     * - Refuse (throw) a destination another open workbook saves back to — other than this
+     *   workbook's own.
      */
     interface WriteRequest {
         /**
@@ -971,8 +1125,8 @@ export declare namespace IWorkbookIO {
          */
         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.
+         * The destination handle: the workbook's own origin for a save, the target for a Save As or an
+         * export. May be unbound (`getPath()` `null`) — see the store contract above.
          */
         origin: IWorkbookIO.Origin;
         /**
@@ -987,13 +1141,22 @@ export declare namespace IWorkbookIO {
         /**
          * Encodes the workbook to bytes using the resolved format, or an alternate format key.
          *
+         * @param format An alternate format key — the one the user picked, for a resolved destination.
+         * @param origin The origin being written, when the store minted one for a destination it
+         *   resolved. Omitted, it is {@link origin}. The caller's
+         *   {@link WriteOptions.onWarnings | onWarnings} sees this as the destination.
+         *
          * @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.
+         *
+         * @returns The bytes to persist, or `null` when the caller declined the write through
+         *   {@link WriteOptions.onWarnings}. A store that receives `null` persists nothing and returns
+         *   `null` — the same outcome as a dismissed save dialog.
          */
-        encode: (format?: string) => Promise<ArrayBufferLike>;
+        encode: (format?: string, origin?: IWorkbookIO.Origin) => Promise<ArrayBufferLike | null>;
     }
     /**
      * The request passed to {@link IWorkbookIO.IBackingStore.read}.
@@ -1049,6 +1212,10 @@ export declare namespace IWorkbookIO {
          * The source size in bytes, if known.
          */
         size?: number;
+        /**
+         * When the source was last modified, in milliseconds since the epoch, if known.
+         */
+        lastModified?: number;
         /**
          * The detected source type (e.g. `'file'`, `'fetch'`), used for a fallback display name.
          */

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

@@ -68,6 +68,13 @@ export declare class DefaultWorkbookIO implements IWorkbookIO {
     write<T extends IWorkbookIO.WriteOptions = IWorkbookIO.WriteOptions>(workbook: IWorkbook, target?: string | IWorkbookIO.Origin | T, optionsArg?: T): Promise<IWorkbookIO.Origin | null>;
     /** @inheritdoc IWorkbookIO.writeAs */
     writeAs<T extends IWorkbookIO.WriteAsOptions = IWorkbookIO.WriteAsOptions>(workbook: IWorkbook, target: string | IWorkbookIO.Origin, options?: T): Promise<IWorkbookIO.Origin | null>;
+    /**
+     * The one write path. `save` is whether the workbook moves to what is written and is marked
+     * clean (a save, a Save As), or stays where it is (an export).
+     *
+     * @internal
+     */
+    protected _write<T extends IWorkbookIO.WriteOptions = IWorkbookIO.WriteOptions>(workbook: IWorkbook, target: string | IWorkbookIO.Origin, save: boolean, options?: T): Promise<IWorkbookIO.Origin | null>;
     /**
      * Strips a known file extension from a file name, returning the base name.
      *
@@ -83,6 +90,8 @@ export declare class DefaultWorkbookIO implements IWorkbookIO {
     protected _baseName(pathOrUrl: string | null | undefined): string | null;
     protected _writeArrayBuffer<T extends IWorkbookIO.WriteOptions = IWorkbookIO.WriteOptions>(workbook: IWorkbook, writeType: IWorkbookIO.WriteFormatType, options?: T): Promise<ArrayBufferLike>;
     protected _readArrayBuffer<T extends IWorkbookIO.ReadOptions = IWorkbookIO.ReadOptions>(arrayBuffer: ArrayBufferLike, format: IWorkbookIO.ReadFormatType, options?: T): Promise<IWorkbook>;
+    /** {@inheritDoc IWorkbookIO.isIWorkbookIO} */
+    get isIWorkbookIO(): true;
 }
 /**
  * A singleton instance of the default {@link IWorkbookIO} implementation.

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

@@ -17,6 +17,10 @@ export interface WorkbookOriginOptions {
      * The last-known size of the source in bytes (stat-style), if known.
      */
     size?: number | null;
+    /**
+     * When the source was last modified, in milliseconds since the epoch (stat-style), if known.
+     */
+    lastModified?: number | null;
     /**
      * Whether the source can be written back to (a silent re-save).
      *
@@ -34,19 +38,20 @@ export interface WorkbookOriginOptions {
  * concrete "light virtual file handle" (see `IO-DESIGN.md`).
  *
  * @remarks
- * Mutable and observable: the IO/store layer holds the instance and calls {@link update} when the
- * source moves (a save that resolved a destination) or is renamed, firing `onChange` so holders —
- * including the workbook itself, whose `getName()`/`onNameChange` derive from this — propagate it.
+ * Names one file for its whole life. What is known about that file — its size, its encryption, its
+ * display label — can change in place ({@link update}, {@link setName}), firing `onChange` so
+ * holders — including the workbook, whose `getName()`/`onNameChange` derive from this — follow.
  * Source logic (paths, URLs, formats) lives here, in the IO layer, not in the workbook model.
  *
  * An **unbound** origin (`path: null`) belongs to an in-memory workbook with no destination yet; a
- * destination-resolving save fills it in place via {@link update}.
+ * save that resolves one moves the workbook to a new origin, leaving this one as it was.
  */
 export declare class WorkbookOrigin implements IWorkbookIO.Origin {
-    private _path;
+    private readonly _path;
     private _name;
     private _format;
     private _size;
+    private _lastModified;
     private _canWrite;
     private _encryption;
     /**
@@ -85,24 +90,28 @@ export declare class WorkbookOrigin implements IWorkbookIO.Origin {
     getPassword(): string | null;
     /** {@inheritDoc IWorkbookIO.Origin.getSize} */
     getSize(): number | null;
+    /** {@inheritDoc IWorkbookIO.Origin.getLastModified} */
+    getLastModified(): number | null;
     /** {@inheritDoc IWorkbookIO.Origin.canWrite} */
     canWrite(): boolean;
     /** {@inheritDoc IWorkbookIO.Origin.setName} */
     setName(name: string | null): void;
     /**
-     * Update one or more fields in place. Fires `onChange` if anything actually changed.
+     * Update what is known about the file in place. Fires `onChange` if anything actually changed.
      *
      * @remarks
-     * This is the **privileged mutation channel** (see `IO-DESIGN.md`): permitted callers are the
-     * backing store (rename/move, destination resolution), the IO layer (filling an unbound origin on
-     * a first destination-resolving save), and the document layer (Save As / rename). Never format
-     * handlers, never the model, never chrome.
+     * The **privileged mutation channel** (see `DESIGN-IO.md`) for the backing store and the IO layer:
+     * the written size, the encryption on disk, the format key a read resolved. Never format handlers,
+     * never the model, never chrome.
+     *
+     * There is no `path`: an origin names one file for its whole life. A save that resolves another
+     * destination mints a new origin for it (see `DESIGN-IO.md` §11).
      */
     update(next: {
-        path?: string | null;
         name?: string | null;
         format?: string | null;
         size?: number | null;
+        lastModified?: number | null;
         canWrite?: boolean;
         encryption?: string | null;
     }): this;

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

@@ -0,0 +1,46 @@
+import { IListener } from '../listener';
+import { IWorkbookIO } from './IWorkbookIO';
+/**
+ * The provider currently supplying `origin`, or `null` when no open workbook lives in it.
+ *
+ * @remarks
+ * How the IO layer finds the workbook a save was for: it holds the origin it wrote from.
+ */
+export declare const getOriginProvider: (origin: IWorkbookIO.Origin) => WorkbookOriginProvider | null;
+/** The origins of every open workbook. */
+export declare const getOpenOrigins: () => IWorkbookIO.Origin[];
+/**
+ * Default {@link IWorkbookIO.OriginProvider}: holds the workbook's current origin and moves when
+ * told to.
+ *
+ * @remarks
+ * {@link setOrigin} is on this class, not the interface — the workbook only reads its origin. The
+ * IO layer moves it after a save that resolved a new destination.
+ *
+ * An origin is supplied by one provider at a time, so the origin a save wrote from identifies
+ * exactly one workbook. Supplying an origin another open provider already supplies throws.
+ */
+export declare class WorkbookOriginProvider implements IWorkbookIO.OriginProvider {
+    private _origin;
+    private _released;
+    private readonly _emitter;
+    constructor(origin: IWorkbookIO.Origin);
+    /** {@inheritDoc IWorkbookIO.OriginProvider.getOrigin} */
+    getOrigin(): IWorkbookIO.Origin;
+    /**
+     * Supplies `origin` from now on. Fires `onOriginChange` unless it is already the current one.
+     *
+     * @remarks
+     * Moves the workbook to another file; it writes nothing. The origin it replaces is left as it was
+     * — it still names its own file, and is free for another workbook.
+     */
+    setOrigin(origin: IWorkbookIO.Origin): void;
+    /**
+     * Stops supplying: the origin is free for another workbook. Called when the workbook closes.
+     */
+    release(): void;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IWorkbookIO.OriginProvider.IListeners, options?: IListener.Options): IListener.Remove;
+    private static _assertFree;
+}
+//# sourceMappingURL=WorkbookOriginProvider.d.ts.map

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

@@ -0,0 +1,49 @@
+/**
+ * A reader over a captured markup fragment.
+ *
+ * @remarks
+ * Content the model does not hold structurally is kept as the source's markup and replayed on save
+ * (a shape, a chart part). This reads the few facts such markup can answer without a model behind
+ * it. It is a reader over a fragment, not an XML library: elements, attributes and character data,
+ * matched by LOCAL name — prefixes are the producer's choice (`xdr:sp`, `a:t` and `c:ser` are only
+ * Excel's). The markup was already parsed once, as part of a whole document, by the reader that
+ * captured it.
+ */
+/** One element of a parsed fragment. `name` is the local name. */
+export interface XmlElement {
+    name: string;
+    attrs: string;
+    children: (XmlElement | string)[];
+    /** Where the element's content starts in the source: just past its open tag. */
+    contentStart: number;
+    /** Where the element's content ends in the source: at its close tag. Equal to `contentStart` for an empty element. */
+    contentEnd: number;
+}
+export declare const decodeEntities: (text: string) => string;
+/** Character data as it has to be spelled inside an element. */
+export declare const encodeText: (text: string) => string;
+/** The fragment's root element, or `null` when there is none to read. */
+export declare const parseFragment: (xml: string) => XmlElement | null;
+export declare const getAttribute: (element: XmlElement, name: string) => string | null;
+export declare const childElements: (element: XmlElement) => XmlElement[];
+export declare const findChild: (element: XmlElement, name: string) => XmlElement | null;
+/** The element at the end of a path of local names, or `null` where the path breaks. */
+export declare const findPath: (element: XmlElement, ...names: string[]) => XmlElement | null;
+/** The element's own character data; what its child elements hold is not read. */
+export declare const readCharacters: (element: XmlElement) => string;
+/**
+ * The children to read in place of an `mc:AlternateContent`: ONE branch, never both.
+ *
+ * @remarks
+ * A producer states the same content once per consumer version, so a sweep over both branches
+ * reads every word twice. The fallback is the rendition for a reader that does not understand the
+ * choice's markup — which, for the markup that gets wrapped this way (an OMML equation), is this
+ * reader: the fallback carries the equation in its linear text form.
+ */
+export declare const alternateBranch: (element: XmlElement) => XmlElement[];
+/**
+ * The plain text of a DrawingML text body (`txBody`, `c:rich`): its paragraphs joined by a newline,
+ * blank ones trimmed from the ends.
+ */
+export declare const readTextBody: (body: XmlElement) => string;
+//# sourceMappingURL=_XmlFragment.d.ts.map

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

@@ -1,3 +1,4 @@
+export * from './IEmbeddedPart';
 export * from './IWorkbookIO';
 export * from './WorkbookIO';
 export * from './WorkbookOrigin';