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

package/types/src/history/IHistory.d.ts

@@ -22,17 +22,35 @@ export declare namespace IHistory {
      * @template S The type of the source for `getSource``.
      * @template C The type of the coordinates the snapshot is bound to.
      * @template J The type of the JSON for `toJSON`.
+     * @template R What `copyTo` resolves with; the coordinates unless the source has more to report.
      */
-    interface ISnapshot<D = any, S = any, C = any, J = any> {
+    interface ISnapshot<D = any, S = any, C = any, J = any, R = C> {
+        /**
+         * Does the asynchronous work a copy needs, before {@link copyTo} is called.
+         *
+         * @remarks
+         * A copy is made inside the destination's transaction, which must not be held open across an
+         * `await`. Anything that has to wait - loading a kind of content, decoding an image - is done
+         * here, with the destination the copy will be made to, so that `copyTo` can complete
+         * synchronously. A snapshot with nothing to wait for leaves this out, or returns `void`.
+         *
+         * @param destination The destination the snapshot will be copied to.
+         * @param options {@link IHistory.CopyToOptions}
+         */
+        prepare?(destination: D, options?: IHistory.CopyToOptions): Promise<void> | void;
         /**
          * Copies the snapshot to the specified range.
          *
+         * @remarks
+         * The copy is made inside the destination's transaction, so it completes synchronously;
+         * anything that has to wait belongs in {@link prepare}.
+         *
          * @param destination The destination `Snapshot source` where the snapshot will be copied.
          * @param options {@link IHistory.CopyToOptions}
          *
-         * @returns A promise that resolves when the copy is complete, or `void` if no asynchronous operation is required.
+         * @returns The result of the copy.
          */
-        copyTo(destination: D, options?: IHistory.CopyToOptions): Promise<C> | C;
+        copyTo(destination: D, options?: IHistory.CopyToOptions): R;
         /**
          * The source that created the snapshot.
          * This is used to quickly do comparisons.

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

@@ -1,3 +1,4 @@
+import { ITransaction } from '../transaction';
 /**
  * Represents a hyperlink for linking to either a URL or a cell address.
  */
@@ -54,6 +55,10 @@ export interface IHyperlink {
      * otherwise `_blank`.
      */
     getTarget(): string;
+    /**
+     * Removes the link from the cell it is attached to. The cell's text stays.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
     /**
      * For runtime type checking.
      */
@@ -89,10 +94,24 @@ export declare namespace IHyperlink {
         screenTip?: string;
         /** {@inheritDoc IHyperlink.getTarget} */
         target?: string;
+        /**
+         * An action the link performs instead of, or beside, following its address, as a file states
+         * it (`hlinkClick/@action`). Office's own (`ppaction://…`) mean nothing in a workbook; kept so
+         * the file reads back as written.
+         */
+        action?: string;
+        /** Whether following the link adds it to the browsing history (`hlinkClick/@history`). */
+        history?: boolean;
     }
     /**
      * A JSON representation useful for persistence.
      */
-    type JSON = Partial<Omit<IHyperlink.Properties, 'textToDisplay'>> | string;
+    type JSON = (Partial<Omit<IHyperlink.Properties, 'textToDisplay'>> & {
+        /**
+         * The text a file recorded for the link (`hyperlink/@display`). Kept and written back as
+         * read; what shows is the cell's own text.
+         */
+        display?: string;
+    }) | string;
 }
 //# sourceMappingURL=IHyperlink.d.ts.map

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

@@ -1,4 +1,5 @@
 import { ITypes } from '../type';
+import { ITransaction } from '../transaction';
 import { IHyperlink } from './IHyperlink';
 /**
  * `true` for an address the browser hands to another application (`mailto:`, `tel:`, `sms:`)
@@ -10,7 +11,10 @@ export declare class Hyperlink implements IHyperlink {
     protected _t: () => string;
     protected _p: IHyperlink.Properties;
     protected _r: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>;
-    constructor(textToDisplay: () => string, resolver: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>, json: IHyperlink.JSON);
+    protected _d: ((options?: ITransaction.OperationOptions) => void) | undefined;
+    constructor(textToDisplay: () => string, resolver: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>, json: IHyperlink.JSON, remover?: (options?: ITransaction.OperationOptions) => void);
+    /** {@inheritDoc IHyperlink.delete} */
+    delete(options?: ITransaction.OperationOptions): void;
     /** {@inheritDoc IHyperlink.open} */
     open(target?: '_self' | '_blank', features?: string): Promise<boolean>;
     /** {@inheritDoc IHyperlink.getTarget} */

package/types/src/i18n/LanguagePack.d.ts

@@ -1,5 +1,5 @@
 import { FormulaError } from '@sheetxl/primitives';
-import { MinifiedDescriptor } from '@sheetxl/scripting';
+import { MinifiedDescriptor, MinifiedEnumDescriptors } from '@sheetxl/scripting';
 import { LanguagePack as BaseLanguagePack, LanguageTag } from '@sheetxl/utils';
 /**
  * The **spreadsheet-language plane** of a language pack (I18N-DESIGN.md Plane 3): function names,
@@ -56,10 +56,18 @@ export interface LanguagePack extends BaseLanguagePack {
      * descriptor. Values are {@link MinifiedDescriptor}s — the SAME shape the built-in
      * descriptor modules compile to, so a generated per-locale module IS a pack chunk with
      * no reshaping; `initializeFunctions` overlays it per-field over the built-in English.
+     *
+     * The module form may also carry `enums` — the copy for enum parameters, again the shape the
+     * descriptor modules compile to. A key is an enum id (`MatchMode`), which serves every function
+     * that declares an enum of that name, or `FUNCTION:EnumId` (`TEXTAFTER:MatchMode`) for the one
+     * function where the same name means something else. The qualified entry wins, per field.
      */
-    functionHelp?: () => Promise<Record<string, MinifiedDescriptor> | {
-        default: Record<string, MinifiedDescriptor>;
-    }>;
+    functionHelp?: () => Promise<Record<string, MinifiedDescriptor> | FunctionHelpModule>;
+}
+/** The module form of a {@link LanguagePack.functionHelp} chunk. */
+export interface FunctionHelpModule {
+    default: Record<string, MinifiedDescriptor>;
+    enums?: MinifiedEnumDescriptors;
 }
 /**
  * The active (or `tag`'s) spreadsheet-language pack — the MERGE of every contributor's plane: the

package/types/src/index.d.ts

@@ -22,15 +22,21 @@ export * from './text';
 export * from './condition';
 export * from './sort';
 export * from './filter';
+export * from './person';
 export * from './comment';
 export * from './hyperlink';
 export * from './numFmt';
 export * from './style';
 export * from './resource';
 export * from './string';
+export * from './richData';
 export * from './anchored';
 export * from './chart';
+export * from './pivot';
+export * from './dataTable';
 export * from './picture';
+export * from './shape';
+export * from './group';
 export * from './scripting';
 export * from './calculation';
 export * from './address';
@@ -50,12 +56,14 @@ export * from './table';
 export { Table } from './table/Table';
 export * from './theme';
 export * from './sheet';
+export * from './outline';
 export * from './sheetHeader';
 export * from './sheetProtection';
 export * from './sheetView';
 export * from './workbook';
 export * from './workbookProtection';
 export * from './workbookView';
+export * from './documentProperties';
 /**
  * The current version of the SDK.
  * @hidden

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.