solve-engine 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/engine.d.cts

@@ -0,0 +1,587 @@
+import { D as DocumentModel, a as ExpressionEngine, V as ViewportRange, c as LineChange, d as InlineSolvePosition } from './PackageRegistry-D-Tv_7ca.cjs';
+export { A as ApplyChangesResult, e as AsyncCachePackageInfo, f as AsyncErrorEvent, g as AsyncResolutionBatcher, h as AsyncResolutionEvent, B as BatcherMetrics, i as BytecodeCacheEntry, C as CacheSnapshot, j as CheckpointSnapshot, E as EvalResults, k as LineCacheEntryInfo, L as LineEvaluation, l as LineState, m as LinesUpdatedEvent } from './PackageRegistry-D-Tv_7ca.cjs';
+import { V as Value } from './Value-KtAQNHur.cjs';
+import { a as VMCheckpointer } from './VMCheckpoints-CqFuLwrT.cjs';
+import { T as Token } from './Token-0jpvUdPY.cjs';
+import { E as EngineError } from './EngineError-DvPSnhZi.cjs';
+import { a as BytecodeProgram } from './BytecodeBuilder-3egMyuDi.cjs';
+export { a as DagSnapshot } from './ScopeManager-CKfQtl7l.cjs';
+import './Parselet-CK8cQu2a.cjs';
+import './pipeline-DPUQt7yL.cjs';
+import './variables.cjs';
+import './Lexer-BJdhlnej.cjs';
+import './resolvers.cjs';
+import '@tanstack/query-core';
+import './NormalizerRule-BrVoVjmP.cjs';
+import './Configuration-fVpd-HC-.cjs';
+
+/**
+ * PageManager, page-based LRU eviction + directional preloading.
+ *
+ * Groups document lines into fixed-size pages (128 lines each) and manages
+ * three temperature tiers:
+ *   • Hot  (viewport ± 3 pages): Keep bytecode + results
+ *   • Warm (viewport ± 6 pages): Keep bytecode, evict results
+ *   • Cold (beyond ± 6 pages): Evict bytecode + results (except variable defs)
+ *
+ * Variable definition bytecode is **never evicted** because it forms the
+ * backbone of the dependency graph and VM checkpoints.
+ *
+ * Preloading: When the user scrolls in a consistent direction, the next
+ * 1–2 pages are pre-compiled via the background worker so bytecode is
+ * cache-hot by the time those lines scroll into view.
+ *
+ * Usage:
+ *   const pm = new PageManager();
+ *   // After evaluation:
+ *   pm.maintainAfterEval(viewport, doc);
+ *   // After scroll (viewport-only change):
+ *   pm.maintainAfterEval(viewport, doc);
+ *   const targets = pm.getPreloadTargets(viewport, doc);
+ *   // dispatch targets to compilation worker
+ */
+
+/**
+ * Splits a long document into pages so only what is near the viewport is held
+ * in full.
+ *
+ * A document is edited constantly and most of it is off screen. Paging keeps
+ * the cost of a keystroke proportional to what is visible rather than to the
+ * length of the document.
+ */
+declare class PageManager {
+    /** Previous viewport for scroll direction detection. null = no previous viewport. */
+    private lastViewportStart;
+    /** Saved scroll direction from the most recent maintainAfterEval call. */
+    private savedDirection;
+    /** Per-page access counter for LRU tracking. */
+    private pageAccess;
+    /** Monotonically increasing access sequence number. */
+    private accessSeq;
+    /** Get the page number for a 1-based line number (0-based page index). */
+    static pageForLine(lineNumber: number): number;
+    /** Get the 1-based inclusive line range for a page. */
+    static pageRange(pageNum: number, docLineCount: number): {
+        startLine: number;
+        endLine: number;
+    };
+    /**
+     * Detect scroll direction from viewport movement.
+     * Returns null on first call (no previous viewport) or no movement.
+     */
+    detectDirection(newViewport: {
+        startLine: number;
+    }): "down" | "up" | 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: {
+        startLine: number;
+        endLine: number;
+    }, doc: DocumentModel): void;
+    /**
+     * 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: {
+        startLine: number;
+        endLine: number;
+    }, doc: DocumentModel): Array<{
+        lineId: number;
+        expression: string;
+        textHash: number;
+    }>;
+    /**
+     * Reset internal state (e.g., after document switch).
+     */
+    clear(): void;
+    /** Record a page access with a monotonic sequence number. */
+    private touchPage;
+    /**
+     * Evict results from all non-variable-def lines in a page.
+     * Bytecode is preserved so Tier 2 execution works on scroll-back.
+     */
+    private evictPageResults;
+    /**
+     * 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.
+     */
+    private evictPageBytecode;
+}
+
+/**
+ * How much work a line's evaluation required.
+ *
+ * The tiers exist because most lines in a document have not changed. A line
+ * that is clean and cached costs far less than one being compiled fresh, and
+ * knowing which happened is how a slow document gets diagnosed.
+ */
+declare enum EvalTier {
+    /** Full pipeline: Lex → Parse → Compile → Execute (visible + dirty). */
+    Tier1 = 1,
+    /** Execute-only from cached bytecode (visible + cached). */
+    Tier2 = 2,
+    /** Compile-only for dependency tracking (invisible). Executes only variable assignments. */
+    Tier3 = 3,
+    /** Skipped, already clean or non-evaluable. */
+    Skipped = 0
+}
+/** Outcome for one line, including which tier handled it. */
+interface EvalLineResult {
+    /** The line's persistent ID from DocumentModel. */
+    lineId: number;
+    /** 1-based line position. */
+    lineNumber: number;
+    /** Which tier was used. */
+    tier: EvalTier;
+    /** The first evaluation result, or null on error / non-evaluable. */
+    result: Value | null;
+    /** All result groups (one per expression/inline-solve), or undefined if skipped. */
+    results?: Value[][];
+    /** Error message, or null. */
+    error: string | null;
+}
+/** Outcome for a whole evaluation pass, with per-tier counts. */
+interface EvalResult {
+    /** Per-line evaluation results. */
+    lines: EvalLineResult[];
+    /** Map of line numbers → flattened results for quick lookup. */
+    resultMap: Map<number, Value[]>;
+    /** Number of lines processed at each tier. */
+    tierCounts: {
+        tier1: number;
+        tier2: number;
+        tier3: number;
+        skipped: number;
+    };
+}
+/**
+ * Orchestrates three-tier evaluation over a persistent DocumentModel.
+ *
+ * ── Tier assignment ─────────────────────────────────────────────────
+ * | Tier  | Condition                          | Action                        |
+ * |───────|────────────────────────────────────|───────────────────────────────|
+ * | **1** | Visible + Dirty (new/changed)      | Full pipeline: lex→parse→compile→execute |
+ * | **2** | Visible + Cached (scroll into view)| Execute from cached bytecode  |
+ * | **3** | Invisible + Dirty                  | Compile-only; execute only variable defs |
+ * | Skip  | Clean, empty, or non-evaluable     | No action                     |
+ *
+ * ── Evaluation order ─────────────────────────────────────────────────
+ * Lines are always processed in ascending document order (line 1 → end)
+ * so that variable assignments flow correctly through the shared VM.
+ * Tier 2 relies on this: by the time a clean cached line is reached,
+ * the VM already contains all variables from preceding Tier-1 lines.
+ *
+ * ── Thread safety ────────────────────────────────────────────────────
+ * Tier 1 (visible+dirty) compilation runs synchronously on the main thread
+ * for immediate rendering. Tier 3 (invisible+dirty) compilation can be
+ * dispatched to a Web Worker via `dispatchBackgroundCompiles()`. Worker-
+ * compiled bytecode is stored in the DocumentModel and validated via
+ * `isBytecodeValid()` to ensure the line text hasn't changed between
+ * dispatch and response.
+ */
+declare class ThreeTierEvaluator {
+    private doc;
+    private engine;
+    private dag;
+    private checkpointer;
+    private compilationWorker;
+    private pageManager;
+    /**
+     * 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.
+     */
+    private globalUnsubscribe;
+    /**
+     * @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: DocumentModel, engine: ExpressionEngine, checkpointer?: VMCheckpointer);
+    /**
+     * 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: ViewportRange, signal?: AbortSignal): EvalResult;
+    /**
+     * 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: ViewportRange): EvalLineResult[];
+    /**
+     * 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: ViewportRange): void;
+    /**
+     * 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(): void;
+    /**
+     * Get the DocumentModel (read-only access for decoration building).
+     */
+    getDoc(): DocumentModel;
+    /**
+     * Evaluate all dirty lines in the document, regardless of viewport.
+     * Used for full re-evaluation after plugin register/unregister.
+     */
+    evaluateAll(signal?: AbortSignal): EvalResult;
+    /**
+     * 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: ViewportRange, signal?: AbortSignal): EvalResult;
+    /**
+     * 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: LineChange[]): {
+        inserted: number[];
+        removed: number[];
+    };
+    /**
+     * 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.
+     */
+    private collectEvalResults;
+    /**
+     * 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.
+     */
+    private hasDirtyLinesBefore;
+    /**
+     * 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)
+     */
+    private evaluateSingleLine;
+    /**
+     * 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.
+     */
+    private evaluateTier1;
+    /**
+     * 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.
+     */
+    private evaluateTier2;
+    /**
+     * 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.
+     */
+    private evaluateTier3;
+    /**
+     * 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: number): void;
+    /**
+     * Get the VM checkpointer, or null if checkpointing is disabled.
+     */
+    getCheckpointer(): VMCheckpointer | null;
+    /**
+     * Get the PageManager (Phase 5.2g).
+     * Exposed for testing.
+     */
+    getPageManager(): PageManager;
+    /**
+     * 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.
+     */
+    private preloadNextPages;
+    /**
+     * 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.
+     */
+    private collectInvisibleCompileTargets;
+    /**
+     * 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.
+     */
+    private extractExpressions;
+}
+
+/** Bounds applied to input before parsing: length and nesting depth. */
+interface ValidationConfig {
+    maxExpressionLength: number;
+    maxComplexity: number;
+}
+/** Whether input passed the safety bounds, and which one it failed. */
+interface SafetyCheckResult {
+    passed: boolean;
+    /**
+     * `error.error` (a plain string) exists purely because it's spread
+     * directly into `evaluateExpressionWithDiagnostic()`'s own return shape
+     * (`{value, tokens, program, error?: string, ...}`), which deliberately
+     * keeps errors as display strings for the debug/diagnostic pipeline
+     * see that method's own doc comment. `error.engineError` is additive
+     * (doesn't replace the string field, so existing consumers of this
+     * exported type are unaffected): it carries the real EngineError this
+     * check constructed internally, so callers that DO want the original
+     * code/category/expected/found/suggestion (prepareExpression(), not the
+     * diagnostic pipeline) don't have to reconstruct a generic one from just
+     * the flattened message.
+     */
+    error?: {
+        value: Value;
+        tokens: Token[];
+        program: BytecodeProgram;
+        error: string;
+        engineError?: EngineError;
+    };
+}
+/**
+ * Check that the expression doesn't exceed the maximum allowed length.
+ */
+declare function checkExpressionLength(expression: string, config: ValidationConfig): SafetyCheckResult;
+/**
+ * Score expression complexity based on token count, function calls, and nesting depth.
+ * Returns the complexity score and whether it exceeds the configured maximum.
+ */
+declare function checkExpressionComplexity(tokens: Token[], config: ValidationConfig): {
+    passed: boolean;
+    complexityScore: number;
+    errorMessage?: string;
+    engineError?: EngineError;
+};
+/**
+ * Extract variable reads and writes from a token stream.
+ *
+ * Handles both IDENT and UNIT tokens as potential variable references.
+ * UNIT tokens occur when the variable name collides with a known unit
+ * (e.g., "b" for bits, "s" for seconds). The colon prefix unambiguously
+ * signals a variable definition context (handled by VariableParselet).
+ * A standalone UNIT token is only a real variable reference when it
+ * isn't in unit-literal position (see {@link isUnitLiteralContext})
+ * otherwise it's a quantity/conversion unit name, never LOAD_VAR'd.
+ *
+ * Also detects user-defined-function DEFINITIONS (`name(params) = body`)
+ * as a read+write of the function's own name, mirroring `:name = value`'s
+ * existing convention of registering the defined name as both, and
+ * excludes the definition's own PARAMETER names from reads/writes
+ * entirely (see {@link collectFunctionParamNames}). A function CALL
+ * (`name(args)`, no trailing `=`) needs no special detection: the call's
+ * own name falls through to the ordinary bare-identifier read-tracking
+ * below, the same as any other `LOAD_VAR`-producing identifier. This is
+ * already correct once calls compile successfully, no change needed.
+ */
+declare function extractReadsAndWrites(tokens: Token[]): {
+    reads: string[];
+    writes: string[];
+};
+/**
+ * Check if a line is effectively empty (whitespace only or only markdown syntax).
+ *
+ * Phase B: Delegates to the ExpressionLexer's character-by-character
+ * markdown line scanner, replacing the old regex-based heuristics.
+ *
+ * Skips lines that contain no evaluable expression:
+ * - Whitespace-only lines
+ * - Markdown structural markers (headings, blockquotes, lists without inline solves)
+ * - Code block fences (```)
+ * - MathJax block fences ($$)
+ * - Table separator rows (|---|)
+ * - Horizontal rules (---, ***, ___)
+ * - Standalone wikilinks / embeds ([[...]], ![[...]])
+ * - Whole-line comments (a line whose first non-whitespace characters are `//`)
+ *
+ * Lines containing inline solves (s\`...\`) are never considered empty.
+ *
+ * Note: a trailing `#`/`//` comment in the MIDDLE of an otherwise-evaluable
+ * line does NOT make isEmptyLine() return true, that line is still an
+ * "expression" line (skip: false). The comment is instead stripped at
+ * tokenization time (ExpressionLexer's HASH/`//` handling emits a COMMENT
+ * token for the rest of the line) and then filtered out of the token
+ * stream by ExpressionEngine.prepareExpression() before parsing, so
+ * `<expr> // note` evaluates identically to `<expr>` alone.
+ */
+declare function isEmptyLine(lineText: string): boolean;
+/**
+ * Find all inline solves in a line with precise coordinate mapping.
+ *
+ * Phase B: Delegates to the ExpressionLexer's character-by-character
+ * scanner (no regex, handles escaped backticks).
+ */
+declare function findInlineSolvesInLine(lineText: string, lineNumber: number): InlineSolvePosition[];
+
+export { DocumentModel, type EvalLineResult, type EvalResult, EvalTier, ExpressionEngine, InlineSolvePosition, LineChange, type SafetyCheckResult, ThreeTierEvaluator, type ValidationConfig, ViewportRange, checkExpressionComplexity, checkExpressionLength, extractReadsAndWrites, findInlineSolvesInLine, isEmptyLine };