@devmm/puredocs-excel 1.0.4 → 1.0.6

package/dist/index.d.ts

@@ -506,8 +506,22 @@ declare class Cell {
     getValue(): CellValue;
     /**
      * Returns the display text of the cell value (always a string).
+     *
+     * Numbers are returned unformatted; use {@link getFormattedText} to apply the
+     * cell's number format.
      */
     getText(): string;
+    /**
+     * Returns the display text with the cell's number format applied, e.g. a
+     * value of 4.5 under `$#,##0.00` renders as `$4.50`, and a date under
+     * `dd/mm/yyyy` as `31/01/2025`.
+     *
+     * Falls back to {@link getText} for values with no format and for format
+     * codes outside the supported subset (fractions, scientific notation,
+     * conditional sections, elapsed time) — so the result is never a misleading
+     * rendering.
+     */
+    getFormattedText(): string;
     /**
      * Sets a formula. The leading '=' is optional.
      * Clears any cached value.
@@ -576,6 +590,45 @@ declare class Cell {
     }, ref: string): CellData;
 }
 
+/** Describes one structural edit on a sheet. */
+interface RefShift {
+    readonly dim: 'row' | 'col';
+    readonly kind: 'insert' | 'delete';
+    /** 1-based index of the first inserted/deleted row or column. */
+    readonly at: number;
+    /** Number of rows/columns inserted or deleted (>= 1). */
+    readonly count: number;
+    /** Name of the sheet the structural edit happened on. */
+    readonly sheetName: string;
+}
+/**
+ * Shifts one 1-based index. Returns `null` when the index falls inside a
+ * delete band (the row/column it pointed at no longer exists).
+ */
+declare function shiftIndex(index: number, shift: RefShift): number | null;
+/**
+ * Shifts an inclusive 1-based [start, end] span, clamping it against a delete
+ * band the way Excel does (endpoints move independently; a partially deleted
+ * span shrinks). Returns `null` when the span is entirely deleted.
+ */
+declare function shiftSpan(start: number, end: number, shift: RefShift): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Shifts a plain "A1" or "A1:B2" reference (no `$` markers — this is for
+ * model metadata such as merges, autofilter and validation sqref parts, which
+ * never carry them). Returns `null` when the referenced area is entirely
+ * deleted.
+ */
+declare function shiftRangeRef(ref: string, shift: RefShift): string | null;
+/**
+ * Shifts a space-separated list of range references (the OOXML `sqref` shape
+ * used by data validations). Parts that are entirely deleted are dropped;
+ * returns `null` when nothing survives.
+ */
+declare function shiftSqref(sqref: string, shift: RefShift): string | null;
+
 /** A part that a drawing anchor references (e.g. `xl/charts/chart1.xml`). */
 interface DrawingDependentPart {
     /** Package-relative path, no leading slash — e.g. `xl/charts/chart1.xml`. */
@@ -612,6 +665,58 @@ declare function buildDrawingXml(anchorsXml: string): string;
 /** Builds a generic `.rels` part from a list of `<Relationship .../>` strings. */
 declare function buildRelsXml(relationships: readonly string[]): string;
 
+/**
+ * Represents the contents of an unzipped xlsx file.
+ * Keys are file paths within the archive (e.g. "xl/workbook.xml").
+ * Values are raw UTF-8 bytes.
+ */
+type ZipEntries = Map<string, Uint8Array>;
+/**
+ * Unzips an xlsx file buffer into a map of path → bytes.
+ *
+ * @param buffer - ArrayBuffer or Uint8Array of the xlsx file
+ * @returns Map of file paths to their raw bytes
+ */
+declare function unzipXlsx(buffer: ArrayBuffer | Uint8Array): ZipEntries;
+/**
+ * Reads and decodes a UTF-8 text entry from a zip archive.
+ * Returns undefined if the entry does not exist.
+ */
+declare function readXmlEntry(entries: ZipEntries, path: string): string | undefined;
+/**
+ * Reads and decodes a UTF-8 text entry, throwing if missing.
+ */
+declare function requireXmlEntry(entries: ZipEntries, path: string): string;
+/**
+ * Returns all entry paths that match the given prefix.
+ * Useful for listing worksheets: prefix = "xl/worksheets/".
+ */
+declare function listEntries(entries: ZipEntries, prefix: string): string[];
+
+/**
+ * Round-trip preservation of package parts the core model does not understand.
+ *
+ * `Workbook.saveAsBuffer()` rebuilds the package from the in-memory model, so
+ * any part core never parsed — drawings, images, themes, comments, pivot
+ * caches, docProps — would silently disappear on open→save. This module
+ * captures those parts at open time so the save pipeline can pass them through
+ * untouched.
+ *
+ * Parts core *does* own are excluded: it regenerates them, and keeping a stale
+ * copy would produce duplicates or dangling relationships.
+ */
+
+interface Relationship {
+    id: string;
+    type: string;
+    /** Target exactly as written in the source rels part. */
+    target: string;
+    /** Target resolved to a package-absolute path, or undefined if external. */
+    resolved?: string;
+    /** True when the relationship points outside the package (TargetMode). */
+    external: boolean;
+}
+
 /**
  * Represents a rectangular range of cells for bulk operations.
  * Port of TVE.PureDocs.Excel.Range (C#)
@@ -637,7 +742,23 @@ declare class Range {
     getValues(): CellValue[][];
     /** Clears all cells in the range (values only, preserves style). */
     clear(): void;
-    /** Auto-fits all columns in the range. */
+    /** Clears values AND styles of all cells in the range. */
+    clearAll(): void;
+    /**
+     * Moves the whole range so its top-left cell lands on `destTopLeft`,
+     * carrying values, formulas, styles and spill anchors. The vacated cells
+     * are cleared and the destination block is fully replaced (empty source
+     * cells clear their destination). Overlapping source/destination is safe.
+     * Formula text is NOT adjusted for the new position.
+     *
+     * @example
+     * ws.getRange('A1:B3').moveTo('D1');
+     */
+    moveTo(destTopLeft: string): void;
+    /**
+     * Auto-fits all columns in the range. Measures every column in one sparse
+     * sweep rather than re-scanning the sheet per column.
+     */
     autoFit(): void;
     /** Applies a CellStyle to all cells in the range. Returns this for chaining. */
     setStyle(style: CellStyle): this;
@@ -670,6 +791,59 @@ declare class Range {
  */
 
 type SheetVisibility = 'visible' | 'hidden' | 'veryHidden';
+/**
+ * What users may still do on a protected sheet. Named from the user's point of
+ * view — the same way Excel's "Protect Sheet" dialog lists its checkboxes —
+ * because the underlying OOXML attributes are inverted (`formatCells="1"` means
+ * formatting is *blocked*), which is a reliable source of bugs.
+ *
+ * Defaults match Excel: selecting cells stays allowed, everything else does not.
+ */
+interface SheetProtection {
+    allowSelectLockedCells: boolean;
+    allowSelectUnlockedCells: boolean;
+    allowFormatCells: boolean;
+    allowFormatColumns: boolean;
+    allowFormatRows: boolean;
+    allowInsertRows: boolean;
+    allowInsertColumns: boolean;
+    allowInsertHyperlinks: boolean;
+    allowDeleteRows: boolean;
+    allowDeleteColumns: boolean;
+    allowSort: boolean;
+    allowAutoFilter: boolean;
+    allowPivotTables: boolean;
+    allowEditObjects: boolean;
+    allowEditScenarios: boolean;
+}
+/** A hyperlink attached to a cell or range. */
+interface Hyperlink {
+    /** The cell or range the link covers, e.g. "A1" or "A1:B2". */
+    readonly ref: string;
+    /** External target, e.g. "https://example.com" or "mailto:a@b.c". */
+    readonly target?: string;
+    /** In-workbook destination, e.g. "Sheet2!A1" or a defined name. */
+    readonly location?: string;
+    /** Text to show instead of the cell's own value. */
+    readonly display?: string;
+    /** Hover tooltip. */
+    readonly tooltip?: string;
+}
+/** A classic cell comment (a "note" in current Excel versions). */
+interface CellComment {
+    /** The cell the comment is attached to, e.g. "B4". */
+    readonly ref: string;
+    readonly text: string;
+    readonly author: string;
+}
+/** Outcome of a structural edit (insert/delete rows or columns). */
+interface StructuralEditResult {
+    /**
+     * References (post-shift, on this sheet) of formula cells that now contain
+     * `#REF!` because something they pointed at was deleted.
+     */
+    readonly refErrors: readonly string[];
+}
 declare class Worksheet {
     #private;
     /** @internal */
@@ -699,10 +873,46 @@ declare class Worksheet {
     getCellFormula(reference: string): string | null;
     /** Spill range (e.g. "A1:A3") of a dynamic-array anchor, or null. Supports A1#. */
     getSpillRange(reference: string): string | null;
+    /**
+     * Iterates the populated rows of the sheet in ascending row order, yielding
+     * each row's 1-based index and its cells (left to right). Rows and cells
+     * that were never written are skipped, so a sparse sheet iterates in
+     * O(populated cells) regardless of its bounds.
+     *
+     * @example
+     * for (const { rowIndex, cells } of ws.rows()) {
+     *   for (const cell of cells) console.log(rowIndex, cell.reference, cell.getValue());
+     * }
+     */
+    rows(): IterableIterator<{
+        rowIndex: number;
+        cells: Cell[];
+    }>;
+    /**
+     * Iterates every populated cell of the sheet in row-major order. Sparse
+     * counterpart to scanning {@link usedBounds} with {@link tryGetCell}.
+     *
+     * @example
+     * for (const cell of ws.cells()) console.log(cell.reference, cell.getValue());
+     */
+    cells(): IterableIterator<Cell>;
+    /**
+     * @internal Visits the populated cells inside a rectangle, passing the
+     * coordinates it already knows so the callback never has to parse a
+     * reference. Backs the Range operations that must not create cells; probing
+     * every coordinate would cost O(area) even on an empty sheet.
+     */
+    forEachCellIn(startRow: number, startColumn: number, endRow: number, endColumn: number, action: (cell: Cell, row: number, column: number) => void): void;
+    /**
+     * @internal Moves a cell by coordinates, skipping the reference parsing that
+     * the public {@link moveCell} has to do. Used by bulk range moves.
+     */
+    moveCellRC(fromRow: number, fromColumn: number, toRow: number, toColumn: number): void;
     /**
      * Returns the 1-based extent of populated cells (largest row and column that
      * contain data). Returns zeros for an empty sheet. Useful for snapshotting a
-     * sheet into a dense 2D array.
+     * sheet into a dense 2D array — though {@link rows} and {@link cells} are
+     * cheaper when a dense shape is not actually required.
      */
     get usedBounds(): {
         rowCount: number;
@@ -710,18 +920,134 @@ declare class Worksheet {
     };
     /** Sets the width of a column (1-based index). */
     setColumnWidth(columnIndex: number, width: number): void;
+    /**
+     * Removes the explicit width of a column so it falls back to the sheet
+     * default. Counterpart to {@link setColumnWidth}; afterwards
+     * {@link getColumnWidth} returns `undefined`. A hidden column stays hidden.
+     */
+    resetColumnWidth(columnIndex: number): void;
+    /**
+     * Shows or hides a column (1-based index). Hidden columns round-trip to the
+     * file as `<col hidden="1">` and keep any explicit width.
+     */
+    setColumnHidden(columnIndex: number, hidden?: boolean): void;
+    /** True if the given 1-based column is hidden. */
+    isColumnHidden(columnIndex: number): boolean;
+    /**
+     * Returns the explicit width of a column (1-based index), or `undefined` when
+     * the column uses the sheet default. Counterpart to {@link setColumnWidth};
+     * widths parsed from an existing file are visible here too, so column layout
+     * can be round-tripped.
+     */
+    getColumnWidth(columnIndex: number): number | undefined;
     /** Auto-fits column width based on content (approximate). */
     autoFitColumn(columnIndex: number): void;
+    /**
+     * Auto-fits an inclusive span of columns (1-based) in a single pass over the
+     * populated cells, instead of re-scanning the sheet once per column.
+     */
+    autoFitColumns(firstColumn: number, lastColumn: number): void;
     /** Sets the height of a row (1-based index). */
     setRowHeight(rowIndex: number, height: number): void;
+    /**
+     * Returns the explicit height of a row (1-based index), or `undefined` when
+     * the row uses the sheet default. Counterpart to {@link setRowHeight}.
+     */
+    getRowHeight(rowIndex: number): number | undefined;
+    /**
+     * Removes the explicit height of a row so it falls back to the sheet
+     * default. Counterpart to {@link setRowHeight}; afterwards
+     * {@link getRowHeight} returns `undefined`. A hidden row stays hidden.
+     */
+    resetRowHeight(rowIndex: number): void;
     /** Shows or hides a row (1-based index). Hidden rows affect SUBTOTAL(101-111). */
     setRowHidden(rowIndex: number, hidden?: boolean): void;
     /** True if the given 1-based row is hidden. */
     isRowHidden(rowIndex: number): boolean;
+    /**
+     * The 1-based indices of every hidden row, ascending. Sparse counterpart to
+     * probing {@link isRowHidden} across {@link usedBounds}.
+     */
+    get hiddenRows(): readonly number[];
+    /**
+     * The 1-based indices of every hidden column, ascending. Counterpart to
+     * {@link isColumnHidden}, in the same spirit as {@link hiddenRows}.
+     */
+    get hiddenColumns(): readonly number[];
+    /**
+     * Inserts `count` empty rows starting at row `at` (1-based). Everything at
+     * or below `at` moves down: cell values, formulas (references are rewritten
+     * the way Excel does), styles, row heights, hidden flags, merges,
+     * autofilter and data-validation ranges.
+     *
+     * Frozen panes are a view property and stay put. Drawing/chart anchors
+     * preserved from a loaded file are opaque XML and do NOT shift — images
+     * keep their absolute position (known limitation).
+     *
+     * When formulas on OTHER sheets reference this sheet, use the
+     * Workbook-level counterpart so they are rewritten too, or call
+     * `applyExternalShift` on each sheet yourself. If a RecalcEngine is
+     * attached, notify it afterwards (e.g. `engine.onRowsInserted(...)`).
+     *
+     * @example
+     * ws.insertRows(3, 2); // pushes row 3 and below down by two rows
+     */
+    insertRows(at: number, count?: number): StructuralEditResult;
+    /**
+     * Deletes `count` rows starting at row `at` (1-based). Rows below move up;
+     * formulas referencing the deleted band get `#REF!` (fully inside) or
+     * shrink (partially inside), exactly like Excel. See {@link insertRows}
+     * for the shifting rules and known limitations.
+     */
+    deleteRows(at: number, count?: number): StructuralEditResult;
+    /**
+     * Inserts `count` empty columns starting at column `at` (1-based).
+     * Column-level counterpart to {@link insertRows}; widths and hidden flags
+     * shift with the columns.
+     */
+    insertColumns(at: number, count?: number): StructuralEditResult;
+    /**
+     * Deletes `count` columns starting at column `at` (1-based).
+     * Column-level counterpart to {@link deleteRows}.
+     */
+    deleteColumns(at: number, count?: number): StructuralEditResult;
+    /**
+     * @internal Rewrites formulas on THIS sheet after a structural edit on a
+     * DIFFERENT sheet (named by `shift.sheetName`), so qualified references
+     * like `'Data'!A5` stay correct. Cell positions here do not change.
+     */
+    applyExternalShift(shift: RefShift): StructuralEditResult;
+    /**
+     * Moves a cell's full contents — value, formula, style and spill anchor —
+     * to another cell, overwriting the destination and clearing the source.
+     * A missing source clears the destination. This is a literal move: formula
+     * text is NOT adjusted for the new position.
+     *
+     * @example
+     * ws.moveCell('A1', 'C5');
+     */
+    moveCell(from: string, to: string): void;
+    /**
+     * Copies a cell's value, formula and style to another cell, overwriting the
+     * destination and leaving the source untouched. A missing source clears the
+     * destination. This is a literal copy: formula references are NOT adjusted,
+     * and the spill anchor (`arrayRef`) is not copied — a recalc engine
+     * re-establishes it.
+     *
+     * @example
+     * ws.copyCell('A1', 'C5');
+     */
+    copyCell(from: string, to: string): void;
     /** Merges cells in the given range (e.g. "A1:B2"). */
     mergeCells(rangeReference: string): void;
     /** Removes a merge for the given range reference. */
     unmergeCells(rangeReference: string): void;
+    /**
+     * All merged ranges on this sheet, in the order they were added (or parsed).
+     * Includes merges read from an existing file, so callers never need to track
+     * their own copy of the list.
+     */
+    get merges(): readonly string[];
     /**
      * Freezes rows and/or columns.
      * @param row    Number of rows to freeze (0 = none)
@@ -739,20 +1065,160 @@ declare class Worksheet {
     /** Sets the visibility state of this worksheet. */
     setVisibility(state: SheetVisibility): void;
     get visibility(): SheetVisibility;
+    /**
+     * Turns on sheet protection, optionally relaxing individual permissions.
+     * Cells are locked by default in Excel, so protecting a sheet makes all of
+     * them read-only; clear a cell style's `locked` flag to leave a cell editable.
+     *
+     * Excel's sheet protection is a UI guard, **not** security: the contents stay
+     * readable to anything that opens the file. This library therefore never
+     * creates a protection password. A password read from an existing file is
+     * preserved so the sheet round-trips unchanged.
+     *
+     * @example
+     * ws.protect();                                  // lock everything
+     * ws.protect({ allowSort: true, allowAutoFilter: true });
+     */
+    protect(options?: Partial<SheetProtection>): void;
+    /** Turns off sheet protection, discarding any password read from a file. */
+    unprotect(): void;
+    /** True when this sheet is protected. */
+    get isProtected(): boolean;
+    /** The active permissions, or `undefined` when the sheet is not protected. */
+    get protection(): Readonly<SheetProtection> | undefined;
+    /**
+     * Attaches a hyperlink to a cell or range. Give `target` for an external
+     * destination or `location` for one inside the workbook; passing both keeps
+     * the external target and uses the location as its fragment, which is how
+     * Excel links to an anchor within a document.
+     *
+     * A cell's displayed text still comes from its own value — set that
+     * separately; `display` only overrides what Excel shows in the edit bar.
+     *
+     * @example
+     * ws.getCell('A1').setValue('Anthropic');
+     * ws.setHyperlink('A1', { target: 'https://anthropic.com', tooltip: 'Open site' });
+     * ws.setHyperlink('B1', { location: "'Sheet2'!A1" });
+     */
+    setHyperlink(ref: string, link: {
+        target?: string;
+        location?: string;
+        display?: string;
+        tooltip?: string;
+    }): void;
+    /** The hyperlink covering exactly this ref, or undefined. */
+    getHyperlink(ref: string): Hyperlink | undefined;
+    /** Removes the hyperlink on this ref. Returns true if one was there. */
+    removeHyperlink(ref: string): boolean;
+    /** Every hyperlink on the sheet, including ones read from a file. */
+    get hyperlinks(): readonly Hyperlink[];
+    /**
+     * Attaches a comment (a "note" in current Excel versions) to a cell,
+     * replacing any comment already there.
+     *
+     * Note that writing comments makes this sheet regenerate its comment and
+     * legacy-drawing parts on save. If the file was opened with other legacy
+     * drawing content on the same sheet — form controls, for instance — that
+     * content is not reproduced. Reading comments has no such effect.
+     *
+     * @example
+     * ws.setComment('B4', 'Check this figure', { author: 'Bill' });
+     */
+    setComment(ref: string, text: string, options?: {
+        author?: string;
+    }): void;
+    /** The comment on a cell, or undefined. */
+    getComment(ref: string): CellComment | undefined;
+    /** Removes the comment on a cell. Returns true if one was there. */
+    removeComment(ref: string): boolean;
+    /** Every comment on the sheet, including ones read from a file. */
+    get comments(): readonly CellComment[];
+    /** @internal True when this sheet must write its own comment parts. */
+    get ownsCommentParts(): boolean;
+    /**
+     * @internal True when the sheet took over its comment parts and any preserved
+     * originals must be dropped — including the case where every comment was
+     * deleted and nothing replaces them.
+     */
+    get commentPartsReplaced(): boolean;
     /**
      * Attaches a drawing provider (e.g. a chart) to this worksheet.
      * Satellite packages such as `@devmm/puredocs-excel-charts` call this; the core
      * save pipeline turns registered providers into valid OOXML drawing/chart parts.
      */
     addDrawingProvider(provider: DrawingProvider): void;
+    /**
+     * Detaches every drawing from this worksheet — both providers added in memory
+     * and any drawing preserved from the file the workbook was opened from.
+     *
+     * Call before re-adding charts when exporting the same in-memory workbook
+     * repeatedly, otherwise each export appends another copy; call on its own to
+     * deliberately drop a chart that came from the source file.
+     */
+    clearDrawings(): void;
     /** True when this worksheet has at least one drawing to serialise. */
     get hasDrawings(): boolean;
     /** @internal — drawing providers, consumed by the save pipeline. */
     get drawingProviders(): readonly DrawingProvider[];
+    /**
+     * @internal Relationships carried over from the source file, minus any whose
+     * leaf element is no longer emitted (a drawing replaced by live providers, or
+     * cleared outright). The save pipeline writes these into the sheet's rels.
+     */
+    get preservedRelationships(): readonly Relationship[];
+    /**
+     * @internal Package paths of relationships that were preserved at load time
+     * but are no longer referenced — a drawing replaced by live providers, or one
+     * cleared outright. The save pipeline prunes these parts so the output has no
+     * orphans.
+     */
+    get droppedPreservedTargets(): readonly string[];
+    /**
+     * @internal Relationship id for a drawing built from live providers. Chosen to
+     * clear every preserved id so the two sets cannot collide.
+     */
+    get drawingRelId(): string;
+    /**
+     * @internal Relationship ids for the parts this sheet generates itself.
+     *
+     * Derived purely from the model so the worksheet XML and the sheet's rels part
+     * — which are written by different code — cannot disagree about an id. Order is
+     * fixed: drawing, then external hyperlinks in insertion order, then the
+     * comments part and its legacy VML drawing.
+     */
+    generatedRels(): {
+        drawing?: string;
+        hyperlinks: Map<string, string>;
+        comments?: string;
+        vmlDrawing?: string;
+    };
+    /** @internal Captures round-trip state from the source package. */
+    loadPreservedState(worksheetXml: string, relationships: readonly Relationship[]): void;
+    /**
+     * @internal Package paths of the comment parts this sheet read at load time.
+     * The save pipeline drops them from the preserved set once the sheet takes
+     * ownership, so they are not written twice.
+     */
+    commentPartPaths(): string[];
+    /**
+     * @internal The relationship pointing at this sheet's comments part, if the
+     * sheet was loaded from a file that had one.
+     */
+    commentsPartPath(): string | undefined;
     /** Builds the xl/worksheets/sheetN.xml string. */
     buildXml(): string;
     /** Parses xl/worksheets/sheetN.xml and loads cells into memory. */
     loadFromXml(xml: string): void;
+    /** @internal Parses an `xl/comments*.xml` part into this sheet's comments. */
+    loadCommentsXml(xml: string): void;
+    /** @internal The comments part content, when this sheet owns it. */
+    buildCommentsXml(): string;
+    /**
+     * @internal The legacy VML drawing that positions the comment boxes. Excel
+     * needs it to draw the note indicator and popup; the comments part alone
+     * carries only the text.
+     */
+    buildCommentsVml(): string;
 }
 
 /**
@@ -835,10 +1301,36 @@ declare class Workbook {
      * Mirrors workbook.AddWorksheet(name) in C#.
      */
     addWorksheet(name: string): Worksheet;
+    /**
+     * Removes the worksheet with the given name, along with any defined names
+     * scoped to it. Throws if the sheet does not exist or is the last remaining
+     * one — a workbook must always keep at least one sheet.
+     *
+     * Sheet ids and relationship ids are re-derived from document order on save,
+     * so the remaining sheets stay consistent after a removal.
+     */
+    removeWorksheet(name: string): void;
     /**
      * Returns a worksheet by name. Throws if not found.
      */
     getWorksheet(name: string): Worksheet;
+    /**
+     * Inserts rows on one sheet and keeps the whole workbook consistent:
+     * formulas on OTHER sheets that reference the edited sheet, and defined
+     * names, are rewritten too. Prefer this over `Worksheet.insertRows` in a
+     * multi-sheet workbook.
+     *
+     * @returns The edited sheet's result; `refErrors` additionally includes
+     *          sheet-qualified refs (e.g. `"Other!B2"`) for affected formula
+     *          cells on other sheets.
+     */
+    insertRows(sheetName: string, at: number, count?: number): StructuralEditResult;
+    /** Workbook-wide counterpart to `Worksheet.deleteRows`. See {@link insertRows}. */
+    deleteRows(sheetName: string, at: number, count?: number): StructuralEditResult;
+    /** Workbook-wide counterpart to `Worksheet.insertColumns`. See {@link insertRows}. */
+    insertColumns(sheetName: string, at: number, count?: number): StructuralEditResult;
+    /** Workbook-wide counterpart to `Worksheet.deleteColumns`. See {@link insertRows}. */
+    deleteColumns(sheetName: string, at: number, count?: number): StructuralEditResult;
     /**
      * Defines (or replaces) a named range.
      *
@@ -886,6 +1378,10 @@ declare class Workbook {
  *
  * Port of TVE.PureDocs.Excel.CellReference (C#)
  */
+/** Largest 1-based row index a worksheet can have (Excel limit). */
+declare const EXCEL_MAX_ROWS = 1048576;
+/** Largest 1-based column index a worksheet can have (column XFD). */
+declare const EXCEL_MAX_COLUMNS = 16384;
 interface ParsedCellRef {
     readonly row: number;
     readonly column: number;
@@ -927,6 +1423,15 @@ declare function columnLetter(column: number): string;
  * columnNumber("AA") // 27
  */
 declare function columnNumber(letters: string): number;
+/**
+ * Formats start/end coordinates as a range reference string. Collapses to a
+ * single cell reference when start and end are the same cell.
+ *
+ * @example
+ * formatRangeRef(1, 1, 10, 2) // "A1:B10"
+ * formatRangeRef(1, 1, 1, 1)  // "A1"
+ */
+declare function formatRangeRef(startRow: number, startColumn: number, endRow: number, endColumn: number): string;
 /**
  * Parses a range reference string like "A1:B10" into start/end coordinates.
  */
@@ -937,6 +1442,24 @@ declare function parseRangeRef(rangeReference: string): {
     endColumn: number;
 };
 
+interface FormulaRewriteResult {
+    /** The rewritten formula text (without leading '='). */
+    readonly text: string;
+    /** True when any reference was actually rewritten. */
+    readonly changed: boolean;
+    /** True when at least one reference was replaced by `#REF!`. */
+    readonly hasRefError: boolean;
+}
+/**
+ * Rewrites the references in one formula for a structural edit.
+ *
+ * @param formula      Formula text without the leading '='.
+ * @param shift        The structural edit that happened.
+ * @param formulaSheet Name of the sheet this formula lives on — unqualified
+ *                     references resolve against it.
+ */
+declare function shiftFormulaRefs(formula: string, shift: RefShift, formulaSheet: string): FormulaRewriteResult;
+
 /**
  * OLE Automation Date (OADate) helpers.
  *
@@ -972,6 +1495,51 @@ declare function isDateFormatId(formatId: number): boolean;
  */
 declare function isDateFormatCode(formatCode: string): boolean;
 
+/**
+ * Renders a numeric value through an OOXML number-format code.
+ *
+ * Deliberately a *subset* of the full spec — it covers the codes an editor
+ * actually round-trips (integers, fixed decimals, thousands separators,
+ * currency, percentages, and positive/negative/zero sections) and returns
+ * `null` for anything it does not understand, so callers can fall back to the
+ * raw value rather than display something wrong.
+ *
+ * Not handled (returns null): fractions (`# ?/?`), scientific (`0.00E+00`),
+ * date/time codes (see date-format-renderer.ts, which Cell routes Date values
+ * to), and conditional sections such as `[<=9999999]###-####`.
+ */
+/**
+ * Applies `formatCode` to `value`.
+ *
+ * @returns the formatted string, or `null` when the code is outside the
+ *          supported subset (caller should fall back to the raw value).
+ */
+declare function formatNumberWithCode(value: number, formatCode: string): string | null;
+
+/**
+ * Renders a Date through an OOXML date/time format code.
+ *
+ * Deliberately a *subset* of the full spec, mirroring the philosophy of
+ * number-format-renderer: it covers the codes an editor actually round-trips
+ * (`yyyy`, `yy`, `m`→`mmmm`, `d`→`dddd`, `h`/`hh`, `s`/`ss`, `AM/PM`, quoted
+ * literals, separators) and returns `null` for anything it does not
+ * understand — elapsed-time brackets (`[h]`), fractional seconds (`ss.00`),
+ * era codes — so callers can fall back rather than display something wrong.
+ *
+ * The `m` month-vs-minute ambiguity uses the standard OOXML rule: `m`/`mm`
+ * means minutes when the previous time token is hours or the next one is
+ * seconds; otherwise it means month.
+ */
+/**
+ * Formats a Date with an OOXML date/time format code, e.g. a value of
+ * 2025-01-31 under `dd/mm/yyyy` renders as `31/01/2025`.
+ *
+ * Returns `null` when the code uses constructs outside the supported subset
+ * (elapsed time `[h]`, fractional seconds, era codes) — callers should fall
+ * back to a locale default rather than render something misleading.
+ */
+declare function formatDateCode(date: Date, formatCode: string): string | null;
+
 /**
  * Cross-platform XML parser.
  *
@@ -990,6 +1558,12 @@ type XmlElement = {
 /**
  * Parses an XML string into a simple XmlElement tree.
  */
+/**
+ * Decodes the five predefined XML entities. `&amp;` is expanded last so that an
+ * escaped entity such as `&amp;lt;` decodes to the literal text `&lt;` rather
+ * than being expanded twice.
+ */
+declare function decodeXmlEntities(value: string): string;
 declare function parseXml(xmlString: string): XmlElement;
 /**
  * Decodes a Uint8Array to a UTF-8 string.
@@ -1055,6 +1629,8 @@ declare const REL_TYPES: {
     readonly chart: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart";
     readonly drawing: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing";
     readonly hyperlink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+    readonly comments: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
+    readonly vmlDrawing: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing";
 };
 declare const CONTENT_TYPES: {
     readonly workbook: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml";
@@ -1065,36 +1641,10 @@ declare const CONTENT_TYPES: {
     readonly chart: "application/vnd.openxmlformats-officedocument.drawingml.chart+xml";
     readonly relationships: "application/vnd.openxmlformats-package.relationships+xml";
     readonly coreProperties: "application/vnd.openxmlformats-package.core-properties+xml";
+    readonly comments: "application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml";
+    readonly vmlDrawing: "application/vnd.openxmlformats-officedocument.vmlDrawing";
 };
 
-/**
- * Represents the contents of an unzipped xlsx file.
- * Keys are file paths within the archive (e.g. "xl/workbook.xml").
- * Values are raw UTF-8 bytes.
- */
-type ZipEntries = Map<string, Uint8Array>;
-/**
- * Unzips an xlsx file buffer into a map of path → bytes.
- *
- * @param buffer - ArrayBuffer or Uint8Array of the xlsx file
- * @returns Map of file paths to their raw bytes
- */
-declare function unzipXlsx(buffer: ArrayBuffer | Uint8Array): ZipEntries;
-/**
- * Reads and decodes a UTF-8 text entry from a zip archive.
- * Returns undefined if the entry does not exist.
- */
-declare function readXmlEntry(entries: ZipEntries, path: string): string | undefined;
-/**
- * Reads and decodes a UTF-8 text entry, throwing if missing.
- */
-declare function requireXmlEntry(entries: ZipEntries, path: string): string;
-/**
- * Returns all entry paths that match the given prefix.
- * Useful for listing worksheets: prefix = "xl/worksheets/".
- */
-declare function listEntries(entries: ZipEntries, prefix: string): string[];
-
 /**
  * Represents the file entries to be zipped.
  * Keys are paths within the archive, values are either bytes or a UTF-8 string.
@@ -1116,4 +1666,4 @@ declare function setXmlEntry(entries: ZipInput, path: string, xml: string): void
  */
 declare function setBinaryEntry(entries: ZipInput, path: string, bytes: Uint8Array): void;
 
-export { CONTENT_TYPES, Cell, type CellData, CellStyle, type CellValue, type ColorXmlAttrs, type DefinedName, DefinedNameManager, type DrawingDependentPart, type DrawingProvider, ExcelAlignment, ExcelBorder, ExcelBorderEdge, ExcelBorderStyle, ExcelColor, ExcelFill, ExcelFont, type ExcelFontOptions, ExcelHorizontalAlignment, ExcelNumberFormat, ExcelPatternType, ExcelReadingOrder, ExcelUnderline, ExcelVerticalAlignRun, ExcelVerticalAlignment, NS, type ParsedCellRef, REL_TYPES, Range, type SheetVisibility, StyleManager, WORKSHEET_DRAWING_REL_ID, Workbook, Worksheet, type XmlAttrs, XmlBuilder, type XmlElement, type ZipEntries, type ZipInput, buildDrawingXml, buildRelsXml, cellRefFromRowCol, columnLetter, columnNumber, decodeUtf8, encodeUtf8, escapeXml, fromOADate, getAttr, getElementsByTagName, isDateFormatCode, isDateFormatId, listEntries, parseCellRef, parseRangeRef, parseXml, readXmlEntry, requireXmlEntry, setBinaryEntry, setXmlEntry, toOADate, unzipXlsx, xml, zipXlsx };
+export { CONTENT_TYPES, Cell, type CellComment, type CellData, CellStyle, type CellValue, type ColorXmlAttrs, type DefinedName, DefinedNameManager, type DrawingDependentPart, type DrawingProvider, EXCEL_MAX_COLUMNS, EXCEL_MAX_ROWS, ExcelAlignment, ExcelBorder, ExcelBorderEdge, ExcelBorderStyle, ExcelColor, ExcelFill, ExcelFont, type ExcelFontOptions, ExcelHorizontalAlignment, ExcelNumberFormat, ExcelPatternType, ExcelReadingOrder, ExcelUnderline, ExcelVerticalAlignRun, ExcelVerticalAlignment, type FormulaRewriteResult, type Hyperlink, NS, type ParsedCellRef, REL_TYPES, Range, type RefShift, type SheetProtection, type SheetVisibility, type StructuralEditResult, StyleManager, WORKSHEET_DRAWING_REL_ID, Workbook, Worksheet, type XmlAttrs, XmlBuilder, type XmlElement, type ZipEntries, type ZipInput, buildDrawingXml, buildRelsXml, cellRefFromRowCol, columnLetter, columnNumber, decodeUtf8, decodeXmlEntities, encodeUtf8, escapeXml, formatDateCode, formatNumberWithCode, formatRangeRef, fromOADate, getAttr, getElementsByTagName, isDateFormatCode, isDateFormatId, listEntries, parseCellRef, parseRangeRef, parseXml, readXmlEntry, requireXmlEntry, setBinaryEntry, setXmlEntry, shiftFormulaRefs, shiftIndex, shiftRangeRef, shiftSpan, shiftSqref, toOADate, unzipXlsx, xml, zipXlsx };