@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/types/modules/excel/utils/ooxml-validator/path-utils.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Path helpers shared across all validator checkers.
+ *
+ * All paths are handled as **forward-slash POSIX strings** because that is
+ * how OPC part names are defined. We never touch the host's path separator.
+ */
+/**
+ * Strip a single leading `/` if present. OPC `PartName` values start with
+ * `/` by spec, but zip entries do not.
+ */
+export declare function stripLeadingSlash(p: string): string;
+/** `.xml`, `.rels`, or `.vml` — the payloads we parse as XML. */
+export declare function isXmlLike(pathName: string): boolean;
+/**
+ * Directory in which a relationships part's **source** part lives. OPC
+ * resolves rel Targets relative to the source part's directory, NOT the
+ * `.rels` file's directory. Examples:
+ *
+ * | .rels path                              | source dir          |
+ * |-----------------------------------------|---------------------|
+ * | `_rels/.rels`                           | ``                  |
+ * | `xl/_rels/workbook.xml.rels`            | `xl`                |
+ * | `xl/worksheets/_rels/sheet1.xml.rels`   | `xl/worksheets`     |
+ */
+export declare function getRelsSourceDir(relsPath: string): string;
+/**
+ * Basename without directory, e.g. `xl/foo/bar.xml` → `bar.xml`.
+ */
+export declare function posixBasename(p: string): string;
+/** Extension without the leading dot, lowercase. `""` when missing. */
+export declare function getExtension(p: string): string;
+/**
+ * Resolve a relationship Target against a .rels path. Handles absolute
+ * targets starting with `/` (relative to package root), `../` traversal,
+ * `./`, and plain relative segments. Never returns a leading slash.
+ *
+ * We do NOT use `node:path` so this module is usable in browsers.
+ */
+export declare function resolveRelTarget(relsPath: string, target: string): string;
+/**
+ * `false` when a resolved rel target escapes the package root. Targets
+ * that escape are malicious or accidentally produced by broken
+ * serialisers and always indicate a corrupt package.
+ */
+export declare function isSafeResolvedPath(resolved: string): boolean;
+/**
+ * Derive the .rels path for a given source part. Symmetric with
+ * `getRelsSourceDir`. Examples:
+ *
+ * | source part                    | rels path                              |
+ * |--------------------------------|----------------------------------------|
+ * | `xl/workbook.xml`              | `xl/_rels/workbook.xml.rels`           |
+ * | `xl/worksheets/sheet1.xml`     | `xl/worksheets/_rels/sheet1.xml.rels`  |
+ */
+export declare function relsPathForPart(partPath: string): string;
+/**
+ * Inverse of {@link relsPathForPart}: source part for a given rels file.
+ * Returns undefined for the root rels (which has no conventional source).
+ */
+export declare function sourcePartForRels(relsPath: string): string | undefined;
+/**
+ * Part name satisfies OPC PartName grammar — not empty, uses only safe
+ * characters, does not end with `/` and does not contain `.` or `..`
+ * segments. We do not validate the full grammar but cover the cases that
+ * break Excel in practice.
+ */
+export declare function isLegalPartName(partName: string): boolean;

package/dist/types/modules/excel/utils/ooxml-validator/reporter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Problem reporter shared by all checkers.
+ *
+ * Two responsibilities:
+ *   1. Filter warnings when `includeWarnings` is `false`.
+ *   2. Short-circuit after `maxProblems` is reached.
+ *
+ * The reporter does not sort or dedupe — checkers are expected to emit at
+ * most one problem per logical issue. Callers get problems in encounter
+ * order, which is stable across runs for the same input.
+ */
+import type { OoxmlProblemKind, OoxmlProblemSeverity, OoxmlValidationProblem } from "./types.js";
+export interface ReporterOptions {
+    maxProblems?: number;
+    includeWarnings?: boolean;
+}
+export declare class Reporter {
+    readonly problems: OoxmlValidationProblem[];
+    private errorCount;
+    private readonly maxProblems?;
+    private readonly includeWarnings;
+    constructor(options?: ReporterOptions);
+    /**
+     * `true` once the configured `maxProblems` cap is reached. Checkers
+     * should consult this at the top of their per-part loops to avoid
+     * doing unnecessary work.
+     */
+    get capped(): boolean;
+    get hasErrors(): boolean;
+    /** Report an error-severity problem. */
+    error(kind: OoxmlProblemKind, message: string, file?: string): void;
+    /** Report a warning-severity problem. Only recorded if includeWarnings. */
+    warning(kind: OoxmlProblemKind, message: string, file?: string): void;
+    private push;
+}
+/**
+ * Convenience alias for the legacy `severity` argument used in the old
+ * flat API. Kept for internal checker code that wants to produce a
+ * problem with a runtime-chosen severity.
+ */
+export declare function reportWithSeverity(reporter: Reporter, severity: OoxmlProblemSeverity, kind: OoxmlProblemKind, message: string, file?: string): void;

