@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/core/workbook.js

@@ -1,9 +1,3 @@
-// The workbook: the top of the model and the entry point of the public API.
-//
-// It owns its worksheets and the document-level properties. Sheet identity follows
-// Excel's rules — names are unique case-insensitively, bounded in length, and free
-// of the characters Excel forbids — so an invalid book cannot be constructed in the
-// first place, rather than failing only at write time.
 import { isCustomUiRelType, parseCustomUi } from '../customui/index.js';
 import { AuthoringError } from '../errors.js';
 import { addVbaReference, parseVbaProject, removeVbaModule, VBA_PROJECT_CONTENT_TYPE, VBA_PROJECT_PART_PATH, VBA_PROJECT_REL_TYPE, VbaAuthorError, vbaProjectSignatureKind, } from '../vba/index.js';
@@ -15,15 +9,6 @@ import { INTERNAL } from './internal.js';
 import { checkTableStyle } from './table-style.js';
 import { applyThemeOverrides, DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, DEFAULT_THEME_XML, OFFICE_BODY_FACE, parseThemeColorScheme, parseThemeFontScheme, THEME_COLOR_SLOTS, } from './theme.js';
 import { Worksheet } from './worksheet.js';
-/**
- * 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 const DEFAULT_WORKBOOK_VIEW = {
     x: -110,
     y: -110,
@@ -32,120 +17,42 @@ export const DEFAULT_WORKBOOK_VIEW = {
     activeTab: 0,
 };
 const MAX_SHEET_NAME_LENGTH = 31;
-// Excel rejects these in a sheet name, plus a leading/trailing apostrophe.
 const INVALID_SHEET_NAME_CHARS = /[*?:\\/[\]]/;
 export class Workbook {
     properties = {};
-    /**
-     * 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.
-     */
     view = { ...DEFAULT_WORKBOOK_VIEW };
-    /**
-     * 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 = false;
-    /**
-     * 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 = undefined;
     #worksheets = [];
     #nextSheetId = 1;
-    // Media is shared workbook-wide: a worksheet anchors an image by its registry index, so one
-    // picture used on several sheets is stored once.
     #media = [];
     #definedNames = [];
-    // Differential styles (`<dxfs>`) are a workbook-level table in styles.xml that conditional
-    // formatting references by index. The library models the classic scale rules directly but preserves
-    // the dxf table as opaque XML fragments, so a rule that references a dxfId (a highlight fill, a
-    // custom number format) keeps a valid target across a read/write cycle instead of dangling.
     #dxfs = [];
-    // Named cell styles (`cellStyleXfs`/`cellStyles` in styles.xml) — the shared, named formatting layer
-    // a cell links to by index. Preserved so a cell whose fill/font/… lives only in a named style keeps
-    // that style, and the link, across a round-trip. Empty when a file declares nothing beyond the
-    // default Normal style, in which case the writer emits just that default.
     #namedStyles = [];
-    // A custom indexed-color palette (`<colors><indexedColors>` in styles.xml) read from a file, each
-    // entry a verbatim `<rgbColor rgb="…"/>` fragment. Preserved so an `indexed="…"` colour reference
-    // keeps its intended RGB across a round-trip instead of resolving to a different default-palette
-    // entry. Empty for a workbook that never overrode the palette.
     #indexedColors = [];
-    // The most-recently-used colour swatches (`<colors><mruColors>` in styles.xml), each a verbatim
-    // `<color rgb="…"/>` fragment. The author's own working set of colours; dropping it on a re-write
-    // quietly resets a habit. Empty for a workbook that never picked a custom colour.
     #mruColors = [];
-    // The custom table-style definitions (`<tableStyles>` in styles.xml), each `<tableStyle>` kept
-    // verbatim, plus the gallery names the file nominates as the default for a new table and pivot. A
-    // table's `tableStyleInfo/@name` can name one of these definitions, so dropping the block leaves
-    // that reference dangling and the table renders unstyled.
     #tableStyles = { styles: [] };
-    // The theme part read from a file, kept verbatim with the closure of parts it reaches. The writer
-    // emits its own default theme for a workbook that has none, so without this a branded theme would be
-    // overwritten by that default and every `theme="n"` colour in the file would silently re-render.
-    // Undefined for a workbook authored from scratch, or read from a package declaring no theme.
     #theme;
-    // Workbook-level references to package content the model does not interpret (pivot caches, slicer
-    // caches), captured verbatim on read so a round-trip re-emits them rather than dropping the pivots
-    // and slicers they back. Empty for a workbook authored from scratch.
     #preservedReferences = [];
-    // The threaded-comment identity registry (`xl/persons/person.xml`), the workbook-level table every
-    // message resolves its author through and every @mention its target. Keyed by person id — see
-    // `restorePersons` for why nothing else will do. Empty for a workbook with no threaded comments.
     #persons = new Map();
-    /** The worksheets in insertion order. */
     get worksheets() {
         return this.#worksheets;
     }
