@lotics/xlsx 0.1.6 → 0.1.8

package/AGENTS.md

@@ -0,0 +1,388 @@
+# @lotics/xlsx — the spreadsheet (.xlsx) read / build / write reference
+
+A self-contained spreadsheet engine: it parses `.xlsx` (and legacy `.xls`) into an immutable
+model, builds workbooks from scratch or from rows, evaluates formulas, authors native pivot
+tables, and writes real `.xlsx` bytes — with **no third-party spreadsheet library** in the
+export path. This file is the "reach for what" guide; the **exact API** of any function is its
+source, which ships with the package: read `node_modules/@lotics/xlsx/src/<module>.ts`.
+
+- **The barrel is the stable surface.** `import { parseExcelBuffer, exportWorkbook } from "@lotics/xlsx"`.
+  Everything documented as "barrel" below comes from there.
+- **Subpath imports** (`import { parseBiff8 } from "@lotics/xlsx/biff8_reader"`) reach internals
+  that are NOT in the stability contract — the formula engine, the legacy reader, the template
+  helper. They work and are documented here where they're the right tool, but they can change
+  shape between versions; prefer the barrel when it covers the task.
+- **Never hand-roll xlsx XML or reach for `exceljs`/`xlsx`/SheetJS.** They are not dependencies.
+  If a primitive is missing, add it to this package — every consumer inherits it.
+
+## The two type families — read this first
+
+The whole package is organized around two shapes. Pick the right one and everything else follows.
+
+- **`ParsedSpreadsheet` — the immutable snapshot.** What `parseExcelBuffer` returns. A plain
+  read-only tree: `sheets[]` → `rows[]` → `cells[]`, plus merges, images, charts, tables, pivots,
+  conditional formats. **If you only READ a file, stay here** — never build a model you won't mutate.
+- **`WorkbookModel` — the mutable model.** Sparse cell storage, a deduplicated `StyleRegistry`,
+  undo/redo commands. **Build this when you WRITE** — every builder (`buildDataWorkbook`,
+  `buildPivotTable`, the raw `SheetModel`) produces one, and `exportWorkbook` consumes one.
+  To edit an existing file, parse to a snapshot then `loadWorkbookFromSnapshot(parsed)`.
+
+```
+bytes ─parseExcelBuffer→ ParsedSpreadsheet ─loadWorkbookFromSnapshot→ WorkbookModel ─exportWorkbook→ bytes
+                          (read here)                                  (mutate here)
+```
+
+`exportWorkbook` takes a `WorkbookModel`, never a snapshot. A snapshot is a dead end for writing.
+
+## Reach by task
+
+### Read an `.xlsx` (or `.xls`) — `excel_parser.ts` (barrel)
+
+`parseExcelBuffer(arrayBuffer, options?) → ParsedSpreadsheet`. **Synchronous.** It takes an
+**`ArrayBuffer`**, not a Node `Buffer` — see the slicing gotcha below. It auto-detects an OLE2
+container (legacy `.xls` or an encrypted `.xlsx`) and routes it to the BIFF8 reader; genuinely
+encrypted files throw `PasswordProtectedError` (re-exported from the barrel for your catch site).
+
+```ts
+import { readFileSync } from "node:fs";
+import { parseExcelBuffer } from "@lotics/xlsx";
+
+const buf = readFileSync("report.xlsx");
+// Buffer is a view over a possibly-pooled ArrayBuffer — slice to its own bytes:
+const wb = parseExcelBuffer(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+
+for (const sheet of wb.sheets) {
+  for (const row of sheet.rows) {          // sparse: only populated rows, in order
+    for (const cell of row.cells) {         // sparse: only populated cols, in order
+      cell.column;        // 1-based column index
+      cell.value;         // the DISPLAY string (number-formatted, e.g. "1.234,00")
+      cell.rawValue;      // the raw number, when the cell is numeric (no reparse of `value`)
+      cell.typedValue;    // lossless typed value string|number|boolean|null (round-trip source)
+      cell.formula;       // formula text WITHOUT a leading "=", e.g. "SUM(A1:A5)"
+      cell.numFmtCode;    // e.g. "#,##0.00", "dd/mm/yyyy"
+      cell.error;         // "#DIV/0!" etc. for error cells
+      cell.content;       // { type: "plain"|"rich_text"|"hyperlink", ... }
+      cell.style;         // CellStyle (fonts, fill, borders, alignment)
+    }
+  }
+}
+```
+
+- **`value` is the formatted display string; `rawValue`/`typedValue` are the machine values.**
+  Do arithmetic on `rawValue`/`typedValue`, never `parseFloat(cell.value)` — the display string
+  is locale/format-mangled.
+- **Rows and cells are sparse and index-bearing.** `row.index` (1-based) and `cell.column`
+  (1-based) are the truth; do not assume `rows[0]` is row 1 or `cells[0]` is column A.
+- **Merges, hidden state, extras:** `sheet.mergedCells` (`{startRow,startCol,endRow,endCol}`,
+  1-based), `sheet.hidden` (hidden/veryHidden sheets are parsed, only tagged — data consumers can
+  still read them), `sheet.freezePane`, `sheet.charts`, `sheet.tables`, `sheet.pivotTables`,
+  `sheet.conditionalFormats`, `sheet.images`, `sheet.dataValidations`. Workbook-scope:
+  `wb.namedRanges`, `wb.pivotCaches`, `wb.fullCalcOnLoad`.
+- **Row cap.** `options.maxRowsPerSheet` defaults to **10 000** (a renderer guard). For full data
+  extraction pass `{ maxRowsPerSheet: Infinity }` and check `sheet.truncated` to see if the cap bit.
+- `parseExcelFromZip(zip, options?)` (barrel) parses from an already-unzipped
+  `Record<string, Uint8Array>` (from `unzipXlsx`, also barrel). Use it when you need BOTH the
+  snapshot AND the raw ZIP entries — pass that same `zip` back to `exportWorkbook` as the
+  `originalZip` to preserve unmodified parts (see Export).
+
+### Legacy `.xls` (BIFF8) — `biff8_reader.ts` (subpath)
+
+The modern parser reads only zip-based OOXML `.xlsx`. A pre-2007 `.xls` is an OLE2 Compound File
+of BIFF records — a completely different container. **`parseExcelBuffer` handles this for you:** it
+detects the OLE2 magic and routes to `parseBiff8`, returning the same `ParsedSpreadsheet` shape, so
+most callers never touch this module. Reach for it directly only when you already hold the bytes as
+a `Uint8Array` and know it's a legacy workbook:
+
+```ts
+import { parseBiff8 } from "@lotics/xlsx/biff8_reader";
+const parsed = parseBiff8(new Uint8Array(bytes), { maxRowsPerSheet: Infinity });
+```
+
+`parseBiff8(bytes: Uint8Array, options?: ParseOptions) → ParsedSpreadsheet`. **Scope is the data
+grid**, so consumers get uniform cell values with no per-caller `.xls` handling:
+
+- Reads: shared strings (`SST`, including `CONTINUE`-split records), string cells (`LABELSST`,
+  `LABEL`), numbers (`NUMBER`, `RK`, `MULRK`), boolean/numeric cached formula results, multi-sheet
+  workbooks (`BOUNDSHEET`), the 1900/1904 date mode (`DATEMODE`), and number-format codes
+  (`FORMAT`/`XF`) — enough to detect dates and currency so serials render correctly downstream.
+- **Does NOT surface:** cell styling (returns `style: {}`), merged cells, charts, images, column
+  widths, row heights, or hidden state. Blank/`MULBLANK`/`BOOLERR` cells are skipped. A formula
+  whose cached result is a **string** or **error** yields nothing (the resolving `STRING` record is
+  out of scope) rather than a wrong value.
+- Encrypted `.xls` (a `FILEPASS` record or an OLE2 `EncryptedPackage` stream) throws
+  `PasswordProtectedError`. A non-BIFF8 OLE2 container throws a plain descriptive error.
+- No third-party dependency and no regex/eval over file bytes — this path replaced SheetJS, which
+  was removed for prototype-pollution + ReDoS CVEs. Do not reintroduce SheetJS.
+
+### Build a sheet from rows — `data_workbook.ts` (barrel)
+
+The common "I have records, give me a styled `.xlsx`" path. Declare each column once with a `type`
+and a `value` accessor; the helper writes a bold frozen header, per-type number formats (dates as
+real Excel serials), right-aligned numerics, and auto-fit widths.
+
+```ts
+import { buildDataWorkbook, exportWorkbook } from "@lotics/xlsx";
+
+const wb = buildDataWorkbook({
+  sheetName: "Phí",                         // sanitized to Excel's rules, ≤31 chars
+  currencyFormat: '#,##0" ₫"',              // default "#,##0"
+  dateFormat: "dd/mm/yyyy",                 // default "dd/mm/yyyy"
+  columns: [
+    { header: "Container", value: (r) => r.container },              // type defaults to "text"
+    { header: "Ngày",     type: "date",     value: (r) => r.date },  // Date | "YYYY-MM-DD"
+    { header: "Số tiền",  type: "currency", value: (r) => r.amount },// number | numeric string
+  ],
+  rows,
+});
+const bytes = exportWorkbook(wb);
+```
+
+- `DataColumnType` = `"text" | "integer" | "number" | "currency" | "date"`. `integer`→`#,##0`,
+  `number`→`#,##0.##`, `currency`→`currencyFormat`, `date`→`dateFormat`; numerics right-align.
+- A `date` accessor returns a `Date` or an ISO `YYYY-MM-DD` string → stored as an Excel serial.
+  An **unparseable** date/number is written as its text so nothing is silently dropped.
+- `value` returning `null`/`undefined`/`""` leaves the cell truly empty. Column `width` (in
+  characters) overrides the auto-fit; auto-fit samples the first 1000 rows.
+- **Multi-sheet:** `buildDataSheet(opts, styles)` builds ONE `SheetModel` into a caller-supplied
+  `StyleRegistry`. Every sheet in one workbook must share the SAME registry (styles are stored by
+  index into it) — build each with `buildDataSheet` against one `new StyleRegistry()`, then
+  `new WorkbookModel({ sheets, activeSheetIndex: 0, styles })`.
+
+### Build cell-by-cell — `workbook_model.ts` (barrel)
+
+When the layout isn't a flat table (forms, invoices, dashboards), drive `SheetModel` directly.
+
+```ts
+import { WorkbookModel, SheetModel, StyleRegistry, exportWorkbook } from "@lotics/xlsx";
+
+const styles = new StyleRegistry();
+const sheet = new SheetModel("Invoice", styles);
+
+sheet.set("A1", "Total", { fontBold: true });          // set(ref, value, style?, numFmt?, formula?)
+sheet.set("B1", 1234.5, undefined, "#,##0.00");        // value + number-format code
+sheet.merge("A1:C1", "Header", { horizontalAlign: "center" });
+sheet.setColumnWidth("A", 24);                          // letter or 0-based index
+sheet.setRowHeight(1, 22);                              // row is 1-based
+sheet.setFreeze("A2");                                  // freeze row 1
+sheet.headerRow(1, ["A", "B", "C"], { background: "#D9E1F2" }); // bold+centered+bordered row
+
+const wb = new WorkbookModel({ sheets: [sheet], activeSheetIndex: 0, styles });
+const bytes = exportWorkbook(wb);
+```
+
+- `set(ref, value, style?, numFmt?, formula?) → CellModel`. `value` is `string | number | boolean
+  | null`. `style` is a `CellStyle` (interned via the registry). `numFmt` is a format-code STRING
+  (`"#,##0.00"`, `"dd/mm/yyyy"`, `"General"`). `formula` is the formula text **WITHOUT `=`** (see
+  Formulas).
+- `SheetModel` also exposes `getCell`, `deleteCell`, `colWidths`/`rowHeights` maps,
+  `hiddenRows`/`hiddenCols` sets, `mergedCells`, `getUsedRange()`, and `view`
+  (`showGridLines`, `zoomScale`, `tabColor`, …).
+- `setWithStyleIndex(ref, value, styleIndex, numFmtCode?, formula?, originalXfIndex?)` is the hot
+  path for bulk fills: it skips the display-value/content materialization. If you later need
+  `cell.displayValue` for such a cell, call `materializeDisplayValue(cell)` (barrel).
+- **Edit a parsed file:** `loadWorkbookFromSnapshot(parsed, date1904?)` turns a `ParsedSpreadsheet`
+  into a `WorkbookModel`, interning every style and marking the registry clean so a value-only edit
+  keeps the export fast path (see Export).
+- **`buildTemplateWorkbook(...)`** (subpath `@lotics/xlsx/template_builder`) is sugar over the above
+  for one or several sheets: `buildTemplateWorkbook((s) => {...})` or
+  `buildTemplateWorkbook({ name, build }, ...)`.
+
+### Styling — `types.ts` (`CellStyle`) + `style_helpers.ts` + `ooxml_color.ts` (barrel)
+
+A `CellStyle` is a flat options bag interned by the `StyleRegistry` (Excel's `cellXfs` model — one
+stored entry per distinct style). Every field is optional:
+
+- **Font:** `fontBold`, `fontItalic`, `fontStrike`, `fontColor` (`#RRGGBB`), `fontSize` (points),
+  `fontName`, `fontUnderline` (`"single"|"double"`), `fontVertAlign` (`"superscript"|"subscript"`).
+- **Fill:** `backgroundColor` (`#RRGGBB`), `patternType`, `gradientData` (`{type, degree, stops}`).
+- **Alignment:** `horizontalAlign` (`"left"|"center"|"right"`), `verticalAlign`
+  (`"top"|"middle"|"bottom"`), `wrapText`, `shrinkToFit`, `indent`, `textRotation`.
+- **Borders:** `borderTop`/`borderRight`/`borderBottom`/`borderLeft`/`borderDiagonal`, each a
+  `BorderStyle` = `{ width, style, color? }` where `style` is an OOXML border style name
+  (`"thin"`, `"medium"`, `"thick"`, `"dashed"`, `"double"`, …).
+
+Reach for the shortcuts instead of hand-writing four border objects:
+
+- `allBorders(style?="thin", color?="#000000")` → all four sides; `topBorder(...)` /
+  `bottomBorder(style?="medium", ...)` → one side. Spread into a `CellStyle`.
+- Colors: `normalizeColor`, `prefixHex`, `hexToArgb`, `hexToOoxmlRgb`, `applyTint` — canonical
+  `#RRGGBB` in the model; the writer converts to OOXML `AARRGGBB` on export.
+
+### Formulas — `set(...)`'s 5th arg + `formula_engine.ts` (subpath)
+
+Two facts govern everything here:
+
+1. **A cell carries formula text AND a cached value.** `sheet.set(ref, cachedValue, style, numFmt,
+   formulaText)`. `exportWorkbook` writes both: `<f>formulaText</f>` and `<v>cachedValue</v>`.
+2. **The writer does NOT recompute.** It also stamps `<calcPr fullCalcOnLoad="1"/>` on the workbook,
+   so **Excel/LibreOffice recompute every formula the moment they open your file** — a formula
+   written with `null` as its cached value still shows the right number in a spreadsheet app.
+
+```ts
+sheet.set("D2", 15, undefined, undefined, "SUM(A2:C2)");  // formula text has NO leading "="
+sheet.set("D3", null, undefined, undefined, "SUM(A3:C3)"); // cached value unknown → Excel fills it
+```
+
+The gap: a **non-Excel** consumer that reads the cached `<v>` (this package's own parser/renderer, a
+PDF/print pipeline, another tool) sees `null`/stale until it recomputes. To fill correct cached
+values yourself before export:
+
+```ts
+import { recomputeAll } from "@lotics/xlsx/formula_engine";
+recomputeAll(workbook);           // evaluates every formula cell, overwriting cached values
+const bytes = exportWorkbook(workbook);
+```
+
+- `recomputeAll(workbook)` and `recomputeIfStale(workbook)` (the latter only recomputes when the
+  workbook declares `fullCalcOnLoad`) are the convenience entry points. For incremental recalc while
+  editing, construct a `FormulaEngine(workbook)` and call `buildGraph()` + `evaluateMissing()` /
+  `evaluateAll()`, or `onCellChanged(sheet, ref, formula)` after each edit.
+- **Unsupported functions:** `LAMBDA`, `LET`, dynamic-array spill, and cube functions are not
+  implemented (no open-source engine covers them) — don't emit workbooks that depend on them and
+  expect this package to evaluate the result. Excel still will, on open.
+- **When you set a cell from a raw user/agent string that may or may not be a formula**, use the
+  command layer instead: `setCellValueCommand` treats a leading `=` as a formula and strips it for
+  you (see Editing). The raw `set()`/`setWithStyleIndex()` path expects the `=` already removed.
+
+### Native pivot tables — `pivot_builder.ts` (barrel)
+
+`buildPivotTable(workbook, spec) → PivotTableModel` authors a **real, refreshable Excel
+PivotTable** (not a pre-rendered cross-tab): `exportWorkbook` serializes it into genuine
+`pivotCacheDefinition` / `pivotCacheRecords` / `pivotTable` OOXML parts, so the user can refresh and
+re-pivot it in Excel.
+
+**v1 shape — the 2D cross-tab:** exactly one row field, one column field, one data (value) field,
+and zero or more page (report-filter) fields.
+
+```ts
+import { buildPivotTable } from "@lotics/xlsx";
+
+buildPivotTable(workbook, {
+  name: "PivotByPort",                          // unique within the workbook
+  source: { sheetName: "Data", ref: "A1:E500" },// first row is the header
+  rowField: 0,                                  // 0-based column index WITHIN the range
+  colField: 2,
+  data: { field: 4, fn: "sum", numFmtId: "3" }, // fn defaults to "sum"
+  pageFields: [1],                              // optional report filters
+  location: { sheetName: "Pivot", anchor: "A3" },
+});
+```
+
+- `data.fn` is a `PivotAggregateFn`: `"sum" | "count" | "countNums" | "average" | "min" | "max" |
+  "product"`. `rowGrandTotals`/`colGrandTotals` default `true`; `styleName` defaults
+  `"PivotStyleLight16"`.
+- **`data.numFmtId` is a BUILT-IN Excel number-format ID** (e.g. `"3"` = `#,##0`), a string, NOT a
+  format code. A custom code like `'#,##0" ₫"'` needs a registered style, which v1 does not wire up.
+- Validation throws (not silently) on an out-of-range field index or a field reused in more than one
+  role (row/column/data/page). The returned model is already attached to the target sheet; just
+  export.
+- The read side of pivots (`ParsedPivotTable`, `ParsedPivotCache`, `PivotTableModel`) is barrel-
+  exported for inspecting pivots parsed out of an existing file.
+
+### Tables, charts, sparklines — authored via the parsed structures (barrel types)
+
+There is **no dedicated `buildTable`/`buildChart` helper.** These features are read-first: the
+parser fills `sheet.tables` (`ParsedTable`), `sheet.charts` (`ParsedChart`), `sheet.sparklineGroups`,
+etc., and they **round-trip through `exportWorkbook` unchanged.** To AUTHOR one, construct the parsed
+structure and push it onto the sheet array on the `SheetModel`; the writer serializes
+`sheet.tables` → `xl/tables/*.xml` and `sheet.charts` → `xl/charts/*.xml` + drawing anchors.
+
+```ts
+sheet.tables.push({
+  name: "tblFees", displayName: "tblFees", ref: "A1:D20",
+  headerRow: true, totalsRow: false, autoFilter: true, styleName: "TableStyleMedium2",
+  columns: [ { id: 1, name: "Container" }, { id: 2, name: "Amount" }, /* … match the range */ ],
+});
+```
+
+A `ParsedChart` needs `chartType` (`"bar"|"col"|"line"|"pie"|"area"|"scatter"|…`), `series[]`
+(`{ name?, values: number[], color? }`), optional `categories`/`axes`/`legendPosition`, and an
+`anchor` (`{ from:{row,col}, to:{row,col} }`, 0-based). Treat this as a lower-level path than
+`buildPivotTable`: you're assembling the read-model by hand, so match the column set to the range and
+verify the output opens in Excel.
+
+### Edit with undo/redo — `spreadsheet_commands.ts` (barrel)
+
+Every mutation that needs to be undoable flows through a command factory that captures inverse state.
+Each returns a `Command` (`{ description, execute, undo }`); run it and push it onto your own history
+(or `command_history.ts`). The full set is barrel-exported: `setCellValueCommand`,
+`setCellStyleCommand`, `setRangeStyleCommand`, `setRangeNumFmtCommand`, `deleteCellCommand`,
+`clearRangeCommand`, `mergeCellsCommand`/`unmergeCellsCommand`, `insertRowsCommand`/
+`deleteRowsCommand`, `insertColsCommand`/`deleteColsCommand`, `setColWidthCommand`/
+`setRowHeightCommand`, `setNamedRangeCommand`, `addSheetCommand`/`deleteSheetCommand`/
+`renameSheetCommand`/`reorderSheetsCommand`, `setHiddenRowsCommand`/`setHiddenColsCommand`,
+`sortColumnCommand`/`multiSortCommand`, `setFreezePanesCommand`, `setZoomCommand`,
+`addConditionalFormatCommand`/`deleteConditionalFormatCommand`, `insertCellsShiftDownCommand`, and
+`batchCommand` (compose several into one undo step).
+
+- `setCellValueCommand(workbook, engine, sheetIndex, row, col, newValue)` — `newValue` is the raw
+  string; a leading `=` is detected and stored as a formula (with `null` cached value for the
+  `engine` to compute). Pass a `FormulaEngine` so dependents recalc; pass `undefined` to skip recalc.
+- Row/col insert/delete re-key populated cells and shift formula references (via
+  `adjustMergedCells*` / `expandFormulaRangesForRowInsert`, also barrel-exported) — this is why they
+  must be commands, not direct `SheetModel` edits.
+- Row/col insert/delete also **clamp the used range**: before shifting, they drop "phantom" cells —
+  value-less, unstyled, General-format padding outside the bounding box of the cells that carry data
+  or formatting. Real files accumulate these (a bloated stored `<dimension>` or a stray fill leaves
+  empty cells far past the data), and left in place they inflate the used range that drives the canvas
+  render width and the exported `<dimension>`. Undo restores them, and cells with any value, formula,
+  style, number format, or hyperlink are never dropped.
+
+### Export to `.xlsx` bytes — `xlsx_writer.ts` (barrel)
+
+`exportWorkbook(workbook, originalZip?) → Uint8Array`. **Synchronous.** Returns a fresh
+zip (`fflate` level 6). Write it to disk:
+
+```ts
+import { writeFileSync } from "node:fs";
+import { exportWorkbook } from "@lotics/xlsx";
+
+const bytes = exportWorkbook(wb);                 // Uint8Array
+writeFileSync("out.xlsx", Buffer.from(bytes));    // Buffer.from wraps the bytes for fs
+```
+
+- **`originalZip` preserves unmodified parts.** When you parsed with `parseExcelFromZip(zip)` and
+  edited the resulting model, pass that same `zip` back: `exportWorkbook(wb, zip)`. Parts the writer
+  regenerates (worksheets, shared strings, workbook, styles) are rebuilt; everything else
+  (drawings, media, themes, VBA) passes through byte-for-byte.
+- **Styles-passthrough fast path.** If `originalZip` is supplied AND no style was mutated
+  (`workbook.styles.dirty === false`, which `loadWorkbookFromSnapshot` sets up) AND the original had
+  `xl/styles.xml`, the writer reuses cells' original `s=` indices and skips rebuilding styles
+  entirely — the dominant path for value-only template fills. Touching any style (interning a new
+  `CellStyle` or a new numFmt code) flips `dirty` and takes the full rebuild.
+
+## Gotchas
+
+- **`parseExcelBuffer` takes an `ArrayBuffer`, not a Node `Buffer`.** A `Buffer` is a view over a
+  possibly-shared/pooled `ArrayBuffer`, so `buf.buffer` may contain other files' bytes. Always slice
+  to the view's own window: `buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength)`.
+  Passing `buf.buffer` directly can hand the parser garbage tail bytes.
+- **Formula text has NO leading `=` on the model path.** `sheet.set(ref, v, s, fmt, "SUM(A1:A5)")`,
+  not `"=SUM(...)"`. The barrel `set`/`setWithStyleIndex` write the string verbatim into `<f>`, and
+  OOXML formulas omit the `=`. The ONLY place a `=` is expected is `setCellValueCommand`, which
+  parses raw user input and strips it.
+- **The writer never recomputes; it relies on `fullCalcOnLoad`.** A formula written with a `null` or
+  stale cached value is correct in Excel (which recalcs on open) but wrong to any consumer that
+  trusts the cached `<v>` without recomputing. Call `recomputeAll(workbook)` before export when a
+  non-Excel reader will consume the file.
+- **Multi-sheet workbooks must share ONE `StyleRegistry`.** Cell styles are stored by index into a
+  single registry; sheets built against different registries render with each other's styles when
+  merged. Use `buildDataSheet(opts, styles)` / `new SheetModel(name, styles)` with one shared
+  registry, never `buildDataWorkbook` per sheet.
+- **Dates are Excel serial numbers plus a date number-format code, not `Date` objects.**
+  `buildDataWorkbook`'s `date` columns convert for you (from a `Date` via LOCAL `YYYY-MM-DD`, or from
+  an ISO string). On the raw model path, store the serial and set a date `numFmt`
+  (`parseToExcelSerial(iso)` from `@lotics/xlsx/numfmt_type` computes one; it interprets the ISO date
+  in UTC and anchors at 1899-12-30 for the Lotus-1900-leap-year bug).
+- **`maxRowsPerSheet` defaults to 10 000 and silently truncates.** For a full extract pass
+  `{ maxRowsPerSheet: Infinity }` and check `sheet.truncated`.
+- **`cell.value` is the formatted display string.** Compute on `cell.rawValue`/`cell.typedValue`;
+  never `parseFloat(cell.value)`.
+- **Legacy `.xls` is data-only.** No styles, merges, widths, charts, or images survive a `.xls`
+  read, and string/error formula results are dropped. If a downstream step needs those, it must come
+  from an `.xlsx`.
+- **Pivot `data.numFmtId` is a built-in numeric ID string, not a format code** — a custom currency
+  code won't apply in v1.
+- **`setWithStyleIndex` leaves `displayValue` empty** (it's the export fast path). If you read
+  `cell.displayValue` off such a cell before exporting, it's `""` until you call
+  `materializeDisplayValue(cell)`.

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@lotics/xlsx",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
     "./*": "./src/*.ts"
   },
   "files": [
-    "src"
+    "src",
+    "AGENTS.md"
   ],
   "publishConfig": {
     "access": "public"

package/src/biff8_reader.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from "vitest";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { parseBiff8 } from "./biff8_reader";
+import { loadWorkbookFromSnapshot } from "./workbook_model";
 import { isOle2, PasswordProtectedError } from "@lotics/office-io";
 
 // A synthetic BIFF8 (.xls) workbook: 250 data rows of Unicode strings + integer,
@@ -28,30 +29,42 @@ describe("parseBiff8", () => {
 
   it("decodes Unicode text cells", () => {
     const s = parseBiff8(fixture).sheets[0];
-    expect(cell(s, 0, 0)).toBe("ID");
-    expect(cell(s, 0, 1)).toBe("Tên khách");
-    expect(cell(s, 0, 2)).toBe("Số tiền");
+    expect(cell(s, 1, 1)).toBe("ID");
+    expect(cell(s, 1, 2)).toBe("Tên khách");
+    expect(cell(s, 1, 3)).toBe("Số tiền");
   });
 
   it("decodes a string that falls past the SST CONTINUE boundary", () => {
     const s = parseBiff8(fixture).sheets[0];
-    expect(cell(s, 200, 1)).toBe("Khách 200 — Công ty TNHH số 200");
-    expect(cell(s, 249, 1)).toBe("Khách 249 — Công ty TNHH số 249");
+    expect(cell(s, 201, 2)).toBe("Khách 200 — Công ty TNHH số 200");
+    expect(cell(s, 250, 2)).toBe("Khách 249 — Công ty TNHH số 249");
   });
 
   it("decodes integer, float and negative numbers to the exact value", () => {
     const s = parseBiff8(fixture).sheets[0];
-    expect(cell(s, 2, 2)).toBe(2000); // integer (RK int)
-    expect(cell(s, 3, 2)).toBe(3000.5); // float
-    expect(cell(s, 5, 2)).toBe(-500); // negative
-    expect(cell(s, 200, 2)).toBe(-20000);
-    expect(cell(s, 249, 2)).toBe(249000.5);
+    expect(cell(s, 3, 3)).toBe(2000); // integer (RK int)
+    expect(cell(s, 4, 3)).toBe(3000.5); // float
+    expect(cell(s, 6, 3)).toBe(-500); // negative
+    expect(cell(s, 201, 3)).toBe(-20000);
+    expect(cell(s, 250, 3)).toBe(249000.5);
   });
 
   it("honors maxRowsPerSheet and flags truncation", () => {
     const s = parseBiff8(fixture, { maxRowsPerSheet: 10 }).sheets[0];
     expect(s.truncated).toBe(true);
-    expect(s.rows.every((r) => r.index < 10)).toBe(true);
+    expect(s.rows.every((r) => r.index <= 10)).toBe(true);
+  });
+
+  it("emits the ParsedSpreadsheet 1-based convention: A1 survives model load and export refs", () => {
+    // The regression that motivated normalization: 0-based BIFF indices fed
+    // loadWorkbookFromSnapshot's 1-based A1-ref construction, mapping the whole
+    // first column to invalid refs (colNumToLetters(0) === ""). The outcome
+    // that matters: the .xls's first cell lands at A1 in the model.
+    const wb = loadWorkbookFromSnapshot(parseBiff8(fixture));
+    const sheet = wb.sheets[0];
+    expect(sheet.cells.get("A1")?.value).toBe("ID");
+    expect(sheet.cells.get("B1")?.value).toBe("Tên khách");
+    expect(sheet.cells.has("0")).toBe(false);
   });
 
   it("rejects an OLE2 buffer with no Workbook stream", () => {
@@ -98,19 +111,19 @@ describe("parseBiff8 number formats", () => {
   };
 
   it("reads a date cell as an Excel serial carrying its date number-format", () => {
-    const c = cell(1, 0);
+    const c = cell(2, 1);
     expect(c?.typedValue).toBe(45672); // 2025-01-15
     expect(c?.numFmtCode).toBe("dd/mm/yyyy");
   });
 
   it("leaves a plain number with no number-format (General)", () => {
-    expect(cell(1, 1)?.typedValue).toBe(42);
-    expect(cell(1, 1)?.numFmtCode).toBeUndefined();
-    expect(cell(1, 2)?.typedValue).toBe(1234.5);
+    expect(cell(2, 2)?.typedValue).toBe(42);
+    expect(cell(2, 2)?.numFmtCode).toBeUndefined();
+    expect(cell(2, 3)?.typedValue).toBe(1234.5);
   });
 
   it("decodes a Unicode string cell", () => {
-    expect(cell(1, 3)?.typedValue).toBe("Ábc");
+    expect(cell(2, 4)?.typedValue).toBe("Ábc");
   });
 });
 

package/src/biff8_reader.ts

@@ -237,7 +237,7 @@ function parseSheet(stream: Uint8Array, start: number, name: string, g: Globals,
     const r = grid.get(ri);
     if (!r) continue;
     const cells = [...r.values()].sort((a, b) => a.column - b.column);
-    rows.push({ index: ri, height: sheet.defaultRowHeight, cells, hidden: false });
+    rows.push({ index: ri + 1, height: sheet.defaultRowHeight, cells, hidden: false });
   }
   sheet.rows = rows;
   sheet.totalRowCount = maxRow + 1;
@@ -247,14 +247,19 @@ function parseSheet(stream: Uint8Array, start: number, name: string, g: Globals,
 
 // ─── Cell builders ──────────────────────────────────────────────────────────
 
+// BIFF stores 0-based row/col on disk; ParsedSpreadsheet is 1-based (the OOXML
+// parser's convention, and what loadWorkbookFromSnapshot's A1-ref construction
+// requires — colNumToLetters(0) is "", so a 0-based column would silently land
+// every first-column cell at an invalid ref). Builders receive the raw BIFF
+// column and normalize at this single escape point.
 function textCell(column: number, text: string): ParsedCell {
-  return { column, value: text, typedValue: text, content: { type: "plain", text }, style: {} };
+  return { column: column + 1, value: text, typedValue: text, content: { type: "plain", text }, style: {} };
 }
 
 function numberCell(column: number, num: number, numFmt: string | undefined): ParsedCell {
   const value = Number.isFinite(num) ? String(num) : "";
   return {
-    column, value, rawValue: num, typedValue: num,
+    column: column + 1, value, rawValue: num, typedValue: num,
     numFmtCode: numFmt && numFmt !== "General" ? numFmt : undefined,
     content: { type: "plain", text: value }, style: {},
   };
@@ -268,7 +273,7 @@ function formulaCell(column: number, body: Uint8Array, numFmt: string | undefine
     const kind = body[6];
     if (kind === 1) {
       const b = body[8] !== 0;
-      return { column, value: b ? "TRUE" : "FALSE", typedValue: b, content: { type: "plain", text: b ? "TRUE" : "FALSE" }, style: {} };
+      return { column: column + 1, value: b ? "TRUE" : "FALSE", typedValue: b, content: { type: "plain", text: b ? "TRUE" : "FALSE" }, style: {} };
     }
     // string (resolved by a following STRING record — none in scope), error, or
     // empty: surface nothing rather than a wrong value.

package/src/spreadsheet_commands.test.ts

@@ -27,10 +27,15 @@ import {
   setShowGridLinesCommand,
   setShowHeadersCommand,
   setHyperlinkCommand,
+  insertRowsCommand,
+  deleteRowsCommand,
+  insertColsCommand,
+  deleteColsCommand,
 } from "./spreadsheet_commands";
 import { CommandHistory } from "./command_history";
 import { WorkbookModel, SheetModel, StyleRegistry } from "./workbook_model";
 import type { ChangeEvent } from "./workbook_model";
+import { rowColToRef, refToRowCol } from "./excel_utils";
 
 function makeWorkbook(): WorkbookModel {
   const styles = new StyleRegistry();
@@ -770,3 +775,107 @@ describe("setHyperlinkCommand", () => {
     expect(wb.sheets[0].hyperlinks.has("A1")).toBe(false);
   });
 });
+
+describe("structural ops clamp phantom cells", () => {
+  // A sheet whose real data ends at column C but that carries value-less,
+  // unstyled "phantom" cells out to column 40 in row 2 — the shape a bloated
+  // stored `<dimension>` (e.g. A1:XDD63) leaves behind. Left alone, these
+  // inflate the used range, driving the render width and exported dimension to
+  // the phantom extent.
+  function makeSheetWithJunkWidth(): WorkbookModel {
+    const wb = makeWorkbook();
+    const sheet = wb.sheets[0];
+    sheet.set("A1", "Name");
+    sheet.set("B1", "Qty");
+    sheet.set("C1", "Price");
+    sheet.set("A2", "Widget");
+    sheet.set("B2", 5);
+    sheet.set("C2", 10);
+    for (let c = 4; c <= 40; c++) sheet.set(rowColToRef(2, c), null);
+    return wb;
+  }
+
+  test("insert-rows drops phantom cells beyond the used-data columns", () => {
+    const wb = makeSheetWithJunkWidth();
+    const sheet = wb.sheets[0];
+    expect(sheet.getUsedRange().maxCol).toBe(40); // phantoms inflate it pre-op
+
+    insertRowsCommand(wb, 0, 2, 1).execute();
+
+    // Used range is clamped to the real data extent (column C = 3).
+    expect(sheet.getUsedRange().maxCol).toBe(3);
+    // No cell — in the inserted row or any other — exists beyond column C.
+    for (const ref of sheet.cells.keys()) {
+      expect(refToRowCol(ref)!.col).toBeLessThanOrEqual(3);
+    }
+    // Data is intact and shifted: row 2 is now blank, data moved to row 3.
+    expect(sheet.getCell("A3")?.value).toBe("Widget");
+  });
+
+  test("preserves an empty but styled cell — not a phantom", () => {
+    // A styles-wired sheet, as loaded from a file, so `set` can intern a style.
+    const styles = new StyleRegistry();
+    const sheet = new SheetModel("Sheet1", styles);
+    const wb = new WorkbookModel({ sheets: [sheet], activeSheetIndex: 0, styles });
+    sheet.set("A1", "data");
+    sheet.set("E1", null, { fontBold: true }); // empty yet meaningfully styled
+    expect(sheet.getCell("E1")?.styleIndex).not.toBe(0);
+
+    insertRowsCommand(wb, 0, 1, 1).execute();
+
+    // The styled empty cell survives (shifted to E2) and still extends the range.
+    expect(sheet.getUsedRange().maxCol).toBe(5);
+    expect(sheet.getCell("E2")?.styleIndex).not.toBe(0);
+  });
+
+  test("leaves phantom cells that sit inside the data bounding box", () => {
+    const wb = makeWorkbook();
+    const sheet = wb.sheets[0];
+    sheet.set("A1", "x");
+    sheet.set("C1", "y"); // data spans A1:C1
+    sheet.set("B1", null); // a phantom INSIDE the box — must not be dropped
+
+    insertRowsCommand(wb, 0, 1, 1).execute();
+
+    // B shifts to B2 and remains present; the box is unchanged.
+    expect(sheet.getCell("B2")).toBeDefined();
+    expect(sheet.getUsedRange().maxCol).toBe(3);
+  });
+
+  test("delete-rows also clamps phantom cells", () => {
+    const wb = makeSheetWithJunkWidth();
+    const sheet = wb.sheets[0];
+    deleteRowsCommand(wb, 0, 1, 1).execute();
+    expect(sheet.getUsedRange().maxCol).toBe(3);
+  });
+
+  test("insert-cols also clamps phantom cells", () => {
+    const wb = makeSheetWithJunkWidth();
+    const sheet = wb.sheets[0];
+    insertColsCommand(wb, 0, 1, 1).execute();
+    // Phantoms pruned; real data A:C shifted right to B:D.
+    expect(sheet.getUsedRange().maxCol).toBe(4);
+  });
+
+  test("delete-cols also clamps phantom cells", () => {
+    const wb = makeSheetWithJunkWidth();
+    const sheet = wb.sheets[0];
+    deleteColsCommand(wb, 0, 1, 1).execute();
+    // Phantoms pruned; B:C shifted left to A:B.
+    expect(sheet.getUsedRange().maxCol).toBe(2);
+  });
+
+  test("undo restores the pruned phantom cells", () => {
+    const wb = makeSheetWithJunkWidth();
+    const sheet = wb.sheets[0];
+    const beforeSize = sheet.cells.size;
+
+    const cmd = insertRowsCommand(wb, 0, 2, 1);
+    cmd.execute();
+    expect(sheet.getUsedRange().maxCol).toBe(3);
+
+    cmd.undo();
+    expect(sheet.cells.size).toBe(beforeSize);
+    expect(sheet.getUsedRange().maxCol).toBe(40);
+  });
+});

package/src/spreadsheet_commands.ts

@@ -9,7 +9,7 @@
 
 import type { Command } from "./command_history";
 import { SheetModel } from "./workbook_model";
-import type { WorkbookModel, CellValue } from "./workbook_model";
+import type { WorkbookModel, CellValue, CellModel } from "./workbook_model";
 import type { CellStyle, CellContent } from "./types";
 import type { ParsedConditionalFormat } from "./excel_cf_types";
 import type { FormulaEngine } from "./formula_engine";
@@ -319,6 +319,90 @@ export function unmergeCellsCommand(
   };
 }
 
+// =============================================================================
+// Phantom-cell clamping for structural row/column ops
+// =============================================================================
+//
+// Real-world .xlsx files accumulate "phantom" cells: value-less, unformatted
+// `<c>` elements that a stray fill-to-the-right or a bloated stored
+// `<dimension>` left behind (e.g. a sheet whose data ends at column G but that
+// carries empty cells out to column XDD). The parser materializes them
+// faithfully, so they land in the model carrying no data and no formatting —
+// yet they inflate the used range, which drives BOTH the canvas render width
+// and the exported `<dimension>`. A file bloated to column 16,332 renders ~1.5M
+// pixels wide.
+//
+// A structural row/column op is the natural normalization point (Excel itself
+// tightens the used range when you insert/delete): before shifting cells, we
+// drop phantom cells that lie OUTSIDE the bounding box of the cells that
+// actually carry information, clamping the sheet to its real extent. We never
+// drop a cell with a value, a formula, a non-default style, a number format, an
+// error, rich text, or a hyperlink — only truly inert padding.
+
+/**
+ * A cell carrying zero information: no value, no formula, the default (empty)
+ * style, the General number format, no error/rich-text, and plain empty
+ * content (so hyperlinks are excluded). Such a cell is indistinguishable from
+ * an absent cell — Excel renders and evaluates them identically.
+ */
+function isInertCell(cell: CellModel): boolean {
+  return (
+    (cell.value === null || cell.value === "") &&
+    cell.formula === undefined &&
+    cell.styleIndex === 0 &&
+    (cell.originalXfIndex === undefined || cell.originalXfIndex === 0) &&
+    (cell.numFmtCode === "General" || cell.numFmtCode === "") &&
+    cell.richText === undefined &&
+    cell.error === undefined &&
+    cell.content.type === "plain" &&
+    cell.content.text === ""
+  );
+}
+
+/**
+ * Drop inert phantom cells that fall outside the bounding box of the sheet's
+ * meaningful (non-inert) cells, clamping the used range to its real extent.
+ * Returns the removed cells keyed by ref so the caller can restore them on undo.
+ */
+function clampInertCells(sheet: SheetModel): Map<string, CellModel> {
+  let minRow = Infinity;
+  let maxRow = 0;
+  let minCol = Infinity;
+  let maxCol = 0;
+  let hasMeaningful = false;
+  for (const [ref, cell] of sheet.cells) {
+    if (isInertCell(cell)) continue;
+    const rc = refToRowColSafe(ref);
+    if (!rc) continue;
+    hasMeaningful = true;
+    if (rc.row < minRow) minRow = rc.row;
+    if (rc.row > maxRow) maxRow = rc.row;
+    if (rc.col < minCol) minCol = rc.col;
+    if (rc.col > maxCol) maxCol = rc.col;
+  }
+
+  const pruned = new Map<string, CellModel>();
+  for (const [ref, cell] of sheet.cells) {
+    if (!isInertCell(cell)) continue;
+    // No meaningful cells at all → every phantom is padding. Otherwise, only
+    // phantoms strictly outside the meaningful bounding box are padding; a
+    // phantom interspersed with real data is left untouched (it doesn't inflate
+    // the used range and dropping it would be a needless mutation).
+    if (!hasMeaningful) {
+      pruned.set(ref, cell);
+      continue;
+    }
+    const rc = refToRowColSafe(ref);
+    if (!rc) continue;
+    if (rc.row < minRow || rc.row > maxRow || rc.col < minCol || rc.col > maxCol) {
+      pruned.set(ref, cell);
+    }
+  }
+
+  for (const ref of pruned.keys()) sheet.cells.delete(ref);
+  return pruned;
+}
+
 // =============================================================================
 // Insert Rows
 // =============================================================================
@@ -334,11 +418,13 @@ export function insertRowsCommand(
   // the inverse of `adjustMergedCellsForRowInsert` and avoids edge cases when
   // inserts split existing ranges.
   let mergeSnapshot: string[] = [];
+  let inertSnapshot = new Map<string, CellModel>();
 
   return {
     description: `Insert ${count} row${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       // Shift existing cells down
       const toMove: Array<{ ref: string; row: number; col: number }> = [];
       for (const [ref] of sheet.cells) {
@@ -388,6 +474,7 @@ export function insertRowsCommand(
         sheet.rowHeights.set(r - count, h);
       }
       for (let r = at; r < at + count; r++) sheet.rowHeights.delete(r);
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "rows_deleted", sheet: sheetIndex, at, count });
     },
   };
@@ -413,11 +500,13 @@ export function deleteRowsCommand(
     }
   }
   let mergeSnapshot: string[] = [];
+  let inertSnapshot = new Map<string, CellModel>();
 
   return {
     description: `Delete ${count} row${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       // Delete cells in the range
       for (const ref of snapshot.keys()) sheet.cells.delete(ref);
       // Shift cells up
@@ -454,6 +543,7 @@ export function deleteRowsCommand(
       for (const [ref, snap] of snapshot) {
         sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
       }
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "rows_inserted", sheet: sheetIndex, at, count });
     },
   };
@@ -471,11 +561,13 @@ export function insertColsCommand(
 ): Command {
   const sheet = workbook.sheets[sheetIndex];
   let mergeSnapshot: string[] = [];
+  let inertSnapshot = new Map<string, CellModel>();
 
   return {
     description: `Insert ${count} column${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       const toMove: Array<{ ref: string; row: number; col: number }> = [];
       for (const [ref] of sheet.cells) {
         const rc = refToRowColSafe(ref);
@@ -519,6 +611,7 @@ export function insertColsCommand(
         sheet.colWidths.set(c - count, w);
       }
       for (let c = at; c < at + count; c++) sheet.colWidths.delete(c);
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "cols_deleted", sheet: sheetIndex, at, count });
     },
   };
@@ -543,11 +636,13 @@ export function deleteColsCommand(
     }
   }
   let mergeSnapshot: string[] = [];
+  let inertSnapshot = new Map<string, CellModel>();
 
   return {
     description: `Delete ${count} column${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       for (const ref of snapshot.keys()) sheet.cells.delete(ref);
       const toMove: Array<{ ref: string; row: number; col: number }> = [];
       for (const [ref] of sheet.cells) {
@@ -580,6 +675,7 @@ export function deleteColsCommand(
       for (const [ref, snap] of snapshot) {
         sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
       }
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "cols_inserted", sheet: sheetIndex, at, count });
     },
   };