@lotics/cli 0.143.0 → 0.143.3

package/AGENTS.md

@@ -1,9 +1,7 @@
 # @lotics/cli — agent index
 
 The model an agent needs before driving this CLI: which surface answers which question, what the
-conventions are, and where the traps are. It deliberately does **not** list commands — `lotics --help`
-renders § COMMANDS from the same table the CLI dispatches on, so it is the one inventory that cannot
-fall behind the binary you have.
+conventions are, and where the traps are.
 
 | Read | For |
 |---|---|
@@ -51,18 +49,15 @@ whether something exists, read `lotics --help` § COMMANDS — the whole section
   `workspace doctor` on findings. Scripts can gate on them.
 - **Text output is the default and is built for reading**; reach for `--json` only when a field is
   needed programmatically.
-- **`lotics report '<json>'` is the channel for what nothing else records.** Telemetry is keyed off
-  commands that FAILED, so the two classes worth the most are invisible to it: a capability that
-  does not exist (no command ran) and a run that exited 0 having done the wrong thing. Reach for it
-  when the platform is genuinely missing something, when a success was wrong, or when an error did
+- **`lotics report '<json>'` is the channel for what nothing else records.** Reach for it
+  when the platform is genuinely missing something (a capability that does not exist — no
+  command ran), when a success was wrong (exited 0, wrong effect), or when an error did
   not name the remedy — not for your own mistakes, which the logs already show.
   **It is a frame, not a paragraph** — `{goal, actual, expected?, tried?, wanted?}`, because a log
   reconstructs what you RAN and never what you WANTED, and that gap is the report. `goal` and
-  `actual` are required; there is no severity or category to pick (how bad and how common are read
-  off the corpus, and a taxonomy in a released binary cannot be corrected without a release). The
+  `actual` are required; there is no severity or category to pick. The
   session's commands attach themselves — do not retype them. Run it bare for the full prompt; a
-  long one rides `@file.json` or an explicit `-` for stdin (bare NEVER reads stdin, so an
-  inherited pipe cannot wedge the one command meant to unblock you).
+  long one rides `@file.json` or an explicit `-` for stdin (bare NEVER reads stdin).
 - **`LOTICS_TELEMETRY=1` correlates a whole session** so the authoring loop's rough edges can be
   found and fixed. Off by default; set it in the shell profile, not per command (each invocation is
   its own process). It sends no arguments, no file contents, and no record data — see README
@@ -93,7 +88,3 @@ whether something exists, read `lotics --help` § COMMANDS — the whole section
   `src/agents/<alias>.md` and is pushed by `app agent set`.
 - **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.
 - **Anything needing a browser.** `app dev` and `file preview` shell out to a local Chrome.
-
-Everything above is a *known* boundary. When you hit one that is NOT listed here — a verb that
-should exist and does not — that is the gap worth reporting, and `lotics report` is how it reaches
-us. Working around it silently is how it stays missing.

package/README.md

@@ -23,9 +23,12 @@ time, so a doc or a whole package added upstream shows up without upgrading this
 Per-command contracts, flags, exit codes and gotchas are in
 [docs/cli_reference.md](./docs/cli_reference.md); `lotics --help` is the always-current verb list.
 
-Two of the platform's primary surfaces have dedicated usage guides that ship inside this
+The platform's primary surfaces have dedicated usage guides that ship inside this
 package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
 
+- [`docs/building_an_app.md`](docs/building_an_app.md) — building a custom-code app end to end:
+  the sequence the steps go in (clarify → model → types → queries → workflows → screens → ship)
+  and the deploy-free inner loop. Read it once before starting an app.
 - [`docs/document_templates.md`](docs/document_templates.md) — generate finished documents
   (PDF, Excel, Word, email) by filling reusable templates: the five template types, the
   create → generate → chain lifecycle, and the marker capabilities.
@@ -33,8 +36,6 @@ package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
   workspace facts an agent can't guess, the access-vs-activation model, and the
   catalog-then-stage retrieval model agents use to pull only the lines they need.
 
