@lotics/xlsx 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/xlsx",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/src/csv_parser.ts

@@ -8,8 +8,12 @@ import type {
 
 const MAX_ROWS = 10_000;
 
-export async function parseCsvFile(url: string, signal?: AbortSignal): Promise<ParsedSpreadsheet> {
-  const response = await fetch(url, { signal });
+export async function parseCsvFile(
+  url: string,
+  signal?: AbortSignal,
+  credentials?: RequestCredentials,
+): Promise<ParsedSpreadsheet> {
+  const response = await fetch(url, { signal, credentials });
   if (!response.ok) {
     throw new Error(`Failed to fetch file: ${response.status} ${response.statusText}`);
   }

package/src/data_workbook.test.ts

@@ -1,8 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { buildDataWorkbook } from "./data_workbook";
+import { buildDataWorkbook, buildDataSheet } from "./data_workbook";
 import { exportWorkbook } from "./xlsx_writer";
 import { parseExcelBuffer } from "./excel_parser";
 import { parseToExcelSerial } from "./numfmt_type";
+import { WorkbookModel, StyleRegistry } from "./workbook_model";
 import type { ParsedSheet, ParsedCell } from "./types";
 
 interface FeeRow {
@@ -109,3 +110,31 @@ describe("buildDataWorkbook", () => {
     expect(widths.get(2)).toBe(40); // explicit override wins
   });
 });
+
+describe("buildDataSheet", () => {
+  it("builds multiple sheets into one shared registry that round-trips with styles intact", () => {
+    // Two sheets sharing ONE registry — cell styles are stored by index into a
+    // single registry, so this is the only correct way to merge data sheets into
+    // one workbook (two buildDataWorkbook calls each mint a private registry).
+    const styles = new StyleRegistry();
+    const columns = [
+      { header: "Container", value: (r: FeeRow) => r.container },
+      { header: "Số tiền", type: "currency" as const, value: (r: FeeRow) => r.amount },
+    ];
+    const a = buildDataSheet({ sheetName: "Gate IN", currencyFormat: '#,##0" ₫"', columns, rows: [ROWS[0]] }, styles);
+    const b = buildDataSheet({ sheetName: "Gate OUT", currencyFormat: '#,##0" ₫"', columns, rows: [ROWS[1]] }, styles);
+    const wb = new WorkbookModel({ sheets: [a, b], activeSheetIndex: 0, styles });
+    const parsed = parseExcelBuffer(new Uint8Array(exportWorkbook(wb)).buffer);
+
+    expect(parsed.sheets.map((s) => s.name)).toEqual(["Gate IN", "Gate OUT"]);
+    // Each sheet's body landed on its own tab.
+    expect(cellAt(parsed.sheets[0], 2, 1)?.value).toBe("ABCD1234567");
+    expect(cellAt(parsed.sheets[0], 2, 2)?.rawValue).toBe(1_500_000);
+    expect(cellAt(parsed.sheets[1], 2, 1)?.value).toBe("WXYZ7654321");
+    // Styles resolve correctly across both sheets: bold header on sheet 2, and the
+    // currency body cell on sheet 1 keeps its right alignment (proves the shared
+    // registry's style indices are valid for every sheet, not just the first).
+    expect(cellAt(parsed.sheets[1], 1, 1)?.style?.fontBold).toBe(true);
+    expect(cellAt(parsed.sheets[0], 2, 2)?.style?.horizontalAlign).toBe("right");
+  });
+});

package/src/data_workbook.ts

@@ -123,23 +123,21 @@ function clampWidth(chars: number): number {
 }
 
 /**
- * Build a single-sheet workbook from typed columns + rows.
+ * Build ONE styled data sheet from typed columns + rows into a caller-supplied
+ * style registry. Use this when assembling a multi-sheet workbook so every sheet
+ * shares one registry (cell styles are stored by index into a single registry —
+ * sheets built against different registries cannot be merged). For the common
+ * single-sheet case use {@link buildDataWorkbook}.
  *
  * ```ts
- * const wb = buildDataWorkbook({
- *   sheetName: "Phí",
- *   currencyFormat: '#,##0" ₫"',
- *   columns: [
- *     { header: "Container", value: (r) => r.container },
- *     { header: "Ngày", type: "date", value: (r) => r.date },
- *     { header: "Số tiền", type: "currency", value: (r) => r.amount },
- *   ],
- *   rows,
- * });
+ * const styles = new StyleRegistry();
+ * const a = buildDataSheet({ sheetName: "A", columns, rows: rowsA }, styles);
+ * const b = buildDataSheet({ sheetName: "B", columns, rows: rowsB }, styles);
+ * const wb = new WorkbookModel({ sheets: [a, b], activeSheetIndex: 0, styles });
  * const bytes = exportWorkbook(wb);
  * ```
  */
-export function buildDataWorkbook<R>(opts: BuildDataWorkbookOptions<R>): WorkbookModel {
+export function buildDataSheet<R>(opts: BuildDataWorkbookOptions<R>, styles: StyleRegistry): SheetModel {
   const {
     columns,
     rows,
@@ -149,7 +147,6 @@ export function buildDataWorkbook<R>(opts: BuildDataWorkbookOptions<R>): Workboo
     headerStyle = DEFAULT_HEADER_STYLE,
   } = opts;
 
-  const styles = new StyleRegistry();
   const sheet = new SheetModel(sanitizeSheetName(sheetName), styles);
 
   // Per-type body cell style (interned once each via the StyleRegistry).
@@ -182,5 +179,28 @@ export function buildDataWorkbook<R>(opts: BuildDataWorkbookOptions<R>): Workboo
   // Freeze the header row.
   if (rows.length > 0 || columns.length > 0) sheet.setFreeze("A2");
 
+  return sheet;
+}
+
+/**
+ * Build a single-sheet workbook from typed columns + rows.
+ *
+ * ```ts
+ * const wb = buildDataWorkbook({
+ *   sheetName: "Phí",
+ *   currencyFormat: '#,##0" ₫"',
+ *   columns: [
+ *     { header: "Container", value: (r) => r.container },
+ *     { header: "Ngày", type: "date", value: (r) => r.date },
+ *     { header: "Số tiền", type: "currency", value: (r) => r.amount },
+ *   ],
+ *   rows,
+ * });
+ * const bytes = exportWorkbook(wb);
+ * ```
+ */
+export function buildDataWorkbook<R>(opts: BuildDataWorkbookOptions<R>): WorkbookModel {
+  const styles = new StyleRegistry();
+  const sheet = buildDataSheet(opts, styles);
   return new WorkbookModel({ sheets: [sheet], activeSheetIndex: 0, styles });
 }

package/src/excel_utils.ts

@@ -120,6 +120,16 @@ export function rowColToRef(row: number, col: number): string {
   return colNumToLetters(col) + String(row);
 }
 
+/** Escape a string for inclusion in XML text or a double-quoted attribute. */
+export function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
 // =============================================================================
 // Packed cell key (row, col) → number
 // =============================================================================

package/src/index.ts

@@ -106,9 +106,24 @@ export { exportWorkbook } from "./xlsx_writer";
 // Data → workbook (the common "rows in, .xlsx out" helper)
 // -----------------------------------------------------------------------------
 
-export { buildDataWorkbook } from "./data_workbook";
+export { buildDataWorkbook, buildDataSheet } from "./data_workbook";
 export type { DataColumn, DataColumnType, BuildDataWorkbookOptions } from "./data_workbook";
 
+// -----------------------------------------------------------------------------
+// Pivot tables (author a native, refreshable Excel PivotTable into a workbook)
+// -----------------------------------------------------------------------------
+
+export { buildPivotTable } from "./pivot_builder";
+export type { PivotBuildSpec } from "./pivot_builder";
+export { PivotTableModel } from "./pivot_model";
+export type {
+  ParsedPivotTable,
+  ParsedPivotCache,
+  PivotCacheField,
+  PivotCacheItem,
+  PivotAggregateFn,
+} from "./ooxml_pivot_types";
+
 export { unzipXlsx } from "./ooxml_zip";
 
 // -----------------------------------------------------------------------------

package/src/pivot_builder.test.ts

@@ -0,0 +1,278 @@
+import { describe, it, expect } from "vitest";
+import { buildDataWorkbook, type DataColumn } from "./data_workbook";
+import { SheetModel } from "./workbook_model";
+import { buildPivotTable } from "./pivot_builder";
+import { exportWorkbook } from "./xlsx_writer";
+import { unzipXlsx } from "./ooxml_zip";
+import { parseExcelBuffer } from "./excel_parser";
+import { recomputePivot, type PivotSourceData } from "./pivot_recompute";
+
+interface Row {
+  line: string;
+  size: string;
+  container: string;
+  amount: number;
+}
+
+const COLUMNS: DataColumn<Row>[] = [
+  { header: "Line", value: (r) => r.line },
+  { header: "Size", value: (r) => r.size },
+  { header: "Container", value: (r) => r.container },
+  { header: "Amount", type: "number", value: (r) => r.amount },
+];
+
+// SHA: 40HC {C1=100, C2=200}, 20DC {C3=50}; CMA: 40HC {C4=70}.
+const ROWS: Row[] = [
+  { line: "SHA", size: "40HC", container: "C1", amount: 100 },
+  { line: "SHA", size: "40HC", container: "C2", amount: 200 },
+  { line: "SHA", size: "20DC", container: "C3", amount: 50 },
+  { line: "CMA", size: "40HC", container: "C4", amount: 70 },
+];
+
+/** A workbook with a "Data" source sheet (A1:D5) + an empty "Pivot" sheet. */
+function workbookWithData() {
+  const wb = buildDataWorkbook<Row>({ sheetName: "Data", columns: COLUMNS, rows: ROWS });
+  wb.sheets.push(new SheetModel("Pivot", wb.styles));
+  return wb;
+}
+
+const decode = (b: Uint8Array) => new TextDecoder().decode(b);
+
+/** Rebuild the recompute source from the fixture (header + records). */
+function fixtureSource(): PivotSourceData {
+  return {
+    header: ["Line", "Size", "Container", "Amount"],
+    records: ROWS.map((r) => [r.line, r.size, r.container, r.amount]),
+  };
+}
+
+describe("buildPivotTable — author a native pivot", () => {
+  it("places a flagged pivot on the target sheet, sized to the result grid", () => {
+    const wb = workbookWithData();
+    const model = buildPivotTable(wb, {
+      name: "FeesByLineSize",
+      source: { sheetName: "Data", ref: "A1:D5" },
+      rowField: 0,
+      colField: 1,
+      data: { field: 3, fn: "sum", numFmtId: "3" },
+      location: { sheetName: "Pivot", anchor: "A1" },
+    });
+    expect(model.authored).toBe(true);
+    expect(wb.sheets[1].pivotTables).toHaveLength(1);
+    // Cache items sort lexicographically → display order: CMA,SHA / 20DC,40HC.
+    expect(model.cache.fields[0].items.map((i) => (i.kind === "string" ? i.value : i.kind))).toEqual(["CMA", "SHA"]);
+    expect(model.cache.fields[1].items.map((i) => (i.kind === "string" ? i.value : i.kind))).toEqual(["20DC", "40HC"]);
+    // Measure / unused columns carry no enumerated items.
+    expect(model.cache.fields[2].items).toEqual([]);
+    expect(model.cache.fields[3].items).toEqual([]);
+    // ref spans the grid: 2 header rows + 2 data rows + grand row = 5; 1 label col + 2 size cols + grand = 4.
+    expect(model.config.ref).toBe("A1:D5");
+  });
+
+  it("rejects fields used in more than one role and out-of-range indices", () => {
+    const wb = workbookWithData();
+    const base = {
+      name: "X",
+      source: { sheetName: "Data", ref: "A1:D5" },
+      colField: 1,
+      data: { field: 3, fn: "sum" as const },
+      location: { sheetName: "Pivot", anchor: "A1" },
+    };
+    expect(() => buildPivotTable(wb, { ...base, rowField: 3 })).toThrow(/more than one role/);
+    expect(() => buildPivotTable(wb, { ...base, rowField: 9 })).toThrow(/out of range/);
+  });
+
+  it("fails loud on export when the source changed after build (stale cache)", () => {
+    const wb = workbookWithData();
+    buildPivotTable(wb, {
+      name: "Stale",
+      source: { sheetName: "Data", ref: "A1:D5" },
+      rowField: 0,
+      colField: 1,
+      data: { field: 3, fn: "sum" },
+      location: { sheetName: "Pivot", anchor: "A1" },
+    });
+    // Introduce a row-axis value the cache was not built with → encoding the
+    // records can't resolve it to a shared item, so the export must throw.
+    wb.sheets[0].set("A2", "ZZZ");
+    expect(() => exportWorkbook(wb)).toThrow(/missing from its cached shared items/);
+  });
+});
+
+describe("native pivot round-trips through the parser", () => {
+  function exportAndParse() {
+    const wb = workbookWithData();
+    buildPivotTable(wb, {
+      name: "FeesByLineSize",
+      source: { sheetName: "Data", ref: "A1:D5" },
+      rowField: 0,
+      colField: 1,
+      data: { field: 3, fn: "sum", name: "Sum of Amount", numFmtId: "3" },
+      pageFields: [],
+      location: { sheetName: "Pivot", anchor: "A1" },
+    });
+    const bytes = exportWorkbook(wb);
+    return { bytes, parsed: parseExcelBuffer(new Uint8Array(bytes).buffer), zip: unzipXlsx(new Uint8Array(bytes).buffer) };
+  }
+
+  it("reparses the pivot table definition (axes, data field, grand totals)", () => {
+    const { parsed } = exportAndParse();
+    const pivot = parsed.sheets.find((s) => s.name === "Pivot")?.pivotTables?.[0];
+    expect(pivot).toBeDefined();
+    expect(pivot!.name).toBe("FeesByLineSize");
+    expect(pivot!.cacheId).toBe(1);
+    expect(pivot!.rowFieldIndices).toEqual([0]);
+    expect(pivot!.colFieldIndices).toEqual([1]);
+    expect(pivot!.dataFields).toHaveLength(1);
+    // numFmtId is emitted on the dataField and round-trips (built-in 3 = #,##0).
+    expect(pivot!.dataFields[0]).toMatchObject({ fieldIndex: 3, subtotal: "sum", name: "Sum of Amount", numFmt: "3" });
+    expect(pivot!.display.rowGrandTotals).toBe(true);
+    expect(pivot!.display.colGrandTotals).toBe(true);
+    expect(pivot!.ref).toBe("A1:D5");
+  });
+
+  it("reparses the cache: worksheet source + sorted shared items + refreshOnLoad", () => {
+    const { parsed } = exportAndParse();
+    const cache = parsed.pivotCaches?.get(1);
+    expect(cache).toBeDefined();
+    expect(cache!.refreshOnLoad).toBe(true);
+    expect(cache!.source).toEqual({ type: "worksheet", sheetName: "Data", ref: "A1:D5" });
+    expect(cache!.fields.map((f) => f.name)).toEqual(["Line", "Size", "Container", "Amount"]);
+    expect(cache!.fields[0].items.map((i) => (i.kind === "string" ? i.value : i.kind))).toEqual(["CMA", "SHA"]);
+    expect(cache!.fields[1].items.map((i) => (i.kind === "string" ? i.value : i.kind))).toEqual(["20DC", "40HC"]);
+    // Measure / unused fields enumerate nothing.
+    expect(cache!.fields[2].items).toEqual([]);
+    expect(cache!.fields[3].items).toEqual([]);
+  });
+
+  it("the round-tripped definition recomputes to the correct cross-tab", () => {
+    const { parsed } = exportAndParse();
+    const pivot = parsed.sheets.find((s) => s.name === "Pivot")!.pivotTables![0];
+    const cache = parsed.pivotCaches!.get(1)!;
+    const grid = recomputePivot(pivot, cache, fixtureSource());
+
+    // Header rows then body. rowLabelCols = 1; data cols = 2 (20DC, 40HC) + grand.
+    const valueAt = (r: number, c: number) => {
+      const cell = grid.cells[r][c];
+      return cell.kind === "value" || cell.kind === "rowTotal" || cell.kind === "colTotal" || cell.kind === "grandTotal"
+        ? cell.value
+        : undefined;
+    };
+    // Row order CMA, SHA after the header rows.
+    const hdr = grid.headerRows;
+    // CMA row: 20DC empty (sum of no records = 0 in the engine), 40HC 70, rowTotal 70.
+    expect(valueAt(hdr, 1)).toBe(0); // CMA × 20DC
+    expect(valueAt(hdr, 2)).toBe(70); // CMA × 40HC
+    expect(valueAt(hdr, 3)).toBe(70); // CMA row total
+    // SHA row: 20DC 50, 40HC 300, rowTotal 350.
+    expect(valueAt(hdr + 1, 1)).toBe(50);
+    expect(valueAt(hdr + 1, 2)).toBe(300);
+    expect(valueAt(hdr + 1, 3)).toBe(350);
+    // Grand row: 20DC 50, 40HC 370, grand 420.
+    expect(valueAt(hdr + 2, 1)).toBe(50);
+    expect(valueAt(hdr + 2, 2)).toBe(370);
+    expect(valueAt(hdr + 2, 3)).toBe(420);
+  });
+
+  it("encodes cache records as shared-item indices (axis) + inline values (measure)", () => {
+    const { zip } = exportAndParse();
+    const records = decode(zip["xl/pivotCache/pivotCacheRecords1.xml"]);
+    expect(records).toContain('count="4"');
+    // First fixture row SHA(idx1)/40HC(idx1)/C1/100 → indices for the two axis
+    // fields, then inline string + inline number.
+    expect(records).toContain('<r><x v="1"/><x v="1"/><s v="C1"/><n v="100"/></r>');
+    // CMA(idx0)/40HC(idx1)/C4/70.
+    expect(records).toContain('<r><x v="0"/><x v="1"/><s v="C4"/><n v="70"/></r>');
+  });
+
+  it("registers content-types, workbook pivotCaches, and the full rels chain", () => {
+    const { zip } = exportAndParse();
+    const ct = decode(zip["[Content_Types].xml"]);
+    expect(ct).toContain("/xl/pivotTables/pivotTable1.xml");
+    expect(ct).toContain("/xl/pivotCache/pivotCacheDefinition1.xml");
+    expect(ct).toContain("/xl/pivotCache/pivotCacheRecords1.xml");
+
+    const wb = decode(zip["xl/workbook.xml"]);
+    expect(wb).toContain("<pivotCaches>");
+    expect(wb).toMatch(/<pivotCache cacheId="1" r:id="rId\d+"\/>/);
+
+    expect(decode(zip["xl/_rels/workbook.xml.rels"])).toContain("pivotCache/pivotCacheDefinition1.xml");
+    // The Pivot sheet (sheet 2) rels → its pivot table.
+    expect(decode(zip["xl/worksheets/_rels/sheet2.xml.rels"])).toContain("../pivotTables/pivotTable1.xml");
+    // pivotTable → cacheDefinition, cacheDefinition → records.
+    expect(decode(zip["xl/pivotTables/_rels/pivotTable1.xml.rels"])).toContain("../pivotCache/pivotCacheDefinition1.xml");
+    expect(decode(zip["xl/pivotCache/_rels/pivotCacheDefinition1.xml.rels"])).toContain("pivotCacheRecords1.xml");
+  });
+
+  it("the exported workbook re-parses without error and keeps the data sheet", () => {
+    const { parsed } = exportAndParse();
+    expect(parsed.sheets.map((s) => s.name)).toEqual(["Data", "Pivot"]);
+    // The source data survived alongside the new pivot parts.
+    const data = parsed.sheets[0];
+    const a1 = data.rows.find((r) => r.index === 1)?.cells.find((c) => c.column === 1);
+    expect(a1?.value).toBe("Line");
+  });
+});
+
+describe("page filter + count aggregation", () => {
+  it("round-trips a page (report-filter) field", () => {
+    const wb = workbookWithData();
+    buildPivotTable(wb, {
+      name: "Filtered",
+      source: { sheetName: "Data", ref: "A1:D5" },
+      rowField: 0,
+      colField: 1,
+      data: { field: 3, fn: "sum" },
+      pageFields: [2], // Container as a report filter
+      location: { sheetName: "Pivot", anchor: "A1" },
+    });
+    const bytes = exportWorkbook(wb);
+    const parsed = parseExcelBuffer(new Uint8Array(bytes).buffer);
+    const pivot = parsed.sheets[1].pivotTables![0];
+    expect(pivot.pageFieldIndices).toEqual([2]);
+    // The page field is enumerated like an axis field (it filters on items).
+    const cache = parsed.pivotCaches!.get(1)!;
+    expect(cache.fields[2].items.map((i) => (i.kind === "string" ? i.value : i.kind))).toEqual(["C1", "C2", "C3", "C4"]);
+  });
+
+  it("Count over a distinct-container roster reproduces distinct counts", () => {
+    // The app's distinct-count pivot pattern: a roster with ONE row per distinct
+    // container; COUNT of the container column = distinct container count.
+    const roster: Row[] = [
+      { line: "SHA", size: "40HC", container: "C1", amount: 0 },
+      { line: "SHA", size: "40HC", container: "C2", amount: 0 },
+      { line: "SHA", size: "20DC", container: "C3", amount: 0 },
+      { line: "CMA", size: "40HC", container: "C4", amount: 0 },
+    ];
+    const wb = buildDataWorkbook<Row>({ sheetName: "Roster", columns: COLUMNS, rows: roster });
+    wb.sheets.push(new SheetModel("Pivot", wb.styles));
+    buildPivotTable(wb, {
+      name: "ContainersByLineSize",
+      source: { sheetName: "Roster", ref: "A1:D5" },
+      rowField: 0,
+      colField: 1,
+      data: { field: 2, fn: "count" }, // count of Container
+      location: { sheetName: "Pivot", anchor: "A1" },
+    });
+    const bytes = exportWorkbook(wb);
+    const parsed = parseExcelBuffer(new Uint8Array(bytes).buffer);
+    const pivot = parsed.sheets[1].pivotTables![0];
+    const cache = parsed.pivotCaches!.get(1)!;
+    const grid = recomputePivot(pivot, cache, {
+      header: ["Line", "Size", "Container", "Amount"],
+      records: roster.map((r) => [r.line, r.size, r.container, r.amount]),
+    });
+    const hdr = grid.headerRows;
+    const num = (r: number, c: number) => {
+      const cell = grid.cells[r][c];
+      return "value" in cell ? cell.value : undefined;
+    };
+    // SHA row (second, after CMA): 20DC=1, 40HC=2, total 3.
+    expect(num(hdr + 1, 1)).toBe(1);
+    expect(num(hdr + 1, 2)).toBe(2);
+    expect(num(hdr + 1, 3)).toBe(3);
+    // Grand row: total distinct containers = 4.
+    expect(num(hdr + 2, 3)).toBe(4);
+    expect(pivot.dataFields[0].subtotal).toBe("count");
+  });
+});

package/src/pivot_builder.ts

@@ -0,0 +1,187 @@
+// =============================================================================
+// Pivot Table Builder
+// =============================================================================
+//
+// Authors a native Excel PivotTable from scratch over a worksheet range. The
+// returned model is attached to the target sheet (`sheet.pivotTables`) and
+// flagged `authored`, so `exportWorkbook` serializes it into real OOXML pivot
+// parts (see `pivot_writer.ts`).
+//
+// v1 shape (the 2D cross-tab): exactly one row field, one column field, one
+// data field, and zero or more page (report-filter) fields. The shared-item
+// order in the cache is the SAME String()-lexicographic order `pivot_recompute`
+// uses to lay out rows/columns, so the saved item indices line up with the
+// displayed order — no remapping needed in the writer.
+// =============================================================================
+
+import type { WorkbookModel } from "./workbook_model";
+import type {
+  ParsedPivotCache,
+  ParsedPivotTable,
+  PivotAggregateFn,
+  PivotCacheField,
+  PivotCacheItem,
+  PivotFieldConfig,
+} from "./ooxml_pivot_types";
+import { PivotTableModel, readSourceData } from "./pivot_model";
+import { recomputePivot, type PivotSourceData } from "./pivot_recompute";
+import { sourceValueToItem, cacheItemKey, cacheItemSortKey } from "./pivot_writer";
+import { refToRowCol, rowColToRef } from "./excel_utils";
+
+export interface PivotBuildSpec {
+  /** Pivot table name — must be unique within the workbook. */
+  name: string;
+  /** Source data range: a sheet + a range whose first row is the header. */
+  source: { sheetName: string; ref: string };
+  /** Source column index (0-based within the range) for the row axis. */
+  rowField: number;
+  /** Source column index for the column axis. */
+  colField: number;
+  /**
+   * The value field placed on the data axis. `numFmtId` is a BUILT-IN Excel
+   * number-format id (e.g. "3" = `#,##0`), not a format code — a custom code
+   * (`'#,##0" ₫"'`) would need a registered style, which v1 does not wire up.
+   */
+  data: { field: number; fn?: PivotAggregateFn; name?: string; numFmtId?: string };
+  /** Source column indices used as report (page) filters. Default none. */
+  pageFields?: number[];
+  /** Where the pivot is placed: a sheet + the top-left anchor cell. */
+  location: { sheetName: string; anchor: string };
+  /** Show the grand-total column (per-row totals). Default true. */
+  rowGrandTotals?: boolean;
+  /** Show the grand-total row (per-column totals). Default true. */
+  colGrandTotals?: boolean;
+  /** Table style name. Default "PivotStyleLight16". */
+  styleName?: string;
+}
+
+const AGG_VERB: Record<PivotAggregateFn, string> = {
+  sum: "Sum",
+  count: "Count",
+  countNums: "Count",
+  average: "Average",
+  min: "Min",
+  max: "Max",
+  product: "Product",
+};
+
+export function buildPivotTable(workbook: WorkbookModel, spec: PivotBuildSpec): PivotTableModel {
+  const target = workbook.sheets.find((s) => s.name === spec.location.sheetName);
+  if (!target) throw new Error(`buildPivotTable: target sheet "${spec.location.sheetName}" not found`);
+
+  // Read the source range. A minimal cache carries only the source coordinates;
+  // `readSourceData` reads header + records straight from the worksheet.
+  const cacheSource = { type: "worksheet" as const, sheetName: spec.source.sheetName, ref: spec.source.ref };
+  const source = readSourceData(workbook, { id: 0, source: cacheSource, fields: [], refreshOnLoad: true });
+  if (!source) throw new Error(`buildPivotTable: source range "${spec.source.ref}" on "${spec.source.sheetName}" not found`);
+
+  const fieldCount = source.header.length;
+  const pageFields = spec.pageFields ?? [];
+  validateSpec(spec, fieldCount, pageFields);
+
+  // Assign a cache id one past the highest existing pivot cache (so authored and
+  // any round-tripped pivots never collide).
+  const existing = workbook.sheets.flatMap((s) => s.pivotTables);
+  const cacheId = existing.reduce((max, p) => Math.max(max, p.cache.id), 0) + 1;
+
+  const axisFields = new Set([spec.rowField, spec.colField, ...pageFields]);
+  const cacheFields: PivotCacheField[] = source.header.map((name, i) => buildCacheField(name, i, source, axisFields.has(i)));
+  const cache: ParsedPivotCache = { id: cacheId, source: cacheSource, fields: cacheFields, refreshOnLoad: true };
+
+  const fn = spec.data.fn ?? "sum";
+  const config: ParsedPivotTable = {
+    name: spec.name,
+    cacheId,
+    ref: "A1:A1", // sized after recompute
+    firstHeaderRow: 1,
+    firstDataRow: 1,
+    firstDataCol: 1,
+    fields: buildFieldConfigs(fieldCount, spec, pageFields),
+    rowFieldIndices: [spec.rowField],
+    colFieldIndices: [spec.colField],
+    pageFieldIndices: pageFields,
+    dataFields: [
+      {
+        name: spec.data.name ?? `${AGG_VERB[fn]} of ${source.header[spec.data.field] || `field ${spec.data.field}`}`,
+        fieldIndex: spec.data.field,
+        subtotal: fn,
+        numFmt: spec.data.numFmtId,
+      },
+    ],
+    styleName: spec.styleName ?? "PivotStyleLight16",
+    display: {
+      rowGrandTotals: spec.rowGrandTotals ?? true,
+      colGrandTotals: spec.colGrandTotals ?? true,
+      showRowStripes: false,
+      showColStripes: false,
+    },
+  };
+
+  // Recompute to size the location ref and the data-offset hints. The result
+  // also seeds `model.result` so a caller can render without a second pass.
+  const grid = recomputePivot(config, cache, source);
+  const anchor = refToRowCol(spec.location.anchor);
+  if (!anchor) throw new Error(`buildPivotTable: invalid anchor "${spec.location.anchor}"`);
+  config.ref = `${spec.location.anchor}:${rowColToRef(anchor.row + grid.rows - 1, anchor.col + grid.cols - 1)}`;
+  config.firstHeaderRow = 1;
+  config.firstDataRow = grid.headerRows;
+  config.firstDataCol = grid.rowLabelCols;
+
+  const model = new PivotTableModel(config, cache, true);
+  model.result = grid;
+  target.pivotTables.push(model);
+  return model;
+}
+
+function validateSpec(spec: PivotBuildSpec, fieldCount: number, pageFields: number[]): void {
+  const inRange = (i: number) => Number.isInteger(i) && i >= 0 && i < fieldCount;
+  if (!inRange(spec.rowField)) throw new Error(`buildPivotTable: rowField ${spec.rowField} out of range (0..${fieldCount - 1})`);
+  if (!inRange(spec.colField)) throw new Error(`buildPivotTable: colField ${spec.colField} out of range (0..${fieldCount - 1})`);
+  if (!inRange(spec.data.field)) throw new Error(`buildPivotTable: data.field ${spec.data.field} out of range (0..${fieldCount - 1})`);
+  for (const p of pageFields) if (!inRange(p)) throw new Error(`buildPivotTable: pageField ${p} out of range (0..${fieldCount - 1})`);
+  const roles = [spec.rowField, spec.colField, spec.data.field, ...pageFields];
+  if (new Set(roles).size !== roles.length) {
+    throw new Error("buildPivotTable: a field cannot be used in more than one role (row/column/data/page)");
+  }
+}
+
+/** Distinct, display-sorted shared items for an axis field; type hints only for
+ *  a measure/unused column (its values inline into the cache records). */
+function buildCacheField(name: string, col: number, source: PivotSourceData, enumerate: boolean): PivotCacheField {
+  const containsNumber = source.records.some((rec) => typeof rec[col] === "number");
+  const containsDate = false;
+  if (!enumerate) return { name, items: [], numFmt: undefined, containsNumber, containsDate };
+
+  const seen = new Set<string>();
+  const items: PivotCacheItem[] = [];
+  for (const rec of source.records) {
+    const item = sourceValueToItem(rec[col]);
+    const key = cacheItemKey(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    items.push(item);
+  }
+  items.sort((a, b) => {
+    const as = cacheItemSortKey(a);
+    const bs = cacheItemSortKey(b);
+    return as < bs ? -1 : as > bs ? 1 : 0;
+  });
+  return { name, items, numFmt: undefined, containsNumber, containsDate };
+}
+
+function buildFieldConfigs(fieldCount: number, spec: PivotBuildSpec, pageFields: number[]): PivotFieldConfig[] {
+  const pageSet = new Set(pageFields);
+  const out: PivotFieldConfig[] = [];
+  for (let i = 0; i < fieldCount; i++) {
+    const axis =
+      i === spec.rowField ? "row" : i === spec.colField ? "column" : pageSet.has(i) ? "page" : i === spec.data.field ? "values" : undefined;
+    out.push({
+      axis,
+      showSubtotal: true,
+      compact: true,
+      showAll: false,
+      selectedPageItem: pageSet.has(i) ? null : undefined,
+    });
+  }
+  return out;
+}

package/src/pivot_model.ts

@@ -30,10 +30,18 @@ export class PivotTableModel {
   cache: ParsedPivotCache;
   /** Last computed result, or undefined before first recompute. */
   result: PivotResultGrid | undefined;
+  /**
+   * True when this pivot was authored from scratch (via `buildPivotTable`) and
+   * must be SERIALIZED by the writer into fresh OOXML parts. Parsed pivots leave
+   * this false — they round-trip verbatim from the original zip, so the writer
+   * skips them. The writer keys emission on this flag.
+   */
+  authored: boolean;
 
-  constructor(config: ParsedPivotTable, cache: ParsedPivotCache) {
+  constructor(config: ParsedPivotTable, cache: ParsedPivotCache, authored = false) {
     this.config = config;
     this.cache = cache;
+    this.authored = authored;
   }
 
   /**

package/src/pivot_writer.ts

@@ -0,0 +1,340 @@
+// =============================================================================
+// OOXML Pivot Table Writer
+// =============================================================================
+//
+// Serializes AUTHORED pivots (built via `pivot_builder`) into the three OOXML
+// parts Excel expects: `pivotTableN.xml`, `pivotCacheDefinitionN.xml`, and
+// `pivotCacheRecordsN.xml`. The inverse of `ooxml_pivot.ts` (the parser); the
+// two are kept format-compatible so a build → write → parse round-trip is
+// lossless for the supported subset.
+//
+// Supported subset (v1): exactly one row field, one column field, one data
+// field, and zero or more page (report-filter) fields, with grand totals. This
+// is the 2D cross-tab shape; multi-level axes and multiple data fields are not
+// emitted (the builder rejects them) so the row/col item layout stays a flat,
+// verifiable list.
+//
+// Every authored cache carries `refreshOnLoad="1"`: the cache records below are
+// a faithful snapshot of the source range, AND Excel rebuilds them from the
+// live worksheet on open, so the pivot is correct in non-refreshing viewers and
+// stays in sync after edits.
+// =============================================================================
+
+import { escapeXml } from "./excel_utils";
+import type {
+  ParsedPivotCache,
+  ParsedPivotTable,
+  PivotCacheField,
+  PivotCacheItem,
+} from "./ooxml_pivot_types";
+import type { PivotSourceRecord } from "./pivot_recompute";
+
+const MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+const REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+
+// =============================================================================
+// Shared item helpers (used by both the builder and this writer)
+// =============================================================================
+
+/** Coerce a raw source cell value to its cache-item representation. */
+export function sourceValueToItem(
+  v: string | number | boolean | null | undefined,
+): PivotCacheItem {
+  if (v === undefined || v === null || v === "") return { kind: "missing" };
+  if (typeof v === "number") return { kind: "number", value: v };
+  if (typeof v === "boolean") return { kind: "boolean", value: v };
+  return { kind: "string", value: v };
+}
+
+/** Canonical key for de-duplicating / looking up a cache item. */
+export function cacheItemKey(item: PivotCacheItem): string {
+  switch (item.kind) {
+    case "missing":
+      return "m:";
+    case "number":
+      return `n:${item.value}`;
+    case "boolean":
+      return `b:${item.value}`;
+    case "string":
+      return `s:${item.value}`;
+    case "date":
+      return `d:${item.value}`;
+    case "error":
+      return `e:${item.value}`;
+  }
+}
+
+/** The label used for ordering — matches `pivot_recompute`'s String()-lexicographic
+ *  tuple sort so the cache item order equals the pivot's displayed row/col order. */
+export function cacheItemSortKey(item: PivotCacheItem): string {
+  return item.kind === "missing" ? "" : String(item.value);
+}
+
+/** Which fields sit on an axis (row/col/page) — i.e. carry enumerated shared
+ *  items and reference them by index in the cache records. The data/unused
+ *  columns inline their values instead. */
+export function enumerateFlags(table: ParsedPivotTable, fieldCount: number): boolean[] {
+  const axis = new Set([...table.rowFieldIndices, ...table.colFieldIndices, ...table.pageFieldIndices]);
+  return Array.from({ length: fieldCount }, (_, i) => axis.has(i));
+}
+
+// =============================================================================
+// pivotCacheRecords
+// =============================================================================
+
+/**
+ * One `<r>` per source row. A field carried on an axis (row/col/page) is
+ * "enumerated": its cells are written as `<x v="i"/>` indices into the cache
+ * field's shared items. Other fields (the measure, unused columns) are written
+ * inline (`<n>`, `<s>`, `<b>`, `<m/>`).
+ */
+export function buildPivotCacheRecordsXml(
+  records: PivotSourceRecord[],
+  cache: ParsedPivotCache,
+  enumerate: boolean[],
+): string {
+  // index map per enumerated field: item key → position in shared items.
+  const indexMaps = cache.fields.map((f, i) => {
+    if (!enumerate[i]) return undefined;
+    const m = new Map<string, number>();
+    f.items.forEach((item, idx) => m.set(cacheItemKey(item), idx));
+    return m;
+  });
+
+  const rows = records.map((rec) => {
+    const cells = cache.fields.map((_f, i) => {
+      const item = sourceValueToItem(rec[i]);
+      const map = indexMaps[i];
+      if (map) {
+        const idx = map.get(cacheItemKey(item));
+        // A value absent from the shared items means the cache is stale (the
+        // source range changed after buildPivotTable) or inconsistent. Fail loud
+        // rather than emit a dangling index or silently bucket the value as blank.
+        if (idx === undefined) {
+          throw new Error(
+            `buildPivotCacheRecordsXml: value ${JSON.stringify(rec[i])} for field "${cache.fields[i].name}" is missing from its cached shared items`,
+          );
+        }
+        return `<x v="${idx}"/>`;
+      }
+      return inlineRecordCell(item);
+    });
+    return `<r>${cells.join("")}</r>`;
+  });
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+    `<pivotCacheRecords xmlns="${MAIN_NS}" xmlns:r="${REL_NS}" count="${records.length}">` +
+    rows.join("") +
+    `</pivotCacheRecords>`
+  );
+}
+
+function inlineRecordCell(item: PivotCacheItem): string {
+  switch (item.kind) {
+    case "missing":
+      return "<m/>";
+    case "number":
+      return `<n v="${item.value}"/>`;
+    case "boolean":
+      return `<b v="${item.value ? 1 : 0}"/>`;
+    case "date":
+      return `<d v="${escapeXml(item.value)}"/>`;
+    case "error":
+      return `<e v="${escapeXml(item.value)}"/>`;
+    case "string":
+      return `<s v="${escapeXml(item.value)}"/>`;
+  }
+}
+
+// =============================================================================
+// pivotCacheDefinition
+// =============================================================================
+
+export function buildPivotCacheDefinitionXml(
+  cache: ParsedPivotCache,
+  enumerate: boolean[],
+  recordCount: number,
+  recordsRelId: string,
+): string {
+  if (cache.source.type !== "worksheet") {
+    throw new Error("buildPivotCacheDefinitionXml: only worksheet sources are supported");
+  }
+  const src = cache.source;
+  const fields = cache.fields
+    .map((f, i) => cacheFieldXml(f, enumerate[i]))
+    .join("");
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+    `<pivotCacheDefinition xmlns="${MAIN_NS}" xmlns:r="${REL_NS}" r:id="${recordsRelId}"` +
+    ` refreshOnLoad="1" refreshedBy="Lotics" createdVersion="6" refreshedVersion="6"` +
+    ` minRefreshableVersion="3" recordCount="${recordCount}">` +
+    `<cacheSource type="worksheet">` +
+    `<worksheetSource ref="${escapeXml(src.ref)}" sheet="${escapeXml(src.sheetName)}"/>` +
+    `</cacheSource>` +
+    `<cacheFields count="${cache.fields.length}">${fields}</cacheFields>` +
+    `</pivotCacheDefinition>`
+  );
+}
+
+function cacheFieldXml(field: PivotCacheField, enumerate: boolean): string {
+  const name = `name="${escapeXml(field.name)}" numFmtId="0"`;
+  if (!enumerate) {
+    // Measure / unused column: no enumerated items, just type hints. Excel
+    // refreshes the rest from the worksheet source.
+    const flags =
+      `containsBlank="${field.items.length === 0 ? 0 : 1}"` +
+      (field.containsNumber ? ` containsString="0" containsNumber="1"` : "");
+    return `<cacheField ${name}><sharedItems ${flags}/></cacheField>`;
+  }
+  const items = field.items.map(sharedItemXml).join("");
+  const hasString = field.items.some((i) => i.kind === "string");
+  const hasNumber = field.items.some((i) => i.kind === "number");
+  const hasBlank = field.items.some((i) => i.kind === "missing");
+  const attrs =
+    `count="${field.items.length}"` +
+    (hasBlank ? ` containsBlank="1"` : "") +
+    (hasNumber && !hasString ? ` containsString="0" containsNumber="1"` : "");
+  return `<cacheField ${name}><sharedItems ${attrs}>${items}</sharedItems></cacheField>`;
+}
+
+function sharedItemXml(item: PivotCacheItem): string {
+  switch (item.kind) {
+    case "missing":
+      return `<m/>`;
+    case "number":
+      return `<n v="${item.value}"/>`;
+    case "boolean":
+      return `<b v="${item.value ? 1 : 0}"/>`;
+    case "date":
+      return `<d v="${escapeXml(item.value)}"/>`;
+    case "error":
+      return `<e v="${escapeXml(item.value)}"/>`;
+    case "string":
+      return `<s v="${escapeXml(item.value)}"/>`;
+  }
+}
+
+// =============================================================================
+// pivotTable
+// =============================================================================
+
+const SUBTOTAL_FN_TO_ENUM: Record<string, string> = {
+  sum: "sum",
+  count: "count",
+  countNums: "countNums",
+  average: "average",
+  min: "min",
+  max: "max",
+  product: "product",
+};
+
+/**
+ * Serialize the pivot table definition. The axis fields (row/col/page) carry a
+ * `<pivotField>` with an `<items>` list; the data and unused fields are emitted
+ * without items. Axis roles are read from `table`, so no enumerate hint is needed.
+ */
+export function buildPivotTableXml(
+  table: ParsedPivotTable,
+  cache: ParsedPivotCache,
+): string {
+  const rowField = table.rowFieldIndices[0];
+  const colField = table.colFieldIndices[0];
+  if (rowField === undefined || colField === undefined) {
+    throw new Error("buildPivotTableXml: a row field and a column field are required");
+  }
+  const pageSet = new Set(table.pageFieldIndices);
+
+  const pivotFields = cache.fields
+    .map((f, i) => {
+      const onAxis =
+        i === rowField ? "axisRow" : i === colField ? "axisCol" : pageSet.has(i) ? "axisPage" : undefined;
+      if (onAxis) return axisPivotFieldXml(onAxis, f.items.length);
+      if (table.dataFields.some((d) => d.fieldIndex === i)) {
+        return `<pivotField dataField="1" showAll="0"/>`;
+      }
+      return `<pivotField showAll="0"/>`;
+    })
+    .join("");
+
+  const rowCount = cache.fields[rowField].items.length;
+  const colCount = cache.fields[colField].items.length;
+  // A bottom grand-total ROW is a colGrandTotals; a right grand-total COLUMN is
+  // a rowGrandTotals (OOXML's naming is "grand totals FOR rows/columns").
+  const rowItems = axisItemsXml("rowItems", rowCount, table.display.colGrandTotals);
+  const colItems = axisItemsXml("colItems", colCount, table.display.rowGrandTotals);
+
+  const pageFieldsXml = table.pageFieldIndices.length
+    ? `<pageFields count="${table.pageFieldIndices.length}">` +
+      table.pageFieldIndices
+        .map((fld) => {
+          const sel = table.fields[fld]?.selectedPageItem;
+          const item = sel === null || sel === undefined ? "" : ` item="${sel}"`;
+          return `<pageField fld="${fld}"${item} hier="-1"/>`;
+        })
+        .join("") +
+      `</pageFields>`
+    : "";
+
+  const dataFieldsXml =
+    `<dataFields count="${table.dataFields.length}">` +
+    table.dataFields
+      .map((d) => {
+        const fn = SUBTOTAL_FN_TO_ENUM[d.subtotal] ?? "sum";
+        const sub = fn === "sum" ? "" : ` subtotal="${fn}"`;
+        const numFmt = d.numFmt ? ` numFmtId="${escapeXml(d.numFmt)}"` : "";
+        return `<dataField name="${escapeXml(d.name)}" fld="${d.fieldIndex}"${sub} baseField="0" baseItem="0"${numFmt}/>`;
+      })
+      .join("") +
+    `</dataFields>`;
+
+  const style =
+    `<pivotTableStyleInfo name="${escapeXml(table.styleName ?? "PivotStyleLight16")}"` +
+    ` showRowHeaders="1" showColHeaders="1"` +
+    ` showRowStripes="${table.display.showRowStripes ? 1 : 0}"` +
+    ` showColStripes="${table.display.showColStripes ? 1 : 0}" showLastColumn="1"/>`;
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+    `<pivotTableDefinition xmlns="${MAIN_NS}" xmlns:r="${REL_NS}"` +
+    ` name="${escapeXml(table.name)}" cacheId="${table.cacheId}"` +
+    ` applyNumberFormats="0" applyBorderFormats="0" applyFontFormats="0"` +
+    ` applyPatternFormats="0" applyAlignmentFormats="0" applyWidthHeightFormats="1"` +
+    ` dataCaption="Values" updatedVersion="6" minRefreshableVersion="3"` +
+    ` useAutoFormatting="1" itemPrintTitles="1" createdVersion="6" indent="0"` +
+    ` outline="1" outlineData="1" multipleFieldFilters="0"` +
+    ` rowGrandTotals="${table.display.rowGrandTotals ? 1 : 0}"` +
+    ` colGrandTotals="${table.display.colGrandTotals ? 1 : 0}">` +
+    // ref spans the body grid only; page-filter rows (if any) are laid out by
+    // Excel above it on refresh, so the location stays body-relative + consistent.
+    `<location ref="${escapeXml(table.ref)}" firstHeaderRow="${table.firstHeaderRow}"` +
+    ` firstDataRow="${table.firstDataRow}" firstDataCol="${table.firstDataCol}"/>` +
+    `<pivotFields count="${cache.fields.length}">${pivotFields}</pivotFields>` +
+    `<rowFields count="1"><field x="${rowField}"/></rowFields>` +
+    rowItems +
+    `<colFields count="1"><field x="${colField}"/></colFields>` +
+    colItems +
+    pageFieldsXml +
+    dataFieldsXml +
+    style +
+    `</pivotTableDefinition>`
+  );
+}
+
+/** A row/col axis field: items listed in shared-item order + a subtotal slot. */
+function axisPivotFieldXml(axis: string, itemCount: number): string {
+  const items: string[] = [];
+  for (let i = 0; i < itemCount; i++) items.push(`<item x="${i}"/>`);
+  items.push(`<item t="default"/>`);
+  return `<pivotField axis="${axis}" showAll="0"><items count="${items.length}">${items.join("")}</items></pivotField>`;
+}
+
+/** `<rowItems>`/`<colItems>`: one `<i>` per shared item (display order = shared
+ *  order, since the cache is pre-sorted) plus a trailing grand-total `<i>`. */
+function axisItemsXml(element: "rowItems" | "colItems", itemCount: number, grandTotal: boolean): string {
+  const items: string[] = [];
+  for (let i = 0; i < itemCount; i++) items.push(`<i><x v="${i}"/></i>`);
+  if (grandTotal) items.push(`<i t="grand"><x/></i>`);
+  return `<${element} count="${items.length}">${items.join("")}</${element}>`;
+}

package/src/xlsx_writer.ts

@@ -12,8 +12,15 @@ import type { WorkbookModel, SheetModel, CellModel } from "./workbook_model";
 import type { CellStyle, RichTextPart, RichTextFont } from "./types";
 import type { ParsedChart, ParsedTable, ParsedDrawing, ChartType, ChartSeries } from "./ooxml_chart_types";
 import type { ParsedConditionalFormat, ParsedCfStyle } from "./excel_cf_types";
-import { rowColToRef, refToRowCol, colNumToLetters } from "./excel_utils";
+import { rowColToRef, refToRowCol, colNumToLetters, escapeXml } from "./excel_utils";
 import { hexToArgb, hexToOoxmlRgb } from "./ooxml_color";
+import { readSourceData } from "./pivot_model";
+import {
+  buildPivotCacheDefinitionXml,
+  buildPivotCacheRecordsXml,
+  buildPivotTableXml,
+  enumerateFlags,
+} from "./pivot_writer";
 
 // =============================================================================
 // Pivot round-trip helpers
@@ -183,6 +190,78 @@ function pivotContentTypeFor(path: string): string | undefined {
   return undefined;
 }
 
+const REL_BASE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+
+function relsXml(rels: { id: string; type: string; target: string }[]): string {
+  return (
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+    `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">\n` +
+    rels.map((r) => `<Relationship Id="${r.id}" Type="${r.type}" Target="${escapeXml(r.target)}"/>`).join("\n") +
+    `\n</Relationships>`
+  );
+}
+
+/**
+ * Serialize every AUTHORED pivot (built via `buildPivotTable`) into fresh OOXML
+ * parts written straight into `entries`, and return the cross-reference snapshot
+ * the regenerated workbook/sheet rels + content-types consume (same shape the
+ * round-trip path produces). Parsed/round-tripped pivots are skipped — they pass
+ * through verbatim. `startFileIndex` is the first pivotTableN/cacheN suffix,
+ * past any round-tripped pivot files, so paths never collide.
+ */
+function emitAuthoredPivots(
+  workbook: WorkbookModel,
+  entries: Record<string, Uint8Array>,
+  startFileIndex: number,
+): PivotRoundTripInfo {
+  const info: PivotRoundTripInfo = {
+    cachesByWorkbook: new Map(),
+    pivotTablesBySheetIndex: new Map(),
+    pivotXmlPaths: [],
+  };
+  let n = startFileIndex;
+  for (let i = 0; i < workbook.sheets.length; i++) {
+    for (const model of workbook.sheets[i].pivotTables) {
+      if (!model.authored) continue;
+      const idx = n++;
+      const enumerate = enumerateFlags(model.config, model.cache.fields.length);
+      const records = readSourceData(workbook, model.cache)?.records ?? [];
+
+      const cacheDefPath = `xl/pivotCache/pivotCacheDefinition${idx}.xml`;
+      const recordsPath = `xl/pivotCache/pivotCacheRecords${idx}.xml`;
+      const tablePath = `xl/pivotTables/pivotTable${idx}.xml`;
+
+      entries[cacheDefPath] = strToU8(buildPivotCacheDefinitionXml(model.cache, enumerate, records.length, "rId1"));
+      entries[`xl/pivotCache/_rels/pivotCacheDefinition${idx}.xml.rels`] = strToU8(
+        relsXml([{ id: "rId1", type: `${REL_BASE}/pivotCacheRecords`, target: `pivotCacheRecords${idx}.xml` }]),
+      );
+      entries[recordsPath] = strToU8(buildPivotCacheRecordsXml(records, model.cache, enumerate));
+      entries[tablePath] = strToU8(buildPivotTableXml(model.config, model.cache));
+      entries[`xl/pivotTables/_rels/pivotTable${idx}.xml.rels`] = strToU8(
+        relsXml([{ id: "rId1", type: `${REL_BASE}/pivotCacheDefinition`, target: `../pivotCache/pivotCacheDefinition${idx}.xml` }]),
+      );
+
+      info.cachesByWorkbook.set(model.cache.id, `pivotCache/pivotCacheDefinition${idx}.xml`);
+      const list = info.pivotTablesBySheetIndex.get(i) ?? [];
+      list.push(`../pivotTables/pivotTable${idx}.xml`);
+      info.pivotTablesBySheetIndex.set(i, list);
+      info.pivotXmlPaths.push(tablePath, cacheDefPath, recordsPath);
+    }
+  }
+  return info;
+}
+
+function mergePivotInfo(a: PivotRoundTripInfo, b: PivotRoundTripInfo): PivotRoundTripInfo {
+  const cachesByWorkbook = new Map(a.cachesByWorkbook);
+  for (const [k, v] of b.cachesByWorkbook) cachesByWorkbook.set(k, v);
+  const pivotTablesBySheetIndex = new Map<number, string[]>();
+  for (const [k, v] of a.pivotTablesBySheetIndex) pivotTablesBySheetIndex.set(k, [...v]);
+  for (const [k, v] of b.pivotTablesBySheetIndex) {
+    pivotTablesBySheetIndex.set(k, [...(pivotTablesBySheetIndex.get(k) ?? []), ...v]);
+  }
+  return { cachesByWorkbook, pivotTablesBySheetIndex, pivotXmlPaths: [...a.pivotXmlPaths, ...b.pivotXmlPaths] };
+}
+
 // =============================================================================
 // Main export function
 // =============================================================================
@@ -244,11 +323,14 @@ export function exportWorkbook(
     : buildStylesXml(workbook);
   if (!stylesPassthrough) entries["xl/styles.xml"] = strToU8(stylesResult.xml);
 
-  // Pivot round-trip: read original workbook.xml + sheet rels to recover the
-  // (cacheId → cacheDefinition path) and (sheet → pivotTable paths) mappings.
-  // The pivot xml files themselves pass through originalZip; we only need to
-  // re-emit the cross-references in the regenerated parts.
-  const pivotInfo = extractPivotRoundTripInfo(originalZip);
+  // Pivot cross-references. Two sources feed the regenerated workbook/sheet rels
+  // + content-types: pivots ROUND-TRIPPED from `originalZip` (their xml passes
+  // through verbatim) and pivots AUTHORED in the model (serialized fresh here,
+  // straight into `entries`).
+  const roundTripInfo = extractPivotRoundTripInfo(originalZip);
+  const authoredStartIndex =
+    roundTripInfo.pivotXmlPaths.filter((p) => p.startsWith("xl/pivotTables/")).length + 1;
+  const pivotInfo = mergePivotInfo(roundTripInfo, emitAuthoredPivots(workbook, entries, authoredStartIndex));
 
   // Build workbook.xml
   entries["xl/workbook.xml"] = strToU8(buildWorkbookXml(workbook, pivotInfo));
@@ -1539,11 +1621,3 @@ function dataUrlToBytes(dataUrl: string): Uint8Array | null {
 // Helpers
 // =============================================================================
 
-function escapeXml(s: string): string {
-  return s
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}