@shbernal/ts-xlsx 2.1.0 → 3.1.0

package/dist/core/workbook.d.ts

@@ -1,13 +1,15 @@
 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, type WorksheetImages } from './image.ts';
+import type { DateEpoch } from './date.ts';
+import type { WorkbookImage, 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 { Color, Font } 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 NamedCellStyle, type TableStyleTable } from './workbook-styles.ts';
 import { type DeclaredThemeSchemes } from './workbook-theme.ts';
 import { type Visibility, Worksheet, type WorksheetState } from './worksheet.ts';
 /**
@@ -155,6 +157,25 @@ export declare class Workbook {
      * workbook whose cached results are authoritative stays unmarked.
      */
     fullCalcOnLoad: boolean;
+    /**
+     * Which date system this workbook's serials count in: `1900` (the Windows default) or `1904` (the
+     * `date1904` flag of `<workbookPr>`, Excel for Macintosh's original). It governs every conversion
+     * between a `Date` and the number a cell actually stores, in both directions, so setting it after
+     * cells hold dates changes what those cells mean rather than converting them.
+     *
+     * Read from the file and written back, because dropping it is not a cosmetic loss: the serials stay
+     * as they were and the consumer re-reads them under the other system, so the workbook silently
+     * changes meaning by four years and a day.
+     */
+    dateEpoch: DateEpoch;
+    /**
+     * The workbook's VBA identity (`<workbookPr codeName>`), the name a macro means by `ThisWorkbook`.
+     * Undefined for a workbook with no VBA project, which is what Excel writes for one.
+     *
+     * Preserved rather than modeled: nothing here reads it, but a `.xlsm` whose code name is dropped on
+     * a round trip has had the binding between its macros and its document cut.
+     */
+    codeName?: string;
     /**
      * 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

package/dist/core/workbook.js

@@ -1,11 +1,12 @@
 import { isCustomUiRelType, parseCustomUi } from '../customui/index.js';
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, quoted } from '../errors.js';
 import { addVbaReference, removeVbaModule, } from '../vba/index.js';
 import { commentThreadGuid } from './comment-thread.js';
-import { findRegisteredImage, normalizeImageExtension, } from './image.js';
 import { INTERNAL } from './internal.js';
+import { INVALID_SHEET_NAME_CHARS, MAX_SHEET_NAME_LENGTH } from './limits.js';
 import { checkTableStyle } from './table-style.js';
 import { OFFICE_BODY_FACE, THEME_COLOR_SLOTS, } from './theme.js';
+import { WorkbookMedia } from './workbook-media.js';
 import { WorkbookStyleTables } from './workbook-styles.js';
 import { WorkbookTheme } from './workbook-theme.js';
 import { WorkbookVbaProject } from './workbook-vba.js';
@@ -17,16 +18,16 @@ export const DEFAULT_WORKBOOK_VIEW = {
     height: 12220,
     activeTab: 0,
 };
-const MAX_SHEET_NAME_LENGTH = 31;
-const INVALID_SHEET_NAME_CHARS = /[*?:\\/[\]]/;
 export class Workbook {
     properties = {};
     view = { ...DEFAULT_WORKBOOK_VIEW };
     fullCalcOnLoad = false;
+    dateEpoch = 1900;
+    codeName;
     protection = undefined;
     #worksheets = [];
     #nextSheetId = 1;
-    #media = [];
+    #media = new WorkbookMedia();
     #definedNames = [];
     #styles = new WorkbookStyleTables();
     #theme = new WorkbookTheme(() => this.#styles.indexedPalette());
@@ -37,7 +38,7 @@ export class Workbook {
     }
     get activeTabIndex() {
         const { activeTab } = this.view;
-        return Number.isInteger(activeTab) && activeTab > 0 && activeTab < this.#worksheets.length
+        return Number.isInteger(activeTab) && activeTab >= 0 && activeTab < this.#worksheets.length
             ? activeTab
             : 0;
     }
@@ -180,31 +181,22 @@ export class Workbook {
         return this.#persons.get(id);
     }
     addImage(options) {
-        this.#media.push({
-            extension: normalizeImageExtension(options.extension, options.buffer),
-            data: options.buffer,
-        });
-        return this.#media.length - 1;
+        return this.#media.register(options.extension, options.buffer);
     }
     get media() {
-        return this.#media;
+        return this.#media.all;
     }
     getImage(id) {
-        return this.#media[id];
+        return this.#media.get(id);
     }
     exportImages(sheet) {
-        const resolve = (id) => {
-            const image = this.#media[id];
-            if (image === undefined) {
-                throw new AuthoringError(`worksheet "${sheet.name}" shows image id ${id}, which is not registered on this ` +
-                    "workbook: a sheet's images can only be exported by the workbook that holds them");
-            }
-            return image;
-        };
         const background = sheet.backgroundImageId;
         return {
-            anchored: sheet.images.map(({ imageId, anchor }) => ({ image: resolve(imageId), anchor })),
-            background: background === undefined ? undefined : resolve(background),
+            anchored: sheet.images.map(({ imageId, anchor }) => ({
+                image: this.#media.require(imageId, sheet.name),
+                anchor,
+            })),
+            background: background === undefined ? undefined : this.#media.require(background, sheet.name),
         };
     }
     importImages(sheet, images) {
@@ -212,20 +204,12 @@ export class Workbook {
             sheet.removeImage(id);
         sheet.removeBackgroundImage();
         for (const { image, anchor } of images.anchored) {
-            sheet.addImageAnchor(this.#registerImage(image), anchor);
+            sheet.addImageAnchor(this.#media.registerExisting(image), anchor);
         }
         if (images.background !== undefined) {
-            sheet.addBackgroundImage(this.#registerImage(images.background));
+            sheet.addBackgroundImage(this.#media.registerExisting(images.background));
         }
     }
-    #registerImage(image) {
-        const candidate = {
-            extension: normalizeImageExtension(image.extension, image.data),
-            data: image.data,
-        };
-        return (findRegisteredImage(this.#media, candidate) ??
-            this.addImage({ buffer: candidate.data, extension: candidate.extension }));
-    }
     get definedNames() {
         return this.#definedNames;
     }
@@ -234,7 +218,7 @@ export class Workbook {
             throw new AuthoringError('a defined name cannot be empty');
         }
         if (definedName.scope !== undefined && this.getWorksheet(definedName.scope) === undefined) {
-            throw new AuthoringError(`defined name "${definedName.name}" is scoped to unknown worksheet "${definedName.scope}"`);
+            throw new AuthoringError(`defined name ${quoted(definedName.name)} is scoped to unknown worksheet ${quoted(definedName.scope)}`);
         }
         this.#definedNames.push(definedName);
     }
@@ -255,11 +239,11 @@ export class Workbook {
         const sheet = this.getWorksheet(nameOrId);
         if (sheet !== undefined)
             return sheet;
-        const wanted = typeof nameOrId === 'number' ? `id ${nameOrId}` : JSON.stringify(nameOrId);
+        const wanted = typeof nameOrId === 'number' ? `id ${nameOrId}` : quoted(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(', ');
+        const have = this.#worksheets.map((sheet) => quoted(sheet.name)).join(', ');
         throw new AuthoringError(`no worksheet ${wanted}; this workbook has ${have}`);
     }
     #assertValidSheetName(name) {
@@ -267,16 +251,16 @@ export class Workbook {
             throw new AuthoringError('worksheet name cannot be empty');
         }
         if (name.length > MAX_SHEET_NAME_LENGTH) {
-            throw new AuthoringError(`worksheet name "${name}" exceeds the ${MAX_SHEET_NAME_LENGTH}-character limit`);
+            throw new AuthoringError(`worksheet name ${quoted(name)} exceeds the ${MAX_SHEET_NAME_LENGTH}-character limit`);
         }
         if (INVALID_SHEET_NAME_CHARS.test(name)) {
-            throw new AuthoringError(`worksheet name "${name}" contains a character Excel forbids (* ? : \\ / [ ])`);
+            throw new AuthoringError(`worksheet name ${quoted(name)} contains a character Excel forbids (* ? : \\ / [ ])`);
         }
         if (name.startsWith("'") || name.endsWith("'")) {
-            throw new AuthoringError(`worksheet name "${name}" cannot start or end with an apostrophe`);
+            throw new AuthoringError(`worksheet name ${quoted(name)} cannot start or end with an apostrophe`);
         }
         if (this.getWorksheet(name) !== undefined) {
-            throw new AuthoringError(`a worksheet named "${name}" already exists (names are case-insensitive)`);
+            throw new AuthoringError(`a worksheet named ${quoted(name)} already exists (names are case-insensitive)`);
         }
     }
     [INTERNAL] = {

package/dist/core/worksheet-comments.d.ts

@@ -1,4 +1,5 @@
 import { type CommentThread } from './comment-thread.ts';
+import { type AxisSplice } from './grid-shift.ts';
 export declare class WorksheetComments {
     #private;
     constructor(sheetName: () => string);
@@ -12,6 +13,6 @@ export declare class WorksheetComments {
      * the cell, so a thread left behind would put a note on one cell and its conversation on another,
      * a pairing the writer emits and Excel refuses.
      */