-Both point to `lotics tools <name>` for exact input schemas.
-
 ## Install
 
 ```bash
@@ -118,7 +119,7 @@ Every request identifies the CLI (`user-agent: lotics-cli/<version> node/<v> <pl
 - Requests carry a session id shared by every command in the sitting — under an agent harness it adopts the harness's own session id, otherwise it rolls over after 30 minutes idle (`~/.lotics/session.json`).
 - Each invocation appends one record to `~/.lotics/telemetry.ndjson` — the command, its exit code, how long it took, and, on a failure, the message that was printed. Batches are sent on a later run; a failed send is retried, never dropped silently.
 
-Arguments contribute a **hash** and a **shape** (`records[].data.name:string`) and nothing else — no values, no file contents, no record data. The hash is the point: two failures in a row with the same hash mean the error message did not tell you enough to fix the call, which is how bad errors get found. This turns "this command failed" into "this command failed after these eleven, and the agent never recovered."
+Arguments contribute a **hash** and a **shape** (`records[].data.name:string`) and nothing else — no values, no file contents, no record data. The hash is the point: two failures in a row with the same hash mean the error message did not tell you enough to fix the call.
 
 Unset, nothing is stored, nothing is sent, and no spool file is created.
 
@@ -148,14 +149,10 @@ reconstruct what you *wanted*, and the gap between the two is the report.
 | `tried` | | what you already tried, and what it said |
 | `wanted` | | what would have unblocked you |
 
-There is no severity or category to pick. How bad and how common are read off the corpus; what you
-were trying to do is not recoverable from anywhere else.
+There is no severity or category to pick.
 
-Reading from stdin needs an explicit `-`. `report`'s only argument IS the report, so a bare
-invocation and a piped one look identical in argv — and "is this a pipe?" cannot tell a live
-writer from a descriptor a supervisor left open, so guessing either hangs forever or drops a
-slow writer's report. With `-` the bare form always prints the frame and a piped one waits as
-long as it takes.
+Reading from stdin needs an explicit `-`. With `-` the bare form always prints the frame and a
+piped one waits as long as it takes.
 
 If `LOTICS_TELEMETRY=1` is set, the commands from your session attach themselves — don't retype
 them. It runs whether or not telemetry is on (invoking it is the consent that passive recording
@@ -163,7 +160,7 @@ needs an opt-in for), posts immediately, and tells you if it did not land.
 
 Do not paste records, file contents, or credentials.
 
-In an app project, `lotics app *` commands derive the credential from the directory when nothing explicit chose one: the manifest names the app's workspace, and when exactly one saved profile owns that workspace, that profile is used — the machine-wide default (which another shell can move between two of your commands) is never consulted. An explicit flag, env var, or directory pin still wins, and an org whose profile remembers a different workspace simply falls through to the announced default, exactly as before.
+In an app project, `lotics app *` commands derive the credential from the directory when nothing explicit chose one: the manifest names the app's workspace, and when exactly one saved profile owns that workspace, that profile is used — the machine-wide default is never consulted. An explicit flag, env var, or directory pin still wins, and an org whose profile remembers a different workspace simply falls through to the announced default.
 
 ## Workspaces
 
@@ -313,7 +310,6 @@ cat input.json | lotics app agent run app_abc recognize        # inputs via stdi
 lotics app agent run app_abc recognize --json                  # full run summary to stdout
 lotics app agent run app_abc recognize --session cli-123 '{}'  # continue an existing thread
 
-# Dev-link @lotics/ui to packages/ui/src for live HMR (Vite alias; deploy bundles it)
 # Dev-link @lotics/ui to a monorepo checkout for ONE command — nothing is written to disk
 LOTICS_UI_SRC=/abs/monorepo/packages/ui/src lotics app dev
 LOTICS_UI_SRC=/abs/monorepo/packages/ui/src lotics app deploy -m "..."   # warns: bundles YOUR kit copy

package/dist/render_page.js

