solve-engine 1.0.1 → 1.1.0

package/dist/chunk-GUG7SNSV.js

@@ -0,0 +1,1764 @@
+import { isEmptyLine, engine_worker_default } from './chunk-JIPATHVY.js';
+import { djb2Hash } from './chunk-5ON7PUAZ.js';
+import { countLines } from './chunk-3BOK2LDK.js';
+import { sharedGlobalVariableStore, globalDagKey } from './chunk-NKW7LKYU.js';
+import { enableValueArena, disableValueArena, errorValue } from './chunk-267JPOTF.js';
+import { DEFAULT_CONFIG } from './chunk-G7Z4HJQA.js';
+import { sharedLexer } from './chunk-OADDUPT3.js';
+import { ErrorFactory, EngineError } from './chunk-ERCOHGXD.js';
+
+// src/engine/SegmentTree.ts
+var SegmentTree = class {
+  constructor() {
+    this.root = null;
+  }
+  // ── Public API ───────────────────────────────────────────────────────
+  /** Total number of elements in the tree. */
+  get length() {
+    return this.root ? this.root.size : 0;
+  }
+  /** Whether the tree is empty. */
+  get isEmpty() {
+    return this.root === null;
+  }
+  /**
+   * Get the lineId at the given 0-based index.
+   * Returns undefined if index is out of bounds.
+   * O(log N) expected.
+   */
+  getAt(index) {
+    if (index < 0 || index >= (this.root?.size ?? 0)) return void 0;
+    return this.nodeAt(this.root, index).lineId;
+  }
+  /**
+   * Insert a single lineId at the given 0-based index.
+   * O(log N) expected.
+   */
+  insertAt(index, lineId) {
+    const [left, right] = split(this.root, index);
+    this.root = merge(merge(left, createNode(lineId)), right);
+  }
+  /**
+   * Delete a single element at the given 0-based index.
+   * Returns the removed lineId, or undefined if out of bounds.
+   * O(log N) expected.
+   */
+  deleteAt(index) {
+    if (index < 0 || index >= (this.root?.size ?? 0)) return void 0;
+    const [left, midRight] = split(this.root, index);
+    const [mid, right] = split(midRight, 1);
+    const removed = mid ? mid.lineId : void 0;
+    this.root = merge(left, right);
+    return removed;
+  }
+  /**
+   * Bulk splice: delete `deleteCount` elements at `startIndex` (0-based),
+   * then insert `newIds` in their place.
+   *
+   * Returns the removed lineId array.
+   * O(log N + deleteCount + insertCount) expected.
+   */
+  spliceAt(startIndex, deleteCount, newIds) {
+    const clampedStart = Math.max(0, startIndex);
+    const clampedCount = Math.min(
+      Math.max(0, deleteCount),
+      (this.root?.size ?? 0) - clampedStart
+    );
+    const [left, midRight] = split(this.root, clampedStart);
+    const [mid, right] = split(midRight, clampedCount);
+    const removed = collectInOrder(mid);
+    const newTree = buildTreap(newIds, 0, newIds.length);
+    this.root = merge(merge(left, newTree), right);
+    return removed;
+  }
+  /**
+   * Replace the entire tree with a new set of lineIds.
+   * O(N), builds a balanced treap from a flat array.
+   */
+  replaceAll(lineIds) {
+    this.root = buildTreap(lineIds, 0, lineIds.length);
+  }
+  /**
+   * Get a contiguous range of lineIds by index.
+   * O(rangeSize + log N), single in-order walk instead of N × O(log N).
+   *
+   * This is the hot path for viewport rendering in DocumentModel.getVisibleLines().
+   */
+  getRange(startIndex, endIndex) {
+    const clampedStart = Math.max(0, startIndex);
+    const clampedEnd = Math.min((this.root?.size ?? 0) - 1, endIndex);
+    if (clampedStart > clampedEnd) return [];
+    const result = [];
+    this.collectRange(this.root, clampedStart, clampedEnd, 0, result);
+    return result;
+  }
+  /**
+   * Clear the tree.
+   */
+  clear() {
+    this.root = null;
+  }
+  // ── Iteration ─────────────────────────────────────────────────────────
+  /**
+   * In-order iterator yielding all lineIds.
+   */
+  *[Symbol.iterator]() {
+    yield* this.inOrder(this.root);
+  }
+  *inOrder(node) {
+    if (!node) return;
+    yield* this.inOrder(node.left);
+    yield node.lineId;
+    yield* this.inOrder(node.right);
+  }
+  // ── Private helpers ───────────────────────────────────────────────────
+  nodeAt(node, index) {
+    const leftSize = node.left ? node.left.size : 0;
+    if (index < leftSize) {
+      return this.nodeAt(node.left, index);
+    } else if (index === leftSize) {
+      return node;
+    } else {
+      return this.nodeAt(node.right, index - leftSize - 1);
+    }
+  }
+  /**
+   * Collect all node values in the range [targetStart, targetEnd] into result.
+   * `offset` is the 0-based start of the current subtree within the full tree.
+   * O(rangeSize + log N), skips entire subtrees outside the target range.
+   */
+  collectRange(node, targetStart, targetEnd, offset, result) {
+    if (!node) return;
+    const leftSize = node.left ? node.left.size : 0;
+    const nodeIndex = offset + leftSize;
+    if (nodeIndex > targetStart && node.left) {
+      this.collectRange(node.left, targetStart, targetEnd, offset, result);
+    }
+    if (nodeIndex >= targetStart && nodeIndex <= targetEnd) {
+      result.push(node.lineId);
+    }
+    if (nodeIndex < targetEnd && node.right) {
+      this.collectRange(node.right, targetStart, targetEnd, nodeIndex + 1, result);
+    }
+  }
+};
+function createNode(lineId) {
+  return {
+    lineId,
+    size: 1,
+    priority: Math.random(),
+    left: null,
+    right: null
+  };
+}
+function updateSize(node) {
+  node.size = 1 + (node.left ? node.left.size : 0) + (node.right ? node.right.size : 0);
+}
+function merge(left, right) {
+  if (!left) return right;
+  if (!right) return left;
+  if (left.priority > right.priority) {
+    left.right = merge(left.right, right);
+    updateSize(left);
+    return left;
+  } else {
+    right.left = merge(left, right.left);
+    updateSize(right);
+    return right;
+  }
+}
+function split(node, index) {
+  if (!node) return [null, null];
+  const leftSize = node.left ? node.left.size : 0;
+  if (index <= leftSize) {
+    const [left, right] = split(node.left, index);
+    node.left = right;
+    updateSize(node);
+    return [left, node];
+  } else {
+    const [left, right] = split(node.right, index - leftSize - 1);
+    node.right = left;
+    updateSize(node);
+    return [node, right];
+  }
+}
+function collectInOrder(node) {
+  const result = [];
+  collect(node, result);
+  return result;
+}
+function collect(node, result) {
+  if (!node) return;
+  collect(node.left, result);
+  result.push(node.lineId);
+  collect(node.right, result);
+}
+function buildTreap(lineIds, start, end) {
+  if (start >= end) return null;
+  const mid = Math.floor((start + end) / 2);
+  const priority = pseudoRandom(mid);
+  const node = {
+    lineId: lineIds[mid],
+    size: end - start,
+    priority,
+    left: buildTreap(lineIds, start, mid),
+    right: buildTreap(lineIds, mid + 1, end)
+  };
+  return node;
+}
+function pseudoRandom(seed) {
+  let x = seed;
+  x = (x >> 16 ^ x) * 73244475;
+  x = (x >> 16 ^ x) * 73244475;
+  x = x >> 16 ^ x;
+  return x / 4294967295;
+}
+
+// src/engine/DocumentModel.ts
+var DocumentModel = class {
+  /**
+   * @param maxLines - Ceiling on the line count, defaulting to the engine's
+   * configured one. Every line costs a LineState with six arrays in it
+   * whatever the line says, so the cost of a document is its line count and
+   * nothing else bounds it: two hundred thousand lines of `1 + 1` exhausted
+   * the heap here, before a single expression had been looked at.
+   */
+  constructor(maxLines = DEFAULT_CONFIG.performance.maxDocumentLines) {
+    /** Persistent line ID → LineState. */
+    this.lines = /* @__PURE__ */ new Map();
+    /** Order-statistic treap representing the current document line order. */
+    this.orderTree = new SegmentTree();
+    /** Monotonically increasing counter for new line IDs. */
+    this.nextLineId = 1;
+    /**
+     * Lazy position cache: lineId → 1-based position.
+     * Built on first `getLinePosition()` call, invalidated on structural edits.
+     */
+    this._positionCache = null;
+    /**
+     * Line IDs currently marked dirty, maintained alongside every
+     * `state.dirty` mutation (in this class and in every other module that
+     * holds a direct `LineState` reference: ThreeTierEvaluator, PageManager).
+     * Lets {@link hasAnyDirtyLineBefore} answer "is anything before position
+     * X dirty" in O(d log N), d = current dirty count, typically tiny once
+     * a document has settled after its initial evaluation, instead of
+     * O(N log N), which used to mean every scroll event re-walked the WHOLE
+     * document via `getLineAt()` regardless of how little of it was actually
+     * dirty. Benchmarked: ~10.6ms per setViewport() call scrolled near the
+     * bottom of a 20k-line document before this fix.
+     */
+    this.dirtyLineIds = /* @__PURE__ */ new Set();
+    this.maxLines = maxLines;
+  }
+  // ── Initialization ──────────────────────────────────────────────────
+  /**
+   * Initialize or replace the entire document from a text blob.
+   * Clears all existing state and assigns new persistent line IDs.
+   *
+   * @throws `DOCUMENT_TOO_LARGE` for a document past {@link maxLines}, before
+   * any of it is stored. Recoverable: nothing has been replaced yet, so the
+   * model still holds whatever it held.
+   */
+  setDocument(text) {
+    const lineCount = countLines(text, this.maxLines);
+    if (lineCount > this.maxLines) {
+      throw ErrorFactory.execution(
+        "DOCUMENT_TOO_LARGE",
+        `This document has more than ${this.maxLines.toLocaleString("en-US")} lines, which is the most the engine will hold at once`,
+        { maxLines: this.maxLines }
+      );
+    }
+    this.lines.clear();
+    this.orderTree.clear();
+    this._positionCache = null;
+    this.dirtyLineIds.clear();
+    this.nextLineId = 1;
+    const rawLines = text.split("\n");
+    const lineIds = new Array(rawLines.length);
+    for (let i = 0; i < rawLines.length; i++) {
+      const lineId = this.nextLineId++;
+      lineIds[i] = lineId;
+      this.lines.set(lineId, {
+        lineId,
+        textHash: djb2Hash(rawLines[i]),
+        text: rawLines[i],
+        expressions: [],
+        bytecodes: [],
+        reads: [],
+        writes: [],
+        results: [],
+        result: null,
+        dirty: true,
+        isVariableDef: false,
+        isEmpty: rawLines[i].trim().length === 0,
+        inlineSolveCount: 0
+      });
+    }
+    this.orderTree.replaceAll(lineIds);
+    for (const id of lineIds) this.dirtyLineIds.add(id);
+  }
+  // ── Structural edits ────────────────────────────────────────────────
+  /**
+   * Apply one or more line-level changes to the document.
+   *
+   * **Precondition:** Changes must be **non-overlapping** in their line ranges.
+   * If two changes target the same or adjacent lines, the reverse-order
+   * processing may produce incorrect results because the first-applied
+   * change shifts the line numbers that the second change references.
+   *
+   * Changes are applied in **reverse order** (highest startLine first) so
+   * that earlier changes in the document don't shift the indices of later
+   * changes during processing.
+   *
+   * Returns both the newly inserted line IDs and the removed line IDs.
+   * Callers should use `removed` to clean up the dependency graph and
+   * other data structures keyed by lineId.
+   */
+  applyChanges(changes) {
+    const inserted = [];
+    const removed = [];
+    const sorted = [...changes].sort((a, b) => b.startLine - a.startLine);
+    for (const change of sorted) {
+      const startIdx = change.startLine - 1;
+      const newIds = [];
+      for (const text of change.insertLines) {
+        const lineId = this.nextLineId++;
+        newIds.push(lineId);
+        inserted.push(lineId);
+        this.lines.set(lineId, {
+          lineId,
+          textHash: djb2Hash(text),
+          text,
+          expressions: [],
+          bytecodes: [],
+          reads: [],
+          writes: [],
+          results: [],
+          result: null,
+          dirty: true,
+          isVariableDef: false,
+          isEmpty: text.trim().length === 0,
+          inlineSolveCount: 0
+        });
+      }
+      for (const id of newIds) this.dirtyLineIds.add(id);
+      const removedIds = this.orderTree.spliceAt(
+        startIdx,
+        change.deleteCount,
+        newIds
+      );
+      for (const id of removedIds) {
+        removed.push(id);
+        this.lines.delete(id);
+        this.dirtyLineIds.delete(id);
+      }
+    }
+    this._positionCache = null;
+    return { inserted, removed };
+  }
+  /**
+   * Insert new lines at the given 1-based position.
+   * Convenience wrapper around applyChanges.
+   */
+  insertLines(atLine, texts) {
+    const change = {
+      startLine: atLine,
+      deleteCount: 0,
+      insertLines: texts
+    };
+    const result = this.applyChanges([change]);
+    return result.inserted;
+  }
+  /**
+   * Delete lines in the given 1-based range [startLine, endLine] inclusive.
+   * Convenience wrapper around applyChanges.
+   */
+  deleteLines(startLine, endLine) {
+    const change = {
+      startLine,
+      deleteCount: endLine - startLine + 1,
+      insertLines: []
+    };
+    const result = this.applyChanges([change]);
+    return result.removed;
+  }
+  /**
+   * Update the text of a single line in place.
+   * If the text hash differs, marks the line dirty and clears its
+   * bytecode/result so it gets re-evaluated.
+   *
+   * Returns true if the text actually changed (hash mismatch).
+   */
+  editLine(lineNumber, newText) {
+    const state = this.getLineAt(lineNumber);
+    if (!state) return false;
+    const newHash = djb2Hash(newText);
+    if (newHash === state.textHash) return false;
+    state.text = newText;
+    state.textHash = newHash;
+    state.expressions = [];
+    state.bytecodes = [];
+    state.results = [];
+    state.result = null;
+    state.inlineSolveCount = 0;
+    state.dirty = true;
+    this.dirtyLineIds.add(state.lineId);
+    state.isEmpty = newText.trim().length === 0;
+    return true;
+  }
+  // ── Queries ─────────────────────────────────────────────────────────
+  /**
+   * Get the LineState at the given 1-based line position. O(1).
+   */
+  getLineAt(position) {
+    const idx = position - 1;
+    const lineId = this.orderTree.getAt(idx);
+    if (lineId === void 0) return void 0;
+    return this.lines.get(lineId);
+  }
+  /**
+   * Get the 1-based position of a line by its persistent ID.
+   * Returns -1 if the line ID is not in the document.
+   *
+   * Uses a lazy position cache: O(N) on first call after structural edit,
+   * O(1) on subsequent calls. The cache is invalidated by any structural edit.
+   */
+  getLinePosition(lineId) {
+    if (this._positionCache) {
+      return this._positionCache.get(lineId) ?? -1;
+    }
+    this._positionCache = /* @__PURE__ */ new Map();
+    let pos = 1;
+    for (const id of this.orderTree) {
+      this._positionCache.set(id, pos++);
+    }
+    return this._positionCache.get(lineId) ?? -1;
+  }
+  /**
+   * Get all LineState entries within the given viewport range (1-based, inclusive).
+   * Uses SegmentTree.getRange() for O(viewport + log N) collection instead of
+   * O(viewport × log N) per-line lookups.
+   */
+  getVisibleLines(startLine, endLine) {
+    const lineIds = this.orderTree.getRange(startLine - 1, endLine - 1);
+    const result = [];
+    for (const lineId of lineIds) {
+      const state = this.lines.get(lineId);
+      if (state) result.push(state);
+    }
+    return result;
+  }
+  /**
+   * Get all LineState entries in order. Useful for batch processing.
+   */
+  getAllLines() {
+    return this.getVisibleLines(1, this.lineCount);
+  }
+  /**
+   * Get a LineState by its persistent line ID. O(1).
+   */
+  getLineById(lineId) {
+    return this.lines.get(lineId);
+  }
+  /**
+   * Get all lines that are marked dirty.
+   */
+  getDirtyLines() {
+    const result = [];
+    for (const state of this.lines.values()) {
+      if (state.dirty) result.push(state);
+    }
+    return result;
+  }
+  /**
+   * Whether any line before `position` (1-based, exclusive) is dirty.
+   *
+   * Used by ThreeTierEvaluator.setViewport() to decide whether cached
+   * checkpoint state might be stale and a full evaluate() (from line 1) is
+   * needed instead of the cheap viewport-only path.
+   *
+   * O(d log N) where d = current dirty line count via {@link dirtyLineIds},
+   * not O(N log N), a document that's mostly clean (the steady state after
+   * initial load) answers this in the cost of resolving a handful of
+   * lineIds to positions, not walking every line up to `position`.
+   */
+  hasAnyDirtyLineBefore(position) {
+    for (const lineId of this.dirtyLineIds) {
+      const pos = this.getLinePosition(lineId);
+      if (pos >= 1 && pos < position) return true;
+    }
+    return false;
+  }
+  /**
+   * Whether any **variable-definition** line before `position` (1-based,
+   * exclusive) is dirty.
+   *
+   * Narrower than {@link hasAnyDirtyLineBefore}: `VMCheckpointer.snapshot()`
+   * only ever records state for lines with `writes.length > 0` (see
+   * VMCheckpoints.ts), so a dirty plain-expression line before the viewport
+   * cannot have invalidated any checkpoint, there's no checkpoint entry
+   * for it to invalidate. Only a dirty variable-def line can mean the VM
+   * state a checkpoint would restore is stale.
+   *
+   * This distinction matters because `PageManager.evictPageBytecode()`
+   * marks evicted non-variable-def lines dirty (so they get Tier 1 if
+   * scrolled back into view), and Tier 3's compile-only path never clears
+   * `dirty` for non-variable-def lines by design. Using the broader
+   * `hasAnyDirtyLineBefore` here meant scrolling far into a large,
+   * variable-def-free document would trip `setViewport()`'s fallback to
+   * `evaluate()` on every single call, evaluate() reprocesses the evicted
+   * lines via Tier 3, which recompiles their bytecode without clearing
+   * dirty, so the very next `maintainAfterEval()` re-evicts and re-dirties
+   * the same lines, forever re-triggering the fallback on an otherwise
+   * unchanged viewport.
+   */
+  hasAnyDirtyVariableDefLineBefore(position) {
+    for (const lineId of this.dirtyLineIds) {
+      const state = this.lines.get(lineId);
+      if (!state || !state.isVariableDef) continue;
+      const pos = this.getLinePosition(lineId);
+      if (pos >= 1 && pos < position) return true;
+    }
+    return false;
+  }
+  /** Number of lines currently marked dirty. For diagnostics/tests. */
+  get dirtyCount() {
+    return this.dirtyLineIds.size;
+  }
+  // ── Thread-safety validation ────────────────────────────────────────
+  /**
+   * Verify that bytecode compiled by a worker is still valid for this line.
+   *
+   * When Phase 5.2h sends compilation to a worker, the worker posts back
+   * `{lineId, bytecode, reads, writes, compiledAgainstHash}`. Between dispatch
+   * and response, the user may have edited the line. This method lets the
+   * main thread check whether the bytecode is still applicable.
+   *
+   * @returns true if the line still exists and its text hash matches.
+   */
+  isBytecodeValid(lineId, compiledAgainstHash) {
+    const state = this.lines.get(lineId);
+    return state !== void 0 && state.textHash === compiledAgainstHash;
+  }
+  // ── State mutations ─────────────────────────────────────────────────
+  /**
+   * Mark a line as clean (re-evaluated successfully).
+   */
+  markClean(lineId) {
+    const state = this.lines.get(lineId);
+    if (state) {
+      state.dirty = false;
+      this.dirtyLineIds.delete(lineId);
+    }
+  }
+  /**
+   * Mark a line as dirty (needs re-evaluation) by its 1-based position.
+   * Convenience for callers that have line numbers instead of line IDs.
+   */
+  markDirtyByLineNumber(lineNumber) {
+    const state = this.getLineAt(lineNumber);
+    if (state) {
+      state.dirty = true;
+      this.dirtyLineIds.add(state.lineId);
+    }
+  }
+  /**
+   * Mark a line as dirty (needs re-evaluation).
+   */
+  markDirty(lineId) {
+    const state = this.lines.get(lineId);
+    if (state) {
+      state.dirty = true;
+      this.dirtyLineIds.add(lineId);
+    }
+  }
+  /**
+   * Mark all lines as dirty (e.g., after plugin register/unregister).
+   */
+  invalidateAll() {
+    for (const state of this.lines.values()) {
+      state.dirty = true;
+    }
+    this.dirtyLineIds = new Set(this.lines.keys());
+  }
+  /**
+   * Update a line's evaluation state after successful execution (Tier 1 / Tier 2).
+   *
+   * Sets results, bytecodes, reads, writes, and marks the line clean.
+   * Supports multi-expression lines (inline solves) via parallel arrays.
+   *
+   * @param lineId - Persistent line identifier.
+   * @param results - Evaluation result groups for each expression (in order). Each element is a Value[].
+   * @param bytecodes - Compiled bytecode for each expression (in order).
+   * @param expressions - Extracted expression strings (in order).
+   * @param reads - Aggregated read variables across all expressions.
+   * @param writes - Aggregated write variables across all expressions.
+   * @param isVariableDef - True if any expression defines a variable.
+   * @param inlineSolveCount - Number of inline solves (0 for full-line).
+   */
+  updateLineResult(lineId, results, bytecodes, expressions, reads, writes, isVariableDef, inlineSolveCount = 0) {
+    const state = this.lines.get(lineId);
+    if (!state) return;
+    state.results = results;
+    state.result = results[0]?.[0] ?? null;
+    state.bytecodes = bytecodes;
+    state.expressions = expressions;
+    state.reads = reads;
+    state.writes = writes;
+    state.isVariableDef = isVariableDef;
+    state.inlineSolveCount = inlineSolveCount;
+    state.dirty = false;
+    this.dirtyLineIds.delete(lineId);
+  }
+  /**
+   * Update a line's compile-only state (Tier 3: background compilation).
+   *
+   * Stores expressions, bytecodes, reads, and writes. Does NOT set results
+   * and does NOT mark the line clean, it still needs execution (Tier 1 or
+   * Tier 2) to produce results. This distinction allows the three-tier
+   * evaluation strategy: compile invisible lines in the background without
+   * executing them, then execute from cached bytecode when scrolled into view.
+   *
+   * @param lineId - Persistent line identifier.
+   * @param expressions - Extracted expression strings (in order).
+   * @param bytecodes - Compiled bytecode for each expression (in order).
+   * @param reads - Aggregated read variables across all expressions.
+   * @param writes - Aggregated write variables across all expressions.
+   * @param isVariableDef - True if any expression defines a variable.
+   * @param inlineSolveCount - Number of inline solves (0 for full-line).
+   */
+  updateLineCompiled(lineId, expressions, bytecodes, reads, writes, isVariableDef, inlineSolveCount = 0) {
+    const state = this.lines.get(lineId);
+    if (!state) return;
+    state.expressions = expressions;
+    state.bytecodes = bytecodes;
+    state.reads = reads;
+    state.writes = writes;
+    state.isVariableDef = isVariableDef;
+    state.inlineSolveCount = inlineSolveCount;
+  }
+  // ── Properties ──────────────────────────────────────────────────────
+  get lineCount() {
+    return this.orderTree.length;
+  }
+  get isEmpty() {
+    return this.orderTree.isEmpty;
+  }
+  /**
+   * Iterator over LineState in document order.
+   */
+  *[Symbol.iterator]() {
+    for (const lineId of this.orderTree) {
+      const state = this.lines.get(lineId);
+      if (state) yield state;
+    }
+  }
+  // ── Lifecycle ───────────────────────────────────────────────────────
+  clear() {
+    this.lines.clear();
+    this.orderTree.clear();
+    this._positionCache = null;
+    this.nextLineId = 1;
+  }
+  /**
+   * Serialize the document model to a plain object for debugging.
+   */
+  toJSON() {
+    return {
+      lineCount: this.lineCount,
+      lines: this.getAllLines().map((s) => ({
+        lineId: s.lineId,
+        text: s.text.substring(0, 80),
+        // truncate for readability
+        textHash: s.textHash,
+        dirty: s.dirty,
+        isVariableDef: s.isVariableDef,
+        isEmpty: s.isEmpty,
+        hasBytecode: s.bytecodes.length > 0,
+        hasResult: s.results.length > 0,
+        inlineSolveCount: s.inlineSolveCount,
+        reads: s.reads,
+        writes: s.writes
+      }))
+    };
+  }
+};
+
+// src/engine/CompilationWorkerManager.ts
+var CompilationWorkerManager = class {
+  constructor() {
+    this.worker = null;
+    this.nextId = 1;
+    this.pending = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Ensure the worker is started (lazy initialization).
+   * Uses esbuild-plugin-inline-worker to inline the worker as a blob URL.
+   */
+  ensureWorker() {
+    if (this.worker) return this.worker;
+    this.worker = engine_worker_default();
+    this.worker.onmessage = (event) => {
+      const data = event.data;
+      if (!data || data.type !== "COMPILE_RESULT") return;
+      const pending = this.pending.get(data.id);
+      if (!pending) return;
+      this.pending.delete(data.id);
+      const results = [];
+      for (const raw of data.results) {
+        results.push(this.reconstructResult(raw));
+      }
+      pending.resolve(results);
+    };
+    this.worker.onerror = (err) => {
+      for (const [id, pending] of this.pending) {
+        pending.reject(
+          new Error(`Compilation worker error: ${err.message}`)
+        );
+        this.pending.delete(id);
+      }
+    };
+    return this.worker;
+  }
+  /**
+   * Batch-compile expressions in the worker.
+   *
+   * Sends a batch of { lineId, expression, textHash } to the worker,
+   * which compiles each and transfers bytecode ArrayBuffers back.
+   * Bytecode is reconstructed into BytecodeProgram objects.
+   *
+   * Results are returned in the same order as the input items.
+   *
+   * @param items Expressions to compile.
+   * @returns Compiled bytecode for each item (or error).
+   */
+  async compileBatch(items) {
+    if (items.length === 0) return [];
+    const worker = this.ensureWorker();
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      worker.postMessage({
+        type: "COMPILE_BATCH",
+        id,
+        items
+      });
+    });
+  }
+  /**
+   * Store worker-compiled bytecode into the DocumentModel, with safety
+   * validation. Only stores bytecode for lines whose text has not changed
+   * since the compilation request was dispatched.
+   *
+   * Results for the same lineId are batched, all bytecodes from
+   * successful compilations are passed to updateLineCompiled in a single
+   * call. This supports multi-expression lines (inline solves).
+   *
+   * @param results Compiled results from the worker.
+   * @param doc The target document model.
+   * @returns Number of results successfully stored (passed safety check).
+   */
+  storeResults(results, doc) {
+    const byLineId = /* @__PURE__ */ new Map();
+    for (const result of results) {
+      if (result.error) continue;
+      const state = doc.getLineById(result.lineId);
+      if (!state) continue;
+      if (state.textHash !== result.compiledAgainstHash) continue;
+      let batch = byLineId.get(result.lineId);
+      if (!batch) {
+        batch = {
+          bytecodes: [],
+          reads: /* @__PURE__ */ new Set(),
+          writes: /* @__PURE__ */ new Set(),
+          isVariableDef: false,
+          expressions: state.expressions.length > 0 ? [...state.expressions] : [],
+          textHash: result.compiledAgainstHash
+        };
+        byLineId.set(result.lineId, batch);
+      }
+      batch.bytecodes.push(result.program);
+      for (const r of result.reads) batch.reads.add(r);
+      for (const w of result.writes) batch.writes.add(w);
+      if (result.isVariableDef) batch.isVariableDef = true;
+    }
+    let stored = 0;
+    for (const [lineId, batch] of byLineId) {
+      if (batch.bytecodes.length === 0) continue;
+      const state = doc.getLineById(lineId);
+      const inlineSolveCount = state?.inlineSolveCount ?? 0;
+      doc.updateLineCompiled(
+        lineId,
+        batch.expressions,
+        batch.bytecodes,
+        [...batch.reads],
+        [...batch.writes],
+        batch.isVariableDef,
+        inlineSolveCount
+      );
+      stored += batch.bytecodes.length;
+    }
+    return stored;
+  }
+  /**
+   * Terminate the worker and clean up.
+   */
+  terminate() {
+    if (this.worker) {
+      this.worker.terminate();
+      this.worker = null;
+      this.pending.clear();
+    }
+  }
+  /**
+   * Whether the worker is currently active.
+   */
+  get isActive() {
+    return this.worker !== null;
+  }
+  // ── Private helpers ────────────────────────────────────────────────
+  /**
+   * Reconstruct a BytecodeProgram from transferred ArrayBuffers.
+   *
+   * The transferred ArrayBuffers are zero-copy, we create TypedArray
+   * views directly over them. No data is copied or serialized.
+   */
+  reconstructResult(raw) {
+    if (raw.error) {
+      return {
+        lineId: raw.lineId,
+        compiledAgainstHash: raw.compiledAgainstHash,
+        program: { opcodes: new Uint8Array(0), numbers: new Float64Array(0), strings: [], hasAsync: false },
+        reads: [],
+        writes: [],
+        isVariableDef: false,
+        error: raw.error
+      };
+    }
+    const opcodes = raw.opcodesLength > 0 ? new Uint8Array(raw.opcodesBuffer, 0, raw.opcodesLength) : new Uint8Array(0);
+    const numbers = raw.numbersLength > 0 ? new Float64Array(raw.numbersBuffer, 0, raw.numbersLength) : new Float64Array(0);
+    const program = {
+      opcodes,
+      numbers,
+      strings: raw.strings,
+      hasAsync: false
+    };
+    return {
+      lineId: raw.lineId,
+      compiledAgainstHash: raw.compiledAgainstHash,
+      program,
+      reads: raw.reads,
+      writes: raw.writes,
+      isVariableDef: raw.isVariableDef,
+      error: null
+    };
+  }
+};
+
+// src/engine/PageManager.ts
+var PAGE_SIZE = 128;
+var HOT_PAGE_RADIUS = 3;
+var WARM_PAGE_RADIUS = 6;
+var PRELOAD_PAGE_COUNT = 2;
+var COLD_EVICT_BUFFER = HOT_PAGE_RADIUS;
+var PageManager = class _PageManager {
+  constructor() {
+    /** Previous viewport for scroll direction detection. null = no previous viewport. */
+    this.lastViewportStart = null;
+    /** Saved scroll direction from the most recent maintainAfterEval call. */
+    this.savedDirection = null;
+    /** Per-page access counter for LRU tracking. */
+    this.pageAccess = /* @__PURE__ */ new Map();
+    /** Monotonically increasing access sequence number. */
+    this.accessSeq = 0;
+  }
+  // ── Static helpers ─────────────────────────────────────────────────
+  /** Get the page number for a 1-based line number (0-based page index). */
+  static pageForLine(lineNumber) {
+    return Math.floor((lineNumber - 1) / PAGE_SIZE);
+  }
+  /** Get the 1-based inclusive line range for a page. */
+  static pageRange(pageNum, docLineCount) {
+    return {
+      startLine: pageNum * PAGE_SIZE + 1,
+      endLine: Math.min((pageNum + 1) * PAGE_SIZE, docLineCount)
+    };
+  }
+  // ── Public API ─────────────────────────────────────────────────────
+  /**
+   * Detect scroll direction from viewport movement.
+   * Returns null on first call (no previous viewport) or no movement.
+   */
+  detectDirection(newViewport) {
+    if (this.lastViewportStart === null) return null;
+    if (newViewport.startLine > this.lastViewportStart) return "down";
+    if (newViewport.startLine < this.lastViewportStart) return "up";
+    return null;
+  }
+  /**
+   * Maintain page tiers after evaluation.
+   *
+   * 1. Records the new viewport position
+   * 2. Touches hot pages (viewport ± HOT_PAGE_RADIUS) for LRU
+   * 3. Evicts cold/warm pages based on distance from viewport
+   *
+   * Call this after every `evaluate()`, `setViewport()`, or `evaluateAll()`.
+   */
+  maintainAfterEval(viewport, doc) {
+    this.savedDirection = this.detectDirection(viewport);
+    this.lastViewportStart = viewport.startLine;
+    const docLineCount = doc.lineCount;
+    const viewportStartPage = _PageManager.pageForLine(viewport.startLine);
+    const viewportEndPage = _PageManager.pageForLine(viewport.endLine);
+    const lastPage = _PageManager.pageForLine(docLineCount);
+    const hotStart = Math.max(0, viewportStartPage - HOT_PAGE_RADIUS);
+    const hotEnd = Math.min(lastPage, viewportEndPage + HOT_PAGE_RADIUS);
+    const warmStart = Math.max(0, viewportStartPage - WARM_PAGE_RADIUS);
+    const warmEnd = Math.min(lastPage, viewportEndPage + WARM_PAGE_RADIUS);
+    for (let p = hotStart; p <= hotEnd; p++) {
+      this.touchPage(p);
+    }
+    for (let p = warmStart; p <= warmEnd; p++) {
+      if (p >= hotStart && p <= hotEnd) continue;
+      this.evictPageResults(p, doc, docLineCount);
+    }
+    const coldLeftEnd = warmStart - 1;
+    const coldLeftStart = Math.max(0, coldLeftEnd - COLD_EVICT_BUFFER + 1);
+    for (let p = coldLeftStart; p <= coldLeftEnd; p++) {
+      this.evictPageBytecode(p, doc, docLineCount);
+    }
+    const coldRightStart = warmEnd + 1;
+    const coldRightEnd = Math.min(lastPage, coldRightStart + COLD_EVICT_BUFFER - 1);
+    for (let p = coldRightStart; p <= coldRightEnd; p++) {
+      this.evictPageBytecode(p, doc, docLineCount);
+    }
+  }
+  /**
+   * Get lines ahead of the viewport that should be pre-compiled.
+   *
+   * Looks PRELOAD_PAGE_COUNT pages ahead of the current scroll direction.
+   * Only returns lines that are dirty, don't already have bytecode,
+   * and are not empty/markdown-only.
+   *
+   * @param viewport The current viewport.
+   * @param doc The document model.
+   * @returns Items ready to send to the compilation worker.
+   */
+  getPreloadTargets(viewport, doc) {
+    const direction = this.savedDirection;
+    if (!direction) return [];
+    const items = [];
+    const viewportEndPage = _PageManager.pageForLine(viewport.endLine);
+    const viewportStartPage = _PageManager.pageForLine(viewport.startLine);
+    const lastPage = _PageManager.pageForLine(doc.lineCount);
+    const pages = [];
+    if (direction === "down") {
+      const startPage = viewportEndPage + HOT_PAGE_RADIUS + 1;
+      const endPage = Math.min(startPage + PRELOAD_PAGE_COUNT - 1, lastPage);
+      for (let p = startPage; p <= endPage && p <= lastPage; p++) {
+        pages.push(p);
+      }
+    } else {
+      const firstPreloadPage = viewportStartPage - HOT_PAGE_RADIUS - 1;
+      for (let p = firstPreloadPage; p > firstPreloadPage - PRELOAD_PAGE_COUNT && p >= 0; p--) {
+        pages.push(p);
+      }
+    }
+    for (const pageNum of pages) {
+      const range = _PageManager.pageRange(pageNum, doc.lineCount);
+      for (let pos = range.startLine; pos <= range.endLine; pos++) {
+        const state = doc.getLineAt(pos);
+        if (!state) continue;
+        if (!state.dirty) continue;
+        if (state.bytecodes.length > 0 && !state.isVariableDef) continue;
+        if (state.isEmpty) continue;
+        if (state.expressions.length > 0) {
+          for (const expression of state.expressions) {
+            if (!expression.trim()) continue;
+            items.push({
+              lineId: state.lineId,
+              expression,
+              textHash: state.textHash
+            });
+          }
+        } else {
+          const inlineSpans = sharedLexer.findInlineSolves(state.text);
+          if (inlineSpans.length > 0) {
+            for (const span of inlineSpans) {
+              if (!span.expression.trim()) continue;
+              items.push({
+                lineId: state.lineId,
+                expression: span.expression,
+                textHash: state.textHash
+              });
+            }
+          } else {
+            const expression = state.text.trim();
+            if (expression) {
+              items.push({
+                lineId: state.lineId,
+                expression,
+                textHash: state.textHash
+              });
+            }
+          }
+        }
+      }
+    }
+    return items;
+  }
+  /**
+   * Reset internal state (e.g., after document switch).
+   */
+  clear() {
+    this.pageAccess.clear();
+    this.accessSeq = 0;
+    this.lastViewportStart = null;
+    this.savedDirection = null;
+  }
+  // ── Private helpers ─────────────────────────────────────────────────
+  /** Record a page access with a monotonic sequence number. */
+  touchPage(pageNum) {
+    this.pageAccess.set(pageNum, ++this.accessSeq);
+  }
+  /**
+   * Evict results from all non-variable-def lines in a page.
+   * Bytecode is preserved so Tier 2 execution works on scroll-back.
+   */
+  evictPageResults(pageNum, doc, docLineCount) {
+    const range = _PageManager.pageRange(pageNum, docLineCount);
+    for (let pos = range.startLine; pos <= range.endLine; pos++) {
+      const state = doc.getLineAt(pos);
+      if (state && !state.isVariableDef && state.results.length > 0) {
+        state.results = [];
+        state.result = null;
+      }
+    }
+  }
+  /**
+   * Evict bytecode + results from all non-variable-def lines in a page.
+   * Variable definition bytecode is **never** evicted, it forms the
+   * backbone of the DAG and VM checkpoints.
+   *
+   * Evicted lines are marked dirty so they get Tier 1 re-evaluation
+   * when scrolled back into view.
+   */
+  evictPageBytecode(pageNum, doc, docLineCount) {
+    const range = _PageManager.pageRange(pageNum, docLineCount);
+    for (let pos = range.startLine; pos <= range.endLine; pos++) {
+      const state = doc.getLineAt(pos);
+      if (!state || state.isVariableDef) continue;
+      if (state.bytecodes.length > 0 || state.results.length > 0) {
+        state.bytecodes = [];
+        state.results = [];
+        state.result = null;
+        doc.markDirty(state.lineId);
+      }
+    }
+  }
+};
+
+// src/engine/ThreeTierEvaluator.ts
+var EvalTier = /* @__PURE__ */ ((EvalTier2) => {
+  EvalTier2[EvalTier2["Tier1"] = 1] = "Tier1";
+  EvalTier2[EvalTier2["Tier2"] = 2] = "Tier2";
+  EvalTier2[EvalTier2["Tier3"] = 3] = "Tier3";
+  EvalTier2[EvalTier2["Skipped"] = 0] = "Skipped";
+  return EvalTier2;
+})(EvalTier || {});
+var ThreeTierEvaluator = class {
+  /**
+   * @param doc The persistent document model.
+   * @param engine The expression engine (shared VM is accessed via engine.getVM()).
+   * @param checkpointer Optional VM state checkpointer. If provided, the evaluator
+   * will create checkpoints after variable-definition lines and support fast VM
+   * restoration via `restoreTo()`. If omitted, checkpointing is disabled.
+   */
+  constructor(doc, engine, checkpointer) {
+    this.compilationWorker = null;
+    /**
+     * Unsubscribe from sharedGlobalVariableStore, set in the constructor
+     * called from terminateWorker(). See the subscription itself below for
+     * why this only marks lines dirty and never re-evaluates synchronously.
+     */
+    this.globalUnsubscribe = null;
+    this.doc = doc;
+    this.engine = engine;
+    this.dag = engine.getDag();
+    this.checkpointer = checkpointer ?? null;
+    this.pageManager = new PageManager();
+    this.engine.setDocumentModel(this.doc);
+    this.globalUnsubscribe = sharedGlobalVariableStore.subscribe((name) => {
+      for (const lineNumber of this.dag.getAffectedLines(globalDagKey(name))) {
+        this.doc.markDirtyByLineNumber(lineNumber);
+      }
+    });
+  }
+  /**
+   * Evaluate all lines needed to render the given viewport.
+   *
+   * Processes lines from 1 to `viewport.endLine` in document order.
+   * Dirty lines in the viewport get Tier-1 full pipeline; clean cached
+   * lines get Tier-2 bytecode execution. Lines after the viewport
+   * get Tier-3 compile-only (with variable-def execution).
+   *
+   * @returns Results for all processed lines, including tier metadata.
+   */
+  evaluate(viewport, signal) {
+    this.engine.setKeystrokeSignal(signal ?? null);
+    enableValueArena();
+    try {
+      const lines = [];
+      const resultMap = /* @__PURE__ */ new Map();
+      const tierCounts = { tier1: 0, tier2: 0, tier3: 0, skipped: 0 };
+      const docEnd = this.doc.lineCount;
+      const evalEnd = Math.min(viewport.endLine, docEnd);
+      for (let pos = 1; pos <= evalEnd; pos++) {
+        const state = this.doc.getLineAt(pos);
+        if (!state) {
+          tierCounts.skipped++;
+          continue;
+        }
+        const inViewport = pos >= viewport.startLine && pos <= viewport.endLine;
+        const lineResult = this.evaluateSingleLine(state, pos, inViewport);
+        lines.push(lineResult);
+        if (lineResult.tier === 1 /* Tier1 */) tierCounts.tier1++;
+        else if (lineResult.tier === 2 /* Tier2 */) tierCounts.tier2++;
+        else if (lineResult.tier === 3 /* Tier3 */) tierCounts.tier3++;
+        else tierCounts.skipped++;
+        if (lineResult.results && inViewport) {
+          resultMap.set(pos, lineResult.results.flat());
+        }
+      }
+      this.pageManager.maintainAfterEval(viewport, this.doc);
+      return { lines, resultMap, tierCounts };
+    } finally {
+      this.engine.setKeystrokeSignal(null);
+      disableValueArena();
+    }
+  }
+  /**
+   * Background-compile invisible dirty lines beyond the viewport (Tier 3 only).
+   *
+   * Compiles expressions to discover reads/writes for the dependency graph
+   * without executing display-only expressions. Variable definitions are
+   * executed to maintain VM state for future Tier-2 executions.
+   *
+   * This is intended to be called after evaluate() so visible lines are
+   * rendered first, then background work fills in the dependency graph.
+   *
+   * **Phase 5.2h:** This synchronous method is retained for environments
+   * without Worker support. Prefer `dispatchBackgroundCompiles()` which
+   * offloads compilation to a Web Worker with Transferable bytecode.
+   */
+  backgroundCompile(viewport) {
+    const results = [];
+    const docEnd = this.doc.lineCount;
+    const startPos = viewport.endLine + 1;
+    for (let pos = startPos; pos <= docEnd; pos++) {
+      const state = this.doc.getLineAt(pos);
+      if (!state) continue;
+      if (!state.dirty) continue;
+      if (state.bytecodes.length > 0 && !state.isVariableDef) continue;
+      const lineResult = this.evaluateSingleLine(state, pos, false);
+      results.push(lineResult);
+    }
+    return results;
+  }
+  /**
+   * Dispatch background compilation to a Web Worker (Phase 5.2h).
+   *
+   * Collects invisible dirty lines beyond the viewport that need compilation,
+   * sends them to the compilation worker, and asynchronously stores the
+   * transferred bytecode in the DocumentModel when the worker responds.
+   *
+   * This is the non-blocking alternative to `backgroundCompile()`. The worker
+   * compiles expressions with Transferable ArrayBuffers (zero-copy postMessage),
+   * so bytecode appears on the main thread without serialization overhead.
+   *
+   * Lines that already have cached bytecode (from a previous worker pass or
+   * synchronous compile) are skipped, only truly uncompiled dirty lines are
+   * sent to the worker.
+   *
+   * **Usage:** Call after `evaluate()` so visible lines render first, then
+   * this fills the bytecode cache for future Tier-2 scrolls.
+   *
+   * @param viewport The current visible range. Lines beyond viewport.endLine
+   * that are dirty and don't have bytecode are dispatched.
+   */
+  dispatchBackgroundCompiles(viewport) {
+    const items = this.collectInvisibleCompileTargets(viewport);
+    if (items.length === 0) return;
+    if (!this.compilationWorker) {
+      this.compilationWorker = new CompilationWorkerManager();
+    }
+    this.compilationWorker.compileBatch(items).then((results) => {
+      this.compilationWorker.storeResults(results, this.doc);
+    }).catch((_err) => {
+    });
+  }
+  /**
+   * Terminate the compilation worker if active, and unsubscribe from
+   * sharedGlobalVariableStore. Call this when the evaluator is no longer
+   * needed to clean up resources, every call site that retires a
+   * ThreeTierEvaluator (document switch, pane destroy()) already calls
+   * this unconditionally, so folding the global-store unsubscribe in here
+   * needs no new call sites anywhere.
+   */
+  terminateWorker() {
+    if (this.compilationWorker) {
+      this.compilationWorker.terminate();
+      this.compilationWorker = null;
+    }
+    if (this.globalUnsubscribe) {
+      this.globalUnsubscribe();
+      this.globalUnsubscribe = null;
+    }
+  }
+  /**
+   * Get the DocumentModel (read-only access for decoration building).
+   */
+  getDoc() {
+    return this.doc;
+  }
+  /**
+   * Evaluate all dirty lines in the document, regardless of viewport.
+   * Used for full re-evaluation after plugin register/unregister.
+   */
+  evaluateAll(signal) {
+    const viewport = { startLine: 1, endLine: this.doc.lineCount };
+    const result = this.evaluate(viewport, signal);
+    return result;
+  }
+  /**
+   * Zero-allocation viewport evaluation, the Phase 5.2e "holy grail."
+   *
+   * **Key insight:** When the user scrolls (viewport-only change, no edits),
+   * we don't need to re-evaluate from line 1. Instead:
+   *
+   * 1. Restore the VM to just before the viewport via the nearest checkpoint.
+   * 2. Evaluate ONLY the visible lines (Tier 2 for clean cached, Tier 1 for dirty).
+   * 3. Lines before the viewport are completely skipped, their state lives in
+   *    the VM checkpointer's prototypal chain.
+   *
+   * **Correctness guard:** If any variable-definition line before the viewport
+   * is dirty (e.g., the user edited a variable def that hasn't been
+   * re-evaluated yet), we clear stale checkpoints and fall back to `evaluate()`
+   * which processes from line 1 and rebuilds fresh checkpoints. This
+   * guarantees that stale checkpoints are never used as restoration targets.
+   * Only variable-def lines matter here, `VMCheckpointer.snapshot()` only
+   * records state for lines that write a variable, so a dirty plain-expression
+   * line before the viewport has no checkpoint to invalidate (see
+   * `DocumentModel.hasAnyDirtyVariableDefLineBefore()`).
+   *
+   * **Performance:** O(visible lines) instead of O(document length). Target:
+   * < 1ms for a typical ~30-line viewport, independent of document size.
+   *
+   * @param viewport The visible line range.
+   * @returns Results for visible lines only. Lines before the viewport are
+   * not included in `lines[]` or `resultMap`.
+   */
+  setViewport(viewport, signal) {
+    this.engine.setKeystrokeSignal(signal ?? null);
+    if (viewport.startLine > 1 && this.hasDirtyLinesBefore(viewport.startLine)) {
+      this.checkpointer?.clear();
+      return this.evaluate(viewport, signal);
+    }
+    this.pageManager.maintainAfterEval(viewport, this.doc);
+    this.preloadNextPages(viewport);
+    this.restoreTo(viewport.startLine - 1);
+    enableValueArena();
+    try {
+      const result = this.collectEvalResults(viewport.startLine, viewport.endLine);
+      return result;
+    } finally {
+      this.engine.setKeystrokeSignal(null);
+      disableValueArena();
+    }
+  }
+  /**
+   * Apply incremental line-level changes to the document model.
+   *
+   * **Phase 5.2f:** Replaces the O(N) `setDocument()` + full re-evaluation
+   * with O(changed) incremental updates. Key benefits:
+   *
+   * 1. Unchanged lines retain their persistent lineIds → bytecode survives
+   * 2. Only changed + DAG-downstream lines are marked dirty → Tier 1 re-evaluation
+   * 3. Clean lines in viewport use Tier 2 (cached bytecode execution)
+   * 4. Clean lines outside viewport are skipped entirely
+   *
+   * The DAG is fully cleared after propagation: shifted lines would have
+   * stale entries keyed by old line numbers, so the DAG is rebuilt from
+   * scratch during the subsequent `evaluate()` call.
+   *
+   * **Caller should follow up with `evaluate(viewport)`** to re-evaluate
+   * dirty lines from line 1 and rebuild the DAG + checkpoints.
+   *
+   * @param changes Line-level changes to apply. Must be non-overlapping.
+   * @returns Metadata about the applied changes.
+   */
+  applyTransaction(changes) {
+    const allWrites = /* @__PURE__ */ new Set();
+    for (const change of changes) {
+      for (let i = 0; i < change.deleteCount; i++) {
+        const lineNum = change.startLine + i;
+        const writes = this.dag.getWrites(lineNum);
+        for (const w of writes) {
+          allWrites.add(w);
+        }
+        this.dag.removeLine(lineNum);
+        this.engine.getLineCache().removeAllForLine(lineNum);
+      }
+    }
+    const downstreamLineIds = /* @__PURE__ */ new Set();
+    for (const writeVar of allWrites) {
+      const affected = this.dag.getAffectedLines(writeVar);
+      for (const lineNum of affected) {
+        const state = this.doc.getLineAt(lineNum);
+        if (state) {
+          downstreamLineIds.add(state.lineId);
+        }
+      }
+    }
+    const result = this.doc.applyChanges(changes);
+    this.checkpointer?.clear();
+    for (const lineId of downstreamLineIds) {
+      this.doc.markDirty(lineId);
+    }
+    this.dag.clear();
+    return {
+      inserted: result.inserted,
+      removed: result.removed
+    };
+  }
+  // ── Private helpers ─────────────────────────────────────────────────
+  /**
+   * Collect evaluation results for a contiguous range of lines.
+   *
+   * Used by both `evaluate()` (startLine=1) and `setViewport()` (any start).
+   * All lines in the range are treated as in-viewport (visible), callers that
+   * need the invisible/dirty → Tier 3 handling should use `evaluate()` instead.
+   *
+   * @param startLine First line to evaluate (1-based, inclusive).
+   * @param endLine Last line to evaluate (1-based, inclusive). Clamped to docEnd.
+   */
+  collectEvalResults(startLine, endLine) {
+    const lines = [];
+    const resultMap = /* @__PURE__ */ new Map();
+    const tierCounts = { tier1: 0, tier2: 0, tier3: 0, skipped: 0 };
+    const docEnd = this.doc.lineCount;
+    const evalEnd = Math.min(endLine, docEnd);
+    for (let pos = startLine; pos <= evalEnd; pos++) {
+      const state = this.doc.getLineAt(pos);
+      if (!state) continue;
+      const lineResult = this.evaluateSingleLine(state, pos, true);
+      lines.push(lineResult);
+      if (lineResult.tier === 1 /* Tier1 */) tierCounts.tier1++;
+      else if (lineResult.tier === 2 /* Tier2 */) tierCounts.tier2++;
+      else if (lineResult.tier === 3 /* Tier3 */) tierCounts.tier3++;
+      else tierCounts.skipped++;
+      if (lineResult.results) {
+        resultMap.set(pos, lineResult.results.flat());
+      }
+    }
+    return { lines, resultMap, tierCounts };
+  }
+  /**
+   * Check whether any **variable-definition** line before `position`
+   * (1-based, exclusive) is dirty.
+   *
+   * Used by `setViewport()` to decide whether to fall back to `evaluate()`:
+   * if a variable-def before the viewport is dirty, the checkpoint state
+   * `restoreTo()` would use may be stale and we need to reprocess from
+   * line 1 to rebuild checkpoints correctly.
+   *
+   * Deliberately narrower than `DocumentModel.hasAnyDirtyLineBefore()`:
+   * checkpoints only snapshot variable-def lines (see VMCheckpointer), so a
+   * dirty plain-expression line before the viewport can't have invalidated
+   * one, there's nothing checkpointed for it to invalidate. Using the
+   * broader check here previously caused a real perf bug: `PageManager`'s
+   * cold-page eviction marks evicted non-variable-def lines dirty, so
+   * scrolling far into a large, variable-def-free document would trip this
+   * guard, fall back to `evaluate()`, which recompiles those lines via
+   * Tier 3 (never clearing their dirty flag by design), causing the very
+   * next `maintainAfterEval()` to re-evict and re-dirty them, a
+   * self-sustaining loop that pinned every subsequent `setViewport()` call
+   * to the cost of a full re-evaluation instead of O(visible lines).
+   *
+   * Delegates to DocumentModel.hasAnyDirtyVariableDefLineBefore(), which
+   * tracks dirty lineIds incrementally instead of scanning every line up to
+   * `position` on every call. This used to be a real per-scroll cost
+   * (benchmarked at ~10ms scrolled near the bottom of a 20k-line document)
+   * since it fired on every viewport change, not just edits.
+   */
+  hasDirtyLinesBefore(position) {
+    return this.doc.hasAnyDirtyVariableDefLineBefore(position);
+  }
+  /**
+   * Evaluate a single line using the appropriate tier.
+   *
+   * Tier assignment logic:
+   * - Empty/markdown-only lines → skipped
+   * - Dirty + in-viewport → Tier 1 (full pipeline)
+   * - Dirty + not in viewport → Tier 3 (compile-only, execute variable defs)
+   * - Clean + has bytecode + in viewport → Tier 2 (execute from cache)
+   * - Clean + no bytecode → skipped (non-evaluable)
+   */
+  evaluateSingleLine(state, lineNumber, inViewport) {
+    const baseResult = {
+      lineId: state.lineId,
+      lineNumber
+    };
+    if (state.isEmpty || isEmptyLine(state.text)) {
+      state.isEmpty = true;
+      this.doc.markClean(state.lineId);
+      return { ...baseResult, tier: 0 /* Skipped */, result: null, error: null };
+    }
+    const { expressions, inlineSolveCount } = this.extractExpressions(state);
+    if (expressions.length === 0) {
+      state.isEmpty = true;
+      this.doc.markClean(state.lineId);
+      return { ...baseResult, tier: 0 /* Skipped */, result: null, error: null };
+    }
+    if (state.dirty) {
+      if (inViewport) {
+        return this.evaluateTier1(state, lineNumber, expressions, inlineSolveCount, baseResult);
+      } else {
+        if (state.bytecodes.length > 0 && state.bytecodes.length === expressions.length && !state.isVariableDef) {
+          return { ...baseResult, tier: 0 /* Skipped */, result: null, error: null };
+        }
+        return this.evaluateTier3(state, lineNumber, expressions, inlineSolveCount, baseResult);
+      }
+    }
+    if (inViewport && state.bytecodes.length > 0) {
+      return this.evaluateTier2(state, lineNumber, baseResult);
+    }
+    return { ...baseResult, tier: 0 /* Skipped */, result: null, error: null };
+  }
+  /**
+   * Tier 1: Full pipeline, lex, parse, compile, execute.
+   * Uses the engine's existing evaluateLine() which handles all pipeline
+   * stages including DAG updates and LineCache population.
+   *
+   * Supports multiple expressions per line (inline solves). Evaluates each
+   * expression left-to-right through the engine so variable definitions in
+   * earlier solves update the VM state before later solves are evaluated.
+   * Reads/writes are aggregated across all expressions for the DAG.
+   */
+  evaluateTier1(state, lineNumber, expressions, inlineSolveCount, baseResult) {
+    const allResults = [];
+    const allBytecodes = [];
+    const allReads = /* @__PURE__ */ new Set();
+    const allWrites = /* @__PURE__ */ new Set();
+    let hasVariableDef = false;
+    let lastValue = null;
+    let firstError = null;
+    let anyFailed = false;
+    let anyPending = false;
+    for (const expression of expressions) {
+      if (!expression.trim()) continue;
+      let value = null;
+      let entry;
+      try {
+        const evaluation = this.engine.evaluateLineDetailed(lineNumber, expression);
+        value = evaluation.values;
+        lastValue = value[0];
+        entry = this.engine.getLineCache().get(lineNumber, expression);
+      } catch (e) {
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        if (!firstError) firstError = errorMessage;
+        anyFailed = true;
+        value = null;
+      }
+      if (value && value.some((v) => v.type === 12 /* Pending */)) {
+        anyPending = true;
+      }
+      if (value) {
+        allResults.push(value);
+      } else {
+        allResults.push([errorValue("eval_failed", firstError ?? "unknown error")]);
+      }
+      if (entry) {
+        allBytecodes.push(entry.bytecode);
+        for (const r of entry.readVariables) allReads.add(r);
+        if (entry.writeVariable) {
+          allWrites.add(entry.writeVariable);
+          hasVariableDef = true;
+        }
+      } else {
+        try {
+          const { program, reads: reads2, writes: writes2 } = this.engine.compileExpression(expression);
+          allBytecodes.push(program);
+          for (const r of reads2) allReads.add(r);
+          for (const w of writes2) allWrites.add(w);
+          if (writes2.length > 0) hasVariableDef = true;
+        } catch (compileErr) {
+          allBytecodes.push({ opcodes: new Uint8Array(0), numbers: new Float64Array(0), strings: [], hasAsync: false });
+          if (compileErr instanceof EngineError && compileErr.context) {
+            const errReads = compileErr.context.reads;
+            const errWrites = compileErr.context.writes;
+            if (Array.isArray(errReads)) for (const r of errReads) allReads.add(r);
+            if (Array.isArray(errWrites)) for (const w of errWrites) allWrites.add(w);
+          }
+        }
+      }
+    }
+    const reads = [...allReads];
+    const writes = [...allWrites];
+    if (anyFailed || anyPending) {
+      this.doc.updateLineCompiled(
+        state.lineId,
+        expressions,
+        allBytecodes,
+        reads,
+        writes,
+        hasVariableDef,
+        inlineSolveCount
+      );
+      state.results = allResults;
+      state.result = allResults[0]?.[0] ?? null;
+      state.inlineSolveCount = inlineSolveCount;
+      state.expressions = expressions;
+    } else {
+      this.doc.updateLineResult(
+        state.lineId,
+        allResults,
+        allBytecodes,
+        expressions,
+        reads,
+        writes,
+        hasVariableDef,
+        inlineSolveCount
+      );
+    }
+    this.dag.registerLine(lineNumber, reads, writes);
+    if (this.checkpointer && writes.length > 0 && !anyFailed && !anyPending) {
+      this.checkpointer.snapshot(lineNumber, state.lineId, writes);
+    }
+    return {
+      ...baseResult,
+      tier: 1 /* Tier1 */,
+      result: lastValue,
+      results: allResults,
+      error: firstError
+    };
+  }
+  /**
+   * Tier 2: Execute from cached bytecode only.
+   * Skips lexing, parsing, and compiling, runs the pre-compiled bytecode
+   * against the engine's shared VM. Supports multiple bytecodes per line
+   * (inline solves), each is executed left-to-right so variable definitions
+   * in earlier bytecodes update the VM before later ones run.
+   * Assumes the VM already has correct variable state from preceding
+   * Tier-1 evaluations.
+   */
+  evaluateTier2(state, lineNumber, baseResult) {
+    if (state.bytecodes.length === 0) {
+      return { ...baseResult, tier: 0 /* Skipped */, result: null, error: null };
+    }
+    const results = [];
+    let lastValue = null;
+    let firstError = null;
+    let anyFailed = false;
+    for (const bytecode of state.bytecodes) {
+      if (bytecode.opcodes.length === 0) continue;
+      try {
+        const value = this.engine.executeCached(bytecode, lineNumber);
+        lastValue = value;
+        results.push([value]);
+      } catch (e) {
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        if (!firstError) firstError = errorMessage;
+        anyFailed = true;
+        results.push([errorValue("exec_failed", errorMessage)]);
+      }
+    }
+    this.dag.registerLine(lineNumber, state.reads, state.writes);
+    state.results = results;
+    state.result = results[0]?.[0] ?? null;
+    if (anyFailed) {
+      this.doc.markDirty(state.lineId);
+    }
+    return { ...baseResult, tier: 2 /* Tier2 */, result: lastValue, results, error: firstError };
+  }
+  /**
+   * Tier 3: Compile-only for invisible lines.
+   * Lex → Parse → Compile to discover reads/writes for the dependency graph.
+   * Executes the bytecode ONLY if the line defines a variable (isVariableDef
+   * or writes.length > 0), because variable assignments affect VM state
+   * that other lines depend on. Pure expression lines are compiled but NOT
+   * executed, saving CPU for large documents.
+   *
+   * Supports multiple expressions per line (inline solves). Each is compiled
+   * separately; variable-def expressions are also executed.
+   */
+  evaluateTier3(state, lineNumber, expressions, inlineSolveCount, baseResult) {
+    const allBytecodes = [];
+    const allReads = /* @__PURE__ */ new Set();
+    const allWrites = /* @__PURE__ */ new Set();
+    let hasVariableDef = false;
+    let lastResult = null;
+    let firstError = null;
+    let anyFailed = false;
+    let anyPending = false;
+    for (const expression of expressions) {
+      if (!expression.trim()) continue;
+      try {
+        const { program, reads: reads2, writes: writes2 } = this.engine.compileExpression(expression);
+        allBytecodes.push(program);
+        for (const r of reads2) allReads.add(r);
+        for (const w of writes2) allWrites.add(w);
+        if (writes2.length > 0) hasVariableDef = true;
+        if (writes2.length > 0 && program.opcodes.length > 0) {
+          lastResult = this.engine.executeCached(program, lineNumber);
+          if (lastResult && lastResult.type === 12 /* Pending */) {
+            anyPending = true;
+          }
+        }
+      } catch (e) {
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        if (!firstError) firstError = errorMessage;
+        anyFailed = true;
+        allBytecodes.push({ opcodes: new Uint8Array(0), numbers: new Float64Array(0), strings: [], hasAsync: false });
+      }
+    }
+    const reads = [...allReads];
+    const writes = [...allWrites];
+    this.doc.updateLineCompiled(
+      state.lineId,
+      expressions,
+      allBytecodes,
+      reads,
+      writes,
+      hasVariableDef,
+      inlineSolveCount
+    );
+    this.dag.registerLine(lineNumber, reads, writes);
+    if (hasVariableDef && lastResult && !anyFailed && !anyPending) {
+      state.results = [[lastResult]];
+      state.result = lastResult;
+      this.doc.markClean(state.lineId);
+      if (this.checkpointer) {
+        this.checkpointer.snapshot(lineNumber, state.lineId, writes);
+      }
+    }
+    return { ...baseResult, tier: 3 /* Tier3 */, result: lastResult, results: hasVariableDef && lastResult && !anyFailed && !anyPending ? [[lastResult]] : void 0, error: firstError };
+  }
+  // ── Public checkpoint API (used by Phase 5.2e setViewport) ──────
+  /**
+   * Restore the VM to the state at or just after the given line number.
+   *
+   * Finds the nearest checkpoint at or before `lineNumber` and replays
+   * all variable definitions from the checkpoint chain into the VM.
+   * After calling this, the VM is ready to evaluate lines starting at
+   * `lineNumber + 1` without re-evaluating all preceding lines.
+   *
+   * **Usage:** Phase 5.2e's `setViewport()` calls `restoreTo(viewport.startLine - 1)`
+   * before evaluating only the newly visible lines. This is the key to
+   * O(visible lines) scrolling.
+   *
+   * @param lineNumber The line number to restore to. Variables defined
+   * at lines ≤ this number will be available in the VM.
+   */
+  restoreTo(lineNumber) {
+    if (this.checkpointer) {
+      this.checkpointer.restoreTo(lineNumber);
+    }
+  }
+  /**
+   * Get the VM checkpointer, or null if checkpointing is disabled.
+   */
+  getCheckpointer() {
+    return this.checkpointer;
+  }
+  /**
+   * Get the PageManager (Phase 5.2g).
+   * Exposed for testing.
+   */
+  getPageManager() {
+    return this.pageManager;
+  }
+  // ── Phase 5.2g: Directional preloading ──────────────────────────
+  /**
+   * Preload the next 1–2 pages in the current scroll direction.
+   *
+   * Called during `setViewport()` (scroll-only path). Collects dirty
+   * uncompiled lines in pages just beyond the viewport and dispatches
+   * them to the background compilation worker so bytecode is ready
+   * before the user scrolls those lines into view.
+   */
+  preloadNextPages(viewport) {
+    const targets = this.pageManager.getPreloadTargets(viewport, this.doc);
+    if (targets.length === 0) return;
+    if (!this.compilationWorker) {
+      this.compilationWorker = new CompilationWorkerManager();
+    }
+    this.compilationWorker.compileBatch(targets).then((results) => {
+      this.compilationWorker.storeResults(results, this.doc);
+    }).catch((_err) => {
+    });
+  }
+  /**
+   * Collect invisible dirty lines that need background compilation.
+   *
+   * Iterates lines beyond `viewport.endLine`, filtering for:
+   * - Dirty lines (need re-compilation)
+   * - Non-empty, non-markdown lines
+   * - No existing bytecode (skip already-compiled Tier 3 lines)
+   *
+   * Returns CompileRequestItem[] suitable for CompilationWorkerManager.
+   */
+  collectInvisibleCompileTargets(viewport) {
+    const items = [];
+    const docEnd = this.doc.lineCount;
+    const startPos = viewport.endLine + 1;
+    for (let pos = startPos; pos <= docEnd; pos++) {
+      const state = this.doc.getLineAt(pos);
+      if (!state) continue;
+      if (!state.dirty) continue;
+      if (state.bytecodes.length > 0 && !state.isVariableDef) continue;
+      if (state.isEmpty || isEmptyLine(state.text)) continue;
+      const { expressions } = this.extractExpressions(state);
+      if (expressions.length === 0) continue;
+      for (const expression of expressions) {
+        if (!expression.trim()) continue;
+        items.push({
+          lineId: state.lineId,
+          expression,
+          textHash: state.textHash
+        });
+      }
+    }
+    return items;
+  }
+  /**
+   * Extract all evaluable expressions from a LineState.
+   *
+   * For full-line expressions: returns `{ expressions: [trimmedText], inlineSolveCount: 0 }`.
+   * For inline solve lines: returns `{ expressions: [...allSolves], inlineSolveCount: N }`.
+   * For pre-extracted (cached) expressions: returns the cached array.
+   *
+   * Inline solves are extracted left-to-right via the sharedLexer, so variable
+   * definitions in earlier solves (e.g., `s\`x = 5\` more text s\`x + 1\``)
+   * correctly update the VM state before later solves are evaluated.
+   */
+  extractExpressions(state) {
+    if (state.expressions.length > 0) {
+      return { expressions: state.expressions, inlineSolveCount: state.inlineSolveCount };
+    }
+    const trimmed = state.text.trim();
+    if (trimmed.length === 0) return { expressions: [], inlineSolveCount: 0 };
+    const inlineSpans = sharedLexer.findInlineSolves(state.text);
+    if (inlineSpans.length > 0) {
+      return {
+        expressions: inlineSpans.map((s) => s.expression),
+        inlineSolveCount: inlineSpans.length
+      };
+    }
+    return { expressions: [trimmed], inlineSolveCount: 0 };
+  }
+};
+
+export { DocumentModel, EvalTier, ThreeTierEvaluator };
+//# sourceMappingURL=chunk-GUG7SNSV.js.map
+//# sourceMappingURL=chunk-GUG7SNSV.js.map