@shbernal/ts-xlsx 1.2.0 → 2.0.0

package/dist/core/workbook.d.ts

@@ -1,24 +1,25 @@
 import { type CustomUiDocument } from '../customui/index.ts';
 import { type VbaLibraryReference, type VbaProject, type VbaProjectSignature } from '../vba/index.ts';
 import { type Person } from './comment-thread.ts';
-import { type WorkbookImage } from './image.ts';
+import { type WorkbookImage, type WorksheetImages } from './image.ts';
 import { INTERNAL } from './internal.ts';
 import type { PreservedPart, PreservedRootReference } from './preserved.ts';
 import type { Color, Font, NamedCellStyle, TableStyleTable } from './style.ts';
 import { type TableStyle } from './table-style.ts';
 import { type ThemeColorScheme, type ThemeFontScheme, type ThemeOverrides } from './theme.ts';
 import type { WorkbookProtection } from './workbook-protection.ts';
+import { type DeclaredThemeSchemes } from './workbook-theme.ts';
 import { Worksheet, type WorksheetState } from './worksheet.ts';
 /**
- * A workbook-level reference to package content the model does not model — a pivot cache
- * (`pivotCacheDefinition`) or a slicer cache (`slicerCache`) — preserved verbatim across a round-trip
+ * A workbook-level reference to package content the model does not model: a pivot cache
+ * (`pivotCacheDefinition`) or a slicer cache (`slicerCache`), preserved verbatim across a round-trip
  * instead of being dropped. `relType` is the workbook relationship Type URI to re-emit; `entryPath`
  * is the part it points at; `parts` is the transitive closure that reference reaches (the entry
  * included). `pivotCacheId` carries the `<pivotCache cacheId>` a pivot cache is registered under in
  * the workbook's `<pivotCaches>`, so the wiring a pivot table resolves its cache through is re-emitted
  * too; it is absent for a slicer cache, which the workbook lists in an extension block instead.
  * `externalReferenceIndex` is the 0-based position of an `externalLink` within the workbook's
- * `<externalReferences>` — the `[n]` a formula or defined name resolves an external cell through — so
+ * `<externalReferences>`, the `[n]` a formula or defined name resolves an external cell through, so
  * the block is re-emitted in the original order and every `[n]` still points at the same linked
  * workbook; it is absent for a pivot/slicer cache.
  */