@@ -4563,7 +4563,7 @@ ${e.toString()}`);
         }
       };
       var type2Number = { "boolean": 3, "string": 2, "number": 1 };
-      var Infix = {
+      var Infix2 = {
         compareOp: (value1, infix, value2, isArray1, isArray2) => {
           if (value1 == null) value1 = 0;
           if (value2 == null) value2 = 0;
@@ -4654,7 +4654,7 @@ ${e.toString()}`);
       module2.exports = {
         Prefix,
         Postfix,
-        Infix,
+        Infix: Infix2,
         Operators: {
           compareOp: ["<", ">", "=", "<>", "<=", ">="],
           concatOp: ["&"],
@@ -4669,7 +4669,7 @@ ${e.toString()}`);
     "../../node_modules/fast-formula-parser/formulas/functions/math.js"(exports2, module2) {
       var FormulaError = require_error();
       var { FormulaHelpers, Types, Factorials, Criteria } = require_helpers();
-      var { Infix } = require_operators();
+      var { Infix: Infix2 } = require_operators();
       var H = FormulaHelpers;
       var f = [];
       var fd2 = [];
@@ -5192,7 +5192,7 @@ ${e.toString()}`);
                 if (criteria.match === criteria.value.test(value2)) {
                   sum += valueToAdd;
                 }
-              } else if (Infix.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
+              } else if (Infix2.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
                 sum += valueToAdd;
               }
             });
@@ -11472,7 +11472,7 @@ ${e.toString()}`);
     "../../node_modules/fast-formula-parser/formulas/functions/statistical.js"(exports2, module2) {
       var FormulaError = require_error();
       var { FormulaHelpers, Types, Criteria, Address } = require_helpers();
-      var { Infix } = require_operators();
+      var { Infix: Infix2 } = require_operators();
       var H = FormulaHelpers;
       var { DistributionFunctions } = require_distribution();
       var StatisticalFunctions = {
@@ -11534,7 +11534,7 @@ ${e.toString()}`);
                   sum += valueToAdd;
                   cnt++;
                 }
-              } else if (Infix.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
+              } else if (Infix2.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
                 sum += valueToAdd;
                 cnt++;
               }
@@ -11573,7 +11573,7 @@ ${e.toString()}`);
               if (criteria.op === "wc") {
                 if (criteria.match === criteria.value.test(value2))
                   cnt++;
-              } else if (Infix.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
+              } else if (Infix2.compareOp(value2, criteria.op, criteria.value, Array.isArray(value2), isCriteriaArray)) {
                 cnt++;
               }
             });
@@ -21126,7 +21126,7 @@ ${e.toString()}`);
     "../../node_modules/fast-formula-parser/grammar/utils.js"(exports2, module2) {
       var FormulaError = require_error();
       var { Address } = require_helpers();
-      var { Prefix, Postfix, Infix, Operators } = require_operators();
+      var { Prefix, Postfix, Infix: Infix2, Operators } = require_operators();
       var Collection = require_collection();
       var MAX_ROW = 1048576;
       var MAX_COLUMN = 16384;
@@ -21250,11 +21250,11 @@ ${e.toString()}`);
           if (this.isFormulaError(val2))
             return val2;
           if (Operators.compareOp.includes(infix))
-            return Infix.compareOp(val1, infix, val2, isArray1, isArray2);
+            return Infix2.compareOp(val1, infix, val2, isArray1, isArray2);
           else if (Operators.concatOp.includes(infix))
-            return Infix.concatOp(val1, infix, val2, isArray1, isArray2);
+            return Infix2.concatOp(val1, infix, val2, isArray1, isArray2);
           else if (Operators.mathOp.includes(infix))
-            return Infix.mathOp(val1, infix, val2, isArray1, isArray2);
+            return Infix2.mathOp(val1, infix, val2, isArray1, isArray2);
           else
             throw new Error(`Unrecognized infix: ${infix}`);
         }
@@ -21806,7 +21806,7 @@ ${e.toString()}`);
     "../../node_modules/fast-formula-parser/grammar/dependency/utils.js"(exports2, module2) {
       var FormulaError = require_error();
       var { FormulaHelpers, Types, Address } = require_helpers();
-      var { Prefix, Postfix, Infix, Operators } = require_operators();
+      var { Prefix, Postfix, Infix: Infix2, Operators } = require_operators();
       var Collection = require_collection();
       var MAX_ROW = 1048576;
       var MAX_COLUMN = 16384;
@@ -53990,14 +53990,14 @@ ${e.toString()}`);
     if (!range) return void 0;
     const header = [];
     for (let col = range.startCol; col <= range.endCol; col++) {
-      const cell = sheet.getCell(rowColToRef(range.startRow, col));
+      const cell = sheet.getCellAt(range.startRow, col);
       header.push(formatHeader(cell?.value));
     }
     const records = [];
     for (let row = range.startRow + 1; row <= range.endRow; row++) {
       const rec = [];
       for (let col = range.startCol; col <= range.endCol; col++) {
-        const cell = sheet.getCell(rowColToRef(row, col));
+        const cell = sheet.getCellAt(row, col);
         rec.push(coerceValue(cell?.value));
       }
       records.push(rec);
@@ -54041,23 +54041,70 @@ ${e.toString()}`);
     get size() {
       return this.store.size;
     }