package/dist/types/modules/excel/utils/ooxml-validator/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Public types for the OOXML validator.
+ *
+ * The validator's job is to detect xlsx packages that Excel will refuse to
+ * open (or silently repair). Each check emits zero or more `Problem` entries
+ * tagged by `kind`; callers can branch on `kind` for structured handling.
+ *
+ * Problem kinds are grouped by subsystem to make ad-hoc extension easy.
+ * New kinds MUST be added to the union below so consumers can enumerate them
+ * at the type level. Removing or renaming kinds is a breaking change.
+ */
+export type PackageStructureKind = "missing-part" | "xml-malformed" | "part-name-invalid";
+export type ContentTypesKind = "content-types-missing" | "content-types-malformed" | "content-types-missing-default" | "content-types-missing-for-part" | "content-types-duplicate-override" | "content-types-wrong-for-part";
+export type RelationshipsKind = "root-rels-missing-officeDocument" | "rels-malformed" | "rels-missing-target" | "rels-duplicate-id" | "rels-empty-target" | "rels-missing-id-attr" | "rels-missing-type-attr" | "rels-invalid-target-path" | "rels-source-missing" | "rels-type-target-mismatch";
+export type WorkbookKind = "workbook-sheet-missing-rel" | "workbook-sheet-wrong-rel-type" | "workbook-duplicate-sheetId" | "workbook-duplicate-sheet-rid" | "workbook-sheet-missing-name" | "workbook-sheet-name-too-long" | "workbook-sheet-name-invalid-chars" | "workbook-sheet-name-duplicate" | "workbook-child-order";
+export type WorksheetKind = "sheet-missing-rels" | "sheet-child-out-of-order" | "sheet-legacyDrawing-after-controls" | "sheet-controls-missing-drawing" | "sheet-control-missing-rel" | "sheet-control-wrong-rel-type" | "sheet-legacyDrawing-missing-rel" | "sheet-legacyDrawing-wrong-rel-type" | "sheet-drawing-missing-rel" | "sheet-drawing-wrong-rel-type" | "sheet-comments-missing-rel" | "sheet-comments-wrong-rel-type" | "sheet-hyperlink-missing-rel" | "sheet-hyperlink-wrong-rel-type" | "sheet-tablePart-missing-rel" | "sheet-tablePart-wrong-rel-type" | "sheet-cell-ref-missing" | "sheet-cell-ref-invalid" | "sheet-cell-ref-row-mismatch" | "sheet-cell-ref-out-of-bounds" | "sheet-cell-style-index-oob" | "sheet-cell-sst-index-oob" | "sheet-merge-invalid-range" | "sheet-merge-overlap" | "sheet-row-index-out-of-bounds" | "sheet-sharedFormula-master-missing" | "sheet-sharedFormula-duplicate-master";
+export type StylesKind = "styles-malformed" | "styles-numFmt-missing-for-xf" | "styles-font-index-oob" | "styles-fill-index-oob" | "styles-border-index-oob";
+export type TableKind = "table-filterColumn-redundant-per-column" | "table-totalsRowFormula-with-builtin-function" | "table-autoFilter-covers-totalsRow";
+export type ChartKind = "chart-missing-chart" | "chart-missing-plotArea" | "chart-child-out-of-order" | "chart-missing-required-child" | "chart-wrong-child-count" | "chart-invalid-enum-value" | "chart-value-out-of-range" | "chart-forbidden-child" | "chart-duplicate-errBars-direction" | "chart-duplicate-series-idx" | "chart-duplicate-series-order" | "chart-pt-idx-out-of-range" | "chart-axid-unresolved" | "chart-theme-missing-schemeClr-slot" | "chart-f-invalid-syntax" | "chart-f-undefined-name" | "chartEx-missing-chart" | "chartEx-missing-plotArea" | "chartEx-missing-series" | "chartEx-series-missing-layoutId" | "chartEx-series-missing-data-id" | "chartEx-series-missing-axis-id" | "chartEx-externalData-missing-rel" | "chartEx-series-too-many-dataId" | "chartEx-typed-element-text-form" | "chartEx-invalid-auto-element" | "chartEx-paretoLine-in-layoutPr" | "chartEx-title-direct-layout" | "chartEx-axis-missing-pos-and-type" | "chartEx-f-uses-direct-range-not-defined-name" | "chartEx-waterfall-missing-subtotals" | "chartEx-chartStyle-stub-form" | "chartEx-chartColorStyle-stub-form";
+export type DrawingKind = "drawing-graphicFrame-missing-chart" | "drawing-anchor-missing" | "drawing-anchor-invalid-coords" | "drawing-chartEx-missing-alternateContent-wrap" | "drawing-chartEx-alternateContent-empty-fallback" | "drawing-chartEx-alternateContent-outer-wrap" | "drawing-chartEx-missing-creationId";
+export type ChartsheetKind = "chartsheet-missing-drawing";
+export type PivotKind = "pivot-missing-cacheId" | "pivot-cacheId-not-in-workbook" | "pivot-cacheRecords-missing";
+/**
+ * All problem kinds emitted by the validator. The historical legacy kind
+ * `sheet-legacyDrawing-after-controls` is preserved for backwards
+ * compatibility — new ordering violations use the generic
+ * `sheet-child-out-of-order` kind.
+ */
+export type OoxmlProblemKind = PackageStructureKind | ContentTypesKind | RelationshipsKind | WorkbookKind | WorksheetKind | StylesKind | TableKind | ChartKind | DrawingKind | ChartsheetKind | PivotKind;
+/**
+ * Historical alias: the old public API exposed a separate union for the
+ * single ordering check. We preserve the name so downstream type-level
+ * references keep compiling.
+ */
+export type OoxmlOrderingProblemKind = "sheet-legacyDrawing-after-controls";
+/**
+ * `error`   — Excel will refuse the file or show a repair prompt.
+ * `warning` — Likely to work but deviates from OPC/OOXML invariants; Excel
+ *             may silently recover.
+ */
+export type OoxmlProblemSeverity = "error" | "warning";
+export interface OoxmlValidationProblem {
+    kind: OoxmlProblemKind;
+    severity: OoxmlProblemSeverity;
+    /** The file this problem is reported for, if any. */
+    file?: string;
+    /** Human-readable description. Stable enough for snapshot tests. */
+    message: string;
+}
+/**
+ * Historical alias retained for callers that used the narrower type before
+ * severity was added. The shape is identical to `OoxmlValidationProblem`.
+ */
+export type OoxmlOrderingValidationProblem = OoxmlValidationProblem;
+export interface OoxmlValidationStats {
+    entryCount: number;
+    xmlLikeCount: number;
+    relsCount: number;
+}
+export interface OoxmlValidationReport {
+    /** `true` when there are no `error`-severity problems. Warnings do not fail. */
+    ok: boolean;
+    problems: OoxmlValidationProblem[];
+    stats: OoxmlValidationStats;
+}
+export interface OoxmlValidateOptions {
+    /**
+     * Check every XML-like entry (.xml / .rels / .vml) for well-formedness.
+     * Default: true.
+     */
+    checkXmlWellFormed?: boolean;
+    /**
+     * Validate relationship targets exist (TargetMode=External is skipped).
+     * Default: true.
+     */
+    checkRelationshipTargets?: boolean;
+    /**
+     * Validate the content types table against package parts.
+     * Default: true.
+     */
+    checkContentTypesOverrides?: boolean;
+    /**
+     * Validate worksheet r:id wiring (controls / drawing / comments / etc.)
+     * and structural invariants (child element order, cell r= consistency,
+     * merge overlaps, style index bounds).
+     * Default: true.
+     */
+    checkWorksheetControlWiring?: boolean;
+    /**
+     * Validate chart / chartEx / drawing / chartsheet / pivot internal
+     * structure. Default: true.
+     */
+    checkChartStructure?: boolean;
+    /**
+     * Validate styles.xml internal integrity (numFmt/font/fill/border
+     * back-references from xf records). Default: true.
+     */
+    checkStylesIntegrity?: boolean;
+    /**
+     * Stop after this many problems across all checks. Useful for large
+     * packages where the first few problems imply the rest.
+     */
+    maxProblems?: number;
+    /**
+     * Include warnings in the output. When `false` (default), warnings are
+     * silently dropped. Errors are always reported regardless of this flag.
+     */
+    includeWarnings?: boolean;
+}