@@ -30,14 +31,14 @@ export interface PreservedWorkbookReference {
     readonly externalReferenceIndex?: number;
 }
 /**
- * The workbook's theme part, captured verbatim from a source package — the `<clrScheme>`,
+ * The workbook's theme part, captured verbatim from a source package: the `<clrScheme>`,
  * `<fontScheme>`, and `<fmtScheme>` every `theme="n"` colour reference and every `scheme="major|minor"`
  * font in the file resolves against.
  *
  * Held opaquely, like {@link Workbook.restoreDifferentialStyles}'s `<dxf>` fragments: the model does
  * not interpret the theme, it only refuses to destroy it. `entryPath` is where the source package held
  * the part (reached through the workbook's `.../theme` relationship, so not necessarily
- * `xl/theme/theme1.xml`), and `parts` is the transitive closure it reaches — the entry included. The
+ * `xl/theme/theme1.xml`), and `parts` is the transitive closure it reaches, the entry included. The
  * closure matters because a theme can carry its own relationships: a picture used as a themed fill is
  * wired by an `r:embed` into the theme's rels part, and re-emitting the theme without it would leave
  * that reference dangling.
@@ -47,14 +48,14 @@ export interface PreservedTheme {
     readonly parts: readonly PreservedPart[];
 }
 /**
- * The workbook's saved window state — OOXML's `<workbookView>`, the single entry of `<bookViews>`.
+ * The workbook's saved window state: OOXML's `<workbookView>`, the single entry of `<bookViews>`.
  *
  * This is the rect a consumer restores the document window to, and the layout every pane geometry is
  * computed against: a frozen split is positioned within it. `activeTab` names the sheet whose tab is
  * selected on open.
  *
  * The position and size are in twips (1/20 of a point), Excel's window unit. A slightly negative
- * `x`/`y` is normal and is what Excel itself writes — a maximised window's frame sits just outside the
+ * `x`/`y` is normal and is what Excel itself writes: a maximised window's frame sits just outside the
  * work area.
  */
 export interface WorkbookView {
@@ -74,7 +75,7 @@ export interface WorkbookView {
     minimized?: boolean;
 }
 /**
- * The window geometry a workbook starts from — the values desktop Excel writes for its own default
+ * The window geometry a workbook starts from: the values desktop Excel writes for its own default
  * window.
  *
  * A default is emitted rather than the element left out because Excel writes `<bookViews>` into every
@@ -89,16 +90,28 @@ export declare const DEFAULT_WORKBOOK_VIEW: {
     readonly height: 12220;
     readonly activeTab: 0;
 };
-/** Document-level metadata written to the package's core properties. */
+/**
+ * Document-level metadata: what Excel's File ▸ Info panel shows. Mostly the package's core
+ * properties (`docProps/core.xml`); `company` is the exception and lives in the extended part,
+ * because that is where OOXML puts it. One interface either way: which part a field lands in is
+ * the format's business, not the caller's.
+ */
 export interface WorkbookProperties {
+    /** The document's title (`dc:title`), as Excel's File ▸ Info shows it. */
+    title?: string;
     creator?: string;
     lastModifiedBy?: string;
     created?: Date;
     modified?: Date;
+    /**
+     * `Company` in the extended properties (`docProps/app.xml`), not the core ones. It is the only
+     * field here that does not live beside the others, because OOXML puts it in the other part.
+     */
+    company?: string;
 }
 /**
- * A named reference in the workbook — the entries Excel surfaces in its Name Manager. A name maps
- * an identifier to a formula (`refersTo`), most often a cell range like `Sheet1!$A$1:$B$2` but
+ * A named reference in the workbook, one of the entries Excel surfaces in its Name Manager. A name
+ * maps an identifier to a formula (`refersTo`), most often a cell range like `Sheet1!$A$1:$B$2` but
  * possibly any formula. A name is global to the workbook unless it names a sheet in {@link scope},
  * which restricts it to that sheet and lets another sheet reuse the same name independently.
  */
@@ -121,7 +134,7 @@ export interface AddWorksheetOptions {
 export interface AddImageOptions {
     /** The image bytes. */
     readonly buffer: Uint8Array;
-    /** The file kind — `"png"`, `"jpeg"`/`"jpg"`, `"gif"`, … A leading dot or a URL query string is
+    /** The file kind: `"png"`, `"jpeg"`/`"jpg"`, `"gif"`, … A leading dot or a URL query string is
      * tolerated and stripped; omit it entirely to infer the kind from the bytes' magic number. */
     readonly extension?: string;
 }
@@ -129,7 +142,7 @@ export declare class Workbook {
     #private;
     readonly properties: WorkbookProperties;
     /**
-     * The workbook's window state — position, size, and the selected sheet. Always present (see
+     * The workbook's window state: position, size, and the selected sheet. Always present (see
      * {@link DEFAULT_WORKBOOK_VIEW} for why it is defaulted rather than left unset) and always written.
      * Reading a file replaces it with that file's saved geometry, so a round-trip restores the window
      * the author left rather than stamping ours over it.
@@ -138,12 +151,12 @@ export declare class Workbook {
     /**
      * Ask consuming spreadsheet apps to recalculate every formula when the file is opened, rather than
      * trusting the cached results stored with each formula cell. Set this when the producer cannot
-     * compute formula results itself — the OOXML `fullCalcOnLoad` flag. Off by default, so a workbook
-     * whose cached results are authoritative stays unmarked.
+     * compute formula results itself. This is the OOXML `fullCalcOnLoad` flag, off by default, so a
+     * workbook whose cached results are authoritative stays unmarked.
      */
     fullCalcOnLoad: boolean;
     /**
-     * Workbook-level structure/window protection — the OOXML `<workbookProtection>` element. Absent by
+     * Workbook-level structure/window protection: the OOXML `<workbookProtection>` element. Absent by
      * default (an unprotected workbook). Set it to lock the workbook shell, or leave it as read from a
      * file so a protected workbook stays locked across a passthrough save rather than being silently
      * unlocked. Distinct from a worksheet's own `protect()`, which guards a single sheet's cells.
@@ -153,7 +166,7 @@ export declare class Workbook {
     get worksheets(): readonly Worksheet[];
     /**
      * The 0-based index of the active sheet: {@link WorkbookView.activeTab} resolved against the sheets
-     * that actually exist. Exactly one sheet is always active — an out-of-range tab (a caller's stale
+     * that actually exist. Exactly one sheet is always active: an out-of-range tab (a caller's stale
      * index, or a file whose sheet was removed after the view was saved) falls back to the first sheet
      * rather than to none, because a package where no sheet is selected gives the consumer no view to
      * initialise on open.
@@ -164,12 +177,12 @@ export declare class Workbook {
     /** The package-root preserved references, in the order they were read. */
     get preservedRootReferences(): readonly PreservedRootReference[];
     /**
-     * The ribbon customisations decoded from this workbook's `customUI` parts — `customUI.xml` (Office
+     * The ribbon customisations decoded from this workbook's `customUI` parts: `customUI.xml` (Office
      * 2007) and/or `customUI14.xml` (Office 2010+), in the order their root relationships were read. Each
      * {@link CustomUiDocument} is tagged with its dialect and exposes the parsed `<ribbon>` tree. Empty
      * for a workbook that customises no ribbon.
      *
-     * This is a **read-only view** over parts the writer already round-trips verbatim — mutating the
+     * This is a **read-only view** over parts the writer already round-trips verbatim. Mutating the
      * returned objects changes nothing on write; the original `customUI` XML is re-emitted byte-for-byte
      * regardless. Parsed lazily on first access and memoised.
      *
@@ -179,15 +192,15 @@ export declare class Workbook {
     /**
      * The VBA project decoded from this workbook's preserved `vbaProject.bin`, or `undefined` for a
      * workbook with no macros. This is a **read-only view** over the bytes the writer already round-trips
-     * verbatim — mutating the returned object changes nothing on write; the original macro blob is
+     * verbatim. Mutating the returned object changes nothing on write; the original macro blob is
      * re-emitted byte-for-byte regardless. Parsed lazily on first access and memoised.
      *
      * @throws {VbaParseError} if a macro project is present but its `vbaProject.bin` is malformed.
      */
     get vbaProject(): VbaProject | undefined;
     /**
-     * The raw `vbaProject.bin` bytes attached to this workbook — the exact macro blob the writer will
-     * embed — or `undefined` for a workbook with no macros. The getter returns a defensive copy, so
+     * The raw `vbaProject.bin` bytes attached to this workbook (the exact macro blob the writer will
+     * embed), or `undefined` for a workbook with no macros. The getter returns a defensive copy, so
      * mutating it changes nothing on write.
      *
      * Assigning bytes attaches (or replaces) the macro project: the written package becomes
@@ -198,14 +211,14 @@ export declare class Workbook {
      * `.bin` produced by another tool. Assigning `undefined` removes the project, reverting the workbook
      * to a plain (non-macro) package.
      *
-     * Replacing or removing the project also drops any digital signature the previous blob carried — a
-     * signature over the old bytes cannot validate new ones — so the result never advertises a broken
-     * signature.
+     * Replacing or removing the project also drops any digital signature the previous blob carried,
+     * because a signature over the old bytes cannot validate new ones, so the result never advertises
+     * a broken signature.
      */
     get vbaProjectBytes(): Uint8Array | undefined;
     set vbaProjectBytes(bytes: Uint8Array | undefined);
     /**
-     * Whether this workbook's VBA project carries a digital signature — `true` if any signature part is
+     * Whether this workbook's VBA project carries a digital signature: `true` if any signature part is
      * attached, `false` for an unsigned project or a workbook with no macros.
      *
      * This reflects the **presence** of a signature blob, not its cryptographic validity: the library
@@ -219,20 +232,20 @@ export declare class Workbook {
     get vbaProjectSigned(): boolean;
     /**
      * The digital signatures attached to this workbook's VBA project, in the order their relationships
-     * are wired off `vbaProject.bin` — up to three generations (legacy, agile, V3) can coexist over the
+     * are wired off `vbaProject.bin`. Up to three generations (legacy, agile, V3) can coexist over the
      * same project bytes. Empty for an unsigned project or a workbook with no macros.
      *
      * Each entry's `bytes` are the raw signature blob passed through verbatim; the library does not parse
      * or verify them (see {@link vbaProjectSigned} on presence-vs-validity). Hand a blob to an external
-     * verifier if you need cryptographic validation — that is deliberately out of this library's scope.
+     * verifier if you need cryptographic validation; that is deliberately out of this library's scope.
      */
     get vbaProjectSignatures(): readonly VbaProjectSignature[];
     /**
-     * Remove a standard module from this workbook's existing macro project, in place — a structural splice
+     * Remove a standard module from this workbook's existing macro project, in place: a structural splice
      * that leaves every remaining module's compiled p-code untouched (see {@link removeVbaModule}).
      * Replacing the project also drops a stale signature, as {@link vbaProjectBytes} does.
      *
-     * Only `procedural` and `class` modules can be removed this way — see {@link removeVbaModule} for why.
+     * Only `procedural` and `class` modules can be removed this way. See {@link removeVbaModule} for why.
      * To author or edit module *source* (which needs real compiled p-code), use the offline
      * `tools/vba-compiler`, then attach its output via {@link vbaProjectBytes}.
      *
@@ -261,7 +274,7 @@ export declare class Workbook {
     /** The preserved `<tableStyles>` block; `styles` is empty when the file declared no custom style. */
     get tableStyles(): TableStyleTable;
     /**
-     * Register a custom table style — a named look a table applies to itself by putting that name in
+     * Register a custom table style: a named look a table applies to itself by putting that name in
      * {@link TableStyleInfo.name}, exactly as it would name one of Excel's built-in gallery styles.
      *
      * ```ts
@@ -278,14 +291,15 @@ export declare class Workbook {
      * ```
      *
      * Each element's formatting is interned into the workbook's shared differential-style table, so two
-     * elements — or a conditional-formatting rule — that paint the same way share one entry.
+     * elements, or a conditional-formatting rule, that paint the same way share one entry.
      *
      * Registering a name a source file already defined **overrides** that definition rather than adding
      * a second one beside it.
      *
-     * @throws {AuthoringError} if the name is empty, or an element carries a `size` outside the four stripe
-     *   types, or a `size` is not a positive integer — see {@link checkTableStyle} for why those are
-     *   refused here rather than silently dropped.
+     * @throws {AuthoringError} if the name is empty, or an element carries a `size` outside the four
+     *   stripe types. See {@link checkTableStyle} for why those are refused here rather than silently
+     *   dropped.
+     * @throws {RangeError} if a `size` is not a positive integer.
      */
     addTableStyle(style: TableStyle): void;
     /** The table styles authored on this workbook, in registration order. */
@@ -297,24 +311,24 @@ export declare class Workbook {
      * typefaces. Merges into what the workbook already has, so branding one accent leaves the other
      * eleven slots alone, and calling it twice accumulates.
      *
-     * This is the workbook-wide palette. A cell that names a colour as `theme="4"` — which is what Excel
-     * writes whenever a user picks from the theme row of the colour picker — follows `accent1` here, so
+     * This is the workbook-wide palette. A cell that names a colour as `theme="4"`, which is what Excel
+     * writes whenever a user picks from the theme row of the colour picker, follows `accent1` here, so
      * one call restyles every such cell, chart and table style at once. Colours are `RRGGBB`; a leading
      * `#` and an 8-hex ARGB are both accepted and reduced, and anything else throws rather than writing
      * a value Excel silently renders as flat black.
      *
-     * What it does **not** touch: the theme's format scheme — the gradient, line and effect styles that
-     * give a theme its texture. Those ride through from the source theme (or the library's default)
-     * untouched, because nobody hand-authors gradient stops from a spreadsheet API and regenerating them
-     * would replace a designer's work with the Office default. For the same reason a slot left
-     * unauthored keeps the source's own encoding, including the `<a:sysClr>` form Excel uses for
-     * `dk1`/`lt1` so they follow the viewer's window colours.
+     * What it does **not** touch: the theme's format scheme, meaning the gradient, line and effect
+     * styles that give a theme its texture. Those ride through from the source theme (or the library's
+     * default) untouched, because nobody hand-authors gradient stops from a spreadsheet API and
+     * regenerating them would replace a designer's work with the Office default. For the same reason a
+     * slot left unauthored keeps the source's own encoding, including the `<a:sysClr>` form Excel uses
+     * for `dk1`/`lt1` so they follow the viewer's window colours.
      *
      * @throws {AuthoringError} if a colour is not 6 or 8 hexadecimal digits.
      */
     setTheme(overrides: ThemeOverrides): void;
     /**
-     * The colour scheme every `theme="n"` reference in this workbook resolves against — anything
+     * The colour scheme every `theme="n"` reference in this workbook resolves against: anything
      * {@link setTheme} authored, over the preserved theme's `<a:clrScheme>`, over the Office default.
      *
      * Note the slot *order*: `theme="0"` is `lt1` and `theme="1"` is `dk1`, which is not the order the
@@ -324,7 +338,7 @@ export declare class Workbook {
     /** The theme's major (heading) and minor (body) typefaces, authored values over the source's. */
     get themeFonts(): ThemeFontScheme;
     /**
-     * The default font as the source package declared it — font id 0 of its styles part, the face every
+     * The default font as the source package declared it: font id 0 of its styles part, the face every
      * cell that names no font of its own renders in. `undefined` for a workbook authored from scratch or
      * read from a package carrying no styles part: nothing was declared, and the library does not
      * fabricate a declaration on the file's behalf.
@@ -334,23 +348,24 @@ export declare class Workbook {
      */
     get declaredDefaultFont(): Font | undefined;
     /**
-     * Author the workbook's default font — the face, size and colour every cell with no font of its own
+     * Author the workbook's default font: the face, size and colour every cell with no font of its own
      * renders in, **empty cells included**. Merges into whatever the workbook already had, so
      * `setDefaultFont({size: 14})` keeps the resolved face and changes only the size, and calling it
      * twice accumulates. This is the one knob that reaches a cell no row or column default can: an
      * untouched cell in an unformatted column.
      *
-     * It writes the styles part's font 0 and **nothing else** — in particular it does not rewrite the
+     * It writes the styles part's font 0 and **nothing else**. In particular it does not rewrite the
      * theme's body typeface. The dependency runs the other way: with no default font authored, font 0
      * follows {@link themeFonts}'s minor face, so `setTheme({fonts: {minor}})` already reaches every
      * unstyled cell and needs no second call here. See {@link defaultFont} for the full chain.
      *
-     * @throws {AuthoringError} if `size` is not a positive finite number, or `name` is empty — both
-     *   produce a styles part Excel renders from some other font without ever reporting why.
+     * @throws {RangeError} if `size` is not a positive finite number, or `name` is empty. Both
+     *   produce a styles part Excel renders from some other font without ever reporting why. Native
+     *   rather than {@link AuthoringError}: one argument out of range is what `RangeError` is for.
      */
     setDefaultFont(font: Font): void;
     /**
-     * The font every cell that names none of its own renders in, resolved and complete — what the writer
+     * The font every cell that names none of its own renders in, resolved and complete: what the writer
      * emits as font id 0. Never `undefined`: a workbook always renders in *some* face, and the chain
      * below always reaches one.
      *
@@ -361,28 +376,28 @@ export declare class Workbook {
      * The two authored levels outrank the file because authoring is an explicit act; between them
      * {@link setDefaultFont} wins on the face because it names font 0 outright while
      * {@link setTheme} names it only by implication. With **nothing** authored the file's own font 0
-     * passes through verbatim — deliberately, because a producer resolves that face by script and we do
-     * not: Excel writes `等线` as font 0 under a theme whose latin body face is `Calibri`, and
+     * passes through verbatim. That is deliberate, because a producer resolves that face by script and
+     * we do not: Excel writes `等线` as font 0 under a theme whose latin body face is `Calibri`, and
      * re-deriving would silently rewrite it.
      *
      * `family` and `scheme` describe the *theme's* body face, so they are carried exactly while the
-     * resolved face still is that face and dropped when a caller names another — which is also what
+     * resolved face still is that face and dropped when a caller names another, which is also what
      * Excel writes: a font 0 naming a non-theme face carries no `<scheme>` at all. Either may be stated
      * outright, in which case the caller's word stands.
      */
     get defaultFont(): Font;
     /**
-     * The theme part text this workbook should write, or `undefined` when nothing was authored and the
-     * source theme (or the writer's default) should ride through untouched.
+     * The colour slots and typefaces {@link setTheme} authored on this workbook, or `undefined` when
+     * none were, in which case the source theme (or the writer's default) rides through untouched.
      *
-     * Authoring generates *over* the existing part rather than from scratch — see
-     * {@link applyThemeOverrides} — so a preserved theme keeps its format scheme, its unauthored slots'
-     * exact encoding, and the relationships it carries.
+     * A serializer composes these *over* the existing part rather than generating one from scratch, so
+     * a preserved theme keeps its format scheme, its unauthored slots' exact encoding, and the
+     * relationships it carries.
      */
-    authoredThemeXml(): string | undefined;
+    get themeOverrides(): ThemeOverrides | undefined;
     /**
      * Resolve a colour reference to a concrete 8-hex ARGB string, or `undefined` when it does not
-     * resolve to a fixed colour — an `auto` colour, one of the two system indexed colours, or a theme
+     * resolve to a fixed colour: an `auto` colour, one of the two system indexed colours, or a theme
      * slot this workbook's scheme does not declare.
      *
      * This is a *derived* view, not a rewrite: the {@link Color} stays exactly as its file encoded it,
@@ -398,12 +413,12 @@ export declare class Workbook {
     /** The named cell styles, in index order (index 0 is Normal); empty when only the default exists. */
     get namedStyles(): readonly NamedCellStyle[];
     /**
-     * Register an identity a threaded comment can name — an author, or someone `@mentioned` in a message.
+     * Register an identity a threaded comment can name: an author, or someone `@mentioned` in a message.
      * A message reaches it by {@link Comment.personId}, a mention by {@link Mention.personId}.
      *
      * Keyed by {@link Person.id} alone, so registering the same id twice replaces the entry rather than
      * adding a second: the id is the identity. Registering the same human twice under *different* ids is
-     * legitimate and is what Excel itself does — see {@link restorePersons}. The id is normalised to the
+     * legitimate and is what Excel itself does. See {@link restorePersons}. The id is normalised to the
      * brace-wrapped upper-case GUID form the format requires, so a `crypto.randomUUID()` is accepted as-is.
      *
      * @throws {SyntaxError} if the id is not a GUID.
@@ -411,7 +426,8 @@ export declare class Workbook {
     addPerson(person: Person): void;
     /**
      * The registered threaded-comment identities, in the order they were read. That order carries no
-     * meaning — Excel re-sorts the registry by person id when it saves — so nothing may depend on it.
+     * meaning, because Excel re-sorts the registry by person id when it saves, so nothing may depend
+     * on it.
      */
     get persons(): readonly Person[];
     /** Look up a registered identity by its {@link Person.id}, or `undefined` if the registry has none. */
@@ -426,13 +442,54 @@ export declare class Workbook {
     get media(): readonly WorkbookImage[];
     /** Look up a registered image by its id, or `undefined` if no image carries that id. */
     getImage(id: number): WorkbookImage | undefined;
+    /**
+     * Every picture `sheet` shows, resolved out of this workbook's media registry into the
+     * workbook-independent form {@link importImages} consumes. `sheet` must belong to this workbook:
+     * that is whose registry its image ids index.
+     *
+     * This is the attached-part half of a sheet copy, and it is deliberately a separate call from
+     * {@link Worksheet.model}: a model is a serialisable value, an image is bytes on the workbook, and
+     * ADR-0005 keeps them apart. Carrying a sheet whole is therefore the two of them together:
+     *
+     * ```ts
+     * destination.model = source.model;
+     * destinationWorkbook.importImages(destination, sourceWorkbook.exportImages(source));
+     * ```
+     *
+     * The exported pictures share the registry's byte arrays rather than copying them: the library
+     * never mutates image bytes, and copying every picture would double the memory of an image-heavy
+     * workbook to defend against a mutation nothing performs.
+     *
+     * @throws {AuthoringError} if the sheet anchors an image id this workbook has not registered,
+     *   which is what a sheet from *another* workbook looks like from here. Emitting a package with a
+     *   drawing pointing at media that was never registered is the silently-broken-image failure this
+     *   refuses to start.
+     */
+    exportImages(sheet: Worksheet): WorksheetImages;
+    /**
+     * Show `images` on `sheet`, a worksheet of this workbook, registering each picture's bytes here
+     * and re-anchoring it against the id they land on. The counterpart to {@link exportImages}, and
+     * the affordance that lets a picture cross workbooks at all: an {@link AnchoredImage}'s `imageId`
+     * indexes one workbook's registry and means nothing in the next, so a raw anchor moved between
+     * workbooks points at media that does not exist there.
+     *
+     * The sheet's existing pictures are replaced, not appended to, so `importImages` is a transfer
+     * rather than an accumulation: the same direction {@link Worksheet.model} assignment goes, and
+     * what makes re-importing a sheet's own export leave it unchanged. An import whose `background` is
+     * absent clears the destination's background for the same reason.
+     *
+     * Registration is content-addressed: a picture whose bytes are already here is re-used at its
+     * existing id rather than stored twice, so importing the same sheet repeatedly, or twenty sheets
+     * sharing one logo, costs one media part.
+     */
+    importImages(sheet: Worksheet, images: WorksheetImages): void;
     /** The workbook's defined names, in the order they were registered. */
     get definedNames(): readonly DefinedName[];
     /**
      * Register a defined name on the workbook.
      *
      * @throws {AuthoringError} if the name is empty, or if a {@link DefinedName.scope} is given that names no
-     *   existing worksheet — a scoped name must target a sheet that is already part of the workbook.
+     *   existing worksheet. A scoped name must target a sheet that is already part of the workbook.
      */
     defineName(definedName: DefinedName): void;
     /**
@@ -445,20 +502,20 @@ export declare class Workbook {
     /** Look up a worksheet by name (case-insensitive) or by numeric id. */
     getWorksheet(nameOrId: string | number): Worksheet | undefined;
     /**
-     * {@link getWorksheet}, for a caller who knows the sheet is there — the miss throws instead of
+     * {@link getWorksheet}, for a caller who knows the sheet is there: the miss throws instead of
      * returning `undefined`, and the message names every sheet the workbook does have.
      *
      * The partial lookup is the right primitive for asking *whether* a sheet exists, and the wrong
      * one for reaching a sheet a template is expected to carry: `undefined` flows on into a `?.`
      * chain and fails several steps later with nothing left to say about which name was missing.
-     * That listing is the whole point — a lookup miss is a typo, a stale template or a renamed tab,
+     * That listing is the whole point: a lookup miss is a typo, a stale template or a renamed tab,
      * and all three are answered by seeing the real names.
      *
      * @throws {AuthoringError} if no worksheet has that name (case-insensitive) or numeric id.
      */
     requireWorksheet(nameOrId: string | number): Worksheet;
     /**
-     * The codec's channel into this workbook — see `core/internal.ts` for why these are not public
+     * The codec's channel into this workbook. See `core/internal.ts` for why these are not public
      * methods. Declared last so every private field it closes over is already in scope.
      */
     readonly [INTERNAL]: WorkbookInternals;
@@ -468,7 +525,7 @@ export declare class Workbook {
  * the finished form the file stated it. Reached as `workbook[INTERNAL]`; see `core/internal.ts`.
  *
  * Every operation replaces what it restores rather than merging, because a reader states a table
- * whole — a half-restored `<dxfs>` would leave existing `dxfId` references pointing into a mix of
+ * whole: a half-restored `<dxfs>` would leave existing `dxfId` references pointing into a mix of
  * two files.
  */
 export interface WorkbookInternals {
@@ -477,39 +534,40 @@ export interface WorkbookInternals {
     /** Record a package-root preserved reference (a customUI ribbon part, custom props) read from a file. */
     addPreservedRootReference(reference: PreservedRootReference): void;
     /**
-     * Reinstate the differential-style (`<dxfs>`) table read from a file — the deserialization
+     * Reinstate the differential-style (`<dxfs>`) table read from a file: the deserialization
      * counterpart the writer re-emits verbatim. Each entry is one `<dxf>…</dxf>` fragment, preserved as
      * opaque XML so a conditional-formatting rule's `dxfId` (an index into this table) stays valid on
      * re-write.
      */
     restoreDifferentialStyles(fragments: readonly string[]): void;
     /**
-     * Reinstate the custom indexed-color palette (`<colors><indexedColors>`) read from a file — each
-     * entry a verbatim `<rgbColor rgb="…"/>` fragment — so a colour referenced by `indexed="…"` keeps
+     * Reinstate the custom indexed-color palette (`<colors><indexedColors>`) read from a file, each
+     * entry a verbatim `<rgbColor rgb="…"/>` fragment, so a colour referenced by `indexed="…"` keeps
      * its intended RGB on re-write instead of the palette being dropped and the colour shifting to a
      * default-palette entry.
      */
     restoreIndexedColors(fragments: readonly string[]): void;
     /**
      * Reinstate the most-recently-used colour swatches (`<colors><mruColors>`) read from a file, each
-     * entry a verbatim `<color rgb="…"/>` fragment — the "Recent Colors" row a spreadsheet application
-     * offers, which is the author's own working set rather than anything the model interprets.
+     * entry a verbatim `<color rgb="…"/>` fragment. This is the "Recent Colors" row a spreadsheet
+     * application offers, which is the author's own working set rather than anything the model
+     * interprets.
      */
     restoreMruColors(fragments: readonly string[]): void;
     /**
-     * Reinstate the custom table-style definitions (`<tableStyles>`) read from a file — see
-     * {@link TableStyleTable} — so a table whose `styleName` names a custom style still resolves to a
+     * Reinstate the custom table-style definitions (`<tableStyles>`) read from a file (see
+     * {@link TableStyleTable}), so a table whose `styleName` names a custom style still resolves to a
      * real definition on re-write instead of dangling, and the file's nominated default table/pivot
      * styles survive.
      */
     restoreTableStyles(table: TableStyleTable): void;
     /**
-     * Reinstate the theme part read from a file — opaque preserved XML plus the closure of parts it
-     * reaches (see {@link PreservedTheme}) — so a workbook's colour and font schemes survive a re-write
+     * Reinstate the theme part read from a file: opaque preserved XML plus the closure of parts it
+     * reaches (see {@link PreservedTheme}), so a workbook's colour and font schemes survive a re-write
      * instead of being replaced by the library's default Office theme. Passing `undefined` drops back
      * to that default.
      */
-    restoreThemePart(theme: PreservedTheme | undefined): void;
+    restoreThemePart(theme: PreservedTheme | undefined, declared: DeclaredThemeSchemes): void;
     /**
      * Reinstate the named cell styles (`cellStyleXfs`/`cellStyles`) read from a file, index for index,
      * so a cell's link to a named style (its `xfId`) stays valid on re-write. Index 0 is the Normal
@@ -517,7 +575,7 @@ export interface WorkbookInternals {
      */
     restoreNamedStyles(styles: readonly NamedCellStyle[]): void;
     /**
-     * Reinstate font id 0 as a file declared it — the face its unstyled cells render in, and the metric
+     * Reinstate font id 0 as a file declared it: the face its unstyled cells render in, and the metric
      * its column widths are expressed in character units of. Restored rather than assumed because the
      * library must not inject its own default ahead of one a file already states: doing so replaces the
      * declared face on every empty cell and silently changes what every `<col width>` means.
@@ -526,13 +584,13 @@ export interface WorkbookInternals {
      */
     restoreDefaultFont(font: Font | undefined): void;
     /**
-     * Reinstate the threaded-comment identity registry (`xl/persons/person.xml`) read from a file — the
+     * Reinstate the threaded-comment identity registry (`xl/persons/person.xml`) read from a file: the
      * authors and mentioned people a comment thread's messages point at.
      *
      * Entries are keyed by {@link Person.id} and by nothing else. A single human legitimately owns
      * several entries: Excel interns a *mentioned* identity as its own `providerId="PeoplePicker"` entry
-     * beside that person's `providerId="AD"` authoring entry — same `displayName`, same `userId`, a
-     * different id — and points the mention at the new one. Collapsing entries by name or `userId` would
+     * beside that person's `providerId="AD"` authoring entry (same `displayName`, same `userId`, a
+     * different id) and points the mention at the new one. Collapsing entries by name or `userId` would
      * merge those two and silently re-point every mention at the wrong identity.
      *
      * {@link Workbook.addPerson} is the authoring verb.