xlvane 1.2.2 → 1.3.0

package/docs/errors.md

@@ -14,7 +14,7 @@ Each code links to its section, which says what to do. The CLI prints the code a
 | --- | --- |
 | [`XLV_E_INVALID_INPUT`](#xlv_e_invalid_input) | The input is not what the function expects: `readWorkbook` and `inspect` accept a `Uint8Array`, an `ArrayBuffer` (or another typed-array … |
 | [`XLV_E_INVALID_OPTION`](#xlv_e_invalid_option) | An option is unknown, has the wrong type or is out of range. |
-| [`XLV_E_INVALID_ARGUMENT`](#xlv_e_invalid_argument) | An argument of a method of `@xlvane/compat` is not valid, in a case where exceljs 4.4.0 accepts it and loses or moves data without an … |
+| [`XLV_E_INVALID_ARGUMENT`](#xlv_e_invalid_argument) | An argument would lose or move data: a method of `@xlvane/compat` where exceljs 4.4.0 accepts it silently, or `appendRows` with array rows when the starting column is ambiguous. |
 | [`XLV_E_LIMIT_EXCEEDED`](#xlv_e_limit_exceeded) | The file exceeds one of the resource limits (`ReadLimits`): input size, number of ZIP entries, decompressed size of one entry or of all … |
 | [`XLV_E_NOT_ZIP`](#xlv_e_not_zip) | The input is not a ZIP archive, so it cannot be an XLSX file. |
 | [`XLV_E_UNSUPPORTED_CONTAINER`](#xlv_e_unsupported_container) | The input is a Compound File Binary container (signature `D0 CF 11 E0 A1 B1 1A E1`). |
@@ -37,6 +37,7 @@ Each code links to its section, which says what to do. The CLI prints the code a
 | [`XLV_E_INVALID_DEFINED_NAME`](#xlv_e_invalid_defined_name) | `defineName` (or `definedNames` of `writeWorkbookStream`) was given a name that spreadsheet applications do not accept, or a duplicate. |
 | [`XLV_E_INVALID_HYPERLINK`](#xlv_e_invalid_hyperlink) | `link` (or `hyperlinks` of a sheet of `writeWorkbookStream`) was given a hyperlink that cannot be stored: not an object, an unknown … |
 | [`XLV_E_INVALID_IMAGE`](#xlv_e_invalid_image) | `NewWorkbook.addImage` (or `images` of `writeWorkbookStream`) was given something that is not the bytes of a PNG, JPEG or GIF file. |
+| [`XLV_E_INVALID_CHART`](#xlv_e_invalid_chart) | `addChart` (or `charts` of a sheet of `writeWorkbookStream`) was given a chart xlvane cannot write: an unknown type or option, no series or more than 255, a range that is not one row or column of a named sheet, … |
 | [`XLV_E_INVALID_TABLE`](#xlv_e_invalid_table) | `addTable` (or `tables` of a sheet of `writeWorkbookStream`) was given a table that spreadsheet applications do not accept: a name or … |
 | [`XLV_E_OVERLAPPING_MERGE`](#xlv_e_overlapping_merge) | A range passed to `merge()` shares cells with a range merged before. |
 | [`XLV_E_FILE_EXISTS`](#xlv_e_file_exists) | `writeWorkbookFile` was asked to write to a path where a file already exists, and `overwrite` was not set. |
@@ -50,6 +51,8 @@ Each code links to its section, which says what to do. The CLI prints the code a
 | [`XLV_E_NOT_SUPPORTED`](#xlv_e_not_supported) | `@xlvane/compat` was asked for an exceljs feature it does not implement, for example a rich-text or hyperlink value, images, tables, … |
 | [`XLV_E_USAGE`](#xlv_e_usage) | The `xlvane` command line was used incorrectly: an unknown command or option, a missing or extra argument, an option without its value, … |
 | [`XLV_E_INTERNAL`](#xlv_e_internal) | The `xlvane` command line caught an error that is not an `XlvError`. |
+| [`XLV_E_NOT_INSTALLED`](#xlv_e_not_installed) | `xlvane mcp` needs the separate package `@xlvane/mcp`, which could not be loaded. |
+| [`XLV_E_PATH_NOT_ALLOWED`](#xlv_e_path_not_allowed) | The MCP server was asked to read or write a path outside the directories it was started with (`--root`), or to write through a symbolic link. |
 
 | Warning | What it means |
 | --- | --- |
@@ -64,13 +67,14 @@ Each code links to its section, which says what to do. The CLI prints the code a
 | [`XLV_W_LIMIT_REACHED`](#xlv_w_limit_reached) | Reading stopped computing something derived from the file because the work would be far out of proportion to its data. |
 | [`XLV_W_INVALID_VALUE`](#xlv_w_invalid_value) | A value does not match its declared type and is returned in a safe form, for example a numeric cell whose text is not a number (returned … |
 | [`XLV_W_UNUSUAL_HYPERLINK`](#xlv_w_unusual_hyperlink) | A sheet has hyperlinks whose external target uses a scheme other than `http`, `https` or `mailto`, for example `file:`, `javascript:` or … |
-| [`XLV_W_DRAWING_CONTENT_NOT_READ`](#xlv_w_drawing_content_not_read) | The drawing of a sheet holds objects other than pictures: charts, shapes, connectors, group shapes, content parts or alternate content. |
+| [`XLV_W_DRAWING_CONTENT_NOT_READ`](#xlv_w_drawing_content_not_read) | The drawing of a sheet holds objects other than pictures and charts: shapes, connectors, group shapes, other graphic frames, content parts or alternate content. |
 | [`XLV_W_THREADED_COMMENTS`](#xlv_w_threaded_comments) | A sheet has threaded comments, the conversations of current Excel versions ([MS-XLSX] §2.3.7). |
 | [`XLV_W_SHEET_PART_MISSING`](#xlv_w_sheet_part_missing) | A sheet listed in the workbook has no part (the relationship or the part itself is missing). |
 | [`XLV_W_SHEET_PART_SHARED`](#xlv_w_sheet_part_shared) | Two or more sheets listed in the workbook lead to the same worksheet part, or relate to the same comments, VML or table part. |
 | [`XLV_W_PART_MISSING`](#xlv_w_part_missing) | The workbook points to a styles or shared strings part that does not exist. |
 | [`XLV_W_FORMULAS_NOT_RECALCULATED`](#xlv_w_formulas_not_recalculated) | Reported by `editCells` and `appendRows` when the workbook contains formulas. |
 | [`XLV_W_INVALID_CELL_REF`](#xlv_w_invalid_cell_ref) | A worksheet contains a row whose number is not a whole number from 1 to 1048576, a cell whose `r` reference is not a valid A1 reference … |
+| [`XLV_W_MERGED_CELL_WRITE`](#xlv_w_merged_cell_write) | `editCells` or `appendRows` wrote a value into a cell of a merged range other than its top-left cell, where it is not shown. |
 
 ## Errors
 
@@ -86,6 +90,7 @@ The settings of a note box (`box` of a note: `margins` in millimetres from 0 to
 
 ### XLV_E_INVALID_ARGUMENT
 An argument of a method of `@xlvane/compat` is not valid, in a case where exceljs 4.4.0 accepts it and loses or moves data without an error: for example `insertRow(0, …)`, a row position given as a string, a negative count in `spliceRows` or `spliceColumns`, an outline level outside 0–7 set on a row or column (exceljs writes it), `duplicateRow` of a row that does not exist, `insertRows` without an array of values, or rows or columns pushed beyond the sheet (row 1048576, column XFD). `details.method`, `details.argument` and `details.value` name the method, the argument and its value (docs/exceljs-compat.md).
+`appendRows` throws it for array rows when tables that start in different columns reach the sheet's last used row, so the column where the rows start is ambiguous (D-K04); `details.tables` names the tables and `details.row` the row. Pass object rows keyed by header text.
 **Fix:** pass a whole number in the range the hint gives (rows from 1, columns from 1), or remove rows at the end of the sheet before inserting.
 
 ### XLV_E_LIMIT_EXCEEDED
@@ -95,9 +100,21 @@ Some limits also bound work derived from a small file (1.1.1, D-H01):
 
 - `maxCells` (`details.limit` `maxCells`, `details.value` the budget): `toCSV`, `readTable`, `toJSON`, `readTableStream`, `xlvane read` and `xlvane convert` write at most `max(maxCells, 16 × cells read)` positions (rows × columns of the output), so a few cells far apart cannot make them produce a value for every position between; `@xlvane/compat`'s `xlsx.load` creates at most as many cells for merged ranges, tables and column definitions, and looks up at most 64 Mi rows (or 16 per cell read) for row settings up to the sheets' dimensions. Pass a smaller `range`, or raise `maxCells` for a trusted file.
 - `maxXmlTextLength`: also the length of an XML comment or processing instruction.
-- `maxSharedStringChars`: also the text of shared formulas, counted apart from shared strings: the length of each sharing cell's formula, as moved to that cell.
+- `maxSharedStringChars`: also the text of shared formulas, counted apart from shared strings: the length of each sharing cell's formula, as moved to that cell. From 1.2.3 (D-J01) also the header names that `readTable`, `toJSON` and `readTableStream` repeat in every row object: the sum of the key lengths times the number of rows (a long header over many rows would otherwise make JSON text far larger than the file); `readTableStream` counts one row at a time.
 
-The MCP server (`@xlvane/mcp`) returns it as a tool error for a file larger than `--max-file-size` (`details.limit` `maxFileBytes`) and for a result longer than `--max-response-chars` (`details.limit` `maxResponseChars`; `read_table` instead returns the rows that fit).
+From 1.2.3 (D-J01):
+
+- `maxCells`: `fromCSV`, `fromJSON` and `writeTable` write at most `max(maxCells, 16 × cells written)` positions (rows × columns), so one very wide row followed by many short ones cannot make them visit every position; each takes a `maxCells` option (default 5 000 000). While streaming, one `<row>` element may hold at most 16 384 cells (`details.value` 16384), the most a row can have, because its cells are held until the element ends. `@xlvane/compat` `xlsx.load` also counts the cells of defined names against its budget, and its `xlsx.read`, `csv.read` and `stream.xlsx.WorkbookReader` stop collecting a stream after `maxInputBytes` (256 MiB; `details.limit` `maxInputBytes`).
+
+From 1.3.0 (D-K04):
+
+- `maxCells`: `editCells` and `appendRows` check, before building any cell, that the cells of the workbook (with a value or only a style) plus the new cells stay within `maxCells`, so the result can be read with the same limits, and they write at most 1 000 000 cells per call unless `limits.maxCells` is given, then at most `maxCells` (`details.limit` `maxCells`, `details.value` the limit). Each cell written takes about 0.5 KB of memory while the file is rebuilt; split the edits into several calls, or pass a larger `maxCells` if there is enough memory.
+- `maxCells`: `insertRows` with `style: 'above'` or `'below'` (and `xlvane edit --insert-rows` with a style) counts the formatted cells copied into the new rows (the formatted cells of the copied row times the number of rows) plus the cells of the workbook against `maxCells`, before the rows are built. Insert fewer rows, use `style: 'none'`, or raise `maxCells`.
+- `sharedFormulaText`: `@xlvane/compat` `cell.formula` of a `{ sharedFormula }` dependent moves the master's formula once and keeps the result; the text moved per workbook (master text read plus moved text built) is limited to 512 Mi characters, the default `maxSharedStringChars` with which `readWorkbook` expands shared formulas, and for masters longer than 8192 characters (the longest formula Office writes, [MS-OI29500] §2.1.1085 a) to 32 Mi characters; also in `stream.xlsx.WorkbookReader` (per read). `location` names the dependent cell; its cached `cell.result` stays readable.
+
+From 1.3.0 (D-K03): `@xlvane/compat` `xlsx.load` limits merged cells to `max(1 048 576, cells in the file)` (`details.limit` `mergedCells`; each merged cell is written with the master's style, so a few bytes of `mergeCell` could ask for millions of styled cells), and `csv.read` stops at more than 1 048 576 rows (`details.limit` `maxRows`) 16 384 fields in a row (`details.limit` `maxColumns`, with `location.line`) or 5 000 000 fields in all (`details.limit` `maxCells`) while it parses.
+
+The MCP server (`@xlvane/mcp`) returns it as a tool error for a file larger than `--max-file-size` (`details.limit` `maxFileBytes`; `convert` to JSON stops building the text at that size), for a workbook with more cells than `--max-cells` (`details.limit` `maxCells`) and for a result longer than `--max-response-chars` (`details.limit` `maxResponseChars`; `read_table` instead returns the rows that fit). `xlvane convert` to JSON returns it when the text would be longer than a JavaScript string can be.
 
 `fromCSV` (and `xlvane convert`/`create` with CSV input) throws it for text with more fields than `maxCells` (default 5 000 000, `details.limit` `maxCells`), more than 16 384 fields on a line or more than 1 048 576 lines.
 
@@ -221,6 +238,10 @@ The workbook already has a sheet with this name. Names are compared ignoring upp
 `NewWorkbook.addImage` (or `images` of `writeWorkbookStream`) was given something that is not the bytes of a PNG, JPEG or GIF file. The format is recognised from the first bytes of the file (PNG `89 50 4E 47 0D 0A 1A 0A`, JPEG `FF D8 FF`, GIF `GIF87a` or `GIF89a`), not from a file name. `details.size` is the number of bytes given.
 **Fix:** pass the file contents as a `Uint8Array`, for example `new Uint8Array(await file.arrayBuffer())`, and convert other formats (SVG, EMF, WMF, BMP, TIFF, WebP) to PNG or JPEG first.
 
+### XLV_E_INVALID_CHART
+`addChart` (or `charts` of a sheet of `writeWorkbookStream`) was given a chart xlvane cannot write: a type other than `column`, `bar`, `line`, `pie`, `scatter` or `area`; an unknown option; no series or more than 255 (a limit of xlvane); `values` or `categories` that are not a sheet-qualified range of one row or one column such as `'Sales'!B2:B13` (no other workbook, no 3-D or whole-column references, no lists); a series `name` that is a reference to more than one cell, or literal text that is empty, longer than 255 characters or holds control characters (also line breaks); a `color` that is not six hex digits `RRGGBB`; a title or axis title that is empty, longer than 255 characters or holds control characters; a `legend` other than `right`, `bottom`, `top`, `left` or `false`; `stacked` on a pie or scatter chart; a pie chart with more than one series, a `color`, `axes` or more than 1 000 values; an axis `min` or `max` that is not a finite number, or `min` not below `max`; a `name` or `description` as refused for pictures; a `legend` or `stacked` of `null` (leave the option out for the default); a hole or a value other than an object in `series`; an invalid position (as for `addImage`). When the workbook is written (for the streaming writer: when every sheet is known), a range that names a sheet the workbook does not have also gives this error, and so does a sheet name given without quotes that reads as a cell or R1C1 reference (such as `S1!$A$1`) when the workbook has no sheet of exactly that name. `writeWorkbook` also refuses charts whose cached values would cover more than 4 000 000 cells, or more than 8 388 608 characters of cached text after escaping, in the whole workbook (limits of xlvane, `details.limit`; `writeWorkbookStream` writes no cached values). `details.option` names the option; `location.sheet` is the sheet of the chart.
+**Fix:** give each range with its sheet, for example `values: "'Sales'!B2:B13"` and `categories: "'Sales'!A2:A13"`, use one row or one column per range, quote sheet names such as `'S1'`, and add the sheet before writing the workbook. For charts over millions of cells, refer to fewer cells or use `writeWorkbookStream`.
+
 ### XLV_E_INVALID_TABLE
 `addTable` (or `tables` of a sheet of `writeWorkbookStream`) was given a table that spreadsheet applications do not accept: a name or display name that is not a valid name (letters, digits, `_`, `.` and `\`, starting with a letter or `_`; no spaces; not a cell reference such as `A1` or `R1C1`; at most 255 characters; ECMA-376 Part 1 §18.5.1.2, §18.17.2.5, [MS-OI29500] §2.1.680), a name already used by another table or a defined name of the workbook (ignoring case), no columns or two columns with the same name (ignoring case), a column name longer than 255 characters, a totals label together with a totals function, `totalsRowFormula` without `totalsRowFunction: "custom"` or the reverse, a style that is not one of the 60 built-in table styles, a range that is not as wide as the columns, leaves no data row or reaches beyond the sheet, a range that overlaps another table, a merged range or the sheet filter ([MS-OI29500] §2.1.680 h; `autoFilter: true` of the streaming writer covers every used cell, so it cannot be combined with tables), or a name equal to a built-in name such as `Print_Area`, `Print_Titles`, `Criteria` or `Database` (with or without `_xlnm.`) or starting with `_xl`. `merge` also throws it for a range that overlaps a table, and so does `defineName` (as `XLV_E_INVALID_DEFINED_NAME`) for a table's name. `details.name` is the table name.
 **Fix:** choose another name, for example `Sales_2026` instead of `Sales 2026`, give every column a unique name, or move the table so that it does not touch other tables or merged cells.
@@ -266,7 +287,7 @@ The CSV text given to `fromCSV` has a quoted field that is never closed, text ri
 `hashPassword` and `verifyPassword` throw it for a hash algorithm other than SHA-1, SHA-256, SHA-384 and SHA-512, and `hashPassword` without a `salt` throws it in a runtime that has no `crypto.getRandomValues` (pass your own random salt there; SR-50, D-C08).
 `editCells` throws it for an array or shared formula in an edit (it writes plain formulas only), and for a cell inside an array formula's range or the master of a shared formula with other cells in its range (D-E02); `details.cell` names it.
 `appendRows` throws it when a table ends with a totals row on the sheet's last used row (the new rows would fall below the totals row; the hint gives the `insertRows` call that grows the table instead), or when growing a table for the new rows would overlap another table (D-R03).
-`insertRows` and `deleteRows` (and `xlvane edit --insert-rows` / `--delete-rows`) also throw it when the sheet has content whose cell references xlvane cannot move yet: tables, charts, shapes and other drawing objects (pictures alone are moved, and deleting rows that would cut a picture is refused), pivot tables, form controls, embedded objects, custom sheet views, threaded comments, extended content such as sparklines or slicers (the conditional formats and data validations of the [MS-XLSX] extension are moved, D-F04), a chart or pivot cache elsewhere that names the sheet, a data table, an array formula the change would split, or a formula or defined name that cannot be adjusted safely (for example a 3-D reference such as `Jan:Mar!A1` that includes the sheet, D-B01). The message names the part or the cell, and `details` gives the element, relationship type or formula.
+`insertRows` and `deleteRows` (and `xlvane edit --insert-rows` / `--delete-rows`) also throw it when the sheet has content whose cell references xlvane cannot move yet: tables, charts, shapes and other drawing objects (pictures alone are moved, and deleting rows that would cut a picture is refused), pivot tables, form controls, embedded objects, custom sheet views, threaded comments, extended content such as sparklines or slicers (the conditional formats and data validations of the [MS-XLSX] extension are moved, D-F04), a chart or pivot cache elsewhere that names the sheet (also when the XML escapes the name, such as `R&amp;D`, or quotes it, such as `'O''Brien'!`; pivot cache definitions are found by part name, content type or workbook relationship, D-K04), a drawing, chart or pivot cache relationship whose target is not a part of the package (for example a chart stored under a percent-encoded name; `details.type` and `details.target`), a data table, an array formula the change would split, or a formula or defined name that cannot be adjusted safely (for example a 3-D reference such as `Jan:Mar!A1` that includes the sheet, D-B01). The message names the part or the cell, and `details` gives the element, relationship type or formula.
 **Fix:** for `@xlvane/compat`, see docs/exceljs-compat.md for the supported subset; remove the call, or keep using exceljs for files that need the feature.
 For `insertRows`/`deleteRows`, insert or delete the rows in a spreadsheet application, or remove the named content first.
 
@@ -283,7 +304,7 @@ The `xlvane` command line caught an error that is not an `XlvError`. This is a b
 **Fix:** report it with the command and, if possible, the input file (see SECURITY.md for files that must stay private).
 
 ### XLV_E_PATH_NOT_ALLOWED
-The MCP server (`@xlvane/mcp`) was asked to read or write a path outside the directories it was started with (`--root`), including paths that leave them through `..` or a symbolic link, or to write through a symbolic link. Nothing was read or written. `details.path` is the path as given and `details.roots` lists the allowed directories.
+The MCP server (`@xlvane/mcp`) was asked to read or write a path outside the directories it was started with (`--root`), including paths that leave them through `..` or a symbolic link (also a link that leaves them and comes back), or to write through a symbolic link. Nothing was read or written. `details.path` is the path as given and `details.roots` lists the allowed directories.
 **Fix:** use a path inside one of the listed directories, or restart the server with another `--root`.
 
 ## Warnings
@@ -309,8 +330,8 @@ Some merged ranges have values in cells other than the top-left one. Spreadsheet
 **Fix:** write the value into the top-left cell of the range (named in the message), or unmerge the range first.
 
 ### XLV_W_LIMIT_REACHED
-Reading stopped computing something derived from the file because the work would be far out of proportion to its data, and the file is read without it. Today: hyperlinks whose ranges cover far more positions than the sheet has cells (more than 16 visits per cell plus 1 000 000); `sheet.hyperlinks` lists every link, but `cell.hyperlink` is not set for the cells of the remaining links (D-H01).
-**Fix:** nothing, if the file comes from an unknown source: this protects the reader. Look up a cell's link in `sheet.hyperlinks` by its range.
+Reading stopped computing something derived from the file because the work would be far out of proportion to its data, and the file is read without it. Today: hyperlinks whose ranges cover far more positions than the sheet has cells (more than 16 visits per cell plus 1 000 000); `sheet.hyperlinks` lists every link, but `cell.hyperlink` is not set for the cells of the remaining links (D-H01). A chart part whose XML is over a limit that applies to one part (`maxXmlTreeElements`, `maxXmlDepth`, `maxXmlAttributes`, `maxXmlNameLength` or `maxXmlTextLength`; the message names it) is skipped: the chart is not in `sheet.charts`, and the rest of the workbook is read (D-K01). The cached and literal values of a chart are parsed under these limits but do not count against `maxXmlTreeElements`. Charts are read after the cells of every sheet, and their chart groups and series count against what the cells leave of `maxCells`; beyond it, that chart and the chart parts read after it are skipped without being parsed.
+**Fix:** nothing, if the file comes from an unknown source: this protects the reader. Look up a cell's link in `sheet.hyperlinks` by its range. To read a skipped chart of a trusted file, raise the limit the message names, for example `{ limits: { maxXmlTreeElements: 4000000 } }` or `{ limits: { maxCells: 20000000 } }`.
 
 ### XLV_W_VERY_HIDDEN_SHEET
 A sheet has the state `veryHidden`: spreadsheet applications offer no menu command to unhide it, so users usually do not know it exists.
@@ -329,7 +350,7 @@ A sheet defines the same cell more than once. The last definition is used, also
 **Fix:** nothing, if the last definition is right; otherwise re-save the file in the application that made it.
 
 ### XLV_W_INVALID_VALUE
-A value does not match its declared type and is returned in a safe form, for example a numeric cell whose text is not a number (returned as text), a boolean cell that is neither 0 nor 1, a shared-string index that does not exist (the cell is treated as empty), a date serial outside the date system (returned as a number), an unknown sheet state (treated as visible), or an invalid style index or range. The message says what was found and what was done.
+A value does not match its declared type and is returned in a safe form, for example a numeric cell whose text is not a number (returned as text), a boolean cell that is neither 0 nor 1, a shared-string index that does not exist (the cell is treated as empty), a date serial outside the date system (returned as a number), an unknown sheet state (treated as visible), or an invalid style index or range. The message says what was found and what was done. A chart is skipped with this warning when its part is not well-formed XML, is not encoded in UTF-8 or UTF-16, has no chart with a plot area, or when the chart's relationship leads to a part whose content type is not the chart content type (D-K01).
 **Fix:** read the message for the cell and the value used; re-save the file in the application that made it to repair the data.
 
 ### XLV_W_UNUSUAL_HYPERLINK
@@ -337,8 +358,8 @@ A sheet has hyperlinks whose external target uses a scheme other than `http`, `h
 **Fix:** nothing for reading; do not open such targets without checking them.
 
 ### XLV_W_DRAWING_CONTENT_NOT_READ
-The drawing of a sheet holds objects other than pictures: charts, shapes, connectors, group shapes, content parts or alternate content. xlvane reads only the pictures (`Sheet.images`); the message gives the number of other objects. `editCells` keeps the whole drawing unchanged; `insertRows` and `deleteRows` refuse such sheets.
-**Fix:** nothing, if you need only the pictures; edit sheets with charts or shapes in a spreadsheet application.
+The drawing of a sheet holds objects other than pictures and charts: shapes, connectors, group shapes, other graphic frames (for example diagrams), content parts or alternate content. xlvane reads only the pictures (`Sheet.images`) and charts (`Sheet.charts`); the message gives the number of other objects. `editCells` keeps the whole drawing unchanged; `insertRows` and `deleteRows` refuse such sheets, and also sheets with charts.
+**Fix:** nothing, if you need only the pictures and charts; edit sheets with shapes in a spreadsheet application.
 
 ### XLV_W_THREADED_COMMENTS
 A sheet has threaded comments, the conversations of current Excel versions ([MS-XLSX] §2.3.7). xlvane reads only the notes (legacy comments, ECMA-376 Part 1 §18.7). Excel stores a placeholder note next to each conversation; its author is `tc={id}` and its text may not contain the replies. `Sheet.notes` lists these placeholders as they are stored.
@@ -349,7 +370,7 @@ A sheet listed in the workbook has no part (the relationship or the part itself
 **Fix:** re-save the file in the application that made it; the sheet's cells are not in the file.
 
 ### XLV_W_SHEET_PART_SHARED
-Two or more sheets listed in the workbook lead to the same worksheet part, or relate to the same comments, VML or table part (part names compared without regard to case, as OPC requires). Spreadsheet applications write one such part per sheet; reading a shared part again for every sheet would decompress and parse it many times, outside the limit on decompressed bytes. The part is read for the first of these sheets only: for a worksheet part, the others are returned with `part: null` and no cells; for a comments, VML or table part, the others are read without its notes or table. A sheet that relates to one table part twice gets that table once. The location names the sheet and the part.
+Two or more sheets listed in the workbook lead to the same worksheet part, or relate to the same comments, VML, table or drawing part (part names compared without regard to case, as OPC requires). Spreadsheet applications write one such part per sheet; reading a shared part again for every sheet would decompress and parse it many times, outside the limit on decompressed bytes. The part is read for the first of these sheets only: for a worksheet part, the others are returned with `part: null` and no cells; for a comments, VML or table part, the others are read without its notes or table; for a drawing part, which belongs to the first worksheet whose `<drawing>` shows it, the others are read without its pictures and charts. A sheet that relates to one table part twice gets that table once. The location names the sheet and the part.
 **Fix:** re-save the file in the application that made it, and check whether the sheets returned without cells should hold data.
 
 ### XLV_W_PART_MISSING

package/docs/exceljs-compat.md

@@ -12,7 +12,7 @@ npm installs an alias `<alias>@npm:<name>` under the alias name in `node_modules
 
 - **ESM:** `import ExcelJS from 'exceljs'` works as with exceljs. `@xlvane/compat` is an ES module, so named imports (`import { Workbook } from 'exceljs'`) work too; exceljs 4.4.0 rejects them because it is a CommonJS package.
 - **CommonJS:** `const ExcelJS = require('exceljs')` needs **Node.js 22.12 or later**. The package is ESM-only and exports the `ExcelJS` object under the name `"module.exports"`, which `require()` of an ES module returns directly from Node.js 22.12 on (Node.js `doc/api/modules.md`, "Loading ECMAScript modules using `require()`"). `engines.node` is `>=22.12`.
-- **Unsupported API** throws an `XlvError` with code `XLV_E_NOT_SUPPORTED`, naming the method (docs/errors.md). Nothing is dropped silently.
+- **Unsupported API** throws an `XlvError` with code `XLV_E_NOT_SUPPORTED`, naming the method (docs/errors.md). A few options and settings are still ignored without an error; they are listed under [Known differences planned for 1.3.1](#known-differences-planned-for-131).
 
 Status: **supported** means the same behaviour as exceljs for the cases covered by the ported tests (`tests/exceljs/`). **Partly** means supported with the difference given in the notes. **Not supported** means it throws `XLV_E_NOT_SUPPORTED`. The source column points to the exceljs 4.4.0 implementation (paths relative to the package root, as installed in `bench/node_modules/exceljs`).
 
@@ -30,15 +30,15 @@ Status: **supported** means the same behaviour as exceljs for the cases covered
 | `views` (workbook windows) | supported | Every view is written as a `workbookView` with exceljs's defaults (`x` 0, `y` 0, `width` 12000, `height` 24000) and `firstSheet`, `activeTab`, `visibility` when given; read back with them (X4-28). | `lib/doc/workbook.js` L28, L164; `lib/xlsx/xform/book/workbook-view-xform.js` |
 | `calcProperties` (`fullCalcOnLoad`) | partly | `fullCalcOnLoad: true` is written as `calcPr fullCalcOnLoad="1"` and read back. exceljs always writes `calcPr calcId="171027"`; xlvane writes `calcPr` only when `fullCalcOnLoad` is set and never a `calcId` (sml.xsd CT_CalcPr makes it optional; xlvane does not calculate, so it claims no calculation engine version; the meaning of `calcId` is not checked against Part 1 prose, PROVISIONAL). `calcProperties` reads back as `{ fullCalcOnLoad: true }` or `{}`; exceljs reads `{}` in both cases. | `lib/doc/workbook.js` L24, L177; `lib/xlsx/xform/book/workbook-calc-properties-xform.js` |
 | `model` (get / set), `nextId`, `clearThemes()` | supported | `model` is a plain snapshot of the workbook that can be set on another workbook (it holds xlvane's worksheet models, not exceljs's internal xform models). `clearThemes()` does nothing: xlvane never keeps or writes a theme part. | `lib/doc/workbook.js` L43, L137, L153–215 |
-| `xlsx.load(buffer, options)` | supported | Reading goes through xlvane's limits for untrusted files. Options as in exceljs (X4-25): `base64` reads base64 text; `ignoreNodes` skips worksheet elements by name (`sheetPr`, `cols`, `sheetData`, `sheetViews`, `autoFilter`, `mergeCells`, `hyperlinks`, `dataValidations`, `conditionalFormatting`, `sheetProtection`, `pageSetup`, `headerFooter`, `rowBreaks`, `drawing`, `picture`, `tableParts`); `maxRows` and `maxCols` refuse bigger worksheets with `XLV_E_LIMIT_EXCEEDED` (exceljs throws a plain `Error`). The same options apply to `readFile` and `read`. | `lib/xlsx/xlsx.js` L257; `lib/xlsx/xform/sheet/worksheet-xform.js` L95, L372 |
+| `xlsx.load(buffer, options)` | supported | Reading goes through xlvane's limits for untrusted files. Options as in exceljs (X4-25): `base64` reads base64 text; `ignoreNodes` skips worksheet elements by name (`sheetPr`, `cols`, `sheetData`, `sheetViews`, `autoFilter`, `mergeCells`, `hyperlinks`, `dataValidations`, `conditionalFormatting`, `sheetProtection`, `pageSetup`, `headerFooter`, `rowBreaks`, `drawing`, `picture`, `tableParts`); `maxRows` and `maxCols` refuse bigger worksheets with `XLV_E_LIMIT_EXCEEDED` (exceljs throws a plain `Error`). The same options apply to `readFile` and `read`. Merged ranges may cover at most max(1 048 576, cells in the file) positions in total (one whole column fits); more throws `XLV_E_LIMIT_EXCEEDED` (`details.limit` `mergedCells`), because each merged cell carries the master's style and is written as a styled cell, so the cost of `writeBuffer` grows with the merged positions: a merged range whose cells all carry the master's style is styled in blocks of rows (K2), also when some of its cells have notes (K3), and even so 1 048 575 merged positions took about 3.5 s and 750 MB (peak resident memory) to write (measured with Node.js 22.23, K3). `ignoreNodes: ["mergeCells"]` skips them. | `lib/xlsx/xlsx.js` L257; `lib/xlsx/xform/sheet/worksheet-xform.js` L95, L372 |
 | `xlsx.readFile(path)` | supported | | `lib/xlsx/xlsx.js` L49 |
 | `xlsx.read(stream)` | supported | | `lib/xlsx/xlsx.js` L244 |
 | `xlsx.writeBuffer(options)` | supported | `useStyles: false` writes no cell or column styles, dates keeping format 14, as exceljs. `useSharedStrings: false` writes inline strings and no shared string table; `zip.compression: 'STORE'` stores every part, `zip.compressionOptions.level` (0–9) sets the deflate level; other `zip` options are ignored (X4-25). The output stays deterministic. The same options apply to `writeFile` and `write`. | `lib/xlsx/xlsx.js` L602–603, L685 |
 | `xlsx.writeFile(path)` | supported | | `lib/xlsx/xlsx.js` L666 |
 | `xlsx.write(stream)` | supported | | `lib/xlsx/xlsx.js` L643 |
 | `xlsx.createInputStream()` | supported | Throws the deprecation error, as in exceljs 4. | `lib/xlsx/xlsx.js` L238 |
-| `csv.read(stream, options)`, `csv.readFile(path, options)` | supported | Adds a worksheet, with exceljs's options (`sheetName`, `dateFormats`, `map`, `parserOptions`: `delimiter`, `quote`, `escape`, `trim`/`ltrim`/`rtrim`, `ignoreEmpty`, `comment`, `skipLines`, `skipRows`, `maxRows`, `headers`, `renameHeaders`, `encoding`) and its default conversion of fields (X4-23), on xlvane's own parser (no fast-csv). Accepts a Node.js readable stream, a Web `ReadableStream` or any (async) iterable of strings or bytes. Differences: text of white space only stays text (exceljs reads `' '` as 0), `-Infinity` stays text (it cannot be stored), a leading byte order mark is dropped (exceljs keeps it in the first field), `headers: true` skips the header line (exceljs throws `data.map is not a function`), a missing file or a malformed line throws `XLV_E_FILE_READ` / `XLV_E_CSV_MALFORMED`. `readFile` needs `node:fs` (Node.js, Bun, Deno). Dates are parsed as dayjs 1.11 customParseFormat parses them in strict mode (D-E06): letters that are no token, such as an unbracketed `T` or `dddd`, are skipped, and each token is searched in the rest of the text. An unclosed quote is reported on the line where it opens; a `quote` or `escape` longer than one character throws `XLV_E_INVALID_OPTION`. | `lib/csv/csv.js` L32–98 |
-| `csv.write(stream, options)`, `csv.writeFile(path, options)`, `csv.writeBuffer(options)` | supported | Writes one worksheet with exceljs's options (`sheetName`, `sheetId`, `dateFormat`, `dateUTC`, `map`, `includeEmptyRows`, `encoding`, `formatterOptions`: `delimiter`, `rowDelimiter`, `quote`, `escape`, `quoteColumns`, `headers`, `writeHeaders`, `includeEndRowDelimiter`, `writeBOM`) and fast-csv's quoting (X4-24); the cross-check sample gives the same text as exceljs 4.4.0. Differences: text that starts with `=`, `+`, `-`, `@`, tab, CR, LF or another control character, or with a full-width or small form of these signs, is written with a leading `'` (CSV injection, docs/facts/csv.md CSV-10, CSV-12; `formulaInjection: "off"` writes it unchanged, as exceljs); a formula result of 0 or `false` is written (exceljs writes an empty field), a date result is formatted as a date and an error result as its text; one blank line per missing row also before the first row (exceljs writes one too few there); a `sheetName` or `sheetId` that does not exist throws `XLV_E_SHEET_NOT_FOUND` (exceljs writes an empty file); header names in `formatterOptions.headers` are escaped like values. With `headers`, an array row gives one field per header (longer rows cut, shorter ones end in empty fields), as fast-csv writes it; `dateFormat: ''` uses the default format, as dayjs does (D-E06). `writeFile` writes `utf8`, `utf16le` or `latin1` and needs `node:fs`. | `lib/csv/csv.js` L109–186 |
+| `csv.read(stream, options)`, `csv.readFile(path, options)` | supported | Adds a worksheet, with exceljs's options (`sheetName`, `dateFormats`, `map`, `parserOptions`: `delimiter`, `quote`, `escape`, `trim`/`ltrim`/`rtrim`, `ignoreEmpty`, `comment`, `skipLines`, `skipRows`, `maxRows`, `headers`, `renameHeaders`, `encoding`; `latin1` is decoded as windows-1252, F10 under [Known differences planned for 1.3.1](#known-differences-planned-for-131)) and its default conversion of fields (X4-23), on xlvane's own parser (no fast-csv). Accepts a Node.js readable stream, a Web `ReadableStream` or any (async) iterable of strings or bytes. Differences: text of white space only stays text (exceljs reads `' '` as 0), `-Infinity` stays text (it cannot be stored), a leading byte order mark is dropped, as in exceljs (fast-csv 4.3.6 removes it: `@fast-csv/parse/build/src/parser/Parser.js` L12-19 `removeBOM`, called by `parse` at L20-23), `headers: true` skips the header line (exceljs throws `data.map is not a function`), a missing file or a malformed line throws `XLV_E_FILE_READ` / `XLV_E_CSV_MALFORMED`. `readFile` needs `node:fs` (Node.js, Bun, Deno). Dates are parsed as dayjs 1.11 customParseFormat parses them in strict mode (D-E06): letters that are no token, such as an unbracketed `T` or `dddd`, are skipped, and each token is searched in the rest of the text. An unclosed quote is reported on the line where it opens; a `quote` or `escape` longer than one character throws `XLV_E_INVALID_OPTION`. Rows are added as they are parsed, as fast-csv streams them, so a malformed line leaves the rows before it in the worksheet. More than 1 048 576 rows, or a row of more than 16 384 fields, throws `XLV_E_LIMIT_EXCEEDED` (`details.limit` `maxRows` or `maxColumns`) as soon as parsing reaches it (exceljs collects the rows and fails with a plain `Error` in `addRow`); rows left out by `ignoreEmpty`, the header, `skipRows` and `maxRows` do not count (K2). More than 5 000 000 fields in the rows added (`DEFAULT_READ_LIMITS.maxCells`, the core's cell limit) throw `XLV_E_LIMIT_EXCEEDED` (`details.limit` `maxCells`, with the line) before any row is added: a text of 5 000 000 characters or more is counted in a first pass (K3; exceljs has no such limit, and 10 MB of `1,1,…` took 885 MB). | `lib/csv/csv.js` L32–98 |
+| `csv.write(stream, options)`, `csv.writeFile(path, options)`, `csv.writeBuffer(options)` | supported | Writes one worksheet with exceljs's options (`sheetName`, `sheetId`, `dateFormat`, `dateUTC`, `map`, `includeEmptyRows`, `encoding`, `formatterOptions`: `delimiter`, `rowDelimiter`, `quote`, `escape`, `quoteColumns`, `headers`, `writeHeaders`, `includeEndRowDelimiter`, `writeBOM`) and fast-csv's quoting (X4-24); `transform`, `quoteHeaders` and `quoteColumns` given as an object are ignored (F9 under [Known differences planned for 1.3.1](#known-differences-planned-for-131)); the cross-check sample gives the same text as exceljs 4.4.0. Differences: text that starts with `=`, `+`, `-`, `@`, tab, CR, LF or another control character, or with a full-width or small form of these signs, is written with a leading `'` (CSV injection, docs/facts/csv.md CSV-10, CSV-12; `formulaInjection: "off"` writes it unchanged, as exceljs); a formula result of 0 or `false` is written (exceljs writes an empty field), a date result is formatted as a date and an error result as its text; one blank line per missing row also before the first row (exceljs writes one too few there); a `sheetName` or `sheetId` that does not exist throws `XLV_E_SHEET_NOT_FOUND` (exceljs writes an empty file); header names in `formatterOptions.headers` are escaped like values. With `headers`, an array row gives one field per header (longer rows cut, shorter ones end in empty fields), as fast-csv writes it; `dateFormat: ''` uses the default format, as dayjs does (D-E06). `writeFile` writes `utf8`, `utf16le` or `latin1` and needs `node:fs`; with `latin1` characters above U+00FF are written as `?` (Node.js, and so exceljs, keeps only their low byte, which can turn U+013D into `=`), and formatter options with such characters throw `XLV_E_INVALID_OPTION`. While formulas are escaped (the default), a `delimiter` holding a formula sign (`=`, `+`, `-`, `@`, their full-width or small forms) or a control character (a lone tab is allowed), a `rowDelimiter` other than `\n`, `\r\n` or `\r`, a `quote` other than `"` or `false`, an `escape` other than the quote, and with `quote: false` a field that starts with `"` throw `XLV_E_INVALID_OPTION`, because a standard CSV reader would otherwise get a field starting with a formula (docs/facts/csv.md CSV-13); `formulaInjection: "off"` writes them as exceljs does. Also while formulas are escaped (K2): text that starts with a byte order mark (U+FEFF or U+FFFE) is escaped, because applications drop a BOM at the start of a file and run what follows; with `encoding: "latin1"` or `"utf16le"` a field is also escaped when its first bytes as written are a BOM (EF BB BF, FF FE, FE FF, for example the latin1 text `=1+1`) or the UTF-8 form of a full-width or small formula sign, and with `latin1` and `writeBOM` (written as the byte FF) a first field starting with `þ`; a value from `map` that is not a number, boolean, `null` or `undefined` (a `String` object, an array, an object with `toString`) is turned into its text once and checked like text (fast-csv writes its text unchecked); a field holding a comma, `;`, tab or `|` is quoted whatever the delimiter (fast-csv quotes only the delimiter and `|`), because an application that splits on another of these characters would see a new field there, and with `quote: false` a field where one of them is followed by a formula sign (after spaces and an opening `"`) throws `XLV_E_INVALID_OPTION`. Also while formulas are escaped (K3): an empty `delimiter` throws `XLV_E_INVALID_OPTION`, and so does, with `latin1` or `utf16le`, a `delimiter` or `rowDelimiter` with characters other than ASCII, because the bytes of a field could otherwise join the next field's (or the delimiter's) into a byte order mark or a formula sign. `utf16le` output starts with the UTF-16LE byte order mark FF FE (exceljs writes it only with `writeBOM: true`). LibreOffice 24.2.7.2 reads a UTF-16LE file as 8-bit text and drops the NUL bytes, with its default import and with charset UTF-8, also after that mark (only charset 65535, UTF-16, decodes it), and starts a formula only at a field beginning with `=` (or a quote and `=`); so with `utf16le` a field whose bytes without NULs begin so (for example `㴀㄀⬀㄀`, bytes 00 3D 00 31 …, or `丽`, 3D 4E) is escaped with `'`, and a field whose bytes there hold a delimiter (`,`, `;`, tab, `|`) or line break followed by `=`, through a character above U+00FF (`ਗ=1`, 17 0A …) or after a quote byte of one (`a∀,=1`; such a quote also counts for all later fields), throws `XLV_E_INVALID_OPTION` (`details.option` `encoding`, with the cell); CJK text whose bytes hold such characters without `=` after them is written unchanged. The mark's bytes come before the first field in that reading, so its opening quote is not taken as quoting there: a quoted first field holding a delimiter or line break followed by `=` (`x,=1+1`) throws `XLV_E_INVALID_OPTION` with `utf16le`, and with `latin1` and `writeBOM` (the byte FF); with UTF-8, whose mark LibreOffice drops, it is written. | `lib/csv/csv.js` L109–186 |
 | `csv.createInputStream()` | supported | Throws the deprecation error, as in exceljs 4. | `lib/csv/csv.js` L101 |
 | `definedNames` (`add`, `addEx`, `remove`, `removeEx`, `removeAllNames`, `forEach`, `getNames`, `getNamesEx`, `getRanges`, `getMatrix`, `model`) | supported | As in exceljs, a name is a set of cells, written as rectangles with absolute references and no sheet scope; on reading, names that are not cell ranges (constants, formulas, `#REF!`) and the sheet scope (`localSheetId`) are dropped. Built-in `_xlnm.` names are not listed: print areas and titles are read into `pageSetup`, as in exceljs, and xlvane writes the autofilter name itself. Names exceljs accepts but Excel does not (for example `A1` or names starting with `_xl`) throw `XLV_E_INVALID_DEFINED_NAME` when the workbook is written. | `lib/doc/defined-names.js`; `lib/xlsx/xform/book/defined-name-xform.js`; `lib/xlsx/xform/book/workbook-xform.js` L187 |
 | `addImage(image)`, `getImage(id)` | supported | PNG, JPEG and GIF given as `buffer`, `base64` (a data URL is accepted, as in exceljs) or `filename`; the format is recognised from the bytes, `extension` is kept but not used (exceljs writes `image/jpg` for `extension: 'jpg'`). As in exceljs, a `filename` is read when the workbook is written (`xlsx.writeBuffer`/`writeFile`/`write` and the streaming `WorkbookWriter`), so a missing file fails there; outside Node.js, Bun and Deno it gives `XLV_E_NOT_SUPPORTED`. Other formats throw `XLV_E_INVALID_IMAGE`. Read back, each image part is one media entry `{ type, name, extension, buffer }`, `buffer` a `Uint8Array`. Identical images are stored once, with one relationship per drawing (exceljs writes one per use). | `lib/doc/workbook.js` L142–151; `lib/xlsx/xlsx.js` L421–442 (L426–429: `filename` read at write) |
@@ -56,7 +56,7 @@ Status: **supported** means the same behaviour as exceljs for the cases covered
 | `eachRow({ includeEmpty }, cb)` | supported | | `lib/doc/worksheet.js` L551 |
 | `getSheetValues()` | supported | Every row object, also an empty one (`[]`), as in exceljs. | `lib/doc/worksheet.js` L571–579 |
 | `rowCount`, `actualRowCount`, `columnCount` | supported | | `lib/doc/worksheet.js` L374, L378, L313 |
-| `mergeCells(range \| t, l, b, r)`, `unMergeCells` | supported | | `lib/doc/worksheet.js` L602, L656 |
+| `mergeCells(range \| t, l, b, r)`, `unMergeCells` | partly | Styles of merged cells differ, see F1 and F2 under [Known differences planned for 1.3.1](#known-differences-planned-for-131). | `lib/doc/worksheet.js` L602, L656 |
 | `mergeCellsWithoutStyle(...)`, `findRows(start, length)`, `lastColumn`, `fillFormula(range, formula, results, shareType)`, `model` (get / set), `destroy()` | supported | `fillFormula` writes the formula into the top-left cell and `{ sharedFormula }` (or the same array formula) into the others, with results from a function, a flat array or a 2-D array, as in exceljs (X4-29). `findRows` returns `_rows.slice(start - 1, start - 1 + length)` as exceljs does (D-E06). `model` is xlvane's own plain snapshot (see `workbook.model`). | `lib/doc/worksheet.js` L181, L309, L370, L607, L678–721, L842–903 |
 | `views` | partly | The first view is written: frozen panes, split panes (`xSplit`/`ySplit` in 1/20 point), `zoomScale` (10–400), `zoomScaleNormal`, `showGridLines`, `showRowColHeaders`, `showRuler`, `rightToLeft`, `style` (`pageBreakPreview`, `pageLayout`), `activeCell`, and `topLeftCell` of a normal view (X4-28). Differences: further views are not written, because xlvane's core writes one `sheetView` per worksheet; `workbookViewId` is always 0; frozen panes always get the cell right of and below the panes as `topLeftCell` (exceljs writes a frozen view's own `topLeftCell` when given, sheet-view-xform.js L50-53); a split view's `topLeftCell` is written as `pane@topLeftCell` and read back, as in exceljs (L72-85, L118-124; D-F02), and its `activeCell` is written and read back as the selection of the active pane; `activePane` is the pane the split implies; `tabSelected` is written for the first visible worksheet, whatever the view says. Every worksheet reads back with one view shaped as exceljs reads it. | `lib/doc/worksheet.js` L114; `lib/xlsx/xform/sheet/sheet-view-xform.js`; `index.d.ts` L33–149 |
 | `autoFilter` (range string) | supported | | `lib/doc/worksheet.js` L116 |
@@ -82,7 +82,7 @@ Status: **supported** means the same behaviour as exceljs for the cases covered
 | `eachCell({ includeEmpty }, cb)` | supported | As in exceljs, cells of a merged range give the master cell's value. | `lib/doc/row.js` L130 |
 | `height`, `hidden` | supported | | `lib/doc/row.js` L310 |
 | `outlineLevel`, `collapsed`, `protection`, `getCellEx(address)` | supported | `outlineLevel` (0–7, [MS-OI29500] §2.1.644) is written and read back; a level outside 0–7 throws `XLV_E_INVALID_ARGUMENT` when it is set (exceljs writes it; D-E06); `collapsed` is derived from the level and `properties.outlineLevelRow`, as in exceljs (X4-28). | `lib/doc/row.js` L45, L286–330 |
-| `font`, `fill`, `border`, `alignment`, `numFmt` setters | supported | Apply to the row's cells. | `lib/doc/row.js` L274, L306 |
+| `font`, `fill`, `border`, `alignment`, `numFmt` setters | partly | Apply to the row's cells. The row's own style is not written or read (F3 under [Known differences planned for 1.3.1](#known-differences-planned-for-131)). | `lib/doc/row.js` L274, L306 |
 | `commit()` | supported | Meaningful for `WorkbookWriter`; does nothing in a normal workbook, as in exceljs. | `lib/doc/row.js` L29 |
 | `cellCount`, `actualCellCount` | supported | | `lib/doc/row.js` L216, L220 |
 | `splice(start, count, ...inserts)` | partly | Cells move with their values, styles and notes, as in exceljs. A row that crosses a merged range at or right of `start` throws `XLV_E_NOT_SUPPORTED` (the range cannot follow the cells of one row; exceljs gives wrong values). Removed cells at the end are removed, not set to `null`. Formulas are not rewritten, as in exceljs. | `lib/doc/row.js` L77–127 |
@@ -96,7 +96,7 @@ Status: **supported** means the same behaviour as exceljs for the cases covered
 | `outlineLevel`, `collapsed`, `protection`, `isDefault`, `toString()`, `equivalentTo(other)` | supported | `outlineLevel` (0–7) is written and read back, and a level outside 0–7 throws `XLV_E_INVALID_ARGUMENT` when it is set (D-E06); `collapsed` is derived from the level and `properties.outlineLevelCol`, as in exceljs (X4-28). | `lib/doc/column.js` L116–147, L238 |
 | `letter`, `number` | supported | | `lib/doc/column.js` L23, L31 |
 | `values` | supported | | `lib/doc/column.js` L179 |
-| `eachCell({ includeEmpty }, cb)` | supported | | `lib/doc/column.js` L168 |
+| `eachCell({ includeEmpty }, cb)` | partly | Without `includeEmpty`, only cells with values are visited (F12 under [Known differences planned for 1.3.1](#known-differences-planned-for-131)). | `lib/doc/column.js` L168 |
 | `font`, `fill`, `border`, `alignment`, `numFmt` setters, `style` | supported | Applied to the column's existing cells, inherited by cells added later (the row style wins), and written as the column's default style (`col@style`). As in exceljs, a styled column without a width is written with width 9, and a column with width 9 and nothing else is not written. The streaming writer writes the column style only with `useStyles: true`. | `lib/doc/column.js` L147, L206, L265 |
 
 ## Cell values
@@ -104,9 +104,9 @@ Status: **supported** means the same behaviour as exceljs for the cases covered
 | Value | Status | Notes | Source in exceljs |
 |---|---|---|---|
 | `null`, number, string, boolean | supported | | `lib/doc/cell.js` L206, L211 |
-| `Date` | supported | Without `numFmt`, a date (also a formula result that is a date) is written with built-in format 14, as exceljs does, also by the streaming writer without `useStyles`; applications show it in the reader's date order, and reading gives `numFmt` `"mm-dd-yy"`. | `lib/doc/cell.js` L538; `lib/xlsx/xform/style/styles-xform.js` L253–266, L498–515 |
+| `Date` | partly | Without `numFmt`, a date (also a formula result that is a date) is written with built-in format 14, as exceljs does, also by the streaming writer without `useStyles`; applications show it in the reader's date order, and reading gives `numFmt` `"mm-dd-yy"`. Time-only values, dates before 1900-03-01, upper-case date formats and dates outside 1900-9999 differ, see F6, F7 and F8 under [Known differences planned for 1.3.1](#known-differences-planned-for-131). | `lib/doc/cell.js` L538; `lib/xlsx/xform/style/styles-xform.js` L253–266, L498–515 |
 | `{ formula, result }` | supported | xlvane does not calculate; `result` is stored as given. | `lib/doc/cell.js` L734 |
-| `{ sharedFormula, result }`, `{ formula, shareType, ref, result }`, `formulaType` | supported | Shared formulas are written as `t="shared"` groups: the master's `ref` is its own `ref` or grows to its last dependent, as in exceljs; array formulas (`shareType: 'array'`) are written with their range (X4-29). Read back as exceljs reads them: the master `{ formula, shareType: 'shared', ref, result }`, a dependent `{ sharedFormula, result }` whose `cell.formula` is the translated formula. `formulaType` is 0 (none), 1 (master) or 2 (shared). The streaming `WorkbookWriter` writes a dependent of a master with `ref` as a shared formula, and any other `{ sharedFormula }` cell as its translated formula, which needs the master's row to be uncommitted. Differences: xlvane refuses (`XLV_E_INVALID_VALUE`) what exceljs writes against the schema rules of Part 1 §18.3.1.40: overlapping shared ranges, a dependent outside its master's range, and a formula in another cell of an array formula's range. A splice (`spliceRows`, `spliceColumns`, `insertRow(s)`, `duplicateRow` with insertion) turns every shared group of the workbook into plain formulas, each adjusted for the splice, because moving the master's text to each dependent would give wrong references; array formulas keep their group and their range moves (D-E06). A `$` in a shared master's `ref` (exceljs `fillFormula` over an absolute range) is read as the same range without `$`. | `lib/doc/cell.js` L744, L811; `lib/xlsx/xform/sheet/cell-xform.js` L94–160, L460–470 |
+| `{ sharedFormula, result }`, `{ formula, shareType, ref, result }`, `formulaType` | supported | Shared formulas are written as `t="shared"` groups: the master's `ref` is its own `ref` or grows to its last dependent, as in exceljs; array formulas (`shareType: 'array'`) are written with their range (X4-29). Read back as exceljs reads them: the master `{ formula, shareType: 'shared', ref, result }`, a dependent `{ sharedFormula, result }` whose `cell.formula` is the translated formula, moved from the master when `cell.formula` is read (loading does not build the dependents' texts, which a huge master shared with many cells made exhaust memory; K2). The moved text is kept on the dependent cell until its value, its master's formula or the position of either changes (exceljs keeps it per value, `lib/doc/cell.js` L861-869, and does not see a later change of the master's formula). The shared-formula text moved in one workbook (each master text read plus each moved text built) may not pass 32 Mi characters plus 256 for each move, so formulas of up to 128 characters never reach the limit; a move past it throws `XLV_E_LIMIT_EXCEEDED` (`details.limit` `sharedFormulaText`, with the dependent's location) from `cell.formula`, because each move costs time in proportion to the master's length: a 4 KB file sharing a 1 000 000-character master with 250 cells took about 47 s to read every dependent's formula once (K4 S1). exceljs has no such limit. A dependent the master's formula cannot be moved to (outside the master's range, or a formula xlvane cannot move safely) is read as its cached value (exceljs reads `{ sharedFormula, result }`). `formulaType` is 0 (none), 1 (master) or 2 (shared). The streaming `WorkbookWriter` writes a dependent of a master with `ref` as a shared formula, and any other `{ sharedFormula }` cell as its translated formula, which needs the master's row to be uncommitted, or a dependent from the streaming `WorkbookReader`: it is `{ sharedFormula, result }` as above, with its translated formula as a non-enumerable `formula` built when it is read (not in `Object.keys` or JSON), so copying its rows with `addRow(row.values).commit()` writes each dependent as its formula (K3). Differences: xlvane refuses (`XLV_E_INVALID_VALUE`) what exceljs writes against the schema rules of Part 1 §18.3.1.40: overlapping shared ranges, a dependent outside its master's range, and a formula in another cell of an array formula's range. A splice (`spliceRows`, `spliceColumns`, `insertRow(s)`, `duplicateRow` with insertion) turns every shared group of the workbook into plain formulas, each adjusted for the splice, because moving the master's text to each dependent would give wrong references; array formulas keep their group and their range moves (D-E06). A `$` in a shared master's `ref` (exceljs `fillFormula` over an absolute range) is read as the same range without `$`. | `lib/doc/cell.js` L744, L811; `lib/xlsx/xform/sheet/cell-xform.js` L94–160, L460–470 |
 | A style on a cell without a value | supported | Written and read back: xlvane's reader keeps cells that hold only a style (D-E05). | `lib/xlsx/xform/sheet/cell-xform.js` |
 | `{ error: '#N/A' }` | supported | | `lib/doc/cell.js` L970 |
 | Other objects and arrays (JSON values) | supported | Kept on the cell with type `String` and written as their JSON text, as exceljs; read back as that text. | `lib/doc/cell.js` L1014–1054 |
@@ -129,7 +129,7 @@ Status: **supported** means the same behaviour as exceljs for the cases covered
 | `border` (`top`, `left`, `bottom`, `right`, `diagonal`) | supported | `diagonal` with `up`, `down`, `style` and `color`, as in exceljs (X4-27). | `lib/doc/cell.js` L75; `lib/xlsx/xform/style/border-xform.js`; `index.d.ts` L258 |
 | `alignment` | supported | `horizontal`, `vertical`, `wrapText`, `shrinkToFit`, `indent`, `readingOrder` (`'ltr'`/`'rtl'`) and `textRotation` (`'vertical'` is 255, −90…−1 are 91…180, as exceljs writes them; X4-27). `textRotation` and `indent` follow exceljs's `validInt` (D-E06): numbers are truncated and numeric strings accepted; a rotation outside −90…90 (other than `'vertical'`) is dropped and an indent below 0 becomes 0, as in exceljs. An indent above 255 in a loaded file (more than Office accepts) is left out, so the workbook can be written again. | `lib/doc/cell.js` L67; `lib/xlsx/xform/style/alignment-xform.js`; `index.d.ts` L280 |
 | `protection` (`locked`, `hidden`) of cells, rows, columns and styles | supported | Written when it differs from the defaults (`locked: true`, `hidden: false`), as in exceljs (X4-27). | `lib/xlsx/xform/style/protection-xform.js` |
-| Colours `{ argb }`, `{ theme, tint }`, `{ indexed }` | supported | | `index.d.ts` |
+| Colours `{ argb }`, `{ theme, tint }`, `{ indexed }` | partly | A six-digit `rgb` read from a file is dropped (F5 under [Known differences planned for 1.3.1](#known-differences-planned-for-131)). | `index.d.ts` |
 
 ## Streaming
 
@@ -141,7 +141,7 @@ Status: **supported** means the same behaviour as exceljs for the cases covered
 | Sheet layout (`columns`, `views`, `properties.tabColor`, `autoFilter`, merges, data validations, conditional formatting, protection, `pageSetup`, `headerFooter`, row breaks) of a streamed worksheet | partly | Must be set before the worksheet's first row is committed. A change made later throws `XLV_E_NOT_SUPPORTED` (at `mergeCells()` or at `worksheet.commit()`), because xlvane writes the layout before the rows. exceljs writes `autoFilter`, merges, validations, conditional formatting and print settings when the worksheet is committed. | `lib/stream/xlsx/worksheet-writer.js` |
 | `WorkbookWriter` options `created`, `modified`, `creator`, `lastModifiedBy`, `lastPrinted`; `definedNames` | partly | Written with exceljs's defaults (`creator` and `lastModifiedBy` "ExcelJS"). Names and these properties are written when the first row is committed (writing starts then); a change made later throws `XLV_E_NOT_SUPPORTED` at `writer.commit()`. exceljs writes them at the end. | `lib/stream/xlsx/workbook-writer.js` L22–40, L64, L264 |
 | `stream.xlsx.WorkbookReader` with `for await` over worksheets and rows | supported | Built on `openWorkbookStream`. Rich text cells come back as `{ richText }`. | `lib/stream/xlsx/workbook-reader.js` L19, L71; `lib/stream/xlsx/worksheet-reader.js` L105 |
-| `WorkbookReader` options and events (`read()`, `parse()`, `on('worksheet' \| 'entry' \| 'end' \| 'finished' \| 'error')`; worksheet `read()`, `on('row' \| 'finished')`) | partly | Options are checked against exceljs's `WorkbookReader.Options` (X4-26). `styles: 'cache'` gives cells their styles; `entries: 'emit'` sends `entry` events for the workbook and each worksheet (not for shared strings, styles or hyperlinks); `hyperlinks: 'cache'` is accepted and, as in exceljs for files in schema order, attaches nothing. `sharedStrings: 'emit' \| 'ignore'` and `hyperlinks: 'emit'` throw `XLV_E_NOT_SUPPORTED`. Without `styles: 'cache'` a date is still read as a `Date` (exceljs gives the serial number, because it does not know the format). The worksheet reader has `name`, `id`, `state`, `workbook`, `dimensions`, `columns`, `getColumn`, the column-key methods and `destroy` (throws). The events come from a small emitter in the package, not from `node:events`. | `lib/stream/xlsx/workbook-reader.js` L20–66, L151, L326; `lib/stream/xlsx/worksheet-reader.js` L13–115 |
+| `WorkbookReader` options and events (`read()`, `parse()`, `on('worksheet' \| 'entry' \| 'end' \| 'finished' \| 'error')`; worksheet `read()`, `on('row' \| 'finished')`) | partly | Options are checked against exceljs's `WorkbookReader.Options` (X4-26). `styles: 'cache'` gives cells their styles; `entries: 'emit'` sends `entry` events for the workbook and each worksheet (not for shared strings, styles or hyperlinks); `hyperlinks: 'cache'` is accepted and, as in exceljs for files in schema order, attaches nothing. `sharedStrings: 'emit' \| 'ignore'` and `hyperlinks: 'emit'` throw `XLV_E_NOT_SUPPORTED`. Without `styles: 'cache'` a date is still read as a `Date` (exceljs gives the serial number, because it does not know the format). A shared formula's master is read as `{ formula, result }`, as exceljs's reader gives it, and each dependent as `{ sharedFormula, result }` whose `cell.formula` is the master's formula moved to it (exceljs's reader gives `{ formula: '', result }`, which exceljs takes as a JSON value; K2), built once per cell and counted against the same limit of moved shared-formula text as in `xlsx.load` (see `{ sharedFormula, result }`), per read of the workbook (K4 S1); a dependent the formula cannot be moved to gives its cached value. The worksheet reader has `name`, `id`, `state`, `workbook`, `dimensions`, `columns`, `getColumn`, the column-key methods and `destroy` (throws). The events come from a small emitter in the package, not from `node:events`. | `lib/stream/xlsx/workbook-reader.js` L20–66, L151, L326; `lib/stream/xlsx/worksheet-reader.js` L13–115 |
 
 ## Other
 
@@ -168,6 +168,7 @@ A workbook loaded with `xlsx.load()` is written again by `xlsx.writeBuffer()` (`
 - Row heights above 409.5 points are read as 409.5; 409.5 itself, which Excel writes, is accepted.
 - A table whose style is a custom style of the file is written without a style name, because xlvane does not write the file's custom table styles; a style name set in code must still be one of the built-in names.
 - Totals-row formulas keep their cached results.
+- Charts are not kept. exceljs 4.4.0 has no chart API (`lib/` mentions charts only in a comment of `lib/xlsx/xform/book/workbook-xform.js` L174–178; docs/facts/charts.md CH-30) and drops the charts of a file it reads and writes again; `@xlvane/compat` does the same and offers no chart API. xlvane itself writes charts with `NewSheet.addChart` and reads them as `Sheet.charts`.
 - `activeTab` and `firstSheet` count chart sheets in the file; chart sheets are not loaded, so the indexes are mapped to the worksheet they fall on, or the worksheet before a chart sheet.
 - Row height, visibility and outline level are also read for rows without cells, up to the sheet's `dimension` or its last cell; rows after both are not looked at.
 
@@ -179,10 +180,29 @@ A workbook loaded with `xlsx.load()` is written again by `xlsx.writeBuffer()` (`
 - `row.destroy()` and `cell.destroy()` do nothing; the row or cell stays usable (exceljs deletes its internals).
 - Errors found while writing name the worksheet and, for cell values and styles, the cell (`error.location`).
 - `worksheet.tables` and `dataValidations.model` have no prototype: keys such as `constructor` or `__proto__` are plain entries.
-- CSV writing: a field whose first character after any NUL characters is a formula character is escaped (NULs are removed when writing); with `formatterOptions.quote: false`, a field with CR, LF or the delimiter throws `XLV_E_INVALID_OPTION` (fast-csv writes it and the CSV then has other fields or rows). CSV reading: fields such as `constructor` or `__proto__` stay text.
+- CSV writing: a field whose first character after any NUL characters is a formula character is escaped (NULs are removed when writing); options that would get around the escape are refused (CSV-13); `latin1` output writes characters above U+00FF as `?`; a leading byte order mark, a BOM or UTF-8 formula sign in the bytes of `latin1` or `utf16le` output, values from `map` that are not strings, and a comma, `;`, tab or `|` inside a field are handled as described for `csv.write` (K2); `csv.read` stops collecting input after 256 MiB (`XLV_E_LIMIT_EXCEEDED`, `maxInputBytes`) and parsing at 1 048 576 rows or 16 384 fields in a row; with `formatterOptions.quote: false`, a field with CR, LF or the delimiter throws `XLV_E_INVALID_OPTION` (fast-csv writes it and the CSV then has other fields or rows). CSV reading: fields such as `constructor` or `__proto__` stay text. `xlsx.load` limits merged cells to max(1 048 576, cells in the file), and does not build the text of shared-formula dependents (K2). After K3: `csv.read` adds at most 5 000 000 fields; with formulas escaped, an empty delimiter, non-ASCII delimiters with `latin1` or `utf16le`, and `utf16le` fields that LibreOffice's 8-bit reading would split before `=` are refused, and `utf16le` output starts with its byte order mark (see `csv.write`); dependents from the streaming reader carry their formula for the streaming writer; notes in a merged range keep the block writing of its style.
 
 ## Known differences found by the cross-check
 
 `tests/exceljs/cross-check.test.ts` runs `tests/exceljs/sample-project` against exceljs 4.4.0 and stores its output in `expected-exceljs-4.4.0.json`. `tests/exceljs/alias.test.ts` requires @xlvane/compat to produce the same output, except for the entries of `KNOWN_DIFFERENCES` in `tests/exceljs/project-helper.ts`, which are listed here:
 
 - None so far for what the sample reads back. The sample covers document properties (including `company` and `manager`), rich text, a column style, defined names (including `cell.name`), the built-in date format, a tab colour, a zoomed frozen view external, `mailto:` and `#` links (without tooltips, which exceljs does not read back), gradient fills, a diagonal border, alignment (`textRotation`, `shrinkToFit`, `readingOrder`) and protection, a shared formula from `fillFormula`, outline levels of rows and columns, workbook views, and `insertRow` with style `'i'`, `spliceRows`, `duplicateRow`, `spliceColumns`, `insertRows` and `row.splice` on plain values (no formulas, merges, notes or names, which exceljs does not move); CSV written with the default and with custom options and read back (no formula-like text, no formula result 0, no gap before the first row); `cross-check.test.ts` and `alias.test.ts` also run the documented deep imports (`deep-imports.cjs`); `alias.test.ts` also checks that LibreOffice shows the dates as exceljs's files do (`1/31/2024`).
+
+## Known differences planned for 1.3.1
+
+Found by a review of 1.3.0 and checked by running exceljs 4.4.0 and `@xlvane/compat` on the same input (Node.js 22.23). They are not fixed yet.
+
+- **F1** A style set on the top-left cell after `mergeCells` (for example `ws.getCell('A1').fill = ...`) does not reach the other cells of the range in memory: `B2.fill` stays `undefined`. exceljs gives every merged cell the master's style object (`lib/doc/cell.js` L168-174, `this.style = master.style`), so a later change of the master's `fill` or `font` shows on all of them. xlvane copies the master's style when merging (`packages/compat/src/model.ts`, `mergeCells`). The written file is the same: the writer gives merged cells the master's style.
+- **F2** `xlsx.load` gives every cell of a merged range the top-left cell's style, replacing the style each cell has in the file (for example a right border on the last cell). exceljs merges loaded ranges without styles (`lib/doc/worksheet.js` L895-901 `_parseMergeCells` calls `mergeCellsWithoutStyle`), so each cell keeps its own. xlvane calls `mergeCells` there (`packages/compat/src/workbook.ts`, `_fill`).
+- **F3** Row styles (`row.fill`, `row.font` and the other row style setters) apply to the row's existing cells only. exceljs also writes the row's own style as `<row s="..." customFormat="1">` (`lib/xlsx/xform/sheet/row-xform.js` L21-23, L44-46) and reads it back as `row.style` (L81, L130), from which cells created later in the row take their style. xlvane neither writes nor reads it.
+- **F4** A cell whose style uses the workbook's default font (font 0, for example Arial 10, with a number format of its own) reads with `font` `undefined`, and after `xlsx.load` and `writeBuffer` it shows Calibri 11. exceljs reads font 0 into `cell.font` (`lib/xlsx/xform/style/styles-xform.js` L318-327, `addStyle` also for id 0) and writes it back as a font of its own. Cells without a style (`s="0"`) are written with Calibri 11 by both.
+- **F5** A six-digit `rgb` colour in a file's styles (`<color rgb="AA0000"/>`) is dropped on reading: the font reads as `{}`. exceljs reads it as `{ argb: 'AA0000' }` (`lib/xlsx/xform/style/color-xform.js` L39-40) and writes it back unchanged (L19-20). When a six-digit `argb` is set in code, xlvane writes `FF` followed by the six digits; exceljs writes the six digits.
+- **F6** Dates near the start of the 1900 date system:
+  - A time-only date such as `new Date(Date.UTC(1899, 11, 30, 13, 20))` throws `XLV_E_INVALID_VALUE` when written ("outside the 1900 date system"); exceljs writes serial 0.5555... (`lib/utils/utils.js` L55-57 `dateToExcel`).
+  - A time-only serial (below 1) with a date format reads as 1899-12-31 plus the time; exceljs gives 1899-12-30 plus the time (`lib/utils/utils.js` L58-61 `excelToDate`, which counts from 1899-12-30).
+  - Dates from 1900-01-01 to 1900-02-28 differ by one day. xlvane writes and reads them with serial 1 = 1900-01-01 (ECMA-376 Part 4 §15.3.4, docs/facts/ecma-376.md E-15); exceljs writes 1900-01-15 as serial 16 and reads serial 15 as 1900-01-14 (same functions), so here exceljs is the one that is off. From 1900-03-01 on both agree.
+- **F7** A number whose format uses upper-case date letters (`DD.MM.YYYY`, `YYYY-MM-DD`, `HH:MM`) reads as a number. exceljs reads it as a `Date`: its test is `/[ymdhMsb]+/` after removing quoted and bracketed parts (`lib/utils/utils.js` L140-151 `isDateFmt`), which the upper-case `M` matches.
+- **F8** Values exceljs writes without checks (`lib/xlsx/xform/sheet/cell-xform.js` L199-250, `render`) that xlvane refuses with `XLV_E_INVALID_VALUE` when the workbook is written: `NaN` and `Infinity` (exceljs writes `<v>NaN</v>`, `<v>Infinity</v>`), an invalid `Date` (exceljs writes `<v>NaN</v>`), dates before 1900-01-01 or after 9999-12-31 (exceljs writes the serial, for example -18260 for 1850-01-01), text of more than 32 767 characters, text with an unpaired UTF-16 surrogate, and formulas of more than 8 192 characters.
+- **F9** `csv.write` and `csv.writeBuffer` ignore, without an error, three fast-csv 4.3 formatter options that exceljs passes on (`lib/csv/csv.js` L118 `fastCsv.format(options.formatterOptions)`): `transform` (`@fast-csv/format/build/src/formatter/RowFormatter.js` L22-23), `quoteHeaders`, and `quoteColumns` given as an object of header names (`@fast-csv/format/build/src/formatter/FieldFormatter.js` L24-35 `shouldQuote`). `quoteColumns` as `true` or as an array works.
+- **F10** `csv.read` with `parserOptions.encoding: 'latin1'` decodes with the WHATWG `TextDecoder('latin1')`, which is windows-1252: the bytes 80 and 93 become U+20AC and U+201C. exceljs, through fast-csv's Node.js `StringDecoder` (`@fast-csv/parse/build/src/CsvParserStream.js` L20), gives U+0080 and U+0093.
+- **F12** `column.eachCell(cb)` without `includeEmpty` visits only the column's cells that have values. exceljs visits the column's cell in every row that has a value in any column (`lib/doc/column.js` L168-177, through `worksheet.eachRow`), so an empty cell next to a filled one is visited too (and created).

package/docs/inspect-json.md

@@ -57,6 +57,8 @@
 | `noteCount` | number | notes (comments) of the sheet (`Sheet.notes`) |
 | `imageCount` | number | pictures of the sheet's drawing (`Sheet.images`); charts and shapes are not counted |
 | `images` | array | up to 10 pictures: `cell` of the top-left corner (`null` for an absolute position) and `format` (`png`, `jpeg`, `gif`, or `null` for other formats) |
+| `chartCount` | number | charts of the sheet's drawing (`Sheet.charts`); charts on chart sheets are not counted |
+| `charts` | array | up to 10 charts: `cell` of the top-left corner (`null` for an absolute position), `types` (the first 10 chart groups in order: `column`, `bar`, `line`, `pie`, `scatter`, `area`, or `other:` and the element name, e.g. `other:radarChart`), `typesTruncated` (`true` when the chart has more than 10 chart groups), `title` (`{ "text" }`, `{ "ref" }` with the reference as stored, either cut to 100 characters followed by `…`, or `null`) and `seriesCount` |
 | `notes` | string[] | up to ten cells that have a note |
 | `protected` | boolean | the sheet is protected (`Sheet.protection.sheet`) |
 | `printArea` | string[] \| null | the print area (`Sheet.printArea`), at most ten ranges |
@@ -132,6 +134,8 @@ Values in `samples` are JSON-safe: numbers, booleans, strings (cut to 100 charac
       "noteCount": 0,
       "imageCount": 0,
       "images": [],
+      "chartCount": 0,
+      "charts": [],
       "notes": [],
       "protected": false,
       "printArea": null,

package/docs/migrate-from-exceljs.md

@@ -0,0 +1,131 @@
+# Migrating from ExcelJS
+
+xlvane is not affiliated with the ExcelJS project; its name is used only to identify the package.
+
+`@xlvane/compat` offers the commonly used part of the exceljs 4.4.0 API on top of xlvane. It is installed under the name `exceljs` with an npm alias, so code that imports `exceljs` keeps its imports:
+
+```json
+"dependencies": {
+  "exceljs": "npm:@xlvane/compat@^1"
+}
+```
+
+npm installs an alias `<alias>@npm:<name>` under the alias name in `node_modules` (npm/cli `docs/lib/content/using-npm/package-spec.md`, "Aliases"; docs/exceljs-compat.md), so `import ExcelJS from 'exceljs'` and `require('exceljs')` load `@xlvane/compat`. What is supported, partly supported and not supported is listed method by method in [docs/exceljs-compat.md](https://github.com/DevXord/xlvane/blob/main/docs/exceljs-compat.md) (also in `node_modules/xlvane/docs/exceljs-compat.md` after installing xlvane).
+
+This guide uses the `xlvane migrate` command of the `xlvane` package. The `xlvane` commands, the report shown below and the TypeScript examples are checked by the tests in `tests/docs/`; the npm commands were run with npm 10.9.9 on 2026-11-03.
+
+## Before you start
+
+- **Node.js.** `@xlvane/compat` is an ES module and declares `engines.node` `>=22.12`. `require('exceljs')` of an ES module works without a flag from Node.js 22.12 (docs/exceljs-compat.md); `import` works too, and so do named imports such as `import { Workbook } from 'exceljs'`.
+- **Version control.** Commit `package.json` and the lockfile first, so the change can be reviewed and undone.
+
+## 1. See what would change
+
+In the directory that holds the project's `package.json`:
+
+```sh
+npx xlvane migrate
+```
+
+`xlvane migrate` does the following, and nothing else:
+
+1. It reads `package.json` of the project directory (the current directory, or the directory given as the first argument). A `package.json` that is a symbolic link is refused.
+2. It looks for an `"exceljs"` entry in `dependencies`, `devDependencies`, `optionalDependencies` and `peerDependencies`, and shows how each would change to `"npm:@xlvane/compat@^1"`. Other sections, such as `overrides`, are not changed.
+3. It prints the Node.js requirement of `require('exceljs')` next to the project's own `engines.node`.
+4. It scans the source files of the project (`.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`, up to 2 MiB each and 10 000 files) for exceljs API that `@xlvane/compat` does not support: `ModelContainer` and deep imports of `exceljs/lib/...`. Only files that contain the text `exceljs` are checked; `node_modules`, folders whose names start with a dot, and symbolic links are skipped. The matching is textual, so a finding is a place to look at, not proof.
+5. It writes nothing unless `--force` is given.
+
+For a project whose `package.json` has `"exceljs": "^4.4.0"` in `dependencies`, with a file `src/report.js` that imports `exceljs` and a file `src/legacy.cjs` that requires `exceljs/lib/xlsx/xform/base-xform`, the report is:
+
+```text
+Change in package.json:
+  dependencies: - "exceljs": "^4.4.0"
+                + "exceljs": "npm:@xlvane/compat@^1"
+Node.js: require('exceljs') of @xlvane/compat needs Node.js 22.12 or later (package.json engines.node: not set).
+
+Scanned 2 source files for exceljs API that @xlvane/compat does not fully support:
+  not supported src/legacy.cjs:1:27  deep import (exceljs/lib/...)
+  Details: docs/exceljs-compat.md. Unsupported calls throw XLV_E_NOT_SUPPORTED at run time.
+
+Nothing was written. Run "xlvane migrate --force" to change package.json.
+```
+
+The same report as JSON (schema in [docs/cli-json.md](https://github.com/DevXord/xlvane/blob/main/docs/cli-json.md)):
+
+```sh
+npx xlvane migrate --json
+```
+
+## 2. Change package.json and install
+
+```sh
+npx xlvane migrate --force --dry-run   # show the change without writing it
+npx xlvane migrate --force             # change package.json
+npm install                            # install @xlvane/compat under the name exceljs
+```
+
+`--force` replaces only the value of each `"exceljs"` entry; the rest of `package.json` keeps its formatting and key order. Instead of `xlvane migrate`, the alias can also be installed directly:
+
+```sh
+npm install exceljs@npm:@xlvane/compat@^1
+```
+
+npm then saves the version it installed as the range (with npm 10.9.9 and `@xlvane/compat` 1.2.2: `"exceljs": "npm:@xlvane/compat@^1.2.2"`).
+
+The code stays as it was. For example, this exceljs code runs unchanged on `@xlvane/compat`:
+
+```ts
+import ExcelJS from 'exceljs';
+
+const workbook = new ExcelJS.Workbook();
+const sheet = workbook.addWorksheet('Sales');
+sheet.columns = [
+  { header: 'Region', key: 'region', width: 15 },
+  { header: 'Revenue', key: 'revenue', width: 12 },
+];
+sheet.addRow({ region: 'North', revenue: 1200 });
+await workbook.xlsx.writeFile('sales.xlsx');
+
+const check = new ExcelJS.Workbook();
+await check.xlsx.readFile('sales.xlsx');
+console.log(check.getWorksheet('Sales')?.getCell('B2').value); // 1200
+```
+
+In CommonJS, `const ExcelJS = require('exceljs');` gives the same object.
+
+## 3. Check the result
+
+- **Run the project's tests.** Unsupported API throws an `XlvError` whose `code` is `XLV_E_NOT_SUPPORTED` and whose message names the method; nothing is dropped silently.
+- **Look at each finding of `xlvane migrate`.** Deep imports of `exceljs/lib/...` do not resolve (`exceljs/dist/es5` and the `exceljs/dist/exceljs*.js` files do); `ModelContainer` throws `XLV_E_NOT_SUPPORTED` when it is constructed.
+- **Read the differences.** [docs/exceljs-compat.md](https://github.com/DevXord/xlvane/blob/main/docs/exceljs-compat.md) lists every method with its status and the exceljs source of each behaviour, and ends with the differences found in reviews and cross-checks. The ones most likely to matter are summarised in the [@xlvane/compat README](https://github.com/DevXord/xlvane/blob/main/packages/compat/README.md#differences-from-exceljs): CSV output escapes text that starts like a formula (`formulaInjection: "off"` writes it unchanged, as exceljs does), a sheet id outside 1 to 65534 is written as the lowest unused id, only the first view of a worksheet is written, the module object is frozen, the streaming writer compresses in JavaScript, and input files are checked against ZIP and XML limits.
+- **TypeScript.** The type names of exceljs's `index.d.ts` are exported and work with `moduleResolution` `bundler` and `nodenext` and with `module: commonjs`. Under `module: node16`, TypeScript refuses `import ExcelJS = require('exceljs')` of an ES module (TS1471); use `nodenext` or `commonjs`.
+- **Browsers and Workers.** The methods that read or write files (`xlsx.readFile`, `xlsx.writeFile`, `csv.readFile`, `csv.writeFile`, the `filename` forms of the streaming classes and of `addImage`) work in Node.js, Bun and Deno; in browsers and Workers they throw `XLV_E_NOT_SUPPORTED`.
+
+To handle an unsupported call in code:
+
+```ts
+import ExcelJS from 'exceljs';
+
+const workbook = new ExcelJS.Workbook();
+try {
+  await workbook.xlsx.readFile('report.xlsx');
+} catch (error) {
+  const code = (error as { code?: unknown }).code;
+  if (code === 'XLV_E_NOT_SUPPORTED') console.error('Not supported by @xlvane/compat:', (error as Error).message);
+  else throw error;
+}
+```
+
+## 4. Roll back
+
+Install exceljs again under its own name, with the range the project used before (here `^4.4.0`):
+
+```sh
+npm install exceljs@^4.4.0
+```
+
+npm replaces the alias in `package.json` and `node_modules`. Restoring `package.json` and the lockfile from version control and running `npm install` has the same effect.
+
+## Reporting a problem
+
+When exceljs code behaves differently on `@xlvane/compat` and the difference is not listed in docs/exceljs-compat.md, please open an issue at https://github.com/DevXord/xlvane/issues with a small script that shows it.