@mog-sdk/node 0.1.10 → 0.1.11

package/dist/index.js

@@ -1311,6 +1311,106 @@ var init_schemas = __esm({
   }
 });
 
+// ../../kernel/src/api/worksheet/change-accumulator.ts
+function colToLetter(col) {
+  let result = "";
+  let c = col;
+  while (c >= 0) {
+    result = String.fromCharCode(c % 26 + 65) + result;
+    c = Math.floor(c / 26) - 1;
+  }
+  return result;
+}
+function toA1(row, col) {
+  return `${colToLetter(col)}${row + 1}`;
+}
+var ChangeAccumulator;
+var init_change_accumulator = __esm({
+  "../../kernel/src/api/worksheet/change-accumulator.ts"() {
+    "use strict";
+    init_esm_shims();
+    ChangeAccumulator = class {
+      constructor() {
+        this.trackers = /* @__PURE__ */ new Set();
+        /**
+         * Pending direct edits set before a mutation, consumed by the next ingest().
+         * Since JS is single-threaded, setDirectEdits() before the bridge call
+         * guarantees these are consumed by the corresponding ingest().
+         */
+        this.pendingDirectEdits = null;
+      }
+      /**
+       * Set the direct edit positions for the next mutation.
+       * Called by cell-operations before triggering the bridge call.
+       * Consumed (cleared) by the next ingest() call.
+       */
+      setDirectEdits(edits) {
+        this.pendingDirectEdits = edits;
+      }
+      /**
+       * Called by MutationResultHandler after every mutation.
+       *
+       * @param changedCells - RecalcResult.changedCells from the MutationResult
+       * @param directEdits - The (sheetId, row, col) tuples that were directly written
+       *                      (to distinguish direct vs cascade)
+       * @param source - user or remote
+       */
+      ingest(changedCells, directEdits, source) {
+        if (this.trackers.size === 0) {
+          this.pendingDirectEdits = null;
+          return;
+        }
+        if (changedCells.length === 0) {
+          this.pendingDirectEdits = null;
+          return;
+        }
+        const edits = directEdits ?? this.pendingDirectEdits;
+        this.pendingDirectEdits = null;
+        const directSet = /* @__PURE__ */ new Set();
+        if (edits) {
+          for (const e of edits) {
+            directSet.add(`${e.sheetId}:${e.row}:${e.col}`);
+          }
+        }
+        const recordsBySheet = /* @__PURE__ */ new Map();
+        for (const cell of changedCells) {
+          const key = `${cell.sheetId}:${cell.row}:${cell.col}`;
+          const origin = source === "remote" ? "remote" : directSet.has(key) ? "direct" : "cascade";
+          const record = {
+            address: toA1(cell.row, cell.col),
+            row: cell.row,
+            col: cell.col,
+            origin,
+            type: "modified"
+          };
+          let list = recordsBySheet.get(cell.sheetId);
+          if (!list) {
+            list = [];
+            recordsBySheet.set(cell.sheetId, list);
+          }
+          list.push(record);
+        }
+        for (const tracker of this.trackers) {
+          const records = recordsBySheet.get(tracker.sheetId);
+          if (records && records.length > 0) {
+            tracker._ingest(records);
+          }
+        }
+      }
+      register(tracker) {
+        this.trackers.add(tracker);
+      }
+      unregister(tracker) {
+        this.trackers.delete(tracker);
+      }
+      /** Number of active trackers. */
+      get activeCount() {
+        return this.trackers.size;
+      }
+    };
+  }
+});
+
 // ../../kernel/src/bridges/mutation-result-handler.ts
 function resolvedPosition(row, col) {
   if (row === POSITION_SENTINEL || col === POSITION_SENTINEL) {
@@ -1323,6 +1423,7 @@ var init_mutation_result_handler = __esm({
   "../../kernel/src/bridges/mutation-result-handler.ts"() {
     "use strict";
     init_esm_shims();
+    init_change_accumulator();
     POSITION_SENTINEL = 4294967295;
     MutationResultHandler = class {
       constructor(eventBus, onUndoDescription) {
@@ -1332,6 +1433,7 @@ var init_mutation_result_handler = __esm({
         this.errorCallbacks = [];
         this.eventBus = eventBus;
         this.onUndoDescription = onUndoDescription;
+        this.changeAccumulator = new ChangeAccumulator();
       }
       /** Set the ViewportCoordinatorRegistry for per-viewport dimension patching. */
       setCoordinatorRegistry(registry2) {
@@ -1353,8 +1455,9 @@ var init_mutation_result_handler = __esm({
        *
        * @param result - MutationResult from a Rust IPC command
        * @param source - Whether this mutation originated from the local user or remote collaboration
+       * @param directEdits - Optional positions of directly-written cells (to distinguish direct vs cascade)
        */
-      applyAndNotify(result, source = "user") {
+      applyAndNotify(result, source = "user", directEdits) {
         if (result.recalc) {
           this.handleRecalcResult(result.recalc, source);
         }
@@ -1415,6 +1518,9 @@ var init_mutation_result_handler = __esm({
         if (result.undoDescription) {
           this.handleUndoDescription(result.undoDescription);
         }
+        if (this.changeAccumulator.activeCount > 0 && result.recalc?.changedCells?.length) {
+          this.changeAccumulator.ingest(result.recalc.changedCells, directEdits ?? null, source);
+        }
       }
       /**
        * Register an error callback for mutation failures.
@@ -5978,6 +6084,9 @@ var init_compute_bridge_gen = __esm({
       getCellFormatWithCf(sheetId, cellId, row, col) {
         return this.core.query(this.core.transport.call("compute_get_cell_format_with_cf", { docId: this.core.docId, sheetId, cellId, row, col }));
       }
+      getResolvedFormat(sheetId, row, col) {
+        return this.core.query(this.core.transport.call("compute_get_resolved_format", { docId: this.core.docId, sheetId, row, col }));
+      }
       setCellFormat(sheetId, cellId, format) {
         return this.core.mutatePlain(this.core.transport.call("compute_set_cell_format", { docId: this.core.docId, sheetId, cellId, format }));
       }
@@ -7784,16 +7893,18 @@ var init_core_defaults = __esm({
 async function getMeta(ctx, sheetId) {
   const name = await ctx.computeBridge.getSheetName(sheetId);
   if (name === null) return void 0;
-  const [frozen, tabColor, hidden] = await Promise.all([
+  const [frozen, tabColor, hidden, defaultRowHeight, defaultColWidth] = await Promise.all([
     ctx.computeBridge.getFrozenPanesQuery(sheetId),
     ctx.computeBridge.getTabColorQuery(sheetId),
-    ctx.computeBridge.isSheetHidden(sheetId)
+    ctx.computeBridge.isSheetHidden(sheetId),
+    ctx.computeBridge.getDefaultRowHeight(sheetId),
+    ctx.computeBridge.getDefaultColWidth(sheetId)
   ]);
   return {
     id: sheetId,
     name,
-    defaultRowHeight: 20,
-    defaultColWidth: 100,
+    defaultRowHeight,
+    defaultColWidth,
     frozenRows: frozen.rows,
     frozenCols: frozen.cols,
     tabColor: tabColor ?? void 0,
@@ -7840,7 +7951,7 @@ var init_range = __esm({
 });
 
 // ../../spreadsheet-utils/src/a1.ts
-function colToLetter2(col) {
+function colToLetter3(col) {
   if (col < 0) {
     throw new Error("Column number must be >= 0");
   }
@@ -7860,8 +7971,8 @@ function letterToCol(letters) {
   }
   return result - 1;
 }
-function toA1(row, col) {
-  return `${colToLetter2(col)}${row + 1}`;
+function toA12(row, col) {
+  return `${colToLetter3(col)}${row + 1}`;
 }
 function parseCellAddress(ref) {
   const match = ref.match(CELL_ADDRESS_REGEX);
@@ -77295,6 +77406,10 @@ async function getRefersToA1(ctx, name) {
   const a1 = await ctx.computeBridge.toA1Display(NIL_SHEET_ID, wire);
   return a1.startsWith("=") ? a1 : `=${a1}`;
 }
+async function getVisible(ctx) {
+  const rustNames = await ctx.computeBridge.getVisibleNamedRanges();
+  return rustNames.map(mapRustNamedRange);
+}
 async function create2(ctx, input, contextSheet, _origin = "user") {
   const formula = await ctx.computeBridge.toIdentityFormula(contextSheet, input.refersToA1);
   const rawFormula = formula;
@@ -77380,7 +77495,7 @@ async function update2(ctx, id, updates, contextSheet, _origin = "user") {
   }
   const newName = updates.name ?? existing.name;
   if (newName !== existing.name) {
-    void ctx.computeBridge.removeNamedRange(existing.name);
+    void ctx.computeBridge.removeNamedRangeById(existing.id);
   }
   let refersToWire = identityFormulaToWire(existing.refersTo);
   if (updates.refersToA1) {
@@ -77467,7 +77582,7 @@ async function remove(ctx, id, _origin = "user") {
   if (!existing) {
     throw new KernelError("DOMAIN_DEFINED_NAME_NOT_FOUND", `Defined name with ID ${id} not found`);
   }
-  void ctx.computeBridge.removeNamedRange(existing.name);
+  void ctx.computeBridge.removeNamedRangeById(existing.id);
 }
 async function exportNames(ctx) {
   const all = await getAll(ctx);
@@ -77492,7 +77607,7 @@ function sanitizeLabel(label) {
   }
   return name;
 }
-function colToLetter(col) {
+function colToLetter2(col) {
   let result = "";
   let c = col;
   while (c >= 0) {
@@ -77566,7 +77681,7 @@ async function createFromSelection(ctx, sheetId, range2, options, _origin = "use
       result.skippedReasons.push({ label: name, reason: validation.message ?? "invalid name" });
       return;
     }
-    const refersToA1 = refStartRow === refEndRow && refStartCol === refEndCol ? `=$${colToLetter(refStartCol)}$${refStartRow + 1}` : `=$${colToLetter(refStartCol)}$${refStartRow + 1}:$${colToLetter(refEndCol)}$${refEndRow + 1}`;
+    const refersToA1 = refStartRow === refEndRow && refStartCol === refEndCol ? `=$${colToLetter2(refStartCol)}$${refStartRow + 1}` : `=$${colToLetter2(refStartCol)}$${refStartRow + 1}:$${colToLetter2(refEndCol)}$${refEndRow + 1}`;
     try {
       await create2(ctx, { name: sanitized, refersToA1 }, sheetId);
       existingKeys.add(key);
@@ -78838,6 +78953,7 @@ init_cell_properties();
 var MAX_RANGE_CELLS = 1e4;
 var MAX_RANGE_BOUNDING_BOX = 5e5;
 var MAX_DESCRIBE_OUTPUT_CHARS = 5e4;
+var MAX_SUMMARY_NAMED_RANGES = 20;
 async function getStyleHints(ctx, sheetId, row, col) {
   const format = await getFormat(ctx, sheetId, row, col);
   if (!format) return null;
@@ -78927,7 +79043,7 @@ function generateFormulaDocumentation(analysis) {
   const lines = [""];
   for (const info of significantPatterns) {
     const examples = info.cells.slice(0, 2).map((cell) => {
-      const addr = `${colToLetter2(cell.col)}${cell.row + 1}`;
+      const addr = `${colToLetter3(cell.col)}${cell.row + 1}`;
       return `${addr}: =${cell.formula}`;
     });
     const exampleStr = examples.length > 0 ? `  (e.g. ${examples.join(", ")})` : "";
@@ -78986,7 +79102,7 @@ function buildLeftContext(leftCells, startRow, startCol, endRow) {
     found.sort((a, b) => a.col - b.col);
     const tokens = found.map((f) => {
       const prefix = "\u2192".repeat(Math.max(0, f.indent));
-      const addr = `${colToLetter2(f.col)}${row + 1}`;
+      const addr = `${colToLetter3(f.col)}${row + 1}`;
       return `${prefix}${addr}:${f.text}`;
     });
     lines.push(tokens.join(" | "));
@@ -79058,7 +79174,7 @@ function buildAboveContext(aboveCells, startRow, startCol, endCol) {
       sawNumeric = true;
       continue;
     }
-    const addr = `${colToLetter2(c)}${bestRow + 1}`;
+    const addr = `${colToLetter3(c)}${bestRow + 1}`;
     if (tokens.length > 0 && sawNumeric) tokens.push("...");
     tokens.push(`${addr}:${d}`);
     sawNumeric = false;
@@ -79116,8 +79232,8 @@ function consolidateRanges(cells) {
         covered.add(`${r},${c}`);
       }
     }
-    const start = `${colToLetter2(cell.col)}${cell.row + 1}`;
-    const end = `${colToLetter2(endCol)}${endRow + 1}`;
+    const start = `${colToLetter3(cell.col)}${cell.row + 1}`;
+    const end = `${colToLetter3(endCol)}${endRow + 1}`;
     ranges.push(start === end ? start : `${start}:${end}`);
   }
   return ranges;
@@ -79188,9 +79304,12 @@ async function getDisplayValue(ctx, sheetId, row, col) {
 async function getCell(ctx, sheetId, row, col) {
   const data = await getData(ctx, sheetId, row, col);
   if (!data) return void 0;
+  const fmt = await getFormat(ctx, sheetId, row, col);
   return {
     value: (data.formula !== void 0 ? data.computed : rawToCellValue(data.raw)) ?? null,
-    formula: data.formula
+    formula: data.formula,
+    format: fmt ?? void 0,
+    formatted: await getDisplayValue(ctx, sheetId, row, col) ?? void 0
   };
 }
 async function getDisplayValue2(ctx, sheetId, row, col) {
@@ -79211,10 +79330,11 @@ async function setCell(ctx, sheetId, row, col, value) {
     throw KernelError.from(null, "COMPUTE_ERROR", `Invalid cell address: row=${row}, col=${col}`);
   }
   const input = value === null || value === void 0 ? "" : value === "" ? "\0" : String(value);
-  const result = await ctx.computeBridge.setCellsByPosition(sheetId, [{ row, col, input }]);
+  ctx.computeBridge.getMutationHandler()?.changeAccumulator.setDirectEdits([{ sheetId, row, col }]);
+  await ctx.computeBridge.setCellsByPosition(sheetId, [{ row, col, input }]);
 }
 async function setCells(ctx, sheetId, cells) {
-  if (cells.length === 0) return { cellsWritten: 0 };
+  if (cells.length === 0) return { cellsWritten: 0, errors: null };
   const edits = cells.map((cell) => {
     let row;
     let col;
@@ -79236,8 +79356,11 @@ async function setCells(ctx, sheetId, cells) {
   }
   const uniqueEdits = Array.from(deduped.values());
   const duplicatesRemoved = edits.length - uniqueEdits.length;
+  ctx.computeBridge.getMutationHandler()?.changeAccumulator.setDirectEdits(
+    uniqueEdits.map((e) => ({ sheetId, row: e.row, col: e.col }))
+  );
   await ctx.computeBridge.setCellsByPosition(sheetId, uniqueEdits);
-  const result = { cellsWritten: uniqueEdits.length };
+  const result = { cellsWritten: uniqueEdits.length, errors: null };
   if (duplicatesRemoved > 0) {
     result.warnings = [
       createWarning("API_DUPLICATE_COORDINATES", `${duplicatesRemoved} duplicate coordinate(s) resolved by last-write-wins`, {
@@ -79343,7 +79466,7 @@ async function batchGetCellPositions(ctx, sheetId, cellIds) {
 
 // ../../kernel/src/api/worksheet/operations/dependency-operations.ts
 init_esm_shims();
-function colToLetter3(col) {
+function colToLetter4(col) {
   let result = "";
   let c = col;
   while (c >= 0) {
@@ -79354,11 +79477,11 @@ function colToLetter3(col) {
 }
 async function getDependents(ctx, sheetId, row, col) {
   const results = await ctx.computeBridge.getDependents(sheetId, row, col);
-  return results.map((r) => `${colToLetter3(r.col)}${r.row + 1}`);
+  return results.map((r) => `${colToLetter4(r.col)}${r.row + 1}`);
 }
 async function getPrecedents(ctx, sheetId, row, col) {
   const results = await ctx.computeBridge.getPrecedents(sheetId, row, col);
-  return results.map((r) => `${colToLetter3(r.col)}${r.row + 1}`);
+  return results.map((r) => `${colToLetter4(r.col)}${r.row + 1}`);
 }
 
 // ../../kernel/src/api/worksheet/operations/fill-operations.ts
@@ -79411,7 +79534,8 @@ async function autoFill(ctx, sheetId, sourceRange, targetRange, mode) {
   return {
     patternType: fillData?.patternType ?? "copy",
     filledCellCount: fillData?.filledCellCount ?? 0,
-    warnings: fillData?.warnings ?? []
+    warnings: fillData?.warnings ?? [],
+    changes: fillData?.changes ?? []
   };
 }
 function splitRangeForSeries(range2, direction) {
@@ -79735,14 +79859,14 @@ async function regexSearch(ctx, sheetId, patterns, options) {
     for (const { regex, source } of compiledPatterns) {
       regex.lastIndex = 0;
       if (regex.test(valueStr)) {
-        const address = `${colToLetter2(cell.col)}${cell.row + 1}`;
+        const address = `${colToLetter3(cell.col)}${cell.row + 1}`;
         results.push({ address, value: valueStr, sheetName, matchedPattern: source });
         break;
       }
       if (options?.includeFormulas && cell.formula) {
         regex.lastIndex = 0;
         if (regex.test(cell.formula)) {
-          const address = `${colToLetter2(cell.col)}${cell.row + 1}`;
+          const address = `${colToLetter3(cell.col)}${cell.row + 1}`;
           results.push({ address, value: valueStr, sheetName, matchedPattern: source });
           break;
         }
@@ -79898,7 +80022,7 @@ async function clearRange2(ctx, sheetId, range2) {
         }
       }
     }
-    return { success: true, data: void 0, affectedCells };
+    return { success: true, data: { cellCount }, affectedCells };
   } catch (e) {
     return {
       success: false,
@@ -79930,6 +80054,8 @@ async function clearWithMode(ctx, sheetId, range2, applyTo = "all") {
     promises.push(clearHyperlinksInRange(ctx, sheetId, n));
   }
   await Promise.all(promises);
+  const cellCount = (n.endRow - n.startRow + 1) * (n.endCol - n.startCol + 1);
+  return { cellCount };
 }
 async function clearHyperlinksInRange(ctx, sheetId, range2) {
   const rangeResult = await ctx.computeBridge.queryRange(
@@ -80048,7 +80174,7 @@ async function findInRange(ctx, sheetId, range2, text, options) {
     const valueStr = cell.formatted ?? viewportCellValueToString(cell.value);
     if (pattern.test(valueStr)) {
       return {
-        address: `${colToLetter2(cell.col)}${cell.row + 1}`,
+        address: `${colToLetter3(cell.col)}${cell.row + 1}`,
         value: valueStr
       };
     }
@@ -80935,6 +81061,84 @@ var WorksheetBindingsImpl = class {
   }
 };
 
+// ../../kernel/src/api/worksheet/index.ts
+init_change_accumulator();
+
+// ../../kernel/src/api/worksheet/changes.ts
+init_esm_shims();
+function parseRangeScope(scope) {
+  const match = scope.match(/^([A-Z]+)(\d+):([A-Z]+)(\d+)$/i);
+  if (!match) return null;
+  const startCol = letterToCol2(match[1].toUpperCase());
+  const startRow = parseInt(match[2], 10) - 1;
+  const endCol = letterToCol2(match[3].toUpperCase());
+  const endRow = parseInt(match[4], 10) - 1;
+  return { startRow, startCol, endRow, endCol };
+}
+function letterToCol2(letters) {
+  let col = 0;
+  for (let i = 0; i < letters.length; i++) {
+    col = col * 26 + (letters.charCodeAt(i) - 64);
+  }
+  return col - 1;
+}
+var ChangeTrackerImpl = class {
+  constructor(sheetId, options, unregister) {
+    this._active = true;
+    this.buffer = [];
+    this.sheetId = sheetId;
+    this.unregister = unregister;
+    this.scopeBounds = options?.scope ? parseRangeScope(options.scope) : null;
+    this.excludeOrigins = options?.excludeOrigins && options.excludeOrigins.length > 0 ? new Set(options.excludeOrigins) : null;
+  }
+  // --- TrackerHandle (called by ChangeAccumulator) ---
+  _ingest(records) {
+    if (!this._active) return;
+    for (const record of records) {
+      if (this.excludeOrigins?.has(record.origin)) continue;
+      if (this.scopeBounds) {
+        const { startRow, startCol, endRow, endCol } = this.scopeBounds;
+        if (record.row < startRow || record.row > endRow || record.col < startCol || record.col > endCol) {
+          continue;
+        }
+      }
+      this.buffer.push(record);
+    }
+  }
+  // --- ChangeTracker public API ---
+  collect() {
+    const result = this.buffer;
+    this.buffer = [];
+    return result;
+  }
+  close() {
+    if (!this._active) return;
+    this._active = false;
+    this.buffer = [];
+    this.unregister();
+  }
+  get active() {
+    return this._active;
+  }
+};
+var WorksheetChangesImpl = class {
+  constructor(ctx, sheetId) {
+    this.ctx = ctx;
+    this.sheetId = sheetId;
+  }
+  track(options) {
+    const accumulator = this.ctx.computeBridge.getMutationHandler()?.changeAccumulator;
+    if (!accumulator) {
+      throw new Error("Change tracking unavailable: MutationResultHandler not initialized");
+    }
+    const tracker = new ChangeTrackerImpl(this.sheetId, options, () => {
+      accumulator.unregister(tracker);
+    });
+    accumulator.register(tracker);
+    return tracker;
+  }
+};
+
 // ../../kernel/src/api/worksheet/charts.ts
 init_esm_shims();
 function buildStatisticalExtra(config) {
@@ -81364,7 +81568,7 @@ function cellRefToA1(cellRef) {
   const col = parseInt(parts[0], 10);
   const row = parseInt(parts[1], 10);
   if (isNaN(col) || isNaN(row)) return cellRef;
-  return toA1(row, col);
+  return toA12(row, col);
 }
 function toApiComment(c) {
   const text = c.content ?? c.runs.map((r) => r.text).join("");
@@ -81465,7 +81669,7 @@ var WorksheetCommentsImpl = class {
     return {
       content,
       author: first.author,
-      cellAddress: toA1(row, col)
+      cellAddress: toA12(row, col)
     };
   }
   async removeNote(a, b) {
@@ -81808,7 +82012,7 @@ var WorksheetFiltersImpl = class {
       }
     }
     return {
-      range: `${toA1(filter.startRow ?? 0, filter.startCol ?? 0)}:${toA1(filter.endRow ?? 0, filter.endCol ?? 0)}`,
+      range: `${toA12(filter.startRow ?? 0, filter.startCol ?? 0)}:${toA12(filter.endRow ?? 0, filter.endCol ?? 0)}`,
       columns
     };
   }
@@ -82183,7 +82387,8 @@ var WorksheetFormatsImpl = class {
       col = b;
       format = c;
     }
-    await this.ctx.computeBridge.setFormatForRanges(this.sheetId, [[row, col, row, col]], format);
+    const result = await this.ctx.computeBridge.setFormatForRanges(this.sheetId, [[row, col, row, col]], format);
+    return { cellCount: result.propertyChanges?.length ?? 0 };
   }
   async setRange(a, b) {
     let range2;
@@ -82195,11 +82400,12 @@ var WorksheetFormatsImpl = class {
       range2 = a;
     }
     const n = normalizeRange(range2);
-    await this.ctx.computeBridge.setFormatForRanges(
+    const result = await this.ctx.computeBridge.setFormatForRanges(
       this.sheetId,
       [[n.startRow, n.startCol, n.endRow, n.endCol]],
       b
     );
+    return { cellCount: result.propertyChanges?.length ?? 0 };
   }
   async setRanges(ranges, format) {
     const boundedRanges = [];
@@ -82230,9 +82436,7 @@ var WorksheetFormatsImpl = class {
   }
   async get(a, b) {
     const { row, col } = resolveCell(a, b);
-    const result = await this.ctx.computeBridge.queryRange(this.sheetId, row, col, row, col);
-    if (!result?.cells || result.cells.length === 0) return null;
-    return result.cells[0]?.format ?? null;
+    return this.ctx.computeBridge.getResolvedFormat(this.sheetId, row, col);
   }
   async adjustIndent(a, b, c) {
     let row, col, amount;
@@ -82256,7 +82460,8 @@ var WorksheetFormatsImpl = class {
   async clearFill(a, b) {
     const { row, col } = resolveCell(a, b);
     const rangeTuple = [row, col, row, col];
-    const current = await this.get(row, col);
+    const result = await this.ctx.computeBridge.queryRange(this.sheetId, row, col, row, col);
+    const current = result?.cells?.[0]?.format ?? null;
     await this.ctx.computeBridge.clearFormatForRanges(this.sheetId, [rangeTuple]);
     if (current) {
       const { backgroundColor, patternType, patternForegroundColor, gradientFill, ...rest } = current;
@@ -83016,8 +83221,8 @@ init_esm_shims();
 init_errors();
 function formatDataSource(sourceSheetName, sourceRange) {
   if (!sourceRange) return "";
-  const start = toA1(sourceRange.startRow, sourceRange.startCol);
-  const end = toA1(sourceRange.endRow, sourceRange.endCol);
+  const start = toA12(sourceRange.startRow, sourceRange.startCol);
+  const end = toA12(sourceRange.endRow, sourceRange.endCol);
   const sheetRef = sourceSheetName ?? "Unknown";
   const needsQuotes = /[^A-Za-z0-9_]/.test(sheetRef);
   const quotedSheet = needsQuotes ? `'${sheetRef}'` : sheetRef;
@@ -83109,7 +83314,7 @@ var WorksheetPivotsImpl = class _WorksheetPivotsImpl {
     }
     return pivots.map((p) => {
       const apiConfig = dataConfigToApiConfig(p, p.sourceSheetName);
-      const location = p.outputLocation ? toA1(p.outputLocation.row, p.outputLocation.col) : void 0;
+      const location = p.outputLocation ? toA12(p.outputLocation.row, p.outputLocation.col) : void 0;
       return {
         name: p.name ?? p.id,
         dataSource: apiConfig.dataSource,
@@ -83642,7 +83847,7 @@ function parseCellRef2(ref) {
   }
   return { row: rowNum - 1, col: col - 1 };
 }
-function colToLetter4(col) {
+function colToLetter5(col) {
   let result = "";
   let c = col;
   while (c >= 0) {
@@ -83652,8 +83857,8 @@ function colToLetter4(col) {
   return result;
 }
 function printRangeToA1(range2) {
-  const startRef = `${colToLetter4(range2.startCol)}${range2.startRow + 1}`;
-  const endRef = `${colToLetter4(range2.endCol)}${range2.endRow + 1}`;
+  const startRef = `${colToLetter5(range2.startCol)}${range2.startRow + 1}`;
+  const endRef = `${colToLetter5(range2.endCol)}${range2.endRow + 1}`;
   return `${startRef}:${endRef}`;
 }
 async function getPageBreaks(ctx, sheetId) {
@@ -84053,7 +84258,11 @@ var WorksheetSlicersImpl = class {
     this.sheetId = sheetId;
   }
   async add(config) {
-    const storedConfig = config;
+    const caption = config.caption ?? config.name ?? "";
+    const storedConfig = {
+      ...config,
+      caption
+    };
     await this.ctx.computeBridge.createSlicer(this.sheetId, storedConfig);
     return storedConfig.id ?? "";
   }
@@ -84767,7 +84976,7 @@ var WorksheetStructureImpl = class {
   async getMergedRegions() {
     const regions = await getAll3(this.ctx, this.sheetId);
     return regions.map((r) => ({
-      range: `${toA1(r.startRow, r.startCol)}:${toA1(r.endRow, r.endCol)}`,
+      range: `${toA12(r.startRow, r.startCol)}:${toA12(r.endRow, r.endCol)}`,
       startRow: r.startRow,
       startCol: r.startCol,
       endRow: r.endRow,
@@ -84830,8 +85039,8 @@ function parseA1Range(range2) {
   };
 }
 function bridgeTableToTableInfo(table) {
-  const startLetter = colToLetter2(table.range.startCol);
-  const endLetter = colToLetter2(table.range.endCol);
+  const startLetter = colToLetter3(table.range.startCol);
+  const endLetter = colToLetter3(table.range.endCol);
   const startRowA1 = table.range.startRow + 1;
   const endRowA1 = table.range.endRow + 1;
   const range2 = `${startLetter}${startRowA1}:${endLetter}${endRowA1}`;
@@ -84876,16 +85085,16 @@ function getDataBodyRangeFromInfo(table) {
   const dataStartRow = table.hasHeaders ? parsed.startRow + 1 : parsed.startRow;
   const dataEndRow = table.showTotals ? parsed.endRow - 1 : parsed.endRow;
   if (dataStartRow > dataEndRow) return null;
-  const startLetter = colToLetter2(parsed.startCol);
-  const endLetter = colToLetter2(parsed.endCol);
+  const startLetter = colToLetter3(parsed.startCol);
+  const endLetter = colToLetter3(parsed.endCol);
   return `${startLetter}${dataStartRow + 1}:${endLetter}${dataEndRow + 1}`;
 }
 function getHeaderRowRangeFromInfo(table) {
   if (!table.hasHeaders) return null;
   const parsed = parseA1Range(table.range);
   if (!parsed) return null;
-  const startLetter = colToLetter2(parsed.startCol);
-  const endLetter = colToLetter2(parsed.endCol);
+  const startLetter = colToLetter3(parsed.startCol);
+  const endLetter = colToLetter3(parsed.endCol);
   const headerRow = parsed.startRow + 1;
   return `${startLetter}${headerRow}:${endLetter}${headerRow}`;
 }
@@ -84893,8 +85102,8 @@ function getTotalRowRangeFromInfo(table) {
   if (!table.showTotals) return null;
   const parsed = parseA1Range(table.range);
   if (!parsed) return null;
-  const startLetter = colToLetter2(parsed.startCol);
-  const endLetter = colToLetter2(parsed.endCol);
+  const startLetter = colToLetter3(parsed.startCol);
+  const endLetter = colToLetter3(parsed.endCol);
   const totalRow = parsed.endRow + 1;
   return `${startLetter}${totalRow}:${endLetter}${totalRow}`;
 }
@@ -84937,9 +85146,9 @@ var WorksheetTablesImpl = class {
     if (!match) {
       throw new KernelError("COMPUTE_ERROR", `Invalid range: ${range2}`);
     }
-    const startCol = letterToCol2(match[1]);
+    const startCol = letterToCol3(match[1]);
     const startRow = parseInt(match[2], 10) - 1;
-    const endCol = letterToCol2(match[3]);
+    const endCol = letterToCol3(match[3]);
     const endRow = parseInt(match[4], 10) - 1;
     await this.ctx.computeBridge.createTable(
       this.sheetId,
@@ -85019,9 +85228,9 @@ var WorksheetTablesImpl = class {
     if (!parsed) {
       throw new KernelError("COMPUTE_ERROR", `Invalid table range: ${table.range}`);
     }
-    const startCol = letterToCol2(parsed[1]);
+    const startCol = letterToCol3(parsed[1]);
     const startRow = parseInt(parsed[2], 10) - 1;
-    const endCol = letterToCol2(parsed[3]);
+    const endCol = letterToCol3(parsed[3]);
     const endRow = parseInt(parsed[4], 10) - 1;
     const filter = await getFilterForRange(this.ctx, this.sheetId, {
       startRow,
@@ -85042,9 +85251,9 @@ var WorksheetTablesImpl = class {
     if (!match) {
       throw new KernelError("COMPUTE_ERROR", `Invalid range: ${newRange}`);
     }
-    const startCol = letterToCol2(match[1]);
+    const startCol = letterToCol3(match[1]);
     const startRow = parseInt(match[2], 10) - 1;
-    const endCol = letterToCol2(match[3]);
+    const endCol = letterToCol3(match[3]);
     const endRow = parseInt(match[4], 10) - 1;
     await this.ctx.computeBridge.resizeTable(name, startRow, startCol, endRow, endCol);
   }
@@ -85175,8 +85384,8 @@ var WorksheetTablesImpl = class {
     if (!parsed) throw new KernelError("COMPUTE_ERROR", `Invalid table range: ${table.range}`);
     const dataStartRow = table.hasHeaders ? parsed.startRow + 1 : parsed.startRow;
     const absRow = dataStartRow + index;
-    const startLetter = colToLetter2(parsed.startCol);
-    const endLetter = colToLetter2(parsed.endCol);
+    const startLetter = colToLetter3(parsed.startCol);
+    const endLetter = colToLetter3(parsed.endCol);
     return `${startLetter}${absRow + 1}:${endLetter}${absRow + 1}`;
   }
   async getRowValues(tableName, index) {
@@ -85215,7 +85424,7 @@ var WorksheetTablesImpl = class {
     const dataStartRow = table.hasHeaders ? parsed.startRow + 1 : parsed.startRow;
     const dataEndRow = table.showTotals ? parsed.endRow - 1 : parsed.endRow;
     if (dataStartRow > dataEndRow) return null;
-    const letter = colToLetter2(col);
+    const letter = colToLetter3(col);
     return `${letter}${dataStartRow + 1}:${letter}${dataEndRow + 1}`;
   }
   async getColumnHeaderRange(tableName, columnIndex) {
@@ -85225,7 +85434,7 @@ var WorksheetTablesImpl = class {
     if (!parsed) return null;
     const col = parsed.startCol + columnIndex;
     if (col > parsed.endCol) return null;
-    const letter = colToLetter2(col);
+    const letter = colToLetter3(col);
     const headerRow = parsed.startRow + 1;
     return `${letter}${headerRow}`;
   }
@@ -85236,7 +85445,7 @@ var WorksheetTablesImpl = class {
     if (!parsed) return null;
     const col = parsed.startCol + columnIndex;
     if (col > parsed.endCol) return null;
-    const letter = colToLetter2(col);
+    const letter = colToLetter3(col);
     return `${letter}${parsed.startRow + 1}:${letter}${parsed.endRow + 1}`;
   }
   async getColumnTotalRange(tableName, columnIndex) {
@@ -85246,7 +85455,7 @@ var WorksheetTablesImpl = class {
     if (!parsed) return null;
     const col = parsed.startCol + columnIndex;
     if (col > parsed.endCol) return null;
-    const letter = colToLetter2(col);
+    const letter = colToLetter3(col);
     const totalRow = parsed.endRow + 1;
     return `${letter}${totalRow}`;
   }
@@ -85345,7 +85554,7 @@ var WorksheetTablesImpl = class {
   async sortClear(_tableName) {
   }
 };
-function letterToCol2(letters) {
+function letterToCol3(letters) {
   let col = 0;
   for (let i = 0; i < letters.length; i++) {
     col = col * 26 + (letters.toUpperCase().charCodeAt(i) - 64);
@@ -85356,9 +85565,9 @@ function parseA1Range2(range2) {
   const match = range2.match(/^([A-Z]+)(\d+):([A-Z]+)(\d+)$/i);
   if (!match) return null;
   return {
-    startCol: letterToCol2(match[1]),
+    startCol: letterToCol3(match[1]),
     startRow: parseInt(match[2], 10) - 1,
-    endCol: letterToCol2(match[3]),
+    endCol: letterToCol3(match[3]),
     endRow: parseInt(match[4], 10) - 1
   };
 }
@@ -85547,8 +85756,8 @@ function rangeSchemaToValidationRule(schema) {
     const start = parseRefIdSimple(ref.startId);
     const end = parseRefIdSimple(ref.endId);
     if (start && end) {
-      const startA1 = toA1(start.row, start.col);
-      const endA1 = toA1(end.row, end.col);
+      const startA1 = toA12(start.row, start.col);
+      const endA1 = toA12(end.row, end.col);
       range2 = startA1 === endA1 ? startA1 : `${startA1}:${endA1}`;
     }
   }
@@ -85581,8 +85790,8 @@ function rangeSchemaToValidationRule(schema) {
       const srcStart = parseRefIdSimple(src.startId);
       const srcEnd = parseRefIdSimple(src.endId);
       if (srcStart && srcEnd) {
-        const srcStartA1 = toA1(srcStart.row, srcStart.col);
-        const srcEndA1 = toA1(srcEnd.row, srcEnd.col);
+        const srcStartA1 = toA12(srcStart.row, srcStart.col);
+        const srcEndA1 = toA12(srcEnd.row, srcEnd.col);
         rule.listSource = srcStartA1 === srcEndA1 ? `=${srcStartA1}` : `=${srcStartA1}:${srcEndA1}`;
       }
     }
@@ -87799,11 +88008,12 @@ var WorksheetImpl = class {
     if (!result.success) {
       throw result.error;
     }
+    return result.data;
   }
   async clear(range2, applyTo) {
     const parsed = parseCellRange(range2);
     if (!parsed) throw new KernelError("COMPUTE_ERROR", `Invalid range: "${range2}"`);
-    await clearWithMode(
+    return clearWithMode(
       this.ctx,
       this.sheetId,
       { sheetId: this.sheetId, ...parsed },
@@ -87851,7 +88061,7 @@ var WorksheetImpl = class {
       format: format ?? void 0,
       hyperlink: hyperlink ?? void 0,
       isMerged: mergeInfo !== void 0,
-      mergedRegion: mergeInfo ? `${toA1(mergeInfo.startRow, mergeInfo.startCol)}:${toA1(mergeInfo.endRow, mergeInfo.endCol)}` : void 0
+      mergedRegion: mergeInfo ? `${toA12(mergeInfo.startRow, mergeInfo.startCol)}:${toA12(mergeInfo.endRow, mergeInfo.endCol)}` : void 0
     };
   }
   async getRawRangeData(range2, _includeFormula) {
@@ -87878,7 +88088,8 @@ var WorksheetImpl = class {
         } else {
           rowData.push({
             value: viewportCellValueToCellValue(vc.value) ?? null,
-            formula: vc.formula
+            formula: vc.formula,
+            format: vc.format ?? void 0
           });
         }
       }
@@ -87903,10 +88114,10 @@ var WorksheetImpl = class {
     const { row, col } = resolveCell(address);
     const data = await getCell(this.ctx, this.sheetId, row, col);
     if (!data) return "";
-    const rawValue = viewportCellValueToString(data.value);
-    let result = rawValue;
+    const displayValue = await getDisplayValue2(this.ctx, this.sheetId, row, col);
+    let result = displayValue;
     if (data.formula) {
-      result = rawValue !== "" ? `${rawValue}(${data.formula})` : `(${data.formula})`;
+      result = displayValue !== "" ? `${displayValue}(${data.formula})` : `(${data.formula})`;
     }
     const styleHintsStr = await getStyleHints(this.ctx, this.sheetId, row, col);
     if (styleHintsStr) {
@@ -87965,17 +88176,15 @@ var WorksheetImpl = class {
     }
     for (let row = parsed.startRow; row <= parsed.endRow; row++) {
       const rowValues = [];
-      let hasContent = false;
       for (let col = parsed.startCol; col <= parsed.endCol; col++) {
-        const cellAddr = toA1(row, col);
+        const cellAddr = toA12(row, col);
         const vc = cellMap.get(`${row},${col}`);
         if (!vc) {
           rowValues.push(`${cellAddr}:`);
           continue;
         }
-        const rawValue = viewportCellValueToString(vc.value);
-        let cellStr = rawValue;
-        hasContent = true;
+        const displayValue = vc.formatted ?? viewportCellValueToString(vc.value);
+        let cellStr = displayValue;
         if (vc.formula) {
           const abbreviation = formulaAnalysis.formulaToId.get(`${row},${col}`);
           if (abbreviation) {
@@ -87986,9 +88195,7 @@ var WorksheetImpl = class {
         }
         rowValues.push(`${cellAddr}:${cellStr}`);
       }
-      if (hasContent) {
-        outputParts.push(rowValues.join(" | "));
-      }
+      outputParts.push(rowValues.join(" | "));
     }
     const formulaDocs = generateFormulaDocumentation(formulaAnalysis);
     if (formulaDocs.length > 0) {
@@ -88077,8 +88284,8 @@ var WorksheetImpl = class {
     lines.push(`Sheet: ${meta.name}`);
     const bounds = await this.ctx.computeBridge.getDataBounds(this.sheetId);
     if (bounds) {
-      const startAddr = toA1(bounds.minRow, bounds.minCol);
-      const endAddr = toA1(bounds.maxRow, bounds.maxCol);
+      const startAddr = toA12(bounds.minRow, bounds.minCol);
+      const endAddr = toA12(bounds.maxRow, bounds.maxCol);
       lines.push(`Used Range: ${startAddr}:${endAddr}`);
       lines.push(
         `Dimensions: ${bounds.maxRow - bounds.minRow + 1} rows x ${bounds.maxCol - bounds.minCol + 1} columns`
@@ -88098,20 +88305,31 @@ var WorksheetImpl = class {
     const tables = await getTablesInSheet(this.ctx, this.sheetId);
     if (tables.length > 0) {
       const tableDescs = tables.map((t) => {
-        const r = `${toA1(t.range.startRow, t.range.startCol)}:${toA1(t.range.endRow, t.range.endCol)}`;
+        const r = `${toA12(t.range.startRow, t.range.startCol)}:${toA12(t.range.endRow, t.range.endCol)}`;
         return `${t.name} at ${r}`;
       });
       lines.push(`Tables: ${tables.length} (${tableDescs.join(", ")})`);
     }
-    const allNamedRanges = await getAll(this.ctx);
-    const sheetNamedRanges = allNamedRanges.filter((nr) => nr.scope === this.sheetId || !nr.scope);
-    if (sheetNamedRanges.length > 0) {
+    const allVisible = await getVisible(this.ctx);
+    const scoped = allVisible.filter((nr) => nr.scope === this.sheetId || !nr.scope);
+    const valid = scoped.filter((nr) => !nr.refersTo.template.includes("#REF!"));
+    const broken = scoped.length - valid.length;
+    if (valid.length > 0 || broken > 0) {
+      const toShow = valid.slice(0, MAX_SUMMARY_NAMED_RANGES);
       const nrDescs = [];
-      for (const nr of sheetNamedRanges) {
+      for (const nr of toShow) {
         const a1 = await getRefersToA1(this.ctx, nr);
         nrDescs.push(`${nr.name}=${a1}`);
       }
-      lines.push(`Named Ranges: ${sheetNamedRanges.length} (${nrDescs.join(", ")})`);
+      let label = `Named Ranges: ${valid.length}`;
+      if (broken > 0) label += ` valid, ${broken} broken (#REF!) omitted`;
+      if (nrDescs.length > 0) {
+        const showing = valid.length > MAX_SUMMARY_NAMED_RANGES ? `showing ${MAX_SUMMARY_NAMED_RANGES}: ` : "";
+        const more = valid.length > MAX_SUMMARY_NAMED_RANGES ? ` \u2014 ${valid.length - MAX_SUMMARY_NAMED_RANGES} more not shown` : "";
+        lines.push(`${label} (${showing}${nrDescs.join(", ")})${more}`);
+      } else {
+        lines.push(label);
+      }
     }
     const maxRows = options?.maxRows;
     const maxCols = options?.maxCols;
@@ -88180,7 +88398,7 @@ var WorksheetImpl = class {
         const rowData = [];
         for (const vc of cells) {
           const rawValue = viewportCellValueToString(vc.value);
-          const addr = toA1(vc.row, vc.col);
+          const addr = toA12(vc.row, vc.col);
           if (vc.formula) {
             rowData.push(`${addr}:${rawValue}(=${vc.formula})`);
           } else {
@@ -88204,7 +88422,7 @@ var WorksheetImpl = class {
   async getUsedRange() {
     const range2 = await getUsedRange2(this.ctx, this.sheetId);
     if (!range2) return null;
-    return `${toA1(range2.startRow, range2.startCol)}:${toA1(range2.endRow, range2.endCol)}`;
+    return `${toA12(range2.startRow, range2.startCol)}:${toA12(range2.endRow, range2.endCol)}`;
   }
   async getCurrentRegion(row, col) {
     return getCurrentRegion(this.ctx, this.sheetId, row, col);
@@ -88214,15 +88432,15 @@ var WorksheetImpl = class {
   }
   async findCells(predicate) {
     const addresses = await findCells(this.ctx, this.sheetId, predicate);
-    return addresses.map((a) => toA1(a.row, a.col));
+    return addresses.map((a) => toA12(a.row, a.col));
   }
   async findByValue(value) {
     const addresses = await findByValue(this.ctx, this.sheetId, value);
-    return addresses.map((a) => toA1(a.row, a.col));
+    return addresses.map((a) => toA12(a.row, a.col));
   }
   async findByFormula(pattern) {
     const addresses = await findByFormula(this.ctx, this.sheetId, pattern);
-    return addresses.map((a) => toA1(a.row, a.col));
+    return addresses.map((a) => toA12(a.row, a.col));
   }
   async regexSearch(patterns, options) {
     const results = await regexSearch(this.ctx, this.sheetId, patterns, {
@@ -88361,7 +88579,7 @@ var WorksheetImpl = class {
     await this.setRange(start.row, start.col, allRows);
     const endRow = start.row + allRows.length - 1;
     const endCol = start.col + headers.length - 1;
-    const rangeA1 = `${toA1(start.row, start.col)}:${toA1(endRow, endCol)}`;
+    const rangeA1 = `${toA12(start.row, start.col)}:${toA12(endRow, endCol)}`;
     await this.tables.add(rangeA1, { name, hasHeaders: true });
   }
   // ===========================================================================
@@ -88754,6 +88972,9 @@ var WorksheetImpl = class {
     }
     return this._cellMetadata;
   }
+  get changes() {
+    return this._changes ??= new WorksheetChangesImpl(this.ctx, this.sheetId);
+  }
   get formats() {
     return this._formats ??= new WorksheetFormatsImpl(this.ctx, this.sheetId);
   }
@@ -91087,6 +91308,31 @@ var WorkbookImpl = class {
       calculationSettings: calcSettings
     });
   }
+  async getIterativeCalculation() {
+    const settings = await this.ctx.computeBridge.getWorkbookSettings();
+    return settings.calculationSettings?.enableIterativeCalculation ?? false;
+  }
+  async setIterativeCalculation(enabled) {
+    const settings = await this.ctx.computeBridge.getWorkbookSettings();
+    const calcSettings = { ...settings.calculationSettings ?? {}, enableIterativeCalculation: enabled };
+    await this.ctx.computeBridge.patchWorkbookSettings({
+      calculationSettings: calcSettings
+    });
+  }
+  async setMaxIterations(n) {
+    const settings = await this.ctx.computeBridge.getWorkbookSettings();
+    const calcSettings = { ...settings.calculationSettings ?? {}, maxIterations: n };
+    await this.ctx.computeBridge.patchWorkbookSettings({
+      calculationSettings: calcSettings
+    });
+  }
+  async setConvergenceThreshold(threshold) {
+    const settings = await this.ctx.computeBridge.getWorkbookSettings();
+    const calcSettings = { ...settings.calculationSettings ?? {}, maxChange: threshold };
+    await this.ctx.computeBridge.patchWorkbookSettings({
+      calculationSettings: calcSettings
+    });
+  }
   async getUsePrecisionAsDisplayed() {
     const settings = await this.ctx.computeBridge.getWorkbookSettings();
     return !(settings.calculationSettings?.fullPrecision ?? true);
@@ -91246,7 +91492,7 @@ var WorkbookImpl = class {
   // Utilities (sync)
   // ===========================================================================
   indexToAddress(row, col) {
-    return toA1(row, col);
+    return toA12(row, col);
   }
   addressToIndex(address) {
     const parsed = parseCellAddress(address);
@@ -91498,6 +91744,7 @@ var api_spec_default = {
     },
     ws: {
       smartArt: "WorksheetSmartArt",
+      changes: "WorksheetChanges",
       formats: "WorksheetFormats",
       layout: "WorksheetLayout",
       view: "WorksheetView",
@@ -91609,6 +91856,26 @@ var api_spec_default = {
           docstring: "Set the calculation mode.\nConvenience mutator \u2014 patches `calculationSettings.calcMode`.",
           usedTypes: []
         },
+        getIterativeCalculation: {
+          signature: "getIterativeCalculation(): Promise<boolean>;",
+          docstring: "Get whether iterative calculation is enabled for circular references.\nConvenience accessor \u2014 equivalent to `(await getSettings()).calculationSettings.enableIterativeCalculation`.",
+          usedTypes: []
+        },
+        setIterativeCalculation: {
+          signature: "setIterativeCalculation(enabled: boolean): Promise<void>;",
+          docstring: "Set whether iterative calculation is enabled for circular references.\nConvenience mutator \u2014 patches `calculationSettings.enableIterativeCalculation`.",
+          usedTypes: []
+        },
+        setMaxIterations: {
+          signature: "setMaxIterations(n: number): Promise<void>;",
+          docstring: "Set the maximum number of iterations for iterative calculation.\nConvenience mutator \u2014 patches `calculationSettings.maxIterations`.",
+          usedTypes: []
+        },
+        setConvergenceThreshold: {
+          signature: "setConvergenceThreshold(threshold: number): Promise<void>;",
+          docstring: "Set the convergence threshold (maximum change) for iterative calculation.\nConvenience mutator \u2014 patches `calculationSettings.maxChange`.",
+          usedTypes: []
+        },
         getUsePrecisionAsDisplayed: {
           signature: "getUsePrecisionAsDisplayed(): Promise<boolean>;",
           docstring: "Whether to use displayed precision instead of full (15-digit) precision.\nConvenience accessor \u2014 inverted from `calculationSettings.fullPrecision`.",
@@ -91820,18 +92087,21 @@ var api_spec_default = {
           usedTypes: []
         },
         clearData: {
-          signature: "clearData(range: string): Promise<void>;",
+          signature: "clearData(range: string): Promise<ClearResult>;",
           docstring: 'Clear all cell data (values and formulas) in a range (A1 notation, e.g. "A1:C3").',
-          usedTypes: []
+          usedTypes: [
+            "ClearResult"
+          ]
         },
         clear: {
-          signature: "clear(range: string, applyTo?: ClearApplyTo): Promise<void>;",
+          signature: "clear(range: string, applyTo?: ClearApplyTo): Promise<ClearResult>;",
           docstring: `Unified clear with mode selection (OfficeJS Range.clear equivalent).
 
 @param range - A1 range string (e.g. "A1:C3")
 @param applyTo - What to clear: 'all' (default), 'contents', 'formats', 'hyperlinks'`,
           usedTypes: [
-            "ClearApplyTo"
+            "ClearApplyTo",
+            "ClearResult"
           ]
         },
         getValue: {
@@ -92710,21 +92980,36 @@ var api_spec_default = {
         }
       }
     },
+    WorksheetChanges: {
+      docstring: "Sub-API for opt-in change tracking on a worksheet.",
+      functions: {
+        track: {
+          signature: "track(options?: ChangeTrackOptions): ChangeTracker;",
+          docstring: "Create a change tracker that accumulates cell-level change records\nfrom this point forward.\n\n@param options - Optional scope and origin filters\n@returns A ChangeTracker handle \u2014 call collect() to drain, close() when done",
+          usedTypes: [
+            "ChangeTrackOptions",
+            "ChangeTracker"
+          ]
+        }
+      }
+    },
     WorksheetFormats: {
       docstring: "Sub-API for cell formatting operations on a worksheet.",
       functions: {
         set: {
-          signature: "set(address: string, format: CellFormat): Promise<void>;",
+          signature: "set(address: string, format: CellFormat): Promise<FormatChangeResult>;",
           docstring: 'Set format for a single cell.\n\n@param address - A1-style cell address (e.g. "A1", "B3")\n@param format - Format properties to apply',
           usedTypes: [
-            "CellFormat"
+            "CellFormat",
+            "FormatChangeResult"
           ]
         },
         setRange: {
-          signature: "setRange(range: string, format: CellFormat): Promise<void>;",
+          signature: "setRange(range: string, format: CellFormat): Promise<FormatChangeResult>;",
           docstring: 'Set format for a contiguous range.\n\n@param range - A1-style range string (e.g. "A1:B2")\n@param format - Format properties to apply',
           usedTypes: [
-            "CellFormat"
+            "CellFormat",
+            "FormatChangeResult"
           ]
         },
         setRanges: {
@@ -92741,10 +93026,10 @@ var api_spec_default = {
           usedTypes: []
         },
         get: {
-          signature: "get(address: string): Promise<CellFormat | null>;",
-          docstring: "Get the format of a single cell.\n\n@param address - A1-style cell address\n@returns The cell format, or null if no format is set",
+          signature: "get(address: string): Promise<ResolvedCellFormat>;",
+          docstring: "Get the fully-resolved format of a single cell.\n\nReturns a dense CellFormat with all fields present (null for unset properties,\nnever undefined). Includes the full cascade (default \u2192 col \u2192 row \u2192 table \u2192 cell \u2192 CF)\nwith theme colors resolved to hex.\n\n@param address - A1-style cell address\n@returns The resolved cell format (always an object, never null)",
           usedTypes: [
-            "CellFormat"
+            "ResolvedCellFormat"
           ]
         },
         adjustIndent: {
@@ -94871,6 +95156,11 @@ var api_spec_default = {
       definition: "'standard' | 'stacked' | 'percentStacked'",
       docstring: ""
     },
+    AutoFillChange: {
+      name: "AutoFillChange",
+      definition: "{\n  row: number;\n  col: number;\n  type: 'value' | 'formula' | 'format' | 'clear';\n}",
+      docstring: "A single cell change produced by the fill engine."
+    },
     AutoFillMode: {
       name: "AutoFillMode",
       definition: "| 'auto' // Detect pattern automatically (default)\n  | 'copy' // Always copy (no series)\n  | 'series' // Force series interpretation\n  | 'days' // Force date unit: days\n  | 'weekdays' // Force date unit: weekdays\n  | 'months' // Force date unit: months\n  | 'years' // Force date unit: years\n  | 'formats' // Copy formats only\n  | 'values' // Copy values only (no formats)\n  | 'withoutFormats' // Copy values + formulas, skip formats\n  | 'linearTrend' // Force linear regression trend\n  | 'growthTrend'",
@@ -94878,7 +95168,7 @@ var api_spec_default = {
     },
     AutoFillResult: {
       name: "AutoFillResult",
-      definition: "{\n  /** The pattern that was detected (or forced by mode) */\n  patternType: FillPatternType;\n  /** Number of cells that were filled */\n  filledCellCount: number;\n  /** Any warnings generated during fill */\n  warnings: AutoFillWarning[];\n}",
+      definition: "{\n  /** The pattern that was detected (or forced by mode) */\n  patternType: FillPatternType;\n  /** Number of cells that were filled */\n  filledCellCount: number;\n  /** Any warnings generated during fill */\n  warnings: AutoFillWarning[];\n  /** Per-cell changes listing each cell written */\n  changes: AutoFillChange[];\n}",
       docstring: "Result from autoFill() \u2014 summary of what the fill engine did."
     },
     AutoFillWarning: {
@@ -95225,6 +95515,37 @@ Example: { ignoreError: true } to suppress error indicators. */
       definition: "{\n  /** If true, value is treated as a formula (prefixed with =) */\n  asFormula?: boolean;\n}",
       docstring: "Options controlling how a cell value is interpreted when written."
     },
+    ChangeOrigin: {
+      name: "ChangeOrigin",
+      definition: "'direct' | 'cascade' | 'remote'",
+      docstring: "Origin of a change: direct write, formula recalculation, or remote collaborator."
+    },
+    ChangeRecord: {
+      name: "ChangeRecord",
+      definition: `{
+  /** Cell address in A1 notation (e.g. "B1"). */
+  address: string;
+  /** 0-based row index. */
+  row: number;
+  /** 0-based column index. */
+  col: number;
+  /** What caused this change. */
+  origin: ChangeOrigin;
+  /** Type of change. */
+  type: 'modified';
+}`,
+      docstring: "WorksheetChanges \u2014 Sub-API for opt-in change tracking.\n\nCreates lightweight trackers that accumulate cell-level change records\nacross mutations. Trackers are opt-in to avoid bloating return values;\nthey return addresses + metadata only (no cell values) so callers can\nhydrate via getRange() when needed.\n\nInspired by:\n- Excel OfficeJS onChanged (lightweight payload + lazy hydration)\n- Firestore onSnapshot (query-scoped subscriptions)\n- Yjs transaction.origin (source/origin tagging for collab)"
+    },
+    ChangeTrackOptions: {
+      name: "ChangeTrackOptions",
+      definition: '{\n  /** Only track changes within this range (A1 notation, e.g. "A1:Z100"). Omit for whole-sheet. */\n  scope?: string;\n  /** Exclude changes from these origin types. */\n  excludeOrigins?: ChangeOrigin[];\n}',
+      docstring: "Options for creating a change tracker."
+    },
+    ChangeTracker: {
+      name: "ChangeTracker",
+      definition: "{\n  /** Drain all accumulated changes since creation or last collect() call.\nReturns addresses + metadata only (no cell values) \u2014 call ws.getRange()\nto hydrate if needed. */\n  collect(): ChangeRecord[];;\n  /** Stop tracking and release internal resources. */\n  close(): void;;\n  /** Whether this tracker is still active (not closed). */\n  active: boolean;\n}",
+      docstring: "A handle that accumulates change records across mutations."
+    },
     Chart: {
       name: "Chart",
       definition: "{\n  id: string;\n  sheetId?: string;\n  createdAt?: number;\n  updatedAt?: number;\n}",
@@ -95359,6 +95680,11 @@ that are stored on the chart but not part of the core config schema. */
       definition: "'all' | 'contents' | 'formats' | 'hyperlinks'",
       docstring: "Determines which aspects of a range to clear.\nMatches OfficeJS Excel.ClearApplyTo enum."
     },
+    ClearResult: {
+      name: "ClearResult",
+      definition: "{\n  /** Number of cells in the cleared range. */\n  cellCount: number;\n}",
+      docstring: "Confirmation returned by clearData() and clear()."
+    },
     CodeResult: {
       name: "CodeResult",
       definition: "{\n  /** Whether execution completed successfully */\n  success: boolean;\n  /** Captured console output */\n  output?: string;\n  /** Error message (if success is false) */\n  error?: string;\n  /** Execution duration in milliseconds */\n  duration?: number;\n}",
@@ -95572,6 +95898,11 @@ Used in condition filters where users specify rules like
       definition: "| 'shape'\n  | 'connector'\n  | 'picture'\n  | 'textbox'\n  | 'chart'\n  | 'camera'\n  | 'equation'\n  | 'smartart'\n  | 'drawing'\n  | 'oleObject'\n  | 'formControl'\n  | 'slicer'\n  | 'wordart'",
       docstring: "Type discriminator for floating objects. Superset of Rust FloatingObjectKind (12 variants) + legacy TS-only 'wordart'."
     },
+    FormatChangeResult: {
+      name: "FormatChangeResult",
+      definition: "{\n  /** Number of cells whose formatting was changed */\n  cellCount: number;\n}",
+      docstring: "Result of a format set/setRange operation."
+    },
     FormatEntry: {
       name: "FormatEntry",
       definition: '{\n  /** Cell value descriptor */\n  value: { type: string; value?: unknown };\n  /** Number format code (e.g., "#,##0.00") */\n  formatCode: string;\n}',
@@ -95940,6 +96271,11 @@ Used in condition filters where users specify rules like
       definition: "{\n  /** Number of duplicate rows removed */\n  removedCount: number;\n  /** Number of unique rows remaining */\n  remainingCount: number;\n}",
       docstring: "Result of a remove-duplicates operation."
     },
+    ResolvedCellFormat: {
+      name: "ResolvedCellFormat",
+      definition: "{\n  [K in keyof CellFormat]-?: CellFormat[K] | null;\n}",
+      docstring: "Dense cell format where every property is explicitly present (null when unset). Returned by formats.get()."
+    },
     RichTextSegment: {
       name: "RichTextSegment",
       definition: "{\n  text: string;\n  bold?: boolean;\n  italic?: boolean;\n  underline?: boolean;\n  strikethrough?: boolean;\n  color?: string;\n  fontName?: string;\n  fontSize?: number;\n}",
@@ -96020,7 +96356,7 @@ Used in condition filters where users specify rules like
     },
     SetCellsResult: {
       name: "SetCellsResult",
-      definition: "{\n  /** Number of cells successfully written */\n  cellsWritten: number;\n  /** Per-cell errors, if any (omitted when all succeed) */\n  errors?: Array<{ addr: string; error: string }>;\n  /** Non-fatal warnings (e.g., deduplication, coercion) */\n  warnings?: OperationWarning[];\n}",
+      definition: "{\n  /** Number of cells successfully written */\n  cellsWritten: number;\n  /** Per-cell errors, if any (omitted when all succeed) */\n  errors?: Array<{ addr: string; error: string }> | null;\n  /** Non-fatal warnings (e.g., deduplication, coercion) */\n  warnings?: OperationWarning[];\n}",
       docstring: "Result of a bulk setCells() operation."
     },
     ShadowAlignment: {
@@ -96424,8 +96760,7 @@ Used in condition filters where users specify rules like
       definition: "{\n  /** All sheets in the workbook */\n  sheets: SheetSnapshot[];\n  /** ID of the currently active sheet */\n  activeSheetId: string;\n  /** Total number of sheets */\n  sheetCount: number;\n}",
       docstring: "A summary snapshot of the entire workbook state."
     }
-  },
-  generated: "2026-04-02T22:03:24.772Z"
+  }
 };
 
 // src/api-describe.ts