@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/core/workbook-styles.d.ts

@@ -1,5 +1,86 @@
-import type { NamedCellStyle, TableStyleTable } from './style.ts';
+import type { CellStyle } from './style.ts';
 import type { TableStyle } from './table-style.ts';
+/**
+ * A named cell style: the OOXML `cellStyleXfs`/`cellStyles` layer. A spreadsheet applies a built-in
+ * or custom style (e.g. "Normal", "Accent1") whose visual facets live in this shared, named layer
+ * rather than on each cell's direct format; a cell links to it and inherits any facet the direct
+ * format leaves unset. The facets are a cell's own (see {@link CellStyle}); `name` is the style's
+ * display name and `builtinId` its Excel gallery index when it is a built-in style.
+ */
+export type NamedCellStyle = Readonly<CellStyle> & {
+    readonly name?: string;
+    readonly builtinId?: number;
+};
+/**
+ * A differential style (OOXML CT_Dxf): formatting laid *over* whatever a cell already carries. Only
+ * the facets present override; the rest of the cell's own style shows through. It carries the subset
+ * of the cell-style facets (see {@link CellStyle}) a `<dxf>` can express: font, number format, fill,
+ * and border.
+ *
+ * Differential styles live in one workbook-level table (`<dxfs>`) that several features index into:
+ * a conditional-formatting rule's highlight format, and a table style's per-element formatting
+ * (`<tableStyleElement dxfId="…">`). They are interned and shared, so two features asking for the
+ * same formatting land on one entry.
+ *
+ * Not every facet reaches every consumer. As a **table style element**, Excel applies only the font,
+ * fill, and border: its own object model exposes `Font`, `Interior`, and `Borders` on a table style
+ * element and nothing for a number format, so a `numFmt` set here is carried faithfully through a
+ * round-trip but has no visible effect. The type is left whole rather than split, because the same
+ * value is legitimately reused across both consumers and narrowing it would only move the surprise.
+ */
+export type DifferentialStyle = Pick<CellStyle, 'font' | 'numFmt' | 'fill' | 'border'>;
+/**
+ * The `<tableStyles>` block of a styles part: the custom table/pivot style definitions a file
+ * declares, and the two gallery names it nominates as the default for a new table and a new pivot.
+ *
+ * Each entry of {@link styles} is one `<tableStyle>…</tableStyle>` fragment kept verbatim, for the
+ * same reason a `<dxf>` is: a `tableStyleElement`'s `dxfId` indexes the differential-style table,
+ * which the writer re-emits **at its original indices**, so the references stay valid without
+ * reparsing anything. That index-stability is load-bearing: renumbering the dxf table would
+ * silently re-point every preserved table style at a different format.
+ *
+ * The two default names are ordinary strings, not fragments: they are re-escaped on write, so they
+ * are held decoded.
+ */
+export interface TableStyleTable {
+    readonly styles: readonly TableStyleDefinition[];
+    readonly defaultTableStyle?: string | undefined;
+    readonly defaultPivotStyle?: string | undefined;
+    /**
+     * The namespace prefixes the verbatim {@link styles} fragments use, mapped to their URI and to
+     * whether the source marked the prefix ignorable (`mc:Ignorable`).
+     *
+     * Carrying a fragment verbatim carries its *prefixes* too. Excel stamps a revision id
+     * (`xr9:uid="{…}"`) on every `<tableStyle>` it writes, so a fragment re-emitted under a
+     * `<styleSheet>` that declares only the default namespace is not namespace-well-formed, and no
+     * consumer can parse the part at all, which is a far louder failure than the dropped table style
+     * this preservation exists to prevent. The writer re-declares each prefix on `<styleSheet>` and
+     * re-states the ignorable ones, exactly as the source did.
+     */
+    readonly namespaces?: readonly TableStyleNamespace[];
+}
+/**
+ * One preserved `<tableStyle>` definition: its bytes, and the `name` a table's style info matches it by.
+ *
+ * The name travels beside the fragment rather than being read back out of it. An authored style
+ * replaces the preserved definition it shares a name with, and a pattern pulling `name="…"` out of
+ * the bytes did not see `name='…'`, which is the same attribute in single quotes: the writer emitted
+ * both definitions under one name, the duplicate {@link Workbook.addTableStyle} promises cannot happen.
+ * The reader takes the name from the scanner that read the element, decoded, whatever its quoting.
+ */
+export interface TableStyleDefinition {
+    /** The style's `name`, decoded; empty for a fragment that declared none. */
+    readonly name: string;
+    /** The `<tableStyle>…</tableStyle>` element exactly as the file spelled it. */
+    readonly xml: string;
+}
+/** One namespace declaration a preserved `<tableStyle>` fragment depends on. */
+export interface TableStyleNamespace {
+    readonly prefix: string;
+    readonly uri: string;
+    /** Whether the source listed this prefix in the stylesheet's `mc:Ignorable`. */
+    readonly ignorable: boolean;
+}
 /**
  * The preserved style tables of a workbook: the `<dxfs>` fragments, the named cell styles, the two
  * colour lists, and the table-style definitions a file declared plus the ones a caller authored.
@@ -19,6 +100,7 @@ export declare class WorkbookStyleTables {
     addCustomTableStyle(style: TableStyle): void;
     indexedPalette(): readonly string[];
     restoreDifferentialStyles(fragments: readonly string[]): void;
+    adoptDifferentialStyle(fragment: string): number;
     restoreNamedStyles(styles: readonly NamedCellStyle[]): void;
     restoreIndexedColors(fragments: readonly string[]): void;
     restoreMruColors(fragments: readonly string[]): void;

package/dist/core/workbook-styles.js

@@ -33,6 +33,10 @@ export class WorkbookStyleTables {
     restoreDifferentialStyles(fragments) {
         replaceContents(this.#differentialStyles, fragments);
     }
+    adoptDifferentialStyle(fragment) {
+        const existing = this.#differentialStyles.indexOf(fragment);
+        return existing === -1 ? this.#differentialStyles.push(fragment) - 1 : existing;
+    }
     restoreNamedStyles(styles) {
         replaceContents(this.#namedStyles, styles);
     }

package/dist/core/workbook-theme.js

@@ -19,9 +19,11 @@ export class WorkbookTheme {
         this.#declared = declared;
     }
     author(overrides) {
-        for (const value of Object.values(overrides.colors ?? {}))
-            normalizeThemeColor(value);
-        Object.assign(this.#authored.colors, overrides.colors ?? {});
+        const colors = Object.fromEntries(Object.entries(overrides.colors ?? {}).map(([slot, value]) => [
+            slot,
+            normalizeThemeColor(value),
+        ]));
+        Object.assign(this.#authored.colors, colors);
         this.#authored.fonts = { ...this.#authored.fonts, ...overrides.fonts };
     }
     get colors() {

package/dist/core/workbook-vba.js

@@ -1,3 +1,4 @@
+import { isRelType } from '../rel-type.js';
 import { addVbaReference, parseVbaProject, removeVbaModule, VBA_PROJECT_CONTENT_TYPE, VBA_PROJECT_PART_PATH, VBA_PROJECT_REL_TYPE, VbaAuthorError, vbaProjectSignatureKind, } from '../vba/index.js';
 import { replaceContents } from './containers.js';
 export class WorkbookVbaProject {
@@ -21,7 +22,7 @@ export class WorkbookVbaProject {
     set bytes(bytes) {
         if (bytes !== undefined)
             parseVbaProject(bytes);
-        replaceContents(this.#references, this.#references.filter((r) => !r.relType.endsWith('/vbaProject')));
+        replaceContents(this.#references, this.#references.filter((r) => !isRelType(r.relType, 'vbaProject')));
         if (bytes !== undefined) {
             this.#references.push({
                 relType: VBA_PROJECT_REL_TYPE,
@@ -70,7 +71,7 @@ export class WorkbookVbaProject {
         this.bytes = addVbaReference(bytes, ref);
     }
     #ref() {
-        return this.#references.find((r) => r.relType.endsWith('/vbaProject'));
+        return this.#references.find((r) => isRelType(r.relType, 'vbaProject'));
     }
     #entry() {
         const ref = this.#ref();

package/dist/core/workbook.d.ts

@@ -1,13 +1,16 @@
 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 { DateEpoch } from './date.ts';
+import { type SheetSplice } from './formula-references.ts';
 import { type WorkbookImage, type WorksheetImages } from './image.ts';
 import { INTERNAL } from './internal.ts';
 import type { PreservedPart, PreservedRootReference } from './preserved.ts';
-import type { Color, Font, NamedCellStyle, TableStyleTable } from './style.ts';
+import type { 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 +158,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
@@ -324,7 +346,8 @@ export declare class Workbook {
      * 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.
+     * @throws {SyntaxError} if a colour is not 6 or 8 hexadecimal digits, with or without a leading `#`.
+     *   Every colour is read before any is stored, so a refused call changes nothing.
      */
     setTheme(overrides: ThemeOverrides): void;
     /**
@@ -333,6 +356,9 @@ export declare class Workbook {
      *
      * 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}.
+     *
+     * Every slot reads back as six uppercase hexadecimal digits, whichever spelling {@link setTheme} was
+     * given or the theme part used.
      */
     get themeColors(): ThemeColorScheme;
     /** The theme's major (heading) and minor (body) typefaces, authored values over the source's. */
