@ozsarman/clarityjs 0.6.0

package/src/parser.js

@@ -0,0 +1,1108 @@
+/**
+ * Clarity.js Parser — AST Builder
+ *
+ * Converts a token stream into an Abstract Syntax Tree.
+ * Every node carries source location for LLM-friendly error messages.
+ *
+ * Grammar (simplified):
+ *
+ *   Program        → (Import | Component)*
+ *   Import         → 'import' IdentList 'from' String
+ *   Component      → 'component' Ident Params '{' Block '}'
+ *   Block          → (StateDecl | EffectDecl | ComputedDecl | RenderBlock | ServerBlock)*
+ *   StateDecl      → 'state' Ident '=' Expr
+ *   ComputedDecl   → 'computed' Ident '=' Expr
+ *   EffectDecl     → 'effect' 'on' '(' IdentList ')' '{' Stmts '}'
+ *   RenderBlock    → 'render' '{' JSXElement '}'
+ *   ServerBlock    → 'server' '{' Stmts '}'
+ *   JSXElement     → '<' TagName Attrs '>' Children '</' TagName '>'
+ *                  | '<' TagName Attrs '/>'
+ *
+ * Author: Claude (Anthropic)
+ */
+
+import { T, Lexer } from './lexer.js';
+
+// ─── ParseError ───────────────────────────────────────────────────────────────
+export class ParseError extends Error {
+  constructor(message, token, source = '') {
+    const line = token?.line ?? '?';
+    const col  = token?.col  ?? '?';
+    const lines = source.split('\n');
+    const snippet = lines[line - 1] ?? '';
+    const pointer = ' '.repeat(Math.max(0, col - 1)) + '^';
+
+    super(
+      `[Clarity Parser] ${message}\n` +
+      `  → Line ${line}, Col ${col}\n` +
+      `  ${snippet}\n` +
+      `  ${pointer}\n` +
+      `  Got: ${token ? `${token.type}(${JSON.stringify(token.value)})` : 'EOF'}\n` +
+      `  LLM-hint: Check syntax near this position. Every block must be opened and closed.`
+    );
+    this.name = 'ParseError';
+    this.token = token;
+    this.line  = line;
+    this.col   = col;
+  }
+}
+
+// ─── AST Node Factories ───────────────────────────────────────────────────────
+// Each factory produces a plain object with a 'type' field.
+// Plain objects = easy to inspect, serialize, and reason about.
+
+const node = {
+  program:      (imports, components, stores, loc) => ({ type: 'Program', imports, components, stores, loc }),
+  import:       (names, source, loc)       => ({ type: 'Import', names, source, loc }),
+  component:    (name, params, body, loc, typeParams) => ({ type: 'Component', name, params, body, loc, typeParams: typeParams ?? [] }),
+  stateDecl:    (name, init, loc)          => ({ type: 'StateDecl', name, init, loc }),
+  computedDecl: (name, expr, loc)          => ({ type: 'ComputedDecl', name, expr, loc }),
+  effectDecl:   (deps, body, loc)          => ({ type: 'EffectDecl', deps, body, loc }),
+  renderBlock:    (root, loc)               => ({ type: 'RenderBlock', root, loc }),
+  aiDecl:         (capability, targets, loc) => ({ type: 'AIDecl', capability, targets, loc }),
+  beforeMountBlock: (body, loc)             => ({ type: 'BeforeMountBlock', body, loc }),
+  onMountBlock:   (body, loc)               => ({ type: 'OnMountBlock', body, loc }),
+  onCleanupBlock: (body, loc)               => ({ type: 'OnCleanupBlock', body, loc }),
+  actionDecl:     (name, params, body, loc) => ({ type: 'ActionDecl', name, params, body, loc }),
+  serverBlock:    (data, loc)               => ({ type: 'ServerBlock', data, loc }),
+  serverDataDecl: (name, init, loc)         => ({ type: 'ServerDataDecl', name, init, loc }),
+  awaitExpr:      (expr, loc)               => ({ type: 'AwaitExpr', expr, loc }),
+
+  // JSX nodes
+  jsxElement:   (tag, attrs, children, selfClose, loc) => ({ type: 'JSXElement', tag, attrs, children, selfClose, loc }),
+  jsxText:      (value, loc)              => ({ type: 'JSXText', value, loc }),
+  jsxExpr:      (expr, loc)               => ({ type: 'JSXExpr', expr, loc }),
+
+  // Attribute nodes
+  attr:         (name, value, loc)               => ({ type: 'Attr', name, value, loc }),
+  eventAttr:    (event, modifiers, handler, loc) => ({ type: 'EventAttr', event, modifiers, handler, loc }),
+  bindAttr:     (prop, signal, loc)              => ({ type: 'BindAttr', prop, signal, loc }),
+
+  // Expression nodes
+  literal:      (value, loc)              => ({ type: 'Literal', value, loc }),
+  ident:        (name, loc)               => ({ type: 'Ident', name, loc }),
+  binary:       (op, left, right, loc)    => ({ type: 'BinaryExpr', op, left, right, loc }),
+  unary:        (op, expr, loc)           => ({ type: 'UnaryExpr', op, expr, loc }),
+  update:       (op, expr, prefix, loc)   => ({ type: 'UpdateExpr', op, expr, prefix, loc }),
+  ternary:      (cond, then, else_, loc)  => ({ type: 'TernaryExpr', cond, then, else: else_, loc }),
+  assign:       (target, op, value, loc)  => ({ type: 'AssignExpr', target, op, value, loc }),
+  member:       (obj, prop, computed, loc)=> ({ type: 'MemberExpr', obj, prop, computed, loc }),
+  call:         (callee, args, loc)       => ({ type: 'CallExpr', callee, args, loc }),
+  arrow:        (params, body, loc)       => ({ type: 'ArrowFn', params, body, loc }),
+  array:        (elements, loc)           => ({ type: 'ArrayExpr', elements, loc }),
+  object:       (properties, loc)         => ({ type: 'ObjectExpr', properties, loc }),
+  prop:         (key, value, loc)         => ({ type: 'ObjectProp', key, value, loc }),
+  template:     (parts, loc)              => ({ type: 'TemplateLiteral', parts, loc }),
+
+  // Statement nodes
+  exprStmt:     (expr, loc)              => ({ type: 'ExprStmt', expr, loc }),
+  returnStmt:   (value, loc)             => ({ type: 'ReturnStmt', value, loc }),
+  ifStmt:       (cond, then, else_, loc) => ({ type: 'IfStmt', cond, then, else: else_, loc }),
+  block:        (body, loc)              => ({ type: 'Block', body, loc }),
+  varDecl:      (kind, name, init, loc)  => ({ type: 'VarDecl', kind, name, init, loc }),
+};
+
+// ─── Parser ───────────────────────────────────────────────────────────────────
+export class Parser {
+  constructor(tokens, source = '') {
+    this.tokens = tokens.filter(t => t.type !== T.NEWLINE); // skip newlines for now
+    this.source = source;
+    this.pos    = 0;
+    this._inAttrValue = false; // prevents comma from being parsed as CommaExpr in lists
+  }
+
+  // ── Public ──
+  parse() {
+    const loc = this._loc();
+    const imports    = [];
+    const components = [];
+    const stores     = [];
+
+    while (!this._atEnd()) {
+      if (this._check(T.IMPORT)) {
+        imports.push(this._parseImport());
+      } else if (this._check(T.COMPONENT)) {
+        components.push(this._parseComponent());
+      } else if (this._check(T.IDENT) && this._current().value === 'store') {
+        const storeLoc = this._loc();
+        this._advance(); // consume 'store'
+        const name = this._eat(T.IDENT).value;
+        this._eat(T.ASSIGN);
+        const init = this._parseExpr();
+        stores.push({ type: 'StoreDecl', name, init, loc: storeLoc });
+      } else if (this._check(T.EOF)) {
+        break;
+      } else {
+        this._advance(); // skip unknown top-level tokens
+      }
+    }
+
+    return node.program(imports, components, stores, loc);
+  }
+
+  // ── Top-Level Parsers ──
+  _parseImport() {
+    const loc = this._loc();
+    this._eat(T.IMPORT);
+
+    const names = [];
+    if (this._check(T.LBRACE)) {
+      this._eat(T.LBRACE);
+      while (!this._check(T.RBRACE) && !this._atEnd()) {
+        names.push(this._eat(T.IDENT).value);
+        if (this._check(T.COMMA)) this._advance();
+      }
+      this._eat(T.RBRACE);
+    } else {
+      names.push(this._eat(T.IDENT).value);
+    }
+
+    this._eat(T.FROM);
+    const source = this._eat(T.STRING).value;
+    return node.import(names, source, loc);
+  }
+
+  _parseComponent() {
+    const loc = this._loc();
+    this._eat(T.COMPONENT);
+    const name = this._eat(T.IDENT).value;
+
+    // ── Generic type parameters: component List<T> or component Map<K, V extends string>
+    // The lexer converts <T into JSX_OPEN(T), so we detect that here.
+    // Type params are purely for type-checking (TypeScript/Volar); the JS codegen ignores them.
+    const typeParams = [];
+    if (this._check(T.JSX_OPEN)) {
+      // Grab the first type param from the JSX_OPEN token value (e.g. "T" from <T)
+      const firstParam = this._advance().value; // JSX_OPEN value = tag name = first type ident
+      if (firstParam) {
+        typeParams.push(this._parseTypeParam(firstParam));
+      }
+      // Parse additional params: , U, , V extends Base
+      while (this._check(T.COMMA)) {
+        this._advance();
+        if (this._check(T.IDENT)) {
+          const paramName = this._advance().value;
+          typeParams.push(this._parseTypeParam(paramName));
+        }
+      }
+      // Consume the closing > (GT token)
+      if (this._check(T.GT)) this._advance();
+      // Also handle JSX_SELF_CLOSE (/>) which shouldn't appear here but guard anyway
+    }
+
+    // Parse params: (name: Type, ...)
+    const params = [];
+    this._eat(T.LPAREN);
+    while (!this._check(T.RPAREN) && !this._atEnd()) {
+      const paramName = this._eat(T.IDENT).value;
+      let paramType = null;
+      if (this._check(T.COLON)) {
+        this._advance();
+        paramType = this._eat(T.IDENT).value;
+      }
+      params.push({ name: paramName, type: paramType });
+      if (this._check(T.COMMA)) this._advance();
+    }
+    this._eat(T.RPAREN);
+
+    const body = this._parseComponentBody();
+    return node.component(name, params, body, loc, typeParams);
+  }
+
+  /**
+   * Parse a single type parameter from the given name string.
+   * Handles:
+   *   T                → { name: 'T', constraint: null }
+   *   T extends string → { name: 'T', constraint: 'string' }
+   *
+   * The `extends` keyword appears as T.IDENT with value 'extends' in this context.
+   */
+  _parseTypeParam(paramName) {
+    let constraint = null;
+    // Check for "extends BaseType" — appears as IDENT('extends') IDENT(type)
+    if (this._check(T.IDENT) && this._current().value === 'extends') {
+      this._advance(); // consume 'extends'
+      const parts = [];
+      // Read the constraint type (may be dotted: string, SomeInterface, React.FC)
+      if (this._check(T.IDENT)) {
+        parts.push(this._advance().value);
+        while (this._check(T.DOT) && this._peekTypeIsIdent()) {
+          this._advance(); // .
+          parts.push(this._advance().value);
+        }
+      }
+      constraint = parts.join('.') || null;
+    }
+    return { name: paramName, constraint };
+  }
+
+  _peekTypeIsIdent() {
+    return this._pos + 1 < this._tokens.length && this._tokens[this._pos + 1]?.type === T.IDENT;
+  }
+
+  _parseComponentBody() {
+    this._eat(T.LBRACE);
+    const body = [];
+
+    while (!this._check(T.RBRACE) && !this._atEnd()) {
+      if (this._check(T.STATE)) {
+        body.push(this._parseStateDecl());
+      } else if (this._check(T.COMPUTED)) {
+        body.push(this._parseComputedDecl());
+      } else if (this._check(T.EFFECT)) {
+        body.push(this._parseEffectDecl());
+      } else if (this._check(T.RENDER)) {
+        body.push(this._parseRenderBlock());
+      } else if (this._check(T.SERVER)) {
+        body.push(this._parseServerBlock());
+      } else if (this._check(T.AI)) {
+        body.push(this._parseAIDecl());
+      } else if (this._check(T.BEFORE_MOUNT)) {
+        body.push(this._parseBeforeMountBlock());
+      } else if (this._check(T.ON_MOUNT)) {
+        body.push(this._parseOnMountBlock());
+      } else if (this._check(T.ON_CLEANUP)) {
+        body.push(this._parseOnCleanupBlock());
+      } else if (this._check(T.ACTION)) {
+        body.push(this._parseActionDecl());
+      } else if (this._check(T.IDENT) && this._current().value === 'ref') {
+        const loc = this._loc();
+        this._advance(); // consume 'ref'
+        const name = this._eat(T.IDENT).value;
+        body.push({ type: 'RefDecl', name, loc });
+      } else if (this._check(T.IDENT) && this._current().value === 'async') {
+        const loc = this._loc();
+        this._advance(); // consume 'async'
+        this._eat(T.STATE); // expect 'state'
+        const name = this._eat(T.IDENT).value;
+        this._eat(T.ASSIGN);
+        const init = this._parseExpr();
+        body.push({ type: 'AsyncStateDecl', name, init, loc });
+      } else if (this._check(T.STYLE_BLOCK)) {
+        // CSS scoping block: style { ... }
+        // The lexer already consumed the braces and extracted raw CSS as token value.
+        const loc = this._loc();
+        const tok = this._advance();
+        body.push({ type: 'StyleBlock', css: tok.value, loc });
+      } else {
+        // Skip unknown tokens inside component body
+        this._advance();
+      }
+    }
+
+    this._eat(T.RBRACE);
+    return body;
+  }
+
+  _parseStateDecl() {
+    const loc = this._loc();
+    this._eat(T.STATE);
+    const name = this._eat(T.IDENT).value;
+    this._eat(T.ASSIGN);
+    const init = this._parseExpr();
+    return node.stateDecl(name, init, loc);
+  }
+
+  _parseComputedDecl() {
+    const loc = this._loc();
+    this._eat(T.COMPUTED);
+    const name = this._eat(T.IDENT).value;
+    this._eat(T.ASSIGN);
+    const expr = this._parseExpr();
+    return node.computedDecl(name, expr, loc);
+  }
+
+  _parseEffectDecl() {
+    const loc = this._loc();
+    this._eat(T.EFFECT);
+    this._eat(T.ON);
+    this._eat(T.LPAREN);
+
+    const deps = [];
+    while (!this._check(T.RPAREN) && !this._atEnd()) {
+      deps.push(this._eat(T.IDENT).value);
+      if (this._check(T.COMMA)) this._advance();
+    }
+    this._eat(T.RPAREN);
+
+    const body = this._parseBlock();
+    return node.effectDecl(deps, body, loc);
+  }
+
+  _parseRenderBlock() {
+    const loc = this._loc();
+    this._eat(T.RENDER);
+    this._eat(T.LBRACE);
+    const root = this._parseJSXElement();
+    this._eat(T.RBRACE);
+    return node.renderBlock(root, loc);
+  }
+
+  _parseServerBlock() {
+    const loc = this._loc();
+    this._eat(T.SERVER);
+    this._eat(T.LBRACE);
+    const data = [];
+    while (!this._check(T.RBRACE) && !this._atEnd()) {
+      // data name = expr  (expr may contain `await fetch(...)`)
+      const declLoc = this._loc();
+      this._eat(T.DATA);
+      const name = this._eat(T.IDENT).value;
+      this._eat(T.ASSIGN);
+      const init = this._parseExpr();
+      data.push(node.serverDataDecl(name, init, declLoc));
+      // optional semicolon
+      if (this._check(T.SEMICOLON)) this._advance();
+    }
+    this._eat(T.RBRACE);
+    return node.serverBlock(data, loc);
+  }
+
+  _parseAIDecl() {
+    const loc = this._loc();
+    this._eat(T.AI);
+    this._eat(T.COLON);
+    const capability = this._eat(T.IDENT).value; // readable, actionable, forbidden
+    if (this._check(T.ASSIGN)) this._advance(); // `=` is optional: `ai:readable [x]` or `ai:readable = [x]`
+    this._eat(T.LBRACKET);
+    const targets = [];
+    // Support member expressions: [user.name, user.email]
+    while (!this._check(T.RBRACKET) && !this._atEnd()) {
+      let target = this._eat(T.IDENT).value;
+      while (this._check(T.DOT)) {
+        this._advance();
+        target += '.' + this._eat(T.IDENT).value;
+      }
+      targets.push(target);
+      if (this._check(T.COMMA)) this._advance();
+    }
+    this._eat(T.RBRACKET);
+    return node.aiDecl(capability, targets, loc);
+  }
+
+  _parseBeforeMountBlock() {
+    const loc = this._loc();
+    this._eat(T.BEFORE_MOUNT);
+    const body = this._parseBlock();
+    return node.beforeMountBlock(body, loc);
+  }
+
+  _parseOnMountBlock() {
+    const loc = this._loc();
+    this._eat(T.ON_MOUNT);
+    const body = this._parseBlock();
+    return node.onMountBlock(body, loc);
+  }
+
+  _parseOnCleanupBlock() {
+    const loc = this._loc();
+    this._eat(T.ON_CLEANUP);
+    const body = this._parseBlock();
+    return node.onCleanupBlock(body, loc);
+  }
+
+  /**
+   * action funcName(param1, param2) { body }
+   * Declares a named function that AI agents are allowed to call via act().
+   * The body can contain any statements (assignments, signal updates, etc.).
+   */
+  _parseActionDecl() {
+    const loc = this._loc();
+    this._eat(T.ACTION);
+    const name = this._eat(T.IDENT).value;
+    this._eat(T.LPAREN);
+    const params = [];
+    while (!this._check(T.RPAREN) && !this._atEnd()) {
+      const pname = this._eat(T.IDENT).value;
+      params.push(pname);
+      if (this._check(T.COMMA)) this._advance();
+    }
+    this._eat(T.RPAREN);
+    const body = this._parseBlock();
+    return node.actionDecl(name, params, body, loc);
+  }
+
+  // ── JSX Parsing ──
+  _parseJSXElement() {
+    const loc = this._loc();
+
+    if (!this._check(T.JSX_OPEN)) {
+      // Could be a text node or expression
+      if (this._check(T.STRING)) {
+        const val = this._advance().value;
+        return node.jsxText(val, loc);
+      }
+      throw new ParseError('Expected JSX element', this._peek(), this.source);
+    }
+
+    const tagName = this._eat(T.JSX_OPEN).value;
+    const attrs   = this._parseJSXAttrs();
+
+    // Self-closing: />
+    if (this._check(T.JSX_SELF_CLOSE) || (this._check(T.SLASH) && this._checkAt(1, T.GT))) {
+      if (this._check(T.SLASH)) this._advance();
+      if (this._check(T.GT)) this._advance();
+      return node.jsxElement(tagName, attrs, [], true, loc);
+    }
+
+    // Opening tag closes: >
+    if (this._check(T.GT)) this._advance();
+
+    // Children
+    const children = this._parseJSXChildren(tagName);
+
+    return node.jsxElement(tagName, attrs, children, false, loc);
+  }
+
+  _parseJSXAttrs() {
+    const attrs = [];
+
+    while (!this._atEnd() && !this._check(T.GT) && !this._check(T.SLASH) && !this._check(T.JSX_SELF_CLOSE)) {
+      const loc = this._loc();
+
+      // Spread attribute: {...expr}
+      // Must be checked before regular LBRACE handling
+      if (this._check(T.LBRACE)) {
+        this._eat(T.LBRACE);
+        if (this._check(T.SPREAD)) {
+          this._advance(); // consume ...
+          const expr = this._parseExpr();
+          this._eat(T.RBRACE);
+          attrs.push({ type: 'SpreadAttr', expr, loc });
+          continue;
+        }
+        // Unexpected { without spread — skip to avoid infinite loop
+        this._advance();
+        continue;
+      }
+
+      // on:event[.modifier]* handler
+      if (this._check(T.ON) || (this._check(T.IDENT) && this._current().value === 'on')) {
+        this._advance();
+        if (this._check(T.COLON)) {
+          this._advance();
+          const eventName = this._eat(T.IDENT).value;
+          // Collect optional chained modifiers: .prevent .stop .enter .escape .space .tab
+          const modifiers = [];
+          while (this._check(T.DOT)) {
+            this._advance(); // consume '.'
+            if (this._check(T.IDENT)) modifiers.push(this._advance().value);
+          }
+          this._eat(T.ASSIGN);
+          this._eat(T.LBRACE);
+          const handler = this._parseExpr();
+          this._eat(T.RBRACE);
+          attrs.push(node.eventAttr(eventName, modifiers, handler, loc));
+          continue;
+        }
+      }
+
+      // bind:prop
+      if (this._check(T.IDENT) && this._current().value === 'bind') {
+        this._advance();
+        if (this._check(T.COLON)) {
+          this._advance();
+          const propName = this._eat(T.IDENT).value;
+          this._eat(T.ASSIGN);
+          this._eat(T.LBRACE);
+          const sig = this._parseExpr();
+          this._eat(T.RBRACE);
+          attrs.push(node.bindAttr(propName, sig, loc));
+          continue;
+        }
+      }
+
+      // Regular attribute: name="value" or name={expr} or just name
+      // Accept plain identifiers AND keyword tokens (e.g. `action`, `data`,
+      // `for`) as attribute names — in JSX they are ordinary HTML attributes,
+      // not language keywords.
+      if (this._isJSXAttrName()) {
+        const name = this._advance().value;
+
+        if (!this._check(T.ASSIGN)) {
+          // Boolean attribute
+          attrs.push(node.attr(name, node.literal(true, loc), loc));
+          continue;
+        }
+
+        this._eat(T.ASSIGN);
+
+        if (this._check(T.STRING)) {
+          const val = this._advance().value;
+          attrs.push(node.attr(name, node.literal(val, loc), loc));
+        } else if (this._check(T.LBRACE)) {
+          this._eat(T.LBRACE);
+          const expr = this._parseExpr();
+          this._eat(T.RBRACE);
+          attrs.push(node.attr(name, expr, loc));
+        } else {
+          this._advance();
+        }
+        continue;
+      }
+
+      // Skip unknown
+      this._advance();
+    }
+
+    return attrs;
+  }
+
+  /**
+   * True when the current token can serve as a JSX attribute name. This is any
+   * identifier OR any keyword token (action, data, route, when, …) whose value
+   * is a valid attribute-name string. Structural / operator tokens are excluded.
+   */
+  _isJSXAttrName() {
+    if (this._check(T.IDENT)) return true;
+    const t = this._current();
+    if (!t || typeof t.value !== 'string') return false;
+    const EXCLUDED = new Set([
+      T.GT, T.LT, T.SLASH, T.JSX_SELF_CLOSE, T.JSX_OPEN, T.JSX_CLOSE,
+      T.LBRACE, T.RBRACE, T.ASSIGN, T.COLON, T.DOT, T.COMMA, T.STRING,
+      T.NUMBER, T.EOF,
+    ]);
+    if (EXCLUDED.has(t.type)) return false;
+    return /^[A-Za-z_][A-Za-z0-9_-]*$/.test(t.value);
+  }
+
+  _parseJSXChildren(parentTag) {
+    const children = [];
+
+    // Token types that are NOT valid inside JSX children as text
+    const NON_TEXT = new Set([T.JSX_OPEN, T.JSX_CLOSE, T.LBRACE, T.RBRACE, T.JSX_TEXT, T.EOF]);
+
+    while (!this._atEnd()) {
+      const loc = this._loc();
+
+      // Closing tag
+      if (this._check(T.JSX_CLOSE)) {
+        this._advance();
+        break;
+      }
+
+      // Nested JSX element
+      if (this._check(T.JSX_OPEN)) {
+        children.push(this._parseJSXElement());
+        continue;
+      }
+
+      // Expression: { expr }
+      if (this._check(T.LBRACE)) {
+        this._eat(T.LBRACE);
+        const expr = this._parseExpr();
+        this._eat(T.RBRACE);
+        children.push(node.jsxExpr(expr, loc));
+        continue;
+      }
+
+      // Explicit JSX_TEXT token
+      if (this._check(T.JSX_TEXT)) {
+        const text = this._advance().value;
+        if (text.trim()) children.push(node.jsxText(text, loc));
+        continue;
+      }
+
+      // Collect consecutive non-structural tokens as plain text
+      // (identifiers, keywords, numbers, punctuation used as text content).
+      // Reconstruct verbatim from the original source so punctuation like
+      // "Clarity.js", "AI-native" or "v0.6" keeps its exact spacing; collapse
+      // runs of whitespace to a single space (HTML-style).
+      if (!NON_TEXT.has(this._peek().type)) {
+        const toks = [];
+        while (!this._atEnd() && !NON_TEXT.has(this._peek().type)) {
+          toks.push(this._advance());
+        }
+        const first = toks[0];
+        const last  = toks[toks.length - 1];
+        let text;
+        if (this.source && first.start != null && last.end != null) {
+          text = this.source.slice(first.start, last.end).replace(/\s+/g, ' ');
+          // Preserve a boundary space if the source had whitespace adjacent to
+          // the run (e.g. between an inline element and following text).
+          if (/\s/.test(this.source[first.start - 1] || '')) text = ' ' + text;
+          if (/\s/.test(this.source[last.end] || ''))         text = text + ' ';
+        } else {
+          // Fallback when no source offsets are available (bare parse()).
+          text = toks.map(t => t.value ?? t.type).join(' ');
+        }
+        if (text.trim()) children.push(node.jsxText(text, loc));
+        continue;
+      }
+
+      break;
+    }
+
+    return children;
+  }
+
+  // ── Expression Parsing ──
+  // Pratt-style precedence climbing
+
+  _parseExpr() {
+    // Support comma expression: a = 1, b = 2
+    // Used in event handlers like on:click={ a++, b = 0 }
+    const loc = this._loc();
+    const first = this._parseTernary();
+    if (this._check(T.COMMA) && !this._inAttrValue) {
+      const parts = [first];
+      while (this._check(T.COMMA)) {
+        this._advance();
+        parts.push(this._parseTernary());
+      }
+      return { type: 'CommaExpr', parts, loc };
+    }
+    return first;
+  }
+
+  _parseTernary() {
+    const loc = this._loc();
+    let expr = this._parseOr();
+
+    if (this._check(T.QUESTION)) {
+      this._advance();
+      const then = this._parseExpr();
+      this._eat(T.COLON);
+      const else_ = this._parseTernary();
+      return node.ternary(expr, then, else_, loc);
+    }
+
+    return expr;
+  }
+
+  _parseOr() {
+    const loc = this._loc();
+    let left = this._parseAnd();
+    while (this._check(T.OR)) {
+      const op = this._advance().value;
+      left = node.binary(op, left, this._parseAnd(), loc);
+    }
+    return left;
+  }
+
+  _parseAnd() {
+    const loc = this._loc();
+    let left = this._parseEquality();
+    while (this._check(T.AND)) {
+      const op = this._advance().value;
+      left = node.binary(op, left, this._parseEquality(), loc);
+    }
+    return left;
+  }
+
+  _parseEquality() {
+    const loc = this._loc();
+    let left = this._parseComparison();
+    while (this._checkAny(T.EQ_EQ, T.NOT_EQ, T.EQ_EQ_EQ, T.NOT_EQ_EQ)) {
+      const op = this._advance().value;
+      left = node.binary(op, left, this._parseComparison(), loc);
+    }
+    return left;
+  }
+
+  _parseComparison() {
+    const loc = this._loc();
+    let left = this._parseAddSub();
+    while (this._checkAny(T.LT, T.GT, T.LT_EQ, T.GT_EQ)) {
+      const op = this._advance().value;
+      left = node.binary(op, left, this._parseAddSub(), loc);
+    }
+    return left;
+  }
+
+  _parseAddSub() {
+    const loc = this._loc();
+    let left = this._parseMulDiv();
+    while (this._checkAny(T.PLUS, T.MINUS)) {
+      const op = this._advance().value;
+      left = node.binary(op, left, this._parseMulDiv(), loc);
+    }
+    return left;
+  }
+
+  _parseMulDiv() {
+    const loc = this._loc();
+    let left = this._parseUnary();
+    while (this._checkAny(T.STAR, T.SLASH, T.PERCENT)) {
+      const op = this._advance().value;
+      left = node.binary(op, left, this._parseUnary(), loc);
+    }
+    return left;
+  }
+
+  _parseUnary() {
+    const loc = this._loc();
+    if (this._checkAny(T.NOT, T.MINUS)) {
+      const op = this._advance().value;
+      return node.unary(op, this._parseUnary(), loc);
+    }
+    if (this._checkAny(T.PLUS_PLUS, T.MINUS_MINUS)) {
+      const op = this._advance().value;
+      return node.update(op, this._parsePostfix(), true, loc);
+    }
+    // `await` — only meaningful inside server { } blocks but we parse it anywhere
+    // so the AST is well-formed; the codegen emits `await` only in async functions.
+    if (this._check(T.IDENT) && this._current().value === 'await') {
+      this._advance();
+      return node.awaitExpr(this._parseUnary(), loc);
+    }
+    return this._parsePostfix();
+  }
+
+  _parsePostfix() {
+    const loc = this._loc();
+    let expr = this._parseCallMember();
+
+    // Post-increment/decrement
+    if (this._checkAny(T.PLUS_PLUS, T.MINUS_MINUS)) {
+      const op = this._advance().value;
+      return node.update(op, expr, false, loc);
+    }
+
+    // Assignment operators
+    // FIX: use _parseTernary (not _parseExpr) for RHS — prevents comma from being
+    // swallowed into the value. e.g. a = x, b = y must parse as (a=x),(b=y) not a=(x,b=y)
+    // This matches JavaScript assignment precedence (right-associative, below comma).
+    if (this._checkAny(T.ASSIGN, T.PLUS_EQ, T.MINUS_EQ)) {
+      const op = this._advance().value;
+      const value = this._parseTernary();
+      return node.assign(expr, op, value, loc);
+    }
+
+    return expr;
+  }
+
+  _parseCallMember() {
+    const loc = this._loc();
+    let expr = this._parsePrimary();
+
+    while (true) {
+      if (this._check(T.DOT)) {
+        this._advance();
+        const prop = this._eat(T.IDENT).value;
+        expr = node.member(expr, node.ident(prop, loc), false, loc);
+        continue;
+      }
+
+      if (this._check(T.LBRACKET)) {
+        this._advance();
+        const index = this._parseExpr();
+        this._eat(T.RBRACKET);
+        expr = node.member(expr, index, true, loc);
+        continue;
+      }
+
+      if (this._check(T.LPAREN)) {
+        this._advance();
+        const args = [];
+        const prevFlag = this._inAttrValue;
+        this._inAttrValue = true; // commas separate arguments
+        while (!this._check(T.RPAREN) && !this._atEnd()) {
+          args.push(this._parseTernary());
+          if (this._check(T.COMMA)) this._advance();
+        }
+        this._inAttrValue = prevFlag;
+        this._eat(T.RPAREN);
+        expr = node.call(expr, args, loc);
+        continue;
+      }
+
+      break;
+    }
+
+    return expr;
+  }
+
+  _parsePrimary() {
+    const loc  = this._loc();
+    const tok  = this._peek();
+
+    // Literals
+    if (tok.type === T.NUMBER) return node.literal(this._advance().value, loc);
+    if (tok.type === T.STRING) return node.literal(this._advance().value, loc);
+    if (tok.type === T.TEMPLATE) return this._parseTemplateLiteral(this._advance(), loc);
+    if (tok.type === T.BOOL)   return node.literal(this._advance().value === 'true', loc);
+    if (tok.type === T.NULL)   { this._advance(); return node.literal(null, loc); }
+    if (tok.type === T.UNDEFINED) { this._advance(); return node.literal(undefined, loc); }
+
+    // Grouping
+    if (tok.type === T.LPAREN) {
+      this._advance();
+      // Check for arrow function: (params) =>
+      const saved = this.pos;
+      try {
+        const params = this._tryParseArrowParams();
+        if (params !== null && this._check(T.ARROW)) {
+          this._advance(); // =>
+          const body = this._check(T.LBRACE)
+            ? this._parseBlock()
+            : this._parseExpr();
+          return node.arrow(params, body, loc);
+        }
+      } catch (_) { /* fall through */ }
+      this.pos = saved;
+      const expr = this._parseExpr();
+      this._eat(T.RPAREN);
+      return expr;
+    }
+
+    // Array literal
+    if (tok.type === T.LBRACKET) {
+      this._advance();
+      const elements = [];
+      const prevFlag = this._inAttrValue;
+      this._inAttrValue = true; // commas are separators inside arrays
+      while (!this._check(T.RBRACKET) && !this._atEnd()) {
+        if (this._check(T.SPREAD)) {
+          this._advance(); // consume ...
+          elements.push({ type: 'SpreadExpr', expr: this._parseTernary(), loc });
+        } else {
+          elements.push(this._parseTernary());
+        }
+        if (this._check(T.COMMA)) this._advance();
+      }
+      this._inAttrValue = prevFlag;
+      this._eat(T.RBRACKET);
+      return node.array(elements, loc);
+    }
+
+    // Object literal
+    if (tok.type === T.LBRACE) {
+      this._advance();
+      const props = [];
+      const prevFlag = this._inAttrValue;
+      this._inAttrValue = true; // commas are separators inside objects
+      while (!this._check(T.RBRACE) && !this._atEnd()) {
+        const key = this._eat(T.IDENT).value;
+        if (this._check(T.COLON)) {
+          this._advance();
+          props.push(node.prop(key, this._parseTernary(), loc));
+        } else {
+          // Shorthand: { foo } → { foo: foo }
+          props.push(node.prop(key, node.ident(key, loc), loc));
+        }
+        if (this._check(T.COMMA)) this._advance();
+      }
+      this._inAttrValue = prevFlag;
+      this._eat(T.RBRACE);
+      return node.object(props, loc);
+    }
+
+    // Identifier (could be arrow function: x => ..., or `new` expression)
+    if (tok.type === T.IDENT) {
+      // new ClassName(...args)
+      if (tok.value === 'new') {
+        this._advance(); // consume 'new'
+        const callee = this._parsePrimary(); // parse constructor name (may be member expr)
+        const args = [];
+        if (this._check(T.LPAREN)) {
+          this._advance(); // consume (
+          const prevFlag = this._inAttrValue;
+          this._inAttrValue = true;
+          while (!this._check(T.RPAREN) && !this._atEnd()) {
+            if (this._check(T.SPREAD)) {
+              this._advance();
+              args.push({ type: 'SpreadExpr', expr: this._parseTernary(), loc });
+            } else {
+              args.push(this._parseTernary());
+            }
+            if (this._check(T.COMMA)) this._advance();
+          }
+          this._inAttrValue = prevFlag;
+          this._eat(T.RPAREN);
+        }
+        return { type: 'NewExpr', callee, args, loc };
+      }
+      const name = this._advance().value;
+      if (this._check(T.ARROW)) {
+        this._advance();
+        const body = this._check(T.LBRACE) ? this._parseBlock() : this._parseExpr();
+        return node.arrow([{ name, type: null }], body, loc);
+      }
+      return node.ident(name, loc);
+    }
+
+    // Keywords used as identifiers in expressions
+    if ([T.STATE, T.EFFECT, T.ON, T.COMPONENT, T.RENDER, T.SERVER, T.COMPUTED].includes(tok.type)) {
+      return node.ident(this._advance().value, loc);
+    }
+
+    // Fallback: skip and return null literal
+    return node.literal(null, loc);
+  }
+
+  // ── Template Literal Parsing ──
+  // Splits the raw token value on ${...} boundaries, parses each expression
+  // part using a fresh Lexer+Parser, and builds a TemplateLiteral AST node.
+  //
+  // Example:  `Hello ${name}, you have ${count} items`
+  //   → TemplateLiteral { parts: [
+  //       { type: 'str',  value: 'Hello ' },
+  //       { type: 'expr', expr: Ident('name') },
+  //       { type: 'str',  value: ', you have ' },
+  //       { type: 'expr', expr: Ident('count') },
+  //       { type: 'str',  value: ' items' },
+  //     ]}
+  _parseTemplateLiteral(token, loc) {
+    const raw   = token.value;
+    const parts = [];
+
+    // Match ${...} interpolations — no support for nested braces inside the
+    // expression (the lexer already handles depth tracking during scan, so
+    // the raw content only has balanced single-level ${...}).
+    const rx = /\$\{([^}]*)\}/g;
+    let lastIdx = 0;
+    let match;
+
+    while ((match = rx.exec(raw)) !== null) {
+      // Static string before this interpolation
+      if (match.index > lastIdx) {
+        parts.push({ type: 'str', value: raw.slice(lastIdx, match.index) });
+      }
+
+      // Parse the expression inside ${...}
+      const exprSrc = match[1].trim();
+      let exprAST;
+      try {
+        const exprTokens = new Lexer(exprSrc, '<template>').tokenize();
+        const exprParser = new Parser(exprTokens, exprSrc);
+        exprAST = exprParser._parseTernary();
+      } catch (_) {
+        // Fallback: treat the raw text as an identifier reference
+        exprAST = node.ident(exprSrc, loc);
+      }
+      parts.push({ type: 'expr', expr: exprAST });
+      lastIdx = match.index + match[0].length;
+    }
+
+    // Trailing static string
+    if (lastIdx < raw.length) {
+      parts.push({ type: 'str', value: raw.slice(lastIdx) });
+    }
+
+    return node.template(parts, loc);
+  }
+
+  _tryParseArrowParams() {
+    const params = [];
+    while (!this._check(T.RPAREN) && !this._atEnd()) {
+      const name = this._eat(T.IDENT).value;
+      let type = null;
+      if (this._check(T.COLON)) {
+        this._advance();
+        type = this._eat(T.IDENT).value;
+      }
+      params.push({ name, type });
+      if (this._check(T.COMMA)) this._advance();
+    }
+    this._eat(T.RPAREN);
+    return params;
+  }
+
+  // ── Statement Parsing ──
+  _parseBlock() {
+    const loc = this._loc();
+    this._eat(T.LBRACE);
+    const body = [];
+    while (!this._check(T.RBRACE) && !this._atEnd()) {
+      const stmt = this._parseStatement();
+      if (stmt) body.push(stmt);
+    }
+    this._eat(T.RBRACE);
+    return node.block(body, loc);
+  }
+
+  _parseStatement() {
+    const loc = this._loc();
+
+    if (this._check(T.RETURN)) {
+      this._advance();
+      const value = !this._checkAny(T.RBRACE, T.NEWLINE, T.SEMICOLON, T.EOF)
+        ? this._parseExpr()
+        : null;
+      return node.returnStmt(value, loc);
+    }
+
+    // if statement: if (cond) { block } [else { block }]
+    // also handles single-statement: if (cond) return expr
+    if (this._check(T.IDENT) && this._current().value === 'if') {
+      this._advance(); // consume 'if'
+      this._eat(T.LPAREN);
+      const cond = this._parseExpr();
+      this._eat(T.RPAREN);
+      // Support both braced block and single inline statement
+      const then = this._check(T.LBRACE)
+        ? this._parseBlock()
+        : node.block([this._parseStatement()].filter(Boolean), loc);
+      let else_ = null;
+      if (this._check(T.IDENT) && this._current().value === 'else') {
+        this._advance();
+        else_ = this._check(T.LBRACE)
+          ? this._parseBlock()
+          : node.block([this._parseStatement()].filter(Boolean), loc);
+      }
+      return node.ifStmt(cond, then, else_, loc);
+    }
+
+    // Variable declaration: const/let/var + ident = expr [, ident = expr ...]
+    if (this._check(T.IDENT) && ['const', 'let', 'var'].includes(this._current().value)) {
+      const kind = this._advance().value;
+      const declarators = [];
+      do {
+        const dname = this._eat(T.IDENT).value;
+        this._eat(T.ASSIGN);
+        const dinit = this._parseTernary(); // not _parseExpr — avoids eating commas between declarators
+        declarators.push({ name: dname, init: dinit });
+      } while (this._check(T.COMMA) && this._advance());
+      if (declarators.length === 1) {
+        return node.varDecl(kind, declarators[0].name, declarators[0].init, loc);
+      }
+      return { type: 'MultiVarDecl', kind, declarators, loc };
+    }
+
+    if (this._check(T.SEMICOLON)) {
+      this._advance();
+      return null;
+    }
+
+    // Consume a bare comma (e.g. inside arrow-function blocks that are arguments
+    // to a call — _inAttrValue suppresses CommaExpr, so the comma is left over)
+    if (this._check(T.COMMA)) {
+      this._advance();
+      return null;
+    }
+
+    const expr = this._parseExpr();
+    if (this._check(T.SEMICOLON)) this._advance();
+    return node.exprStmt(expr, loc);
+  }
+
+  // ── Token Utilities ──
+  _peek()                  { return this.tokens[this.pos] ?? { type: T.EOF, value: null, line: 0, col: 0 }; }
+  _current()               { return this.tokens[this.pos]; }
+  _peekNext()              { return this.tokens[this.pos + 1]; }
+  _checkAt(offset, type)   { return (this.tokens[this.pos + offset]?.type ?? T.EOF) === type; }
+  _atEnd()                 { return this._peek().type === T.EOF; }
+  _check(type)             { return this._peek().type === type; }
+  _checkAny(...types)      { return types.includes(this._peek().type); }
+  _loc()                   { const t = this._peek(); return { line: t.line, col: t.col }; }
+
+  _advance() {
+    const tok = this._peek();
+    if (!this._atEnd()) this.pos++;
+    return tok;
+  }
+
+  _eat(type) {
+    if (!this._check(type)) {
+      throw new ParseError(`Expected ${type}`, this._peek(), this.source);
+    }
+    return this._advance();
+  }
+}
+
+// ─── Convenience export ───────────────────────────────────────────────────────
+export function parse(tokens, source) {
+  return new Parser(tokens, source).parse();
+}
+