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

package/dist/Token-0jpvUdPY.d.cts

@@ -0,0 +1,245 @@
+/**
+ * Lexer token produced by {@link ExpressionLexer} and consumed by parsers.
+ *
+ * Each token carries:
+ * - `type`: string name (e.g. "NUMBER", "PLUS") for diagnostics and parselet lookup
+ * - `typeId`: integer ID for O(1) comparison in parser hot paths
+ * - `value`/`text`: the token's semantic value and raw source text
+ * - `offset`/`line`/`col`: source position for error messages and highlighting
+ */
+interface Token {
+    /** String token type (e.g., "NUMBER", "PLUS", "IDENT"). Used by ParseletRegistry string-keyed maps and error messages. */
+    type: string;
+    /** Integer token type ID for fast comparison in Parser hot path.
+     * Populated by the Lexer via registerTokenType(). Use tokenTypeId(type) to get a type's ID. */
+    typeId: number;
+    value: string;
+    text: string;
+    offset: number;
+    lineBreaks: number;
+    line: number;
+    col: number;
+}
+/**
+ * Canonical token type name constants.
+ * All token types used by the lexer, parser, and VM are defined here.
+ * Custom/plugin token types should be registered via {@link registerTokenType}.
+ */
+declare const TokenTypes: {
+    readonly NUMBER: "NUMBER";
+    readonly BIGINT: "BIGINT";
+    readonly STRING: "STRING";
+    readonly IDENT: "IDENT";
+    readonly PLUS: "PLUS";
+    readonly MINUS: "MINUS";
+    readonly STAR: "STAR";
+    readonly SLASH: "SLASH";
+    readonly CARET: "CARET";
+    readonly PERCENT: "PERCENT";
+    readonly LSHIFT: "LSHIFT";
+    readonly RSHIFT: "RSHIFT";
+    readonly URSHIFT: "URSHIFT";
+    readonly LPAREN: "LPAREN";
+    readonly RPAREN: "RPAREN";
+    readonly LBRACKET: "LBRACKET";
+    readonly RBRACKET: "RBRACKET";
+    readonly LBRACE: "LBRACE";
+    readonly RBRACE: "RBRACE";
+    readonly COMMA: "COMMA";
+    readonly DOT: "DOT";
+    readonly COLON: "COLON";
+    readonly SEMICOLON: "SEMICOLON";
+    readonly EQUALS: "EQUALS";
+    readonly DOLLAR: "DOLLAR";
+    readonly POUND: "POUND";
+    readonly EURO: "EURO";
+    readonly YEN: "YEN";
+    readonly RUBLE: "RUBLE";
+    readonly WON: "WON";
+    readonly QUESTION: "QUESTION";
+    readonly BANG: "BANG";
+    readonly BIT_AND: "BIT_AND";
+    readonly BIT_OR: "BIT_OR";
+    readonly BIT_NOT: "BIT_NOT";
+    readonly KEYWORD: "KEYWORD";
+    readonly EOF: "EOF";
+    readonly ERROR: "ERROR";
+    readonly WS: "WS";
+    readonly NEWLINE: "NEWLINE";
+    readonly DATETIME_LITERAL: "DATETIME_LITERAL";
+    readonly DURATION: "DURATION";
+    readonly UNIT: "UNIT";
+    readonly ROLL: "ROLL";
+    readonly PI: "PI";
+    readonly E: "E";
+    readonly MOD: "MOD";
+    readonly OF: "OF";
+    readonly INCREASE_BY: "INCREASE_BY";
+    readonly DECREASE_BY: "DECREASE_BY";
+    readonly OF_WHAT_IS: "OF_WHAT_IS";
+    readonly ON_WHAT_IS: "ON_WHAT_IS";
+    readonly OFF_WHAT_IS: "OFF_WHAT_IS";
+    readonly NOW: "NOW";
+    readonly TODAY: "TODAY";
+    readonly TOMORROW: "TOMORROW";
+    readonly YESTERDAY: "YESTERDAY";
+    readonly DURATION_DAY: "DURATION_DAY";
+    readonly DURATION_WEEK: "DURATION_WEEK";
+    readonly DURATION_MONTH: "DURATION_MONTH";
+    readonly DURATION_YEAR: "DURATION_YEAR";
+    readonly DURATION_HOUR: "DURATION_HOUR";
+    readonly DURATION_MINUTE: "DURATION_MINUTE";
+    readonly DURATION_SECOND: "DURATION_SECOND";
+    readonly FUNC: "FUNC";
+    readonly CONVERT: "CONVERT";
+    readonly TO: "TO";
+    readonly BEST: "BEST";
+    readonly NEXT: "NEXT";
+    readonly LAST: "LAST";
+    readonly UNTIL: "UNTIL";
+    readonly SINCE: "SINCE";
+    readonly BETWEEN: "BETWEEN";
+    readonly FROM: "FROM";
+    readonly INCREASE: "INCREASE";
+    readonly DECREASE: "DECREASE";
+    readonly UNICODE_MATH: "UNICODE_MATH";
+    readonly TIMES_BY: "TIMES_BY";
+    readonly MULTIPLY_BY: "MULTIPLY_BY";
+    readonly DIVIDE_BY: "DIVIDE_BY";
+    readonly NEQ: "NEQ";
+    readonly IN: "IN";
+    readonly BIT_XOR: "BIT_XOR";
+    readonly EQUALITY: "EQUALITY";
+    readonly GTE: "GTE";
+    readonly LTE: "LTE";
+    readonly LT: "LT";
+    readonly GT: "GT";
+    readonly LOGICAL_AND: "LOGICAL_AND";
+    readonly LOGICAL_OR: "LOGICAL_OR";
+    readonly OR: "OR";
+    readonly TRUE: "TRUE";
+    readonly FALSE: "FALSE";
+    readonly IF: "IF";
+    readonly THEN: "THEN";
+    readonly ELSE: "ELSE";
+    readonly AS: "AS";
+    readonly CONVERTER_NAME: "CONVERTER_NAME";
+    readonly AVERAGE_OF: "AVERAGE_OF";
+    readonly MEDIAN_OF: "MEDIAN_OF";
+    readonly TOTAL_OF: "TOTAL_OF";
+    readonly COUNT_OF: "COUNT_OF";
+    readonly LARGER_OF: "LARGER_OF";
+    readonly SMALLER_OF: "SMALLER_OF";
+    readonly HALF_OF: "HALF_OF";
+    readonly MIDPOINT_BETWEEN: "MIDPOINT_BETWEEN";
+    readonly RANDOM_NUMBER: "RANDOM_NUMBER";
+    readonly IS_TO: "IS_TO";
+    readonly CLAMP: "CLAMP";
+    readonly MAP: "MAP";
+    readonly REDUCE: "REDUCE";
+    readonly SUM_FN: "SUM_FN";
+    readonly PROD_FN: "PROD_FN";
+    readonly EXPAND_FN: "EXPAND_FN";
+    readonly FACTOR_FN: "FACTOR_FN";
+    readonly SOLVE_FN: "SOLVE_FN";
+    readonly DER_FN: "DER_FN";
+    readonly INTEGRAL_FN: "INTEGRAL_FN";
+    readonly TAYLOR_FN: "TAYLOR_FN";
+    readonly JACOBIAN_FN: "JACOBIAN_FN";
+    readonly CONJ_FN: "CONJ_FN";
+    readonly RE_FN: "RE_FN";
+    readonly IM_FN: "IM_FN";
+    readonly CANCEL_FN: "CANCEL_FN";
+    readonly APART_FN: "APART_FN";
+    readonly IMAGINARY: "IMAGINARY";
+    readonly THEREFORE: "THEREFORE";
+    readonly TIME_IN: "TIME_IN";
+    readonly DATE_IN: "DATE_IN";
+    readonly TIME_DIFFERENCE_BETWEEN: "TIME_DIFFERENCE_BETWEEN";
+    readonly CITY_NAME: "CITY_NAME";
+    readonly BACKTICK_OPEN: "BACKTICK_OPEN";
+    readonly INLINE_SOLVE_START: "INLINE_SOLVE_START";
+    readonly COMMENT: "COMMENT";
+    readonly VEC2: "VEC2";
+    readonly VEC3: "VEC3";
+    readonly VEC4: "VEC4";
+    readonly FLOAT: "FLOAT";
+    readonly GLOBAL: "GLOBAL";
+    readonly OVER: "OVER";
+    readonly RATE_AT: "RATE_AT";
+    readonly COMPOUND_INTEREST_ON: "COMPOUND_INTEREST_ON";
+    readonly INTEREST_ON: "INTEREST_ON";
+    readonly DAILY_REPAYMENT_ON: "DAILY_REPAYMENT_ON";
+    readonly MONTHLY_REPAYMENT_ON: "MONTHLY_REPAYMENT_ON";
+    readonly ANNUAL_REPAYMENT_ON: "ANNUAL_REPAYMENT_ON";
+    readonly TOTAL_REPAYMENT_ON: "TOTAL_REPAYMENT_ON";
+    readonly DAILY_LOAN_INTEREST_ON: "DAILY_LOAN_INTEREST_ON";
+    readonly MONTHLY_LOAN_INTEREST_ON: "MONTHLY_LOAN_INTEREST_ON";
+    readonly ANNUAL_LOAN_INTEREST_ON: "ANNUAL_LOAN_INTEREST_ON";
+    readonly TOTAL_LOAN_INTEREST_ON: "TOTAL_LOAN_INTEREST_ON";
+    readonly TAX_ON: "TAX_ON";
+    readonly TAX_OFF: "TAX_OFF";
+    readonly WHAT_IS: "WHAT_IS";
+    readonly WHAT_WAS: "WHAT_WAS";
+    readonly VALUE_OF: "VALUE_OF";
+    readonly WORTH_IN: "WORTH_IN";
+    readonly ASSUMING: "ASSUMING";
+    readonly IN_YEAR_DOLLARS: "IN_YEAR_DOLLARS";
+    readonly INGREDIENT_NAME: "INGREDIENT_NAME";
+    readonly WORKDAYS_IN: "WORKDAYS_IN";
+    readonly WEEKDAY_ON: "WEEKDAY_ON";
+    readonly CURRENT_TIMESTAMP: "CURRENT_TIMESTAMP";
+    readonly TO_DATE: "TO_DATE";
+    readonly TO_TIMESTAMP: "TO_TIMESTAMP";
+    readonly WEEKDAY_IN: "WEEKDAY_IN";
+    readonly MONTH_ON: "MONTH_ON";
+    readonly MONTH_IN: "MONTH_IN";
+    readonly WEEK_ON: "WEEK_ON";
+    readonly WEEK_IN: "WEEK_IN";
+    readonly BETWEEN_UNIT: "BETWEEN_UNIT";
+    readonly IS_WEEKEND: "IS_WEEKEND";
+    readonly IS_WORKDAY: "IS_WORKDAY";
+    readonly VIDEO_TIMECODE: "VIDEO_TIMECODE";
+    readonly FRAME_COUNT: "FRAME_COUNT";
+    readonly AT: "AT";
+    readonly CURRENCY_SYMBOL: "CURRENCY_SYMBOL";
+    readonly PREV: "PREV";
+    readonly LINE_REF: "LINE_REF";
+    readonly SUM_RANGE_CALL: "SUM_RANGE_CALL";
+    readonly AVERAGE_RANGE_CALL: "AVERAGE_RANGE_CALL";
+    readonly TOTAL_ABOVE: "TOTAL_ABOVE";
+    readonly SUM_ABOVE: "SUM_ABOVE";
+    readonly AVERAGE_ABOVE: "AVERAGE_ABOVE";
+};
+/**
+ * A token's kind, as a string.
+ *
+ * Deliberately open rather than an enum: a package registers its own token
+ * types at runtime, and a closed set would make that impossible.
+ */
+type TokenType = (typeof TokenTypes)[keyof typeof TokenTypes];
+/**
+ * Register a token type name and get back its integer ID.
+ * Idempotent, returns existing ID if already registered.
+ * Call once per token type at module initialization time.
+ */
+declare function registerTokenType(name: string): number;
+/**
+ * Get the integer ID for a token type name.
+ * Lazily registers unknown token types on first access, enabling plugin providers
+ * to define custom token types (VEC2, VEC3, etc.) without pre-registration.
+ * All built-in TokenTypes are pre-registered via registerAllTokenTypes().
+ */
+declare function tokenTypeId(name: string): number;
+/**
+ * Get the string name for a token type ID (for error messages and debugging).
+ * Returns `UNKNOWN_${id}` if the ID is not registered.
+ */
+declare function tokenTypeName(id: number): string;
+/**
+ * Bootstrap all known token types from TokenTypes at module load.
+ * Call this once after TokenTypes is defined.
+ */
+declare function registerAllTokenTypes(): void;
+
+export { type Token as T, type TokenType as a, TokenTypes as b, registerTokenType as c, tokenTypeName as d, registerAllTokenTypes as r, tokenTypeId as t };

