@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/esm/modules/excel/workbook.browser.js

@@ -13,13 +13,22 @@ import { formatCsv } from "../csv/format/index.js";
 import { parseCsv } from "../csv/parse/index.js";
 import { CsvParserStream, CsvFormatterStream } from "../csv/stream/index.js";
 import { parseNumberFromCsv } from "../csv/utils/number.js";
+// Chart runtime accessed through the host-registry slot; see
+// `chart-host-registry.ts` and `chart/install.ts`. Keeps chart code
+// out of consumer bundles when they don't import
+// `@cj-tech-master/excelts/chart`.
+import { getChartSupport } from "./chart-host-registry.js";
+import { Chartsheet } from "./chartsheet.js";
 import { DefinedNames } from "./defined-names.js";
-import { ExcelDownloadError, ExcelNotSupportedError } from "./errors.js";
-import { WorkbookReader } from "./stream/workbook-reader.js";
-import { WorkbookWriter } from "./stream/workbook-writer.js";
+import { ExcelDownloadError, ExcelNotSupportedError, WorksheetNameError } from "./errors.js";
+import { withPivotChartSource } from "./pivot-chart.js";
+import { WorkbookReader } from "./stream/workbook-reader.browser.js";
+import { WorkbookWriter } from "./stream/workbook-writer.browser.js";
+import { synthGuid } from "./utils/guid.js";
 import { buildWorkbookProtection } from "./utils/workbook-protection.js";
 import { Worksheet } from "./worksheet.js";
-import { XLSX } from "./xlsx/xlsx.js";
+import { RelType } from "./xlsx/rel-type.js";
+import { XLSX } from "./xlsx/xlsx.browser.js";
 import { invokeFormulaEngine } from "../formula/host-registry.js";
 import { formatMarkdown } from "../markdown/format/index.js";
 import { parseMarkdown, parseMarkdownAll } from "../markdown/parse/index.js";
@@ -265,6 +274,22 @@ function buildFormatterOptions(options) {
         writeHeaders: options?.writeHeaders
     };
 }
+function isComboChartOptions(chart) {
+    return !!chart && typeof chart === "object" && "groups" in chart;
+}
+function isChartExOptions(chart) {
+    return !!chart && typeof chart === "object" && "type" in chart && isChartExType(chart.type);
+}
+function isChartExType(type) {
+    return (type === "sunburst" ||
+        type === "treemap" ||
+        type === "waterfall" ||
+        type === "funnel" ||
+        type === "histogram" ||
+        type === "pareto" ||
+        type === "boxWhisker" ||
+        type === "regionMap");
+}
 // =============================================================================
 // Workbook Class
 // =============================================================================
@@ -300,8 +325,21 @@ class Workbook {
         this.media = [];
         this.pivotTables = [];
         this.externalLinks = [];
-        this._passthrough = {};
-        this._rawDrawings = {};
+        this._chartEntries = {};
+        this._chartRels = {};
+        this._chartStyles = {};
+        this._chartColors = {};
+        this._chartExStyles = {};
+        this._chartExColors = {};
+        this._chartExEntries = {};
+        this._chartExRels = {};
+        this._chartExStructuredEntries = {};
+        this._chartsheets = [];
+        this._persons = [];
+        this._slicerParts = {};
+        this._slicerCacheParts = {};
+        this._timelineParts = {};
+        this._timelineCacheParts = {};
         this._writerExternalLinkCache = new Map();
         this._definedNames = new DefinedNames(options?.formulaSyntaxProbe);
     }
@@ -346,11 +384,97 @@ class Workbook {
         // Deep copy via model: the getter serializes ALL worksheet properties and the
         // setter deserializes them, so future properties are automatically included.
         const sourceModel = source.model;
+        // Remap chart numbers so the source's `chartNumber` / `chartExNumber`
+        // references point at entries we actually copy into the target
+        // workbook. Build the map here so the rewritten `charts` array and
+        // the copied entries use consistent ids.
+        const chartMap = new Map();
+        const chartExMap = new Map();
+        const sourceWorkbook = source.workbook;
+        const differentWorkbook = sourceWorkbook !== this;
+        const sourceCharts = sourceModel.charts ?? [];
+        // `nextChartNumber()` / `nextChartExNumber()` compute `max(existing) + 1`
+        // from the entry maps — they do NOT reserve a slot. Calling them in
+        // a tight loop without an intervening `addChartEntry` therefore
+        // returns the SAME number N times, and the second loop below then
+        // overwrites `_chartEntries[dstNum]` repeatedly — only the last
+        // cloned entry survives, the others are silently lost. Track the
+        // allocator locally so each source chart gets a unique target slot.
+        let nextChartAlloc = this.nextChartNumber();
+        let nextChartExAlloc = this.nextChartExNumber();
+        for (const anchor of sourceCharts) {
+            if (anchor.chartNumber && anchor.chartNumber > 0 && !chartMap.has(anchor.chartNumber)) {
+                chartMap.set(anchor.chartNumber, nextChartAlloc++);
+            }
+            if (anchor.chartExNumber &&
+                anchor.chartExNumber > 0 &&
+                !chartExMap.has(anchor.chartExNumber)) {
+                chartExMap.set(anchor.chartExNumber, nextChartExAlloc++);
+            }
+        }
+        const remappedCharts = sourceCharts.map(anchor => ({
+            ...anchor,
+            chartNumber: anchor.chartNumber
+                ? (chartMap.get(anchor.chartNumber) ?? anchor.chartNumber)
+                : anchor.chartNumber,
+            chartExNumber: anchor.chartExNumber
+                ? (chartExMap.get(anchor.chartExNumber) ?? anchor.chartExNumber)
+                : anchor.chartExNumber
+        }));
         newWs.model = {
             ...sourceModel,
             id: newWs.id,
-            name: newWs.name
+            name: newWs.name,
+            charts: remappedCharts
         };
+        // Copy the actual chart parts + sidecars into the target workbook
+        // so the remapped `charts` array references live entries. Without
+        // this, `importSheet` left the target with chart anchors but no
+        // backing chart XML, producing a broken package on save. We copy
+        // both the structured model (via `getChartEntry` / `addChartEntry`
+        // — the public API) and all sidecars (`copyChartSidecars` /
+        // `copyChartExSidecars`).
+        if (chartMap.size > 0 || chartExMap.size > 0) {
+            for (const [srcNum, dstNum] of chartMap) {
+                const entry = sourceWorkbook.getChartEntry(srcNum);
+                if (!entry) {
+                    continue;
+                }
+                // Deep-clone the entry with every metadata field preserved —
+                // rawData / userShapesXml (byte slices), modelSnapshot and the
+                // dirty / preferRawPatch / requireRawPatch writer hints, plus
+                // per-entry `rels`. Previously only `model`, `rawData`, and
+                // `userShapesXml` were copied, so the cross-workbook import
+                // path produced charts where the raw-patch fast path couldn't
+                // run and the change-detection snapshot didn't reflect the
+                // source entry's load-time state.
+                this.addChartEntry(cloneChartEntry(entry, dstNum));
+                if (differentWorkbook) {
+                    sourceWorkbook.copyChartSidecars(srcNum, dstNum, this);
+                }
+                else {
+                    this.copyChartSidecars(srcNum, dstNum);
+                }
+            }
+            for (const [srcNum, dstNum] of chartExMap) {
+                const exEntry = sourceWorkbook.getChartExStructuredEntry?.(srcNum);
+                if (exEntry) {
+                    this.addChartExStructuredEntry(cloneChartExEntry(exEntry, dstNum));
+                }
+                else {
+                    const rawBytes = sourceWorkbook._chartExEntries?.[srcNum];
+                    if (rawBytes) {
+                        this._chartExEntries[dstNum] = rawBytes.slice();
+                    }
+                }
+                if (differentWorkbook) {
+                    sourceWorkbook.copyChartExSidecars(srcNum, dstNum, this);
+                }
+                else {
+                    this.copyChartExSidecars(srcNum, dstNum);
+                }
+            }
+        }
         return newWs;
     }
     // ===========================================================================