package/dist/types/modules/excel/utils/ooxml-validator/xml-utils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * XML helpers that tolerate namespace prefixes.
+ *
+ * OOXML serialisers are allowed to write `<drawing>` or `<x:drawing>` —
+ * both are legal in the same schema. All validator checks must therefore
+ * match on the **local name**, not the prefixed name. These helpers also
+ * tolerate namespaced attributes like `r:id` vs `ns0:id`.
+ */
+import { findChildren } from "../../../xml/dom.js";
+import type { XmlDocument, XmlElement } from "../../../xml/types.js";
+/**
+ * Extract the local name from a tag name, i.e. the part after the last `:`.
+ * For `drawing` returns `drawing`; for `x:drawing` returns `drawing`.
+ */
+export declare function localName(name: string): string;
+/** Namespace-insensitive element-name equality. */
+export declare function matchesLocal(name: string, target: string): boolean;
+/** Find first child element with matching **local** name. */
+export declare function findChildLocal(el: XmlElement, local: string): XmlElement | undefined;
+/** Find all child elements with matching **local** name. */
+export declare function findChildrenLocal(el: XmlElement, local: string): XmlElement[];
+/** `true` when any descendant (or self) has matching local name. */
+export declare function hasDescendantLocal(root: XmlElement, local: string): boolean;
+/** Collect all descendants (including self) matching local name. */
+export declare function collectDescendantsLocal(root: XmlElement, local: string): XmlElement[];
+/**
+ * Read an attribute by local name. The OOXML convention is to use
+ * namespaced attributes like `r:id` but some serialisers strip or
+ * renumber the prefix. We match by suffix `:<local>` or exact `local`.
+ */
+export declare function attrByLocalName(el: XmlElement, local: string): string | undefined;
+/**
+ * Parse an XML string into a DOM tree. Returns `undefined` and records the
+ * failure as a malformed XML problem via `onMalformed`. We don't throw
+ * because validators must continue after a parse failure.
+ */
+export declare function tryParseXml(xml: string, onMalformed: (err: Error) => void): XmlDocument | undefined;
+export { findChildren };