package/dist/Token-0jpvUdPY.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Lexer token produced by {@link ExpressionLexer} and consumed by parsers.
+ *
+ * Each token carries:
+ * - `type`: string name (e.g. "NUMBER", "PLUS") for diagnostics and parselet lookup
+ * - `typeId`: integer ID for O(1) comparison in parser hot paths
+ * - `value`/`text`: the token's semantic value and raw source text
+ * - `offset`/`line`/`col`: source position for error messages and highlighting
+ */
+interface Token {
+    /** String token type (e.g., "NUMBER", "PLUS", "IDENT"). Used by ParseletRegistry string-keyed maps and error messages. */
+    type: string;
+    /** Integer token type ID for fast comparison in Parser hot path.
+     * Populated by the Lexer via registerTokenType(). Use tokenTypeId(type) to get a type's ID. */
+    typeId: number;
+    value: string;
+    text: string;
+    offset: number;
+    lineBreaks: number;
+    line: number;
+    col: number;
+}
+/**
+ * Canonical token type name constants.
+ * All token types used by the lexer, parser, and VM are defined here.
+ * Custom/plugin token types should be registered via {@link registerTokenType}.
+ */
+declare const TokenTypes: {
+    readonly NUMBER: "NUMBER";
+    readonly BIGINT: "BIGINT";
+    readonly STRING: "STRING";
+    readonly IDENT: "IDENT";
+    readonly PLUS: "PLUS";
+    readonly MINUS: "MINUS";
+    readonly STAR: "STAR";
+    readonly SLASH: "SLASH";
+    readonly CARET: "CARET";
+    readonly PERCENT: "PERCENT";
+    readonly LSHIFT: "LSHIFT";
+    readonly RSHIFT: "RSHIFT";
+    readonly URSHIFT: "URSHIFT";
+    readonly LPAREN: "LPAREN";
+    readonly RPAREN: "RPAREN";
+    readonly LBRACKET: "LBRACKET";
+    readonly RBRACKET: "RBRACKET";
+    readonly LBRACE: "LBRACE";
+    readonly RBRACE: "RBRACE";
+    readonly COMMA: "COMMA";
+    readonly DOT: "DOT";
+    readonly COLON: "COLON";
+    readonly SEMICOLON: "SEMICOLON";
+    readonly EQUALS: "EQUALS";
+    readonly DOLLAR: "DOLLAR";
+    readonly POUND: "POUND";
+    readonly EURO: "EURO";
+    readonly YEN: "YEN";
+    readonly RUBLE: "RUBLE";
+    readonly WON: "WON";
+    readonly QUESTION: "QUESTION";
+    readonly BANG: "BANG";
+    readonly BIT_AND: "BIT_AND";
+    readonly BIT_OR: "BIT_OR";
+    readonly BIT_NOT: "BIT_NOT";
+    readonly KEYWORD: "KEYWORD";
+    readonly EOF: "EOF";
+    readonly ERROR: "ERROR";
+    readonly WS: "WS";
+    readonly NEWLINE: "NEWLINE";
+    readonly DATETIME_LITERAL: "DATETIME_LITERAL";
+    readonly DURATION: "DURATION";
+    readonly UNIT: "UNIT";
+    readonly ROLL: "ROLL";
+    readonly PI: "PI";
+    readonly E: "E";
+    readonly MOD: "MOD";
+    readonly OF: "OF";
+    readonly INCREASE_BY: "INCREASE_BY";
+    readonly DECREASE_BY: "DECREASE_BY";
+    readonly OF_WHAT_IS: "OF_WHAT_IS";
+    readonly ON_WHAT_IS: "ON_WHAT_IS";
+    readonly OFF_WHAT_IS: "OFF_WHAT_IS";
+    readonly NOW: "NOW";
+    readonly TODAY: "TODAY";
+    readonly TOMORROW: "TOMORROW";
+    readonly YESTERDAY: "YESTERDAY";
+    readonly DURATION_DAY: "DURATION_DAY";
+    readonly DURATION_WEEK: "DURATION_WEEK";
+    readonly DURATION_MONTH: "DURATION_MONTH";
+    readonly DURATION_YEAR: "DURATION_YEAR";
+    readonly DURATION_HOUR: "DURATION_HOUR";
+    readonly DURATION_MINUTE: "DURATION_MINUTE";
+    readonly DURATION_SECOND: "DURATION_SECOND";
+    readonly FUNC: "FUNC";
+    readonly CONVERT: "CONVERT";
+    readonly TO: "TO";
+    readonly BEST: "BEST";
+    readonly NEXT: "NEXT";
+    readonly LAST: "LAST";
+    readonly UNTIL: "UNTIL";
+    readonly SINCE: "SINCE";
+    readonly BETWEEN: "BETWEEN";
+    readonly FROM: "FROM";
+    readonly INCREASE: "INCREASE";
+    readonly DECREASE: "DECREASE";
+    readonly UNICODE_MATH: "UNICODE_MATH";
+    readonly TIMES_BY: "TIMES_BY";
+    readonly MULTIPLY_BY: "MULTIPLY_BY";
+    readonly DIVIDE_BY: "DIVIDE_BY";
+    readonly NEQ: "NEQ";
+    readonly IN: "IN";
+    readonly BIT_XOR: "BIT_XOR";
+    readonly EQUALITY: "EQUALITY";
+    readonly GTE: "GTE";
+    readonly LTE: "LTE";
+    readonly LT: "LT";
+    readonly GT: "GT";
+    readonly LOGICAL_AND: "LOGICAL_AND";
+    readonly LOGICAL_OR: "LOGICAL_OR";
+    readonly OR: "OR";
+    readonly TRUE: "TRUE";
+    readonly FALSE: "FALSE";
+    readonly IF: "IF";
+    readonly THEN: "THEN";
+    readonly ELSE: "ELSE";
+    readonly AS: "AS";
+    readonly CONVERTER_NAME: "CONVERTER_NAME";
+    readonly AVERAGE_OF: "AVERAGE_OF";
+    readonly MEDIAN_OF: "MEDIAN_OF";
+    readonly TOTAL_OF: "TOTAL_OF";
+    readonly COUNT_OF: "COUNT_OF";
+    readonly LARGER_OF: "LARGER_OF";
+    readonly SMALLER_OF: "SMALLER_OF";
+    readonly HALF_OF: "HALF_OF";
+    readonly MIDPOINT_BETWEEN: "MIDPOINT_BETWEEN";
+    readonly RANDOM_NUMBER: "RANDOM_NUMBER";
+    readonly IS_TO: "IS_TO";
+    readonly CLAMP: "CLAMP";
+    readonly MAP: "MAP";
+    readonly REDUCE: "REDUCE";
+    readonly SUM_FN: "SUM_FN";
+    readonly PROD_FN: "PROD_FN";
+    readonly EXPAND_FN: "EXPAND_FN";
+    readonly FACTOR_FN: "FACTOR_FN";
+    readonly SOLVE_FN: "SOLVE_FN";
+    readonly DER_FN: "DER_FN";
+    readonly INTEGRAL_FN: "INTEGRAL_FN";
+    readonly TAYLOR_FN: "TAYLOR_FN";
+    readonly JACOBIAN_FN: "JACOBIAN_FN";
+    readonly CONJ_FN: "CONJ_FN";
+    readonly RE_FN: "RE_FN";
+    readonly IM_FN: "IM_FN";
+    readonly CANCEL_FN: "CANCEL_FN";
+    readonly APART_FN: "APART_FN";
+    readonly IMAGINARY: "IMAGINARY";
+    readonly THEREFORE: "THEREFORE";
+    readonly TIME_IN: "TIME_IN";
+    readonly DATE_IN: "DATE_IN";
+    readonly TIME_DIFFERENCE_BETWEEN: "TIME_DIFFERENCE_BETWEEN";
+    readonly CITY_NAME: "CITY_NAME";
+    readonly BACKTICK_OPEN: "BACKTICK_OPEN";
+    readonly INLINE_SOLVE_START: "INLINE_SOLVE_START";
+    readonly COMMENT: "COMMENT";
+    readonly VEC2: "VEC2";
+    readonly VEC3: "VEC3";
+    readonly VEC4: "VEC4";
+    readonly FLOAT: "FLOAT";
+    readonly GLOBAL: "GLOBAL";
+    readonly OVER: "OVER";
+    readonly RATE_AT: "RATE_AT";
+    readonly COMPOUND_INTEREST_ON: "COMPOUND_INTEREST_ON";
+    readonly INTEREST_ON: "INTEREST_ON";
+    readonly DAILY_REPAYMENT_ON: "DAILY_REPAYMENT_ON";
+    readonly MONTHLY_REPAYMENT_ON: "MONTHLY_REPAYMENT_ON";
+    readonly ANNUAL_REPAYMENT_ON: "ANNUAL_REPAYMENT_ON";
+    readonly TOTAL_REPAYMENT_ON: "TOTAL_REPAYMENT_ON";
+    readonly DAILY_LOAN_INTEREST_ON: "DAILY_LOAN_INTEREST_ON";
+    readonly MONTHLY_LOAN_INTEREST_ON: "MONTHLY_LOAN_INTEREST_ON";
+    readonly ANNUAL_LOAN_INTEREST_ON: "ANNUAL_LOAN_INTEREST_ON";
+    readonly TOTAL_LOAN_INTEREST_ON: "TOTAL_LOAN_INTEREST_ON";
+    readonly TAX_ON: "TAX_ON";
+    readonly TAX_OFF: "TAX_OFF";
+    readonly WHAT_IS: "WHAT_IS";
+    readonly WHAT_WAS: "WHAT_WAS";
+    readonly VALUE_OF: "VALUE_OF";
+    readonly WORTH_IN: "WORTH_IN";
+    readonly ASSUMING: "ASSUMING";
+    readonly IN_YEAR_DOLLARS: "IN_YEAR_DOLLARS";
+    readonly INGREDIENT_NAME: "INGREDIENT_NAME";
+    readonly WORKDAYS_IN: "WORKDAYS_IN";
+    readonly WEEKDAY_ON: "WEEKDAY_ON";
+    readonly CURRENT_TIMESTAMP: "CURRENT_TIMESTAMP";
+    readonly TO_DATE: "TO_DATE";
+    readonly TO_TIMESTAMP: "TO_TIMESTAMP";
+    readonly WEEKDAY_IN: "WEEKDAY_IN";
+    readonly MONTH_ON: "MONTH_ON";
+    readonly MONTH_IN: "MONTH_IN";
+    readonly WEEK_ON: "WEEK_ON";
+    readonly WEEK_IN: "WEEK_IN";
+    readonly BETWEEN_UNIT: "BETWEEN_UNIT";
+    readonly IS_WEEKEND: "IS_WEEKEND";
+    readonly IS_WORKDAY: "IS_WORKDAY";
+    readonly VIDEO_TIMECODE: "VIDEO_TIMECODE";
+    readonly FRAME_COUNT: "FRAME_COUNT";
+    readonly AT: "AT";
+    readonly CURRENCY_SYMBOL: "CURRENCY_SYMBOL";
+    readonly PREV: "PREV";
+    readonly LINE_REF: "LINE_REF";
+    readonly SUM_RANGE_CALL: "SUM_RANGE_CALL";
+    readonly AVERAGE_RANGE_CALL: "AVERAGE_RANGE_CALL";
+    readonly TOTAL_ABOVE: "TOTAL_ABOVE";
+    readonly SUM_ABOVE: "SUM_ABOVE";
+    readonly AVERAGE_ABOVE: "AVERAGE_ABOVE";
+};
+/**
+ * A token's kind, as a string.
+ *
+ * Deliberately open rather than an enum: a package registers its own token
+ * types at runtime, and a closed set would make that impossible.
+ */
+type TokenType = (typeof TokenTypes)[keyof typeof TokenTypes];
+/**
+ * Register a token type name and get back its integer ID.
+ * Idempotent, returns existing ID if already registered.
+ * Call once per token type at module initialization time.
+ */
+declare function registerTokenType(name: string): number;
+/**
+ * Get the integer ID for a token type name.
+ * Lazily registers unknown token types on first access, enabling plugin providers
+ * to define custom token types (VEC2, VEC3, etc.) without pre-registration.
+ * All built-in TokenTypes are pre-registered via registerAllTokenTypes().
+ */
+declare function tokenTypeId(name: string): number;
+/**
+ * Get the string name for a token type ID (for error messages and debugging).
+ * Returns `UNKNOWN_${id}` if the ID is not registered.
+ */
+declare function tokenTypeName(id: number): string;
+/**
+ * Bootstrap all known token types from TokenTypes at module load.
+ * Call this once after TokenTypes is defined.
+ */
+declare function registerAllTokenTypes(): void;
+
+export { type Token as T, type TokenType as a, TokenTypes as b, registerTokenType as c, tokenTypeName as d, registerAllTokenTypes as r, tokenTypeId as t };