+    /**
+     * The populated extent of this map, memoized until a mutation invalidates it.
+     *
+     * It lives HERE rather than on `SheetModel` because it is a pure function of
+     * the cell set: a cache held next to the data cannot outlive it, so replacing
+     * a sheet's map can never serve the previous map's extent. Every mutator
+     * below drops it, including the packed pair — those bypass `set`/`delete`
+     * entirely and are what the row/column commands use.
+     *
+     * Walking PACKED keys is the other half. `keys()` unpacks each key into an A1
+     * string, which the caller then reparsed with a regex, so the old form packed,
+     * unpacked and reparsed the whole sheet on every call — and it is called once
+     * per oversized range during a recompute.
+     */
+    usedRange() {
+      if (!this.usedRangeCache) {
+        let minRow2 = Infinity;
+        let maxRow2 = 0;
+        let minCol2 = Infinity;
+        let maxCol2 = 0;
+        for (const packed of this.store.keys()) {
+          const { row, col } = unpackRowCol(packed);
+          if (row < minRow2) minRow2 = row;
+          if (row > maxRow2) maxRow2 = row;
+          if (col < minCol2) minCol2 = col;
+          if (col > maxCol2) maxCol2 = col;
+        }
+        this.usedRangeCache = maxRow2 === 0 ? { minRow: 1, maxRow: 1, minCol: 1, maxCol: 1 } : { minRow: minRow2, maxRow: maxRow2, minCol: minCol2, maxCol: maxCol2 };
+      }
+      const { minRow, maxRow, minCol, maxCol } = this.usedRangeCache;
+      return { minRow, maxRow, minCol, maxCol };
+    }
     get(ref2) {
       return this.store.get(packRef(ref2));
     }
+    /**
+     * Read by coordinate, skipping the A1 round trip.
+     *
+     * `get(ref)` costs a number→string→regex→number conversion per call, which
+     * is invisible until a caller reads a range cell by cell: on one real
+     * workbook `refToRowCol` alone was 39% of a full recompute. A caller already
+     * holding (row, col) — the range resolver, any grid walk — should use this.
+     */
+    getAt(row, col) {
+      return this.store.get(packRowCol(row, col));
+    }
     set(ref2, cell) {
       const key = packRef(ref2);
       if (key < 0) return this;
       this.store.set(key, cell);
+      this.usedRangeCache = void 0;
       return this;
     }
     has(ref2) {
       return this.store.has(packRef(ref2));
     }
     delete(ref2) {
-      return this.store.delete(packRef(ref2));
+      const deleted = this.store.delete(packRef(ref2));
+      if (deleted) this.usedRangeCache = void 0;
+      return deleted;
     }
     clear() {
       this.store.clear();
+      this.usedRangeCache = void 0;
     }
     *keys() {
       for (const k of this.store.keys()) yield unpackRef(k);
@@ -54085,10 +54132,13 @@ ${e.toString()}`);
     /** Direct packed-key set, for the same hot loops. */
     setPacked(packed, cell) {
       this.store.set(packed, cell);
+      this.usedRangeCache = void 0;
     }
     /** Direct packed-key delete. */
     deletePacked(packed) {
-      return this.store.delete(packed);
+      const deleted = this.store.delete(packed);
+      if (deleted) this.usedRangeCache = void 0;
+      return deleted;
     }
   };
   var StyleRegistry = class {
@@ -54271,6 +54321,10 @@ ${e.toString()}`);
     getCell(ref2) {
       return this.cells.get(ref2);
     }