-    shift(axis: 'row' | 'col', start: number, count: number, delta: number): void;
+    shift(splice: AxisSplice): void;
     restore(threads: readonly CommentThread[]): void;
 }

package/dist/core/worksheet-comments.js

@@ -1,10 +1,12 @@
+import { quoted } from '../errors.js';
 import { decodeCellRef, encodeAddress } from './address.js';
 import { commentThreadGuid, commentThreadOffset } from './comment-thread.js';
 import { replaceContents } from './containers.js';
-import { isDeletedSpan, shiftIndex } from './grid-shift.js';
+import { shiftPoint } from './grid-shift.js';
 export class WorksheetComments {
     #sheetName;
     #threads = [];
+    #takenIds = new Set();
     constructor(sheetName) {
         this.#sheetName = sheetName;
     }
@@ -12,14 +14,14 @@ export class WorksheetComments {
         return this.#threads;
     }
     add(thread) {
-        const taken = new Set(this.#threads.flatMap((held) => held.comments.map((comment) => comment.id)));
+        const claimed = new Set();
         const comments = thread.comments.map((comment) => {
             const id = commentThreadGuid(comment.id, 'a comment id');
-            if (taken.has(id)) {
-                throw new SyntaxError(`a comment id must be unique within a sheet, but "${id}" is already used on "${this.#sheetName()}": ` +
+            if (this.#takenIds.has(id) || claimed.has(id)) {
+                throw new SyntaxError(`a comment id must be unique within a sheet, but ${quoted(id)} is already used on ${quoted(this.#sheetName())}: ` +
                     'a reply and the legacy fallback comment both find their thread by it');
             }
-            taken.add(id);
+            claimed.add(id);
             return {
                 ...comment,
                 id,
@@ -38,30 +40,35 @@ export class WorksheetComments {
             };
         });
         this.#threads.push({ ...thread, ref: anchorRef(thread.ref), comments });
+        for (const id of claimed)
+            this.#takenIds.add(id);
     }
     at(reference) {
         const anchor = anchorRef(reference);
         return this.#threads.find((thread) => thread.ref === anchor);
     }
-    shift(axis, start, count, delta) {
+    shift(splice) {
         const survivors = [];
         for (const thread of this.#threads) {
-            const { col, row } = decodeCellRef(thread.ref);
-            const line = axis === 'row' ? row : col;
-            if (isDeletedSpan(line, line, start, count))
+            const anchor = decodeCellRef(thread.ref);
+            const moved = shiftPoint(anchor, splice);
+            if (moved === undefined)
                 continue;
-            const moved = shiftIndex(line, start, count, delta, axis);
-            if (moved === line) {
+            if (moved.col === anchor.col && moved.row === anchor.row) {
                 survivors.push(thread);
                 continue;
             }
-            const ref = axis === 'row' ? encodeAddress(col, moved) : encodeAddress(moved, row);
-            survivors.push({ ...thread, ref });
+            survivors.push({ ...thread, ref: encodeAddress(moved.col, moved.row) });
         }
         replaceContents(this.#threads, survivors);
     }
     restore(threads) {
         replaceContents(this.#threads, threads);
+        this.#takenIds.clear();
+        for (const thread of threads) {
+            for (const comment of thread.comments)
+                this.#takenIds.add(comment.id);
+        }
     }
 }
 function anchorRef(reference) {

package/dist/core/worksheet-merges.d.ts

@@ -0,0 +1,44 @@
+import type { MergeRect } from './merge.ts';
+/** What removing a declared range did, which is two answers because a range and a rectangle are not
+ * the same thing: an unbounded whole-row/column merge is declared but has no rectangle, so dropping
+ * it leaves every geometry derived from the rectangles (the used extent, the index) still valid. */
+export interface MergeRemoval {
+    /** Whether a merge with this exact range string was declared. */
+    readonly existed: boolean;
+    /** Whether a rectangle went with it, so anything derived from the rectangles is now stale. */
+    readonly rectsChanged: boolean;
+}
+export declare class WorksheetMerges {
+    #private;
+    /** The declared ranges, in the order they were added. Live, not a copy. */
+    get ranges(): readonly string[];
+    /**
+     * The bounded regions as rectangles. Live, and its *identity* is stable for the sheet's lifetime:
+     * {@link UsedExtent} holds this array by reference, so every rewrite here goes through
+     * `replaceContents` rather than reassignment.
+     */
+    get rects(): readonly MergeRect[];
+    /**
+     * Declare a merged range, returning the rectangle it covers, or `undefined` for an unbounded
+     * whole-row/column range, which is declared and overlap-checks against nothing.
+     *
+     * @throws {AuthoringError} if the range overlaps an already-merged region. Excel forbids
+     *   overlapping merges and writes such geometry as a file it then offers to repair.
+     */
+    add(range: string): MergeRect | undefined;
+    /** Drop a declared range and, with it, the rectangle it covers. The inverse of {@link add}. */
+    remove(range: string): MergeRemoval;
+    /**
+     * Resolve a position to the top-left of the region covering it, or to itself when none does. This
+     * is what makes a write through a covered address land on the region's master.
+     */
+    masterOf(row: number, col: number): {
+        row: number;
+        col: number;
+    };
+    /** Replace every declared range and rectangle at once: what a structural splice re-anchors to. */
+    replaceAll(ranges: readonly string[], rects: readonly MergeRect[]): void;
+    /** Report that something outside has rewritten the grid under these regions. */
+    invalidate(): void;
+    clear(): void;
+}

package/dist/core/worksheet-merges.js

@@ -0,0 +1,59 @@
+import { AuthoringError, quoted } from '../errors.js';
+import { boundedRect, decodeRange } from './address.js';
+import { replaceContents } from './containers.js';
+import { MergeIndex } from './merge-index.js';
+export class WorksheetMerges {
+    #ranges = [];
+    #rects = [];
+    #index = new MergeIndex(this.#rects);
+    get ranges() {
+        return this.#ranges;
+    }
+    get rects() {
+        return this.#rects;
+    }
+    add(range) {
+        const rect = boundedRect(decodeRange(range));
+        if (rect !== undefined) {
+            if (this.#index.overlapping(rect) !== undefined) {
+                throw new AuthoringError(`merged range ${quoted(range)} overlaps an existing merged region`);
+            }
+            this.#rects.push(rect);
+            this.#index.note(rect);
+        }
+        this.#ranges.push(range);
+        return rect;
+    }
+    remove(range) {
+        const index = this.#ranges.indexOf(range);
+        if (index === -1)
+            return { existed: false, rectsChanged: false };
+        this.#ranges.splice(index, 1);
+        const rect = boundedRect(decodeRange(range));
+        if (rect === undefined)
+            return { existed: true, rectsChanged: false };
+        const { top, left, bottom, right } = rect;
+        const at = this.#rects.findIndex((r) => r.top === top && r.left === left && r.bottom === bottom && r.right === right);
+        if (at === -1)
+            return { existed: true, rectsChanged: false };
+        this.#rects.splice(at, 1);
+        this.#index.invalidate();
+        return { existed: true, rectsChanged: true };
+    }
+    masterOf(row, col) {
+        return this.#index.masterOf(row, col);
+    }
+    replaceAll(ranges, rects) {
+        replaceContents(this.#ranges, ranges);
+        replaceContents(this.#rects, rects);
+        this.#index.invalidate();
+    }
+    invalidate() {
+        this.#index.invalidate();
+    }
+    clear() {
+        this.#ranges.length = 0;
+        this.#rects.length = 0;
+        this.#index.invalidate();
+    }
+}

package/dist/core/worksheet-model.d.ts

@@ -3,7 +3,15 @@ import type { Worksheet, WorksheetModel } from './worksheet.ts';
 /** One field of a {@link WorksheetModel}, with both directions of its round-trip declared together. */
 interface ModelFacet<K extends keyof WorksheetModel = keyof WorksheetModel> {
     readonly key: K;
-    /** Produce the field's value, copied deeply enough that mutating it cannot reach back into the sheet. */
+    /**
+     * Produce the field's value, in a form a caller cannot mutate the sheet through.
+     *
+     * Copying is one way to get there and the type is the other. `tabColor`, `autoFilter` and
+     * `protection` are handed back by reference precisely because their types are readonly all the way
+     * down, so there is nothing to defend against and a clone would only be one more shape to keep in
+     * step with its declaration. Every other field is a mutable record or array and is copied, which is
+     * where the spreads below come from.
+     */
     readonly read: (sheet: Worksheet) => WorksheetModel[K];
     /**
      * Apply the field to a sheet whose content has already been reset. Takes the whole model rather

package/dist/core/worksheet-model.js

@@ -6,6 +6,21 @@ import { INTERNAL } from './internal.js';
 function facet(key, read, write) {
     return { key, read, write: (sheet, model) => write(sheet, model[key]) };
 }
+function recordFacet(key) {
+    return {
+        key,
+        read: (sheet) => ({ ...sheet[key] }),
+        write: (sheet, model) => overwrite(sheet[key], model[key]),
+    };
+}
+function recordsFacet(key) {
+    const copy = (breaks) => breaks.map((brk) => ({ ...brk }));
+    return {
+        key,
+        read: (sheet) => copy(sheet[key]),
+        write: (sheet, model) => replaceContents(sheet[key], copy(model[key])),
+    };
+}
 export const WORKSHEET_MODEL_FACETS = [
     facet('state', (sheet) => sheet.state, (sheet, value) => {
         sheet.state = value;
@@ -13,15 +28,15 @@ export const WORKSHEET_MODEL_FACETS = [
     facet('tabColor', (sheet) => sheet.tabColor, (sheet, value) => {
         sheet.tabColor = value;
     }),
-    facet('properties', (sheet) => ({ ...sheet.properties }), (sheet, value) => overwrite(sheet.properties, value)),
-    facet('outline', (sheet) => ({ ...sheet.outline }), (sheet, value) => overwrite(sheet.outline, value)),
-    facet('view', (sheet) => ({ ...sheet.view }), (sheet, value) => overwrite(sheet.view, value)),
-    facet('pageSetup', (sheet) => ({ ...sheet.pageSetup }), (sheet, value) => overwrite(sheet.pageSetup, value)),
-    facet('printOptions', (sheet) => ({ ...sheet.printOptions }), (sheet, value) => overwrite(sheet.printOptions, value)),
-    facet('pageMargins', (sheet) => ({ ...sheet.pageMargins }), (sheet, value) => overwrite(sheet.pageMargins, value)),
-    facet('headerFooter', (sheet) => ({ ...sheet.headerFooter }), (sheet, value) => overwrite(sheet.headerFooter, value)),
-    facet('rowBreaks', (sheet) => sheet.rowBreaks.map((brk) => ({ ...brk })), (sheet, value) => replaceContents(sheet.rowBreaks, value.map((brk) => ({ ...brk })))),
-    facet('columnBreaks', (sheet) => sheet.columnBreaks.map((brk) => ({ ...brk })), (sheet, value) => replaceContents(sheet.columnBreaks, value.map((brk) => ({ ...brk })))),
+    recordFacet('properties'),
+    recordFacet('outline'),
+    recordFacet('view'),
+    recordFacet('pageSetup'),
+    recordFacet('printOptions'),
+    recordFacet('pageMargins'),
+    recordFacet('headerFooter'),
+    recordsFacet('rowBreaks'),
+    recordsFacet('columnBreaks'),
     facet('columns', (sheet) => [...sheet.columns()].map(({ index, properties }) => ({ index, properties: { ...properties } })), (sheet, value) => {
         for (const { index, properties } of value)
             Object.assign(sheet.getColumn(index), properties);

package/dist/core/worksheet.d.ts

@@ -12,7 +12,7 @@ import type { PreservedWorksheetReference } from './preserved.ts';
 import { type SheetProtection, type SheetProtectionOptions } from './protection.ts';
 import { Range } from './range.ts';
 import { Row } from './row.ts';
-import type { CellStyle, Color, Fill } from './style.ts';
+import type { CellContent, CellStyle, Color, Fill } from './style.ts';
 import { Table, type TableOptions } from './table.ts';
 import type { CellValue } from './value.ts';
 /**
@@ -24,7 +24,7 @@ import type { CellValue } from './value.ts';
  */
 export type Visibility = 'visible' | 'hidden' | 'veryHidden';
 /** Narrow a raw `<sheet state>` or `<workbookView visibility>` token to a known {@link Visibility}. */
-export declare function isVisibility(value: string): value is Visibility;
+export declare const isVisibility: (value: string) => value is Visibility;
 export interface WorksheetState {
     /** Sheet visibility, as Excel models it. Defaults to `visible`. */
     readonly state: Visibility;
@@ -107,8 +107,13 @@ export interface RowProperties {
     /** Background fill applied to the row's cells that carry no fill of their own. */
     fill?: Fill;
 }
-/** One materialised cell in a {@link WorksheetModel}: its position, value, and per-cell style facets. */
-export interface CellModel extends CellStyle {
+/**
+ * One materialised cell in a {@link WorksheetModel}: its position, value, note, and every facet of its
+ * formatting. Extends {@link CellContent} rather than {@link CellStyle} so the quote-prefix flag and
+ * the named-style link travel with a model round-trip: they are written and read back like any other
+ * facet, and leaving them off the tuple is what made a `dst.model = src.model` drop them.
+ */
+export interface CellModel extends CellContent {
     readonly row: number;
     readonly col: number;
     value: CellValue;
@@ -177,6 +182,17 @@ export declare class Worksheet {
      * never fabricates one.
      */
     tabColor: Color | undefined;
+    /**
+     * The sheet's VBA identity (`<sheetPr codeName>`), the name a macro means by `Sheet1`. Undefined
+     * for a sheet in a workbook with no VBA project, which is what Excel writes for one.
+     *
+     * Preserved rather than modeled: nothing here reads it, but a `.xlsm` whose sheet code names are
+     * dropped on a round trip has had the binding between its macros and its sheets cut. Deliberately
+     * absent from {@link WorksheetModel}, which is the copy shape: a code name identifies *this* sheet
+     * to the workbook's VBA project, so copying it onto a second sheet would give the project two
+     * sheets answering to one name.
+     */
+    codeName?: string;
     /** Sheet-level format defaults. Mutate in place: `sheet.properties.defaultRowHeight = 20`. */
     readonly properties: WorksheetProperties;
     /**
@@ -267,6 +283,7 @@ export declare class Worksheet {
      *
      * @throws {SyntaxError} if the reference is unparseable, names another worksheet, or leaves an
      *   axis unbounded.
+     * @throws {AuthoringError} if the numeric form is called with fewer than four corners.
      * @throws {RangeError} if a numeric corner is not a positive integer within the sheet's bounds.
      */
     getRange(reference: string): Range;
@@ -276,14 +293,21 @@ export declare class Worksheet {
      * or 0 for an empty sheet. Spans gaps: a value in row 5 makes this 5 even if rows 2–4
      * are empty. This is the used-range extent, not a populated-row tally (see
      * {@link actualRowCount}).
+     *
+     * *Carrying anything* is deliberately wide: a value, a cell's own style facet, quote-prefix flag
+     * or named-style link, a note, a row height or outline level, or a merge reaching down. Styling a
+     * band of empty rows is how a template is laid out, so those rows are used and {@link addRow}
+     * appends past them. A cell merely materialised by {@link getCell} and left untouched carries
+     * nothing, so reading a far address never grows the sheet.
      */
     get rowCount(): number;
     /** The number of rows that hold at least one non-empty cell, ignoring gaps and formatting-only rows. */
     get actualRowCount(): number;
     /**
-     * The 1-based index of the last column carrying anything (a non-empty cell or its own format
+     * The 1-based index of the last column carrying anything (a used cell or the column's own format
      * properties), or 0 for an empty sheet. The used-range width, mirroring {@link rowCount} for the
-     * other axis: a value in column E makes this 5 even if columns B–D are empty.
+     * other axis, down to what *carrying anything* means: a value in column E makes this 5 even if
+     * columns B–D are empty, and a column holding nothing but a styled empty cell is still used.
      */
     get columnCount(): number;
     /**
@@ -505,6 +529,9 @@ export declare class Worksheet {
      * shift with the rows they cover.
      *
      * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
+     * @throws {RangeError} if an inserted row would land past the last row of the grid. The sheet is
+     *   left untouched, so this is a refused edit rather than half of one: a region pushed off the edge
+     *   clamps and absorbs the loss, but content pushed off it is what Excel refuses outright.
      */
     spliceRows(start: number, count: number, ...inserts: RowInput[]): void;
     /**
@@ -548,9 +575,13 @@ export declare class Worksheet {
     /**
      * Copy the row at the 1-based `start`, `options.count` times (default 1). With `options.insert`
      * (the default) the copies are inserted directly after the source, shifting the rows below, and
-     * any merged range there, down by `count`; otherwise the copies overwrite the rows immediately
-     * below without shifting. Each copy is a faithful duplicate of the source's values and per-cell
-     * styles, and carries no merge of its own, so a range can be merged onto a duplicated row afterwards.
+     * any merged range there, down by `count`; otherwise the copies *replace* the rows immediately
+     * below without shifting. A destination row is not overlaid but wholly re-made, so a cell it held
+     * in a column the source leaves empty is dropped, exactly as it would be with a shifting insert.
+     *
+     * Each copy is a faithful duplicate of the source: its cell values, its per-cell styles, and its
+     * row properties (height, hidden, outline level, row fill). It carries no merge of its own, so a
+     * range can be merged onto a duplicated row afterwards.
      *
      * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
      */
@@ -566,6 +597,10 @@ export declare class Worksheet {
      * indexed by row (index 0 → row 1); an empty array inserts a blank column.
      *
      * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
+     * @throws {RangeError} if an inserted column would land past the last column, or one of its values
+     *   past the last row. The sheet is left untouched, so this is a refused edit rather than half of
+     *   one: a region pushed off the edge clamps and absorbs the loss, but content pushed off it is
+     *   what Excel refuses outright, and {@link addColumn} refuses the same argument identically.
      */
     spliceColumns(start: number, count: number, ...inserts: CellValue[][]): void;
     /**
@@ -573,7 +608,8 @@ export declare class Worksheet {
      * by one. `values` is an array of values indexed by row (index 0 → row 1), like
      * {@link addColumn}. Shorthand for {@link spliceColumns}`(pos, 0, values)`.
      *
-     * @throws {RangeError} if `pos` is not a positive integer.
+     * @throws {RangeError} if `pos` is not a positive integer, or if the column would land past the
+     *   last column or one of its values past the last row; see {@link spliceColumns}.
      */
     insertColumn(pos: number, values: CellValue[]): void;
     /**
@@ -682,18 +718,42 @@ export interface WorksheetInternals {
      */
     cellAt(row: number, col: number): Cell;
     /**
-     * The store behind a {@link Row} or {@link Column} handle. These six exist because the handles are
+     * The cell materialised at a position, or `undefined` when nothing has been written there.
+     *
+     * Merge-blind and non-materialising, which is what separates it from `Worksheet.getCell`: that
+     * resolves a covered address to its merge master, so `hasCell(row, col)` followed by a `getCell` of
+     * the same position can hand back a *different* cell. A caller walking a rectangle got the master
+     * once per covered position and never saw the covered cells at all, which made a `clearStyle` over a
+     * merge clear the master repeatedly and the covered cells not once. A caller that wants merge
+     * resolution keeps `getCell`; a caller enumerating what is actually stored wants this.
+     */
+    peekCell(row: number, col: number): Cell | undefined;
+    /**
+     * {@link cellAt} with merge resolution: the cell a write to this position lands on, materialised.
+     *
+     * What {@link Worksheet.getCell} does, minus the address. `getCell` is the public spelling and takes
+     * an A1 reference, so a caller already holding a row and a column had to encode one and have it
+     * decoded straight back. That round-trip costs about three times a positional read, and a
+     * {@link Range} write performs one per cell: styling a 100x100 block spent 10,000 encodes and 10,000
+     * regex decodes on positions it already had.
+     */
+    masterAt(row: number, col: number): Cell;
+    /**
+     * The store behind a {@link Row} or {@link Column} handle. These exist because the handles are
      * views rather than records: they hold a sheet and a position, and every read and write goes
      * through here to the one authoritative map. `…PropertiesOf` never fabricates, so reading a row
      * cannot extend the used range; `ensure…` is what a write calls, so the record appears exactly
-     * when a value is set.
+     * when a value is set; `drop…` is what clearing the last field calls, so the record disappears
+     * exactly when the line stops being formatted, which is what keeps the used range honest.
      */
     rowPropertiesOf(number: number): RowProperties | undefined;
     ensureRowProperties(number: number): RowProperties;
+    dropRowProperties(number: number): void;
     /** The row's materialised cells in ascending column order. */
     rowCells(number: number): Cell[];
     columnPropertiesOf(index: number): ColumnProperties | undefined;
     ensureColumnProperties(index: number): ColumnProperties;
+    dropColumnProperties(index: number): void;
     /** The column's materialised cells in ascending row order. */
     columnCells(index: number): Cell[];
 }