@lotics/xlsx 0.1.0

package/src/spreadsheet_commands.ts

@@ -0,0 +1,1805 @@
+// =============================================================================
+// Spreadsheet Commands
+// =============================================================================
+//
+// Reversible command implementations for all spreadsheet mutations.
+// Each command captures enough state to undo itself.
+// Used with CommandHistory for undo/redo support.
+// =============================================================================
+
+import type { Command } from "./command_history";
+import { SheetModel } from "./workbook_model";
+import type { WorkbookModel, CellValue } from "./workbook_model";
+import type { CellStyle, CellContent } from "./types";
+import type { ParsedConditionalFormat } from "./excel_cf_types";
+import type { FormulaEngine } from "./formula_engine";
+import type { PivotTableModel } from "./pivot_model";
+import type { ParsedPivotTable } from "./ooxml_pivot_types";
+import { rowColToRef, refToRowCol } from "./excel_utils";
+import { adjustFormulaRefsForRowShift, adjustFormulaRefsForColShift } from "./clipboard";
+
+// =============================================================================
+// Set Cell Value
+// =============================================================================
+
+export function setCellValueCommand(
+  workbook: WorkbookModel,
+  engine: FormulaEngine | undefined,
+  sheetIndex: number,
+  row: number,
+  col: number,
+  newValue: string,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const ref = rowColToRef(row, col);
+  const oldCell = sheet.getCell(ref);
+  const oldValue = oldCell?.value ?? null;
+  const oldFormula = oldCell?.formula;
+  // Determine if this is a formula
+  const isFormula = newValue.startsWith("=");
+  const formula = isFormula ? newValue.slice(1) : undefined;
+  const value: CellValue = isFormula
+    ? null // Will be computed by formula engine
+    : parseInputValue(newValue);
+
+  const styleIndex = oldCell?.styleIndex ?? 0;
+  const numFmtCode = oldCell?.numFmtCode ?? "General";
+
+  return {
+    description: `Set ${ref} = ${newValue}`,
+    execute() {
+      sheet.set(ref, value, sheet.styles?.get(styleIndex), numFmtCode, formula);
+      if (engine) {
+        engine.onCellChanged(sheet.name, ref, formula);
+      }
+      workbook.emit({
+        type: "cell_value",
+        sheet: sheetIndex,
+        ref,
+        oldValue,
+        newValue: value,
+      });
+    },
+    undo() {
+      if (oldValue === null && !oldFormula) {
+        sheet.deleteCell(ref);
+      } else {
+        sheet.set(ref, oldValue, sheet.styles?.get(styleIndex), numFmtCode, oldFormula);
+      }
+      if (engine) {
+        engine.onCellChanged(sheet.name, ref, oldFormula);
+      }
+      workbook.emit({
+        type: "cell_value",
+        sheet: sheetIndex,
+        ref,
+        oldValue: value,
+        newValue: oldValue,
+      });
+    },
+  };
+}
+
+// =============================================================================
+// Set Cell Style
+// =============================================================================
+
+export function setCellStyleCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  row: number,
+  col: number,
+  styleOverride: Partial<CellStyle>,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const ref = rowColToRef(row, col);
+  const cell = sheet.getCell(ref);
+  const oldStyleIndex = cell?.styleIndex ?? 0;
+  const newStyleIndex = workbook.styles.merge(oldStyleIndex, styleOverride);
+
+  return {
+    description: `Style ${ref}`,
+    execute() {
+      let c = sheet.getCell(ref);
+      if (!c) {
+        c = sheet.set(ref, null, sheet.styles?.get(newStyleIndex));
+      } else {
+        c.styleIndex = newStyleIndex;
+      }
+      workbook.emit({
+        type: "cell_style",
+        sheet: sheetIndex,
+        ref,
+        oldStyle: oldStyleIndex,
+        newStyle: newStyleIndex,
+      });
+    },
+    undo() {
+      let c = sheet.getCell(ref);
+      if (!c) {
+        c = sheet.set(ref, null, sheet.styles?.get(oldStyleIndex));
+      } else {
+        c.styleIndex = oldStyleIndex;
+      }
+      workbook.emit({
+        type: "cell_style",
+        sheet: sheetIndex,
+        ref,
+        oldStyle: newStyleIndex,
+        newStyle: oldStyleIndex,
+      });
+    },
+  };
+}
+
+// =============================================================================
+// Set Range Style (apply style to all cells in a range)
+// =============================================================================
+
+export function setRangeStyleCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  startRow: number,
+  startCol: number,
+  endRow: number,
+  endCol: number,
+  styleOverride: Partial<CellStyle>,
+): Command {
+  const commands: Command[] = [];
+  for (let r = startRow; r <= endRow; r++) {
+    for (let c = startCol; c <= endCol; c++) {
+      commands.push(setCellStyleCommand(workbook, sheetIndex, r, c, styleOverride));
+    }
+  }
+
+  const rangeRef = `${rowColToRef(startRow, startCol)}:${rowColToRef(endRow, endCol)}`;
+
+  return {
+    description: `Style ${rangeRef}`,
+    execute() {
+      for (const cmd of commands) cmd.execute();
+    },
+    undo() {
+      for (let i = commands.length - 1; i >= 0; i--) commands[i].undo();
+    },
+  };
+}
+
+// =============================================================================
+// Delete Cell
+// =============================================================================
+
+export function deleteCellCommand(
+  workbook: WorkbookModel,
+  engine: FormulaEngine | undefined,
+  sheetIndex: number,
+  row: number,
+  col: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const ref = rowColToRef(row, col);
+  const oldCell = sheet.getCell(ref);
+  const snapshot = oldCell
+    ? {
+        value: oldCell.value,
+        displayValue: oldCell.displayValue,
+        formula: oldCell.formula,
+        styleIndex: oldCell.styleIndex,
+        numFmtCode: oldCell.numFmtCode,
+        content: oldCell.content,
+        richText: oldCell.richText,
+      }
+    : null;
+
+  return {
+    description: `Clear ${ref}`,
+    execute() {
+      sheet.deleteCell(ref);
+      if (engine) {
+        engine.onCellChanged(sheet.name, ref);
+      }
+      workbook.emit({
+        type: "cell_value",
+        sheet: sheetIndex,
+        ref,
+        oldValue: snapshot?.value ?? null,
+        newValue: null,
+      });
+    },
+    undo() {
+      if (snapshot) {
+        sheet.set(ref, snapshot.value, sheet.styles?.get(snapshot.styleIndex), snapshot.numFmtCode, snapshot.formula);
+      }
+      if (engine) {
+        engine.onCellChanged(sheet.name, ref, snapshot?.formula);
+      }
+      workbook.emit({
+        type: "cell_value",
+        sheet: sheetIndex,
+        ref,
+        oldValue: null,
+        newValue: snapshot?.value ?? null,
+      });
+    },
+  };
+}
+
+// =============================================================================
+// Clear Range (delete all cells in a range)
+// =============================================================================
+
+export function clearRangeCommand(
+  workbook: WorkbookModel,
+  engine: FormulaEngine | undefined,
+  sheetIndex: number,
+  startRow: number,
+  startCol: number,
+  endRow: number,
+  endCol: number,
+): Command {
+  const commands: Command[] = [];
+  const sheet = workbook.sheets[sheetIndex];
+  for (let r = startRow; r <= endRow; r++) {
+    for (let c = startCol; c <= endCol; c++) {
+      const ref = rowColToRef(r, c);
+      if (sheet.getCell(ref)) {
+        commands.push(deleteCellCommand(workbook, engine, sheetIndex, r, c));
+      }
+    }
+  }
+
+  const rangeRef = `${rowColToRef(startRow, startCol)}:${rowColToRef(endRow, endCol)}`;
+
+  return {
+    description: `Clear ${rangeRef}`,
+    execute() {
+      for (const cmd of commands) cmd.execute();
+    },
+    undo() {
+      for (let i = commands.length - 1; i >= 0; i--) commands[i].undo();
+    },
+  };
+}
+
+// =============================================================================
+// Merge Cells
+// =============================================================================
+
+export function mergeCellsCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  startRow: number,
+  startCol: number,
+  endRow: number,
+  endCol: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const mergeRef = `${rowColToRef(startRow, startCol)}:${rowColToRef(endRow, endCol)}`;
+
+  return {
+    description: `Merge ${mergeRef}`,
+    execute() {
+      if (!sheet.mergedCells.includes(mergeRef)) {
+        sheet.mergedCells.push(mergeRef);
+      }
+      workbook.emit({ type: "merge", sheet: sheetIndex, ref: mergeRef });
+    },
+    undo() {
+      const idx = sheet.mergedCells.indexOf(mergeRef);
+      if (idx >= 0) sheet.mergedCells.splice(idx, 1);
+      workbook.emit({ type: "unmerge", sheet: sheetIndex, ref: mergeRef });
+    },
+  };
+}
+
+// =============================================================================
+// Unmerge Cells
+// =============================================================================
+
+export function unmergeCellsCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  mergeRef: string,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+
+  return {
+    description: `Unmerge ${mergeRef}`,
+    execute() {
+      const idx = sheet.mergedCells.indexOf(mergeRef);
+      if (idx >= 0) sheet.mergedCells.splice(idx, 1);
+      workbook.emit({ type: "unmerge", sheet: sheetIndex, ref: mergeRef });
+    },
+    undo() {
+      if (!sheet.mergedCells.includes(mergeRef)) {
+        sheet.mergedCells.push(mergeRef);
+      }
+      workbook.emit({ type: "merge", sheet: sheetIndex, ref: mergeRef });
+    },
+  };
+}
+
+// =============================================================================
+// Insert Rows
+// =============================================================================
+
+export function insertRowsCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  at: number,
+  count: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  // Snapshot merged ranges so undo can restore them. Cheaper than recomputing
+  // the inverse of `adjustMergedCellsForRowInsert` and avoids edge cases when
+  // inserts split existing ranges.
+  let mergeSnapshot: string[] = [];
+
+  return {
+    description: `Insert ${count} row${count > 1 ? "s" : ""} at ${at}`,
+    execute() {
+      mergeSnapshot = [...sheet.mergedCells];
+      // Shift existing cells down
+      const toMove: Array<{ ref: string; row: number; col: number }> = [];
+      for (const [ref] of sheet.cells) {
+        const rc = refToRowColSafe(ref);
+        if (rc && rc.row >= at) toMove.push({ ref, ...rc });
+      }
+      toMove.sort((a, b) => b.row - a.row); // bottom-up to avoid collisions
+      for (const { ref, row, col } of toMove) {
+        const cell = sheet.cells.get(ref)!;
+        sheet.cells.delete(ref);
+        sheet.cells.set(rowColToRef(row + count, col), cell);
+      }
+      // Shift row heights
+      const heightsToShift = Array.from(sheet.rowHeights.entries()).filter(([r]) => r >= at).sort((a, b) => b[0] - a[0]);
+      for (const [r, h] of heightsToShift) {
+        sheet.rowHeights.delete(r);
+        sheet.rowHeights.set(r + count, h);
+      }
+      // Adjust formula references and merged-cell ranges in lock-step.
+      adjustAllFormulasForRowShift(sheet, at, count);
+      adjustMergedCellsForRowInsert(sheet, at, count);
+      workbook.emit({ type: "rows_inserted", sheet: sheetIndex, at, count });
+    },
+    undo() {
+      sheet.mergedCells = [...mergeSnapshot];
+      // Shift cells back up
+      const toMove: Array<{ ref: string; row: number; col: number }> = [];
+      for (const [ref] of sheet.cells) {
+        const rc = refToRowColSafe(ref);
+        if (rc && rc.row >= at + count) toMove.push({ ref, ...rc });
+      }
+      // Delete inserted empty rows
+      for (const [ref] of sheet.cells) {
+        const rc = refToRowColSafe(ref);
+        if (rc && rc.row >= at && rc.row < at + count) sheet.cells.delete(ref);
+      }
+      toMove.sort((a, b) => a.row - b.row); // top-down
+      for (const { ref, row, col } of toMove) {
+        const cell = sheet.cells.get(ref)!;
+        sheet.cells.delete(ref);
+        sheet.cells.set(rowColToRef(row - count, col), cell);
+      }
+      // Shift row heights back
+      const heightsToShift = Array.from(sheet.rowHeights.entries()).filter(([r]) => r >= at + count).sort((a, b) => a[0] - b[0]);
+      for (const [r, h] of heightsToShift) {
+        sheet.rowHeights.delete(r);
+        sheet.rowHeights.set(r - count, h);
+      }
+      for (let r = at; r < at + count; r++) sheet.rowHeights.delete(r);
+      workbook.emit({ type: "rows_deleted", sheet: sheetIndex, at, count });
+    },
+  };
+}
+
+// =============================================================================
+// Delete Rows
+// =============================================================================
+
+export function deleteRowsCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  at: number,
+  count: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  // Snapshot deleted cells
+  const snapshot = new Map<string, { value: CellValue; displayValue: string; formula?: string; styleIndex: number; numFmtCode: string; content: CellContent }>();
+  for (const [ref, cell] of sheet.cells) {
+    const rc = refToRowColSafe(ref);
+    if (rc && rc.row >= at && rc.row < at + count) {
+      snapshot.set(ref, { value: cell.value, displayValue: cell.displayValue, formula: cell.formula, styleIndex: cell.styleIndex, numFmtCode: cell.numFmtCode, content: cell.content });
+    }
+  }
+  let mergeSnapshot: string[] = [];
+
+  return {
+    description: `Delete ${count} row${count > 1 ? "s" : ""} at ${at}`,
+    execute() {
+      mergeSnapshot = [...sheet.mergedCells];
+      // Delete cells in the range
+      for (const ref of snapshot.keys()) sheet.cells.delete(ref);
+      // Shift cells up
+      const toMove: Array<{ ref: string; row: number; col: number }> = [];
+      for (const [ref] of sheet.cells) {
+        const rc = refToRowColSafe(ref);
+        if (rc && rc.row >= at + count) toMove.push({ ref, ...rc });
+      }
+      toMove.sort((a, b) => a.row - b.row);
+      for (const { ref, row, col } of toMove) {
+        const cell = sheet.cells.get(ref)!;
+        sheet.cells.delete(ref);
+        sheet.cells.set(rowColToRef(row - count, col), cell);
+      }
+      adjustAllFormulasForRowShift(sheet, at, -count);
+      adjustMergedCellsForRowDelete(sheet, at, count);
+      workbook.emit({ type: "rows_deleted", sheet: sheetIndex, at, count });
+    },
+    undo() {
+      sheet.mergedCells = [...mergeSnapshot];
+      // Shift cells back down
+      const toMove: Array<{ ref: string; row: number; col: number }> = [];
+      for (const [ref] of sheet.cells) {
+        const rc = refToRowColSafe(ref);
+        if (rc && rc.row >= at) toMove.push({ ref, ...rc });
+      }
+      toMove.sort((a, b) => b.row - a.row);
+      for (const { ref, row, col } of toMove) {
+        const cell = sheet.cells.get(ref)!;
+        sheet.cells.delete(ref);
+        sheet.cells.set(rowColToRef(row + count, col), cell);
+      }
+      // Restore snapshot
+      for (const [ref, snap] of snapshot) {
+        sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
+      }
+      workbook.emit({ type: "rows_inserted", sheet: sheetIndex, at, count });
+    },
+  };
+}
+
+// =============================================================================
+// Insert Columns
+// =============================================================================
+
+export function insertColsCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  at: number,
+  count: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  let mergeSnapshot: string[] = [];
+
+  return {
+    description: `Insert ${count} column${count > 1 ? "s" : ""} at ${at}`,
+    execute() {
+      mergeSnapshot = [...sheet.mergedCells];
+      const toMove: Array<{ ref: string; row: number; col: number }> = [];
+      for (const [ref] of sheet.cells) {
+        const rc = refToRowColSafe(ref);
+        if (rc && rc.col >= at) toMove.push({ ref, ...rc });
+      }
+      toMove.sort((a, b) => b.col - a.col);
+      for (const { ref, row, col } of toMove) {
+        const cell = sheet.cells.get(ref)!;
+        sheet.cells.delete(ref);
+        sheet.cells.set(rowColToRef(row, col + count), cell);
+      }
+      const widthsToShift = Array.from(sheet.colWidths.entries()).filter(([c]) => c >= at).sort((a, b) => b[0] - a[0]);
+      for (const [c, w] of widthsToShift) {
+        sheet.colWidths.delete(c);
+        sheet.colWidths.set(c + count, w);
+      }
+      adjustAllFormulasForColShift(sheet, at, count);
+      adjustMergedCellsForColInsert(sheet, at, count);
+      workbook.emit({ type: "cols_inserted", sheet: sheetIndex, at, count });
+    },
+    undo() {
+      sheet.mergedCells = [...mergeSnapshot];
+      const toMove: Array<{ ref: string; row: number; col: number }> = [];
+      for (const [ref] of sheet.cells) {
+        const rc = refToRowColSafe(ref);
+        if (rc && rc.col >= at + count) toMove.push({ ref, ...rc });
+      }
+      for (const [ref] of sheet.cells) {
+        const rc = refToRowColSafe(ref);
+        if (rc && rc.col >= at && rc.col < at + count) sheet.cells.delete(ref);
+      }
+      toMove.sort((a, b) => a.col - b.col);
+      for (const { ref, row, col } of toMove) {
+        const cell = sheet.cells.get(ref)!;
+        sheet.cells.delete(ref);
+        sheet.cells.set(rowColToRef(row, col - count), cell);
+      }
+      const widthsToShift = Array.from(sheet.colWidths.entries()).filter(([c]) => c >= at + count).sort((a, b) => a[0] - b[0]);
+      for (const [c, w] of widthsToShift) {
+        sheet.colWidths.delete(c);
+        sheet.colWidths.set(c - count, w);
+      }
+      for (let c = at; c < at + count; c++) sheet.colWidths.delete(c);
+      workbook.emit({ type: "cols_deleted", sheet: sheetIndex, at, count });
+    },
+  };
+}
+
+// =============================================================================
+// Delete Columns
+// =============================================================================
+
+export function deleteColsCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  at: number,
+  count: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const snapshot = new Map<string, { value: CellValue; displayValue: string; formula?: string; styleIndex: number; numFmtCode: string; content: CellContent }>();
+  for (const [ref, cell] of sheet.cells) {
+    const rc = refToRowColSafe(ref);
+    if (rc && rc.col >= at && rc.col < at + count) {
+      snapshot.set(ref, { value: cell.value, displayValue: cell.displayValue, formula: cell.formula, styleIndex: cell.styleIndex, numFmtCode: cell.numFmtCode, content: cell.content });
+    }
+  }
+  let mergeSnapshot: string[] = [];
+
+  return {
+    description: `Delete ${count} column${count > 1 ? "s" : ""} at ${at}`,
+    execute() {
+      mergeSnapshot = [...sheet.mergedCells];
+      for (const ref of snapshot.keys()) sheet.cells.delete(ref);
+      const toMove: Array<{ ref: string; row: number; col: number }> = [];
+      for (const [ref] of sheet.cells) {
+        const rc = refToRowColSafe(ref);
+        if (rc && rc.col >= at + count) toMove.push({ ref, ...rc });
+      }
+      toMove.sort((a, b) => a.col - b.col);
+      for (const { ref, row, col } of toMove) {
+        const cell = sheet.cells.get(ref)!;
+        sheet.cells.delete(ref);
+        sheet.cells.set(rowColToRef(row, col - count), cell);
+      }
+      adjustAllFormulasForColShift(sheet, at, -count);
+      adjustMergedCellsForColDelete(sheet, at, count);
+      workbook.emit({ type: "cols_deleted", sheet: sheetIndex, at, count });
+    },
+    undo() {
+      sheet.mergedCells = [...mergeSnapshot];
+      const toMove: Array<{ ref: string; row: number; col: number }> = [];
+      for (const [ref] of sheet.cells) {
+        const rc = refToRowColSafe(ref);
+        if (rc && rc.col >= at) toMove.push({ ref, ...rc });
+      }
+      toMove.sort((a, b) => b.col - a.col);
+      for (const { ref, row, col } of toMove) {
+        const cell = sheet.cells.get(ref)!;
+        sheet.cells.delete(ref);
+        sheet.cells.set(rowColToRef(row, col + count), cell);
+      }
+      for (const [ref, snap] of snapshot) {
+        sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
+      }
+      workbook.emit({ type: "cols_inserted", sheet: sheetIndex, at, count });
+    },
+  };
+}
+
+// =============================================================================
+// Set Column Width
+// =============================================================================
+
+export function setColWidthCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  col: number,
+  newWidth: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const oldWidth = sheet.colWidths.get(col) ?? sheet.defaultColWidth;
+
+  return {
+    description: `Resize column ${col}`,
+    execute() {
+      sheet.colWidths.set(col, newWidth);
+    },
+    undo() {
+      if (oldWidth === sheet.defaultColWidth) {
+        sheet.colWidths.delete(col);
+      } else {
+        sheet.colWidths.set(col, oldWidth);
+      }
+    },
+  };
+}
+
+// =============================================================================
+// Set Row Height
+// =============================================================================
+
+export function setRowHeightCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  row: number,
+  newHeight: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const oldHeight = sheet.rowHeights.get(row) ?? sheet.defaultRowHeight;
+
+  return {
+    description: `Resize row ${row}`,
+    execute() {
+      sheet.rowHeights.set(row, newHeight);
+    },
+    undo() {
+      if (oldHeight === sheet.defaultRowHeight) {
+        sheet.rowHeights.delete(row);
+      } else {
+        sheet.rowHeights.set(row, oldHeight);
+      }
+    },
+  };
+}
+
+// =============================================================================
+// Set Named Range
+// =============================================================================
+
+export function setNamedRangeCommand(
+  workbook: WorkbookModel,
+  name: string,
+  expr: string,
+): Command {
+  const oldExpr = workbook.namedRanges.get(name);
+
+  return {
+    description: `Define name ${name} = ${expr}`,
+    execute() {
+      workbook.namedRanges.set(name, expr);
+    },
+    undo() {
+      if (oldExpr === undefined) {
+        workbook.namedRanges.delete(name);
+      } else {
+        workbook.namedRanges.set(name, oldExpr);
+      }
+    },
+  };
+}
+
+// =============================================================================
+// Set Range Number Format
+// =============================================================================
+
+export function setRangeNumFmtCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  startRow: number,
+  startCol: number,
+  endRow: number,
+  endCol: number,
+  numFmtCode: string,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const snapshot = new Map<string, { value: CellValue; styleIndex: number; numFmtCode: string; formula?: string } | null>();
+  for (let r = startRow; r <= endRow; r++) {
+    for (let c = startCol; c <= endCol; c++) {
+      const ref = rowColToRef(r, c);
+      const cell = sheet.getCell(ref);
+      snapshot.set(ref, cell ? { value: cell.value, styleIndex: cell.styleIndex, numFmtCode: cell.numFmtCode, formula: cell.formula } : null);
+    }
+  }
+  const rangeRef = `${rowColToRef(startRow, startCol)}:${rowColToRef(endRow, endCol)}`;
+
+  return {
+    description: `Format ${rangeRef} as ${numFmtCode}`,
+    execute() {
+      for (let r = startRow; r <= endRow; r++) {
+        for (let c = startCol; c <= endCol; c++) {
+          const ref = rowColToRef(r, c);
+          const cell = sheet.getCell(ref);
+          if (cell) {
+            sheet.set(ref, cell.value, sheet.styles?.get(cell.styleIndex), numFmtCode, cell.formula);
+          } else {
+            sheet.set(ref, null, undefined, numFmtCode);
+          }
+        }
+      }
+    },
+    undo() {
+      for (const [ref, snap] of snapshot) {
+        if (snap) {
+          sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
+        } else {
+          sheet.deleteCell(ref);
+        }
+      }
+    },
+  };
+}
+
+// =============================================================================
+// Sheet Management
+// =============================================================================
+
+export function addSheetCommand(workbook: WorkbookModel, name: string): Command {
+  return {
+    description: `Add sheet ${name}`,
+    execute() {
+      workbook.sheets.push(new SheetModel(name, workbook.styles));
+      workbook.emit({ type: "sheet_added", index: workbook.sheets.length - 1 });
+    },
+    undo() {
+      const index = workbook.sheets.length - 1;
+      workbook.sheets.pop();
+      workbook.emit({ type: "sheet_deleted", index });
+    },
+  };
+}
+
+export function deleteSheetCommand(workbook: WorkbookModel, index: number): Command {
+  const snapshot = workbook.sheets[index];
+  return {
+    description: `Delete sheet ${snapshot.name}`,
+    execute() {
+      workbook.sheets.splice(index, 1);
+      workbook.emit({ type: "sheet_deleted", index });
+    },
+    undo() {
+      workbook.sheets.splice(index, 0, snapshot);
+      workbook.emit({ type: "sheet_added", index });
+    },
+  };
+}
+
+export function renameSheetCommand(workbook: WorkbookModel, index: number, newName: string): Command {
+  const oldName = workbook.sheets[index].name;
+  return {
+    description: `Rename sheet ${oldName} → ${newName}`,
+    execute() {
+      workbook.sheets[index].name = newName;
+      workbook.emit({ type: "sheet_renamed", index, oldName, newName });
+    },
+    undo() {
+      workbook.sheets[index].name = oldName;
+      workbook.emit({ type: "sheet_renamed", index, oldName: newName, newName: oldName });
+    },
+  };
+}
+
+// =============================================================================
+// Batch Command
+// =============================================================================
+
+export function batchCommand(
+  description: string,
+  commands: Command[],
+): Command {
+  return {
+    description,
+    execute() {
+      for (const cmd of commands) cmd.execute();
+    },
+    undo() {
+      for (let i = commands.length - 1; i >= 0; i--) commands[i].undo();
+    },
+  };
+}
+
+// =============================================================================
+// Set Hidden Rows
+// =============================================================================
+
+// =============================================================================
+// Add Table — convert a range to a styled Excel Table
+// =============================================================================
+
+export function addTableCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  table: import("./ooxml_chart_types").ParsedTable,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  return {
+    description: `Insert table ${table.name}`,
+    execute() {
+      sheet.tables.push(table);
+    },
+    undo() {
+      const idx = sheet.tables.findIndex((t) => t.name === table.name);
+      if (idx >= 0) sheet.tables.splice(idx, 1);
+    },
+  };
+}
+
+export function removeTableCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  tableName: string,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  let savedIdx = -1;
+  let savedTable: import("./ooxml_chart_types").ParsedTable | undefined;
+  return {
+    description: `Convert table ${tableName} to range`,
+    execute() {
+      savedIdx = sheet.tables.findIndex((t) => t.name === tableName);
+      if (savedIdx >= 0) {
+        savedTable = sheet.tables[savedIdx];
+        sheet.tables.splice(savedIdx, 1);
+      }
+    },
+    undo() {
+      if (savedTable && savedIdx >= 0) {
+        sheet.tables.splice(savedIdx, 0, savedTable);
+      }
+    },
+  };
+}
+
+export function setSheetTabColorCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  newColor: string | undefined,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const oldColor = sheet.view.tabColor;
+
+  return {
+    description: `Set tab color`,
+    execute() {
+      sheet.view.tabColor = newColor;
+    },
+    undo() {
+      sheet.view.tabColor = oldColor;
+    },
+  };
+}
+
+// =============================================================================
+// Set Hidden Rows
+// =============================================================================
+
+export function setHiddenRowsCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  newHidden: Set<number>,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const oldHidden = new Set(sheet.hiddenRows);
+
+  return {
+    description: `Set hidden rows`,
+    execute() {
+      sheet.hiddenRows = new Set(newHidden);
+    },
+    undo() {
+      sheet.hiddenRows = new Set(oldHidden);
+    },
+  };
+}
+
+// =============================================================================
+// Set Hidden Cols
+// =============================================================================
+
+export function setHiddenColsCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  newHidden: Set<number>,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const oldHidden = new Set(sheet.hiddenCols);
+
+  return {
+    description: `Set hidden cols`,
+    execute() {
+      sheet.hiddenCols = new Set(newHidden);
+    },
+    undo() {
+      sheet.hiddenCols = new Set(oldHidden);
+    },
+  };
+}
+
+// =============================================================================
+// Set Pivot Config
+// =============================================================================
+
+/**
+ * Replace a pivot's `config` (axis assignments, value aggregations, layout)
+ * and recompute. Captures the old config so undo restores it. The caller
+ * builds the next config; this command swaps it atomically.
+ */
+export function setPivotConfigCommand(
+  workbook: WorkbookModel,
+  pivot: PivotTableModel,
+  newConfig: ParsedPivotTable,
+): Command {
+  const oldConfig = pivot.config;
+
+  return {
+    description: `Update pivot ${oldConfig.name}`,
+    execute() {
+      pivot.config = newConfig;
+      pivot.recompute(workbook);
+    },
+    undo() {
+      pivot.config = oldConfig;
+      pivot.recompute(workbook);
+    },
+  };
+}
+
+// =============================================================================
+// Sort Column
+// =============================================================================
+
+export function sortColumnCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  col: number,
+  ascending: boolean,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const used = sheet.getUsedRange();
+
+  // Snapshot ALL cells in the used range before sorting
+  const snapshot = new Map<string, { value: CellValue; displayValue: string; formula?: string; styleIndex: number; numFmtCode: string; content: CellContent } | undefined>();
+  for (let r = used.minRow; r <= used.maxRow; r++) {
+    for (let c = used.minCol; c <= used.maxCol; c++) {
+      const ref = rowColToRef(r, c);
+      const cell = sheet.getCell(ref);
+      if (cell) {
+        snapshot.set(ref, { value: cell.value, displayValue: cell.displayValue, formula: cell.formula, styleIndex: cell.styleIndex, numFmtCode: cell.numFmtCode, content: cell.content });
+      } else {
+        snapshot.set(ref, undefined);
+      }
+    }
+  }
+
+  return {
+    description: `Sort column ${col} ${ascending ? "asc" : "desc"}`,
+    execute() {
+      sortColumnInPlace(sheet, col, ascending);
+    },
+    undo() {
+      // Restore all cells from snapshot
+      for (const [ref, snap] of snapshot) {
+        if (snap) {
+          sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
+        } else {
+          sheet.deleteCell(ref);
+        }
+      }
+    },
+  };
+}
+
+// =============================================================================
+// Multi-Column Sort
+// =============================================================================
+
+export interface SortSpec {
+  col: number;
+  ascending: boolean;
+}
+
+export function multiSortCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  sortSpecs: SortSpec[],
+  hasHeader: boolean,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const used = sheet.getUsedRange();
+
+  // Snapshot ALL cells in the used range before sorting
+  const snapshot = new Map<string, { value: CellValue; displayValue: string; formula?: string; styleIndex: number; numFmtCode: string; content: CellContent } | undefined>();
+  for (let r = used.minRow; r <= used.maxRow; r++) {
+    for (let c = used.minCol; c <= used.maxCol; c++) {
+      const ref = rowColToRef(r, c);
+      const cell = sheet.getCell(ref);
+      if (cell) {
+        snapshot.set(ref, { value: cell.value, displayValue: cell.displayValue, formula: cell.formula, styleIndex: cell.styleIndex, numFmtCode: cell.numFmtCode, content: cell.content });
+      } else {
+        snapshot.set(ref, undefined);
+      }
+    }
+  }
+
+  return {
+    description: `Multi-sort by ${sortSpecs.length} keys`,
+    execute() {
+      multiSortInPlace(sheet, sortSpecs, hasHeader ? used.minRow + 1 : used.minRow);
+    },
+    undo() {
+      for (const [ref, snap] of snapshot) {
+        if (snap) {
+          sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
+        } else {
+          sheet.deleteCell(ref);
+        }
+      }
+    },
+  };
+}
+
+// =============================================================================
+// Set Freeze Panes
+// =============================================================================
+
+export function setFreezePanesCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  newFreeze: { row: number; col: number } | undefined,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const oldFreeze = sheet.freeze ? { ...sheet.freeze } : undefined;
+
+  return {
+    description: newFreeze ? `Freeze at row ${newFreeze.row}, col ${newFreeze.col}` : "Unfreeze panes",
+    execute() {
+      sheet.freeze = newFreeze ? { ...newFreeze } : undefined;
+    },
+    undo() {
+      sheet.freeze = oldFreeze ? { ...oldFreeze } : undefined;
+    },
+  };
+}
+
+// =============================================================================
+// Set Zoom
+// =============================================================================
+
+export function setZoomCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  newZoom: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const oldZoom = sheet.view.zoomScale;
+
+  return {
+    description: `Zoom ${oldZoom}% → ${newZoom}%`,
+    execute() {
+      sheet.view.zoomScale = newZoom;
+    },
+    undo() {
+      sheet.view.zoomScale = oldZoom;
+    },
+  };
+}
+
+// =============================================================================
+// Add Conditional Format
+// =============================================================================
+
+export function addConditionalFormatCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  cf: ParsedConditionalFormat,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+
+  return {
+    description: `Add CF rule on ${cf.ref}`,
+    execute() {
+      sheet.conditionalFormats.push(cf);
+    },
+    undo() {
+      sheet.conditionalFormats.pop();
+    },
+  };
+}
+
+// =============================================================================
+// Delete Conditional Format
+// =============================================================================
+
+export function deleteConditionalFormatCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  index: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const snapshot = sheet.conditionalFormats[index];
+
+  return {
+    description: `Delete CF rule #${index}`,
+    execute() {
+      sheet.conditionalFormats.splice(index, 1);
+    },
+    undo() {
+      sheet.conditionalFormats.splice(index, 0, snapshot);
+    },
+  };
+}
+
+// =============================================================================
+// Reorder Sheets
+// =============================================================================
+
+export function reorderSheetsCommand(
+  workbook: WorkbookModel,
+  fromIndex: number,
+  toIndex: number,
+): Command {
+  return {
+    description: `Move sheet ${fromIndex} → ${toIndex}`,
+    execute() {
+      const [sheet] = workbook.sheets.splice(fromIndex, 1);
+      workbook.sheets.splice(toIndex, 0, sheet);
+    },
+    undo() {
+      const [sheet] = workbook.sheets.splice(toIndex, 1);
+      workbook.sheets.splice(fromIndex, 0, sheet);
+    },
+  };
+}
+
+// =============================================================================
+// Insert Cells (Shift Down)
+// =============================================================================
+
+export function insertCellsShiftDownCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  startRow: number,
+  startCol: number,
+  endRow: number,
+  endCol: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const height = endRow - startRow + 1;
+
+  return {
+    description: `Insert cells shift down ${rowColToRef(startRow, startCol)}:${rowColToRef(endRow, endCol)}`,
+    execute() {
+      // For each column in the range, shift cells down by `height` starting from startRow
+      for (let c = startCol; c <= endCol; c++) {
+        // Collect cells at or below startRow in this column
+        const toMove: Array<{ row: number; ref: string }> = [];
+        for (const [ref] of sheet.cells) {
+          const rc = refToRowColSafe(ref);
+          if (rc && rc.col === c && rc.row >= startRow) toMove.push({ row: rc.row, ref });
+        }
+        toMove.sort((a, b) => b.row - a.row); // bottom-up
+        for (const { ref, row } of toMove) {
+          const cell = sheet.cells.get(ref)!;
+          sheet.cells.delete(ref);
+          sheet.cells.set(rowColToRef(row + height, c), cell);
+        }
+      }
+    },
+    undo() {
+      for (let c = startCol; c <= endCol; c++) {
+        // Delete the inserted empty cells
+        for (let r = startRow; r <= endRow; r++) {
+          sheet.deleteCell(rowColToRef(r, c));
+        }
+        // Shift cells back up
+        const toMove: Array<{ row: number; ref: string }> = [];
+        for (const [ref] of sheet.cells) {
+          const rc = refToRowColSafe(ref);
+          if (rc && rc.col === c && rc.row >= startRow + height) toMove.push({ row: rc.row, ref });
+        }
+        toMove.sort((a, b) => a.row - b.row); // top-down
+        for (const { ref, row } of toMove) {
+          const cell = sheet.cells.get(ref)!;
+          sheet.cells.delete(ref);
+          sheet.cells.set(rowColToRef(row - height, c), cell);
+        }
+      }
+    },
+  };
+}
+
+// =============================================================================
+// Insert Cells (Shift Right)
+// =============================================================================
+
+export function insertCellsShiftRightCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  startRow: number,
+  startCol: number,
+  endRow: number,
+  endCol: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const width = endCol - startCol + 1;
+
+  return {
+    description: `Insert cells shift right ${rowColToRef(startRow, startCol)}:${rowColToRef(endRow, endCol)}`,
+    execute() {
+      for (let r = startRow; r <= endRow; r++) {
+        const toMove: Array<{ col: number; ref: string }> = [];
+        for (const [ref] of sheet.cells) {
+          const rc = refToRowColSafe(ref);
+          if (rc && rc.row === r && rc.col >= startCol) toMove.push({ col: rc.col, ref });
+        }
+        toMove.sort((a, b) => b.col - a.col); // right-to-left
+        for (const { ref, col } of toMove) {
+          const cell = sheet.cells.get(ref)!;
+          sheet.cells.delete(ref);
+          sheet.cells.set(rowColToRef(r, col + width), cell);
+        }
+      }
+    },
+    undo() {
+      for (let r = startRow; r <= endRow; r++) {
+        for (let c = startCol; c <= endCol; c++) {
+          sheet.deleteCell(rowColToRef(r, c));
+        }
+        const toMove: Array<{ col: number; ref: string }> = [];
+        for (const [ref] of sheet.cells) {
+          const rc = refToRowColSafe(ref);
+          if (rc && rc.row === r && rc.col >= startCol + width) toMove.push({ col: rc.col, ref });
+        }
+        toMove.sort((a, b) => a.col - b.col); // left-to-right
+        for (const { ref, col } of toMove) {
+          const cell = sheet.cells.get(ref)!;
+          sheet.cells.delete(ref);
+          sheet.cells.set(rowColToRef(r, col - width), cell);
+        }
+      }
+    },
+  };
+}
+
+// =============================================================================
+// Delete Cells (Shift Up)
+// =============================================================================
+
+export function deleteCellsShiftUpCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  startRow: number,
+  startCol: number,
+  endRow: number,
+  endCol: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const height = endRow - startRow + 1;
+
+  // Snapshot deleted cells
+  const snapshot = new Map<string, { value: CellValue; displayValue: string; formula?: string; styleIndex: number; numFmtCode: string; content: CellContent }>();
+  for (let r = startRow; r <= endRow; r++) {
+    for (let c = startCol; c <= endCol; c++) {
+      const ref = rowColToRef(r, c);
+      const cell = sheet.getCell(ref);
+      if (cell) {
+        snapshot.set(ref, { value: cell.value, displayValue: cell.displayValue, formula: cell.formula, styleIndex: cell.styleIndex, numFmtCode: cell.numFmtCode, content: cell.content });
+      }
+    }
+  }
+
+  return {
+    description: `Delete cells shift up ${rowColToRef(startRow, startCol)}:${rowColToRef(endRow, endCol)}`,
+    execute() {
+      for (let c = startCol; c <= endCol; c++) {
+        // Delete cells in the range
+        for (let r = startRow; r <= endRow; r++) {
+          sheet.deleteCell(rowColToRef(r, c));
+        }
+        // Shift cells up
+        const toMove: Array<{ row: number; ref: string }> = [];
+        for (const [ref] of sheet.cells) {
+          const rc = refToRowColSafe(ref);
+          if (rc && rc.col === c && rc.row > endRow) toMove.push({ row: rc.row, ref });
+        }
+        toMove.sort((a, b) => a.row - b.row); // top-down
+        for (const { ref, row } of toMove) {
+          const cell = sheet.cells.get(ref)!;
+          sheet.cells.delete(ref);
+          sheet.cells.set(rowColToRef(row - height, c), cell);
+        }
+      }
+    },
+    undo() {
+      for (let c = startCol; c <= endCol; c++) {
+        // Shift cells back down
+        const toMove: Array<{ row: number; ref: string }> = [];
+        for (const [ref] of sheet.cells) {
+          const rc = refToRowColSafe(ref);
+          if (rc && rc.col === c && rc.row >= startRow) toMove.push({ row: rc.row, ref });
+        }
+        toMove.sort((a, b) => b.row - a.row); // bottom-up
+        for (const { ref, row } of toMove) {
+          const cell = sheet.cells.get(ref)!;
+          sheet.cells.delete(ref);
+          sheet.cells.set(rowColToRef(row + height, c), cell);
+        }
+      }
+      // Restore snapshot
+      for (const [ref, snap] of snapshot) {
+        sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
+      }
+    },
+  };
+}
+
+// =============================================================================
+// Delete Cells (Shift Left)
+// =============================================================================
+
+export function deleteCellsShiftLeftCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  startRow: number,
+  startCol: number,
+  endRow: number,
+  endCol: number,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const width = endCol - startCol + 1;
+
+  // Snapshot deleted cells
+  const snapshot = new Map<string, { value: CellValue; displayValue: string; formula?: string; styleIndex: number; numFmtCode: string; content: CellContent }>();
+  for (let r = startRow; r <= endRow; r++) {
+    for (let c = startCol; c <= endCol; c++) {
+      const ref = rowColToRef(r, c);
+      const cell = sheet.getCell(ref);
+      if (cell) {
+        snapshot.set(ref, { value: cell.value, displayValue: cell.displayValue, formula: cell.formula, styleIndex: cell.styleIndex, numFmtCode: cell.numFmtCode, content: cell.content });
+      }
+    }
+  }
+
+  return {
+    description: `Delete cells shift left ${rowColToRef(startRow, startCol)}:${rowColToRef(endRow, endCol)}`,
+    execute() {
+      for (let r = startRow; r <= endRow; r++) {
+        for (let c = startCol; c <= endCol; c++) {
+          sheet.deleteCell(rowColToRef(r, c));
+        }
+        const toMove: Array<{ col: number; ref: string }> = [];
+        for (const [ref] of sheet.cells) {
+          const rc = refToRowColSafe(ref);
+          if (rc && rc.row === r && rc.col > endCol) toMove.push({ col: rc.col, ref });
+        }
+        toMove.sort((a, b) => a.col - b.col); // left-to-right
+        for (const { ref, col } of toMove) {
+          const cell = sheet.cells.get(ref)!;
+          sheet.cells.delete(ref);
+          sheet.cells.set(rowColToRef(r, col - width), cell);
+        }
+      }
+    },
+    undo() {
+      for (let r = startRow; r <= endRow; r++) {
+        const toMove: Array<{ col: number; ref: string }> = [];
+        for (const [ref] of sheet.cells) {
+          const rc = refToRowColSafe(ref);
+          if (rc && rc.row === r && rc.col >= startCol) toMove.push({ col: rc.col, ref });
+        }
+        toMove.sort((a, b) => b.col - a.col); // right-to-left
+        for (const { ref, col } of toMove) {
+          const cell = sheet.cells.get(ref)!;
+          sheet.cells.delete(ref);
+          sheet.cells.set(rowColToRef(r, col + width), cell);
+        }
+      }
+      for (const [ref, snap] of snapshot) {
+        sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
+      }
+    },
+  };
+}
+
+// =============================================================================
+// Set Show Grid Lines
+// =============================================================================
+
+export function setShowGridLinesCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  show: boolean,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const oldValue = sheet.view.showGridLines;
+
+  return {
+    description: show ? "Show grid lines" : "Hide grid lines",
+    execute() {
+      sheet.view.showGridLines = show;
+    },
+    undo() {
+      sheet.view.showGridLines = oldValue;
+    },
+  };
+}
+
+// =============================================================================
+// Set Show Headers
+// =============================================================================
+
+export function setShowHeadersCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  show: boolean,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const oldValue = sheet.view.showHeaders;
+
+  return {
+    description: show ? "Show headers" : "Hide headers",
+    execute() {
+      sheet.view.showHeaders = show;
+    },
+    undo() {
+      sheet.view.showHeaders = oldValue;
+    },
+  };
+}
+
+// =============================================================================
+// Set Hyperlink
+// =============================================================================
+
+export function setHyperlinkCommand(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  ref: string,
+  url: string | undefined,
+): Command {
+  const sheet = workbook.sheets[sheetIndex];
+  const oldUrl = sheet.hyperlinks.get(ref);
+  const cell = sheet.getCell(ref);
+  const oldContent = cell?.content;
+
+  return {
+    description: url ? `Set hyperlink on ${ref}` : `Remove hyperlink from ${ref}`,
+    execute() {
+      if (url) {
+        sheet.hyperlinks.set(ref, url);
+      } else {
+        sheet.hyperlinks.delete(ref);
+      }
+      // Rebuild content to reflect hyperlink change
+      const c = sheet.getCell(ref);
+      if (c) {
+        const displayValue = c.displayValue;
+        if (url) {
+          c.content = { type: "hyperlink", text: displayValue, url };
+        } else {
+          c.content = { type: "plain", text: displayValue };
+        }
+      }
+    },
+    undo() {
+      if (oldUrl) {
+        sheet.hyperlinks.set(ref, oldUrl);
+      } else {
+        sheet.hyperlinks.delete(ref);
+      }
+      const c = sheet.getCell(ref);
+      if (c && oldContent) {
+        c.content = oldContent;
+      } else if (c) {
+        c.content = { type: "plain", text: c.displayValue };
+      }
+    },
+  };
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Parse user input into a typed CellValue. */
+function parseInputValue(input: string): CellValue {
+  if (input === "") return null;
+  if (input.toUpperCase() === "TRUE") return true;
+  if (input.toUpperCase() === "FALSE") return false;
+  const num = Number(input);
+  if (!isNaN(num) && input.trim() !== "") return num;
+  return input;
+}
+
+function refToRowColSafe(ref: string): { row: number; col: number } | undefined {
+  return refToRowCol(ref) ?? undefined;
+}
+
+/** Adjust all formula references in a sheet for a row insert/delete. */
+function adjustAllFormulasForRowShift(sheet: SheetModel, atRow: number, delta: number): void {
+  for (const cell of sheet.cells.values()) {
+    if (cell.formula) {
+      cell.formula = adjustFormulaRefsForRowShift(cell.formula, atRow, delta);
+    }
+  }
+}
+
+/** Adjust all formula references in a sheet for a column insert/delete. */
+function adjustAllFormulasForColShift(sheet: SheetModel, atCol: number, delta: number): void {
+  for (const cell of sheet.cells.values()) {
+    if (cell.formula) {
+      cell.formula = adjustFormulaRefsForColShift(cell.formula, atCol, delta);
+    }
+  }
+}
+
+/** Sort sheet rows in-place by a column value. */
+function sortColumnInPlace(sheet: SheetModel, col: number, ascending: boolean): void {
+  const used = sheet.getUsedRange();
+  const rows: { row: number; val: number | string | null }[] = [];
+  for (let r = used.minRow; r <= used.maxRow; r++) {
+    const ref = rowColToRef(r, col);
+    const cell = sheet.getCell(ref);
+    const val = cell?.value ?? null;
+    rows.push({ row: r, val: typeof val === "boolean" ? (val ? 1 : 0) : val });
+  }
+  rows.sort((a, b) => {
+    if (a.val === null && b.val === null) return 0;
+    if (a.val === null) return 1;
+    if (b.val === null) return -1;
+    if (typeof a.val === "number" && typeof b.val === "number") return ascending ? a.val - b.val : b.val - a.val;
+    const sa = String(a.val).toLowerCase();
+    const sb = String(b.val).toLowerCase();
+    return ascending ? sa.localeCompare(sb) : sb.localeCompare(sa);
+  });
+  // Snapshot all rows, then write back in new order
+  const allCells = new Map<string, Map<number, ReturnType<typeof sheet.getCell>>>();
+  for (let r = used.minRow; r <= used.maxRow; r++) {
+    const rowCells = new Map<number, ReturnType<typeof sheet.getCell>>();
+    for (let c = used.minCol; c <= used.maxCol; c++) {
+      const ref = rowColToRef(r, c);
+      const cell = sheet.getCell(ref);
+      if (cell) rowCells.set(c, { ...cell });
+      sheet.deleteCell(ref);
+    }
+    allCells.set(String(r), rowCells);
+  }
+  for (let i = 0; i < rows.length; i++) {
+    const sourceRow = rows[i].row;
+    const targetRow = used.minRow + i;
+    const rowCells = allCells.get(String(sourceRow));
+    if (!rowCells) continue;
+    for (const [c, cell] of rowCells) {
+      if (cell) {
+        const ref = rowColToRef(targetRow, c);
+        sheet.set(ref, cell.value, sheet.styles?.get(cell.styleIndex), cell.numFmtCode, cell.formula);
+      }
+    }
+  }
+}
+
+/** Sort sheet rows in-place by multiple column keys (cascading comparison). */
+function multiSortInPlace(sheet: SheetModel, sortSpecs: SortSpec[], startRow: number): void {
+  const used = sheet.getUsedRange();
+
+  // Build row index with sort key values
+  const rowEntries: { row: number; vals: (number | string | null)[] }[] = [];
+  for (let r = startRow; r <= used.maxRow; r++) {
+    const vals = sortSpecs.map((spec) => {
+      const ref = rowColToRef(r, spec.col);
+      const cell = sheet.getCell(ref);
+      const val = cell?.value ?? null;
+      return typeof val === "boolean" ? (val ? 1 : 0) : val;
+    });
+    rowEntries.push({ row: r, vals });
+  }
+
+  // Cascading comparison: try each sort key in order
+  rowEntries.sort((a, b) => {
+    for (let k = 0; k < sortSpecs.length; k++) {
+      const aVal = a.vals[k];
+      const bVal = b.vals[k];
+      const asc = sortSpecs[k].ascending;
+      if (aVal === null && bVal === null) continue;
+      if (aVal === null) return 1;
+      if (bVal === null) return -1;
+      if (typeof aVal === "number" && typeof bVal === "number") {
+        const diff = asc ? aVal - bVal : bVal - aVal;
+        if (diff !== 0) return diff;
+        continue;
+      }
+      const sa = String(aVal).toLowerCase();
+      const sb = String(bVal).toLowerCase();
+      const cmp = asc ? sa.localeCompare(sb) : sb.localeCompare(sa);
+      if (cmp !== 0) return cmp;
+    }
+    return 0;
+  });
+
+  // Snapshot all rows, then write back in new order
+  const allCells = new Map<string, Map<number, ReturnType<typeof sheet.getCell>>>();
+  for (let r = startRow; r <= used.maxRow; r++) {
+    const rowCells = new Map<number, ReturnType<typeof sheet.getCell>>();
+    for (let c = used.minCol; c <= used.maxCol; c++) {
+      const ref = rowColToRef(r, c);
+      const cell = sheet.getCell(ref);
+      if (cell) rowCells.set(c, { ...cell });
+      sheet.deleteCell(ref);
+    }
+    allCells.set(String(r), rowCells);
+  }
+  for (let i = 0; i < rowEntries.length; i++) {
+    const sourceRow = rowEntries[i].row;
+    const targetRow = startRow + i;
+    const rowCells = allCells.get(String(sourceRow));
+    if (!rowCells) continue;
+    for (const [c, cell] of rowCells) {
+      if (cell) {
+        const ref = rowColToRef(targetRow, c);
+        sheet.set(ref, cell.value, sheet.styles?.get(cell.styleIndex), cell.numFmtCode, cell.formula);
+      }
+    }
+  }
+}
+
+// =============================================================================
+// Merged-cell range adjustment
+// =============================================================================
+//
+// `insertRowsCommand` and `deleteRowsCommand` now own merged-cell range
+// shifting and contraction. Previously this lived as separate functions
+// callers had to remember to invoke (e.g. excel_placeholder_engine).
+
+/** Shift merged-cell ranges to accommodate a row insertion at `atRow`. */
+export function adjustMergedCellsForRowInsert(sheet: SheetModel, atRow: number, count: number): void {
+  sheet.mergedCells = sheet.mergedCells.map((range) => {
+    const [startRef, endRef] = range.split(":");
+    const start = refToRowCol(startRef);
+    const end = refToRowCol(endRef);
+    if (!start || !end) return range;
+
+    let r1 = start.row;
+    let r2 = end.row;
+
+    if (r1 >= atRow) {
+      r1 += count;
+      r2 += count;
+    } else if (r2 >= atRow) {
+      r2 += count;
+    }
+
+    return `${rowColToRef(r1, start.col)}:${rowColToRef(r2, end.col)}`;
+  });
+}
+
+/**
+ * Adjust merged-cell ranges after a row deletion. Ranges fully inside the
+ * deleted span are dropped, overlapping ranges are contracted, and ranges
+ * entirely after the deletion shift up.
+ */
+export function adjustMergedCellsForRowDelete(sheet: SheetModel, atRow: number, count: number): void {
+  const endRow = atRow + count - 1;
+  const updated: string[] = [];
+  for (const range of sheet.mergedCells) {
+    const [startRef, endRef] = range.split(":");
+    const start = refToRowCol(startRef);
+    const end = refToRowCol(endRef);
+    if (!start || !end) {
+      updated.push(range);
+      continue;
+    }
+
+    let r1 = start.row;
+    let r2 = end.row;
+
+    if (r1 > endRow) {
+      r1 -= count;
+      r2 -= count;
+    } else if (r2 < atRow) {
+      // unchanged
+    } else if (r1 >= atRow && r2 <= endRow) {
+      continue;
+    } else if (r1 < atRow && r2 > endRow) {
+      r2 -= count;
+    } else if (r1 < atRow) {
+      r2 = atRow - 1;
+    } else {
+      r1 = atRow;
+      r2 -= count;
+    }
+
+    if (r2 < r1) continue;
+    updated.push(`${rowColToRef(r1, start.col)}:${rowColToRef(r2, end.col)}`);
+  }
+  sheet.mergedCells = updated;
+}
+
+/** Shift merged-cell ranges to accommodate a column insertion at `atCol`. */
+export function adjustMergedCellsForColInsert(sheet: SheetModel, atCol: number, count: number): void {
+  sheet.mergedCells = sheet.mergedCells.map((range) => {
+    const [startRef, endRef] = range.split(":");
+    const start = refToRowCol(startRef);
+    const end = refToRowCol(endRef);
+    if (!start || !end) return range;
+
+    let c1 = start.col;
+    let c2 = end.col;
+
+    if (c1 >= atCol) {
+      c1 += count;
+      c2 += count;
+    } else if (c2 >= atCol) {
+      c2 += count;
+    }
+
+    return `${rowColToRef(start.row, c1)}:${rowColToRef(end.row, c2)}`;
+  });
+}
+
+/** Adjust merged-cell ranges after a column deletion. Mirrors the row variant. */
+export function adjustMergedCellsForColDelete(sheet: SheetModel, atCol: number, count: number): void {
+  const endCol = atCol + count - 1;
+  const updated: string[] = [];
+  for (const range of sheet.mergedCells) {
+    const [startRef, endRef] = range.split(":");
+    const start = refToRowCol(startRef);
+    const end = refToRowCol(endRef);
+    if (!start || !end) {
+      updated.push(range);
+      continue;
+    }
+
+    let c1 = start.col;
+    let c2 = end.col;
+
+    if (c1 > endCol) {
+      c1 -= count;
+      c2 -= count;
+    } else if (c2 < atCol) {
+      // unchanged
+    } else if (c1 >= atCol && c2 <= endCol) {
+      continue;
+    } else if (c1 < atCol && c2 > endCol) {
+      c2 -= count;
+    } else if (c1 < atCol) {
+      c2 = atCol - 1;
+    } else {
+      c1 = atCol;
+      c2 -= count;
+    }
+
+    if (c2 < c1) continue;
+    updated.push(`${rowColToRef(start.row, c1)}:${rowColToRef(end.row, c2)}`);
+  }
+  sheet.mergedCells = updated;
+}
+
+// =============================================================================
+// Formula range expansion
+// =============================================================================
+
+/**
+ * After inserting rows inside a region used by a range formula (e.g.
+ * `SUM(C5:C5)` with template row 5 + 9 inserted rows → `SUM(C5:C14)`),
+ * widen any range whose end exactly matches the template's last row.
+ *
+ * Used by the Excel template placeholder engine when expanding `{{#each}}`
+ * blocks. Lives in the command layer so future callers don't have to
+ * reimplement it.
+ */
+export function expandFormulaRangesForRowInsert(
+  sheet: SheetModel,
+  templateStartRow: number,
+  templateEndRow: number,
+  insertedCount: number,
+): void {
+  const rangeRe = /(\$?)([A-Z]+)(\$?)(\d+):(\$?)([A-Z]+)(\$?)(\d+)/g;
+
+  for (const [ref, cell] of sheet.cells) {
+    if (!cell.formula) continue;
+
+    const newFormula = cell.formula.replace(
+      rangeRe,
+      (match, ca1, c1, ra1, r1s, ca2, c2, ra2, r2s) => {
+        const r1 = parseInt(r1s, 10);
+        const r2 = parseInt(r2s, 10);
+
+        if (r1 <= templateStartRow && r2 === templateEndRow) {
+          return `${ca1}${c1}${ra1}${r1}:${ca2}${c2}${ra2}${r2 + insertedCount}`;
+        }
+        return match;
+      },
+    );
+
+    if (newFormula !== cell.formula) {
+      sheet.set(ref, cell.value, sheet.styles?.get(cell.styleIndex), cell.numFmtCode, newFormula);
+    }
+  }
+}