@@ -885,17 +1009,14 @@ class Workbook {
      * Create a streaming workbook writer for large files.
      * This is more memory-efficient than using Workbook for large datasets.
      *
-     * @param options - Options for the workbook writer
-     *   - Node.js: can use { filename } or { stream }
-     *   - Browser: must use { stream }
-     * @returns A new WorkbookWriter instance
+     * File-path output (`{ filename }`) is a Node.js-only feature and is
+     * exposed by the Node `Workbook` subclass, which overrides this
+     * factory to return the Node `WorkbookWriter`. This browser base
+     * only accepts `{ stream }`.
      *
      * @example
      * ```ts
-     * // Node.js with filename
-     * const writer = Workbook.createStreamWriter({ filename: "large-file.xlsx" });
-     *
-     * // Browser or Node.js with stream
+     * // Browser (or Node.js with an explicit stream)
      * const writer = Workbook.createStreamWriter({ stream: writableStream });
      *
      * const sheet = writer.addWorksheet("Sheet1");
@@ -912,16 +1033,15 @@ class Workbook {
      * Create a streaming workbook reader for large files.
      * This is more memory-efficient than using Workbook.xlsx.readFile for large datasets.
      *
-     * @param input - File path (Node.js only) or readable stream
-     * @param options - Options for the workbook reader
-     * @returns A new WorkbookReader instance
+     * File-path input (`string`) is a Node.js-only feature and is exposed
+     * by the Node `Workbook` subclass, which overrides this factory to
+     * return the Node `WorkbookReader`. This browser base accepts the
+     * cross-platform `CommonInput` type
+     * (`Uint8Array | ArrayBuffer | Readable | ReadableStream`).
      *
      * @example
      * ```ts
-     * // Node.js with file path
-     * const reader = Workbook.createStreamReader("large-file.xlsx");
-     *
-     * // Browser or Node.js with stream
+     * // Browser or Node.js with stream / buffer
      * const reader = Workbook.createStreamReader(readableStream);
      *
      * for await (const event of reader) {
@@ -941,25 +1061,59 @@ class Workbook {
     // Worksheet Management
     // ===========================================================================
     get nextId() {
-        // Find the next unique spot to add worksheet
+        // Worksheets and chartsheets share a single `sheetId` namespace in
+        // `workbook.xml`'s `<sheets>` element (OOXML requires each
+        // `sheetId` to be globally unique across both families). Allocating
+        // from `_worksheets` alone used to hand out an id already claimed
+        // by a chartsheet whenever the author interleaved their calls —
+        // e.g. `addWorksheet(×16)` → ids 1-16; `addChartsheet(×2)` → ids
+        // 17-18 (via `_nextSheetId()`); then `addWorksheet("X")` walked
+        // `_worksheets` slots 1..16, found them full, and returned
+        // `_worksheets.length = 17`, colliding with the first chartsheet.
+        // Excel rejects the resulting workbook as corrupt. Collect
+        // chartsheet ids up front so the search honours the shared pool.
+        const chartsheetIds = new Set();
+        for (const cs of this._chartsheets) {
+            if (cs && typeof cs.id === "number" && Number.isFinite(cs.id)) {
+                chartsheetIds.add(cs.id);
+            }
+        }
+        // Prefer reusing vacated `_worksheets` slots (left as holes by
+        // `removeWorksheetEx`) so ids stay stable across delete+add cycles.
         for (let i = 1; i < this._worksheets.length; i++) {
-            if (!this._worksheets[i]) {
+            if (!this._worksheets[i] && !chartsheetIds.has(i)) {
                 return i;
             }
         }
-        return this._worksheets.length || 1;
+        // No reusable hole — hand out the next id beyond the current
+        // tail, skipping any slots already taken by chartsheets.
+        let candidate = this._worksheets.length || 1;
+        while (chartsheetIds.has(candidate)) {
+            candidate++;
+        }
+        return candidate;
     }
     /**
      * Add a new worksheet and return a reference to it
      */
     addWorksheet(name, options) {
         const id = this.nextId;
-        const lastOrderNo = this._worksheets.reduce((acc, ws) => ((ws && ws.orderNo) > acc ? ws.orderNo : acc), 0);
+        // Allocate `orderNo` from the unified worksheet+chartsheet counter.
+        // Looking only at `_worksheets` here (the previous implementation)
+        // silently collides when a chartsheet has been added in between:
+        // e.g. `addWorksheet("A")` → orderNo 0; `addChartsheet(…)` → 1
+        // (via `_nextSheetOrderNo()`); `addWorksheet("B")` → 1 again
+        // (because `max(worksheets.orderNo) + 1 = 0 + 1 = 1`), so A and
+        // B share an ordinal with the chartsheet. The writer's stable
+        // sort then interleaves them non-deterministically, scrambling
+        // the user's tab order (`[A, CS, B]` could come out as
+        // `[A, B, CS]` or `[A, CS, B]` across runs).
+        const orderNo = this._nextSheetOrderNo();
         const worksheetOptions = {
             ...options,
             id,
             name,
-            orderNo: lastOrderNo + 1,
+            orderNo,
             workbook: this
         };
         const worksheet = new Worksheet(worksheetOptions);
@@ -967,6 +1121,15 @@ class Workbook {
         return worksheet;
     }
     removeWorksheetEx(worksheet) {
+        // Release any workbook-wide table names this sheet held so the names can
+        // be reused by future tables on other sheets without spurious "name
+        // already exists" errors.
+        const tables = worksheet.tables;
+        if (tables) {
+            for (const tableName of Object.keys(tables)) {
+                this._tableNames.delete(tableName.toLowerCase());
+            }
+        }
         this._worksheets[worksheet.id] = undefined;
     }
     removeWorksheet(id) {
@@ -1000,6 +1163,269 @@ class Workbook {
             .sort((a, b) => a.orderNo - b.orderNo)
             .filter(Boolean);
     }
+    /**
+     * Add a chartsheet containing a single chart and return the created chartsheet.
+     */
+    addChartsheet(name, options) {
+        const sheetName = this._validateChartsheetName(name ?? `Chart${this._chartsheets.length + 1}`);
+        const sheetNo = this._nextChartsheetNo();
+        const id = this._nextSheetId();
+        // Assign a unified `orderNo` across worksheets and chartsheets so
+        // the writer can preserve the author's interleaved tab layout.
+        // Without this, workbook-xform `prepare()` sorted by `sheetNo`
+        // (file-path number, independent per family) and reordered
+        // `[ws1, cs1, ws2]` into `[ws1, ws2, cs1]`.
+        const orderNo = this._nextSheetOrderNo();
+        const chartsheet = {
+            sheetNo,
+            id,
+            name: sheetName,
+            orderNo,
+            state: options.state ?? "visible",
+            tabSelected: options.tabSelected,
+            zoomScale: options.zoomScale,
+            workbookViewId: options.workbookViewId,
+            zoomToFit: options.zoomToFit,
+            pageMargins: options.pageMargins,
+            pageSetup: options.pageSetup,
+            drawing: { rId: "rId1" }
+        };
+        if (isChartExOptions(options.chart)) {
+            const chartSupport = getChartSupport();
+            const chartExNumber = this.nextChartExNumber();
+            const model = chartSupport.buildChartExModel(options.chart);
+            try {
+                chartSupport.fillChartExCaches(model, this);
+            }
+            catch {
+                // Cache population is best-effort; never let it break chart creation.
+            }
+            this.addChartExStructuredEntry({ chartExNumber, model });
+            chartsheet.chartExNumber = chartExNumber;
+        }
+        else {
+            const chartSupport = getChartSupport();
+            const chartNumber = this.nextChartNumber();
+            const chartModel = isComboChartOptions(options.chart)
+                ? chartSupport.buildComboChartModel(options.chart)
+                : chartSupport.buildChartModel(options.chart);
+            try {
+                chartSupport.fillChartCaches(chartModel, this);
+            }
+            catch {
+                // Cache population is best-effort; never let it break chart creation.
+            }
+            const entry = { chartNumber, model: chartModel };
+            // Resolve programmatic `series.spPr.fill.blip._pendingImage`
+            // payloads into workbook media entries and chart rels. The
+            // worksheet-embedded `addChart` path does this immediately
+            // after `fillChartCaches`; chartsheets ran the same builder
+            // output but skipped the image-resolution step entirely, so a
+            // picture-fill series authored via `addChartsheet` was
+            // registered with its `_pendingImage` stuck on the model and
+            // never reached `media/imageN.{ext}` — Excel rendered the
+            // series as a transparent fill. Safe to call before
+            // `addChartEntry` so the stored entry carries its resolved
+            // `entry.rels` from the start.
+            try {
+                chartSupport.resolvePendingChartImages(entry, this, chartNumber);
+            }
+            catch {
+                // Image resolution is best-effort; a broken image payload
+                // should never take down chart creation — the series keeps
+                // its `pictureOptions`, just without the blipFill.
+            }
+            this.addChartEntry(entry);
+            this._applyChartsheetSidecars(chartNumber, options.chart);
+            chartsheet.chartNumber = chartNumber;
+        }
+        this._chartsheets.push(chartsheet);
+        return new Chartsheet(chartsheet, this);
+    }
+    /**
+     * Add a chartsheet containing a classic pivot chart linked to an existing pivot table.
+     */
+    addPivotChartsheet(name, pivotTable, options) {
+        return this.addChartsheet(name, {
+            ...options,
+            chart: withPivotChartSource(pivotTable, options.chart)
+        });
+    }
+    /** Return chartsheets in workbook order. */
+    get chartsheets() {
+        return this._chartsheets.map(model => new Chartsheet(model, this));
+    }
+    getChartsheet(nameOrIndex) {
+        const model = this._getChartsheetModel(nameOrIndex);
+        return model ? new Chartsheet(model, this) : undefined;
+    }
+    removeChartsheet(nameOrIndex) {
+        const index = typeof nameOrIndex === "number"
+            ? nameOrIndex
+            : this._chartsheets.findIndex(sheet => sheet.name.toLowerCase() === nameOrIndex.toLowerCase());
+        if (index < 0 || index >= this._chartsheets.length) {
+            return false;
+        }
+        const [removed] = this._chartsheets.splice(index, 1);
+        if (removed.chartNumber) {
+            this.removeChartEntry?.(removed.chartNumber);
+        }
+        if (removed.chartExNumber) {
+            this.removeChartExStructuredEntry?.(removed.chartExNumber);
+        }
+        return true;
+    }
+    _getChartsheetModel(nameOrIndex) {
+        return typeof nameOrIndex === "number"
+            ? this._chartsheets[nameOrIndex]
+            : this._chartsheets.find(sheet => sheet.name.toLowerCase() === nameOrIndex.toLowerCase());
+    }
+    renameChartsheet(nameOrIndex, name) {
+        const model = this._getChartsheetModel(nameOrIndex);
+        if (!model) {
+            return false;
+        }
+        const currentName = model.name;
+        if (currentName === name) {
+            return true;
+        }
+        model.name = "__excelts_pending_chartsheet_rename__";
+        try {
+            model.name = this._validateChartsheetName(name);
+            return true;
+        }
+        catch (error) {
+            model.name = currentName;
+            throw error;
+        }
+    }
+    copyChartsheet(nameOrIndex, name) {
+        const source = this._getChartsheetModel(nameOrIndex);
+        if (!source) {
+            return undefined;
+        }
+        const cloneName = this._validateChartsheetName(name ?? `${source.name} Copy`);
+        const clone = {
+            ...deepClone(source),
+            id: this._nextSheetId(),
+            sheetNo: this._nextChartsheetNo(),
+            // New tab position — the clone goes to the tail of the tab
+            // bar, matching Excel's "Duplicate" behaviour. Drop the
+            // deep-cloned `orderNo` from the source.
+            orderNo: this._nextSheetOrderNo(),
+            name: cloneName,
+            drawingName: undefined,
+            relationships: source.relationships ? deepClone(source.relationships) : undefined
+        };
+        if (source.chartNumber) {
+            const entry = this.getChartEntry(source.chartNumber);
+            if (entry) {
+                const chartNumber = this.nextChartNumber();
+                // Clone the entry with ALL metadata: rawData, modelSnapshot,
+                // dirty, preferRawPatch, requireRawPatch, rels (per-entry),
+                // userShapesXml. A freshly-created entry carrying only `model`
+                // would lose Excel-authored user-shape overlays, the raw-patch
+                // fast path, and any per-entry rels that aren't in
+                // `_chartRels`. Keeping them in lockstep means a clone of a
+                // just-loaded chart matches the source byte-for-byte.
+                this.addChartEntry(cloneChartEntry(entry, chartNumber));
+                this.copyChartSidecars(source.chartNumber, chartNumber);
+                clone.chartNumber = chartNumber;
+                clone.chartExNumber = undefined;
+            }
+        }
+        else if (source.chartExNumber) {
+            const entry = this.getChartExStructuredEntry(source.chartExNumber);
+            const chartExNumber = this.nextChartExNumber();
+            if (entry) {
+                // Same rationale as the classic branch — carry dirty /
+                // preferRawPatch / requireRawPatch / rawData / modelSnapshot
+                // across the clone so the raw-patch path keeps working on
+                // the duplicate.
+                this.addChartExStructuredEntry(cloneChartExEntry(entry, chartExNumber));
+            }
+            else if (this._chartExEntries[source.chartExNumber]) {
+                this._chartExEntries[chartExNumber] = this._chartExEntries[source.chartExNumber].slice();
+            }
+            // Copy the chartEx sidecars (authored rels) so the cloned
+            // chartsheet's XML references stay valid. Previously a chartEx
+            // with `cx14:` / media rels on the source lost every relationship
+            // on the clone.
+            this.copyChartExSidecars(source.chartExNumber, chartExNumber);
+            clone.chartExNumber = chartExNumber;
+            clone.chartNumber = undefined;
+        }
+        this._chartsheets.push(clone);
+        return new Chartsheet(clone, this);
+    }
+    replaceChartsheetChart(nameOrIndex, chart) {
+        const wrapper = this.getChartsheet(nameOrIndex);
+        if (!wrapper) {
+            return false;
+        }
+        const model = wrapper.model;
+        const chartSupport = getChartSupport();
+        // Build the replacement first so a malformed options object throws
+        // *before* we remove the existing chart entry. Without this, a
+        // failed `buildChartExModel` / `buildChartModel` would leave the
+        // chartsheet empty (old chart nuked, new chart never registered).
+        let newChartExModel;
+        let newChartModel;
+        if (isChartExOptions(chart)) {
+            newChartExModel = chartSupport.buildChartExModel(chart);
+        }
+        else if (isComboChartOptions(chart)) {
+            newChartModel = chartSupport.buildComboChartModel(chart);
+        }
+        else {
+            newChartModel = chartSupport.buildChartModel(chart);
+        }
+        // Remove existing entries only after the new model builds cleanly.
+        if (model.chartNumber) {
+            this.removeChartEntry?.(model.chartNumber);
+            model.chartNumber = undefined;
+        }
+        if (model.chartExNumber) {
+            this.removeChartExStructuredEntry?.(model.chartExNumber);
+            model.chartExNumber = undefined;
+        }
+        if (newChartExModel) {
+            const chartExNumber = this.nextChartExNumber();
+            try {
+                chartSupport.fillChartExCaches(newChartExModel, this);
+            }
+            catch {
+                // Cache population is best-effort; never let it break chart replacement.
+            }
+            this.addChartExStructuredEntry({ chartExNumber, model: newChartExModel });
+            model.chartExNumber = chartExNumber;
+        }
+        else if (newChartModel) {
+            const chartNumber = this.nextChartNumber();
+            try {
+                chartSupport.fillChartCaches(newChartModel, this);
+            }
+            catch {
+                // Cache population is best-effort; never let it break chart replacement.
+            }
+            const entry = { chartNumber, model: newChartModel };
+            // Resolve programmatic `series.spPr.fill.blip._pendingImage`
+            // payloads — matches the classic `addChart` and `addChartsheet`
+            // paths. Previously replacement via `replaceChartsheetChart`
+            // silently dropped picture-fill payloads on the floor.
+            try {
+                chartSupport.resolvePendingChartImages(entry, this, chartNumber);
+            }
+            catch {
+                // Image resolution is best-effort; a broken image payload
+                // should never take down chart replacement.
+            }
+            this.addChartEntry(entry);
+            this._applyChartsheetSidecars(chartNumber, chart);
+            model.chartNumber = chartNumber;
+        }
+        return true;
+    }
     /**
      * Iterate over all sheets.
      *
@@ -1016,6 +1442,47 @@ class Workbook {
     get definedNames() {
         return this._definedNames;
     }
+    /**
+     * Workbook-level directory of people referenced by threaded comments.
+     * Mutating the returned array adds/removes entries in the persistent
+     * state; writers emit `xl/persons/person.xml` only when this list is
+     * non-empty.
+     *
+     * Most callers don't need to touch this directly — creating a
+     * {@link ThreadedComment} through `cell.note` handles registration
+     * automatically.
+     */
+    get persons() {
+        return this._persons;
+    }
+    /**
+     * Register a person in the workbook persons list and return its id.
+     *
+     * When an entry with the same {@link displayName} + {@link userId}
+     * already exists, its existing id is returned so duplicate
+     * commenters collapse onto a single entry. New entries receive a
+     * synthesised `{GUID}` id.
+     *
+     * @param displayName — shown in the comment bubble author line
+     * @param userId — optional identity-provider user id (email / SID)
+     * @param providerId — optional provider identifier ("AD", …)
+     */
+    registerPerson(displayName, userId, providerId) {
+        const existing = this._persons.find(p => p.displayName === displayName && p.userId === userId);
+        if (existing) {
+            return existing.id;
+        }
+        const id = `{${synthGuid()}}`;
+        const entry = { id, displayName };
+        if (userId !== undefined) {
+            entry.userId = userId;
+        }
+        if (providerId !== undefined) {
+            entry.providerId = providerId;
+        }
+        this._persons.push(entry);
+        return id;
+    }
     // ===========================================================================
     // Formula Calculation
     // ===========================================================================
@@ -1131,6 +1598,371 @@ class Workbook {
         return this.media[Number(id)];
     }
     // ===========================================================================
+    // Charts
+    // ===========================================================================
+    /**
+     * Return the next available 1-based chart number.
+     */
+    nextChartNumber() {
+        const existing = Object.keys(this._chartEntries).map(Number);
+        return existing.length > 0 ? Math.max(...existing) + 1 : 1;
+    }
+    /**
+     * Store a chart entry in the workbook (keyed by chartNumber).
+     */
+    addChartEntry(entry) {
+        this._chartEntries[entry.chartNumber] = entry;
+    }
+    setChartStyle(chartNumber, data) {
+        this._chartStyles[chartNumber] = data;
+    }
+    setChartColors(chartNumber, data) {
+        this._chartColors[chartNumber] = data;
+    }
+    copyChartSidecars(sourceChartNumber, targetChartNumber, targetWorkbook = this) {
+        const style = this._chartStyles[sourceChartNumber];
+        if (style) {
+            targetWorkbook.setChartStyle(targetChartNumber, style.slice());
+        }
+        const colors = this._chartColors[sourceChartNumber];
+        if (colors) {
+            targetWorkbook.setChartColors(targetChartNumber, colors.slice());
+        }
+        // Copy the full chart rels bag (`_chartRels`), not just the
+        // style/colors pair. A classic chart can carry rels to embedded
+        // images (pictureFill), external data links, and `<c:userShapes>`
+        // drawing parts — without copying those the clone ends up with
+        // dangling rIds. Deep-copy each rel so a later mutation on the
+        // source doesn't leak into the clone.
+        //
+        // Rewrite style/colors Targets to the destination chart number —
+        // verbatim copy would leave the rel pointing at the source's
+        // `style{src}.xml`, while the writer emits `style{dst}.xml` and
+        // produces a chart whose .rels references a non-existent file.
+        //
+        // For image rels on a cross-workbook copy (`targetWorkbook !==
+        // this`), re-register each referenced image in the destination
+        // workbook and rewrite the Target to point at the new media
+        // file. Without this, a pictureFill that round-tripped through
+        // `importSheet` pointed at the source workbook's media array —
+        // which the destination package doesn't ship, so Excel shows a
+        // broken image icon.
+        const srcRels = this._chartRels[sourceChartNumber];
+        if (Array.isArray(srcRels) && srcRels.length > 0) {
+            const crossWorkbook = targetWorkbook !== this;
+            targetWorkbook._chartRels[targetChartNumber] = srcRels.map(rel => {
+                if (typeof rel !== "object" || rel === null) {
+                    return rel;
+                }
+                const cloned = { ...rel };
+                const target = typeof cloned.Target === "string" ? cloned.Target : undefined;
+                if (target) {
+                    if (/^style\d+\.xml$/.test(target)) {
+                        cloned.Target = `style${targetChartNumber}.xml`;
+                    }
+                    else if (/^colors\d+\.xml$/.test(target)) {
+                        cloned.Target = `colors${targetChartNumber}.xml`;
+                    }
+                    else if (crossWorkbook && cloned.Type === RelType.Image) {
+                        const rewritten = this._rewriteCrossWorkbookImageTarget(target, targetWorkbook);
+                        if (rewritten !== undefined) {
+                            cloned.Target = rewritten;
+                        }
+                    }
+                }
+                return cloned;
+            });
+        }
+    }
+    /**
+     * Copy the media referenced by `target` (e.g. `../media/image3.png`)
+     * from this workbook's media collection into `targetWorkbook`, then
+     * return the rewritten Target pointing at the destination workbook's
+     * copy. Returns `undefined` when the source media can't be
+     * resolved — callers leave the original target in place and let
+     * the writer emit a broken rel (same degradation as before the
+     * cross-workbook rewrite landed).
+     *
+     * The on-disk naming convention is determined by the destination
+     * workbook's `addImage`, so we take the `id` the new image gets and
+     * compute `../media/image{id+1}.{ext}` (the same formula used in
+     * `chart-images.ts:resolvePendingChartImages`). Centralising the
+     * mapping here keeps the cross-workbook copy robust against future
+     * media-naming changes on either workbook.
+     */
+    _rewriteCrossWorkbookImageTarget(target, targetWorkbook) {
+        const match = /\/media\/image(\d+)\.([a-zA-Z0-9]+)$/.exec(target);
+        if (!match) {
+            return undefined;
+        }
+        const sourceMediaIndex = parseInt(match[1], 10) - 1;
+        if (!Number.isFinite(sourceMediaIndex) || sourceMediaIndex < 0) {
+            return undefined;
+        }
+        const medium = this.getImage?.(sourceMediaIndex);
+        if (!medium) {
+            return undefined;
+        }
+        const ext = medium.extension;
+        if (ext !== "png" && ext !== "jpeg" && ext !== "gif") {
+            return undefined;
+        }
+        const payload = {
+            extension: ext
+        };
+        // `instanceof Uint8Array` is realm-sensitive: buffers that crossed
+        // a Worker / iframe / `structuredClone` boundary carry a different
+        // `Uint8Array` prototype and fail the operator even though they
+        // are byte-granular typed arrays. Duck-type via `ArrayBuffer.isView`
+        // + `BYTES_PER_ELEMENT === 1` so cross-workbook copies from a
+        // worker-loaded Workbook preserve the image bytes; otherwise the
+        // copy path silently falls through to `return undefined`, dropping
+        // every image from the chart. Matches `chart-images.ts`'s handling
+        // of the same realm-crossing issue.
+        const buf = medium.buffer;
+        if (buf &&
+            ArrayBuffer.isView(buf) &&
+            buf.BYTES_PER_ELEMENT === 1) {
+            payload.buffer =
+                buf instanceof Uint8Array
+                    ? buf.slice()
+                    : new Uint8Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+        }
+        else if (typeof medium.base64 === "string") {
+            payload.base64 = medium.base64;
+        }
+        else {
+            return undefined;
+        }
+        const newId = targetWorkbook.addImage(payload);
+        return `../media/image${newId + 1}.${ext}`;
+    }
+    /**
+     * Copy the ChartEx-specific sidecar state from one `chartExNumber` slot
+     * to another. Classic charts have `copyChartSidecars` for chart-style /
+     * chart-colors; ChartEx charts carry their own `_chartExRels`
+     * (relationship entries for extension packages, embedded images, etc.)
+     * that the classic helper does not touch. Without this, cloning a
+     * ChartEx via {@link Chart.copyTo} / {@link Chartsheet.clone} silently
+     * dropped every relationship the source had — authored `cx14:`
+     * extensions, embedded custom geometry, or linked media ended up
+     * pointing at an undefined rel id on the clone.
+     */
+    copyChartExSidecars(sourceChartExNumber, targetChartExNumber, targetWorkbook = this) {
+        const rels = this._chartExRels[sourceChartExNumber];
+        if (rels && rels.length > 0) {
+            // Rewrite `Target` for rels that point at numbered sidecars
+            // (styleEx / colorsEx / userShapes). Those files get different
+            // on-disk numbers on the clone — copying the rel verbatim
+            // leaves it pointing at the source's sidecar, so saving the
+            // package produces a chartEx whose .rels references
+            // `styleEx{src}.xml` while the writer emits `styleEx{dst}.xml`.
+            // Strip the number from the source Target and re-stamp it with
+            // the target's number.
+            //
+            // For image rels on a cross-workbook copy (`targetWorkbook !==
+            // this`), re-register each referenced image in the destination
+            // workbook and rewrite the Target — same logic as classic chart
+            // sidecars. Without this, a ChartEx with embedded images (e.g.
+            // pictureFill or custom geometry) would reference media that
+            // doesn't exist in the destination package.
+            const crossWorkbook = targetWorkbook !== this;
+            targetWorkbook._chartExRels[targetChartExNumber] = rels.map(r => {
+                if (typeof r !== "object" || r === null) {
+                    return r;
+                }
+                const cloned = { ...r };
+                const target = typeof cloned.Target === "string" ? cloned.Target : undefined;
+                if (target) {
+                    const styleExMatch = /^styleEx\d+\.xml$/.exec(target);
+                    if (styleExMatch) {
+                        cloned.Target = `styleEx${targetChartExNumber}.xml`;
+                    }
+                    else if (/^colorsEx\d+\.xml$/.exec(target)) {
+                        cloned.Target = `colorsEx${targetChartExNumber}.xml`;
+                    }
+                    else if (crossWorkbook && cloned.Type === RelType.Image) {
+                        const rewritten = this._rewriteCrossWorkbookImageTarget(target, targetWorkbook);
+                        if (rewritten !== undefined) {
+                            cloned.Target = rewritten;
+                        }
+                    }
+                }
+                return cloned;
+            });
+        }
+        // ChartEx style / colors sidecars (matching `_chartStyles` /
+        // `_chartColors` for classic charts). Previously only `_chartExRels`
+        // was copied — a cloned chartEx lost its authored chartExStyle and
+        // chartExColors bytes, so the saved package re-derived them from
+        // defaults and the clone looked different from the source.
+        const exStyle = this._chartExStyles[sourceChartExNumber];
+        if (exStyle) {
+            targetWorkbook._chartExStyles[targetChartExNumber] = exStyle.slice();
+        }
+        const exColors = this._chartExColors[sourceChartExNumber];
+        if (exColors) {
+            targetWorkbook._chartExColors[targetChartExNumber] = exColors.slice();
+        }
+    }
+    _applyChartsheetSidecars(chartNumber, chartOptions) {
+        if (isChartExOptions(chartOptions)) {
+            return;
+        }
+        if (!chartOptions.chartStyle && !chartOptions.chartColors) {
+            return;
+        }
+        const chartSupport = getChartSupport();
+        if (chartOptions.chartStyle) {
+            this.setChartStyle(chartNumber, new TextEncoder().encode(chartSupport.buildChartStyle(chartOptions.chartStyle)));
+        }
+        if (chartOptions.chartColors) {
+            this.setChartColors(chartNumber, new TextEncoder().encode(chartSupport.buildChartColors(chartOptions.chartColors)));
+        }
+    }
+    /**
+     * Retrieve a chart entry by its 1-based chart number.
+     */
+    getChartEntry(chartNumber) {
+        return this._chartEntries[chartNumber];
+    }
+    /**
+     * Remove a chart entry from the workbook.
+     * Safe to call even if the chart number doesn't exist.
+     */
+    removeChartEntry(chartNumber) {
+        delete this._chartEntries[chartNumber];
+        delete this._chartRels[chartNumber];
+        delete this._chartStyles[chartNumber];
+        delete this._chartColors[chartNumber];
+    }
+    // ===========================================================================
+    // ChartEx (Office 2016+) structured entries
+    // ===========================================================================
+    /** Return the next available 1-based chartEx number. */
+    nextChartExNumber() {
+        const rawKeys = Object.keys(this._chartExEntries ?? {}).map(Number);
+        const structKeys = Object.keys(this._chartExStructuredEntries ?? {}).map(Number);
+        const combined = [...rawKeys, ...structKeys];
+        return combined.length > 0 ? Math.max(...combined) + 1 : 1;
+    }
+    /**
+     * Store a structured chartEx entry.
+     * Loaded entries may also keep raw bytes for clean passthrough.
+     */
+    addChartExStructuredEntry(entry) {
+        if (!this._chartExStructuredEntries) {
+            this._chartExStructuredEntries = {};
+        }
+        this._chartExStructuredEntries[entry.chartExNumber] = entry;
+    }
+    /** Get a structured chartEx entry by number. */
+    getChartExStructuredEntry(chartExNumber) {
+        return this._chartExStructuredEntries?.[chartExNumber];
+    }
+    _nextChartsheetNo() {
+        const existing = this._chartsheets.map(cs => cs.sheetNo).filter(Number.isFinite);
+        return existing.length > 0 ? Math.max(...existing) + 1 : 1;
+    }
+    /**
+     * Next value for the unified `orderNo` (tab-bar position) counter
+     * shared between worksheets and chartsheets. Used by the writer's
+     * `prepare()` to emit `<sheets>` in the author's insertion order,
+     * preserving interleaved `[ws, cs, ws]` layouts that the old
+     * sheetNo-based sort used to reshuffle.
+     */
+    _nextSheetOrderNo() {
+        let max = -1;
+        for (const ws of this._worksheets) {
+            if (ws && typeof ws.orderNo === "number" && ws.orderNo > max) {
+                max = ws.orderNo;
+            }
+        }
+        for (const cs of this._chartsheets) {
+            if (typeof cs.orderNo === "number" && cs.orderNo > max) {
+                max = cs.orderNo;
+            }
+        }
+        return max + 1;
+    }
+    _nextSheetId() {
+        const worksheetIds = this.worksheets.map(ws => ws.id);
+        const chartsheetIds = this._chartsheets.map(cs => cs.id).filter(Number.isFinite);
+        const ids = [...worksheetIds, ...chartsheetIds];
+        return ids.length > 0 ? Math.max(...ids) + 1 : 1;
+    }
+    /**
+     * Validate a sheet name (worksheet OR chartsheet) against Excel's
+     * single unified namespace. Returns the (possibly truncated) name on
+     * success; throws {@link WorksheetNameError} on invalid input.
+     *
+     * Unifying the check at the workbook level fixes three related
+     * regressions that used to exist in the per-family validators:
+     *   1. `Worksheet.name` setter only cross-checked against other
+     *      worksheets, so `addChartsheet("S")` followed by
+     *      `addWorksheet("S")` silently produced a duplicate tab name.
+     *   2. The chartsheet regex was missing the backslash, so
+     *      `addChartsheet("A\\B")` sneaked through — Excel rejects it.
+     *   3. `Chartsheet.name = …` bypassed validation entirely, letting
+     *      users mutate the model into a corrupt state.
+     *
+     * @param name - Proposed sheet name. `undefined` / empty / over-31
+     *   chars / containing any of `* ? : \\ / [ ]` / leading or trailing
+     *   single-quote is rejected. Names ≤31 chars are passed through;
+     *   longer ones are truncated (non-production builds emit a warning).
+     * @param existing - The sheet being renamed (if any) — it is
+     *   excluded from the duplicate check so `sheet.name = sheet.name`
+     *   is a no-op rather than a self-collision.
+     */
+    validateSheetName(name, existing) {
+        if (typeof name !== "string") {
+            throw new WorksheetNameError("The name has to be a string.");
+        }
+        if (name === "") {
+            throw new WorksheetNameError("The name can't be empty.");
+        }
+        if (name === "History") {
+            throw new WorksheetNameError('The name "History" is protected. Please use a different name.');
+        }
+        // Illegal characters per Excel's own naming rules: asterisk (*),
+        // question mark (?), colon (:), forward slash (/), backslash (\),
+        // left bracket ([), right bracket (]). The chartsheet regex used
+        // to omit `\\`; unified here so both families enforce the same
+        // char set.
+        if (/[*?:/\\[\]]/.test(name)) {
+            throw new WorksheetNameError(`Sheet name ${name} cannot include any of the following characters: * ? : \\ / [ ]`);
+        }
+        if (/(^')|('$)/.test(name)) {
+            throw new WorksheetNameError(`The first or last character of sheet name cannot be a single quotation mark: ${name}`);
+        }
+        if (name.length > 31) {
+            if (process.env.NODE_ENV !== "production") {
+                console.warn(`Sheet name ${name} exceeds 31 chars. This will be truncated`);
+            }
+            name = name.substring(0, 31);
+        }
+        const nameLower = name.toLowerCase();
+        const duplicateWorksheet = this.worksheets.find(ws => ws && ws !== existing && ws.name.toLowerCase() === nameLower);
+        const duplicateChartsheet = this._chartsheets.find(cs => cs && cs !== existing && cs.name.toLowerCase() === nameLower);
+        if (duplicateWorksheet || duplicateChartsheet) {
+            throw new WorksheetNameError(`Sheet name already exists: ${name}`);
+        }
+        return name;
+    }
+    _validateChartsheetName(name) {
+        return this.validateSheetName(name);
+    }
+    /** Remove a structured chartEx entry. */
+    removeChartExStructuredEntry(chartExNumber) {
+        if (this._chartExStructuredEntries) {
+            delete this._chartExStructuredEntries[chartExNumber];
+        }
+        delete this._chartExEntries[chartExNumber];
+        delete this._chartExRels[chartExNumber];
+        delete this._chartExStyles[chartExNumber];
+        delete this._chartExColors[chartExNumber];
+    }
+    // ===========================================================================
     // External Workbook Links
     // ===========================================================================
     /**
@@ -1284,6 +2116,12 @@ class Workbook {
             worksheets: this.worksheets.map(worksheet => worksheet.model),
             sheets: this.worksheets.map(ws => ws.model).filter(Boolean),
             definedNames: this._definedNames.model,
+            // Live `DefinedNames` instance — required by the write-time
+            // chartEx transform `prepareChartExSidecars`, which registers
+            // hidden `_xlchart.vN.M` names on the fly and needs an object
+            // that can mutate in place. The serialised `definedNames`
+            // array above is re-materialised after the transform runs.
+            definedNamesInstance: this._definedNames,
             views: this.views,
             company: this.company,
             manager: this.manager,
@@ -1299,10 +2137,23 @@ class Workbook {
             media: this.media,
             pivotTables: this.pivotTables,
             calcProperties: this.calcProperties,
-            passthrough: this._passthrough,
-            rawDrawings: this._rawDrawings,
             defaultFont: this._defaultFont,
-            externalLinks: this.externalLinks
+            externalLinks: this.externalLinks,
+            chartEntries: this._chartEntries,
+            chartRels: this._chartRels,
+            chartStyles: this._chartStyles,
+            chartColors: this._chartColors,
+            chartExStyles: this._chartExStyles,
+            chartExColors: this._chartExColors,
+            chartExEntries: this._chartExEntries,
+            chartExRels: this._chartExRels,
+            chartExStructuredEntries: this._chartExStructuredEntries,
+            chartsheets: this._chartsheets,
+            persons: this._persons,
+            slicerParts: this._slicerParts,
+            slicerCacheParts: this._slicerCacheParts,
+            timelineParts: this._timelineParts,
+            timelineCacheParts: this._timelineCacheParts
         };
     }
     set model(value) {
@@ -1345,12 +2196,44 @@ class Workbook {
         // Handle pivot tables - either newly created or loaded from file
         // Loaded pivot tables come from loadedPivotTables after reconciliation
         this.pivotTables = value.pivotTables || value.loadedPivotTables || [];
-        // Preserve passthrough files (charts, etc.) for round-trip preservation
-        this._passthrough = value.passthrough || {};
-        // Preserve raw drawing data for drawings with chart references
-        this._rawDrawings = value.rawDrawings || {};
         // Preserve default font for round-trip fidelity
         this._defaultFont = value.defaultFont;
+        // Restore chart entries
+        this._chartEntries = value.chartEntries || {};
+        this._chartRels = value.chartRels || {};
+        this._chartStyles = value.chartStyles || {};
+        this._chartColors = value.chartColors || {};
+        this._chartExStyles = value.chartExStyles || {};
+        this._chartExColors = value.chartExColors || {};
+        this._chartExEntries = value.chartExEntries || {};
+        this._chartExRels = value.chartExRels || {};
+        this._chartExStructuredEntries = value.chartExStructuredEntries || {};
+        // Restore chartsheets. Populate each chartsheet's `orderNo` from
+        // the position in `value.sheets` (workbook.xml tab order) so the
+        // writer's `prepare()` can sort interleaved worksheets +
+        // chartsheets back into the author's layout. Matches the
+        // equivalent loop above for worksheets.
+        this._chartsheets = value.chartsheets || [];
+        if (value.sheets) {
+            for (const cs of this._chartsheets) {
+                const idx = value.sheets.findIndex((s) => s.id === cs.id);
+                if (idx !== -1) {
+                    cs.orderNo = idx;
+                }
+            }
+        }
+        // Restore threaded-comment person directory. Always assign a new
+        // list so callers editing the previous value don't mutate the
+        // newly-loaded workbook by accident.
+        this._persons = value.persons ? [...value.persons] : [];
+        // Restore raw-passthrough slicer/timeline parts so dashboards
+        // survive round-trip. The maps are stored by reference — loaders
+        // and writers treat them as read-only; mutating them between
+        // load and save is not supported.
+        this._slicerParts = value.slicerParts ?? {};
+        this._slicerCacheParts = value.slicerCacheParts ?? {};
+        this._timelineParts = value.timelineParts ?? {};
+        this._timelineCacheParts = value.timelineCacheParts ?? {};
         // Preserve external workbook references (empty array if none)
         this.externalLinks = value.externalLinks ? [...value.externalLinks] : [];
         // Reset the writer-scoped auto-discovery cache — loading a fresh
@@ -1375,4 +2258,56 @@ Workbook.Writer = WorkbookWriter;
  * // Browser: new Workbook.Reader(readableStream)
  */
 Workbook.Reader = WorkbookReader;
+function deepClone(value) {
+    if (typeof structuredClone === "function") {
+        return structuredClone(value);
+    }
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Deep-copy a {@link ChartEntry}, preserving every field that affects
+ * write-time behaviour — rawData (for the raw-patch fast path),
+ * modelSnapshot (change detection), dirty / preferRawPatch /
+ * requireRawPatch (writer hints), style / colors (ancillary parts),
+ * rels (per-entry relationship bag), and userShapesXml (annotation
+ * overlay). The caller supplies the new `chartNumber`; everything
+ * else is a structural clone so later mutations on one entry don't
+ * leak into the other.
+ *
+ * `rawData` and `userShapesXml` are `Uint8Array`s — `.slice()` is
+ * used instead of `structuredClone` to keep the fast path cheap.
+ */
+function cloneChartEntry(entry, chartNumber) {
+    return {
+        chartNumber,
+        model: deepClone(entry.model),
+        ...(entry.rawData ? { rawData: entry.rawData.slice() } : {}),
+        ...(entry.modelSnapshot !== undefined ? { modelSnapshot: entry.modelSnapshot } : {}),
+        ...(entry.dirty !== undefined ? { dirty: entry.dirty } : {}),
+        ...(entry.preferRawPatch !== undefined ? { preferRawPatch: entry.preferRawPatch } : {}),
+        ...(entry.requireRawPatch !== undefined ? { requireRawPatch: entry.requireRawPatch } : {}),
+        ...(entry.style ? { style: deepClone(entry.style) } : {}),
+        ...(entry.colors ? { colors: deepClone(entry.colors) } : {}),
+        ...(entry.rels ? { rels: entry.rels.map(r => ({ ...r })) } : {}),
+        ...(entry.userShapesXml ? { userShapesXml: entry.userShapesXml.slice() } : {})
+    };
+}
+/**
+ * Deep-copy a {@link ChartExEntry}, preserving the same write-time
+ * fields as {@link cloneChartEntry} but for the ChartEx family
+ * (structured model + rawData + dirty / preferRawPatch /
+ * requireRawPatch + rels).
+ */
+function cloneChartExEntry(entry, chartExNumber) {
+    return {
+        chartExNumber,
+        model: deepClone(entry.model),
+        ...(entry.rawData ? { rawData: entry.rawData.slice() } : {}),
+        ...(entry.modelSnapshot !== undefined ? { modelSnapshot: entry.modelSnapshot } : {}),
+        ...(entry.dirty !== undefined ? { dirty: entry.dirty } : {}),
+        ...(entry.preferRawPatch !== undefined ? { preferRawPatch: entry.preferRawPatch } : {}),
+        ...(entry.requireRawPatch !== undefined ? { requireRawPatch: entry.requireRawPatch } : {}),
+        ...(entry.rels ? { rels: entry.rels.map(r => ({ ...r })) } : {})
+    };
+}
 export { Workbook };