package/dist/types/modules/excel/workbook.browser.d.ts

@@ -10,16 +10,18 @@
  * - streaming: createStreamWriter/createStreamReader for large files
  */
 import type { CsvParseOptions, CsvFormatOptions } from "../csv/types.js";
+import type { ChartEntry, ChartExEntry } from "./chart/chart.js";
+import { Chartsheet, type AddChartsheetOptions, type AddPivotChartsheetOptions } from "./chartsheet.js";
 import { DefinedNames, type DefinedNameModel } from "./defined-names.js";
 import type { PivotTable } from "./pivot-table.js";
-import { WorkbookReader, type WorkbookReaderOptions } from "./stream/workbook-reader.js";
-import { WorkbookWriter, type WorkbookWriterOptions } from "./stream/workbook-writer.js";
-import type { AddWorksheetOptions, CalculationProperties, CellValue, Font, ImageData, WorkbookProperties, WorkbookProtection, WorkbookView, Buffer as ExcelBuffer } from "./types.js";
+import { WorkbookReader, type WorkbookReaderOptions, type CommonInput } from "./stream/workbook-reader.browser.js";
+import { WorkbookWriter, type WorkbookWriterOptions } from "./stream/workbook-writer.browser.js";
+import type { AddWorksheetOptions, CalculationProperties, CellValue, Font, ImageData, ThreadedCommentPerson, WorkbookProperties, WorkbookProtection, WorkbookView, Buffer as ExcelBuffer } from "./types.js";
 import { Worksheet, type WorksheetModel } from "./worksheet.js";
