@shbernal/ts-xlsx 3.0.0 → 3.2.0

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
@@ -23,7 +31,7 @@ interface ModelFacet<K extends keyof WorksheetModel = keyof WorksheetModel> {
  * load-bearing: cells are placed at their exact positions before any merge exists, so a covered
  * cell's value lands where the model says instead of being routed to a region master mid-load.
  */
-export declare const WORKSHEET_MODEL_FACETS: (ModelFacet<"autoFilter"> | ModelFacet<"cells"> | ModelFacet<"columnBreaks"> | ModelFacet<"columns"> | ModelFacet<"conditionalFormattings"> | ModelFacet<"dataValidations"> | ModelFacet<"headerFooter"> | ModelFacet<"merges"> | ModelFacet<"outline"> | ModelFacet<"pageMargins"> | ModelFacet<"pageSetup"> | ModelFacet<"printOptions"> | ModelFacet<"properties"> | ModelFacet<"protection"> | ModelFacet<"rowBreaks"> | ModelFacet<"rows"> | ModelFacet<"state"> | ModelFacet<"tabColor"> | ModelFacet<"tables"> | ModelFacet<"view">)[];
+export declare const WORKSHEET_MODEL_FACETS: (ModelFacet<"autoFilter"> | ModelFacet<"cells"> | ModelFacet<"columnBreaks"> | ModelFacet<"columns"> | ModelFacet<"conditionalFormattings"> | ModelFacet<"dataValidations"> | ModelFacet<"headerFooter"> | ModelFacet<"hyperlinks"> | ModelFacet<"merges"> | ModelFacet<"outline"> | ModelFacet<"pageMargins"> | ModelFacet<"pageSetup"> | ModelFacet<"printOptions"> | ModelFacet<"properties"> | ModelFacet<"protection"> | ModelFacet<"rowBreaks"> | ModelFacet<"rows"> | ModelFacet<"state"> | ModelFacet<"tabColor"> | ModelFacet<"tables"> | ModelFacet<"view">)[];
 /**
  * Compile-time proof that {@link WORKSHEET_MODEL_FACETS} covers every {@link WorksheetModel} field.
  * A field added without a facet resolves this to that field's name, which does not satisfy `never`,

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);
@@ -51,6 +66,10 @@ export const WORKSHEET_MODEL_FACETS = [
         for (const range of value)
             sheet.mergeCells(range);
     }),
+    facet('hyperlinks', (sheet) => sheet.hyperlinks.map((link) => ({ ...link })), (sheet, value) => {
+        for (const link of value)
+            sheet.addHyperlink(link);
+    }),
     facet('dataValidations', (sheet) => sheet.dataValidations.map(({ sqref, rule, extended }) => ({
         sqref,
         rule: cloneDataValidation(rule),

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

@@ -1,4 +1,4 @@
-import { type AnchoredImage, type AnchorPoint, type ImageAnchor, type ImageEditAs } from './image.ts';
+import { type AnchoredImage, type AnchorPoint, type ImageAnchor, type ImageEditAs, type PictureProperties } from './image.ts';
 /** The two shapes {@link WorksheetPictures.add} accepts, in caller-facing pixel units. */
 export type PixelAnchor = {
     readonly tl: AnchorPoint;
@@ -22,8 +22,8 @@ export declare class WorksheetPictures {
     /** The anchored images, in the order they were added. */
     get anchors(): AnchoredImage[];
     get backgroundImageId(): number | undefined;
-    add(imageId: number, anchor: PixelAnchor): void;
-    addAnchor(imageId: number, anchor: ImageAnchor): void;
+    add(imageId: number, anchor: PixelAnchor, properties?: PictureProperties): void;
+    addAnchor(imageId: number, anchor: ImageAnchor, properties?: PictureProperties): void;
     remove(imageId: number): void;
     setBackground(imageId: number | undefined): void;
 }

package/dist/core/worksheet-pictures.js

@@ -1,5 +1,5 @@
 import { replaceContents } from './containers.js';
-import { PX_TO_EMU, resolveAnchorPoint, } from './image.js';
+import { pictureProperties, PX_TO_EMU, resolveAnchorPoint, } from './image.js';
 export class WorksheetPictures {
     #metrics;
     #anchors = [];
@@ -13,7 +13,8 @@ export class WorksheetPictures {
     get backgroundImageId() {
         return this.#backgroundImageId;
     }
-    add(imageId, anchor) {
+    add(imageId, anchor, properties = {}) {
+        const picture = pictureProperties(properties);
         const columnWidth = (col) => this.#metrics.columnWidth(col);
         const rowHeight = (row) => this.#metrics.rowHeight(row);
         if ('ext' in anchor) {
@@ -22,16 +23,16 @@ export class WorksheetPictures {
                 cy: Math.round(anchor.ext.height * PX_TO_EMU),
             };
             const from = resolveAnchorPoint(anchor.tl, columnWidth, rowHeight);
-            this.#anchors.push({ imageId, anchor: { from, ext } });
+            this.#anchors.push({ imageId, anchor: { from, ext }, ...picture });
             return;
         }
         const from = resolveAnchorPoint(anchor.tl, columnWidth, rowHeight);
         const to = resolveAnchorPoint(anchor.br, columnWidth, rowHeight);
         const twoCell = anchor.editAs !== undefined ? { from, to, editAs: anchor.editAs } : { from, to };
-        this.#anchors.push({ imageId, anchor: twoCell });
+        this.#anchors.push({ imageId, anchor: twoCell, ...picture });
     }
-    addAnchor(imageId, anchor) {
-        this.#anchors.push({ imageId, anchor });
+    addAnchor(imageId, anchor, properties = {}) {
+        this.#anchors.push({ imageId, anchor, ...pictureProperties(properties) });
     }
     remove(imageId) {
         replaceContents(this.#anchors, this.#anchors.filter((image) => image.imageId !== imageId));

package/dist/core/worksheet.d.ts

@@ -4,7 +4,9 @@ import { Column } from './column.ts';
 import type { CommentThread } from './comment-thread.ts';
 import type { ConditionalFormatting } from './conditional-formatting.ts';
 import type { DataValidation, DataValidationEntry } from './data-validation.ts';
-import type { AnchoredImage, AnchorPoint, ImageAnchor, ImageEditAs } from './image.ts';
+import { type SheetSplice } from './formula-references.ts';
+import { type Hyperlink } from './hyperlink.ts';
+import type { AnchoredImage, AnchorPoint, ImageAnchor, ImageEditAs, PictureProperties } from './image.ts';
 import { INTERNAL } from './internal.ts';
 import type { HeaderFooter, PageBreak, PageMargins, PageSetup, PrintOptions } from './page-setup.ts';
 import { type ParsedPivotTable, PivotTable, type PivotTableOptions } from './pivot-table.ts';
@@ -12,9 +14,9 @@ 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';
+import { type CellValue } from './value.ts';
 /**
  * Whether a thing Excel can hide is showing: a sheet's tab, or the document window itself.
  *
@@ -107,8 +109,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;
@@ -159,6 +166,7 @@ export interface WorksheetModel {
     }[];
     cells: CellModel[];
     merges: string[];
+    hyperlinks: Hyperlink[];
     dataValidations: DataValidationEntry[];
     conditionalFormattings: ConditionalFormatting[];
     tables: TableOptions[];
@@ -177,6 +185,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;
     /**
@@ -206,15 +225,17 @@ export declare class Worksheet {
     /** Page header/footer text. Mutate in place: `sheet.headerFooter.oddHeader = '&C&"..."'`. */
     readonly headerFooter: HeaderFooter;
     /**
-     * Manual horizontal page breaks (`<rowBreaks>`): each break's `id` is a row the print layout splits
-     * before. Mutate in place: `sheet.rowBreaks.push({id: 3})`. Empty means no manual row breaks and the
-     * writer emits no `<rowBreaks>` element.
+     * Horizontal page breaks (`<rowBreaks>`): each break's `id` is the last row before it, so
+     * `sheet.rowBreaks.push({id: 3})` starts a new printed page at row 4. Mutate in place. A row splice
+     * moves a break with the row after it. Empty means no row breaks and the writer emits no
+     * `<rowBreaks>` element.
      */
     readonly rowBreaks: PageBreak[];
     /**
-     * Manual vertical page breaks (`<colBreaks>`): each break's `id` is a column the print layout splits
-     * before. Mutate in place: `sheet.columnBreaks.push({id: 3})`. Empty means no manual column breaks and
-     * the writer emits no `<colBreaks>` element.
+     * Vertical page breaks (`<colBreaks>`): each break's `id` is the last column before it, so
+     * `sheet.columnBreaks.push({id: 3})` starts a new printed page at column D. Mutate in place. A column
+     * splice moves a break with the column after it. Empty means no column breaks and the writer emits
+     * no `<colBreaks>` element.
      */
     readonly columnBreaks: PageBreak[];
     constructor(name: string, id: number, state?: WorksheetState['state']);
@@ -267,6 +288,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;
@@ -341,7 +363,8 @@ export declare class Worksheet {
     getTable(name: string): Table | undefined;
     /**
      * Add a pivot table to this (destination) sheet, summarising a source sheet's data. The source is
-     * read once, now, so the pivot is a snapshot: later edits to the source do not change it. The
+     * read once, now, so the pivot is a snapshot: later edits to the source's values do not change it,
+     * while a row or column splice of the source sheet moves its {@link PivotTable.sourceRef}. The
      * supported shape (one summed value field, at least one row and column field) is enforced here.
      *
      * @throws {AuthoringError} if the metric, fields, or source shape are unsupported.
@@ -354,7 +377,9 @@ export declare class Worksheet {
      * read-only inspection view (source range, field roles, value field, aggregation). A pivot
      * authored on this sheet via {@link addPivotTable} does not appear here; a pivot loaded from a
      * file does not appear in {@link pivotTables}. The loaded pivots re-emit verbatim through
-     * byte-preservation, so this collection is never itself serialised.
+     * byte-preservation, so this collection is never itself serialised. A row or column splice of a
+     * pivot's source sheet moves its {@link ParsedPivotSource.ref} here and in the cache the writer
+     * emits, by one rule, so the view says what is written.
      */
     get loadedPivotTables(): readonly ParsedPivotTable[];
     /**
@@ -366,7 +391,8 @@ export declare class Worksheet {
      * Every message supplies its own {@link Comment.id} and {@link Comment.date}, and names its author by
      * {@link Comment.personId} into the workbook registry ({@link Workbook.addPerson}): the writer has no
      * clock and no id generator, so nothing here is invented and the same workbook always serialises to the
-     * same bytes. Every id is normalised to the brace-wrapped upper-case GUID form the format requires, so a
+     * same bytes. An author id nobody registered is refused when the workbook is written, where the
+     * registry is complete; a message with no `personId` is written as Excel writes an unknown author. Every id is normalised to the brace-wrapped upper-case GUID form the format requires, so a
      * `crypto.randomUUID()` is accepted as-is.
      *
      * Message ids must be unique **within this sheet**, because that is the scope in which they mean
@@ -404,25 +430,33 @@ export declare class Worksheet {
      *
      * Grid points are 0-based (`{col: 0, row: 0}` is cell A1). A later row/column splice re-pins the
      * anchor to the same logical position.
+     *
+     * `properties` gives the picture alternative text and a title, crops it, or makes it a link; see
+     * {@link PictureProperties}.
+     *
+     * A sheet read from a file keeps its drawing whole when the drawing holds a chart, a shape or other
+     * content the library does not model. A picture added to such a sheet is written into that drawing,
+     * beside what it holds, and read back it is part of the kept drawing rather than one of
+     * {@link images}.
      */
     addImage(imageId: number, anchor: {
         readonly tl: AnchorPoint;
         readonly br: AnchorPoint;
         readonly editAs?: ImageEditAs;
-    }): void;
+    }, properties?: PictureProperties): void;
     addImage(imageId: number, anchor: {
         readonly tl: AnchorPoint;
         readonly ext: {
             readonly width: number;
             readonly height: number;
         };
-    }): void;
+    }, properties?: PictureProperties): void;
     /**
      * Anchor an image with a pre-built model anchor in the model's own units (EMUs). This is the
      * low-level primitive {@link addImage} builds on and the reader uses to re-pin an image parsed from
      * a drawing part without a lossy pixel round-trip.
      */
-    addImageAnchor(imageId: number, anchor: ImageAnchor): void;
+    addImageAnchor(imageId: number, anchor: ImageAnchor, properties?: PictureProperties): void;
     /** Drop every anchor of the given workbook image from this sheet. The image stays registered on the
      * workbook (another sheet may still show it), so only this sheet's anchors are removed; the writer
      * then omits any media no sheet anchors any longer. */
@@ -448,9 +482,16 @@ export declare class Worksheet {
      * anchor's, exactly how Excel collapses a range on merge. Leaving it would emit a populated `<c>`
      * under the `<mergeCell>` ref, the geometry Excel opens with a repair prompt. Covered-cell styles
      * survive (a border spanning the merge is legal), so only the conflicting value is cleared.
+     *
+     * The range is stored in canonical form, `$` anchors dropped and the top-left corner first, so
+     * merging `$B$2:$A$1` reports `A1:B2` through {@link merges}.
+     *
+     * @throws {SyntaxError} if the range is unparseable or names a worksheet: a merge belongs to the
+     *   sheet it is made on, and a prefix naming another one used to be ignored.
+     * @throws {AuthoringError} if the range overlaps an already-merged region.
      */
     mergeCells(range: string): void;
-    /** The merged ranges on this sheet, in the order they were added. */
+    /** The merged ranges on this sheet, in canonical form (`A1:B2`), in the order they were added. */
     get merges(): readonly string[];
     /**
      * The sheet's autofilter (its range plus any per-column criteria), or `undefined` when the sheet
@@ -467,9 +508,12 @@ export declare class Worksheet {
     get autoFilter(): AutoFilter | undefined;
     set autoFilter(filter: string | AutoFilter | undefined);
     /**
-     * Remove a merged range previously added with {@link mergeCells}, returning whether a merge with
-     * that exact range string existed. The covering rectangle is dropped alongside it, so a cell the
-     * merge had masked addresses independently again. The inverse of {@link mergeCells}.
+     * Remove a merged range previously added with {@link mergeCells}, returning whether such a merge
+     * existed. The range matches however it is spelled (`$` anchors, corner order), since merges are
+     * stored and compared in canonical form. The covering rectangle is dropped alongside it, so a cell
+     * the merge had masked addresses independently again. The inverse of {@link mergeCells}.
+     *
+     * @throws {SyntaxError} if the range is unparseable or names a worksheet.
      */
     unmergeCells(range: string): boolean;
     /**
@@ -493,6 +537,8 @@ export declare class Worksheet {
      * range (`"A1:A10"`), a whole column, or several space-separated areas (`"A1:C1 A3:C3"`) sharing one
      * rule set. The block is stored once against the range, defensively copied so the getter never hands
      * back a reference into the caller's object.
+     *
+     * @throws {AuthoringError} when `formatting.ref` names no cells: empty, or no area of it decodes.
      */
     addConditionalFormatting(formatting: ConditionalFormatting): void;
     /** The conditional formattings on this sheet, each bound to its target range, in insertion order. */
@@ -502,6 +548,35 @@ export declare class Worksheet {
      * contains the cell wins, mirroring how a spreadsheet resolves overlapping validations.
      */
     dataValidationAt(reference: string): DataValidation | undefined;
+    /**
+     * Put a hyperlink on a cell or a rectangle of cells: `{ref: 'B2', target: 'https://example.com'}`,
+     * or `{ref: 'D1:H1', target: '#Summary!A1', tooltip: 'Back to the summary'}`. A `#`-prefixed target
+     * is a place in this workbook; any other is a URL or a path, written as given.
+     *
+     * A link is not part of a cell's value, so it goes on a number, a date, a formula or an empty cell as
+     * readily as on text, and the value stays whatever it is. A link over the same `ref` as one already
+     * on the sheet replaces it. One over a different range is added beside it: where two cover a cell,
+     * {@link hyperlinkAt} reports the later, and Excel keeps both.
+     *
+     * A row or column splice moves a link with the cells it covers, growing it when lines are inserted
+     * inside it and shrinking it when some of its lines are deleted, as Excel does.
+     *
+     * @throws {SyntaxError} if `ref` is not a reference.
+     * @throws {AuthoringError} if `ref` names a whole row or column rather than cells.
+     */
+    addHyperlink(link: Hyperlink): void;
+    /**
+     * Remove the hyperlink whose `ref` is `ref`, and report whether there was one. A link over a wider
+     * range that merely covers `ref` stays.
+     */
+    removeHyperlink(ref: string): boolean;
+    /** The hyperlinks on this sheet, in the order they were added. */
+    get hyperlinks(): readonly Hyperlink[];
+    /**
+     * The hyperlink a cell opens, or `undefined` when none covers it. Of two links covering the cell, the
+     * one added later.
+     */
+    hyperlinkAt(reference: string): Hyperlink | undefined;
     /**
      * Remove `count` rows starting at the 1-based `start`, then insert the given rows in their place.
      * Rows below the edit shift by `inserts.length - count`: a delete pulls the tail up, an insert
@@ -511,7 +586,21 @@ export declare class Worksheet {
      * silently becomes a no-op. Cells carry their full style to the shifted position, and merged ranges
      * shift with the rows they cover.
      *
+     * Formulas move with the rows as Excel moves them: a reference to this sheet, in any sheet's formula,
+     * a defined name, a data validation, a conditional format or a table's column formulas, follows the
+     * row it names, and one to a deleted row becomes `#REF!`. An authored pivot drawing from this sheet
+     * has its source range moved the same way. What the inserted rows carry is written against the sheet after the
+     * edit and is not moved. A dynamic array whose range the edit leaves holding another formula has its
+     * spill blocked, as Excel blocks it: the array formula keeps its own cell alone and caches `#SPILL!`.
+     *
      * @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.
+     * @throws {AuthoringError} if the edit would cut through a Ctrl+Shift+Enter array formula's range: an
+     *   insert strictly inside it, or a delete taking part of it. Excel refuses the same edit, as a change
+     *   to part of an array, and the sheet is left untouched. An edit moving or deleting the whole range,
+     *   and any edit through a dynamic array's range, goes ahead.
      */
     spliceRows(start: number, count: number, ...inserts: RowInput[]): void;
     /**
@@ -547,7 +636,8 @@ export declare class Worksheet {
      * beneath them. `freeze(1)` pins a header row; `freeze(0, 1)` pins the first column. Passing both
      * zero clears the freeze (equivalent to {@link unfreeze}).
      *
-     * @throws {RangeError} if either split is a negative or non-integer count.
+     * @throws {RangeError} if either split is a negative or non-integer count, or leaves no row or
+     *   column of the grid to scroll. The view is left as it was.
      */
     freeze(ySplit?: number, xSplit?: number): void;
     /** Clear any frozen split, returning the sheet to a normal (fully scrolling) view. */
@@ -561,9 +651,16 @@ export declare class Worksheet {
      *
      * 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.
+     * range can be merged onto a duplicated row afterwards. A formula is copied as Excel copies a row,
+     * its relative references moved down with it and its cached result dropped, since that was computed
+     * over the source's cells; an inserted copy is taken from the source as the insert left it. A copy
+     * landing in a dynamic array's range blocks its spill, as {@link spliceRows} says.
      *
-     * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
+     * @throws {RangeError} if `start` is not a positive integer or `count` is negative, or if a copy
+     *   would land past the last row. The sheet is left untouched.
+     * @throws {AuthoringError} if a copy would land inside a Ctrl+Shift+Enter array formula's range, or
+     *   replace part of one, which Excel refuses as a change to part of an array. The sheet is left
+     *   untouched.
      */
     duplicateRow(start: number, options?: {
         count?: number;
@@ -576,7 +673,15 @@ export declare class Worksheet {
      * the right of the edit re-anchors to its new columns. Each inserted column is an array of values
      * indexed by row (index 0 → row 1); an empty array inserts a blank column.
      *
+     * Formulas move with the columns, by the rules {@link spliceRows} gives for rows.
+     *
      * @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.
+     * @throws {AuthoringError} if the edit would cut through a Ctrl+Shift+Enter array formula's range, by
+     *   the rule {@link spliceRows} gives for rows. The sheet is left untouched.
      */
     spliceColumns(start: number, count: number, ...inserts: CellValue[][]): void;
     /**
@@ -584,7 +689,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;
     /**
@@ -684,6 +790,14 @@ export interface WorksheetInternals {
      * restores that credential verbatim rather than re-hashing.
      */
     restoreProtection(protection: SheetProtection): void;
+    /**
+     * Hand the sheet what moves the formulas beyond it, every other sheet's and the workbook's defined
+     * names, when a splice of this sheet moves the lines they refer to. The workbook sets it on each sheet
+     * it creates.
+     */
+    setFormulaHost(host: (edit: SheetSplice) => void): void;
+    /** Move the references this sheet's formulas make to a spliced sheet, which here is another one. */
+    spliceFormulas(edit: SheetSplice): void;
     /**
      * Materialise the cell at an exact 1-based position, creating it on first access. Unlike
      * {@link Worksheet.getCell} this performs no merge resolution: the cell returned is the one at
@@ -693,18 +807,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[];
 }