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

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

@@ -1,36 +1,169 @@
+import { IRange } from '@sheetxl/primitives';
+import { AbstractCollection } from '../type';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { ICellRange } from '../cellRange';
 import { IExternalBook } from './IExternalBook';
 import { IExternalBookCollection } from './IExternalBookCollection';
 /**
- * Implementation for {@link IExternalBookCollection}.
+ * A single cached snapshot of another workbook — the read-only view over one {@link IExternalBook.JSON}.
  */
-export declare class ExternalBookCollection implements IExternalBookCollection {
+declare class ExternalBook implements IExternalBook {
+    private _json;
+    private _id;
+    /** The owner, for the `[n]` projection — a book's position is the collection's fact, not its own. */
+    private _collection;
+    constructor(json: IExternalBook.JSON, id: string, collection: ExternalBookCollection);
+    getId(): string;
+    getDisplayName(sheetName?: string | null): string;
+    getSources(): readonly IExternalBook.SourceEntry[];
+    getSheetNames(): readonly string[];
+    getDefinedNames(): readonly IExternalBook.DefinedNameEntry[];
+    getSheetData(sheetIndex: number): IExternalBook.SheetData | null;
+    getDependents(): readonly IRange.Coords[];
+    delete(txOptions?: ITransaction.OperationOptions): void;
+    breakLink(txOptions?: ITransaction.OperationOptions): void;
+    refresh(): Promise<IExternalBook.RefreshResult>;
+    toJSON(): IExternalBook.JSON | null;
+    /** A copy holding a source's current contents in place of the cache; the sources stay. */
+    _withSnapshot(snapshot: IExternalBook.Snapshot): ExternalBook;
+    /** A copy with every cached sheet marked `refreshError` — the values themselves untouched. */
+    _withRefreshError(): ExternalBook;
+    /** A copy with one more sheet name — the book is immutable; the collection swaps it. */
+    _withSheetName(sheetName: string): ExternalBook;
+    readonly isIExternalBook: true;
+}
+interface State {
     /**
-     * Positional, `[n]`-indexed (`_items[0]` is `[1]`) — `null` at a position is a DDE/OLE link or
+     * Positional, `[n]`-indexed (`items[0]` is `[1]`) — `null` at a position is a DDE/OLE link or
      * otherwise unmodeled. Gaps carry meaning (the position still counts), so this is never compacted.
      */
-    private _items;
+    items: readonly (ExternalBook | null)[];
+    /**
+     * Runtime ids, parallel to {@link items} and one per POSITION — a `null` DDE/OLE slot gets one
+     * too, so a formula citing it keeps its place when a book in front of it is removed.
+     */
+    ids: readonly string[];
+}
+/**
+ * Implementation for {@link IExternalBookCollection}.
+ *
+ * @remarks
+ * The positional list lives in the transaction store rather than in fields, so `add`, `delete` and
+ * `breakLink` undo — and an undo brings a slot's id back with it, which is what heals the formulas
+ * that kept citing it (see {@link _remove}).
+ */
+export declare class ExternalBookCollection extends AbstractCollection<IExternalBook> implements IExternalBookCollection {
+    protected _transactions: ITransaction.IStore;
+    private _stateId;
+    private _transactionsRemoveListener;
+    private _getDependentsById;
+    private _getSheetRange;
+    private readonly _resolver;
     constructor(options?: ExternalBookCollection.ConstructorOptions);
-    [Symbol.iterator](): IterableIterator<IExternalBook>;
-    /** Only the modeled books — gaps (DDE/OLE) are omitted, not positional. Use {@link getByIndex} for `[n]` lookup. */
-    getItems(): IExternalBook[];
-    getCount(): number;
-    getByIndex(n: number): IExternalBook | null;
+    /**
+     * @internal
+     * The runtime id at `[n]` (1-based), including a DDE/OLE gap's, or `null` if there is no such
+     * position. `[n]` is where the SOURCE FILE stores a book — it renumbers when another is broken,
+     * and no surface a reader sees spells one — so this and its inverse are the compiler's, for
+     * parsing a typed `[7]` and for imaging an id back into canonical text. Not on
+     * {@link IExternalBookCollection}: a consumer wanting one book wants `getById`.
+     */
+    _getIdByIndex(n: number): string | null;
+    /**
+     * @internal
+     * The 1-based `[n]` a runtime id currently sits at, or `-1` — the inverse of
+     * {@link _getIdByIndex}. Linear: a workbook has a handful of books.
+     */
+    _getIndexById(id: string): number;
+    getById(id: string): IExternalBook | null;
+    /** Only the modeled books — gaps (DDE/OLE) are omitted, not positional. */
+    protected _getItems(): IExternalBook[];
+    /**
+     * @internal
+     * The book at `[n]` (1-based), or `null` where `n` is past the end or holds a DDE/OLE gap.
+     * Slot-numbered, so it is the compiler's and the tests' — not on
+     * {@link IExternalBookCollection}, where `at()` gives position among the books that exist and
+     * `toJSON()` gives the slots with their gaps.
+     */
+    _getByIndex(n: number): IExternalBook | null;
+    /** {@inheritDoc IExternalBookCollection.add} */
+    add(options: IExternalBookCollection.AddOptions, txOptions?: ITransaction.OperationOptions): IExternalBook;
+    /**
+     * @internal
+     * {@link IExternalBook.delete} — the book delegates here, where the state lives. Takes an id
+     * rather than a book so a DDE/OLE gap, which has no book object, can go too.
+     *
+     * @returns `false` if nothing was at that id.
+     */
+    _remove(id: string, txOptions?: ITransaction.OperationOptions): boolean;
+    /** @internal {@link IExternalBook.breakLink} — the book delegates here, where the state lives. */
+    _breakLink(id: string, txOptions?: ITransaction.OperationOptions): boolean;
+    /** {@inheritDoc IExternalBookCollection.breakAll} */
+    breakAll(txOptions?: ITransaction.OperationOptions): number;
+    /** {@inheritDoc IExternalBookCollection.refreshAll} */
+    refreshAll(): Promise<IExternalBook.RefreshResult[]>;
+    /**
+     * @internal
+     * {@link IExternalBook.refresh}: the resolver is asked, and its answer replaces the book's cache
+     * in one transaction — the engine rebuilds the book's grids from it on the change notification.
+     */
+    _refresh(bookId: string): Promise<IExternalBook.RefreshResult>;
+    /** Excel's record of a refresh that could not complete: `refreshError` on each cached sheet. */
+    protected _markRefreshError(bookId: string): void;
+    /**
+     * The value pass in front of a removal: every cell block that cites the book becomes its current
+     * values — the WHOLE formula, as Excel does, not only the external operand.
+     *
+     * @remarks
+     * A dependent that is a NAME (its scope is the name's virtual grid, not a sheet) is left as it
+     * is. Its citation then images as `#REF!` once the slot goes, which is one of the three outcomes
+     * DESIGN-EXTERNAL-LINKS §6 item 8 lists for Excel; the measurement that picks between them has
+     * not been taken, and a name has no computed value to write back until phase D in any case.
+     */
+    protected _breakDependents(book: IExternalBook): void;
+    /** @internal Backs {@link IExternalBook.getDependents}; empty without an engine to ask. */
+    _getDependents(bookId: string): readonly IRange.Coords[];
+    /**
+     * @internal
+     * Records a sheet name a formula cited on a book that did not list it — the authoring half of
+     * the bind rule (DESIGN-EXTERNAL-LINKS §5 step 13). Returns the sheet's index in the book.
+     */
+    _addSheetName(bookId: string, sheetName: string): number;
     toJSON(): (IExternalBook.JSON | null)[] | null;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IExternalBookCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    close(): void;
+    protected _assertWritable(): void;
+    protected _getState(): State;
+    protected _beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
+    protected _updateState(state: (prevState: State) => State, options: ITransaction.OperationOptions): void;
     readonly isIExternalBookCollection: true;
 }
 export declare namespace ExternalBookCollection {
     interface ConstructorOptions {
         /**
          * Books to hydrate at construction, in `IWorkbook.JSON.externalBooks` order — which IS `[n]`
-         * order (1-based). A `null` entry is a preserved gap (see {@link IExternalBookCollection.getByIndex}).
+         * order (1-based). A `null` entry is a preserved gap.
          *
          * @remarks
          * Taken here rather than through a separate `fromJSON()` call — mirrors
          * `NamedFormulaCollection`'s reasoning: this collection owns the items, so hydrating at
-         * construction avoids a pre-load lifecycle state. Unlike named formulas, nothing here is
-         * mutable yet, so there is no transactional persist scope to speak of either.
+         * construction avoids a pre-load lifecycle state.
          */
         json?: (IExternalBook.JSON | null)[];
+        /** Shared with the workbook so `add`/`delete`/`breakLink` undo with everything else. */
+        transactions?: ITransaction.IStore;
+        /** The engine's citation index — backs {@link IExternalBook.getDependents}. */
+        getDependents?: (bookId: string) => readonly IRange.Coords[];
+        /** Opens a source on refresh — `ICellContainerOptions.externalBookResolver`, for the collection's life. */
+        resolver?: IExternalBook.IResolver | null;
+        /**
+         * A range over a dependent's coords, whose `scope` is a sheet's stable id — or `null` for a
+         * scope that is not a sheet (a name's virtual grid). Backs the value pass of `breakLink`.
+         */
+        getSheetRange?: (coords: IRange.Coords) => ICellRange | null;
     }
 }
+export {};
 //# sourceMappingURL=ExternalBookCollection.d.ts.map

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

@@ -0,0 +1,96 @@
+import { IExternalBook } from './IExternalBook';
+/**
+ * The two halves of a scope that names an external book: how the book was written, and the sheet
+ * (if any) after it.
+ *
+ * @remarks
+ * `[1]Sheet1` -> `{ book: '1', positional: true, sheetName: 'Sheet1' }`
+ * `[1]`       -> `{ book: '1', positional: true, sheetName: null }` — the `[1]!Name` form
+ * `[Budget.xlsx]Sheet1`        -> `{ book: 'Budget.xlsx', positional: false, ... }`
+ * `C:\d\[Budget.xlsx]Sheet1`   -> `{ book: 'Budget.xlsx', dir: 'C:\d\', positional: false, ... }`
+ */
+export interface ExternalScopeParts {
+    /** The text inside the brackets — a position (`1`) or a file name (`Budget.xlsx`). */
+    book: string;
+    /** Whether {@link book} is a `[n]` position rather than a file name. */
+    positional: boolean;
+    /** Anything before the `[`, kept verbatim — a directory or URL prefix, `''` when there is none. */
+    dir: string;
+    /** The sheet after the `]`, or `null` for the book-scoped `[1]!Name` form. */
+    sheetName: string | null;
+}
+/**
+ * Splits a sheet scope that carries an external book prefix, or `null` if it carries none.
+ *
+ * @remarks
+ * Quotes are the caller's problem: the scope reaching here has already been unquoted by the parser
+ * (`'[1]P3.1'!` and `[1]P3.1!` both arrive as `[1]P3.1`), which is the whole reason a book and its
+ * sheet are ONE symbol rather than two.
+ */
+export declare function parseExternalScope(scope: string): ExternalScopeParts | null;
+/**
+ * The name Excel writes INSIDE the brackets — `Budget.xlsx` in `[Budget.xlsx]Sheet1`: the last
+ * segment of the book's first source, URL-decoded.
+ *
+ * @remarks
+ * A free function rather than a member of {@link IExternalBook}, deliberately. It is a projection of
+ * `getSources()`, and "the file's name" is already `IWorkbookIO.Origin`'s vocabulary, where
+ * `getName()` is the name WITHOUT its extension and `getExtension()` is separate. A second,
+ * conflicting spelling of that noun on a neighbouring interface is how the two get confused.
+ *
+ * The `book` role entry is the path the source is opened from and is sorted first by the reader, so
+ * the first entry is the one to read. An `xlPathMissing` target is a bare name rather than a URI and
+ * has no separator to split on, which this handles by finding none.
+ */
+export declare function externalBookFileName(book: IExternalBook): string;
+/**
+ * Excel's source-CLOSED spelling of a scope into this book: `C:\dir\[Book.xlsx]Sheet1`, unquoted.
+ *
+ * @remarks
+ * This is the form Excel's own formula bar shows for a book it cannot see, which is the state every
+ * book is in until a resolver opens one (DESIGN-EXTERNAL-LINKS §4B). The caller quotes it —
+ * `sheetNameToString` does, since a path carries separators no sheet name may.
+ *
+ * The directory is the first source that carries one: a book Excel recorded by a RELATIVE path
+ * (`NamesSource.xlsx`, a sibling of the host) keeps its absolute location in the xxl21
+ * `alternateUrls` companion, and Excel's formula bar shows that location, not the bare name — a
+ * bare name is the OPEN spelling ({@link externalBookOpenName}).
+ *
+ * @param sheetName Omitted for the book-scoped `[1]!Name` form, which shows as `C:\dir\[Book.xlsx]`.
+ */
+export declare function externalBookClosedName(book: IExternalBook, sheetName?: string | null): string;
+/**
+ * The relationship type a book's own part records for the path it is opened from — what
+ * {@link sourceEntryFromPath} writes, and what the xlsx reader finds on nearly every book.
+ */
+export declare const EXTERNAL_LINK_PATH_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/externalLinkPath";
+/**
+ * The source entry Excel would record for a path a user typed — the inverse of
+ * {@link externalBookClosedName}'s directory half, so a minted book displays back as it was typed.
+ *
+ * @remarks
+ * A Windows path becomes a `file:///` URI with forward slashes and percent-encoding, a UNC path a
+ * `file://server/share/…` one, and a URL or a bare relative name is kept verbatim — the three
+ * target shapes measured in the corpus (DESIGN-EXTERNAL-LINKS §2.2).
+ */
+export declare function sourceEntryFromPath(path: string): IExternalBook.SourceEntry;
+/**
+ * WHERE the source file is, as a path a reader can act on: `C:\dir\Book.xlsx`,
+ * `\server\share\Book.xlsx`, `https://host/Book.xlsx`. `null` when no source carries a
+ * location at all.
+ *
+ * @remarks
+ * NOT {@link externalBookClosedName}, which is a formula SPELLING (bracketed, and about the book's
+ * own recorded path). This answers the different question a links pane asks — "which file is
+ * this?" — and so it skips a source that records only a bare name: an `xlPathMissing` rel, or a
+ * relative `book` path whose absolute companion (the xxl21 `alternateUrls` extension) is the entry
+ * that actually locates the file. Sources are searched in order, so the book's own path still wins
+ * whenever it carries a directory.
+ */
+export declare function externalBookLocation(book: IExternalBook): string | null;
+/**
+ * Excel's source-OPEN spelling: `[Book.xlsx]Sheet1`. Used once a resolver holds the book, and as
+ * the form a user may type in either state.
+ */
+export declare function externalBookOpenName(book: IExternalBook, sheetName?: string | null): string;
+//# sourceMappingURL=ExternalBookName.d.ts.map

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

@@ -1,24 +1,50 @@
+import { IRange } from '@sheetxl/primitives';
 import { Tuple } from '../collections';
 import { ICell } from '../cell';
+import { ITransaction } from '../transaction';
 /**
  * A cached snapshot of another workbook, referenced from a formula as `[n]Sheet1!$A$1`.
  *
  * @remarks
- * Excel's external link is not a live reference — it is the cache plus enough identity to go
- * re-fetch the source. See the design doc for the full model:
+ * Excel's external link is not a live reference — it is the cache plus enough to go re-fetch the
+ * source. See the design doc for the full model:
  * `private-assets/design/calc/DESIGN-EXTERNAL-LINKS.md`.
  *
- * Read-only. There is no `setPath`/`breakLinks` here yet — authoring lands with the resolver API
- * (design doc §4C), not this phase.
+ * Two members read as "which book is this", and they answer different questions:
+ *
+ * | member | answers | persisted | unique |
+ * | --- | --- | --- | --- |
+ * | {@link getSources} | WHERE the source file is | yes, in the file | **no** — two books can both be `Budget.xlsx` |
+ * | {@link getId} | WHICH book this is, to us | no, minted per load | yes |
+ *
+ * They cannot collapse into one: a path cannot be the key, because two books may share one — hence
+ * a runtime id that is not one. {@link getDisplayName} is a projection of {@link getSources}, not a
+ * third identity.
+ *
+ * A book has no position member. The `n` in `[n]` is where the SOURCE FILE stores this book in its
+ * list, it renumbers when another book is removed, and no surface the reader sees spells one — so
+ * it belongs to {@link IExternalBookCollection}, which is what orders them, and not to the book.
+ *
+ * A book is immutable. Adding, removing and breaking one are the collection's operations
+ * ({@link IExternalBookCollection}); what a book itself answers beyond its snapshot is
+ * {@link getDependents} — which formulas cite it.
  */
 export interface IExternalBook {
     /**
-     * The book's identity, as read from its part's own relationships — an ORDERED list, not a single
-     * path with optional alternates. A book can carry several of these at once (`externalLinkPath`,
-     * `xlExternalLinkPath/xlPathMissing`, `externalLinkLongPath`, and the xxl21 `alternateUrls`
-     * extension are all instances of this one shape).
+     * Where the source workbook is — read from this book's own part relationships.
+     *
+     * @remarks
+     * An ORDERED list, not one path with optional alternates: a book can carry several at once
+     * (`externalLinkPath`, `xlExternalLinkPath/xlPathMissing`, `externalLinkLongPath` and the xxl21
+     * `alternateUrls` extension are all instances of this one shape), and the entry the book is opened
+     * from is sorted first. A LOCATION, never a key — two books can both be `Budget.xlsx`, which is
+     * exactly why {@link getId} exists.
+     *
+     * Deliberately NOT an {@link IWorkbookIO.Origin}: an origin is a live, listenable handle the IO
+     * layer owns and can write back to, and this is a dead `(relType, target)` pair the source file
+     * recorded. Turning one into the other is what a phase-E locator does.
      */
-    getIdentity(): readonly IExternalBook.IdentityEntry[];
+    getSources(): readonly IExternalBook.SourceEntry[];
     /**
      * The source book's sheet names, in its own order — the ONLY names the book is known by.
      *
@@ -28,23 +54,94 @@ export interface IExternalBook {
      */
     getSheetNames(): readonly string[];
     /**
-     * The source book's own defined names, as seen at cache time — raw, uncompiled text.
+     * The source book's own defined names, as seen at cache time — raw text, as the part spells it.
      *
      * @remarks
-     * Parsing `refersTo` into something evaluable is phase 2/3's job (design doc §5). Kept verbatim
-     * here so nothing is lost between read and then.
+     * `refersTo` is what Excel cached: a leading `=` and quoted sheet names of the SOURCE
+     * (`='Data Sheet'!$B$2`), `#REF!` for a name that held an expression rather than a reference, and
+     * never a `sheetId` — Excel flattens a sheet-scoped source name into the book's namespace. Kept
+     * verbatim; the engine compiles it inside the book (`[1]!Name` computes from the cache).
      */
     getDefinedNames(): readonly IExternalBook.DefinedNameEntry[];
     /**
      * The cached cell values for one of the book's sheets, or `null` if that sheet was never cached.
      *
      * @remarks
-     * **Sparse, and uncached is not the same as empty.** Values only — no format, no style, no
-     * comment; a cached date is a plain serial (design doc §2.5).
+     * **Sparse.** A cell the cache does not hold — and a sheet it holds nothing for — reads as a
+     * BLANK cell, which is what Excel computes with the source closed (design doc §6 items 1/2).
+     * Values only — no format, no style, no comment; a cached date is a plain serial (§2.5).
      *
      * @param sheetIndex Position in {@link getSheetNames}, matching the XML's `sheetId` (0-based).
      */
     getSheetData(sheetIndex: number): IExternalBook.SheetData | null;
+    /**
+     * Which book this is, to us — stable for the life of the workbook and **never persisted**.
+     *
+     * @remarks
+     * `[n]` is a POSITION, not a key: removing a book renumbers every citation after it. So a compiled
+     * formula stores this id, and the `[n]` is projected from the collection's ordering
+     * (the collection's ordering) whenever canonical text is produced. Same arrangement
+     * `NamedFormulaCollection` uses for a named formula. Minted at
+     * construction; a `.sxl` round trip mints new ones.
+     */
+    getId(): string;
+    /**
+     * How a scope into this book SPELLS, unquoted — Excel's source-closed form
+     * (`C:\dir\[Budget.xlsx]Sheet1`) while the book is closed, its source-open form
+     * (`[Budget.xlsx]Sheet1`) once a resolver holds it.
+     *
+     * @remarks
+     * A readout of the book's state, not a preference — see DESIGN-EXTERNAL-LINKS §4B. Until phase E
+     * there is no resolver, so this is always the closed form. The caller quotes it.
+     *
+     * @param sheetName Omitted for the book-scoped `[1]!Name` form.
+     */
+    getDisplayName(sheetName?: string | null): string;
+    /**
+     * Every formula block that cites this book — directly, through a sheet of it, or as `[n]!Name`.
+     *
+     * @remarks
+     * Derived from the compiled formulas, never stored: the same index a defined name's dependents
+     * come from, so it is exact and current after any edit. A block on a sheet has that sheet's
+     * stable id as its `scope`; a block whose `scope` is a defined name's id is that name's body,
+     * which cites the book on behalf of everything that uses the name. A block citing the book
+     * through two sheets is listed once.
+     *
+     * Empty until the calculation engine has compiled the workbook's formulas.
+     */
+    getDependents(): readonly IRange.Coords[];
+    /**
+     * Removes this book, renumbering every later `[n]`. One undoable step.
+     *
+     * @remarks
+     * A formula still citing the book is NOT rewritten: it keeps the slot's id, images as `#REF!`
+     * and computes `#REF!` — so an undo, which brings the slot and its id back, heals it. To turn
+     * citations into values first, as Excel's Break Links does, use {@link breakLink}. A book that
+     * is already gone is left alone.
+     */
+    delete(txOptions?: ITransaction.OperationOptions): void;
+    /**
+     * Excel's Break Link: every cell formula that cites this book becomes its current values (the
+     * whole formula, not only the external operand), then the book is removed. One undoable step.
+     *
+     * @remarks
+     * A defined name that cites the book is left as it is and images as `#REF!` afterwards.
+     * {@link IExternalBookCollection.breakAll} is this for every book. A book that is already gone
+     * is left alone.
+     */
+    breakLink(txOptions?: ITransaction.OperationOptions): void;
+    /**
+     * Re-reads this book from its source and replaces the cache — Excel's Refresh on a row of the
+     * Workbook Links pane.
+     *
+     * @remarks
+     * Needs a resolver (`ICellContainerOptions.externalBookResolver`, given when the workbook is
+     * built); without one every book is `'unavailable'` and nothing changes, which is the state a
+     * workbook is in until a host supplies one (DESIGN-EXTERNAL-LINKS §4D). A replaced cache is one undoable step, and every formula
+     * citing the book reads the new values. A resolver that throws leaves the cache as it was and
+     * marks each cached sheet `refreshError`, as Excel records a refresh it could not complete.
+     */
+    refresh(): Promise<IExternalBook.RefreshResult>;
     /**
      * For runtime type checking.
      */
@@ -53,7 +150,8 @@ export interface IExternalBook {
 }
 export declare namespace IExternalBook {
     /**
-     * One `(relTypeUri, target)` pair from the book part's own relationships.
+     * One `(relTypeUri, target)` pair from the book part's own relationships — one place the source
+     * workbook may be found.
      *
      * @remarks
      * `type` is the full relationship-type URI (not a shorthand) — it is what tells apart an
@@ -61,9 +159,20 @@ export declare namespace IExternalBook {
      * `externalLinkLongPath`, and an xxl21 `alternateUrls` entry. Emitting one under a hard-coded rel
      * type would silently rewrite what the source file said.
      */
-    interface IdentityEntry {
+    interface SourceEntry {
         type: string;
         target: string;
+        /**
+         * How the book's own XML refers to this entry, when it refers to it at all: `book` is the path
+         * the book is opened from, `absoluteUrl` its 2021 cloud-URL companion.
+         *
+         * @remarks
+         * Not derivable from {@link type} — the two can carry the SAME relationship type (measured on
+         * task 40234, where a relative and an absolute `externalLinkPath` sit on one part). Absent for
+         * an entry nothing points at, which is a real shape too: an `xlPathMissing` or
+         * `externalLinkLongPath` rel rides along on the part without being referenced from it.
+         */
+        role?: 'book' | 'absoluteUrl';
     }
     interface DefinedNameEntry {
         name: string;
@@ -72,6 +181,45 @@ export declare namespace IExternalBook {
         /** Position in {@link IExternalBook.getSheetNames}, when the name is sheet-scoped. */
         sheetIndex?: number;
     }
+    /**
+     * A source book's current contents, as a resolver answers them — the cache that replaces the
+     * book's. The same three parts the file caches; the book's sources are not part of it.
+     */
+    interface Snapshot {
+        sheetNames: readonly string[];
+        definedNames?: readonly DefinedNameEntry[];
+        /** One entry per sheet the source holds values for; a sheet absent here reads blank. */
+        sheetDataSet?: readonly SheetData[];
+    }
+    /** What one {@link IExternalBook.refresh} came to. */
+    interface RefreshResult {
+        bookId: string;
+        /**
+         * `'refreshed'` — the cache was replaced from the source. `'unavailable'` — nothing could open
+         * the source: no resolver is installed, or the resolver declined this book; the cache stands.
+         * `'failed'` — the resolver threw; the cache stands and its sheets are marked `refreshError`.
+         */
+        status: 'refreshed' | 'unavailable' | 'failed';
+        /** For `'failed'`: what went wrong. */
+        error?: string;
+    }
+    /**
+     * Opens a book's source and answers its current contents, or declines.
+     *
+     * @remarks
+     * DESIGN-EXTERNAL-LINKS §4D: the default one (phase E) is `WorkbookIO.read` with
+     * `calcOnLoad: 'none'`, taking the source's own cached values and never evaluating it — that is
+     * what Excel's cache holds, and it keeps A-cites-B-cites-C from becoming a crawl. An extension
+     * point for a source that is not a workbook file. WHETHER a source may be opened at all — an
+     * untrusted file naming an arbitrary path or URL — is the host's decision, made before this is
+     * asked; a resolver never fetches on its own initiative, only on {@link IExternalBook.refresh}.
+     */
+    interface IResolver {
+        /** The name to show for a book, overriding its own spelling. Sync, fetches nothing. */
+        displayName?(book: IExternalBook): string | null;
+        /** The source's current contents, or `null` to decline (the cache stands). */
+        resolve(book: IExternalBook): Promise<Snapshot | null>;
+    }
     interface SheetData {
         /** Position in {@link IExternalBook.getSheetNames} this cache belongs to — the XML's `sheetId`, 0-based. */
         sheetIndex: number;
@@ -85,10 +233,14 @@ export declare namespace IExternalBook {
         data: Tuple.GridTuple<ICell.JSON>;
     }
     interface JSON {
-        identity: IdentityEntry[];
+        /**
+         * Absent between the link visitor and `XLSXReader`: a visitor never sees its own part's sibling
+         * `.rels` file, so the reader attaches these afterwards. `getSources()` reads it as empty.
+         */
+        sources?: SourceEntry[];
         sheetNames: string[];
         definedNames?: DefinedNameEntry[];
-        /** One entry per CACHED sheet, not per sheet — a sheet absent here was never cached (not empty). */
+        /** One entry per CACHED sheet, not per sheet — a sheet absent here was never cached, and reads blank. */
         sheetDataSet?: SheetData[];
         /** `mc:Ignorable="x14 xxl21"` was present on the part root — preserved so a future writer round-trips it. */
         mceIgnorable?: boolean;

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

@@ -1,20 +1,47 @@
 import { ICollection } from '../type';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
 import { IExternalBook } from './IExternalBook';
 /**
  * The workbook's external books, in `[n]` order.
  *
  * @remarks
- * **Positional, not an identity — see {@link IExternalBook}.** `[n]` in a formula is this
- * collection's index at read time; nothing in the source file names a book any other way. Read-only
- * for now: there is no `add`/`remove` here yet, matching the design doc's phase 1 scope (authoring
- * arrives with the resolver API in a later phase).
+ * **Positional, not a key — see {@link IExternalBook}.** `[n]` in a formula is this
+ * collection's index at read time; nothing in the source file names a book any other way.
+ *
+ * A link is created by a formula and removed by breaking it — Excel's model, and ours. Typing
+ * `'C:\path\[Budget.xlsx]Sheet1'!A1` into a cell adds a book here with an empty cache; {@link add}
+ * is the same step without the formula. {@link IExternalBook.breakLink} is what Excel's Workbook
+ * Links pane does: every citing formula becomes its values, then the slot goes.
  */
 export interface IExternalBookCollection extends ICollection<IExternalBook> {
     /**
-     * The book that formula text `[n]` (1-based) addresses, or `null` if `n` is beyond what was
-     * preserved on read, or its position is a DDE/OLE link (unmodeled — see {@link getItems}).
+     * The book carrying a runtime id, or `null` — for an unknown id and for a DDE/OLE gap alike,
+     * since a gap has an id but no book.
+     */
+    getById(id: string): IExternalBook | null;
+    /**
+     * Adds a book at the end — the next `[n]` — with an empty cache.
+     *
+     * @remarks
+     * This is the state Excel is in when it cannot find a link's source: the file round-trips, and
+     * Excel opens it and offers to update. Undoable.
+     *
+     * @param options Where the source is and, optionally, which sheets it has.
+     */
+    add(options: IExternalBookCollection.AddOptions, txOptions?: ITransaction.OperationOptions): IExternalBook;
+    /**
+     * {@link IExternalBook.breakLink} for every book, in one undoable step — the pane's Break all.
+     *
+     * @returns How many books were broken. Gaps stay: a DDE/OLE slot has nothing to value.
+     */
+    breakAll(txOptions?: ITransaction.OperationOptions): number;
+    /**
+     * {@link IExternalBook.refresh} for every book, in order — the pane's Refresh all.
+     *
+     * @returns One result per book. Without a resolver every one is `'unavailable'`.
      */
-    getByIndex(n: number): IExternalBook | null;
+    refreshAll(): Promise<IExternalBook.RefreshResult[]>;
     /**
      * @returns The positional array, gaps included — `null` at index `i` means `[i+1]` is a DDE/OLE
      * link or otherwise unmodeled, not that it is absent. `null` overall if there are no entries at
@@ -25,5 +52,50 @@ export interface IExternalBookCollection extends ICollection<IExternalBook> {
      * For runtime type checking.
      */
     readonly isIExternalBookCollection: true;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: IExternalBookCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** Closes the collection; the workbook's to call. */
+    close(): void;
+}
+export declare namespace IExternalBookCollection {
+    /**
+     * When the cached values of these books should be re-read from their sources, on open.
+     *
+     * @remarks
+     * `userSet` asks the user on open, `always` refreshes without asking, `never` uses the cache.
+     *
+     * The mode governs the books as a SET — no single book carries one — but it is read and written
+     * on the workbook (`IWorkbook.getUpdateLinks`), where Excel's object model and the file both
+     * keep it.
+     */
+    type UpdateLinks = 'always' | 'never' | 'userSet';
+    interface AddOptions {
+        /**
+         * Where the source workbook is: a path or URL (`C:\dir\Budget.xlsx`, `\\server\share\Budget.xlsx`,
+         * `https://host/Budget.xlsx`, or a bare `Budget.xlsx` relative to this workbook), or the
+         * full `(relType, target)` entries a file would record.
+         */
+        sources: string | readonly IExternalBook.SourceEntry[];
+        /** The source's sheet names, if known. A formula citing a sheet not listed here adds it. */
+        sheetNames?: readonly string[];
+    }
+    interface Events {
+        /**
+         * A book was added, removed or refreshed, or a sheet name was recorded on one. Fires once per
+         * change, and on the undo or redo of one.
+         */
+        onCollectionChange?(source: IExternalBookCollection): void;
+        /**
+         * Called once, when the workbook that owns these books closes.
+         */
+        onClose?(source: IExternalBookCollection): void;
+    }
+    interface IListeners extends IListener.Callbacks<IExternalBookCollection, IExternalBookCollection.Events> {
+    }
 }
 //# sourceMappingURL=IExternalBookCollection.d.ts.map

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

@@ -1,3 +1,4 @@
 export * from './IExternalBook';
 export * from './IExternalBookCollection';
+export * from './ExternalBookName';
 //# sourceMappingURL=index.d.ts.map