+    /** Read by coordinate, skipping the A1 round trip — see `CellMap.getAt`. */
+    getCellAt(row, col) {
+      return this.cells.getAt(row, col);
+    }
     /**
      * Set cell value with optional inline style. Interns style via the
      * StyleRegistry when available. When `style` is supplied and matches the
@@ -54365,22 +54419,12 @@ ${e.toString()}`);
         this.set(ref2, label, style);
       });
     }
-    /** Compute the bounding box of all non-empty cells. */
+    /**
+     * The populated extent of the sheet. Derived from — and cached by — the cell
+     * map, so it cannot outlive the data it describes.
+     */
     getUsedRange() {
-      let minRow = Infinity;
-      let maxRow = 0;
-      let minCol = Infinity;
-      let maxCol = 0;
-      for (const ref2 of this.cells.keys()) {
-        const rc = refToRowCol(ref2);
-        if (!rc) continue;
-        if (rc.row < minRow) minRow = rc.row;
-        if (rc.row > maxRow) maxRow = rc.row;
-        if (rc.col < minCol) minCol = rc.col;
-        if (rc.col > maxCol) maxCol = rc.col;
-      }
-      if (maxRow === 0) return { minRow: 1, maxRow: 1, minCol: 1, maxCol: 1 };
-      return { minRow, maxRow, minCol, maxCol };
+      return this.cells.usedRange();
     }
   };
   var WorkbookModel = class {
@@ -54627,7 +54671,7 @@ ${e.toString()}`);
       let visible = true;
       for (const filterCol of activeFilters) {
         const col = startCol + filterCol.colIndex;
-        const cell = sheet.getCell(rowColToRef(r, col));
+        const cell = sheet.getCellAt(r, col);
         const cellText = cell?.displayValue ?? "";
         if (filterCol.filterValues && filterCol.filterValues.length > 0) {
           if (!filterCol.filterValues.includes(cellText)) {
@@ -61857,6 +61901,28 @@ ${e.toString()}`);
     const bang = key.indexOf("!");
     return { sheet: key.slice(0, bang), ref: key.slice(bang + 1) };
   }
