@devmm/puredocs-excel-formula 1.0.6 → 1.0.7

package/dist/index.cjs

@@ -804,6 +804,19 @@ var SheetRangeReferenceNode = class extends FormulaNode {
     return ctx.getSheetRangeValues(this.sheetName, this.startRef, this.endRef);
   }
 };
+var FullRangeReferenceNode = class extends FormulaNode {
+  constructor(startCol, endCol, startRow, endRow, sheetName) {
+    super();
+    this.startCol = startCol;
+    this.endCol = endCol;
+    this.startRow = startRow;
+    this.endRow = endRow;
+    this.sheetName = sheetName;
+  }
+  evaluate(ctx) {
+    return this.sheetName === void 0 ? ctx.getFullRangeValues(this.startCol, this.endCol, this.startRow, this.endRow) : ctx.getSheetFullRangeValues(this.sheetName, this.startCol, this.endCol, this.startRow, this.endRow);
+  }
+};
 var NamedRangeNode = class extends FormulaNode {
   constructor(name) {
     super();
@@ -1023,7 +1036,7 @@ var CallNode = class extends FormulaNode {
 };
 
 // src/formula-parser.ts
-var _tokens, _pos2, _FormulaParser_instances, current_get, advance_fn, expect_fn, parseComparison_fn, parseConcatenation_fn, parseAddSub_fn, parseMulDiv_fn, parseUnary_fn, parsePower_fn, parsePercent_fn, parsePostfix_fn, parsePrimary_fn, parseFunction_fn, parseArgList_fn;
+var _tokens, _pos2, _FormulaParser_instances, current_get, advance_fn, expect_fn, parseComparison_fn, parseConcatenation_fn, parseAddSub_fn, parseMulDiv_fn, parseUnary_fn, parsePower_fn, parsePercent_fn, parsePostfix_fn, parsePrimary_fn, tryParseFullRange_fn, parseFunction_fn, parseArgList_fn;
 var FormulaParser = class {
   constructor(tokens) {
     __privateAdd(this, _FormulaParser_instances);
@@ -1147,6 +1160,10 @@ parsePrimary_fn = function() {
   switch (token.type) {
     case 0 /* Number */: {
       __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
+      if (__privateGet(this, _FormulaParser_instances, current_get).type === 4 /* Colon */) {
+        const full = __privateMethod(this, _FormulaParser_instances, tryParseFullRange_fn).call(this, token.value);
+        if (full) return full;
+      }
       const n = parseFloat(token.value);
       if (isNaN(n)) throw new FormulaException(`Invalid number: ${token.value}`);
       return new NumberNode(n);
@@ -1175,15 +1192,22 @@ parsePrimary_fn = function() {
       const sheetName = parts[0];
       const cellRef = parts[1] ?? "";
       if (__privateGet(this, _FormulaParser_instances, current_get).type === 4 /* Colon */) {
+        const full = __privateMethod(this, _FormulaParser_instances, tryParseFullRange_fn).call(this, cellRef, sheetName);
+        if (full) return full;
         __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
         const end = __privateMethod(this, _FormulaParser_instances, expect_fn).call(this, 3 /* CellReference */);
         return new SheetRangeReferenceNode(sheetName, cellRef, end.value);
       }
       return new SheetCellReferenceNode(sheetName, cellRef);
     }
-    case 23 /* NamedRange */:
+    case 23 /* NamedRange */: {
       __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
+      if (__privateGet(this, _FormulaParser_instances, current_get).type === 4 /* Colon */) {
+        const full = __privateMethod(this, _FormulaParser_instances, tryParseFullRange_fn).call(this, token.value);
+        if (full) return full;
+      }
       return new NamedRangeNode(token.value);
+    }
     case 24 /* SpillReference */:
       __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
       return new SpillReferenceNode(token.value);
@@ -1201,6 +1225,28 @@ parsePrimary_fn = function() {
       );
   }
 };
+/**
+ * Completes a whole-column or whole-row reference whose first half has already
+ * been consumed and whose ':' is the current token. Returns null — consuming
+ * nothing — when the two halves are not a matching pair of columns or rows, so
+ * the caller can fall back to its normal interpretation.
+ *
+ * Both halves must be the same kind: `A:A` and `1:5` are ranges, `A:1` is not
+ * a reference at all in Excel and must stay an error rather than becoming a
+ * silently different region.
+ */
+tryParseFullRange_fn = function(startText, sheetName) {
+  const endToken = __privateGet(this, _tokens)[__privateGet(this, _pos2) + 1];
+  if (!endToken) return null;
+  const start = classifyBound(startText);
+  const end = classifyBound(endToken.value);
+  if (!start || !end || start.kind !== end.kind) return null;
+  __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
+  __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
+  const lo = Math.min(start.index, end.index);
+  const hi = Math.max(start.index, end.index);
+  return start.kind === "col" ? new FullRangeReferenceNode(lo, hi, null, null, sheetName) : new FullRangeReferenceNode(null, null, lo, hi, sheetName);
+};
 parseFunction_fn = function() {
   const nameToken = __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
   __privateMethod(this, _FormulaParser_instances, expect_fn).call(this, 6 /* LeftParen */);
@@ -1227,6 +1273,18 @@ parseArgList_fn = function() {
   __privateMethod(this, _FormulaParser_instances, expect_fn).call(this, 7 /* RightParen */);
   return args;
 };
+function classifyBound(text) {
+  const bare = text.replace(/\$/g, "");
+  if (/^\d+$/.test(bare)) {
+    const row2 = parseInt(bare, 10);
+    return row2 >= 1 && row2 <= puredocsExcel.EXCEL_MAX_ROWS ? { kind: "row", index: row2 } : null;
+  }
+  if (/^[A-Za-z]{1,3}$/.test(bare)) {
+    const col = puredocsExcel.columnNumber(bare.toUpperCase());
+    return col >= 1 && col <= puredocsExcel.EXCEL_MAX_COLUMNS ? { kind: "col", index: col } : null;
+  }
+  return null;
+}
 function comparisonOp(type) {
   switch (type) {
     case 16 /* Equal */:
@@ -1246,6 +1304,137 @@ function comparisonOp(type) {
   }
 }
 
+// src/criteria-index.ts
+var EPSILON = 1e-10;
+var indexes = /* @__PURE__ */ new WeakMap();
+function build(arr) {
+  const byText = /* @__PURE__ */ new Map();
+  const byNumber = /* @__PURE__ */ new Map();
+  const classes = /* @__PURE__ */ new Map();
+  const addToClass = (kind, v, i2) => {
+    const group = classes.get(kind);
+    if (group) group.positions.push(i2);
+    else classes.set(kind, { positions: [i2], representative: v });
+  };
+  let i = 0;
+  for (const v of arr.values()) {
+    const textKey = v.asText().toUpperCase();
+    const atText = byText.get(textKey);
+    if (atText) atText.push(i);
+    else byText.set(textKey, [i]);
+    if (v.isNumber) {
+      const n = v.numberValue;
+      const atNum = byNumber.get(n);
+      if (atNum) atNum.push(i);
+      else byNumber.set(n, [i]);
+    } else {
+      addToClass(v.kind, v, i);
+    }
+    i++;
+  }
+  const sortedNumbers = Float64Array.from(byNumber.keys()).sort();
+  const cumulative = new Int32Array(sortedNumbers.length + 1);
+  for (let k = 0; k < sortedNumbers.length; k++) {
+    cumulative[k + 1] = cumulative[k] + byNumber.get(sortedNumbers[k]).length;
+  }
+  return { byText, byNumber, sortedNumbers, cumulative, classes: [...classes.values()] };
+}
+function indexOf(arr) {
+  let idx = indexes.get(arr);
+  if (!idx) {
+    idx = build(arr);
+    indexes.set(arr, idx);
+  }
+  return idx;
+}
+function lowerBound(sorted, target) {
+  let lo = 0, hi = sorted.length;
+  while (lo < hi) {
+    const mid2 = lo + hi >> 1;
+    if (sorted[mid2] < target) lo = mid2 + 1;
+    else hi = mid2;
+  }
+  return lo;
+}
+function upperBound(sorted, target) {
+  let lo = 0, hi = sorted.length;
+  while (lo < hi) {
+    const mid2 = lo + hi >> 1;
+    if (sorted[mid2] <= target) lo = mid2 + 1;
+    else hi = mid2;
+  }
+  return lo;
+}
+function matchingPositions(criteriaRange, criteria, minSize) {
+  if (!criteriaRange.isArray) return null;
+  const arr = criteriaRange.arrayVal;
+  if (arr.length < minSize) return null;
+  if (criteria.kind === "equalsText") {
+    return indexOf(arr).byText.get(criteria.text) ?? EMPTY;
+  }
+  if (criteria.kind === "equalsNumber") {
+    const target = criteria.number;
+    const idx = indexOf(arr);
+    const exact2 = idx.byNumber.get(target);
+    let near;
+    const { sortedNumbers } = idx;
+    for (let k = lowerBound(sortedNumbers, target - EPSILON); k < sortedNumbers.length; k++) {
+      const value2 = sortedNumbers[k];
+      if (value2 > target + EPSILON) break;
+      if (value2 === target) continue;
+      if (!criteria.test(FormulaValue.number(value2))) continue;
+      (near ?? (near = [])).push(...idx.byNumber.get(value2));
+    }
+    const blanks = criteria.test(FormulaValue.blank) ? blankPositions(idx) : void 0;
+    if (!near && !blanks?.length) return exact2 ?? EMPTY;
+    const merged = [...exact2 ?? EMPTY, ...near ?? EMPTY, ...blanks ?? EMPTY];
+    merged.sort((a, b) => a - b);
+    return merged;
+  }
+  if (criteria.kind === "compareNumber") {
+    return comparePositions(indexOf(arr), criteria, arr.length);
+  }
+  return null;
+}
+function comparePositions(idx, criteria, length) {
+  const target = criteria.number;
+  const { sortedNumbers } = idx;
+  let from = 0;
+  let to = sortedNumbers.length;
+  switch (criteria.op) {
+    case ">":
+      from = upperBound(sortedNumbers, target);
+      break;
+    case ">=":
+      from = lowerBound(sortedNumbers, target);
+      break;
+    case "<":
+      to = lowerBound(sortedNumbers, target);
+      break;
+    default:
+      to = upperBound(sortedNumbers, target);
+      break;
+  }
+  const budget = length >> 1;
+  const matchedClasses = idx.classes.filter((g) => criteria.test(g.representative));
+  let total = idx.cumulative[to] - idx.cumulative[from];
+  for (const group of matchedClasses) total += group.positions.length;
+  if (total > budget) return null;
+  const positions = [];
+  for (let k = from; k < to; k++) {
+    for (const i of idx.byNumber.get(sortedNumbers[k])) positions.push(i);
+  }
+  for (const group of matchedClasses) {
+    for (const i of group.positions) positions.push(i);
+  }
+  positions.sort((a, b) => a - b);
+  return positions;
+}
+function blankPositions(idx) {
+  return idx.classes.find((g) => g.representative.isBlank)?.positions;
+}
+var EMPTY = [];
+
 // src/functions/math-functions.ts
 function registerMath(r) {
   r.register("SUM", sum, 1);
@@ -1307,34 +1496,72 @@ function valueAt(v, i) {
 function lengthOf(v) {
   return v.isArray ? v.arrayVal.length : 1;
 }
-function computeIfsMask(a, c, startIdx, len2) {
-  const mask = new Uint8Array(len2).fill(1);
+var INDEX_MIN_RANGE = 32;
+function resolveIfsSelection(a, c, startIdx, len2) {
+  const ranges = [];
+  const criteria = [];
+  let seed;
+  let seedPair = -1;
   for (let p = startIdx; p + 1 < a.length; p += 2) {
     const cr = a[p].evaluate(c);
     if (cr.isError) return { ok: false, error: cr };
     const crit = a[p + 1].evaluate(c);
     if (crit.isError) return { ok: false, error: crit };
-    const critText = crit.asText();
+    const compiled = exports.FormulaHelper.compileCriteria(crit.asText());
+    ranges.push(cr);
+    criteria.push(compiled);
+    if (seed === void 0) {
+      const positions = matchingPositions(cr, compiled, INDEX_MIN_RANGE);
+      if (positions) {
+        seed = positions;
+        seedPair = ranges.length - 1;
+      }
+    }
+  }
+  if (seed !== void 0) {
+    let candidates = [];
+    for (const i of seed) if (i < len2) candidates.push(i);
+    for (let k = 0; k < ranges.length && candidates.length > 0; k++) {
+      if (k === seedPair) continue;
+      const range = ranges[k];
+      const test = criteria[k].test;
+      const next = [];
+      for (const i of candidates) if (test(valueAt(range, i))) next.push(i);
+      candidates = next;
+    }
+    return { ok: true, positions: candidates };
+  }
+  const mask = new Uint8Array(len2).fill(1);
+  for (let k = 0; k < ranges.length; k++) {
+    const range = ranges[k];
+    const test = criteria[k].test;
     for (let i = 0; i < len2; i++) {
       if (!mask[i]) continue;
-      if (!exports.FormulaHelper.matchesCriteria(valueAt(cr, i), critText)) mask[i] = 0;
+      if (!test(valueAt(range, i))) mask[i] = 0;
     }
   }
   return { ok: true, mask };
 }
+function forEachSelected(sel, len2, visit) {
+  if ("positions" in sel) {
+    for (const i of sel.positions) visit(i);
+    return;
+  }
+  const { mask } = sel;
+  for (let i = 0; i < len2; i++) if (mask[i]) visit(i);
+}
 function sumIfs(a, c) {
   if (a.length < 3 || a.length % 2 === 0) return FormulaValue.errorValue;
   const sumRange = a[0].evaluate(c);
   if (sumRange.isError) return sumRange;
   const len2 = lengthOf(sumRange);
-  const m = computeIfsMask(a, c, 1, len2);
-  if (!m.ok) return m.error;
+  const sel = resolveIfsSelection(a, c, 1, len2);
+  if (!sel.ok) return sel.error;
   let total = 0;
-  for (let i = 0; i < len2; i++) {
-    if (!m.mask[i]) continue;
+  forEachSelected(sel, len2, (i) => {
     const r = valueAt(sumRange, i).tryAsDouble();
     if (r.ok) total += r.value;
-  }
+  });
   return FormulaValue.number(total);
 }
 function countIfs(a, c) {
@@ -1342,10 +1569,12 @@ function countIfs(a, c) {
   const first = a[0].evaluate(c);
   if (first.isError) return first;
   const len2 = lengthOf(first);
-  const m = computeIfsMask(a, c, 0, len2);
-  if (!m.ok) return m.error;
+  const sel = resolveIfsSelection(a, c, 0, len2);
+  if (!sel.ok) return sel.error;
   let n = 0;
-  for (let i = 0; i < len2; i++) if (m.mask[i]) n++;
+  forEachSelected(sel, len2, () => {
+    n++;
+  });
   return FormulaValue.number(n);
 }
 function averageIfs(a, c) {
@@ -1353,17 +1582,16 @@ function averageIfs(a, c) {
   const avgRange = a[0].evaluate(c);
   if (avgRange.isError) return avgRange;
   const len2 = lengthOf(avgRange);
-  const m = computeIfsMask(a, c, 1, len2);
-  if (!m.ok) return m.error;
+  const sel = resolveIfsSelection(a, c, 1, len2);
+  if (!sel.ok) return sel.error;
   let total = 0, cnt = 0;
-  for (let i = 0; i < len2; i++) {
-    if (!m.mask[i]) continue;
+  forEachSelected(sel, len2, (i) => {
     const r = valueAt(avgRange, i).tryAsDouble();
     if (r.ok) {
       total += r.value;
       cnt++;
     }
-  }
+  });
   return cnt === 0 ? FormulaValue.errorDiv0 : FormulaValue.number(total / cnt);
 }
 function sumSq(a, c) {
@@ -4187,39 +4415,43 @@ exports.FormulaHelper = void 0;
     return result;
   }
   FormulaHelper2.flattenArgs = flattenArgs;
-  function matchesCriteria(value2, criteria) {
-    criteria = criteria.trim();
-    const opMatch = /^(>=|<=|<>|>|<|=)(.*)$/.exec(criteria);
+  function compileCriteria(criteria) {
+    const trimmed = criteria.trim();
+    const opMatch = /^(>=|<=|<>|>|<|=)(.*)$/.exec(trimmed);
     if (opMatch) {
       const op = opMatch[1];
       const rhs = opMatch[2];
       const rhsVal = parseFloat(rhs);
       const rhsNum = isNaN(rhsVal) ? null : rhsVal;
-      const cmp = rhsNum !== null ? FormulaValue.compare(value2, FormulaValue.number(rhsNum)) : FormulaValue.compare(value2, FormulaValue.text(rhs));
-      switch (op) {
-        case ">":
-          return cmp > 0;
-        case ">=":
-          return cmp >= 0;
-        case "<":
-          return cmp < 0;
-        case "<=":
-          return cmp <= 0;
-        case "<>":
-          return !FormulaValue.areEqual(value2, rhsNum !== null ? FormulaValue.number(rhsNum) : FormulaValue.text(rhs));
-        case "=":
-          return FormulaValue.areEqual(value2, rhsNum !== null ? FormulaValue.number(rhsNum) : FormulaValue.text(rhs));
+      const rhsValue = rhsNum !== null ? FormulaValue.number(rhsNum) : FormulaValue.text(rhs);
+      if (op === "=") {
+        return rhsNum !== null ? numberEquality(rhsNum) : textEquality(rhs);
       }
+      if (op === "<>") {
+        return { kind: "other", test: (v) => !FormulaValue.areEqual(v, rhsValue) };
+      }
+      const wanted = op === ">" ? (c) => c > 0 : op === ">=" ? (c) => c >= 0 : op === "<" ? (c) => c < 0 : (c) => c <= 0;
+      const test = (v) => wanted(FormulaValue.compare(v, rhsValue));
+      return rhsNum !== null ? { kind: "compareNumber", number: rhsNum, op, test } : { kind: "other", test };
     }
-    if (criteria.includes("*") || criteria.includes("?")) {
-      const pattern = wildcardToRegex(criteria);
-      return pattern.test(value2.asText());
-    }
-    const num5 = parseFloat(criteria);
-    if (!isNaN(num5)) {
-      return FormulaValue.areEqual(value2, FormulaValue.number(num5));
+    if (trimmed.includes("*") || trimmed.includes("?")) {
+      const pattern = wildcardToRegex(trimmed);
+      return { kind: "other", test: (v) => pattern.test(v.asText()) };
     }
-    return value2.asText().toUpperCase() === criteria.toUpperCase();
+    const num5 = parseFloat(trimmed);
+    return isNaN(num5) ? textEquality(trimmed) : numberEquality(num5);
+  }
+  FormulaHelper2.compileCriteria = compileCriteria;
+  function numberEquality(n) {
+    const target = FormulaValue.number(n);
+    return { kind: "equalsNumber", number: n, test: (v) => FormulaValue.areEqual(v, target) };
+  }
+  function textEquality(s) {
+    const upper2 = s.toUpperCase();
+    return { kind: "equalsText", text: upper2, test: (v) => v.asText().toUpperCase() === upper2 };
+  }
+  function matchesCriteria(value2, criteria) {
+    return compileCriteria(criteria).test(value2);
   }
   FormulaHelper2.matchesCriteria = matchesCriteria;
   function wildcardToRegex(pattern) {
@@ -4229,7 +4461,7 @@ exports.FormulaHelper = void 0;
 })(exports.FormulaHelper || (exports.FormulaHelper = {}));
 
 // src/formula-context.ts
-var _sheet, _functions2, _evaluating, _scopes, _FormulaContext_instances, lookupScope_fn;
+var _sheet, _functions2, _evaluating, _scopes, _FormulaContext_instances, lookupScope_fn, forSheet_fn;
 var _FormulaContext = class _FormulaContext {
   constructor(sheet, formulaRow = 0, formulaCol = 0, evaluating, registry) {
     __privateAdd(this, _FormulaContext_instances);
@@ -4274,24 +4506,70 @@ var _FormulaContext = class _FormulaContext {
   getRangeValues(startRef, endRef) {
     const s = puredocsExcel.parseCellRef(startRef);
     const e = puredocsExcel.parseCellRef(endRef);
-    const rows2 = e.row - s.row + 1;
-    const cols = e.column - s.column + 1;
+    return this.getRangeValuesByIndex(s.row, s.column, e.row, e.column);
+  }
+  /**
+   * Resolves a rectangle already known in coordinates. Split out from
+   * {@link getRangeValues} because whole-column references and the range memo
+   * both work in numbers, and formatting them back into `A1` strings only to
+   * re-parse them is measurable at range scale.
+   */
+  getRangeValuesByIndex(startRow, startCol, endRow, endCol) {
+    const rows2 = endRow - startRow + 1;
+    const cols = endCol - startCol + 1;
+    const cache = rows2 * cols > 1 ? this.rangeCache : void 0;
+    const sheetKey = cache ? __privateGet(this, _sheet).name.toUpperCase() : "";
+    if (cache) {
+      const hit = cache.get(sheetKey, startRow, startCol, endRow, endCol);
+      if (hit !== void 0) return hit;
+    }
     const arr = new ArrayValue(rows2, cols);
-    for (let r = 0; r < rows2; r++) {
-      for (let c = 0; c < cols; c++) {
-        const ref = puredocsExcel.cellRefFromRowCol(s.row + r, s.column + c);
-        arr.set(r, c, this.getCellValue(ref));
+    const at = __privateGet(this, _sheet).getCellValueAt;
+    if (at) {
+      for (let r = 0; r < rows2; r++) {
+        for (let c = 0; c < cols; c++) {
+          arr.set(r, c, FormulaValue.fromObjectSync(at.call(__privateGet(this, _sheet), startRow + r, startCol + c)));
+        }
+      }
+    } else {
+      for (let r = 0; r < rows2; r++) {
+        for (let c = 0; c < cols; c++) {
+          const ref = puredocsExcel.cellRefFromRowCol(startRow + r, startCol + c);
+          arr.set(r, c, this.getCellValue(ref));
+        }
       }
     }
-    return FormulaValue.array(arr);
+    const value2 = FormulaValue.array(arr);
+    if (cache && rows2 > 0 && cols > 0) {
+      cache.set(sheetKey, startRow, startCol, endRow, endCol, value2, rows2 * cols);
+    }
+    return value2;
+  }
+  /**
+   * Resolves a whole-column (`A:A`) or whole-row (`1:1`) reference, bounded by
+   * the sheet's used range the way Excel does. Without a bound this would
+   * materialise a million-cell array for a sheet with twelve rows in it.
+   *
+   * A sheet that cannot report its extent yields `#REF!` rather than a guess:
+   * silently reading nothing would make SUM(A:A) return 0 on a full column.
+   */
+  getFullRangeValues(startCol, endCol, startRow, endRow) {
+    const bounds = __privateGet(this, _sheet).usedBounds;
+    if (!bounds) return FormulaValue.errorRef;
+    if (bounds.rowCount === 0 || bounds.columnCount === 0) return FormulaValue.blank;
+    const r0 = startRow ?? 1;
+    const r1 = endRow ?? bounds.rowCount;
+    const c0 = startCol ?? 1;
+    const c1 = endCol ?? bounds.columnCount;
+    const lastRow = Math.min(r1, bounds.rowCount);
+    const lastCol = Math.min(c1, bounds.columnCount);
+    if (lastRow < r0 || lastCol < c0) return FormulaValue.blank;
+    return this.getRangeValuesByIndex(r0, c0, lastRow, lastCol);
   }
   getSheetCellValue(sheetName, cellReference) {
     if (!this.workbook) return FormulaValue.errorRef;
     try {
-      const sheet = this.workbook.getWorksheet(sheetName);
-      const ctx = new _FormulaContext(sheet, this.formulaRow, this.formulaCol, __privateGet(this, _evaluating), __privateGet(this, _functions2));
-      ctx.workbook = this.workbook;
-      return ctx.getCellValue(cellReference);
+      return __privateMethod(this, _FormulaContext_instances, forSheet_fn).call(this, sheetName).getCellValue(cellReference);
     } catch {
       return FormulaValue.errorRef;
     }
@@ -4299,10 +4577,16 @@ var _FormulaContext = class _FormulaContext {
   getSheetRangeValues(sheetName, startRef, endRef) {
     if (!this.workbook) return FormulaValue.errorRef;
     try {
-      const sheet = this.workbook.getWorksheet(sheetName);
-      const ctx = new _FormulaContext(sheet, this.formulaRow, this.formulaCol, __privateGet(this, _evaluating), __privateGet(this, _functions2));
-      ctx.workbook = this.workbook;
-      return ctx.getRangeValues(startRef, endRef);
+      return __privateMethod(this, _FormulaContext_instances, forSheet_fn).call(this, sheetName).getRangeValues(startRef, endRef);
+    } catch {
+      return FormulaValue.errorRef;
+    }
+  }
+  /** Whole-column/whole-row reference qualified by a sheet name. */
+  getSheetFullRangeValues(sheetName, startCol, endCol, startRow, endRow) {
+    if (!this.workbook) return FormulaValue.errorRef;
+    try {
+      return __privateMethod(this, _FormulaContext_instances, forSheet_fn).call(this, sheetName).getFullRangeValues(startCol, endCol, startRow, endRow);
     } catch {
       return FormulaValue.errorRef;
     }
@@ -4357,6 +4641,21 @@ lookupScope_fn = function(name) {
   }
   return void 0;
 };
+/**
+ * A sibling context bound to another sheet, sharing this one's circular-
+ * reference guard and range memo. These contexts only read values — they
+ * never evaluate an AST — so the name resolver and recursion budget are
+ * deliberately not carried over; passing them would suggest a scoping
+ * relationship that does not exist. The memo, on the other hand, must be
+ * carried: cross-sheet ranges are the most expensive reads in a workbook.
+ */
+forSheet_fn = function(sheetName) {
+  const sheet = this.workbook.getWorksheet(sheetName);
+  const ctx = new _FormulaContext(sheet, this.formulaRow, this.formulaCol, __privateGet(this, _evaluating), __privateGet(this, _functions2));
+  ctx.workbook = this.workbook;
+  ctx.rangeCache = this.rangeCache;
+  return ctx;
+};
 var FormulaContext = _FormulaContext;
 
 // src/lru-cache.ts
@@ -4476,6 +4775,7 @@ function buildContext(sheet, opts) {
     evaluating
   );
   ctx.recursionGuard = opts.recursionGuard ?? { depth: 0, max: DEFAULT_LAMBDA_DEPTH };
+  ctx.rangeCache = opts.rangeCache;
   const wb = opts.workbook;
   if (wb) {
     ctx.workbook = wb;
@@ -4527,7 +4827,8 @@ function evaluateAst(ast, sheet, options) {
     const ctx = buildContext(sheet, {
       workbook: options?.workbook,
       formulaRow: options?.formulaRow,
-      formulaCol: options?.formulaCol
+      formulaCol: options?.formulaCol,
+      rangeCache: options?.rangeCache
     });
     return ast.evaluate(ctx);
   } catch {
@@ -4548,6 +4849,149 @@ function getAstCacheStats() {
 function setAstCacheCapacity(capacity) {
   astCache.resize(capacity);
 }
+
+// src/range-cache.ts
+var TILE_ROWS = 64;
+var TILE_COLS = 64;
+var MAX_TILES_PER_RANGE = 32;
+var DEFAULT_MAX_CELLS = 2e6;
+var _entries, _tiles, _wide, _placements, _sizes, _cells, _maxCells, _RangeCache_static, contains_fn, _RangeCache_instances, drop_fn, fileIn_fn;
+var _RangeCache = class _RangeCache {
+  constructor(maxCells = DEFAULT_MAX_CELLS) {
+    __privateAdd(this, _RangeCache_instances);
+    /** `SHEET r0 c0 r1 c1` → the memoised array value. Insertion-ordered (FIFO eviction). */
+    __privateAdd(this, _entries, /* @__PURE__ */ new Map());
+    /** `sheet tr tc` → entry keys whose rectangle overlaps that tile. */
+    __privateAdd(this, _tiles, /* @__PURE__ */ new Map());
+    /** sheet → entry keys whose rectangle is too broad to tile. */
+    __privateAdd(this, _wide, /* @__PURE__ */ new Map());
+    /** entry key → buckets it was filed under, for cheap removal. */
+    __privateAdd(this, _placements, /* @__PURE__ */ new Map());
+    /** entry key → its area, so eviction can give the budget back. */
+    __privateAdd(this, _sizes, /* @__PURE__ */ new Map());
+    /** Number of cells across all cached rectangles, kept under {@link #maxCells}. */
+    __privateAdd(this, _cells, 0);
+    __privateAdd(this, _maxCells);
+    this.hits = 0;
+    this.misses = 0;
+    __privateSet(this, _maxCells, maxCells);
+  }
+  get size() {
+    return __privateGet(this, _entries).size;
+  }
+  get cachedCells() {
+    return __privateGet(this, _cells);
+  }
+  static key(sheet, r0, c0, r1, c1) {
+    return `${sheet} ${r0} ${c0} ${r1} ${c1}`;
+  }
+  get(sheet, r0, c0, r1, c1) {
+    const hit = __privateGet(this, _entries).get(_RangeCache.key(sheet, r0, c0, r1, c1));
+    if (hit === void 0) this.misses++;
+    else this.hits++;
+    return hit;
+  }
+  /** Memoises a rectangle's value. `cells` is its area, for the budget. */
+  set(sheet, r0, c0, r1, c1, value2, cells) {
+    if (cells <= 0 || cells > __privateGet(this, _maxCells)) return;
+    const key = _RangeCache.key(sheet, r0, c0, r1, c1);
+    if (__privateGet(this, _entries).has(key)) __privateMethod(this, _RangeCache_instances, drop_fn).call(this, key);
+    __privateGet(this, _entries).set(key, value2);
+    __privateSet(this, _cells, __privateGet(this, _cells) + cells);
+    const buckets = [];
+    const tileRow0 = r0 / TILE_ROWS | 0, tileRow1 = r1 / TILE_ROWS | 0;
+    const tileCol0 = c0 / TILE_COLS | 0, tileCol1 = c1 / TILE_COLS | 0;
+    const tileCount = (tileRow1 - tileRow0 + 1) * (tileCol1 - tileCol0 + 1);
+    if (tileCount > MAX_TILES_PER_RANGE) {
+      __privateMethod(this, _RangeCache_instances, fileIn_fn).call(this, __privateGet(this, _wide), sheet, key, buckets, `w ${sheet}`);
+    } else {
+      for (let tr = tileRow0; tr <= tileRow1; tr++) {
+        for (let tc = tileCol0; tc <= tileCol1; tc++) {
+          const bucket = `${sheet} ${tr} ${tc}`;
+          __privateMethod(this, _RangeCache_instances, fileIn_fn).call(this, __privateGet(this, _tiles), bucket, key, buckets, `t ${bucket}`);
+        }
+      }
+    }
+    __privateGet(this, _placements).set(key, buckets);
+    __privateGet(this, _sizes).set(key, cells);
+    if (__privateGet(this, _cells) > __privateGet(this, _maxCells)) {
+      for (const oldest of __privateGet(this, _entries).keys()) {
+        if (__privateGet(this, _cells) <= __privateGet(this, _maxCells)) break;
+        if (oldest === key) continue;
+        __privateMethod(this, _RangeCache_instances, drop_fn).call(this, oldest);
+      }
+    }
+  }
+  /** Drops every cached rectangle containing the given cell. */
+  invalidateCell(sheet, row2, col) {
+    var _a, _b;
+    const tile = __privateGet(this, _tiles).get(`${sheet} ${row2 / TILE_ROWS | 0} ${col / TILE_COLS | 0}`);
+    if (tile) {
+      for (const key of [...tile]) {
+        if (__privateMethod(_a = _RangeCache, _RangeCache_static, contains_fn).call(_a, key, sheet, row2, col)) __privateMethod(this, _RangeCache_instances, drop_fn).call(this, key);
+      }
+    }
+    const wide = __privateGet(this, _wide).get(sheet);
+    if (wide) {
+      for (const key of [...wide]) {
+        if (__privateMethod(_b = _RangeCache, _RangeCache_static, contains_fn).call(_b, key, sheet, row2, col)) __privateMethod(this, _RangeCache_instances, drop_fn).call(this, key);
+      }
+    }
+  }
+  clear() {
+    __privateGet(this, _entries).clear();
+    __privateGet(this, _tiles).clear();
+    __privateGet(this, _wide).clear();
+    __privateGet(this, _placements).clear();
+    __privateGet(this, _sizes).clear();
+    __privateSet(this, _cells, 0);
+  }
+};
+_entries = new WeakMap();
+_tiles = new WeakMap();
+_wide = new WeakMap();
+_placements = new WeakMap();
+_sizes = new WeakMap();
+_cells = new WeakMap();
+_maxCells = new WeakMap();
+_RangeCache_static = new WeakSet();
+contains_fn = function(key, sheet, row2, col) {
+  const parts = key.split(" ");
+  const n = parts.length;
+  const c1 = +parts[n - 1], r1 = +parts[n - 2], c0 = +parts[n - 3], r0 = +parts[n - 4];
+  if (parts.slice(0, n - 4).join(" ") !== sheet) return false;
+  return row2 >= r0 && row2 <= r1 && col >= c0 && col <= c1;
+};
+_RangeCache_instances = new WeakSet();
+drop_fn = function(key) {
+  if (!__privateGet(this, _entries).delete(key)) return;
+  __privateSet(this, _cells, __privateGet(this, _cells) - (__privateGet(this, _sizes).get(key) ?? 0));
+  __privateGet(this, _sizes).delete(key);
+  const buckets = __privateGet(this, _placements).get(key);
+  if (buckets) {
+    for (const bucket of buckets) {
+      const store = bucket.charCodeAt(0) === 119 ? __privateGet(this, _wide) : __privateGet(this, _tiles);
+      const bucketKey = bucket.slice(2);
+      const set = store.get(bucketKey);
+      if (!set) continue;
+      set.delete(key);
+      if (set.size === 0) store.delete(bucketKey);
+    }
+    __privateGet(this, _placements).delete(key);
+  }
+};
+fileIn_fn = function(store, bucketKey, entryKey, buckets, bucketId) {
+  let set = store.get(bucketKey);
+  if (!set) {
+    set = /* @__PURE__ */ new Set();
+    store.set(bucketKey, set);
+  }
+  if (set.has(entryKey)) return;
+  set.add(entryKey);
+  buckets.push(bucketId);
+};
+__privateAdd(_RangeCache, _RangeCache_static);
+var RangeCache = _RangeCache;
 function extractReferences(ast, formulaSheet, registry = FunctionRegistry.default, resolveName2) {
   const refs = [];
   let volatile = false;
@@ -4576,6 +5020,14 @@ function extractReferences(ast, formulaSheet, registry = FunctionRegistry.defaul
       refs.push(cell(node.sheetName, node.cellReference));
     } else if (node instanceof SheetRangeReferenceNode) {
       refs.push(range(node.sheetName, node.startRef, node.endRef));
+    } else if (node instanceof FullRangeReferenceNode) {
+      refs.push({
+        sheet: (node.sheetName ?? formulaSheet).toUpperCase(),
+        startRow: node.startRow ?? 1,
+        endRow: node.endRow ?? puredocsExcel.EXCEL_MAX_ROWS,
+        startCol: node.startCol ?? 1,
+        endCol: node.endCol ?? puredocsExcel.EXCEL_MAX_COLUMNS
+      });
     } else if (node instanceof NamedRangeNode) {
       expandName(node.name);
     } else if (node instanceof SpillReferenceNode) {
@@ -4612,19 +5064,30 @@ function refContains(ref, sheet, row2, col) {
 }
 
 // src/dependency-index.ts
-var TILE_ROWS = 64;
-var TILE_COLS = 64;
+var TILE_ROWS2 = 64;
+var TILE_COLS2 = 64;
 var MAX_TILES_PER_REF = 32;
-var _tiles, _wide, _placements, _DependencyIndex_instances, fileIn_fn;
+var MAX_EXACT_SPAN = 16;
+var MAX_BUCKETS_PER_REF = 64;
+var tileOfRow = (row2) => row2 / TILE_ROWS2 | 0;
+var tileOfCol = (col) => col / TILE_COLS2 | 0;
+var _buckets, _placements2, _DependencyIndex_instances, visit_fn, file_fn;
 var DependencyIndex = class {
   constructor() {
     __privateAdd(this, _DependencyIndex_instances);
-    /** `sheet|tileRow|tileCol` → formula keys whose precedents overlap that tile. */
-    __privateAdd(this, _tiles, /* @__PURE__ */ new Map());
-    /** sheet → formula keys with a precedent too broad to tile. */
-    __privateAdd(this, _wide, /* @__PURE__ */ new Map());
-    /** formula key → the bucket keys it was filed under, for cheap removal. */
-    __privateAdd(this, _placements, /* @__PURE__ */ new Map());
+    /**
+     * All buckets in one map, keyed by a discriminating prefix:
+     *
+     *   `t s tr tc`  rectangle compact in both dimensions
+     *   `c s col tr` narrow columns, row tiles     (the common case)
+     *   `C s col`    narrow columns, every row     (`A:A`)
+     *   `r s row tc` narrow rows, column tiles
+     *   `R s row`    narrow rows, every column     (`1:1`)
+     *   `w s`        broad in both dimensions
+     */
+    __privateAdd(this, _buckets, /* @__PURE__ */ new Map());
+    /** formula key → the buckets it was filed under, for cheap removal. */
+    __privateAdd(this, _placements2, /* @__PURE__ */ new Map());
   }
   /** Registers (or re-registers) a formula's precedent rectangles. */
   add(formulaKey, refs) {
@@ -4632,78 +5095,117 @@ var DependencyIndex = class {
     if (refs.length === 0) return;
     const buckets = [];
     for (const ref of refs) {
-      const tileRow0 = ref.startRow / TILE_ROWS | 0;
-      const tileRow1 = ref.endRow / TILE_ROWS | 0;
-      const tileCol0 = ref.startCol / TILE_COLS | 0;
-      const tileCol1 = ref.endCol / TILE_COLS | 0;
-      const tileCount = (tileRow1 - tileRow0 + 1) * (tileCol1 - tileCol0 + 1);
-      if (tileCount > MAX_TILES_PER_REF) {
-        __privateMethod(this, _DependencyIndex_instances, fileIn_fn).call(this, __privateGet(this, _wide), ref.sheet, formulaKey, buckets, `w ${ref.sheet}`);
+      const rowSpan = ref.endRow - ref.startRow + 1;
+      const colSpan = ref.endCol - ref.startCol + 1;
+      const rowTile0 = tileOfRow(ref.startRow), rowTile1 = tileOfRow(ref.endRow);
+      const colTile0 = tileOfCol(ref.startCol), colTile1 = tileOfCol(ref.endCol);
+      const rowTiles = rowTile1 - rowTile0 + 1;
+      const colTiles = colTile1 - colTile0 + 1;
+      if (colSpan <= MAX_EXACT_SPAN && colSpan <= rowSpan) {
+        if (colSpan * rowTiles <= MAX_BUCKETS_PER_REF && rowTiles <= MAX_TILES_PER_REF) {
+          for (let col = ref.startCol; col <= ref.endCol; col++) {
+            for (let tr = rowTile0; tr <= rowTile1; tr++) {
+              __privateMethod(this, _DependencyIndex_instances, file_fn).call(this, `c ${ref.sheet} ${col} ${tr}`, formulaKey, buckets);
+            }
+          }
+        } else {
+          for (let col = ref.startCol; col <= ref.endCol; col++) {
+            __privateMethod(this, _DependencyIndex_instances, file_fn).call(this, `C ${ref.sheet} ${col}`, formulaKey, buckets);
+          }
+        }
         continue;
       }
-      for (let tr = tileRow0; tr <= tileRow1; tr++) {
-        for (let tc = tileCol0; tc <= tileCol1; tc++) {
-          const key = `${ref.sheet} ${tr} ${tc}`;
-          __privateMethod(this, _DependencyIndex_instances, fileIn_fn).call(this, __privateGet(this, _tiles), key, formulaKey, buckets, `t ${key}`);
+      if (rowSpan <= MAX_EXACT_SPAN) {
+        if (rowSpan * colTiles <= MAX_BUCKETS_PER_REF && colTiles <= MAX_TILES_PER_REF) {
+          for (let row2 = ref.startRow; row2 <= ref.endRow; row2++) {
+            for (let tc = colTile0; tc <= colTile1; tc++) {
+              __privateMethod(this, _DependencyIndex_instances, file_fn).call(this, `r ${ref.sheet} ${row2} ${tc}`, formulaKey, buckets);
+            }
+          }
+        } else {
+          for (let row2 = ref.startRow; row2 <= ref.endRow; row2++) {
+            __privateMethod(this, _DependencyIndex_instances, file_fn).call(this, `R ${ref.sheet} ${row2}`, formulaKey, buckets);
+          }
         }
+        continue;
       }
+      if (rowTiles * colTiles <= MAX_TILES_PER_REF) {
+        for (let tr = rowTile0; tr <= rowTile1; tr++) {
+          for (let tc = colTile0; tc <= colTile1; tc++) {
+            __privateMethod(this, _DependencyIndex_instances, file_fn).call(this, `t ${ref.sheet} ${tr} ${tc}`, formulaKey, buckets);
+          }
+        }
+        continue;
+      }
+      __privateMethod(this, _DependencyIndex_instances, file_fn).call(this, `w ${ref.sheet}`, formulaKey, buckets);
     }
-    __privateGet(this, _placements).set(formulaKey, buckets);
+    __privateGet(this, _placements2).set(formulaKey, buckets);
   }
   /** Forgets a formula. */
   remove(formulaKey) {
-    const buckets = __privateGet(this, _placements).get(formulaKey);
+    const buckets = __privateGet(this, _placements2).get(formulaKey);
     if (!buckets) return;
     for (const bucket of buckets) {
-      const wide = bucket.charCodeAt(0) === 119;
-      const store = wide ? __privateGet(this, _wide) : __privateGet(this, _tiles);
-      const key = bucket.slice(2);
-      const set = store.get(key);
+      const set = __privateGet(this, _buckets).get(bucket);
       if (!set) continue;
       set.delete(formulaKey);
-      if (set.size === 0) store.delete(key);
+      if (set.size === 0) __privateGet(this, _buckets).delete(bucket);
     }
-    __privateGet(this, _placements).delete(formulaKey);
+    __privateGet(this, _placements2).delete(formulaKey);
   }
   /** Drops every registration. */
   clear() {
-    __privateGet(this, _tiles).clear();
-    __privateGet(this, _wide).clear();
-    __privateGet(this, _placements).clear();
+    __privateGet(this, _buckets).clear();
+    __privateGet(this, _placements2).clear();
   }
   /**
    * Calls `visit` with the key of each formula that *may* read the given cell.
-   * Callers still confirm with {@link refContains}: a tile is coarser than a
-   * rectangle, so this over-approximates by at most a tile's worth.
+   * Callers still confirm with {@link refContains}: buckets are coarser than
+   * rectangles in the broad dimension, so this over-approximates.
+   *
+   * A fixed six lookups, whatever the workbook contains.
    */
   candidates(sheet, row2, col, visit) {
-    const tile = __privateGet(this, _tiles).get(
-      `${sheet} ${row2 / TILE_ROWS | 0} ${col / TILE_COLS | 0}`
-    );
-    if (tile) for (const key of tile) visit(key);
-    const wide = __privateGet(this, _wide).get(sheet);
-    if (wide) for (const key of wide) visit(key);
+    const tr = tileOfRow(row2);
+    const tc = tileOfCol(col);
+    __privateMethod(this, _DependencyIndex_instances, visit_fn).call(this, `c ${sheet} ${col} ${tr}`, visit);
+    __privateMethod(this, _DependencyIndex_instances, visit_fn).call(this, `C ${sheet} ${col}`, visit);
+    __privateMethod(this, _DependencyIndex_instances, visit_fn).call(this, `r ${sheet} ${row2} ${tc}`, visit);
+    __privateMethod(this, _DependencyIndex_instances, visit_fn).call(this, `R ${sheet} ${row2}`, visit);
+    __privateMethod(this, _DependencyIndex_instances, visit_fn).call(this, `t ${sheet} ${tr} ${tc}`, visit);
+    __privateMethod(this, _DependencyIndex_instances, visit_fn).call(this, `w ${sheet}`, visit);
   }
 };
-_tiles = new WeakMap();
-_wide = new WeakMap();
-_placements = new WeakMap();
+_buckets = new WeakMap();
+_placements2 = new WeakMap();
 _DependencyIndex_instances = new WeakSet();
-fileIn_fn = function(store, key, formulaKey, buckets, bucketId) {
-  let set = store.get(key);
+visit_fn = function(bucket, visit) {
+  const set = __privateGet(this, _buckets).get(bucket);
+  if (set) for (const key of set) visit(key);
+};
+file_fn = function(bucket, formulaKey, buckets) {
+  let set = __privateGet(this, _buckets).get(bucket);
   if (!set) {
     set = /* @__PURE__ */ new Set();
-    store.set(key, set);
+    __privateGet(this, _buckets).set(bucket, set);
   }
   if (set.has(formulaKey)) return;
   set.add(formulaKey);
-  buckets.push(bucketId);
+  buckets.push(bucket);
 };
 
 // src/recalc-engine.ts
 function createWorkbookRecalcModel(workbook) {
   return {
     getCellValue: (sheet, ref) => workbook.getWorksheet(sheet).getCellValue(ref),
+    // Falls back to the reference-string read rather than reporting "no value":
+    // an older core without getCellValueAt must still return the real value,
+    // because a silent undefined here reads as a blank cell.
+    getCellValueAt: (sheet, row2, column2) => {
+      const ws = workbook.getWorksheet(sheet);
+      return ws.getCellValueAt ? ws.getCellValueAt(row2, column2) : ws.getCellValue(puredocsExcel.cellRefFromRowCol(row2, column2));
+    },
+    getUsedBounds: (sheet) => workbook.getWorksheet(sheet).usedBounds,
     setCellValue: (sheet, ref, value2) => {
       workbook.getWorksheet(sheet).getCell(ref).setComputedValue(value2);
     },
@@ -4732,7 +5234,7 @@ function parseKey(key) {
   const { row: row2, column: column2 } = puredocsExcel.parseCellRef(ref);
   return { sheet, ref, row: row2, col: column2 };
 }
-var _model, _registry, _formulas, _sheetNames, _spills, _spillOwner, _dependents, _volatiles, _sheetLikes, _workbookLike, _RecalcEngine_instances, register_fn, unregister_fn, rememberSheet_fn, applyShift_fn, shiftPrecedents_fn, shiftSpillBookkeeping_fn, recalcFrom_fn, runFixpoint_fn, addVolatiles_fn, dependentClosure_fn, forEachDirectDependent_fn, evaluatePass_fn, writeResult_fn, isOccupied_fn, clearSpill_fn, evaluateFormulaValue_fn, sheetLike_fn, buildSheetLike_fn, buildWorkbookLike_fn;
+var _model, _registry, _formulas, _sheetNames, _spills, _spillOwner, _dependents, _volatiles, _sheetLikes, _workbookLike, _rangeCache, _RecalcEngine_instances, writeCell_fn, register_fn, unregister_fn, rememberSheet_fn, recalcInOrder_fn, applyShift_fn, shiftPrecedents_fn, shiftSpillBookkeeping_fn, recalcFrom_fn, runFixpoint_fn, addVolatiles_fn, dependentClosure_fn, forEachDirectDependent_fn, evaluatePass_fn, writeResult_fn, isOccupied_fn, clearSpill_fn, evaluateFormulaValue_fn, sheetLike_fn, buildSheetLike_fn, buildWorkbookLike_fn;
 var RecalcEngine = class {
   constructor(model, registry = FunctionRegistry.default) {
     __privateAdd(this, _RecalcEngine_instances);
@@ -4758,6 +5260,14 @@ var RecalcEngine = class {
     /** Memoised per-sheet adapters — these are stateless w.r.t. the formula. */
     __privateAdd(this, _sheetLikes, /* @__PURE__ */ new Map());
     __privateAdd(this, _workbookLike);
+    /**
+     * Memo for range reads. The engine owns it because it owns the writes: every
+     * value written goes through {@link #writeCell}, which drops the cached
+     * rectangles containing that cell. Nothing else may write to the model behind
+     * the engine's back without calling {@link onCellChanged} — that was already
+     * true for dependency tracking, and now also keeps this memo honest.
+     */
+    __privateAdd(this, _rangeCache, new RangeCache());
     __privateSet(this, _model, model);
     __privateSet(this, _registry, registry);
   }
@@ -4795,8 +5305,63 @@ var RecalcEngine = class {
       volatile
     });
     __privateGet(this, _model).setCellFormula?.(sheet, r, text);
+    __privateGet(this, _rangeCache).invalidateCell(s, row2, column2);
     return __privateMethod(this, _RecalcEngine_instances, recalcFrom_fn).call(this, [{ sheet: s, row: row2, col: column2 }], key);
   }
+  /**
+   * Indexes many formulas **without evaluating anything**.
+   *
+   * This is the path for loading a workbook. `setCellFormula` is built for an
+   * edit: it recalculates the new cell and everything downstream of it, which is
+   * right for one keystroke and quadratic for a file — registering N formulas one
+   * by one evaluates the whole workbook N times. Here the formulas are only
+   * parsed and filed into the dependency index; call {@link recalcAll} once
+   * afterwards, or nothing at all if the cached values from the file will do.
+   *
+   * The model is deliberately **not** written to. These formulas are assumed to
+   * be the ones the model already holds (they came from the file), and persisting
+   * them again would clear each cell's cached value — leaving every formula cell
+   * blank until a full recalculation had run. Use `setCellFormula` for formulas
+   * the user is actually introducing.
+   *
+   * A formula that fails to parse is reported rather than thrown: one unsupported
+   * construct in a large workbook should not abort the load.
+   */
+  registerBulk(entries) {
+    const resolveName2 = __privateGet(this, _model).getDefinedName ? (n, sh) => __privateGet(this, _model).getDefinedName(n, sh) : void 0;
+    let registered = 0;
+    const failed = [];
+    for (const entry of entries) {
+      const { sheet, ref, formula } = entry;
+      if (!formula) continue;
+      const text = formula.startsWith("=") ? formula.slice(1) : formula;
+      const s = normSheet(sheet);
+      const r = normRef(ref);
+      try {
+        const { row: row2, column: column2 } = puredocsExcel.parseCellRef(r);
+        const ast = parseFormulaUncached(text);
+        const { refs, volatile } = extractReferences(ast, s, __privateGet(this, _registry), resolveName2);
+        __privateMethod(this, _RecalcEngine_instances, rememberSheet_fn).call(this, sheet);
+        __privateMethod(this, _RecalcEngine_instances, register_fn).call(this, {
+          sheet: s,
+          sheetName: sheet,
+          ref: r,
+          key: keyOf(s, r),
+          row: row2,
+          col: column2,
+          formula: text,
+          ast,
+          refs,
+          volatile
+        });
+        registered++;
+      } catch (err) {
+        failed.push({ sheet, ref, error: err instanceof Error ? err.message : String(err) });
+      }
+    }
+    if (registered > 0) __privateGet(this, _rangeCache).clear();
+    return { registered, failed };
+  }
   /**
    * Removes a formula from a cell and recalculates its dependents (which may now
    * read a plain input value instead). Returns the recomputed dependent cells.
@@ -4809,6 +5374,7 @@ var RecalcEngine = class {
     __privateMethod(this, _RecalcEngine_instances, unregister_fn).call(this, key);
     __privateGet(this, _model).clearCell?.(sheet, r);
     const { row: row2, column: column2 } = puredocsExcel.parseCellRef(r);
+    __privateGet(this, _rangeCache).invalidateCell(s, row2, column2);
     return __privateMethod(this, _RecalcEngine_instances, recalcFrom_fn).call(this, [{ sheet: s, row: row2, col: column2 }]);
   }
   /**
@@ -4819,8 +5385,8 @@ var RecalcEngine = class {
     __privateMethod(this, _RecalcEngine_instances, rememberSheet_fn).call(this, sheet);
     const s = normSheet(sheet);
     const r = normRef(ref);
-    __privateGet(this, _model).setCellValue(sheet, r, value2);
     const { row: row2, column: column2 } = puredocsExcel.parseCellRef(r);
+    __privateMethod(this, _RecalcEngine_instances, writeCell_fn).call(this, sheet, r, value2, row2, column2);
     return __privateMethod(this, _RecalcEngine_instances, recalcFrom_fn).call(this, [{ sheet: s, row: row2, col: column2 }]);
   }
   /**
@@ -4832,11 +5398,48 @@ var RecalcEngine = class {
     const s = normSheet(sheet);
     const r = normRef(ref);
     const { row: row2, column: column2 } = puredocsExcel.parseCellRef(r);
+    __privateGet(this, _rangeCache).invalidateCell(s, row2, column2);
     return __privateMethod(this, _RecalcEngine_instances, recalcFrom_fn).call(this, [{ sheet: s, row: row2, col: column2 }]);
   }
-  /** Recalculates every registered formula in dependency order. */
-  recalcAll() {
-    return __privateMethod(this, _RecalcEngine_instances, evaluatePass_fn).call(this, [...__privateGet(this, _formulas).values()]).results;
+  /**
+   * Recalculates every registered formula.
+   *
+   * By default the order is derived here, with a topological sort over the
+   * dependency index. `order` — typically `workbook.calcChain` — supplies one
+   * instead, so the sort is not needed.
+   *
+   * **A supplied order is verified, not trusted.** Evaluating in a stale order
+   * makes a formula read a precedent that has not been computed yet, and the
+   * result is a plausible wrong number with nothing to distinguish it from a
+   * right one. In a calculation engine that is the worst failure available, so
+   * this checks as it goes: after each formula is written, the dependency index
+   * says who reads it, and any reader that was already evaluated is an inversion.
+   * On the first inversion the ordered attempt is abandoned and the whole
+   * recalculation is redone through the sorted path, whose result is returned;
+   * `onOrderConflict`, if given, is told which pair conflicted.
+   *
+   * The verification costs about what the sort it replaces costs, so `order` is
+   * worth roughly nothing now (measured at ~9% of a full recalculation on a
+   * 2 000-formula workbook, after the dependency index stopped being the
+   * bottleneck). It is kept because reading an order Excel already computed is a
+   * reasonable thing to want; prefer plain `recalcAll()` unless you have measured
+   * a reason not to.
+   *
+   * Registered formulas the order does not mention are evaluated afterwards
+   * through the sorted path, and a dynamic array that spills still triggers the
+   * usual fixpoint, so neither silently misses cells.
+   */
+  recalcAll(options) {
+    const order = options?.order;
+    if (!order || order.length === 0) {
+      return __privateMethod(this, _RecalcEngine_instances, evaluatePass_fn).call(this, [...__privateGet(this, _formulas).values()]).results;
+    }
+    const attempt = __privateMethod(this, _RecalcEngine_instances, recalcInOrder_fn).call(this, order);
+    if (attempt.conflict) {
+      options?.onOrderConflict?.(attempt.conflict);
+      return __privateMethod(this, _RecalcEngine_instances, evaluatePass_fn).call(this, [...__privateGet(this, _formulas).values()]).results;
+    }
+    return attempt.results;
   }
   /** The precedents recorded for a formula cell (mainly for tests/inspection). */
   getPrecedents(sheet, ref) {
@@ -4886,7 +5489,23 @@ _dependents = new WeakMap();
 _volatiles = new WeakMap();
 _sheetLikes = new WeakMap();
 _workbookLike = new WeakMap();
+_rangeCache = new WeakMap();
 _RecalcEngine_instances = new WeakSet();
+/**
+ * The single write path into the model. Writing a value invalidates the
+ * cached rectangles that contain the cell, so a formula evaluated later in the
+ * same pass cannot read a pre-write copy of a range. Coordinates are passed in
+ * where the caller already knows them, to avoid re-parsing the reference.
+ */
+writeCell_fn = function(sheetName, ref, value2, row2, col) {
+  __privateGet(this, _model).setCellValue(sheetName, ref, value2);
+  if (row2 === void 0 || col === void 0) {
+    const parsed = puredocsExcel.parseCellRef(ref);
+    row2 = parsed.row;
+    col = parsed.column;
+  }
+  __privateGet(this, _rangeCache).invalidateCell(normSheet(sheetName), row2, col);
+};
 /** Registers an entry in the map, the reverse index and the volatile set. */
 register_fn = function(entry) {
   __privateGet(this, _formulas).set(entry.key, entry);
@@ -4902,6 +5521,49 @@ unregister_fn = function(key) {
 rememberSheet_fn = function(name) {
   __privateGet(this, _sheetNames).set(normSheet(name), name);
 };
+/**
+ * One pass in a caller-supplied order, watching for inversions.
+ *
+ * The check is the mirror image of the topological sort: instead of asking
+ * "which of my precedents come first?", it asks, of each formula just
+ * evaluated, "has anything that reads me already run?". The dependency index
+ * answers that directly, and one positive answer is enough to know the order
+ * cannot be trusted.
+ */
+recalcInOrder_fn = function(order) {
+  const results = [];
+  const changed = [];
+  const done = /* @__PURE__ */ new Set();
+  let spilled = false;
+  for (const { sheet, ref } of order) {
+    const key = keyOf(sheet, ref);
+    if (done.has(key)) continue;
+    const entry = __privateGet(this, _formulas).get(key);
+    if (!entry) continue;
+    done.add(key);
+    const written = __privateMethod(this, _RecalcEngine_instances, writeResult_fn).call(this, entry);
+    results.push(written.result);
+    changed.push(...written.changed);
+    if (written.result.spill) spilled = true;
+    let conflict;
+    __privateMethod(this, _RecalcEngine_instances, forEachDirectDependent_fn).call(this, { sheet: entry.sheet, row: entry.row, col: entry.col }, (dep) => {
+      if (conflict || dep.key === entry.key) return;
+      if (done.has(dep.key)) conflict = { dependent: dep.key, precedent: entry.key };
+    });
+    if (conflict) return { results: [], conflict };
+  }
+  const rest = [...__privateGet(this, _formulas).values()].filter((e) => !done.has(e.key));
+  if (rest.length > 0) {
+    const pass = __privateMethod(this, _RecalcEngine_instances, evaluatePass_fn).call(this, rest);
+    results.push(...pass.results);
+    changed.push(...pass.changed);
+  }
+  if (spilled) {
+    const evaluated = new Set(done);
+    results.push(...__privateMethod(this, _RecalcEngine_instances, runFixpoint_fn).call(this, __privateMethod(this, _RecalcEngine_instances, dependentClosure_fn).call(this, changed, evaluated), evaluated));
+  }
+  return { results };
+};
 applyShift_fn = function(shift) {
   const editedSheet = normSheet(shift.sheetName);
   const isRowShift = shift.dim === "row";
@@ -4943,6 +5605,7 @@ applyShift_fn = function(shift) {
   __privateGet(this, _volatiles).clear();
   for (const e of rekeyed) __privateMethod(this, _RecalcEngine_instances, register_fn).call(this, e);
   __privateMethod(this, _RecalcEngine_instances, shiftSpillBookkeeping_fn).call(this, shift, editedSheet);
+  __privateGet(this, _rangeCache).clear();
   const pending = /* @__PURE__ */ new Map();
   for (const k of needsRecalc) {
     const e = __privateGet(this, _formulas).get(k);
@@ -5013,7 +5676,7 @@ shiftSpillBookkeeping_fn = function(shift, editedSheet) {
         const shifted = shiftCellKey(m);
         if (!shifted) continue;
         const cell = parseKey(shifted);
-        __privateGet(this, _model).setCellValue(__privateGet(this, _sheetNames).get(cell.sheet) ?? cell.sheet, cell.ref, null);
+        __privateMethod(this, _RecalcEngine_instances, writeCell_fn).call(this, __privateGet(this, _sheetNames).get(cell.sheet) ?? cell.sheet, cell.ref, null, cell.row, cell.col);
       }
       continue;
     }
@@ -5154,7 +5817,7 @@ evaluatePass_fn = function(entries) {
     if (emitted.has(k)) continue;
     __privateMethod(this, _RecalcEngine_instances, clearSpill_fn).call(this, e.key, changed);
     const value2 = FormulaValue.errorRef.toObject();
-    __privateGet(this, _model).setCellValue(e.sheetName, e.ref, value2);
+    __privateMethod(this, _RecalcEngine_instances, writeCell_fn).call(this, e.sheetName, e.ref, value2, e.row, e.col);
     changed.push({ sheet: e.sheet, row: e.row, col: e.col });
     results.push({ sheet: e.sheetName, ref: e.ref, value: value2, circular: true });
   }
@@ -5175,7 +5838,7 @@ writeResult_fn = function(e) {
     __privateMethod(this, _RecalcEngine_instances, clearSpill_fn).call(this, anchorKey, changed);
     __privateGet(this, _model).setCellArrayRef?.(e.sheetName, e.ref, null);
     const value2 = fv2.toObject();
-    __privateGet(this, _model).setCellValue(e.sheetName, e.ref, value2);
+    __privateMethod(this, _RecalcEngine_instances, writeCell_fn).call(this, e.sheetName, e.ref, value2, e.row, e.col);
     changed.push({ sheet: e.sheet, row: e.row, col: e.col });
     return { result: { sheet: e.sheetName, ref: e.ref, value: value2 }, changed };
   }
@@ -5196,7 +5859,7 @@ writeResult_fn = function(e) {
     __privateMethod(this, _RecalcEngine_instances, clearSpill_fn).call(this, anchorKey, changed);
     __privateGet(this, _model).setCellArrayRef?.(e.sheetName, e.ref, null);
     const value2 = FormulaValue.error(9 /* Spill */).toObject();
-    __privateGet(this, _model).setCellValue(e.sheetName, e.ref, value2);
+    __privateMethod(this, _RecalcEngine_instances, writeCell_fn).call(this, e.sheetName, e.ref, value2, e.row, e.col);
     changed.push({ sheet: e.sheet, row: e.row, col: e.col });
     return { result: { sheet: e.sheetName, ref: e.ref, value: value2 }, changed };
   }
@@ -5205,7 +5868,7 @@ writeResult_fn = function(e) {
     for (let dc = 0; dc < cols; dc++) {
       const r = e.row + dr, c = e.col + dc;
       const ref = puredocsExcel.cellRefFromRowCol(r, c);
-      __privateGet(this, _model).setCellValue(e.sheetName, ref, arr.get(dr, dc).toObject());
+      __privateMethod(this, _RecalcEngine_instances, writeCell_fn).call(this, e.sheetName, ref, arr.get(dr, dc).toObject(), r, c);
       changed.push({ sheet: e.sheet, row: r, col: c });
       if (dr !== 0 || dc !== 0) {
         const cellKey2 = keyOf(e.sheet, ref);
@@ -5217,7 +5880,7 @@ writeResult_fn = function(e) {
   for (const oldKey of prevSpill) {
     if (newSpill.has(oldKey)) continue;
     const cell = parseKey(oldKey);
-    __privateGet(this, _model).setCellValue(__privateGet(this, _sheetNames).get(cell.sheet) ?? cell.sheet, cell.ref, null);
+    __privateMethod(this, _RecalcEngine_instances, writeCell_fn).call(this, __privateGet(this, _sheetNames).get(cell.sheet) ?? cell.sheet, cell.ref, null, cell.row, cell.col);
     __privateGet(this, _spillOwner).delete(oldKey);
     changed.push({ sheet: cell.sheet, row: cell.row, col: cell.col });
   }
@@ -5244,7 +5907,7 @@ clearSpill_fn = function(anchorKey, changed) {
   if (!spill) return;
   for (const cellKey2 of spill) {
     const cell = parseKey(cellKey2);
-    __privateGet(this, _model).setCellValue(__privateGet(this, _sheetNames).get(cell.sheet) ?? cell.sheet, cell.ref, null);
+    __privateMethod(this, _RecalcEngine_instances, writeCell_fn).call(this, __privateGet(this, _sheetNames).get(cell.sheet) ?? cell.sheet, cell.ref, null, cell.row, cell.col);
     __privateGet(this, _spillOwner).delete(cellKey2);
     changed.push({ sheet: cell.sheet, row: cell.row, col: cell.col });
   }
@@ -5261,7 +5924,8 @@ evaluateFormulaValue_fn = function(e) {
   return evaluateAst(e.ast, __privateMethod(this, _RecalcEngine_instances, sheetLike_fn).call(this, e.sheetName), {
     workbook: __privateMethod(this, _RecalcEngine_instances, buildWorkbookLike_fn).call(this),
     formulaRow: e.row,
-    formulaCol: e.col
+    formulaCol: e.col,
+    rangeCache: __privateGet(this, _rangeCache)
   });
 };
 /**
@@ -5278,9 +5942,16 @@ sheetLike_fn = function(sheetName) {
   return cached;
 };
 buildSheetLike_fn = function(sheetName) {
+  const model = __privateGet(this, _model);
   return {
     name: sheetName,
     getCellValue: (ref) => __privateGet(this, _model).getCellValue(sheetName, ref),
+    getCellValueAt: model.getCellValueAt ? (row2, column2) => model.getCellValueAt(sheetName, row2, column2) : void 0,
+    // A getter, not a snapshot: the extent grows as formulas write results,
+    // and a whole-column reference read later in the same pass must see it.
+    get usedBounds() {
+      return model.getUsedBounds?.(sheetName);
+    },
     isRowHidden: __privateGet(this, _model).isRowHidden ? (row2) => __privateGet(this, _model).isRowHidden(sheetName, row2) : void 0,
     getCellFormula: __privateGet(this, _model).getCellFormula ? (ref) => __privateGet(this, _model).getCellFormula(sheetName, ref) : void 0,
     getSpillRange: __privateGet(this, _model).getSpillRange ? (ref) => __privateGet(this, _model).getSpillRange(sheetName, ref) : void 0
@@ -5319,12 +5990,14 @@ exports.FormulaLexer = FormulaLexer;
 exports.FormulaNode = FormulaNode;
 exports.FormulaParser = FormulaParser;
 exports.FormulaValue = FormulaValue;
+exports.FullRangeReferenceNode = FullRangeReferenceNode;
 exports.FunctionCallNode = FunctionCallNode;
 exports.FunctionRegistry = FunctionRegistry;
 exports.ImplicitIntersectionNode = ImplicitIntersectionNode;
 exports.LruCache = LruCache;
 exports.NamedRangeNode = NamedRangeNode;
 exports.NumberNode = NumberNode;
+exports.RangeCache = RangeCache;
 exports.RangeReferenceNode = RangeReferenceNode;
 exports.RecalcEngine = RecalcEngine;
 exports.SheetCellReferenceNode = SheetCellReferenceNode;