@@ -392,7 +418,8 @@ export declare class Workbook {
      *
      * A serializer composes these *over* the existing part rather than generating one from scratch, so
      * a preserved theme keeps its format scheme, its unauthored slots' exact encoding, and the
-     * relationships it carries.
+     * relationships it carries. Its colours are already reduced to the six uppercase hexadecimal digits
+     * a slot holds.
      */
     get themeOverrides(): ThemeOverrides | undefined;
     /**
@@ -540,6 +567,12 @@ export interface WorkbookInternals {
      * re-write.
      */
     restoreDifferentialStyles(fragments: readonly string[]): void;
+    /**
+     * The index of a `<dxf>` fragment a sheet carried inline, found among the differential styles or
+     * appended after them, so a conditional format read from the extension form holds a `dxfId` like any
+     * other rule.
+     */
+    adoptDifferentialStyle(fragment: string): number;
     /**
      * Reinstate the custom indexed-color palette (`<colors><indexedColors>`) read from a file, each
      * entry a verbatim `<rgbColor rgb="…"/>` fragment, so a colour referenced by `indexed="…"` keeps
@@ -596,4 +629,9 @@ export interface WorkbookInternals {
      * {@link Workbook.addPerson} is the authoring verb.
      */
     restorePersons(persons: readonly Person[]): void;
+    /**
+     * Every row and column splice made to the workbook's sheets, in the order they were made, for the
+     * writer to replay over the references a preserved part spells.
+     */
+    splices(): readonly SheetSplice[];
 }