+  var COARSE_COL_SUFFIX = ":*";
+  var COARSE_ROW_PREFIX = "*:";
+  function columnKey(sheet, column) {
+    return `${sheet}!${column}${COARSE_COL_SUFFIX}`;
+  }
+  function rowKey(sheet, row) {
+    return `${sheet}!${COARSE_ROW_PREFIX}${row}`;
+  }
+  function isCoarseKey(key) {
+    return key.endsWith(COARSE_COL_SUFFIX) || key.includes(`!${COARSE_ROW_PREFIX}`);
+  }
+  var A1 = /^([A-Z]+)(\d+)$/;
+  function coarseKeysFor(cellKeyStr) {
+    const bang = cellKeyStr.indexOf("!");
+    if (bang < 0) return [];
+    const sheet = cellKeyStr.slice(0, bang);
+    const ref2 = cellKeyStr.slice(bang + 1);
+    const m = A1.exec(ref2);
+    if (!m) return [];
+    return [columnKey(sheet, m[1]), rowKey(sheet, Number(m[2]))];
+  }
+  var EMPTY = /* @__PURE__ */ new Set();
   var DependencyGraph = class {
     constructor() {
       // Forward edges: cell → cells it references (precedents)
@@ -61891,19 +61957,35 @@ ${e.toString()}`);
     }
     /** Get all cells that directly depend on the given cell. */
     getDirectDependents(cell) {
-      return Array.from(this.dependents.get(cell) ?? []);
+      return Array.from(this.dependentsOf(cell));
+    }
+    /**
+     * Everything that references this cell — directly, or through the column or
+     * row node that contains it. The single place `dependents` is read, so a
+     * whole-column reference cannot be forgotten by one traversal and honoured by
+     * another.
+     */
+    dependentsOf(cell) {
+      const direct = this.dependents.get(cell);
+      if (isCoarseKey(cell)) return direct ?? EMPTY;
+      const coarse = coarseKeysFor(cell);
+      let widened;
+      for (const key of coarse) {
+        const via = this.dependents.get(key);
+        if (!via || via.size === 0) continue;
+        widened ?? (widened = new Set(direct));
+        for (const d of via) widened.add(d);
+      }
+      return widened ?? direct ?? EMPTY;
     }
     /** Get all cells that need recalculation when the given cells change, in topological order. */
     getRecalcOrder(changed) {
-      const changedSet = new Set(changed);
       const affected = /* @__PURE__ */ new Set();
       const queue = [...changed];
       let head = 0;
       while (head < queue.length) {
         const cell = queue[head++];
-        const deps = this.dependents.get(cell);
-        if (!deps) continue;
-        for (const dep of deps) {
+        for (const dep of this.dependentsOf(cell)) {
           if (!affected.has(dep)) {
             affected.add(dep);
             queue.push(dep);
@@ -61912,15 +61994,11 @@ ${e.toString()}`);
       }
       if (affected.size === 0) return [];
       const inDegree = /* @__PURE__ */ new Map();
+      for (const cell of affected) inDegree.set(cell, 0);
       for (const cell of affected) {
-        let count = 0;
-        const prec = this.precedents.get(cell);
-        if (prec) {
-          for (const p of prec) {
-            if (affected.has(p)) count++;
-          }
+        for (const dep of this.dependentsOf(cell)) {
+          if (affected.has(dep)) inDegree.set(dep, (inDegree.get(dep) ?? 0) + 1);
         }
-        inDegree.set(cell, count);
       }
       const result = [];
       const ready = [];
@@ -61931,9 +62009,7 @@ ${e.toString()}`);
       while (readyHead < ready.length) {
         const cell = ready[readyHead++];
         result.push(cell);
-        const deps = this.dependents.get(cell);
-        if (!deps) continue;
-        for (const dep of deps) {
+        for (const dep of this.dependentsOf(cell)) {
           if (!affected.has(dep)) continue;
           const newDeg = (inDegree.get(dep) ?? 1) - 1;
           inDegree.set(dep, newDeg);
@@ -61954,12 +62030,13 @@ ${e.toString()}`);
       const stack = new Array();
       const prec = this.precedents.get(cell);
       if (!prec) return null;
+      const originCoarse = new Set(coarseKeysFor(cell));
       for (const p of prec) {
         stack.push({ cell: p, path: [cell, p] });
       }
       while (stack.length > 0) {
         const { cell: current, path } = stack.pop();
-        if (current === cell) return path;
+        if (current === cell || originCoarse.has(current)) return path;
         if (visited.has(current)) continue;
         visited.add(current);
         const nextPrec = this.precedents.get(current);
@@ -62072,6 +62149,20 @@ ${e.toString()}`);
     };
   }
 
+  // ../xlsx/src/blank_comparison.ts
+  var import_operators = __toESM(require_operators(), 1);
+  var patched = false;
+  function applyExcelBlankSemantics() {
+    if (patched) return;
+    patched = true;
+    const original = import_operators.Infix.compareOp;
+    import_operators.Infix.compareOp = (value1, infix, value2, isArray1, isArray2) => {
+      if (value1 == null && typeof value2 === "string") value1 = "";
+      if (value2 == null && typeof value1 === "string") value2 = "";
+      return original(value1, infix, value2, isArray1, isArray2);
+    };
+  }
+
   // ../xlsx/src/formula_engine.ts
   var unwrapArg = (a) => a !== null && typeof a === "object" && "value" in a ? a.value : a;
   function adaptFormulajs(fn) {
@@ -62114,9 +62205,24 @@ ${e.toString()}`);
     bridgeCtxCache = withCtx;
     return withCtx;
   }
