@particle-academy/holy-sheet 2.3.0 → 2.4.0

package/dist/index.cjs

@@ -133,16 +133,16 @@ function allStringish(sample) {
 
 // src/helpers/array-builder.ts
 var ArrayBuilder = {
-  build(rows, headers = null, sheetName = "Sheet 1", options = {}) {
+  build(rows, headers = null, sheetName2 = "Sheet 1", options = {}) {
     let hdrs = headers;
     let data = rows;
     if (hdrs === null) {
-      if (rows.length === 0) return wrap([], [], sheetName, options);
+      if (rows.length === 0) return wrap([], [], sheetName2, options);
       hdrs = (rows[0] ?? []).map((v) => String(v));
       data = rows.slice(1);
     }
     const columns = inferColumns(data, hdrs, options);
-    return wrap(columns, data, sheetName, options);
+    return wrap(columns, data, sheetName2, options);
   }
 };
 function inferColumns(rows, headers, options) {
@@ -151,8 +151,8 @@ function inferColumns(rows, headers, options) {
     return Inference.detect(columnValues, String(headerName), options);
   });
 }
-function wrap(columns, rows, sheetName, options) {
-  const sheet = { name: sheetName, columns, rows };
+function wrap(columns, rows, sheetName2, options) {
+  const sheet = { name: sheetName2, columns, rows };
   if (options.theme !== void 0) sheet.theme = options.theme;
   if (options.totals && typeof options.totals === "object") sheet.totals = options.totals;
   if (options.frozenRows !== void 0) sheet.frozenRows = Math.trunc(Number(options.frozenRows));
@@ -165,16 +165,16 @@ var CsvBuilder = {
   build(csv, options = {}) {
     const delimiter = options.delimiter ?? ",";
     const enclosure = options.enclosure ?? '"';
-    const sheetName = options.sheetName ?? "Sheet 1";
+    const sheetName2 = options.sheetName ?? "Sheet 1";
     const rows = parseRows(csv, delimiter, enclosure);
     if (rows.length === 0) {
-      return { sheets: [{ name: sheetName, columns: [], rows: [] }] };
+      return { sheets: [{ name: sheetName2, columns: [], rows: [] }] };
     }
     const headers = rows[0].map((v) => String(v));
     const dataRows = rows.slice(1).map(
       (row) => row.map((cell) => isNumericString(cell) ? numericStringToNumber(cell) : cell)
     );
-    return ArrayBuilder.build(dataRows, headers, sheetName, options);
+    return ArrayBuilder.build(dataRows, headers, sheetName2, options);
   }
 };
 function parseRows(csv, delimiter, quote) {
@@ -721,6 +721,7 @@ var ERR_REF = "#REF!";
 var ERR_NAME = "#NAME?";
 var ERR_DIV0 = "#DIV/0!";
 var ERR_CIRC = "#CIRC!";
+var SHEET_QUALIFIER = "('(?:[^']|'')+'|[A-Za-z_][A-Za-z0-9_.]*)!";
 var LinterError = class extends Error {
   constructor(errorCode) {
     super(errorCode);
@@ -731,9 +732,16 @@ var FormulaLinter = class {
   constructor() {
     this.index = /* @__PURE__ */ new Map();
     this.cache = /* @__PURE__ */ new Map();
+    /**
+     * Every sheet name, keyed by its lower-cased form. Excel matches sheet names
+     * without regard to case, and a reference to a sheet that is not here is
+     * `#REF!` rather than a range of blanks.
+     */
+    this.sheetNames = /* @__PURE__ */ new Map();
   }
   lint(schema) {
     const workbook = new Normalizer().normalize(schema);
+    this.sheetNames = new Map(workbook.sheets.map((sheet) => [sheet.name.toLowerCase(), sheet.name]));
     this.index = this.buildIndex(workbook);
     this.cache = /* @__PURE__ */ new Map();
     const issues = [];
@@ -809,6 +817,24 @@ var FormulaLinter = class {
         tokens.push({ type: "STRING", value });
         continue;
       }
+      if (ch === "'") {
+        const start = i;
+        i++;
+        for (; ; ) {
+          if (i >= len) throw new LinterError(ERR_NAME);
+          if (src[i] === "'") {
+            if (i + 1 < len && src[i + 1] === "'") {
+              i += 2;
+              continue;
+            }
+            i++;
+            break;
+          }
+          i++;
+        }
+        tokens.push({ type: "SHEET", value: src.slice(start, i) });
+        continue;
+      }
       if (isAlpha(ch) || ch === "_" || ch === "$") {
         const start = i;
         while (i < len && (isAlnum(src[i]) || src[i] === "_" || src[i] === "$" || src[i] === ".")) i++;
@@ -926,16 +952,18 @@ var FormulaLinter = class {
       c.pos++;
       return tok.value;
     }
-    if (tok.type === "IDENT") {
+    if (tok.type === "SHEET" || tok.type === "IDENT") {
       const next = c.tokens[c.pos + 1];
       const next2 = c.tokens[c.pos + 2];
       if (next && next.type === "OP" && next.value === "!" && next2 && next2.type === "IDENT") {
-        const sheetName = this.cleanSheetName(tok.value);
+        const sheetName2 = this.sheetNames.get(this.cleanSheetName(tok.value).toLowerCase());
+        if (sheetName2 === void 0) throw new LinterError(ERR_REF);
         c.pos += 2;
         const startTok = c.tokens[c.pos].value;
         c.pos++;
-        return this.resolveRefOrRange(startTok, sheetName, c, stack);
+        return this.resolveRefOrRange(startTok, sheetName2, c, stack);
       }
+      if (tok.type === "SHEET") throw new LinterError(ERR_NAME);
       if (next && next.type === "OP" && next.value === "(") {
         const name = tok.value.toUpperCase();
         c.pos += 2;
@@ -980,9 +1008,13 @@ var FormulaLinter = class {
     const r = ref.replace(/\$/g, "").toUpperCase();
     return /^[A-Z]+\d+$/.test(r) ? r : null;
   }
+  /**
+   * Unwrap the single quotes Excel puts around a sheet name that needs them,
+   * and turn its doubled quote back into one: 'Q3 ''Final''' is Q3 'Final'.
+   */
   cleanSheetName(name) {
     if (name.length >= 2 && name[0] === "'" && name[name.length - 1] === "'") {
-      return name.slice(1, -1);
+      return name.slice(1, -1).split("''").join("'");
     }
     return name;
   }
@@ -1150,7 +1182,7 @@ var FormulaLinter = class {
       case ERR_VALUE:
         return this.hintValue(formula, sheet);
       case ERR_REF:
-        return "A cell reference points to a cell that doesn't exist in the workbook. Check column letters and row numbers.";
+        return this.hintRef(formula);
       case ERR_NAME:
         return "The formula references an unknown function or has a syntax error. Holy Sheet supports: SUM, AVERAGE, COUNT, COUNTA, MIN, MAX, IF, ROUND, ABS, LEN, UPPER, LOWER, CONCAT.";
       case ERR_DIV0:
@@ -1161,20 +1193,29 @@ var FormulaLinter = class {
         return "Formula evaluation failed.";
     }
   }
+  hintRef(formula) {
+    for (const m of formula.matchAll(new RegExp(SHEET_QUALIFIER, "g"))) {
+      const name = this.cleanSheetName(m[1]);
+      if (!this.sheetNames.has(name.toLowerCase())) {
+        return `The formula refers to a sheet named '${name}', and this workbook has no such sheet. Its sheets are: ${[...this.sheetNames.values()].join(", ")}. Quote a name that contains spaces or punctuation: 'My Sheet'!A1.`;
+      }
+    }
+    return "A cell reference points to a cell that doesn't exist in the workbook. Check column letters and row numbers.";
+  }
   hintValue(formula, sheet) {
-    const re = /(?:([A-Za-z][A-Za-z0-9_]*)!)?\$?([A-Z]+)\$?(\d+)/gi;
+    const re = new RegExp(`(?:${SHEET_QUALIFIER})?\\$?([A-Z]+)\\$?(\\d+)`, "gi");
     const offenders = [];
     for (const m of formula.matchAll(re)) {
-      const sheetName = m[1] ? m[1] : sheet;
+      const sheetName2 = m[1] ? this.sheetNames.get(this.cleanSheetName(m[1]).toLowerCase()) ?? this.cleanSheetName(m[1]) : sheet;
       const a1 = m[2].toUpperCase() + m[3];
-      const key = sheetName + "!" + a1;
+      const key = sheetName2 + "!" + a1;
       const cell = this.index.get(key);
       if (!cell) continue;
       const value = this.cache.has(key) ? this.cache.get(key) : cell.formula !== null ? null : cell.value;
       if (typeof value === "string" && !isNumericString(value) && value !== "") {
         const row = parseInt(m[3], 10);
         const col = m[2];
-        const next = sheetName + "!" + col.toUpperCase() + (row + 1);
+        const next = sheetName2 + "!" + col.toUpperCase() + (row + 1);
         const nextCell = this.index.get(next);
         let suggestion = "";
         if (nextCell && isNumericString(nextCell.value)) {
@@ -2390,7 +2431,7 @@ var OdsStyles = class {
       }
     }
     const parts = childrenIn(el2, NS.NUMBER);
-    const has = (local) => parts.some((p) => p.name === local);
+    const has2 = (local) => parts.some((p) => p.name === local);
     const number = parts.find((p) => p.name === "number");
     let decimals = null;
     if (number) {
@@ -2399,7 +2440,7 @@ var OdsStyles = class {
     }
     switch (el2.name) {
       case "number-style": {
-        if (has("scientific-number") || has("fraction")) return null;
+        if (has2("scientific-number") || has2("fraction")) return null;
         for (const text of parts.filter((p) => p.name === "text")) {
           const iso = currencyCode(ownText(text).replace(/[-()"\u00A0]/g, ""));
           if (iso !== null) return { displayFormat: "currency", decimals: decimals ?? 0, currency: iso };
@@ -2417,7 +2458,7 @@ var OdsStyles = class {
         return out;
       }
       case "date-style":
-        return ["hours", "minutes", "seconds", "am-pm"].some(has) ? { displayFormat: "datetime" } : { displayFormat: "date" };
+        return ["hours", "minutes", "seconds", "am-pm"].some(has2) ? { displayFormat: "datetime" } : { displayFormat: "date" };
       case "time-style":
         return { displayFormat: "datetime" };
       case "text-style":
@@ -2484,11 +2525,11 @@ function currencyCode(symbol) {
 // src/reader/ods/ods-text.ts
 var SKIPPED = /* @__PURE__ */ new Set(["annotation", "note"]);
 function paragraphs(node) {
-  const lines = [];
+  const lines2 = [];
   for (const c of node.children) {
-    if (c.ns === NS.TEXT && (c.name === "p" || c.name === "h")) lines.push(paragraph(c));
+    if (c.ns === NS.TEXT && (c.name === "p" || c.name === "h")) lines2.push(paragraph(c));
   }
-  return lines.length === 0 ? null : lines.join("\n");
+  return lines2.length === 0 ? null : lines2.join("\n");
 }
 function paragraph(p) {
   const state = { out: "", ignoreSpace: true };
@@ -3751,6 +3792,778 @@ function gmDateZ() {
   return (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
 }
 
+// src/ops/php.ts
+function isArr(value) {
+  return typeof value === "object" && value !== null;
+}
+function has(value, key) {
+  return isArr(value) && Object.prototype.hasOwnProperty.call(value, key) && value[key] !== void 0;
+}
+function get(value, key) {
+  return has(value, key) ? value[key] ?? null : null;
+}
+function isEmptyArr(value) {
+  return isArr(value) && Object.keys(value).every((k) => value[k] === void 0);
+}
+function valuesOf(value) {
+  if (Array.isArray(value)) return value.slice();
+  if (isArr(value)) return Object.keys(value).filter((k) => value[k] !== void 0).map((k) => value[k]);
+  return [];
+}
+function entriesOf(value) {
+  if (Array.isArray(value)) return value.map((item, i) => [String(i), item]);
+  if (isArr(value)) return Object.keys(value).filter((k) => value[k] !== void 0).map((k) => [k, value[k]]);
+  return [];
+}
+function phpInt2(value) {
+  if (value === null || value === void 0) return 0;
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (typeof value === "number") return Number.isFinite(value) ? Math.trunc(value) || 0 : 0;
+  if (typeof value === "string") {
+    const m = /^[ \t\n\r\v\f]*[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?/.exec(value);
+    if (!m) return 0;
+    const n = Number(m[0].trim());
+    return Number.isFinite(n) ? Math.trunc(n) || 0 : 0;
+  }
+  if (isArr(value)) return isEmptyArr(value) ? 0 : 1;
+  return 0;
+}
+function phpString(value) {
+  if (value === null || value === void 0 || value === false) return "";
+  if (value === true) return "1";
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  if (isArr(value)) return "Array";
+  return String(value);
+}
+function asciiUpper(value) {
+  return value.replace(/[a-z]+/g, (s) => s.toUpperCase());
+}
+function parseAddress(address) {
+  const m = /^([A-Z]+)(\d+)$/.exec(asciiUpper(address.replace(/^[ \t\n\r\v\0]+|[ \t\n\r\v\0]+$/g, "")));
+  if (!m) return null;
+  return [CellAddress.index(m[1]), parseInt(m[2], 10)];
+}
+var letter = CellAddress.letter;
+
+// src/ops/sheet-reducer.ts
+var SheetReducer = {
+  /** Sheet keys the granular ops address. A sheet with any other key is authored form. */
+  CELL_FORM_KEYS: ["name", "cells", "mergedRegions", "columnWidths", "frozenRows", "frozenCols"],
+  applyAll(schema, ops) {
+    for (const op of ops) {
+      schema = SheetReducer.apply(schema, op);
+    }
+    return schema;
+  },
+  apply(schema, op) {
+    const type = get(op, "type");
+    if (type === "set_workbook") {
+      return isArr(get(op, "data")) ? op.data : schema;
+    }
+    if (type === "set_meta") {
+      const out = { ...schema };
+      if (get(op, "meta") === null) {
+        delete out["meta"];
+      } else {
+        out["meta"] = op.meta;
+      }
+      return out;
+    }
+    const sheets = isArr(get(schema, "sheets")) ? valuesOf(schema.sheets) : [];
+    if (type === "add_sheet") {
+      if (!isArr(get(op, "sheet"))) {
+        return schema;
+      }
+      const index = Math.max(0, Math.min(sheets.length, phpInt2(get(op, "index") ?? sheets.length)));
+      sheets.splice(index, 0, op.sheet);
+      return { ...schema, sheets };
+    }
+    const at2 = find(sheets, phpString(get(op, "sheet") ?? ""));
+    if (at2 === null) {
+      return schema;
+    }
+    switch (type) {
+      case "remove_sheet":
+        sheets.splice(at2, 1);
+        break;
+      case "rename_sheet":
+        sheets[at2] = { ...sheets[at2], name: phpString(get(op, "name") ?? sheets[at2].name) };
+        break;
+      case "move_sheet": {
+        const [moved] = sheets.splice(at2, 1);
+        const to = Math.max(0, Math.min(sheets.length, phpInt2(get(op, "toIndex") ?? at2)));
+        sheets.splice(to, 0, moved);
+        break;
+      }
+      case "replace_sheet":
+        if (isArr(get(op, "data"))) {
+          sheets[at2] = op.data;
+        }
+        break;
+      case "set_merged_regions":
+        sheets[at2] = setOrUnset(sheets[at2], "mergedRegions", get(op, "mergedRegions") ?? [], EMPTY);
+        break;
+      case "set_column_widths":
+        sheets[at2] = setOrUnset(sheets[at2], "columnWidths", get(op, "columnWidths") ?? [], EMPTY);
+        break;
+      case "set_frozen":
+        sheets[at2] = setOrUnset(sheets[at2], "frozenRows", phpInt2(get(op, "rows") ?? 0), 0);
+        sheets[at2] = setOrUnset(sheets[at2], "frozenCols", phpInt2(get(op, "cols") ?? 0), 0);
+        break;
+      case "set_cell":
+        sheets[at2] = setCell(sheets[at2], op);
+        break;
+      case "set_range":
+        sheets[at2] = setRange(sheets[at2], op);
+        break;
+      case "clear_cell": {
+        const address = asciiUpper(phpString(get(op, "address") ?? ""));
+        const cells = sheets[at2].cells;
+        if (isArr(cells) && !Array.isArray(cells) && has(cells, address)) {
+          const copy = { ...cells };
+          delete copy[address];
+          sheets[at2] = { ...sheets[at2], cells: copy };
+        }
+        break;
+      }
+      case "insert_rows":
+        sheets[at2] = shiftRows(sheets[at2], phpInt2(get(op, "at") ?? 0), Math.max(0, phpInt2(get(op, "count") ?? 0)));
+        break;
+      case "delete_rows":
+        sheets[at2] = shiftRows(sheets[at2], phpInt2(get(op, "at") ?? 0), -Math.max(0, phpInt2(get(op, "count") ?? 0)));
+        break;
+      case "insert_columns":
+        sheets[at2] = shiftColumns(sheets[at2], phpInt2(get(op, "at") ?? 0), Math.max(0, phpInt2(get(op, "count") ?? 0)));
+        break;
+      case "delete_columns":
+        sheets[at2] = shiftColumns(sheets[at2], phpInt2(get(op, "at") ?? 0), -Math.max(0, phpInt2(get(op, "count") ?? 0)));
+        break;
+      default:
+        return schema;
+    }
+    return { ...schema, sheets };
+  }
+};
+var EMPTY = /* @__PURE__ */ Symbol("empty");
+function find(sheets, name) {
+  for (let i = 0; i < sheets.length; i++) {
+    if (get(sheets[i], "name") === name) {
+      return i;
+    }
+  }
+  return null;
+}
+function setOrUnset(sheet, key, value, empty) {
+  const out = { ...sheet };
+  if (value === null || (empty === EMPTY ? isEmptyArr(value) : value === empty)) {
+    delete out[key];
+  } else {
+    out[key] = value;
+  }
+  return out;
+}
+function setCell(sheet, op) {
+  const address = asciiUpper(phpString(get(op, "address") ?? ""));
+  if (parseAddress(address) === null) {
+    return sheet;
+  }
+  const cells = isArr(get(sheet, "cells")) ? { ...sheet.cells } : {};
+  const existing = get(cells, address);
+  const value = get(op, "value");
+  const carries = (key) => has(op, key) && op[key] !== null;
+  if (existing === null && value === null && !carries("formula") && !carries("computedValue") && !carries("format") && !carries("comment")) {
+    return sheet;
+  }
+  const cell = has(op, "value") ? { value } : {};
+  for (const key of ["formula", "computedValue"]) {
+    if (carries(key)) {
+      cell[key] = op[key];
+    }
+  }
+  for (const key of ["format", "comment"]) {
+    if (has(op, key)) {
+      if (op[key] !== null) {
+        cell[key] = op[key];
+      }
+    } else if (isArr(existing) && has(existing, key)) {
+      cell[key] = existing[key];
+    }
+  }
+  if (Object.keys(cell).length === 0) {
+    delete cells[address];
+  } else {
+    cells[address] = cell;
+  }
+  return { ...sheet, cells };
+}
+function setRange(sheet, op) {
+  const start = parseAddress(phpString(get(op, "start") ?? ""));
+  if (start === null || !isArr(get(op, "values"))) {
+    return sheet;
+  }
+  const [col0, row0] = start;
+  const rows = valuesOf(op.values);
+  for (let r = 0; r < rows.length; r++) {
+    const row = valuesOf(isArr(rows[r]) ? rows[r] : []);
+    for (let c = 0; c < row.length; c++) {
+      sheet = setCell(sheet, { address: letter(col0 + c) + String(row0 + r), value: row[c] === void 0 ? null : row[c] });
+    }
+  }
+  return sheet;
+}
+function shiftRows(sheet, at2, delta) {
+  if (at2 < 1 || delta === 0) {
+    return sheet;
+  }
+  sheet = remapCells(sheet, (col, row) => {
+    if (row < at2) {
+      return [col, row];
+    }
+    if (delta < 0 && row < at2 - delta) {
+      return null;
+    }
+    return [col, row + delta];
+  });
+  return remapMerges(sheet, "row", at2, delta);
+}
+function shiftColumns(sheet, at2, delta) {
+  if (at2 < 1 || delta === 0) {
+    return sheet;
+  }
+  sheet = remapCells(sheet, (col, row) => {
+    const number = col + 1;
+    if (number < at2) {
+      return [col, row];
+    }
+    if (delta < 0 && number < at2 - delta) {
+      return null;
+    }
+    return [col + delta, row];
+  });
+  if (isArr(get(sheet, "columnWidths"))) {
+    const widths = /* @__PURE__ */ new Map();
+    for (const [index, width] of entriesOf(sheet.columnWidths)) {
+      const i = phpInt2(index);
+      const number = i + 1;
+      if (number < at2) {
+        widths.set(i, width);
+      } else if (delta > 0 || number >= at2 - delta) {
+        widths.set(i + delta, width);
+      }
+    }
+    const sorted = {};
+    for (const [index, width] of [...widths.entries()].sort((x, y) => x[0] - y[0])) {
+      sorted[index] = width;
+    }
+    sheet = setOrUnset(sheet, "columnWidths", sorted, EMPTY);
+  }
+  return remapMerges(sheet, "col", at2, delta);
+}
+function shiftSpan(start, end, at2, delta) {
+  if (delta > 0) {
+    return [start >= at2 ? start + delta : start, end >= at2 ? end + delta : end];
+  }
+  const last = at2 - delta - 1;
+  const newStart = start < at2 ? start : start > last ? start + delta : at2;
+  const newEnd = end < at2 ? end : end > last ? end + delta : at2 - 1;
+  return newEnd < newStart ? null : [newStart, newEnd];
+}
+function remapCells(sheet, move) {
+  if (!isArr(get(sheet, "cells"))) {
+    return sheet;
+  }
+  const placed = [];
+  for (const [address, cell] of entriesOf(sheet.cells)) {
+    const parsed = parseAddress(address);
+    if (parsed === null) {
+      continue;
+    }
+    const to = move(parsed[0], parsed[1]);
+    if (to !== null) {
+      placed.push([to[1], to[0], letter(to[0]) + String(to[1]), cell]);
+    }
+  }
+  placed.sort((x, y) => x[0] - y[0] || x[1] - y[1]);
+  const cells = {};
+  for (const [, , address, cell] of placed) {
+    cells[address] = cell;
+  }
+  return { ...sheet, cells };
+}
+function remapMerges(sheet, axis, at2, delta) {
+  if (!isArr(get(sheet, "mergedRegions"))) {
+    return sheet;
+  }
+  const regions = [];
+  for (const region of valuesOf(sheet.mergedRegions)) {
+    const start = parseAddress(phpString(get(region, "start") ?? ""));
+    const end = parseAddress(phpString(get(region, "end") ?? ""));
+    if (start === null || end === null) {
+      regions.push(region);
+      continue;
+    }
+    if (axis === "row") {
+      const moved = shiftSpan(start[1], end[1], at2, delta);
+      if (moved === null) {
+        continue;
+      }
+      regions.push({ start: letter(start[0]) + String(moved[0]), end: letter(end[0]) + String(moved[1]) });
+    } else {
+      const moved = shiftSpan(start[0] + 1, end[0] + 1, at2, delta);
+      if (moved === null) {
+        continue;
+      }
+      regions.push({ start: letter(moved[0] - 1) + String(start[1]), end: letter(moved[1] - 1) + String(end[1]) });
+    }
+  }
+  return setOrUnset(sheet, "mergedRegions", regions, EMPTY);
+}
+
+// src/ops/sheet-diff.ts
+var SheetDiff = {
+  /** Above this many LCS cells (after trimming the common prefix and suffix), rows or columns are not aligned. */
+  ALIGN_LIMIT: 25e4,
+  diff(a, b) {
+    if (SheetDiff.same(a, b) || SheetDiff.equivalent(a, b)) {
+      return [];
+    }
+    const ops = granular(a, b);
+    if (SheetDiff.same(SheetReducer.applyAll(a, ops), b)) {
+      return ops;
+    }
+    return [{ type: "set_workbook", data: b }];
+  },
+  /**
+   * Whether two schemas write the same workbook.
+   *
+   * Both are written and read back. `meta.created` is compared only when both
+   * schemas name one: the writer stamps the current time on a schema that
+   * does not, and that timestamp is not an edit.
+   */
+  equivalent(a, b) {
+    let describedA = described(a);
+    let describedB = described(b);
+    if (!namesCreated(a) || !namesCreated(b)) {
+      describedA = withoutCreated(describedA);
+      describedB = withoutCreated(describedB);
+    }
+    return SheetDiff.same(describedA, describedB);
+  },
+  /**
+   * Structural equality with map key order ignored and list order kept.
+   *
+   * Equality is on values, never on insertion order — a JS object cannot keep
+   * the order of integer-like keys anyway (`columnWidths`). It follows PHP's
+   * canonical form, where lists and maps are one array type: `{}` equals `[]`,
+   * and an object keyed exactly "0".."n-1" equals the list of its values.
+   *
+   * Two divergences from the PHP `same()` cannot be removed, because the
+   * distinctions do not exist in JS values:
+   *
+   * - PHP encodes the float `1.0` as `1.0` and the int `1` as `1`, so it calls
+   *   them different; JS has one number, so here they are the same. A PHP diff
+   *   can therefore emit a `set_cell` that rewrites `1` as `1.0` where this one
+   *   emits nothing. Parsed JSON gives PHP a float only for a literal written
+   *   with a fraction or exponent.
+   * - PHP treats an int-keyed array whose keys are 0..n-1 but out of order (for
+   *   example `columnWidths` decoded from `{"1":140,"0":120}`) as a map, not a
+   *   list, and so as different from the same widths in order. A JS object has
+   *   no such order to compare.
+   */
+  same(a, b) {
+    return canon(a) === canon(b);
+  },
+  /**
+   * Hunks of a longest-common-subsequence alignment: [start in a, deleted, inserted].
+   *
+   * Ties break toward deleting first. Past `ALIGN_LIMIT` the changed middle is
+   * one hunk.
+   */
+  hunks(a, b) {
+    const n = a.length;
+    const m = b.length;
+    let prefix = 0;
+    while (prefix < n && prefix < m && a[prefix] === b[prefix]) {
+      prefix++;
+    }
+    let suffix = 0;
+    while (suffix < n - prefix && suffix < m - prefix && a[n - 1 - suffix] === b[m - 1 - suffix]) {
+      suffix++;
+    }
+    const midA = a.slice(prefix, n - suffix);
+    const midB = b.slice(prefix, m - suffix);
+    const rows = midA.length;
+    const cols = midB.length;
+    if (rows === 0 && cols === 0) {
+      return [];
+    }
+    if (rows * cols > SheetDiff.ALIGN_LIMIT) {
+      return [[prefix, rows, cols]];
+    }
+    const lengths = [];
+    for (let i2 = 0; i2 <= rows; i2++) {
+      lengths.push(new Int32Array(cols + 1));
+    }
+    for (let i2 = rows - 1; i2 >= 0; i2--) {
+      for (let j2 = cols - 1; j2 >= 0; j2--) {
+        lengths[i2][j2] = midA[i2] === midB[j2] ? lengths[i2 + 1][j2 + 1] + 1 : Math.max(lengths[i2 + 1][j2], lengths[i2][j2 + 1]);
+      }
+    }
+    const hunks = [];
+    let open = null;
+    let i = 0;
+    let j = 0;
+    while (i < rows || j < cols) {
+      if (i < rows && j < cols && midA[i] === midB[j]) {
+        if (open !== null) {
+          hunks.push(open);
+          open = null;
+        }
+        i++;
+        j++;
+        continue;
+      }
+      open ?? (open = [prefix + i, 0, 0]);
+      if (j >= cols || i < rows && lengths[i + 1][j] >= lengths[i][j + 1]) {
+        open[1]++;
+        i++;
+      } else {
+        open[2]++;
+        j++;
+      }
+    }
+    if (open !== null) {
+      hunks.push(open);
+    }
+    return hunks;
+  }
+};
+function namesCreated(schema) {
+  return get(get(schema, "meta"), "created") !== null;
+}
+function withoutCreated(schema) {
+  const out = { ...schema };
+  if (isArr(out["meta"]) && !Array.isArray(out["meta"])) {
+    const meta = { ...out["meta"] };
+    delete meta["created"];
+    out["meta"] = meta;
+  }
+  if (has(out, "meta") && isEmptyArr(out["meta"])) {
+    delete out["meta"];
+  }
+  return out;
+}
+function described(schema) {
+  return Agent.read(Agent.toBytes(schema));
+}
+function sheetName(sheet) {
+  return phpString(get(sheet, "name") ?? "");
+}
+function granular(a, b) {
+  const sheetsA = isArr(get(a, "sheets")) ? valuesOf(a.sheets) : [];
+  const sheetsB = isArr(get(b, "sheets")) ? valuesOf(b.sheets) : [];
+  const namesA = sheetsA.map(sheetName);
+  const namesB = sheetsB.map(sheetName);
+  if (new Set(namesA).size !== namesA.length || new Set(namesB).size !== namesB.length) {
+    return [{ type: "set_workbook", data: b }];
+  }
+  const ops = [];
+  if (!SheetDiff.same(get(a, "meta"), get(b, "meta"))) {
+    ops.push({ type: "set_meta", meta: get(b, "meta") });
+  }
+  const removed = namesA.filter((name) => !namesB.includes(name));
+  const added = namesB.filter((name) => !namesA.includes(name));
+  const renames = /* @__PURE__ */ new Map();
+  const renamedTo = (name) => [...renames.values()].includes(name);
+  for (const old of removed) {
+    for (const name of added) {
+      if (renamedTo(name)) {
+        continue;
+      }
+      if (SheetDiff.same(withoutName(sheetsA[namesA.indexOf(old)]), withoutName(sheetsB[namesB.indexOf(name)]))) {
+        renames.set(old, name);
+        break;
+      }
+    }
+  }
+  let unmatchedRemoved = removed.filter((name) => !renames.has(name));
+  let unmatchedAdded = added.filter((name) => !renamedTo(name));
+  if (unmatchedRemoved.length === 1 && unmatchedAdded.length === 1) {
+    renames.set(unmatchedRemoved[0], unmatchedAdded[0]);
+    unmatchedRemoved = [];
+    unmatchedAdded = [];
+  }
+  for (const name of unmatchedRemoved) {
+    ops.push({ type: "remove_sheet", sheet: name });
+  }
+  for (const name of namesA) {
+    if (renames.has(name)) {
+      ops.push({ type: "rename_sheet", sheet: name, name: renames.get(name) });
+    }
+  }
+  namesB.forEach((name, index) => {
+    if (unmatchedAdded.includes(name)) {
+      ops.push({ type: "add_sheet", index, sheet: sheetsB[index] });
+    }
+  });
+  let state = SheetReducer.applyAll(a, ops);
+  namesB.forEach((name, index) => {
+    const current = new Map(entriesOf(get(state, "sheets") ?? []).map(([key, sheet]) => [key, sheetName(sheet)]));
+    if ((current.get(String(index)) ?? null) !== name) {
+      const op = { type: "move_sheet", sheet: name, toIndex: index };
+      ops.push(op);
+      state = SheetReducer.apply(state, op);
+    }
+  });
+  sheetsB.forEach((target, index) => {
+    const current = state.sheets[index];
+    if (SheetDiff.same(current, target)) {
+      return;
+    }
+    for (const op of sheetOps(current, target)) {
+      ops.push(op);
+    }
+  });
+  return ops;
+}
+function sheetOps(sheet, target) {
+  const name = phpString(target["name"]);
+  const replace = [{ type: "replace_sheet", sheet: name, data: target }];
+  if (!isCellForm(sheet) || !isCellForm(target)) {
+    return replace;
+  }
+  const ops = [];
+  let work = sheet;
+  for (const axis of ["row", "col"]) {
+    const structural = structuralOps(name, work, target, axis);
+    for (const op of structural) {
+      ops.push(op);
+      work = applyToSheet(work, op);
+    }
+  }
+  const cellsW = isArr(get(work, "cells")) ? work["cells"] : {};
+  const cellsT = isArr(get(target, "cells")) ? target["cells"] : {};
+  const addresses = [...new Set([...entriesOf(cellsW), ...entriesOf(cellsT)].map(([address]) => address))];
+  for (const address of rowMajor(addresses)) {
+    if (!has(cellsT, address)) {
+      ops.push({ type: "clear_cell", sheet: name, address });
+      continue;
+    }
+    const was = get(cellsW, address);
+    if (was !== null && SheetDiff.same(was, cellsT[address])) {
+      continue;
+    }
+    ops.push(setCellOp(name, address, isArr(was) ? was : null, isArr(cellsT[address]) ? cellsT[address] : {}));
+  }
+  if (!SheetDiff.same(get(work, "mergedRegions") ?? [], get(target, "mergedRegions") ?? [])) {
+    ops.push({ type: "set_merged_regions", sheet: name, mergedRegions: get(target, "mergedRegions") ?? [] });
+  }
+  if (!SheetDiff.same(get(work, "columnWidths") ?? [], get(target, "columnWidths") ?? [])) {
+    ops.push({ type: "set_column_widths", sheet: name, columnWidths: get(target, "columnWidths") ?? {} });
+  }
+  if (!identical(get(work, "frozenRows") ?? 0, get(target, "frozenRows") ?? 0) || !identical(get(work, "frozenCols") ?? 0, get(target, "frozenCols") ?? 0)) {
+    ops.push({
+      type: "set_frozen",
+      sheet: name,
+      rows: get(target, "frozenRows") ?? 0,
+      cols: get(target, "frozenCols") ?? 0
+    });
+  }
+  let result = sheet;
+  for (const op of ops) {
+    result = applyToSheet(result, op);
+  }
+  return SheetDiff.same(result, target) ? ops : replace;
+}
+function identical(x, y) {
+  return isArr(x) || isArr(y) ? SheetDiff.same(x, y) : x === y;
+}
+function setCellOp(sheet, address, was, cell) {
+  const op = { type: "set_cell", sheet, address };
+  if (has(cell, "value")) {
+    op["value"] = cell["value"];
+  }
+  for (const key of ["formula", "computedValue"]) {
+    if (has(cell, key)) {
+      op[key] = cell[key];
+    }
+  }
+  for (const key of ["format", "comment"]) {
+    if (!SheetDiff.same(get(was, key), get(cell, key))) {
+      op[key] = get(cell, key);
+    }
+  }
+  return op;
+}
+function structuralOps(name, sheet, target, axis) {
+  const sheetLines = lines(sheet, axis);
+  const targetLines = lines(target, axis);
+  const ops = [];
+  for (const [start, deleted, inserted] of SheetDiff.hunks(sheetLines, targetLines).reverse()) {
+    const kept = Math.min(deleted, inserted);
+    const at2 = start + kept + 1;
+    if (deleted > inserted) {
+      ops.push({ type: axis === "row" ? "delete_rows" : "delete_columns", sheet: name, at: at2, count: deleted - inserted });
+    } else if (inserted > deleted && at2 <= sheetLines.length) {
+      ops.push({ type: axis === "row" ? "insert_rows" : "insert_columns", sheet: name, at: at2, count: inserted - deleted });
+    }
+  }
+  return ops;
+}
+function lines(sheet, axis) {
+  const grouped = /* @__PURE__ */ new Map();
+  let max = 0;
+  for (const [address, cell] of entriesOf(isArr(get(sheet, "cells")) ? sheet["cells"] : {})) {
+    const parsed = parseAddress(address);
+    if (parsed === null) {
+      continue;
+    }
+    const [col, row] = parsed;
+    const line = axis === "row" ? row : col + 1;
+    const position = axis === "row" ? col : row;
+    let group = grouped.get(line);
+    if (group === void 0) {
+      group = /* @__PURE__ */ new Map();
+      grouped.set(line, group);
+    }
+    group.set(position, cell);
+    max = Math.max(max, line);
+  }
+  const out = [];
+  for (let i = 1; i <= max; i++) {
+    const positions = [...(grouped.get(i) ?? /* @__PURE__ */ new Map()).entries()].sort((x, y) => x[0] - y[0]);
+    out.push(canonEntries(positions.map(([position, cell]) => [String(position), cell])));
+  }
+  return out;
+}
+function applyToSheet(sheet, op) {
+  return SheetReducer.apply({ sheets: [sheet] }, op).sheets[0];
+}
+function isCellForm(sheet) {
+  return entriesOf(sheet).every(([key]) => SheetReducer.CELL_FORM_KEYS.includes(key));
+}
+function withoutName(sheet) {
+  const out = isArr(sheet) ? { ...sheet } : {};
+  delete out["name"];
+  return out;
+}
+function rowMajor(addresses) {
+  const parsed = [];
+  for (const address of addresses) {
+    const cell = parseAddress(address);
+    if (cell !== null) {
+      parsed.push([cell[1], cell[0], address]);
+    }
+  }
+  parsed.sort((x, y) => x[0] - y[0] || x[1] - y[1]);
+  return parsed.map(([, , address]) => address);
+}
+function canon(value) {
+  if (Array.isArray(value)) {
+    return "[" + value.map(canon).join(",") + "]";
+  }
+  if (isArr(value)) {
+    return canonEntries(entriesOf(value));
+  }
+  return JSON.stringify(value) ?? "null";
+}
+function canonEntries(entries) {
+  if (entries.every(([key], i) => key === String(i))) {
+    return "[" + entries.map(([, item]) => canon(item)).join(",") + "]";
+  }
+  const sorted = entries.slice().sort((x, y) => x[0] < y[0] ? -1 : x[0] > y[0] ? 1 : 0);
+  return "{" + sorted.map(([key, item]) => JSON.stringify(key) + ":" + canon(item)).join(",") + "}";
+}
+
+// src/ops/sheet-op-schema.ts
+var SheetOpSchema = {
+  /** Every op type, in the order the variants are listed. */
+  TYPES: [
+    "set_cell",
+    "set_range",
+    "set_workbook",
+    "clear_cell",
+    "insert_rows",
+    "delete_rows",
+    "insert_columns",
+    "delete_columns",
+    "add_sheet",
+    "remove_sheet",
+    "rename_sheet",
+    "move_sheet",
+    "replace_sheet",
+    "set_merged_regions",
+    "set_column_widths",
+    "set_frozen",
+    "set_meta"
+  ],
+  /** A fresh object on every call, so a caller editing it changes nothing here. */
+  jsonSchema() {
+    const address = () => ({ type: "string", pattern: "^[A-Za-z]+[0-9]+$" });
+    const sheet = () => ({ type: "string", minLength: 1 });
+    const count = () => ({ type: "integer", minimum: 1 });
+    const position = () => ({ type: "integer", minimum: 1 });
+    const object = () => ({ type: "object" });
+    const nullableObject = () => ({ type: ["object", "null"] });
+    const value = () => ({ type: ["string", "number", "boolean", "null"] });
+    const variants = [
+      variant(
+        "set_cell",
+        { sheet: sheet(), address: address(), value: value(), formula: { type: "string" }, computedValue: value(), format: nullableObject(), comment: nullableObject() },
+        ["sheet", "address"],
+        "Write one cell. Omitting formula or computedValue clears it; omitting format or comment keeps it; null clears it."
+      ),
+      variant(
+        "set_range",
+        { sheet: sheet(), start: address(), end: address(), values: { type: "array", items: { type: "array", items: value() } } },
+        ["sheet", "start", "values"],
+        "Write a block of values row-major from start, each as a set_cell with no formula."
+      ),
+      variant("set_workbook", { data: object() }, ["data"], "Replace the whole workbook schema."),
+      variant("clear_cell", { sheet: sheet(), address: address() }, ["sheet", "address"], "Remove one cell."),
+      variant("insert_rows", { sheet: sheet(), at: position(), count: count() }, ["sheet", "at", "count"], "Insert rows before 1-based row `at`; cells, merges below move down."),
+      variant("delete_rows", { sheet: sheet(), at: position(), count: count() }, ["sheet", "at", "count"], "Delete rows starting at 1-based row `at`; cells, merges below move up."),
+      variant("insert_columns", { sheet: sheet(), at: position(), count: count() }, ["sheet", "at", "count"], "Insert columns before 1-based column `at` (A = 1); cells, merges and widths move right."),
+      variant("delete_columns", { sheet: sheet(), at: position(), count: count() }, ["sheet", "at", "count"], "Delete columns starting at 1-based column `at`; cells, merges and widths move left."),
+      variant("add_sheet", { index: { type: "integer", minimum: 0 }, sheet: object() }, ["index", "sheet"], "Insert a sheet at a 0-based position."),
+      variant("remove_sheet", { sheet: sheet() }, ["sheet"], "Remove a sheet by name."),
+      variant("rename_sheet", { sheet: sheet(), name: sheet() }, ["sheet", "name"], "Rename a sheet."),
+      variant("move_sheet", { sheet: sheet(), toIndex: { type: "integer", minimum: 0 } }, ["sheet", "toIndex"], "Move a sheet to a 0-based position."),
+      variant("replace_sheet", { sheet: sheet(), data: object() }, ["sheet", "data"], "Replace one sheet whole."),
+      variant(
+        "set_merged_regions",
+        { sheet: sheet(), mergedRegions: { type: "array", items: { type: "object", required: ["start", "end"], properties: { start: address(), end: address() } } } },
+        ["sheet", "mergedRegions"],
+        "Set every merged region of a sheet."
+      ),
+      variant("set_column_widths", { sheet: sheet(), columnWidths: object() }, ["sheet", "columnWidths"], "Set every column width of a sheet (0-based column index to pixels)."),
+      variant(
+        "set_frozen",
+        { sheet: sheet(), rows: { type: "integer", minimum: 0 }, cols: { type: "integer", minimum: 0 } },
+        ["sheet", "rows", "cols"],
+        "Set frozen rows and columns."
+      ),
+      variant("set_meta", { meta: nullableObject() }, ["meta"], "Replace the workbook meta, or remove it with null.")
+    ];
+    return {
+      $schema: "http://json-schema.org/draft-07/schema#",
+      title: "Holy Sheet op",
+      description: "One op from Agent::diff, applied by Agent::reduce.",
+      oneOf: variants
+    };
+  }
+};
+function variant(type, properties, required, description) {
+  return {
+    type: "object",
+    description,
+    required: ["type", ...required],
+    additionalProperties: false,
+    properties: { type: { const: type }, ...properties }
+  };
+}
+
 // src/holy-sheet.schema.json
 var holy_sheet_schema_default = {
   $schema: "http://json-schema.org/draft-07/schema#",
@@ -4115,7 +4928,7 @@ var holy_sheet_schema_default = {
 };
 
 // src/agent.ts
-var VERSION = "2.3.0";
+var VERSION = "2.4.0";
 function toU8(input) {
   return input instanceof Uint8Array ? input : new Uint8Array(input);
 }
@@ -4168,8 +4981,8 @@ var Agent = {
     return new Validator().validateAndRepair(schema);
   },
   /** Build a schema from a flat array of rows (+ optional headers). */
-  fromArray(rows, headers = null, sheetName = "Sheet 1", options = {}) {
-    return ArrayBuilder.build(rows, headers, sheetName, options);
+  fromArray(rows, headers = null, sheetName2 = "Sheet 1", options = {}) {
+    return ArrayBuilder.build(rows, headers, sheetName2, options);
   },
   /** Build a schema from CSV content (read files yourself in Node). */
   fromCsv(csv, options = {}) {
@@ -4179,10 +4992,55 @@ var Agent = {
   lint(schema) {
     return new FormulaLinter().lint(schema);
   },
+  /**
+   * The ops that turn schema `a` into schema `b`. Mirrors PHP `Agent::diff`, and
+   * gives the same ops in the same order for the same inputs.
+   *
+   * - `reduce(a, diff(a, b))` equals `b` (key order aside).
+   * - Schemas that write the same workbook diff to `[]`, so
+   *   `diff(s, read(toBytes(s)))` is `[]`: a save without a change records
+   *   nothing.
+   * - One changed cell is one `set_cell`; an inserted row is one
+   *   `insert_rows` plus its cells.
+   *
+   * Store `diff(newer, older)` to keep a version as the ops that restore it.
+   * Both schemas must be valid: the "same workbook" check writes them.
+   */
+  diff(a, b) {
+    return SheetDiff.diff(a, b);
+  },
+  /**
+   * Apply one op, or a list of them, to a schema; returns a new schema and never
+   * modifies the input. An op naming a sheet that is not there is skipped.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  reduce(schema, opOrOps) {
+    return SheetReducer.applyAll(schema, isOpList(opOrOps) ? Object.values(opOrOps) : [opOrOps]);
+  },
+  /**
+   * JSON Schema for one op. `set_cell`, `set_range` and `set_workbook` are
+   * fancy-sheets' `SheetOp` shapes.
+   */
+  opSchema() {
+    return SheetOpSchema.jsonSchema();
+  },
+  /**
+   * Whether two schemas write the same workbook: a columns/rows sheet and the
+   * cell map it becomes are equivalent, and so are a schema without
+   * `meta.created` and its written copy.
+   */
+  equivalent(a, b) {
+    return SheetDiff.equivalent(a, b);
+  },
   version() {
     return VERSION;
   }
 };
+function isOpList(opOrOps) {
+  if (Array.isArray(opOrOps)) return true;
+  if (typeof opOrOps !== "object" || opOrOps === null) return false;
+  return Object.keys(opOrOps).every((key, i) => key === String(i));
+}
 
 // src/holy-sheet.ts
 var HolySheet = class {
@@ -4207,8 +5065,8 @@ var HolySheet = class {
   validateAndRepair(schema) {
     return Agent.validateAndRepair(schema);
   }
-  fromArray(rows, headers = null, sheetName = "Sheet 1", options = {}) {
-    return Agent.fromArray(rows, headers, sheetName, options);
+  fromArray(rows, headers = null, sheetName2 = "Sheet 1", options = {}) {
+    return Agent.fromArray(rows, headers, sheetName2, options);
   }
   fromCsv(csv, options = {}) {
     return Agent.fromCsv(csv, options);
@@ -4237,6 +5095,9 @@ exports.Normalizer = Normalizer;
 exports.OdsReader = OdsReader;
 exports.Repairer = Repairer;
 exports.SchemaException = SchemaException;
+exports.SheetDiff = SheetDiff;
+exports.SheetOpSchema = SheetOpSchema;
+exports.SheetReducer = SheetReducer;
 exports.Theme = Theme;
 exports.UnsupportedFormatException = UnsupportedFormatException;
 exports.VERSION = VERSION;