package/dist/core/workbook.js

@@ -1,11 +1,14 @@
 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 { spliceFormula } from './formula-references.js';
+import { pictureProperties } 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,27 +20,28 @@ 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());
     #preservedReferences = [];
+    #splices = [];
     #persons = new Map();
     get worksheets() {
         return this.#worksheets;
     }
     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,52 +184,36 @@ 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((picture) => ({
+                image: this.#media.require(picture.imageId, sheet.name),
+                anchor: picture.anchor,
+                ...pictureProperties(picture),
+            })),
+            background: background === undefined ? undefined : this.#media.require(background, sheet.name),
         };
     }
     importImages(sheet, images) {
         for (const id of new Set(sheet.images.map((image) => image.imageId)))
             sheet.removeImage(id);
         sheet.removeBackgroundImage();
-        for (const { image, anchor } of images.anchored) {
-            sheet.addImageAnchor(this.#registerImage(image), anchor);
+        for (const picture of images.anchored) {
+            sheet.addImageAnchor(this.#media.registerExisting(picture.image), picture.anchor, pictureProperties(picture));
         }
         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,16 +222,31 @@ 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);
     }
     addWorksheet(name, options = {}) {
         this.#assertValidSheetName(name);
         const sheet = new Worksheet(name, this.#nextSheetId++, options.state ?? 'visible');
+        sheet[INTERNAL].setFormulaHost((edit) => {
+            this.#spliceFormulasBeyond(sheet, edit);
+        });
         this.#worksheets.push(sheet);
         return sheet;
     }
+    #spliceFormulasBeyond(spliced, edit) {
+        this.#splices.push(edit);
+        for (const sheet of this.#worksheets) {
+            if (sheet !== spliced)
+                sheet[INTERNAL].spliceFormulas(edit);
+        }
+        for (const [index, definedName] of this.#definedNames.entries()) {
+            const refersTo = spliceFormula(definedName.refersTo, definedName.scope, edit);
+            if (refersTo !== definedName.refersTo)
+                this.#definedNames[index] = { ...definedName, refersTo };
+        }
+    }
     getWorksheet(nameOrId) {
         if (typeof nameOrId === 'number') {
             return this.#worksheets.find((sheet) => sheet.id === nameOrId);
@@ -255,11 +258,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 +270,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] = {
@@ -289,6 +292,7 @@ export class Workbook {
         restoreDifferentialStyles: (fragments) => {
             this.#styles.restoreDifferentialStyles(fragments);
         },
+        adoptDifferentialStyle: (fragment) => this.#styles.adoptDifferentialStyle(fragment),
         restoreIndexedColors: (fragments) => {
             this.#styles.restoreIndexedColors(fragments);
         },
@@ -312,5 +316,6 @@ export class Workbook {
             for (const person of persons)
                 this.#persons.set(person.id, person);
         },
+        splices: () => this.#splices,
     };
 }

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,49 @@
+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. The range is stored
+     * in canonical form (see {@link canonicalMerge}).
+     *
+     * @throws {SyntaxError} if the range is unparseable or names a worksheet.
+     * @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}, and it
+     * matches however the range is spelled, since both sides are compared in canonical form.
+     *
+     * @throws {SyntaxError} if the range is unparseable or names a worksheet.
+     */
+    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;
+    clear(): void;
+}

package/dist/core/worksheet-merges.js

@@ -0,0 +1,65 @@
+import { AuthoringError, InternalError, quoted } from '../errors.js';
+import { boundedRect, decodeRange, encodeRect } from './address.js';
+import { replaceContents } from './containers.js';
+import { MergeIndex } from './merge-index.js';
+function canonicalMerge(range) {
+    const decoded = decodeRange(range);
+    if (decoded.sheetName !== undefined) {
+        throw new SyntaxError(`merged range ${quoted(range)} names worksheet ${quoted(decoded.sheetName)}: a merge belongs to the sheet it is made on`);
+    }
+    const rect = boundedRect(decoded);
+    return { canonical: rect === undefined ? decoded.dimensions : encodeRect(rect), rect };
+}
+export class WorksheetMerges {
+    #ranges = [];
+    #rects = [];
+    #index = new MergeIndex(this.#rects);
+    get ranges() {
+        return this.#ranges;
+    }
+    get rects() {
+        return this.#rects;
+    }
+    add(range) {
+        const { canonical, rect } = canonicalMerge(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(canonical);
+        return rect;
+    }
+    remove(range) {
+        const { canonical, rect } = canonicalMerge(range);
+        const index = this.#ranges.indexOf(canonical);
+        if (index === -1)
+            return { existed: false, rectsChanged: false };
+        this.#ranges.splice(index, 1);
+        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) {
+            throw new InternalError(`merged range ${quoted(canonical)} was declared without its rectangle`);
+        }
+        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();
+    }
+    clear() {
+        this.#ranges.length = 0;
+        this.#rects.length = 0;
+        this.#index.invalidate();
+    }
+}