-    /**
-     * 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() {
         const { activeTab } = this.view;
         return Number.isInteger(activeTab) && activeTab > 0 && activeTab < this.#worksheets.length
             ? activeTab
             : 0;
     }
-    /** The workbook-level preserved references, in the order they were read. */
     get preservedReferences() {
         return this.#preservedReferences;
     }
-    // Package-root references to unmodeled content wired from `_rels/.rels` (the ribbon customUI parts,
-    // custom document properties, a thumbnail), captured verbatim on read so a round-trip re-declares
-    // them in the regenerated root rels rather than dropping them. Empty for a workbook authored from
-    // scratch.
     #preservedRootReferences = [];
-    /** The package-root preserved references, in the order they were read. */
     get preservedRootReferences() {
         return this.#preservedRootReferences;
     }
-    // Lazily-parsed customUI ribbon view. `#customUiParsed` distinguishes "not yet parsed" from a genuine
-    // "no ribbon parts" (an empty array), so a ribbon-free workbook is not re-scanned on every access.
     #customUiParsed = false;
     #customUI = [];
-    /**
-     * 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 {CustomUiParseError} if a `customUI` part is present but its XML is malformed.
-     */
     get customUI() {
         if (!this.#customUiParsed) {
             this.#customUI = this.#preservedRootReferences
@@ -158,18 +65,8 @@ export class Workbook {
         }
         return this.#customUI;
     }
-    // Lazily-decoded macro source. `#vbaParsed` distinguishes "not yet decoded" from a genuine "no
-    // macros" (`undefined`) result, so a macro-free workbook is not re-probed on every access.
     #vbaParsed = false;
     #vbaProject = undefined;
-    /**
-     * 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 {VbaParseError} if a macro project is present but its `vbaProject.bin` is malformed.
-     */
     get vbaProject() {
         if (!this.#vbaParsed) {
             const bytes = this.#vbaProjectEntry()?.bytes;
@@ -178,34 +75,12 @@ export class Workbook {
         }
         return this.#vbaProject;
     }
-    /**
-     * 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() {
         return this.#vbaProjectEntry()?.bytes.slice();
     }
     set vbaProjectBytes(bytes) {
-        // Validate before touching any state: a malformed blob must fail closed and leave the existing
-        // project intact, never half-remove it. Only past this point do we mutate.
         if (bytes !== undefined)
             parseVbaProject(bytes);
-        // Drop any existing project; its whole closure goes, taking a now-stale signature part with it. A
-        // fresh reference then mirrors exactly what the reader captures for a macro workbook, so the writer
-        // emits a byte-identical macro-enabled package with no writer changes.
         replaceContents(this.#preservedReferences, this.#preservedReferences.filter((r) => !r.relType.endsWith('/vbaProject')));
         if (bytes !== undefined) {
             this.#preservedReferences.push({
@@ -224,37 +99,12 @@ export class Workbook {
         this.#vbaParsed = false;
         this.#vbaProject = 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() {
         return this.#vbaSignatures().length > 0;
     }
-    /**
-     * 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() {
         return this.#vbaSignatures();
     }
-    // Walk the VBA project's preserved closure for its signature parts — each reached by a signature
-    // relationship off `vbaProject.bin`. Computed on each access rather than memoised: the closure is
-    // small and already in memory, and recomputing sidesteps a cache that a signature-dropping mutation
-    // (`vbaProjectBytes` replace, module remove, reference add) would otherwise have to invalidate.
     #vbaSignatures() {
         const ref = this.#vbaProjectRef();
         const entry = ref?.parts.find((p) => p.path === ref.entryPath);
@@ -271,19 +121,6 @@ export class Workbook {
         }
         return signatures;
     }
-    /**
-     * 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 {VbaAuthorError} if the workbook has no macro project, or `name` is not in the project,
-     *   or names a `document`/`designer` module.
-     * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
-     */
     removeVbaModule(name) {
         const bytes = this.vbaProjectBytes;
         if (bytes === undefined) {
@@ -291,16 +128,6 @@ export class Workbook {
         }
         this.vbaProjectBytes = removeVbaModule(bytes, name);
     }
-    /**
-     * 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 {VbaAuthorError} if the workbook has no macro project, or any field of `ref` is invalid
-     *   (see {@link VbaLibraryReference}).
-     * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
-     */
     addVbaReference(ref) {
         const bytes = this.vbaProjectBytes;
         if (bytes === undefined) {
@@ -315,162 +142,60 @@ export class Workbook {
         const ref = this.#vbaProjectRef();
         return ref?.parts.find((p) => p.path === ref.entryPath);
     }
-    /** The preserved differential-style (`<dxfs>`) fragments, in index order. */
     get differentialStyles() {
         return this.#dxfs;
     }
-    /** The preserved custom indexed-color palette, in index order; empty when the default palette rules. */
     get indexedColors() {
         return this.#indexedColors;
     }
-    /** The preserved most-recently-used colour swatches, in order; empty when the file declared none. */
     get mruColors() {
         return this.#mruColors;
     }
-    /** The preserved `<tableStyles>` block; `styles` is empty when the file declared no custom style. */
     get tableStyles() {
         return this.#tableStyles;
     }
-    // Table styles authored on this workbook, keyed by name so registering the same name twice replaces
-    // rather than duplicates — two definitions sharing a name leave a table's reference ambiguous.
     #customTableStyles = new Map();
-    /**
-     * 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 {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) {
         checkTableStyle(style);
         this.#customTableStyles.set(style.name, style);
     }
-    /** The table styles authored on this workbook, in registration order. */
     get customTableStyles() {
         return [...this.#customTableStyles.values()];
     }
-    /** The preserved theme part, or undefined when the workbook rides the library's default theme. */
     get themePart() {
         return this.#theme;
     }
-    // The theme's colour scheme, decoded from the preserved part (and merged with any authored
-    // overrides) on first use. Cached because resolving a colour is a per-cell operation and the part is
-    // otherwise held as bytes; invalidated whenever the theme is replaced or authored.
     #themeColors;
-    // Colour slots and typefaces the caller authored, merged over whatever the workbook already had.
     #authoredTheme = {
         colors: {},
         fonts: {},
     };
-    /**
-     * 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 {AuthoringError} if a colour is not 6 or 8 hexadecimal digits.
-     */
     setTheme(overrides) {
-        // Validated eagerly, by running the generation the writer will later run: a colour rejected at
-        // write time would surface far from the call that supplied it.
         applyThemeOverrides(this.#baseThemeXml(), overrides);
         Object.assign(this.#authoredTheme.colors, overrides.colors ?? {});
         this.#authoredTheme.fonts = { ...this.#authoredTheme.fonts, ...(overrides.fonts ?? {}) };
         this.#themeColors = undefined;
     }
-    /**
-     * 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() {
         if (this.#themeColors === undefined) {
             const xml = this.#themeXml();
-            // A theme that declares no scheme (or none this reader decodes) falls back to the Office
-            // default rather than resolving nothing: the file still renders against *some* scheme, and the
-            // default is the one the writer would have shipped.
             const parsed = xml === undefined ? {} : parseThemeColorScheme(xml);
             const base = Object.keys(parsed).length === 0 ? DEFAULT_THEME_COLOR_SCHEME : parsed;
             this.#themeColors = { ...base, ...this.#authoredTheme.colors };
         }
         return this.#themeColors;
     }
-    /** The theme's major (heading) and minor (body) typefaces, authored values over the source's. */
     get themeFonts() {
         const xml = this.#themeXml();
         const parsed = xml === undefined ? {} : parseThemeFontScheme(xml);
         const base = Object.keys(parsed).length === 0 ? DEFAULT_THEME_FONTS : parsed;
         return { ...base, ...this.#authoredTheme.fonts };
     }
-    // Font id 0 exactly as a source file declared it, before anything was authored over it. Held apart
-    // from the authored layer because the two answer different questions and only their separation makes
-    // the round-trip faithful: a file's font 0 must ride through untouched, while an authored one must
-    // win. Undefined for a workbook built from scratch, or read from a package with no styles part.
     #declaredDefaultFont;
-    // The facets {@link setDefaultFont} has accumulated, merged in call order. Undefined until a caller
-    // authors one, which is what tells {@link defaultFont} it may re-derive rather than pass through.
     #authoredDefaultFont;
-    /**
-     * 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() {
         return this.#declaredDefaultFont;
     }
-    /**
-     * 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 {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) {
         if (font.size !== undefined && !(Number.isFinite(font.size) && font.size > 0)) {
             throw new AuthoringError(`default font size must be a positive number, not ${font.size}`);
@@ -480,27 +205,6 @@ export class Workbook {
         }
         this.#authoredDefaultFont = { ...this.#authoredDefaultFont, ...font };
     }
-    /**
-     * 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() {
         const declared = this.#declaredDefaultFont;
         const authored = this.#authoredDefaultFont;
@@ -510,8 +214,6 @@ export class Workbook {
         }
         const bodyFace = this.themeFonts.minor ?? OFFICE_BODY_FACE;
         const face = authored?.name ?? authoredFace ?? declared?.name ?? bodyFace;
-        // Size and colour are completed rather than merely merged: a font 0 that states neither is the
-        // "missing default font" foreign readers warn about, so the emitted entry always carries both.
         const font = {
             size: 11,
             color: { theme: 1 },
@@ -534,26 +236,15 @@ export class Workbook {
         }
         return 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() {
         const { colors, fonts } = this.#authoredTheme;
         if (Object.keys(colors).length === 0 && Object.keys(fonts).length === 0)
             return undefined;
         return applyThemeOverrides(this.#baseThemeXml(), { colors, fonts });
     }
-    // The part authored overrides are applied on top of: the preserved source theme, else the default
-    // one the writer would otherwise have emitted.
     #baseThemeXml() {
         return this.#themeXml() ?? DEFAULT_THEME_XML;
     }
-    // The preserved theme part's text, decoded from the entry part of its closure.
     #themeXml() {
         const theme = this.#theme;
         if (theme === undefined)
@@ -561,64 +252,25 @@ export class Workbook {
         const entry = theme.parts.find((part) => part.path === theme.entryPath);
         return entry === undefined ? undefined : new TextDecoder().decode(entry.bytes);
     }
-    /**
-     * 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) {
         return resolveColor(color, { theme: this.themeColors, indexed: this.#indexedPalette() });
     }
-    // The workbook's custom palette as plain ARGB strings. `#indexedColors` holds verbatim
-    // `<rgbColor rgb="…"/>` fragments — the form the writer re-emits — so the value is read out here
-    // rather than stored twice in two shapes that could drift.
     #indexedPalette() {
         return this.#indexedColors.map((fragment) => /\brgb="([^"]*)"/.exec(fragment)?.[1] ?? '');
     }
-    /** The named cell styles, in index order (index 0 is Normal); empty when only the default exists. */
     get namedStyles() {
         return this.#namedStyles;
     }
-    /**
-     * 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) {
         const id = commentThreadGuid(person.id, 'a person id');
         this.#persons.set(id, { ...person, id });
     }
-    /**
-     * 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() {
         return [...this.#persons.values()];
     }
-    /** Look up a registered identity by its {@link Person.id}, or `undefined` if the registry has none. */
     getPerson(id) {
         return this.#persons.get(id);
     }
-    /**
-     * 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) {
         this.#media.push({
             extension: normalizeImageExtension(options.extension, options.buffer),
@@ -626,24 +278,15 @@ export class Workbook {
         });
         return this.#media.length - 1;
     }
-    /** The registered images, indexed by the id {@link addImage} returned. */
     get media() {
         return this.#media;
     }
-    /** Look up a registered image by its id, or `undefined` if no image carries that id. */
     getImage(id) {
         return this.#media[id];
     }
-    /** The workbook's defined names, in the order they were registered. */
     get definedNames() {
         return this.#definedNames;
     }
-    /**
-     * 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.
-     */
     defineName(definedName) {
         if (definedName.name.length === 0) {
             throw new AuthoringError('a defined name cannot be empty');
@@ -653,19 +296,12 @@ export class Workbook {
         }
         this.#definedNames.push(definedName);
     }
-    /**
-     * Create a worksheet and append it to the workbook.
-     *
-     * @throws {AuthoringError} if the name is empty, too long, contains a forbidden character,
-     *   or collides (case-insensitively) with an existing sheet.
-     */
     addWorksheet(name, options = {}) {
         this.#assertValidSheetName(name);
         const sheet = new Worksheet(name, this.#nextSheetId++, options.state ?? 'visible');
         this.#worksheets.push(sheet);
         return sheet;
     }
-    /** Look up a worksheet by name (case-insensitive) or by numeric id. */
     getWorksheet(nameOrId) {
         if (typeof nameOrId === 'number') {
             return this.#worksheets.find((sheet) => sheet.id === nameOrId);
@@ -673,6 +309,17 @@ export class Workbook {
         const target = nameOrId.toLowerCase();
         return this.#worksheets.find((sheet) => sheet.name.toLowerCase() === target);
     }
+    requireWorksheet(nameOrId) {
+        const sheet = this.getWorksheet(nameOrId);
+        if (sheet !== undefined)
+            return sheet;
+        const wanted = typeof nameOrId === 'number' ? `id ${nameOrId}` : JSON.stringify(nameOrId);
+        if (this.#worksheets.length === 0) {
+            throw new AuthoringError(`no worksheet ${wanted}: this workbook has no worksheets`);
+        }
+        const have = this.#worksheets.map((sheet) => JSON.stringify(sheet.name)).join(', ');
+        throw new AuthoringError(`no worksheet ${wanted}; this workbook has ${have}`);
+    }
     #assertValidSheetName(name) {
         if (name.length === 0) {
             throw new AuthoringError('worksheet name cannot be empty');
@@ -690,10 +337,6 @@ export class Workbook {
             throw new AuthoringError(`a worksheet named "${name}" already exists (names are case-insensitive)`);
         }
     }
-    /**
-     * 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.
-     */
     [INTERNAL] = {
         addPreservedReference: (reference) => {
             this.#preservedReferences.push(reference);