@shbernal/ts-xlsx 1.0.0

package/dist/core/workbook.d.ts

@@ -0,0 +1,528 @@
+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 { 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 { 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
+ * 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
+ * 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.
+ */
+export interface PreservedWorkbookReference {
+    readonly relType: string;
+    readonly entryPath: string;
+    readonly parts: readonly PreservedPart[];
+    readonly pivotCacheId?: string;
+    readonly externalReferenceIndex?: number;
+}
+/**
+ * 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
+ * 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.
+ */
+export interface PreservedTheme {
+    readonly entryPath: string;
+    readonly parts: readonly PreservedPart[];
+}
+/**
+ * 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
+ * work area.
+ */
+export interface WorkbookView {
+    /** Left edge of the document window, in twips. */
+    x: number;
+    /** Top edge of the document window, in twips. */
+    y: number;
+    /** Window width, in twips. */
+    width: number;
+    /** Window height, in twips. */
+    height: number;
+    /** 0-based index into {@link Workbook.worksheets} of the sheet selected on open. */
+    activeTab: number;
+    /** Window visibility; omit for a normally visible window. */
+    visibility?: 'visible' | 'hidden' | 'veryHidden';
+    /** Whether the document window opens minimised; omit for a restored window. */
+    minimized?: boolean;
+}
+/**
+ * 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
+ * file it saves and consumers lay panes out against that rect. With no view at all the frozen-pane
+ * split is computed against an uninitialised window, and the frozen region can stay unpainted until
+ * some later event forces a relayout.
+ */
+export declare const DEFAULT_WORKBOOK_VIEW: {
+    readonly x: -110;
+    readonly y: -110;
+    readonly width: 19420;
+    readonly height: 12220;
+    readonly activeTab: 0;
+};
+/** Document-level metadata written to the package's core properties. */
+export interface WorkbookProperties {
+    creator?: string;
+    lastModifiedBy?: string;
+    created?: Date;
+    modified?: Date;
+}
+/**
+ * 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
+ * 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.
+ */
+export interface DefinedName {
+    /** The name as typed in a formula, e.g. `"TaxRate"`. Built-in names carry an `_xlnm.` prefix. */
+    readonly name: string;
+    /** The formula the name resolves to, e.g. `"Sheet1!$A$1:$B$2"`. */
+    readonly refersTo: string;
+    /** The sheet the name is scoped to; omit for a workbook-global name. */
+    readonly scope?: string;
+    /** A human note shown beside the name in Excel's Name Manager. */
+    readonly comment?: string;
+    /** Hide the name from the Name Manager UI without removing it. */
+    readonly hidden?: boolean;
+}
+export interface AddWorksheetOptions {
+    readonly state?: WorksheetState['state'];
+}
+/** A picture registered on the workbook, ready to be anchored to a worksheet. */
+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
+     * tolerated and stripped; omit it entirely to infer the kind from the bytes' magic number. */
+    readonly extension?: string;
+}
+export declare class Workbook {
+    #private;
+    readonly properties: WorkbookProperties;
+    /**
+     * 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.
+     */
+    readonly view: WorkbookView;
+    /**
+     * 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.
+     */
+    fullCalcOnLoad: boolean;
+    /**
+     * 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.
+     */
+    protection: WorkbookProtection | undefined;
+    /** The worksheets in insertion order. */
+    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
+     * 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.
+     */
+    get activeTabIndex(): number;
+    /** The workbook-level preserved references, in the order they were read. */
+    get preservedReferences(): readonly PreservedWorkbookReference[];
+    /** 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
+     * 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
+     * returned objects changes nothing on write; the original `customUI` XML is re-emitted byte-for-byte
+     * regardless. Parsed lazily on first access and memoised.
+     *
+     * @throws {@link CustomUiParseError} if a `customUI` part is present but its XML is malformed.
+     */
+    get customUI(): readonly CustomUiDocument[];
+    /**
+     * 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
+     * re-emitted byte-for-byte regardless. Parsed lazily on first access and memoised.
+     *
+     * @throws {@link 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
+     * mutating it changes nothing on write.
+     *
+     * Assigning bytes attaches (or replaces) the macro project: the written package becomes
+     * macro-enabled and re-embeds these bytes verbatim. The bytes must be a well-formed VBA container
+     * (a CFB holding a `dir` stream); a malformed blob is rejected with {@link VbaParseError} rather
+     * than written out to produce a package Excel would flag for repair. This is the attach-blob path:
+     * copy a project between workbooks with `dst.vbaProjectBytes = src.vbaProjectBytes`, or import a
+     * `.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.
+     */
+    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
+     * 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
+     * neither parses the PKCS#7/CMS structure nor validates the certificate chain or signer. A `true`
+     * here means "a signature is attached," never "this signature is valid." Replacing or editing the
+     * project drops its signatures (a signature over the old bytes cannot validate new ones), so this
+     * reads `false` again after {@link vbaProjectBytes}, {@link removeVbaModule}, or
+     * {@link addVbaReference} mutates the project. See {@link vbaProjectSignatures} for the raw bytes and
+     * which generation(s) are present.
+     */
+    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
+     * 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.
+     */
+    get vbaProjectSignatures(): readonly VbaProjectSignature[];
+    /**
+     * 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.
+     * 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}.
+     *
+     * @throws {@link VbaAuthorError} if the workbook has no macro project, or `name` is not in the project,
+     *   or names a `document`/`designer` module.
+     * @throws {@link VbaParseError} if the attached `vbaProject.bin` is malformed.
+     */
+    removeVbaModule(name: string): void;
+    /**
+     * Add a registered (COM type-library) reference to this workbook's existing macro project, in place.
+     * Every existing module, reference, and host-info record rides through unchanged (see
+     * {@link addVbaReference}). Replacing the project also drops a stale signature, as
+     * {@link vbaProjectBytes} does.
+     *
+     * @throws {@link VbaAuthorError} if the workbook has no macro project, or any field of `ref` is invalid
+     *   (see {@link VbaLibraryReference}).
+     * @throws {@link VbaParseError} if the attached `vbaProject.bin` is malformed.
+     */
+    addVbaReference(ref: VbaLibraryReference): void;
+    /** The preserved differential-style (`<dxfs>`) fragments, in index order. */
+    get differentialStyles(): readonly string[];
+    /** The preserved custom indexed-color palette, in index order; empty when the default palette rules. */
+    get indexedColors(): readonly string[];
+    /** The preserved most-recently-used colour swatches, in order; empty when the file declared none. */
+    get mruColors(): readonly string[];
+    /** 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
+     * {@link TableStyleInfo.name}, exactly as it would name one of Excel's built-in gallery styles.
+     *
+     * ```ts
+     * workbook.addTableStyle({
+     *   name: 'Harbour',
+     *   elements: {
+     *     wholeTable: {border: {top: {style: 'thin'}, bottom: {style: 'thin'}}},
+     *     headerRow: {font: {bold: true, color: {argb: 'FFFFFFFF'}},
+     *                 fill: {type: 'pattern', pattern: 'solid', bgColor: {argb: 'FFBB2649'}}},
+     *     firstRowStripe: {fill: {type: 'pattern', pattern: 'solid', bgColor: {argb: 'FFF6E7EB'}}},
+     *   },
+     * });
+     * sheet.addTable({name: 'Cargo', ref: 'A1:B3', columns, style: {name: 'Harbour'}});
+     * ```
+     *
+     * 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.
+     *
+     * Registering a name a source file already defined **overrides** that definition rather than adding
+     * a second one beside it.
+     *
+     * @throws {@link 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.
+     */
+    addTableStyle(style: TableStyle): void;
+    /** The table styles authored on this workbook, in registration order. */
+    get customTableStyles(): readonly TableStyle[];
+    /** The preserved theme part, or undefined when the workbook rides the library's default theme. */
+    get themePart(): PreservedTheme | undefined;
+    /**
+     * Author the workbook's theme: any subset of the twelve colour-scheme slots, and either of the two
+     * 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
+     * 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.
+     *
+     * @throws {@link 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
+     * {@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
+     * slots appear in the theme part. See {@link THEME_COLOR_SLOTS}.
+     */
+    get themeColors(): ThemeColorScheme;
+    /** 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
+     * 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.
+     *
+     * This is the *round-trip* surface. {@link defaultFont} is what the workbook actually renders in,
+     * which is this once anything has been authored over it.
+     */
+    get declaredDefaultFont(): Font | undefined;
+    /**
+     * 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
+     * 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 {@link 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.
+     */
+    setDefaultFont(font: Font): void;
+    /**
+     * 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.
+     *
+     * ```
+     * authored default font  >  authored theme body face  >  the source file's font 0  >  theme body face
+     * ```
+     *
+     * 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
+     * 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
+     * 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.
+     *
+     * 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.
+     */
+    authoredThemeXml(): string | 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
+     * 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,
+     * so a round-trip re-emits `theme="4" tint="0.4"` rather than a literal ARGB. Resolving into the
+     * model would sever every cell's link to the theme, so recolouring the workbook would stop working,
+     * and would inflate the styles table with one distinct colour per shade.
+     *
+     * A `theme` reference resolves through {@link themeColors}; an `indexed` one through the workbook's
+     * custom `<indexedColors>` palette when it declares one, else the built-in legacy palette. A `tint`
+     * is applied last.
+     */
+    resolveColor(color: Color): string | undefined;
+    /** 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.
+     * 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
+     * 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.
+     */
+    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.
+     */
+    get persons(): readonly Person[];
+    /** Look up a registered identity by its {@link Person.id}, or `undefined` if the registry has none. */
+    getPerson(id: string): Person | undefined;
+    /**
+     * Register a picture on the workbook and return its numeric id. Pass the id to
+     * {@link Worksheet.addImage} to anchor the picture to a sheet; the same id may be anchored on any
+     * number of sheets and positions, and the bytes are still stored only once.
+     */
+    addImage(options: AddImageOptions): number;
+    /** The registered images, indexed by the id {@link addImage} returned. */
+    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;
+    /** The workbook's defined names, in the order they were registered. */
+    get definedNames(): readonly DefinedName[];
+    /**
+     * Register a defined name on the workbook.
+     *
+     * @throws {@link 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.
+     */
+    defineName(definedName: DefinedName): void;
+    /**
+     * Create a worksheet and append it to the workbook.
+     *
+     * @throws {@link AuthoringError} if the name is empty, too long, contains a forbidden character,
+     *   or collides (case-insensitively) with an existing sheet.
+     */
+    addWorksheet(name: string, options?: AddWorksheetOptions): Worksheet;
+    /** Look up a worksheet by name (case-insensitive) or by numeric id. */
+    getWorksheet(nameOrId: string | number): Worksheet | undefined;
+    /**
+     * 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;
+}
+/**
+ * What a codec may do to a `Workbook` that an author may not: reinstate state read from a file, in
+ * 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
+ * two files.
+ */
+export interface WorkbookInternals {
+    /** Record a workbook-level preserved reference (a pivot or slicer cache) read from a file. */
+    addPreservedReference(reference: PreservedWorkbookReference): void;
+    /** 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
+     * 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
+     * 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.
+     */
+    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
+     * 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
+     * instead of being replaced by the library's default Office theme. Passing `undefined` drops back
+     * to that default.
+     */
+    restoreThemePart(theme: PreservedTheme | undefined): 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
+     * default.
+     */
+    restoreNamedStyles(styles: readonly NamedCellStyle[]): void;
+    /**
+     * 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.
+     *
+     * {@link Workbook.setDefaultFont} is the authoring verb; this is only the file's own word.
+     */
+    restoreDefaultFont(font: Font | undefined): void;
+    /**
+     * 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
+     * merge those two and silently re-point every mention at the wrong identity.
+     *
+     * {@link Workbook.addPerson} is the authoring verb.
+     */
+    restorePersons(persons: readonly Person[]): void;
+}