-import { XLSX } from "./xlsx/xlsx.js";
+import type { ChartsheetModel } from "./xlsx/xform/sheet/chartsheet-xform.js";
+import { XLSX } from "./xlsx/xlsx.browser.js";
 import type { SyntaxProbe } from "../formula/default-syntax-probe.js";
 import type { MarkdownOptions } from "../markdown/types.js";
-import type { Readable } from "../stream/index.js";
 import type { IReadable, IWritable } from "../stream/types.js";
 import { type DateFormat } from "../../utils/datetime.js";
 /** Internal media type - more flexible than public Media type */
@@ -43,6 +45,16 @@ export interface WorkbookModel {
     worksheets: WorksheetModel[];
     sheets?: WorksheetModel[];
     definedNames: DefinedNameModel[];
+    /**
+     * Live `DefinedNames` instance — used by the write-time chartEx
+     * transform (`prepareChartExSidecars`) which registers hidden
+     * `_xlchart.vN.M` defined names on the fly and needs an object
+     * it can mutate in place. The serialised `definedNames` array
+     * above is re-materialised from this instance after the
+     * transform runs. Optional because the model is also used for
+     * input paths that don't carry the live instance.
+     */
+    definedNamesInstance?: unknown;
     views: WorkbookView[];
     company: string;
     manager: string;
@@ -60,12 +72,41 @@ export interface WorkbookModel {
     /** Loaded pivot tables from file - used during reconciliation */
     loadedPivotTables?: PivotTable[];
     calcProperties: Partial<CalculationProperties>;
-    /** Passthrough files (charts, etc.) preserved for round-trip */
-    passthrough?: Record<string, Uint8Array>;
-    /** Raw drawing XML data for passthrough (when drawing contains chart references) */
-    rawDrawings?: Record<string, Uint8Array>;
     /** Default font preserved from the original file for round-trip fidelity */
     defaultFont?: Partial<Font>;
+    /** Chart entries indexed by 1-based chart number */
+    chartEntries?: Record<number, ChartEntry>;
+    /** Chart rels indexed by chart number — preserved for round-trip */
+    chartRels?: Record<number, any[]>;
+    /** Chart style XML raw bytes indexed by style number — preserved for round-trip */
+    chartStyles?: Record<number, Uint8Array>;
+    /** Chart colors XML raw bytes indexed by colors number — preserved for round-trip */
+    chartColors?: Record<number, Uint8Array>;
+    chartExStyles?: Record<number, Uint8Array>;
+    chartExColors?: Record<number, Uint8Array>;
+    /** ChartEx raw bytes (Office 2016+ extended charts) indexed by chartEx number */
+    chartExEntries?: Record<number, Uint8Array>;
+    /** ChartEx rels indexed by chartEx number */
+    chartExRels?: Record<number, any[]>;
+    /** Structured chartEx entries (loaded or programmatically built) indexed by chartEx number */
+    chartExStructuredEntries?: Record<number, ChartExEntry>;
+    /** Chartsheets parsed from the XLSX file — preserved for round-trip */
+    chartsheets?: any[];
+    /**
+     * Office 365 threaded-comment person directory, hydrated from
+     * `xl/persons/person.xml` on load and serialised back on save when
+     * non-empty. See {@link Workbook.persons}.
+     */
+    persons?: ThreadedCommentPerson[];
+    /**
+     * Raw-passthrough slicer parts keyed by zip-relative path. Excelts
+     * does not structurally model slicers yet but preserves the bytes on
+     * round-trip so dashboards continue to work.
+     */
+    slicerParts?: Record<string, Uint8Array>;
+    slicerCacheParts?: Record<string, Uint8Array>;
+    timelineParts?: Record<string, Uint8Array>;
+    timelineCacheParts?: Record<string, Uint8Array>;
     /**
      * External workbook references in declaration order. Matches the on-disk
      * `[N]Sheet!Ref` indexing (1-based). Empty or undefined when the workbook
@@ -116,7 +157,7 @@ export interface ExternalLinkModel {
      * path relative to the current workbook: `"测试.xlsx"`, `"data/ref.xlsx"`.
      * Office resolves bare relative paths from the current workbook's
      * directory — *that* is the fix for the "Office goes to the Documents
-     * folder" problem described in exceljs#3039.
+     * folder" problem with external links.
      *
      * Absolute `file:///` or `http(s)://` URIs are accepted and written
      * through unchanged.
@@ -260,10 +301,6 @@ declare class Workbook {
     protected _worksheets: Worksheet[];
     protected _definedNames: DefinedNames;
     protected _themes?: unknown;
-    /** Passthrough files (charts, etc.) preserved for round-trip */
-    protected _passthrough: Record<string, Uint8Array>;
-    /** Raw drawing XML data for passthrough (when drawing contains chart references) */
-    protected _rawDrawings: Record<string, Uint8Array>;
     /** Default font preserved from original file for round-trip fidelity */
     protected _defaultFont?: Partial<Font>;
     /**
@@ -281,6 +318,53 @@ declare class Workbook {
     protected _writerExternalLinkCache: Map<string, ExternalLinkModel>;
     /** Global registry of table names (lowercase) for cross-worksheet uniqueness checks. */
     readonly _tableNames: Set<string>;
+    /** Chart entries indexed by 1-based chart number */
+    protected _chartEntries: Record<number, ChartEntry>;
+    /** Chart rels indexed by chart number — preserved for round-trip */
+    protected _chartRels: Record<number, any[]>;
+    /** Chart style XML raw bytes indexed by style number — preserved for round-trip */
+    protected _chartStyles: Record<number, Uint8Array>;
+    /** Chart colors XML raw bytes indexed by colors number — preserved for round-trip */
+    protected _chartColors: Record<number, Uint8Array>;
+    protected _chartExStyles: Record<number, Uint8Array>;
+    protected _chartExColors: Record<number, Uint8Array>;
+    /** ChartEx raw bytes (Office 2016+ extended charts) indexed by chartEx number */
+    protected _chartExEntries: Record<number, Uint8Array>;
+    /** ChartEx rels indexed by chartEx number */
+    protected _chartExRels: Record<number, any[]>;
+    /** ChartEx structured entries (loaded or built programmatically via addChartEx). */
+    protected _chartExStructuredEntries: Record<number, ChartExEntry>;
+    /** Chartsheets parsed from the XLSX file — preserved for round-trip */
+    protected _chartsheets: ChartsheetModel[];
+    /**
+     * Office 365 threaded-comment person directory (`xl/persons/person.xml`).
+     * Referenced by per-sheet `threadedComment/@personId`. Hydrated on
+     * load, preserved across save. Programmatic comments that don't supply
+     * a personId get auto-registered against this list.
+     */
+    protected _persons: ThreadedCommentPerson[];
+    /**
+     * Raw XML passthrough for Office 2010+ slicers and timelines.
+     *
+     * Structured creation of these controls is out of scope for the
+     * current release — the OOXML surface is large (four coordinated
+     * part families: `xl/slicers`, `xl/slicerCaches`, `xl/timelines`,
+     * `xl/timelineCaches`, plus sheet-level extensions and workbook-
+     * level cache list entries). The passthrough here prevents silent
+     * data loss when an Excel dashboard with slicers or timelines
+     * travels through excelts: we capture every part verbatim on read
+     * and re-emit them on write, along with their rels and Content
+     * Types overrides.
+     *
+     * The map key is the full zip-relative path (e.g.
+     * `"xl/slicers/slicer1.xml"`), the value is the exact bytes we
+     * found in the input. Loaders that construct a workbook
+     * programmatically never touch these maps.
+     */
+    protected _slicerParts: Record<string, Uint8Array>;
+    protected _slicerCacheParts: Record<string, Uint8Array>;
+    protected _timelineParts: Record<string, Uint8Array>;
+    protected _timelineCacheParts: Record<string, Uint8Array>;
     private _xlsx?;
     /**
      * @param options Optional construction options.
@@ -494,17 +578,14 @@ declare 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");
@@ -519,16 +600,15 @@ declare 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) {
@@ -541,7 +621,7 @@ declare class Workbook {
      * }
      * ```
      */
-    static createStreamReader(input: string | Readable, options?: WorkbookReaderOptions): WorkbookReader;
+    static createStreamReader(input: CommonInput, options?: WorkbookReaderOptions): WorkbookReader;
     get nextId(): number;
     /**
      * Add a new worksheet and return a reference to it
@@ -557,6 +637,22 @@ declare class Workbook {
      * Return a clone of worksheets in order
      */
     get worksheets(): Worksheet[];
+    /**
+     * Add a chartsheet containing a single chart and return the created chartsheet.
+     */
+    addChartsheet(name: string | undefined, options: AddChartsheetOptions): Chartsheet;
+    /**
+     * Add a chartsheet containing a classic pivot chart linked to an existing pivot table.
+     */
+    addPivotChartsheet(name: string | undefined, pivotTable: PivotTable, options: AddPivotChartsheetOptions): Chartsheet;
+    /** Return chartsheets in workbook order. */
+    get chartsheets(): Chartsheet[];
+    getChartsheet(nameOrIndex: string | number): Chartsheet | undefined;
+    removeChartsheet(nameOrIndex: string | number): boolean;
+    private _getChartsheetModel;
+    renameChartsheet(nameOrIndex: string | number, name: string): boolean;
+    copyChartsheet(nameOrIndex: string | number, name?: string): Chartsheet | undefined;
+    replaceChartsheetChart(nameOrIndex: string | number, chart: AddChartsheetOptions["chart"]): boolean;
     /**
      * Iterate over all sheets.
      *
@@ -564,6 +660,30 @@ declare class Workbook {
      */
     eachSheet(callback: (sheet: Worksheet, id: number) => void): void;
     get definedNames(): 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(): ThreadedCommentPerson[];
+    /**
+     * 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: string, userId?: string, providerId?: string): string;
     /**
      * Recalculate all formula cells in this workbook.
      *
@@ -666,6 +786,104 @@ declare class Workbook {
      */
     addImage(image: ImageData): number;
     getImage(id: number | string): WorkbookMedia | undefined;
+    /**
+     * Return the next available 1-based chart number.
+     */
+    nextChartNumber(): number;
+    /**
+     * Store a chart entry in the workbook (keyed by chartNumber).
+     */
+    addChartEntry(entry: ChartEntry): void;
+    setChartStyle(chartNumber: number, data: Uint8Array): void;
+    setChartColors(chartNumber: number, data: Uint8Array): void;
+    copyChartSidecars(sourceChartNumber: number, targetChartNumber: number, targetWorkbook?: Workbook): void;
+    /**
+     * 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.
+     */
+    private _rewriteCrossWorkbookImageTarget;
+    /**
+     * 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: number, targetChartExNumber: number, targetWorkbook?: Workbook): void;
+    private _applyChartsheetSidecars;
+    /**
+     * Retrieve a chart entry by its 1-based chart number.
+     */
+    getChartEntry(chartNumber: number): ChartEntry | undefined;
+    /**
+     * Remove a chart entry from the workbook.
+     * Safe to call even if the chart number doesn't exist.
+     */
+    removeChartEntry(chartNumber: number): void;
+    /** Return the next available 1-based chartEx number. */
+    nextChartExNumber(): number;
+    /**
+     * Store a structured chartEx entry.
+     * Loaded entries may also keep raw bytes for clean passthrough.
+     */
+    addChartExStructuredEntry(entry: ChartExEntry): void;
+    /** Get a structured chartEx entry by number. */
+    getChartExStructuredEntry(chartExNumber: number): ChartExEntry | undefined;
+    private _nextChartsheetNo;
+    /**
+     * 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.
+     */
+    private _nextSheetOrderNo;
+    private _nextSheetId;
+    /**
+     * 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: string, existing?: Worksheet | {
+        name: string;
+    }): string;
+    private _validateChartsheetName;
+    /** Remove a structured chartEx entry. */
+    removeChartExStructuredEntry(chartExNumber: number): void;
     /**
      * Declare that formulas in this workbook may reference an external
      * workbook. Registers the target so the output file contains the required