package/dist/VMCheckpoints-BmDwIXgK.d.ts

@@ -0,0 +1,171 @@
+import { V as Value } from './Value-KtAQNHur.js';
+import { V as VM } from './ScopeManager-B5k0nk05.js';
+import { U as UserFunctionDef } from './BytecodeBuilder-3egMyuDi.js';
+
+/**
+ * A point-in-time snapshot of VM variable state.
+ *
+ * Uses **prototypal inheritance** for memory efficiency: each checkpoint's
+ * `variables` object has its parent checkpoint's `variables` as its
+ * `__proto__`. This means a `getVar("x")` lookup walks the prototype chain
+ * until it finds `x`, and only variables that CHANGED at this checkpoint
+ * consume heap space. Unchanged variables are inherited from the parent.
+ *
+ * ```text
+ * Checkpoint 0 (root):  {}                        // empty scope
+ * Checkpoint 1 (:x=5):  { x: 5 }    __proto__ → 0
+ * Checkpoint 2 (:y=8):  { y: 8 }    __proto__ → 1
+ * Checkpoint 3 (:x=3):  { x: 3 }    __proto__ → 2   // shadows x=5
+ * ```
+ *
+ * To look up `x` at checkpoint 3: find own `x=3` → done.
+ * To look up `y` at checkpoint 3: not own → walk proto to checkpoint 2 → `y=8`.
+ * To look up `z` at checkpoint 3: not found anywhere → undefined.
+ *
+ * **Memory:** O(number of variable definitions) heap, independent of
+ * document length. Typical Obsidian documents have < 100 variable defs,
+ * so total checkpoint heap is < 10 KB.
+ */
+interface VMCheckpoint {
+    /** 1-based line number where this checkpoint was created. */
+    lineNumber: number;
+    /** Persistent line ID from DocumentModel. */
+    lineId: number;
+    /**
+     * Variable name → Value at this checkpoint.
+     * Own properties are variables set/updated at this line.
+     * The prototype chain provides inherited variables from parent checkpoints.
+     */
+    variables: Record<string, Value>;
+    /**
+     * User-defined-function name → definition at this checkpoint. SEPARATE
+     * from `variables` above (not prototypally chained the same way
+     * `restoreTo()` replays every checkpoint in the chain in order, so a
+     * later redefinition of the same function name naturally overwrites an
+     * earlier one during replay, without needing its own prototype walk).
+     *
+     * Without this field, a function definition's checkpoint entry would be
+     * SILENTLY LOST: `snapshot()` used to call `vm.getVar(name)` for every
+     * written name, which returns `undefined` for a function name (function
+     * defs live in `vm.userFunctions`, not the flat variable store), and a
+     * `val !== undefined` guard silently skipped it. A scroll-triggered
+     * `restoreTo()` would then reset the VM and replay only `variables`,
+     * making a function defined above the new viewport vanish (calling it
+     * would throw `UNDEFINED_FUNCTION`) even though the document still
+     * shows its definition line as clean/cached.
+     */
+    functions: Record<string, UserFunctionDef>;
+    /** Parent checkpoint (closer to document start), or null for root. */
+    parent: VMCheckpoint | null;
+}
+/**
+ * Manages VM state checkpoints for the three-tier evaluation strategy.
+ *
+ * **Checkpoint creation:** After a variable-definition line executes
+ * (Tier 1 or Tier 3), `snapshot()` records the current values of the
+ * written variables. The checkpoint is linked via prototypal inheritance
+ * to the previous checkpoint, so only changed variables consume memory.
+ *
+ * **Checkpoint restoration:** Before evaluating a viewport whose start line
+ * is not line 1, `restoreTo(lineNumber)` resets the VM and replays all
+ * variable definitions up to and including that line. This avoids
+ * re-evaluating the entire document from line 1 on every scroll.
+ *
+ * **Thread safety:** Checkpoints are created synchronously on the main
+ * thread during evaluation. They are immutable after creation (Value is
+ * an immutable type), so no synchronization is needed.
+ *
+ * **Integration with Phase 5.2e:** `setViewport()` will use `getNearestCheckpoint()`
+ * to find the checkpoint just before the new viewport start, then call
+ * `restoreTo()` to set up the VM before evaluating only the visible lines.
+ * This is the key to O(visible lines) scrolling instead of O(document).
+ */
+declare class VMCheckpointer {
+    /** Ordered array of checkpoints (ascending lineNumber). */
+    private checkpoints;
+    /** The VM instance whose variables are snapshotted/restored. */
+    private vm;
+    constructor(vm: VM);
+    /**
+     * Create a checkpoint at the current line, recording the VM values of
+     * the specified variables.
+     *
+     * Uses prototypal inheritance: `Object.create(parent.variables)` so
+     * that inherited variable lookups fall through to previous checkpoints
+     * without copying all variables into each checkpoint.
+     *
+     * @param lineNumber 1-based line position.
+     * @param lineId Persistent line ID from DocumentModel.
+     * @param variableNames Names of variables that were written at this line.
+     * @returns The new checkpoint, or null if no variable names provided.
+     */
+    snapshot(lineNumber: number, lineId: number, variableNames: string[]): VMCheckpoint | null;
+    /**
+     * Restore the VM to the state at or just after the given line number.
+     *
+     * Finds the nearest checkpoint whose `lineNumber <= targetLineNumber`,
+     * then replays all variable definitions from root → that checkpoint
+     * into the VM via `setVar()`. The VM's stack is also reset.
+     *
+     * If no checkpoint exists at or before the target line, the VM is
+     * fully reset (empty scope, empty stack).
+     *
+     * **Performance:** O(number of checkpoints × variables per checkpoint).
+     * With prototypal inheritance, `Object.keys()` on each checkpoint
+     * returns only the variables that were set at that checkpoint (not
+     * inherited ones), so the total work is O(total variable definitions
+     * in the document), which is < 100 for typical Obsidian documents.
+     *
+     * @param lineNumber Target 1-based line number. The VM will have the
+     * state that existed AFTER evaluating lines up to `lineNumber`.
+     */
+    restoreTo(lineNumber: number): void;
+    /**
+     * Find the nearest checkpoint at or before the given line number.
+     *
+     * Uses linear scan (checkpoints are sorted by lineNumber and the list
+     * is short, typically < 20 for Obsidian documents). Can be upgraded
+     * to binary search if needed for documents with 1000+ variable defs.
+     *
+     * @returns The nearest checkpoint, or null if none exists before the line.
+     */
+    getNearestCheckpoint(lineNumber: number): VMCheckpoint | null;
+    /**
+     * Get a specific checkpoint by its line number.
+     * @returns The checkpoint, or undefined if not found.
+     */
+    getCheckpointAt(lineNumber: number): VMCheckpoint | undefined;
+    /**
+     * Get the entire checkpoint chain from root to the last checkpoint.
+     * Useful for debugging and serialization.
+     */
+    getAllCheckpoints(): readonly VMCheckpoint[];
+    /**
+     * Look up a variable's value through the checkpoint chain.
+     *
+     * Walks the prototype chain starting from the most recent checkpoint,
+     * looking for the variable name as an own property. This is O(depth)
+     * where depth is the number of checkpoints since the variable was
+     * last set.
+     *
+     * **Note:** This queries the checkpointer's snapshot, not the VM.
+     * The VM may have been modified since the last snapshot (e.g., by
+     * Tier 2 execution of non-variable-def lines that don't create checkpoints).
+     *
+     * @returns The Value, or undefined if the variable was never set.
+     */
+    lookupVariable(name: string): Value | undefined;
+    /**
+     * Clear all checkpoints. The underlying VM is NOT reset, call
+     * `vm.reset()` separately if needed.
+     */
+    clear(): void;
+    /** Number of checkpoints stored. */
+    get count(): number;
+    /** Returns true if no checkpoints have been created. */
+    get isEmpty(): boolean;
+    /** The associated VM instance. */
+    get vmInstance(): VM;
+}
+
+export { type VMCheckpoint as V, VMCheckpointer as a };