@xnoxs/flux-lang 3.1.1

package/src/parser.js

@@ -0,0 +1,1671 @@
+'use strict';
+
+const { T } = require('./lexer');
+
+// Human-readable labels for token types used in error messages
+const TOKEN_LABEL = {
+  COLON:      '":"',          COMMA:    '","',        DOT:      '"."',
+  LPAREN:     '"("',          RPAREN:   '")"',
+  LBRACKET:   '"["',          RBRACKET: '"]"',
+  LBRACE:     '"{"',          RBRACE:   '"}"',
+  ARROW:      '"->"',         FATARROW: '"=>"',
+  EQ:         '"="',          EQEQ:     '"=="',       NEQ:      '"!="',
+  PLUS:       '"+"',          MINUS:    '"-"',        STAR:     '"*"',
+  SLASH:      '"/"',          PERCENT:  '"%"',        STARSTAR: '"**"',
+  LT:         '"<"',          GT:       '">"',        LTE:      '"<="', GTE: '">="',
+  PIPE:       '"|>"',         PIPEB:    '"|"',        DOTDOT:   '".."',
+  DOTDOTDOT:  '"..."',        QUESTION: '"?"',        BANG:     '"!"',
+  NEWLINE:    'end of line',
+  INDENT:     'indented block',
+  DEDENT:     'end of block',
+  EOF:        'end of file',
+  IDENT:      'identifier',
+  NUMBER:     'number',
+  STRING:     'string',
+  BOOL:       'true/false',
+  NULL:       'null',
+  FN:         '"fn"',         VAL:  '"val"',   VAR:    '"var"',
+  IF:         '"if"',         ELSE: '"else"',  FOR:    '"for"',
+  WHILE:      '"while"',      IN:   '"in"',    RETURN: '"return"',
+  CLASS:      '"class"',      NEW:  '"new"',   SELF:   '"self"',
+  IMPORT:     '"import"',     FROM: '"from"',  EXPORT: '"export"',
+  MATCH:      '"match"',      WHEN: '"when"',
+  AND:        '"and"',        OR:   '"or"',    NOT:    '"not"',
+  ASYNC:      '"async"',      AWAIT:'"await"',
+  TRY:        '"try"',        CATCH:'"catch"', FINALLY:'"finally"', THROW:'"throw"',
+};
+
+function tokenLabel(type, value) {
+  if (TOKEN_LABEL[type]) return TOKEN_LABEL[type];
+  if (value != null && value !== type) return `"${value}"`;
+  return `"${type.toLowerCase()}"`;
+}
+
+class ParseError extends Error {
+  constructor(msg, tok) {
+    super(msg);
+    this.name = 'ParseError';
+    this.tok  = tok;
+    this.line = tok ? tok.line : null;
+    this.col  = tok ? tok.col  : null;
+  }
+}
+
+// ── "Did you mean?" suggestion engine ────────────────────────────────────────
+
+// All Flux keywords a user might misspell
+const FLUX_KEYWORDS = [
+  'val', 'var', 'fn', 'return', 'if', 'else', 'for', 'in', 'while', 'do',
+  'break', 'continue', 'match', 'when', 'class', 'extends', 'self', 'new',
+  'interface', 'implements', 'import', 'export', 'from', 'as', 'default',
+  'and', 'or', 'not', 'async', 'await', 'try', 'catch', 'finally', 'throw',
+  'type', 'enum', 'static', 'abstract', 'override', 'readonly',
+  'private', 'public', 'protected', 'true', 'false', 'null',
+];
+
+// Common language cross-contamination: JS / Python / other → Flux
+const COMMON_ALIASES = {
+  // JavaScript habits
+  'function':  { fix: 'fn',          note: 'Flux uses "fn" instead of "function"' },
+  'func':      { fix: 'fn',          note: 'Flux uses "fn" for functions' },
+  'def':       { fix: 'fn',          note: 'Flux uses "fn" for functions (not "def" like Python)' },
+  'const':     { fix: 'val',         note: 'Flux uses "val" for immutable bindings (not "const")' },
+  'let':       { fix: 'var',         note: 'Flux uses "var" for mutable bindings (not "let")' },
+  'elif':      { fix: 'else if',     note: 'Flux uses "else if" (not "elif" like Python)' },
+  'elsif':     { fix: 'else if',     note: 'Flux uses "else if" (not "elsif")' },
+  'elseif':    { fix: 'else if',     note: 'Flux uses "else if" as two separate keywords' },
+  'switch':    { fix: 'match',       note: 'Flux uses "match/when" instead of "switch/case"' },
+  'case':      { fix: 'when',        note: 'Flux uses "when" inside a "match" block' },
+  'foreach':   { fix: 'for ... in',  note: 'Flux uses "for item in collection:" syntax' },
+  'forEach':   { fix: 'for ... in',  note: 'Flux uses "for item in collection:" syntax' },
+  'lambda':    { fix: 'fn',          note: 'Flux uses "fn" or the "->" arrow for inline functions' },
+  'struct':    { fix: 'class',       note: 'Flux uses "class" for data types (no structs)' },
+  'interface': null, // valid Flux keyword
+  'print':     null, // valid Flux builtin
+  // Capitalisation mistakes
+  'Fn':        { fix: 'fn',     note: 'Flux keywords are lowercase' },
+  'FN':        { fix: 'fn',     note: 'Flux keywords are lowercase' },
+  'Val':       { fix: 'val',    note: 'Flux keywords are lowercase' },
+  'Var':       { fix: 'var',    note: 'Flux keywords are lowercase' },
+  'If':        { fix: 'if',     note: 'Flux keywords are lowercase' },
+  'Else':      { fix: 'else',   note: 'Flux keywords are lowercase' },
+  'For':       { fix: 'for',    note: 'Flux keywords are lowercase' },
+  'While':     { fix: 'while',  note: 'Flux keywords are lowercase' },
+  'Return':    { fix: 'return', note: 'Flux keywords are lowercase' },
+  'Class':     { fix: 'class',  note: 'Flux keywords are lowercase' },
+  'Import':    { fix: 'import', note: 'Flux keywords are lowercase' },
+  'Export':    { fix: 'export', note: 'Flux keywords are lowercase' },
+  'New':       { fix: 'new',    note: 'Flux keywords are lowercase' },
+  'True':      { fix: 'true',   note: 'Flux keywords are lowercase' },
+  'False':     { fix: 'false',  note: 'Flux keywords are lowercase' },
+  'Null':      { fix: 'null',   note: 'Flux keywords are lowercase' },
+  'Async':     { fix: 'async',  note: 'Flux keywords are lowercase' },
+  'Await':     { fix: 'await',  note: 'Flux keywords are lowercase' },
+  'Match':     { fix: 'match',  note: 'Flux keywords are lowercase' },
+  'Try':       { fix: 'try',    note: 'Flux keywords are lowercase' },
+  'Catch':     { fix: 'catch',  note: 'Flux keywords are lowercase' },
+};
+
+// Levenshtein distance (max 2 — bail out early for performance)
+function levenshtein(a, b, maxDist = 2) {
+  if (Math.abs(a.length - b.length) > maxDist) return maxDist + 1;
+  const m = a.length, n = b.length;
+  const prev = new Uint8Array(n + 1);
+  const curr = new Uint8Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    let rowMin = i;
+    for (let j = 1; j <= n; j++) {
+      const cost  = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+      if (curr[j] < rowMin) rowMin = curr[j];
+    }
+    if (rowMin > maxDist) return maxDist + 1;
+    curr.copyWithin(0, 0, n + 1);
+    prev.set(curr);
+  }
+  return prev[n];
+}
+
+// Returns a hint string if `word` looks like a misspelled Flux keyword, else null
+function suggestKeyword(word) {
+  if (!word || word.length < 2) return null;
+
+  // 1. Exact alias match (cross-language / capitalisation)
+  if (Object.prototype.hasOwnProperty.call(COMMON_ALIASES, word)) {
+    const alias = COMMON_ALIASES[word];
+    if (!alias) return null; // explicitly marked as valid
+    return `Did you mean "${alias.fix}"? ${alias.note}`;
+  }
+
+  // 2. Fuzzy match against all keywords (distance ≤ 2, prefer closer matches)
+  let bestDist = 3;
+  let bestKw   = null;
+  for (const kw of FLUX_KEYWORDS) {
+    if (Math.abs(word.length - kw.length) > 2) continue;
+    const d = levenshtein(word.toLowerCase(), kw, 2);
+    if (d < bestDist) { bestDist = d; bestKw = kw; }
+  }
+  if (bestKw && bestDist <= 2 && word !== bestKw) {
+    return `Did you mean "${bestKw}"?`;
+  }
+
+  return null;
+}
+
+// ── Parser ────────────────────────────────────────────────────────────────────
+class Parser {
+  constructor(tokens) {
+    this.tokens = tokens;
+    this.pos    = 0;
+  }
+
+  peek(n = 0)  { return this.tokens[this.pos + n] || { type: T.EOF, value: null, line: 0, col: 0 }; }
+  check(type)  { return this.peek().type === type; }
+  at(...types) { return types.includes(this.peek().type); }
+
+  eat(type) {
+    const tok = this.peek();
+    if (tok.type !== type) {
+      const exp  = tokenLabel(type, null);
+      const got  = tokenLabel(tok.type, tok.value);
+      const err  = new ParseError(`Expected ${exp} but got ${got}`, tok);
+      // If we got an identifier where a keyword was expected, check for typo
+      if (tok.type === T.IDENT) {
+        const hint = suggestKeyword(tok.value);
+        if (hint) err.hint = hint;
+      }
+      throw err;
+    }
+    this.pos++;
+    return tok;
+  }
+
+  maybe(type)  { if (this.check(type)) { this.pos++; return true; } return false; }
+  skip()       { return this.tokens[this.pos++]; }
+  skipNewlines() { while (this.check(T.NEWLINE)) this.pos++; }
+  err(msg) { throw new ParseError(msg, this.peek()); }
+
+  parseBlock() {
+    this.eat(T.COLON);
+    if (this.check(T.NEWLINE)) {
+      this.pos++;
+      this.eat(T.INDENT);
+      const body = this.parseStmtList(() =>
+        this.check(T.DEDENT) || this.check(T.EOF));
+      this.maybe(T.DEDENT);
+      return body;
+    }
+    const stmt = this.parseOneStmt();
+    return [stmt];
+  }
+
+  // Parse an indented block WITHOUT a leading colon (used by `->` multiline arrow).
+  parseIndentedBlock() {
+    this.eat(T.NEWLINE);
+    this.eat(T.INDENT);
+    const body = this.parseStmtList(() => this.check(T.DEDENT) || this.check(T.EOF));
+    this.maybe(T.DEDENT);
+    return body;
+  }
+
+  parse() {
+    this.skipNewlines();
+    const body = this.parseStmtList(() => this.check(T.EOF));
+    return { type: 'Program', body };
+  }
+
+  parseStmtList(stopFn) {
+    const stmts = [];
+    while (!stopFn()) {
+      this.skipNewlines();
+      if (stopFn()) break;
+      stmts.push(this.parseOneStmt());
+    }
+    return stmts;
+  }
+
+  parseOneStmt() {
+    const tok = this.peek();
+    switch (tok.type) {
+      case T.VAR:
+      case T.VAL:      return this.parseVarDecl();
+      case T.FN:       return this.parseFnDecl();
+      case T.ASYNC:    return this.parseAsyncFn();
+      case T.CLASS:    return this.parseClassDecl();
+      case T.IF:       return this.parseIf();
+      case T.FOR:      return this.parseFor();
+      case T.WHILE:    return this.parseWhile();
+      case T.DO:       return this.parseDoWhile();
+      case T.MATCH:    return this.parseMatch();
+      case T.RETURN:   return this.parseReturn();
+      case T.BREAK: {
+        this.skip();
+        // break label — label is an IDENT on the same line (no newline between)
+        const blabel = (!this.check(T.NEWLINE) && !this.check(T.EOF) && this.check(T.IDENT)) ? this.skip().value : null;
+        this.skipNewlines();
+        return { type:'BreakStmt', label:blabel, loc:tok };
+      }
+      case T.CONTINUE: {
+        this.skip();
+        const clabel = (!this.check(T.NEWLINE) && !this.check(T.EOF) && this.check(T.IDENT)) ? this.skip().value : null;
+        this.skipNewlines();
+        return { type:'ContinueStmt', label:clabel, loc:tok };
+      }
+      case T.IMPORT:    return this.parseImport();
+      case T.EXPORT:    return this.parseExport();
+      case T.TRY:       return this.parseTryCatch();
+      case T.THROW:     return this.parseThrow();
+      case T.TYPE:      return this.parseTypeDecl();
+      case T.INTERFACE: return this.parseInterfaceDecl();
+      case T.ENUM:      return this.parseEnumDecl();
+      default: {
+        // Keyword tokens that are in the lexer but not valid statement-starters
+        const STMT_KW_HINTS = {
+          [T.CONST]:      { msg: '"const" is not a Flux keyword', hint: 'Did you mean "val"? Flux uses "val" for immutable bindings (not "const")' },
+          [T.TYPEOF]:     { msg: '"typeof" is an expression, not a statement' },
+          [T.INSTANCEOF]: { msg: '"instanceof" is an expression, not a statement' },
+          [T.SATISFIES]:  { msg: '"satisfies" is a type expression, not a statement' },
+        };
+        if (Object.prototype.hasOwnProperty.call(STMT_KW_HINTS, tok.type)) {
+          const info = STMT_KW_HINTS[tok.type];
+          const err  = new ParseError(info.msg, tok);
+          if (info.hint) err.hint = info.hint;
+          throw err;
+        }
+        // Labeled statement: identifier followed by COLON then a loop/while
+        // e.g. `outer: for i in 0..5:` or `loop: while true:`
+        if (tok.type === T.IDENT && this.peek(1).type === T.COLON) {
+          const afterColon = this.peek(2).type;
+          if (afterColon === T.FOR || afterColon === T.WHILE) {
+            const label = this.skip().value; // consume label name
+            this.pos++;                       // consume ':'
+            const body = this.parseOneStmt();
+            return { type:'LabeledStmt', label, body, loc:tok };
+          }
+        }
+        // Check if IDENT looks like a misspelled statement-level keyword.
+        // Only trigger when the next token cannot be an expression-continuation
+        // (dot, call, index, assignment, arrow, etc.) — otherwise the identifier
+        // is a valid expression statement start (e.g. `Fs.writeFileSync(…)`).
+        if (tok.type === T.IDENT) {
+          const next = this.peek(1).type;
+          const isExprContinuation = (
+            next === T.DOT    || next === T.LPAREN  || next === T.LBRACKET ||
+            next === T.EQ     || next === T.PLUSEQ   || next === T.MINUSEQ  ||
+            next === T.STAREQ || next === T.SLASHEQ  || next === T.PERCENTEQ ||
+            next === T.ARROW  || next === T.FATARROW  || next === T.QUESTION  ||
+            next === T.EQEQ   || next === T.NEQ       || next === T.AND       ||
+            next === T.OR     || next === T.PIPE
+          );
+          if (!isExprContinuation) {
+            const hint = suggestKeyword(tok.value);
+            if (hint) {
+              const err = new ParseError(`Unexpected identifier "${tok.value}"`, tok);
+              err.hint  = hint;
+              throw err;
+            }
+          }
+        }
+        return this.parseExprStmt();
+      }
+    }
+  }
+
+  // ── var / val ─────────────────────────────────────────────────
+  parseVarDecl() {
+    const kind = this.peek().type === T.VAR ? 'var' : 'val';
+    const loc  = this.skip();
+
+    if (this.check(T.LBRACE)) {
+      const pattern = this.parseObjectDestructurePattern();
+      this.eat(T.EQ);
+      const init = this.parseExpr();
+      this.skipNewlines();
+      return { type:'DestructureDecl', kind, patternType:'object', pattern, init, loc };
+    }
+
+    if (this.check(T.LBRACKET)) {
+      const pattern = this.parseArrayDestructurePattern();
+      this.eat(T.EQ);
+      const init = this.parseExpr();
+      this.skipNewlines();
+      return { type:'DestructureDecl', kind, patternType:'array', pattern, init, loc };
+    }
+
+    const name = this.eat(T.IDENT).value;
+    let typeAnn = null;
+    if (this.maybe(T.COLON)) typeAnn = this.parseTypeAnn();
+    let init = null;
+    if (this.maybe(T.EQ))   init = this.parseExpr();
+    this.skipNewlines();
+    return { type:'VarDecl', kind, name, typeAnn, init, loc };
+  }
+
+  parseObjectDestructurePattern() {
+    this.eat(T.LBRACE);
+    const props = [];
+    while (!this.check(T.RBRACE) && !this.check(T.EOF)) {
+      let rest = false;
+      if (this.check(T.DOTDOTDOT)) { this.pos++; rest = true; }
+      const key = this.eat(T.IDENT).value;
+      if (rest) { props.push({ key, alias: key, rest: true }); break; }
+      let alias = key;
+      if (this.maybe(T.COLON)) alias = this.eat(T.IDENT).value;
+      let defaultVal = null;
+      if (this.maybe(T.EQ)) defaultVal = this.parseExpr();
+      props.push({ key, alias, defaultVal, rest: false });
+      if (!this.maybe(T.COMMA)) break;
+    }
+    this.eat(T.RBRACE);
+    return props;
+  }
+
+  parseArrayDestructurePattern() {
+    this.eat(T.LBRACKET);
+    const items = [];
+    while (!this.check(T.RBRACKET) && !this.check(T.EOF)) {
+      if (this.check(T.COMMA)) { items.push(null); this.pos++; continue; }
+      let rest = false;
+      if (this.check(T.DOTDOTDOT)) { this.pos++; rest = true; }
+      const name = this.eat(T.IDENT).value;
+      let defaultVal = null;
+      if (this.maybe(T.EQ)) defaultVal = this.parseExpr();
+      items.push({ name, defaultVal, rest });
+      if (rest) break;
+      if (!this.maybe(T.COMMA)) break;
+    }
+    this.eat(T.RBRACKET);
+    return items;
+  }
+
+  // ── Type annotation ────────────────────────────────────────────────────────
+  // Grammar:
+  //   TypeAnn           = IntersectionType (| IntersectionType)*
+  //   IntersectionType  = SingleType (& SingleType)*
+  //   SingleType        = IDENT[<...>][][][?]
+  //                     | [T, T, ...]        (tuple)
+  //                     | { key: T, ... }    (inline object type)
+  //                     | keyof T
+  //                     | typeof IDENT
+  //                     | readonly T
+  //                     | (TypeAnn)          (parenthesised)
+  parseTypeAnn() {
+    let name = this._parseIntersectionType();
+    // Union types: A | B | C
+    while (this.check(T.PIPEB)) {
+      this.pos++;
+      name += ' | ' + this._parseIntersectionType();
+    }
+    return name;
+  }
+
+  _parseIntersectionType() {
+    let name = this._parseSingleType();
+    // Intersection types: A & B & C
+    while (this.check(T.AMPERSAND)) {
+      this.pos++;
+      name += ' & ' + this._parseSingleType();
+    }
+    return name;
+  }
+
+  _parseSingleType() {
+    const tok = this.peek();
+
+    // Tuple type: [String, Int, Bool]
+    if (tok.type === T.LBRACKET) {
+      this.pos++;
+      const parts = [];
+      while (!this.check(T.RBRACKET) && !this.check(T.EOF)) {
+        parts.push(this.parseTypeAnn());
+        if (!this.maybe(T.COMMA)) break;
+      }
+      this.eat(T.RBRACKET);
+      return '[' + parts.join(', ') + ']';
+    }
+
+    // Inline object type: { key: Type; key2?: Type }
+    if (tok.type === T.LBRACE) {
+      this.pos++;
+      const pairs = [];
+      while (!this.check(T.RBRACE) && !this.check(T.EOF)) {
+        let readonly_ = false;
+        if (this.check(T.READONLY)) { this.pos++; readonly_ = true; }
+        // [key: Type] index signature
+        if (this.check(T.LBRACKET)) {
+          this.pos++;
+          const indexName = this.eat(T.IDENT).value;
+          this.eat(T.COLON);
+          const indexKeyType = this.parseTypeAnn();
+          this.eat(T.RBRACKET);
+          this.eat(T.COLON);
+          const indexValType = this.parseTypeAnn();
+          pairs.push(`[${indexName}: ${indexKeyType}]: ${indexValType}`);
+        } else {
+          const key = this.at(T.IDENT, T.STRING) ? this.skip().value : this.eat(T.IDENT).value;
+          let optional = false;
+          if (this.check(T.QUESTION)) { this.pos++; optional = true; }
+          this.eat(T.COLON);
+          const valType = this.parseTypeAnn();
+          const prefix = readonly_ ? 'readonly ' : '';
+          pairs.push(`${prefix}${key}${optional ? '?' : ''}: ${valType}`);
+        }
+        // Allow comma or semicolon between members
+        this.maybe(T.COMMA);
+      }
+      this.eat(T.RBRACE);
+      return '{ ' + pairs.join(', ') + ' }';
+    }
+
+    // Parenthesised type: (A | B)
+    if (tok.type === T.LPAREN) {
+      this.pos++;
+      const inner = this.parseTypeAnn();
+      this.eat(T.RPAREN);
+      return '(' + inner + ')';
+    }
+
+    // keyof T
+    if (tok.type === T.IDENT && tok.value === 'keyof') {
+      this.pos++;
+      return 'keyof ' + this._parseSingleType();
+    }
+
+    // typeof x
+    if (tok.type === T.TYPEOF) {
+      this.pos++;
+      return 'typeof ' + this.eat(T.IDENT).value;
+    }
+
+    // readonly T
+    if (tok.type === T.READONLY) {
+      this.pos++;
+      return 'readonly ' + this._parseSingleType();
+    }
+
+    // infer T (conditional type helper)
+    if (tok.type === T.IDENT && tok.value === 'infer') {
+      this.pos++;
+      return 'infer ' + this.eat(T.IDENT).value;
+    }
+
+    // Function type: fn(T1, T2) -> RetType
+    if (tok.type === T.FN) {
+      this.pos++;
+      const paramTypes = [];
+      if (this.check(T.LPAREN)) {
+        this.pos++;
+        while (!this.check(T.RPAREN) && !this.check(T.EOF)) {
+          // named param: name: Type  OR  just: Type
+          let pt;
+          if (this.check(T.IDENT) && this.peek(1).type === T.COLON) {
+            this.pos += 2; // skip name + colon
+            pt = this.parseTypeAnn();
+          } else {
+            pt = this.parseTypeAnn();
+          }
+          paramTypes.push(pt);
+          if (!this.maybe(T.COMMA)) break;
+        }
+        this.eat(T.RPAREN);
+      }
+      let retType = 'Void';
+      if (this.check(T.ARROW)) {
+        this.pos++;
+        retType = this.parseTypeAnn();
+      }
+      return `fn(${paramTypes.join(', ')}) -> ${retType}`;
+    }
+
+    // Standard named/generic type: String, Array<T>, Map<K,V>
+    let name;
+    if (tok.type === T.IDENT || tok.type === T.CONST || tok.type === T.TYPE) {
+      name = this.skip().value;
+    } else {
+      name = this.eat(T.IDENT).value;
+    }
+
+    // Conditional type: T extends U ? A : B
+    if (this.check(T.EXTENDS)) {
+      this.pos++;
+      const constraint = this._parseSingleType();
+      this.eat(T.QUESTION);
+      const thenType  = this.parseTypeAnn();
+      this.eat(T.COLON);
+      const elseType  = this.parseTypeAnn();
+      return `${name} extends ${constraint} ? ${thenType} : ${elseType}`;
+    }
+
+    // Generics: List<T>, Map<K, V>, Array<String>
+    if (this.check(T.LT)) {
+      this.pos++;
+      const params = [this._parseGenericArg()];
+      while (this.maybe(T.COMMA)) params.push(this._parseGenericArg());
+      this.eat(T.GT);
+      name += '<' + params.join(', ') + '>';
+    }
+
+    // Array suffix: String[]
+    while (this.check(T.LBRACKET) && this.peek(1).type === T.RBRACKET) {
+      this.pos += 2;
+      name += '[]';
+    }
+
+    // Nullable shorthand: String?
+    if (this.check(T.QUESTION) && this.peek(1).type !== T.DOT) {
+      this.pos++;
+      name += '?';
+    }
+
+    return name;
+  }
+
+  // Parse generic argument — supports full type ann + conditional types
+  _parseGenericArg() {
+    return this.parseTypeAnn();
+  }
+
+  // ── Look-ahead: is current position a type annotation followed by ':' ? ──
+  // Used to disambiguate `fn f() -> RetType:` vs `fn f() -> expr`
+  _isTypeAnnBeforeColon() {
+    const peek = (n) => this.tokens[this.pos + n] || { type: T.EOF };
+    let i = 0;
+
+    // Tuple / inline-object / paren — complex: just check if LBRACKET then scan to RBRACKET
+    if (peek(i).type === T.LBRACKET || peek(i).type === T.LBRACE || peek(i).type === T.LPAREN) {
+      let depth = 0;
+      const open  = new Set([T.LBRACKET, T.LBRACE, T.LPAREN, T.LT]);
+      const close = new Set([T.RBRACKET, T.RBRACE, T.RPAREN, T.GT]);
+      while (peek(i).type !== T.EOF) {
+        if (open.has(peek(i).type))  depth++;
+        if (close.has(peek(i).type)) depth--;
+        i++;
+        if (depth === 0) break;
+      }
+      if (peek(i).type === T.QUESTION) i++;
+      // & or | are ok too before :
+      while (peek(i).type === T.PIPEB || peek(i).type === T.AMPERSAND) {
+        i++;
+        if (peek(i).type !== T.IDENT) return false;
+        i++;
+      }
+      return peek(i).type === T.COLON;
+    }
+
+    // keyof / typeof / readonly
+    if (peek(i).type === T.TYPEOF || peek(i).type === T.READONLY ||
+        (peek(i).type === T.IDENT && (peek(i).value === 'keyof' || peek(i).value === 'readonly'))) {
+      i++;
+    }
+
+    if (peek(i).type !== T.IDENT) return false;
+    i++;
+    // Generics <...>
+    if (peek(i).type === T.LT) {
+      i++; let depth = 1;
+      while (peek(i).type !== T.EOF && depth > 0) {
+        if (peek(i).type === T.LT) depth++;
+        if (peek(i).type === T.GT) depth--;
+        i++;
+      }
+    }
+    // Array []
+    while (peek(i).type === T.LBRACKET && peek(i+1).type === T.RBRACKET) i += 2;
+    // Nullable ?
+    if (peek(i).type === T.QUESTION) i++;
+    // Union types
+    while (peek(i).type === T.PIPEB) {
+      i++;
+      if (peek(i).type !== T.IDENT) return false;
+      i++;
+      if (peek(i).type === T.LT) {
+        i++; let depth = 1;
+        while (peek(i).type !== T.EOF && depth > 0) {
+          if (peek(i).type === T.LT) depth++;
+          if (peek(i).type === T.GT) depth--;
+          i++;
+        }
+      }
+      while (peek(i).type === T.LBRACKET && peek(i+1).type === T.RBRACKET) i += 2;
+      if (peek(i).type === T.QUESTION) i++;
+    }
+    return peek(i).type === T.COLON;
+  }
+
+  // ── type Name<T, U> = Variant1(f1, f2) | Variant2 | ... ───────
+  parseTypeDecl() {
+    const loc = this.eat(T.TYPE);
+    const name = this.eat(T.IDENT).value;
+    // Optional generic type parameters: <T>, <T, U>, etc.
+    const typeParams = [];
+    if (this.check(T.LT)) {
+      this.pos++;
+      while (!this.check(T.GT) && !this.check(T.EOF)) {
+        typeParams.push(this.eat(T.IDENT).value);
+        if (!this.maybe(T.COMMA)) break;
+      }
+      this.eat(T.GT);
+    }
+    this.eat(T.EQ);
+
+    const variants = [];
+    while (true) {
+      const vname = this.eat(T.IDENT).value;
+      const fields = [];
+      const fieldTypes = {};
+      if (this.check(T.LPAREN)) {
+        this.eat(T.LPAREN);
+        while (!this.check(T.RPAREN) && !this.check(T.EOF)) {
+          const ftok = this.peek();
+          let fname;
+          if (ftok.type === T.IDENT || ftok.type in T) {
+            fname = this.skip().value;
+          } else {
+            this.err(`Expected field name, got '${ftok.type}'`);
+          }
+          // Support named fields with type: Variant(fieldName: Type)
+          if (this.maybe(T.COLON)) {
+            fieldTypes[fname] = this.parseTypeAnn();
+          }
+          fields.push(fname);
+          if (!this.maybe(T.COMMA)) break;
+        }
+        this.eat(T.RPAREN);
+      }
+      variants.push({ name: vname, fields, fieldTypes });
+      if (!this.check(T.PIPEB)) break;
+      this.pos++;
+    }
+    this.skipNewlines();
+    return { type: 'TypeDecl', name, variants, loc };
+  }
+
+  // ── Lookahead: is COLON followed by a type annotation then NEWLINE/EOF?
+  // Used to distinguish `fn f(): RetType\n  body` from `fn f(): singleExpr`
+  _isColonReturnType() {
+    const saved = this.pos;
+    try {
+      this.pos++; // skip COLON
+      if (!this.at(T.IDENT, T.LBRACKET, T.LBRACE, T.LPAREN, T.FN, T.READONLY, T.TYPEOF)) return false;
+      this.parseTypeAnn();
+      return this.check(T.NEWLINE) || this.check(T.EOF);
+    } catch (_) {
+      return false;
+    } finally {
+      this.pos = saved;
+    }
+  }
+
+  // ── fn ─────────────────────────────────────────────────────────
+  parseFnDecl(isAsync = false) {
+    const loc = this.eat(T.FN);
+    // Allow reserved keywords as method/function names (e.g. `fn new(...)`)
+    const KEYWORD_AS_NAME = new Set([
+      T.NEW, T.DELETE, T.FROM, T.AS, T.DEFAULT, T.IS, T.IN, T.TYPE
+    ]);
+    const name = (this.check(T.IDENT) || KEYWORD_AS_NAME.has(this.peek().type))
+      ? this.skip().value : null;
+    const params = this.parseParamList();
+
+    let retType = null;
+
+    if (this.check(T.ARROW)) {
+      this.pos++; // consume ->
+      if (this._isTypeAnnBeforeColon()) {
+        // Return type annotation: fn foo(x) -> String:
+        retType = this.parseTypeAnn();
+        const body = this.parseBlock();
+        return { type:'FnDecl', name, params, retType, body, inline:false, async:isAsync, loc };
+      } else {
+        // Inline body: fn foo(x) -> expr
+        const body = this.parseExpr();
+        this.skipNewlines();
+        return { type:'FnDecl', name, params, retType:null, body, inline:true, async:isAsync, loc };
+      }
+    }
+
+    if (this.check(T.COLON)) {
+      // Check for `fn f(): RetType\n    body` — colon-style return type annotation
+      if (this._isColonReturnType()) {
+        this.pos++; // eat ':'
+        retType = this.parseTypeAnn();
+        // Parse indented body block
+        if (this.check(T.NEWLINE)) this.pos++;
+        if (this.check(T.INDENT)) {
+          this.pos++;
+          const body = this.parseStmtList(() => this.check(T.DEDENT) || this.check(T.EOF));
+          this.maybe(T.DEDENT);
+          return { type:'FnDecl', name, params, retType, body, inline:false, async:isAsync, loc };
+        }
+        // Single-line body after return type (edge case)
+        const stmt = this.parseOneStmt();
+        return { type:'FnDecl', name, params, retType, body:[stmt], inline:false, async:isAsync, loc };
+      }
+      const body = this.parseBlock();
+      return { type:'FnDecl', name, params, retType:null, body, inline:false, async:isAsync, loc };
+    }
+
+    this.err('Expected -> or : after function signature');
+  }
+
+  // ── async fn ──────────────────────────────────────────────────
+  parseAsyncFn() {
+    this.eat(T.ASYNC);
+    if (!this.check(T.FN)) this.err('Expected fn after async');
+    return this.parseFnDecl(true);
+  }
+
+  parseParamList() {
+    this.eat(T.LPAREN);
+    const params = [];
+    while (!this.check(T.RPAREN) && !this.check(T.EOF)) {
+      let rest = false;
+      if (this.check(T.DOTDOTDOT)) { this.pos++; rest = true; }
+      const name    = this.eat(T.IDENT).value;
+      let   optional = false;
+      let   typeAnn = null;
+      if (!rest && this.check(T.QUESTION)) { this.pos++; optional = true; }
+      if (!rest && this.maybe(T.COLON)) typeAnn = this.parseTypeAnn();
+      let defaultVal = null;
+      if (!rest && this.maybe(T.EQ)) defaultVal = this.parseExpr();
+      params.push({ name, typeAnn, optional, defaultVal, rest });
+      if (rest) break;
+      if (!this.maybe(T.COMMA)) break;
+    }
+    this.eat(T.RPAREN);
+    return params;
+  }
+
+  // ── access modifier helper ─────────────────────────────────────
+  parseAccessModifiers() {
+    const mods = new Set();
+    const modTokens = new Set([
+      T.PRIVATE, T.PUBLIC, T.PROTECTED, T.READONLY,
+      T.STATIC, T.ABSTRACT, T.OVERRIDE
+    ]);
+    while (modTokens.has(this.peek().type)) {
+      mods.add(this.skip().value);
+    }
+    return mods;
+  }
+
+  // ── class ─────────────────────────────────────────────────────
+  parseClassDecl() {
+    const loc = this.eat(T.CLASS);
+    const name = this.eat(T.IDENT).value;
+    let superClass = null;
+    let interfaces = [];
+    // Generic type params: class Foo<T>
+    let typeParams = [];
+    if (this.check(T.LT)) {
+      this.pos++;
+      typeParams.push(this.eat(T.IDENT).value);
+      while (this.maybe(T.COMMA)) typeParams.push(this.eat(T.IDENT).value);
+      this.eat(T.GT);
+    }
+    if (this.maybe(T.EXTENDS)) superClass = this.eat(T.IDENT).value;
+    if (this.maybe(T.IMPLEMENTS)) {
+      interfaces.push(this.eat(T.IDENT).value);
+      while (this.maybe(T.COMMA)) interfaces.push(this.eat(T.IDENT).value);
+    }
+
+    this.eat(T.COLON);
+    if (this.check(T.NEWLINE)) {
+      this.pos++;
+      this.eat(T.INDENT);
+    }
+
+    const fields  = [];
+    const methods = [];
+
+    while (!this.check(T.DEDENT) && !this.check(T.EOF)) {
+      this.skipNewlines();
+      if (this.check(T.DEDENT) || this.check(T.EOF)) break;
+
+      const mods = this.parseAccessModifiers();
+
+      // getter/setter: `get propName():` or `set propName(v):` (no fn keyword)
+      // Also: `fn get propName():` or `fn set propName(v):` (with fn keyword)
+      const isGetSet = this.check(T.IDENT) && (this.peek().value === 'get' || this.peek().value === 'set') && (this.peek(1).type === T.IDENT || this.peek(1).type === T.FN);
+      const isFnGetSet = this.check(T.FN) && (this.peek(1).type === T.IDENT) && (this.peek(1).value === 'get' || this.peek(1).value === 'set') && this.peek(2).type === T.IDENT;
+      if (isGetSet && this.peek(1).type !== T.FN) {
+        const loc = this.peek();
+        const kind = this.skip().value; // 'get' or 'set'
+        const name = this.eat(T.IDENT).value;
+        const params = this.parseParamList();
+        let retType = null;
+        if (this.check(T.ARROW)) { this.pos++; if (this._isTypeAnnBeforeColon()) retType = this.parseTypeAnn(); }
+        else if (this.check(T.COLON) && this._isColonReturnType()) { this.pos++; retType = this.parseTypeAnn(); }
+        const body = this.parseBlock();
+        const m = { type:'FnDecl', name, params, retType, body, inline:false, async:false, modifiers:mods, getset:kind, loc };
+        methods.push(m);
+      } else if (this.check(T.FN)) {
+        const m = this.parseFnDecl();
+        m.modifiers = mods;
+        methods.push(m);
+      } else if (this.check(T.ASYNC)) {
+        const m = this.parseAsyncFn();
+        m.modifiers = mods;
+        methods.push(m);
+      } else if (this.check(T.STATIC) && (this.peek(1).type === T.FN || this.peek(1).type === T.ASYNC)) {
+        this.skip();
+        const m = this.check(T.ASYNC) ? this.parseAsyncFn() : this.parseFnDecl();
+        m.modifiers = mods; m.modifiers.add('static');
+        methods.push(m);
+      } else if (this.check(T.IDENT)) {
+        const fname = this.eat(T.IDENT).value;
+        let optional = false;
+        if (this.check(T.QUESTION)) { this.pos++; optional = true; }
+        this.eat(T.COLON);
+        const ftype = this.parseTypeAnn();
+        this.skipNewlines();
+        fields.push({ name: fname, typeAnn: ftype, optional, modifiers: mods });
+      } else {
+        this.skip();
+      }
+    }
+    this.maybe(T.DEDENT);
+    return { type:'ClassDecl', name, typeParams, superClass, interfaces, fields, methods, loc };
+  }
+
+  // ── interface ──────────────────────────────────────────────────
+  parseInterfaceDecl() {
+    const loc = this.eat(T.INTERFACE);
+    const name = this.eat(T.IDENT).value;
+    // Generic type params: interface Container<T>
+    let typeParams = [];
+    if (this.check(T.LT)) {
+      this.pos++;
+      typeParams.push(this.eat(T.IDENT).value);
+      while (this.maybe(T.COMMA)) typeParams.push(this.eat(T.IDENT).value);
+      this.eat(T.GT);
+    }
+    let superInterfaces = [];
+    if (this.maybe(T.EXTENDS)) {
+      superInterfaces.push(this.eat(T.IDENT).value);
+      while (this.maybe(T.COMMA)) superInterfaces.push(this.eat(T.IDENT).value);
+    }
+
+    this.eat(T.COLON);
+    if (this.check(T.NEWLINE)) {
+      this.pos++;
+      this.eat(T.INDENT);
+    }
+
+    const members = [];
+    while (!this.check(T.DEDENT) && !this.check(T.EOF)) {
+      this.skipNewlines();
+      if (this.check(T.DEDENT) || this.check(T.EOF)) break;
+
+      const mods = this.parseAccessModifiers();
+
+      if (this.check(T.ASYNC)) {
+        this.pos++;
+        this.eat(T.FN);
+        const mname = this.eat(T.IDENT).value;
+        const params = this.parseParamList();
+        let retType = null;
+        if (this.maybe(T.ARROW)) retType = this.parseTypeAnn();
+        this.skipNewlines();
+        members.push({ kind: 'method', name: mname, params, retType, modifiers: mods, isAsync: true });
+      } else if (this.check(T.FN)) {
+        this.eat(T.FN);
+        const mname = this.eat(T.IDENT).value;
+        const params = this.parseParamList();
+        let retType = null;
+        if (this.maybe(T.ARROW)) retType = this.parseTypeAnn();
+        this.skipNewlines();
+        members.push({ kind: 'method', name: mname, params, retType, modifiers: mods, isAsync: false });
+      } else if (this.check(T.IDENT)) {
+        const fname = this.eat(T.IDENT).value;
+        let optional = false;
+        if (this.check(T.QUESTION)) { this.pos++; optional = true; }
+        this.eat(T.COLON);
+        const ftype = this.parseTypeAnn();
+        this.skipNewlines();
+        members.push({ kind: 'field', name: fname, typeAnn: ftype, optional, modifiers: mods });
+      } else {
+        this.skip();
+      }
+    }
+    this.maybe(T.DEDENT);
+    return { type: 'InterfaceDecl', name, typeParams, superInterfaces, members, loc };
+  }
+
+  // ── enum ───────────────────────────────────────────────────────
+  parseEnumDecl() {
+    const loc = this.eat(T.ENUM);
+    const name = this.eat(T.IDENT).value;
+
+    this.eat(T.COLON);
+    if (this.check(T.NEWLINE)) {
+      this.pos++;
+      this.eat(T.INDENT);
+    }
+
+    const members = [];
+    let autoIndex = 0;
+
+    while (!this.check(T.DEDENT) && !this.check(T.EOF)) {
+      this.skipNewlines();
+      if (this.check(T.DEDENT) || this.check(T.EOF)) break;
+
+      const mname = this.eat(T.IDENT).value;
+      let value = null;
+      if (this.maybe(T.EQ)) {
+        value = this.parseExpr();
+        // FIX: after an explicit numeric value, continue auto-index from it
+        // so subsequent auto-assigned members follow the explicit value.
+        if (value.type === 'NumberLit') autoIndex = value.value;
+      } else {
+        value = { type: 'NumberLit', value: autoIndex };
+      }
+      autoIndex++;
+      this.skipNewlines();
+      members.push({ name: mname, value });
+    }
+    this.maybe(T.DEDENT);
+    return { type: 'EnumDecl', name, members, loc };
+  }
+
+  // ── if / else if / else ───────────────────────────────────────
+  parseIf() {
+    const loc = this.eat(T.IF);
+    const cond = this.parseExpr();
+    const then = this.parseBlock();
+    const elseifs = [];
+    let else_ = null;
+
+    this.skipNewlines();
+    while (this.check(T.ELSE)) {
+      this.pos++;
+      if (this.check(T.IF)) {
+        this.pos++;
+        const eic = this.parseExpr();
+        const eib = this.parseBlock();
+        elseifs.push({ cond:eic, body:eib });
+        this.skipNewlines();
+      } else {
+        else_ = this.parseBlock();
+        break;
+      }
+    }
+    return { type:'IfStmt', cond, then, elseifs, else_, loc };
+  }
+
+  // ── for x in iter / for await x in iter ──────────────────────
+  parseFor() {
+    const loc = this.eat(T.FOR);
+    let isAwait = false;
+    if (this.check(T.AWAIT)) { this.pos++; isAwait = true; }
+
+    // Support destructuring in loop variable: for [a, b] in ..., for {x} in ...
+    let varName;
+    let varPattern = null;
+    if (this.check(T.LBRACKET)) {
+      // Array destructuring: for [a, b] in arr
+      this.pos++;
+      const names = [];
+      while (!this.check(T.RBRACKET) && !this.check(T.EOF)) {
+        if (this.check(T.DOTDOTDOT)) { this.pos++; names.push({ rest: true, name: this.eat(T.IDENT).value }); break; }
+        names.push({ name: this.eat(T.IDENT).value });
+        if (!this.maybe(T.COMMA)) break;
+      }
+      this.eat(T.RBRACKET);
+      varName = '__item__';
+      varPattern = { type: 'array', names };
+    } else {
+      varName = this.eat(T.IDENT).value;
+    }
+
+    // Accept both `in` and `of` (of is an identifier in the lexer)
+    if (this.check(T.IN)) {
+      this.pos++;
+    } else if (this.check(T.IDENT) && this.peek().value === 'of') {
+      this.pos++;
+      isAwait = isAwait; // keep flag
+    } else {
+      this.eat(T.IN); // will throw with proper error
+    }
+
+    const iter = this.parseExpr();
+    const body = this.parseBlock();
+    return { type:'ForInStmt', var:varName, varPattern, iter, body, isAwait, loc };
+  }
+
+  // ── while ─────────────────────────────────────────────────────
+  parseWhile() {
+    const loc = this.eat(T.WHILE);
+    const cond = this.parseExpr();
+    const body = this.parseBlock();
+    return { type:'WhileStmt', cond, body, loc };
+  }
+
+  // ── do...while ────────────────────────────────────────────────
+  parseDoWhile() {
+    const loc = this.eat(T.DO);
+    const body = this.parseBlock();
+    this.skipNewlines();
+    this.eat(T.WHILE);
+    const cond = this.parseExpr();
+    this.skipNewlines();
+    return { type:'DoWhileStmt', body, cond, loc };
+  }
+
+  // ── match / when ──────────────────────────────────────────────
+  parseMatch() {
+    const loc = this.eat(T.MATCH);
+    const subject = this.parseExpr();
+    this.eat(T.COLON);
+    if (this.check(T.NEWLINE)) this.pos++;
+    this.eat(T.INDENT);
+
+    const arms = [];
+    while (!this.check(T.DEDENT) && !this.check(T.EOF)) {
+      this.skipNewlines();
+      if (this.check(T.DEDENT) || this.check(T.EOF)) break;
+      this.eat(T.WHEN);
+      const pattern = this.parsePattern();
+
+      let guard = null;
+      if (this.check(T.IF)) {
+        this.pos++;
+        guard = this.parseExpr();
+      }
+
+      if (this.check(T.ARROW)) {
+        this.pos++;
+        const expr = this.parseExpr();
+        this.skipNewlines();
+        arms.push({ pattern, guard, body:[{ type:'ExprStmt', expr }], inline:true });
+      } else if (this.check(T.COLON)) {
+        // peek(1) is the token after ':'. If it's not a NEWLINE, the body is
+        // a single inline expression on the same line → treat as inline (return value).
+        const isInline = this.peek(1).type !== T.NEWLINE;
+        const body = this.parseBlock();
+        arms.push({ pattern, guard, body, inline: isInline && body.length === 1 && body[0].type === 'ExprStmt' });
+      }
+    }
+    this.maybe(T.DEDENT);
+    return { type:'MatchStmt', subject, arms, loc };
+  }
+
+  parsePattern() {
+    if (this.check(T.WILDCARD)) { this.skip(); return { type:'WildcardPat' }; }
+
+    if (this.check(T.IDENT) && this.peek(1).type === T.LPAREN) {
+      const vname = this.eat(T.IDENT).value;
+      this.eat(T.LPAREN);
+      const bindings = [];
+      while (!this.check(T.RPAREN) && !this.check(T.EOF)) {
+        // Allow _ (wildcard) as a binding name inside variant patterns
+        if (this.check(T.WILDCARD)) {
+          bindings.push('_');
+          this.pos++;
+        } else {
+          bindings.push(this.eat(T.IDENT).value);
+        }
+        if (!this.maybe(T.COMMA)) break;
+      }
+      this.eat(T.RPAREN);
+      return { type:'VariantPat', variant:vname, bindings };
+    }
+
+    let left = this.parsePrimary();
+
+    while (this.check(T.DOT)) {
+      this.pos++;
+      const prop = this.skip().value;
+      left = { type:'MemberExpr', obj:left, prop };
+    }
+
+    if (this.check(T.DOTDOT)) {
+      this.pos++;
+      const right = this.parsePrimary();
+      return { type:'RangePat', start:left, end:right };
+    }
+    return { type:'LiteralPat', value:left };
+  }
+
+  // ── return ────────────────────────────────────────────────────
+  parseReturn() {
+    const loc = this.eat(T.RETURN);
+    let value = null;
+    if (!this.at(T.NEWLINE, T.EOF, T.DEDENT))
+      value = this.parseExpr();
+    this.skipNewlines();
+    return { type:'ReturnStmt', value, loc };
+  }
+
+  // ── try / catch / finally ─────────────────────────────────────
+  parseTryCatch() {
+    const loc = this.eat(T.TRY);
+    const tryBody = this.parseBlock();
+
+    let catchParam = null;
+    let catchBody  = null;
+    let finallyBody = null;
+
+    this.skipNewlines();
+    if (this.check(T.CATCH)) {
+      this.pos++;
+      if (this.check(T.LPAREN)) {
+        this.pos++;
+        catchParam = this.eat(T.IDENT).value;
+        // optional type annotation: catch(e: Error)
+        if (this.maybe(T.COLON)) this.parseTypeAnn(); // consume, discard
+        this.eat(T.RPAREN);
+      }
+      catchBody = this.parseBlock();
+      this.skipNewlines();
+    }
+    if (this.check(T.FINALLY)) {
+      this.pos++;
+      finallyBody = this.parseBlock();
+    }
+    return { type:'TryCatchStmt', tryBody, catchParam, catchBody, finallyBody, loc };
+  }
+
+  // ── throw ─────────────────────────────────────────────────────
+  parseThrow() {
+    const loc = this.eat(T.THROW);
+    const value = this.parseExpr();
+    this.skipNewlines();
+    return { type:'ThrowStmt', value, loc };
+  }
+
+  // ── import ────────────────────────────────────────────────────
+  parseImport() {
+    this.eat(T.IMPORT);
+    if (this.check(T.STAR)) {
+      this.pos++;
+      this.eat(T.AS);
+      const namespaceName = this.eat(T.IDENT).value;
+      this.eat(T.FROM);
+      const source = this.eat(T.STRING).value;
+      this.skipNewlines();
+      return { type:'ImportDecl', names:[], defaultName:null, namespaceName, source };
+    }
+    if (this.check(T.IDENT)) {
+      const defaultName = this.eat(T.IDENT).value;
+      this.eat(T.FROM);
+      const source = this.eat(T.STRING).value;
+      this.skipNewlines();
+      return { type:'ImportDecl', names:[], defaultName, source };
+    }
+    const names = [];
+    if (this.maybe(T.LBRACE)) {
+      while (!this.check(T.RBRACE) && !this.check(T.EOF)) {
+        const name = this.eat(T.IDENT).value;
+        let alias = name;
+        if (this.check(T.AS)) { this.pos++; alias = this.eat(T.IDENT).value; }
+        names.push({ name, alias });
+        if (!this.maybe(T.COMMA)) break;
+      }
+      this.eat(T.RBRACE);
+    }
+    this.eat(T.FROM);
+    const source = this.eat(T.STRING).value;
+    this.skipNewlines();
+    return { type:'ImportDecl', names, defaultName:null, source };
+  }
+
+  // ── export ────────────────────────────────────────────────────
+  parseExport() {
+    this.eat(T.EXPORT);
+    if (this.check(T.DEFAULT) && (this.peek(1).type === T.FN || this.peek(1).type === T.ASYNC)) {
+      this.pos++;
+      const decl = this.check(T.ASYNC) ? (this.pos++, this.parseFnDecl(true)) : this.parseFnDecl();
+      return { type:'ExportDecl', isDefault:true, decl };
+    }
+    if (this.check(T.DEFAULT)) {
+      this.pos++;
+      const value = this.parseExpr();
+      this.skipNewlines();
+      return { type:'ExportDecl', isDefault:true, decl:value };
+    }
+    if (this.check(T.ASYNC)) {
+      this.pos++;
+      if (!this.check(T.FN)) this.err('Expected fn after async');
+      const decl = this.parseFnDecl(true);
+      return { type:'ExportDecl', isDefault:false, decl };
+    }
+    const decl = this.parseOneStmt();
+    return { type:'ExportDecl', isDefault:false, decl };
+  }
+
+  // ── expression statement ──────────────────────────────────────
+  parseExprStmt() {
+    const expr = this.parseExpr();
+    this.skipNewlines();
+    return { type:'ExprStmt', expr };
+  }
+
+  // ── Expressions ───────────────────────────────────────────────
+  parseExpr() { return this.parsePipe(); }
+
+  parsePipe() {
+    let left = this.parseAssign();
+    while (true) {
+      if (this.check(T.PIPE)) {
+        this.pos++;
+        const right = this.parseAssign();
+        left = { type:'PipeExpr', left, right };
+      } else if (this.check(T.NEWLINE)) {
+        // Multi-line pipe: look past NEWLINEs to see if next meaningful token is |>
+        let i = 1;
+        while (this.peek(i).type === T.NEWLINE) i++;
+        if (this.peek(i).type === T.PIPE) {
+          // Consume all pending NEWLINEs then the PIPE token
+          while (this.check(T.NEWLINE)) this.pos++;
+          this.pos++; // consume |>
+          const right = this.parseAssign();
+          left = { type:'PipeExpr', left, right };
+        } else {
+          break;
+        }
+      } else {
+        break;
+      }
+    }
+    return left;
+  }
+
+  parseAssign() {
+    const left = this.parseTernary();
+    const ASSIGN = {
+      [T.EQ]:'=', [T.PLUSEQ]:'+=', [T.MINUSEQ]:'-=',
+      [T.STAREQ]:'*=', [T.SLASHEQ]:'/=', [T.PERCENTEQ]:'%='
+    };
+    const op = ASSIGN[this.peek().type];
+    if (op) { this.pos++; return { type:'AssignExpr', target:left, op, value:this.parseAssign() }; }
+    return left;
+  }
+
+  parseTernary() {
+    const cond = this.parseNullish();
+    if (this.maybe(T.QUESTION)) {
+      const then  = this.parseNullish();
+      this.eat(T.COLON);
+      const else_ = this.parseTernary();
+      return { type:'TernaryExpr', cond, then, else_ };
+    }
+    return cond;
+  }
+
+  parseNullish() {
+    let l = this.parseOr();
+    while (this.check(T.NULLISH)) {
+      this.pos++;
+      const r = this.parseOr();
+      l = { type:'BinaryExpr', op:'??', left:l, right:r };
+    }
+    return l;
+  }
+
+  parseOr() {
+    let l = this.parseAnd();
+    while (this.check(T.OR) || this.check(T.OROR)) { this.pos++; const r = this.parseAnd(); l = { type:'BinaryExpr', op:'||', left:l, right:r }; }
+    return l;
+  }
+
+  parseAnd() {
+    let l = this.parseBitOr();
+    while (this.check(T.AND) || this.check(T.ANDAND)) { this.pos++; const r = this.parseBitOr(); l = { type:'BinaryExpr', op:'&&', left:l, right:r }; }
+    return l;
+  }
+
+  parseBitOr() {
+    let l = this.parseBitXor();
+    while (this.check(T.PIPEB)) { this.pos++; const r = this.parseBitXor(); l = { type:'BinaryExpr', op:'|', left:l, right:r }; }
+    return l;
+  }
+
+  parseBitXor() {
+    let l = this.parseBitAnd();
+    while (this.check(T.CARET)) { this.pos++; const r = this.parseBitAnd(); l = { type:'BinaryExpr', op:'^', left:l, right:r }; }
+    return l;
+  }
+
+  parseBitAnd() {
+    let l = this.parseEq();
+    while (this.check(T.AMPERSAND)) { this.pos++; const r = this.parseEq(); l = { type:'BinaryExpr', op:'&', left:l, right:r }; }
+    return l;
+  }
+
+  parseEq() {
+    let l = this.parseRel();
+    while (this.at(T.EQEQ, T.NEQ, T.EQEQEQ, T.NEQEQ)) { const op = this.skip().value; const r = this.parseRel(); l = { type:'BinaryExpr', op, left:l, right:r }; }
+    return l;
+  }
+
+  parseRel() {
+    let l = this.parseShift();
+    while (this.at(T.LT, T.LTE, T.GT, T.GTE) || this.check(T.IN)) {
+      const op = this.skip().value;
+      const r = this.parseShift();
+      l = { type:'BinaryExpr', op, left:l, right:r };
+    }
+    return l;
+  }
+
+  parseShift() {
+    let l = this.parseRange();
+    while (this.at(T.LSHIFT, T.RSHIFT)) { const op = this.skip().value; const r = this.parseRange(); l = { type:'BinaryExpr', op, left:l, right:r }; }
+    return l;
+  }
+
+  parseRange() {
+    const l = this.parseAdd();
+    if (this.check(T.DOTDOT)) { this.pos++; const r = this.parseAdd(); return { type:'RangeExpr', start:l, end:r }; }
+    return l;
+  }
+
+  parseAdd() {
+    let l = this.parseMul();
+    while (this.at(T.PLUS, T.MINUS)) { const op = this.skip().value; const r = this.parseMul(); l = { type:'BinaryExpr', op, left:l, right:r }; }
+    return l;
+  }
+
+  parseMul() {
+    let l = this.parsePow();
+    while (this.at(T.STAR, T.SLASH, T.PERCENT)) { const op = this.skip().value; const r = this.parsePow(); l = { type:'BinaryExpr', op, left:l, right:r }; }
+    return l;
+  }
+
+  parsePow() {
+    const l = this.parseUnary();
+    if (this.check(T.STARSTAR)) { this.pos++; return { type:'BinaryExpr', op:'**', left:l, right:this.parsePow() }; }
+    return l;
+  }
+
+  parseUnary() {
+    if (this.check(T.MINUS))       { this.pos++; return { type:'UnaryExpr',  op:'-',  operand:this.parseUnary() }; }
+    if (this.check(T.NOT))         { this.pos++; return { type:'UnaryExpr',  op:'!',  operand:this.parseUnary() }; }
+    if (this.check(T.BANG))        { this.pos++; return { type:'UnaryExpr',  op:'!',  operand:this.parseUnary() }; }
+    if (this.check(T.TILDE))       { this.pos++; return { type:'UnaryExpr',  op:'~',  operand:this.parseUnary() }; }
+    if (this.check(T.PLUSPLUS))    { this.pos++; return { type:'UpdateExpr', op:'++', prefix:true, operand:this.parseUnary() }; }
+    if (this.check(T.MINUSMINUS))  { this.pos++; return { type:'UpdateExpr', op:'--', prefix:true, operand:this.parseUnary() }; }
+    if (this.check(T.AWAIT))       { this.pos++; return { type:'AwaitExpr',            operand:this.parseUnary() }; }
+    if (this.check(T.TYPEOF))      { this.pos++; return { type:'TypeofExpr',           operand:this.parseUnary() }; }
+    return this.parseLambdaOrPostfix();
+  }
+
+  parseLambdaOrPostfix() {
+    const saved = this.pos;
+    // Single-param lambda: x -> expr  OR  x ->\n    block  OR  _ -> expr
+    if (this.check(T.IDENT) || this.check(T.WILDCARD)) {
+      const name = this.skip().value ?? '_';
+      if (this.check(T.ARROW)) {
+        this.pos++;
+        if (this.check(T.NEWLINE)) {
+          // Multiline block body: x ->\n    stmts
+          const body = this.parseIndentedBlock();
+          return { type:'LambdaExpr', params:[{ name }], body, block:true };
+        }
+        const body = this.parseExpr();
+        return { type:'LambdaExpr', params:[{ name }], body };
+      }
+      this.pos = saved;
+    }
+    return this.parsePostfix();
+  }
+
+  parsePostfix() {
+    let expr = this.parsePrimary();
+    loop: while (true) {
+      if (this.check(T.PLUSPLUS)) {
+        this.pos++;
+        expr = { type:'UpdateExpr', op:'++', prefix:false, operand:expr };
+      } else if (this.check(T.MINUSMINUS)) {
+        this.pos++;
+        expr = { type:'UpdateExpr', op:'--', prefix:false, operand:expr };
+      } else if (this.check(T.DOT)) {
+        this.pos++;
+        const propTok = this.peek();
+        if (propTok.type !== T.IDENT && !(propTok.type in T)) this.err(`Expected property name, got '${propTok.type}'`);
+        const prop = this.skip().value;
+        expr = { type:'MemberExpr', obj:expr, prop };
+      } else if (this.check(T.QUESTIONDOT)) {
+        this.pos++;
+        if (this.check(T.LPAREN)) {
+          const args = this.parseArgList();
+          expr = { type:'OptCallExpr', callee:expr, args };
+        } else if (this.check(T.LBRACKET)) {
+          this.pos++;
+          const idx = this.parseExpr();
+          this.eat(T.RBRACKET);
+          expr = { type:'OptIndexExpr', obj:expr, idx };
+        } else {
+          const propTok = this.peek();
+          if (propTok.type !== T.IDENT && !(propTok.type in T)) this.err(`Expected property name, got '${propTok.type}'`);
+          const prop = this.skip().value;
+          expr = { type:'OptMemberExpr', obj:expr, prop };
+        }
+      } else if (this.check(T.INSTANCEOF)) {
+        this.pos++;
+        const right = this.eat(T.IDENT).value;
+        expr = { type:'BinaryExpr', op:'instanceof', left:expr, right:{ type:'Identifier', name:right } };
+      } else if (this.check(T.AS)) {
+        this.pos++;
+        if (this.check(T.CONST)) {
+          this.pos++;
+          expr = { type:'AsConstExpr', expr };
+        } else {
+          const castType = this.parseTypeAnn();
+          expr = { type:'CastExpr', expr, castType };
+        }
+      } else if (this.check(T.SATISFIES)) {
+        this.pos++;
+        const satType = this.parseTypeAnn();
+        expr = { type:'SatisfiesExpr', expr, satType };
+      } else if (this.check(T.IS)) {
+        this.pos++;
+        const isType = this.parseTypeAnn();
+        expr = { type:'IsExpr', expr, isType };
+      } else if (this.check(T.BANG)) {
+        this.pos++;
+        expr = { type:'NonNullExpr', expr };
+      } else if (this.check(T.LBRACKET)) {
+        this.pos++;
+        const idx = this.parseExpr();
+        this.eat(T.RBRACKET);
+        expr = { type:'IndexExpr', obj:expr, idx };
+      } else if (this.check(T.LPAREN)) {
+        const args = this.parseArgList();
+        if (this.check(T.ARROW)) {
+          this.pos++;
+          const body  = this.parseExpr();
+          const params = args.map(a => ({ name: a.type === 'Identifier' ? a.name : '_' }));
+          return { type:'LambdaExpr', params, body };
+        }
+        expr = { type:'CallExpr', callee:expr, args };
+      } else {
+        break loop;
+      }
+    }
+    return expr;
+  }
+
+  parseArgList() {
+    this.eat(T.LPAREN);
+    const args = [];
+    while (!this.check(T.RPAREN) && !this.check(T.EOF)) {
+      if (this.check(T.DOTDOTDOT)) {
+        this.pos++;
+        args.push({ type:'SpreadExpr', expr:this.parseExpr() });
+      } else {
+        args.push(this.parseExpr());
+      }
+      if (!this.maybe(T.COMMA)) break;
+    }
+    this.eat(T.RPAREN);
+    return args;
+  }
+
+  parsePrimary() {
+    const tok = this.peek();
+    switch (tok.type) {
+      case T.NUMBER:   return (this.pos++, { type:'NumberLit', value:tok.value, loc:tok });
+      case T.BOOL:     return (this.pos++, { type:'BoolLit',   value:tok.value, loc:tok });
+      case T.NULL:     return (this.pos++, { type:'NullLit',   loc:tok });
+      case T.SELF:     return (this.pos++, { type:'SelfExpr',  loc:tok });
+      case T.WILDCARD: return (this.pos++, { type:'Identifier', name:'_', loc:tok });
+      case T.IDENT:    return (this.pos++, { type:'Identifier', name:tok.value, loc:tok });
+
+      case T.STRING:
+        this.pos++;
+        if (tok.value && tok.value.template)
+          return { type:'TemplateLit', parts:tok.value.parts, loc:tok };
+        return { type:'StringLit', value:tok.value, loc:tok };
+
+      case T.REGEX:
+        return (this.pos++, { type:'RegexLit', value:tok.value, loc:tok });
+
+      case T.NEW: {
+        this.pos++;
+        const callee = this.eat(T.IDENT).value;
+        const args   = this.parseArgList();
+        return { type:'NewExpr', callee, args };
+      }
+
+      case T.FN: {
+        this.pos++;
+        const params = this.parseParamList();
+        if (this.check(T.ARROW)) {
+          this.pos++;
+          // Check if it's a return type annotation or inline body
+          if (this._isTypeAnnBeforeColon()) {
+            const retType = this.parseTypeAnn();
+            const body = this.parseBlock();
+            return { type:'FnDecl', name:null, params, retType, body, inline:false, async:false, loc:tok };
+          }
+          const body = this.parseExpr();
+          return { type:'FnDecl', name:null, params, retType:null, body, inline:true, async:false, loc:tok };
+        }
+        if (this.check(T.COLON)) {
+          const body = this.parseBlock();
+          return { type:'FnDecl', name:null, params, retType:null, body, inline:false, async:false, loc:tok };
+        }
+        this.err('Expected -> or : after anonymous fn');
+      }
+
+      // match used as an expression: val result = match x: when ...
+      // CodeGenerator wraps it in an IIFE so it yields a value.
+      case T.MATCH:
+        return this.parseMatch();
+
+      case T.LPAREN: {
+        this.pos++;
+        if (this.check(T.RPAREN)) {
+          this.pos++;
+          if (this.check(T.ARROW)) {
+            this.pos++;
+            if (this.check(T.NEWLINE)) {
+              const body = this.parseIndentedBlock();
+              return { type:'LambdaExpr', params:[], body, block:true };
+            }
+            const body = this.parseExpr();
+            return { type:'LambdaExpr', params:[], body };
+          }
+          return { type:'NullLit' };
+        }
+        const first = this.parseExpr();
+        if (this.check(T.RPAREN)) {
+          this.pos++;
+          if (this.check(T.ARROW)) {
+            this.pos++;
+            if (this.check(T.NEWLINE)) {
+              const body = this.parseIndentedBlock();
+              const name = first.type === 'Identifier' ? first.name : '_';
+              return { type:'LambdaExpr', params:[{ name }], body, block:true };
+            }
+            const body = this.parseExpr();
+            const name = first.type === 'Identifier' ? first.name : '_';
+            return { type:'LambdaExpr', params:[{ name }], body };
+          }
+          return first;
+        }
+        const items = [first];
+        while (this.maybe(T.COMMA)) items.push(this.parseExpr());
+        this.eat(T.RPAREN);
+        if (this.check(T.ARROW)) {
+          this.pos++;
+          const params = items.map(i => ({ name: i.type === 'Identifier' ? i.name : '_' }));
+          if (this.check(T.NEWLINE)) {
+            const body = this.parseIndentedBlock();
+            return { type:'LambdaExpr', params, body, block:true };
+          }
+          const body = this.parseExpr();
+          return { type:'LambdaExpr', params, body };
+        }
+        // FIX: (a, b, c) without -> is not a lambda — if multiple items, raise a
+        // parse error instead of silently discarding items[1..n].
+        if (items.length > 1)
+          this.err(`Unexpected comma in expression — did you mean a lambda? Write (${items.map((_,k)=>'p'+k).join(', ')}) -> expr`);
+        return items[0];
+      }
+
+      case T.LBRACKET: {
+        this.pos++;
+        const items = [];
+        while (!this.check(T.RBRACKET) && !this.check(T.EOF)) {
+          if (this.check(T.DOTDOTDOT)) {
+            this.pos++;
+            items.push({ type:'SpreadExpr', expr:this.parseExpr() });
+          } else {
+            items.push(this.parseExpr());
+          }
+          if (!this.maybe(T.COMMA)) break;
+        }
+        this.eat(T.RBRACKET);
+        return { type:'ArrayExpr', items };
+      }
+
+      case T.LBRACE: {
+        this.pos++;
+        const pairs = [];
+        while (!this.check(T.RBRACE) && !this.check(T.EOF)) {
+          if (this.check(T.DOTDOTDOT)) {
+            this.pos++;
+            pairs.push({ spread: true, value: this.parseExpr() });
+            if (!this.maybe(T.COMMA)) break;
+            continue;
+          }
+          // Computed property key: { [expr]: value }
+          if (this.check(T.LBRACKET)) {
+            this.pos++;
+            const keyExpr = this.parseExpr();
+            this.eat(T.RBRACKET);
+            this.eat(T.COLON);
+            const val = this.parseExpr();
+            pairs.push({ computed: true, keyExpr, value: val });
+            if (!this.maybe(T.COMMA)) break;
+            continue;
+          }
+          // Allow reserved words as property keys (valid JS — e.g. { type: x, var: y })
+          const key = this.check(T.STRING) ? this.eat(T.STRING).value
+                    : this.check(T.IDENT)  ? this.eat(T.IDENT).value
+                    : this.skip().value;
+          if (!this.check(T.COLON)) {
+            pairs.push({ key, value:{ type:'Identifier', name:key } });
+          } else {
+            this.eat(T.COLON);
+            const val = this.parseExpr();
+            pairs.push({ key, value:val });
+          }
+          if (!this.maybe(T.COMMA)) break;
+        }
+        this.eat(T.RBRACE);
+        return { type:'ObjectExpr', pairs };
+      }
+
+      default:
+        this.err(`Unexpected token: ${tok.type} (${JSON.stringify(tok.value)})`);
+    }
+  }
+}
+
+module.exports = { Parser, ParseError };