+  var MAX_EXPANDED_CELLS = 1e4;
   var _FormulaEngine = class _FormulaEngine {
     constructor(workbook) {
       this.graph = new DependencyGraph();
+      /**
+       * Formula cells (by key) whose text the parser could not read AT ALL, found
+       * while building the graph from a loaded file.
+       *
+       * They are held apart from every other failure because the honest response
+       * differs: a formula that evaluates TO an error has been understood, so
+       * writing `#DIV/0!` reports a real answer, while one we cannot parse has not
+       * been — and overwriting the value its author computed would replace a
+       * correct number with a guess. These keep their cached value and are named in
+       * the report instead. The engine's own rule, one level down: degrade what you
+       * cannot draw, refuse what you cannot read.
+       */
+      this.unreadableFormulas = /* @__PURE__ */ new Set();
+      applyExcelBlankSemantics();
       this.workbook = workbook;
       this.parser = new import_fast_formula_parser.default({
         onCell: (ref2) => this.resolveCell(ref2),
@@ -62137,11 +62243,13 @@ ${e.toString()}`);
     /** Build dependency graph from all formula cells in the workbook. */
     buildGraph() {
       this.graph.clear();
+      this.unreadableFormulas.clear();
       for (const sheet of this.workbook.sheets) {
         for (const [ref2, cell] of sheet.cells) {
           if (!cell.formula) continue;
           const key = cellKey({ sheet: sheet.name, ref: ref2 });
-          const deps = this.extractDependencies(cell.formula, sheet.name);
+          const { deps, readable } = this.analyzeFormula(cell.formula, sheet.name);
+          if (!readable) this.unreadableFormulas.add(key);
           this.graph.setDependencies(key, deps);
         }
       }
@@ -62197,8 +62305,13 @@ ${e.toString()}`);
     onCellChanged(sheetName, ref2, formula) {
       const key = cellKey({ sheet: sheetName, ref: ref2 });
       if (formula) {
-        const deps = this.extractDependencies(formula, sheetName);
+        const { deps, readable } = this.analyzeFormula(formula, sheetName);
         this.graph.setDependencies(key, deps);
+        this.unreadableFormulas.delete(key);
+        if (!readable) {
+          this.setCellError(key, "#ERROR!");
+          return;
+        }
         const cycle = this.graph.detectCycle(key);
         if (cycle) {
           this.setCellError(key, "#CIRC!");
@@ -62207,6 +62320,7 @@ ${e.toString()}`);
         this.evaluateCell(key);
       } else {
         this.graph.removeCell(key);
+        this.unreadableFormulas.delete(key);
       }
       const order = this.graph.getRecalcOrder([key]);
       for (const depKey of order) {
@@ -62223,6 +62337,7 @@ ${e.toString()}`);
     // ===========================================================================
     /** Evaluate a single formula cell and update its value. */
     evaluateCell(key) {
+      if (this.unreadableFormulas.has(key)) return;
       const { sheet: sheetName, ref: ref2 } = parseCellKey(key);
       const sheetIndex = this.workbook.sheets.findIndex((s) => s.name === sheetName);
       if (sheetIndex < 0) return;
@@ -62271,26 +62386,60 @@ ${e.toString()}`);
     // ===========================================================================
     /** Extract cell/range references from a formula string. Returns empty array for unparseable formulas. */
     extractDependencies(formula, currentSheet) {
-      const sheet = this.workbook.sheets.find((s) => s.name === currentSheet);
-      const expanded = sheet ? expandStructuredRefs(formula, sheet.tables, 1) : formula;
-      const deps = this.depParser.parse(expanded, { sheet: currentSheet, row: 1, col: 1 });
+      return this.analyzeFormula(formula, currentSheet).deps;
+    }
+    /**
+     * Dependencies plus whether the parser could read the formula at all.
+     *
+     * `fast-formula-parser` reports a formula it cannot LEX by throwing, the same
+     * channel it uses for `#VALUE!`, so the lexer failure of a single cell used to
+     * escape `buildGraph` and abort the recompute for the entire workbook —
+     * observed on a real workbook whose `VLOOKUP` pointed at another file
+     * (`'[1]DATA'!B:C`, an external-workbook reference the lexer has no rule for).
+     * Anything the grammar does not cover lands here the same way, so this catches
+     * the class rather than that one syntax.
+     */
+    analyzeFormula(formula, currentSheet) {
+      let deps;
+      try {
+        const sheet = this.workbook.sheets.find((s) => s.name === currentSheet);
+        const expanded = sheet ? expandStructuredRefs(formula, sheet.tables, 1) : formula;
+        deps = this.depParser.parse(expanded, { sheet: currentSheet, row: 1, col: 1 });
+      } catch {
+        return { deps: [], readable: false };
+      }
       const refs = [];
       for (const dep of deps) {
         const depSheet = dep.sheet ?? currentSheet;
         if (dep.from && dep.to) {
-          const maxCells = 1e4;
-          let count = 0;
-          for (let r = dep.from.row; r <= dep.to.row && count < maxCells; r++) {
-            for (let c = dep.from.col; c <= dep.to.col && count < maxCells; c++) {
+          const rows = dep.to.row - dep.from.row + 1;
+          const cols = dep.to.col - dep.from.col + 1;
+          if (rows * cols > MAX_EXPANDED_CELLS) {
+            if (cols <= rows) {
+              for (let c = dep.from.col; c <= dep.to.col; c++) {
+                refs.push(columnKey(depSheet, colNumToLetters(c)));
+              }
+            } else {
+              for (let r = dep.from.row; r <= dep.to.row; r++) {
+                refs.push(rowKey(depSheet, r));
+              }
+            }
+            continue;
+          }
+          for (let r = dep.from.row; r <= dep.to.row; r++) {
+            for (let c = dep.from.col; c <= dep.to.col; c++) {
               refs.push(cellKey({ sheet: depSheet, ref: rowColToRef(r, c) }));
-              count++;
             }
           }
         } else if (dep.row != null && dep.col != null) {
           refs.push(cellKey({ sheet: depSheet, ref: rowColToRef(dep.row, dep.col) }));
         }
       }
-      return refs;
+      return { deps: refs, readable: true };
+    }
+    /** Formula cells the parser could not read, by key. Read by the recompute report. */
+    unreadable() {
+      return this.unreadableFormulas;
     }
     // ===========================================================================
     // Cell value resolution callbacks
@@ -62320,8 +62469,7 @@ ${e.toString()}`);
       for (let r = ref2.from.row; r <= lastRow; r++) {
         const row = [];
         for (let c = ref2.from.col; c <= lastCol; c++) {
-          const cell = sheet.getCell(rowColToRef(r, c));
-          row.push(cell?.value ?? null);
+          row.push(sheet.getCellAt(r, c)?.value ?? null);
         }
         result.push(row);
       }
@@ -62411,15 +62559,19 @@ ${e.toString()}`);
     const engine = new FormulaEngine(workbook);
     engine.buildGraph();
     engine.evaluateAll();
-    return collectRecomputeReport(workbook);
+    return collectRecomputeReport(workbook, engine.unreadable());
   }
-  function collectRecomputeReport(workbook) {
+  function collectRecomputeReport(workbook, unreadable) {
     let total = 0;
     const unevaluated = [];
     for (const sheet of workbook.sheets) {
       for (const [ref2, cell] of sheet.cells) {
         if (!cell.formula) continue;
         total++;
+        if (unreadable.has(cellKey({ sheet: sheet.name, ref: ref2 }))) {
+          unevaluated.push({ sheet: sheet.name, ref: ref2, formula: cell.formula, error: "#UNREADABLE!" });
+          continue;
+        }
         if (cell.value === null) {
           unevaluated.push({ sheet: sheet.name, ref: ref2, formula: cell.formula, error: cell.error ?? "#ERROR!" });
         }