@words-lang/parser 0.1.0

package/dist/parser/parser.js

@@ -0,0 +1,1600 @@
+"use strict";
+/**
+ * parser.ts
+ *
+ * The WORDS parser. Consumes a flat token stream produced by the Lexer and
+ * builds an AST described in ast.ts.
+ *
+ * Design principles:
+ *
+ * - Recursive descent. Each grammar rule has a corresponding private method.
+ *   Methods consume tokens and return AST nodes.
+ *
+ * - Error recovery. When an unexpected token is encountered the parser emits
+ *   a diagnostic, skips tokens until it finds a safe synchronisation point
+ *   (typically a newline, a closing paren, or a known top-level keyword), and
+ *   continues. This means a single parse pass collects all errors in the file.
+ *
+ * - No exceptions for parse errors. All problems are collected in `this.diagnostics`
+ *   and returned alongside the partial AST in the `ParseResult`.
+ *
+ * - Comments and newlines are consumed transparently by the `skip()` helper
+ *   unless the calling rule explicitly needs them (e.g. ownership declaration
+ *   detection requires newlines).
+ *
+ * - `system` and `state` are both keywords and identifier prefixes in access
+ *   expressions (`system.setContext`, `state.context`). The parser disambiguates
+ *   by context — inside a `uses` block or argument value position, these are
+ *   treated as access expression roots, not construct keywords.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Parser = void 0;
+const token_1 = require("../lexer/token");
+const diagnostics_1 = require("../analyser/diagnostics");
+// ── Parser ────────────────────────────────────────────────────────────────────
+class Parser {
+    constructor(tokens) {
+        /** Current position in the token stream. */
+        this.pos = 0;
+        /** Diagnostics collected during this parse. */
+        this.diagnostics = [];
+        this.tokens = tokens;
+    }
+    // ── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Parses the entire token stream and returns a ParseResult containing
+     * the document AST and all collected diagnostics.
+     * Never throws — all errors are collected as diagnostics.
+     */
+    parse() {
+        const document = this.parseDocument();
+        return { document, diagnostics: this.diagnostics };
+    }
+    // ── Document ───────────────────────────────────────────────────────────────
+    /**
+     * Parses a complete `.wds` file.
+     *
+     * Detects the ownership declaration pattern — a bare `module ModuleName`
+     * on its own line at the top of component files. If the first non-trivial
+     * content is `module PascalIdent Newline` (with no opening `(`), it is
+     * captured as `ownerModule` and the next construct is parsed normally.
+     */
+    parseDocument() {
+        this.skipComments();
+        let ownerModule = null;
+        // Detect ownership declaration: module ModuleName \n (no body follows)
+        if (this.check(token_1.TokenType.Module)) {
+            const saved = this.pos;
+            this.advance(); // consume 'module'
+            this.skipComments();
+            if (this.check(token_1.TokenType.PascalIdent)) {
+                const name = this.current().value;
+                this.advance(); // consume name
+                this.skipComments();
+                // If the next meaningful token is a newline or EOF (not a string or '('),
+                // this is an ownership declaration, not a module definition.
+                if (this.check(token_1.TokenType.Newline) || this.check(token_1.TokenType.EOF)) {
+                    ownerModule = name;
+                    this.skipTrivia();
+                }
+                else {
+                    // Not an ownership declaration — restore and parse normally.
+                    this.pos = saved;
+                }
+            }
+            else {
+                this.pos = saved;
+            }
+        }
+        const nodes = [];
+        while (!this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.EOF))
+                break;
+            const savedPos = this.pos;
+            const node = this.parseTopLevel();
+            if (node !== null) {
+                nodes.push(node);
+            }
+            else if (this.pos === savedPos) {
+                // parseTopLevel returned null without advancing (e.g. synchronise()
+                // stopped at an RParen that has no matching open at the top level).
+                // Force progress to prevent an infinite loop.
+                this.advance();
+            }
+        }
+        return { kind: 'Document', ownerModule, nodes };
+    }
+    // ── Top-level dispatch ─────────────────────────────────────────────────────
+    /**
+     * Parses one top-level construct and returns it, or emits a diagnostic
+     * and returns null if the current token does not start a known construct.
+     */
+    parseTopLevel() {
+        const tok = this.current();
+        switch (tok.type) {
+            case token_1.TokenType.System: return this.parseSystem();
+            case token_1.TokenType.Module: return this.parseModule();
+            case token_1.TokenType.State: return this.parseState();
+            case token_1.TokenType.Context: return this.parseContext();
+            case token_1.TokenType.Screen: return this.parseScreen();
+            case token_1.TokenType.View: return this.parseView();
+            case token_1.TokenType.Provider: return this.parseProvider();
+            case token_1.TokenType.Adapter: return this.parseAdapter();
+            case token_1.TokenType.Interface: return this.parseInterface();
+            default:
+                this.error(diagnostics_1.DiagnosticCode.P_INVALID_CONSTRUCT_POSITION, `Unexpected token '${tok.value}' — expected a construct keyword (system, module, state, context, screen, view, provider, adapter, interface)`, tok);
+                this.synchronise();
+                return null;
+        }
+    }
+    // ── System ─────────────────────────────────────────────────────────────────
+    /**
+     * Parses:
+     *   system SystemName "description" (
+     *     modules ( ModuleOne ModuleTwo )
+     *     interface ( ... )
+     *   )
+     */
+    parseSystem() {
+        const tok = this.expect(token_1.TokenType.System);
+        this.skipTrivia();
+        const name = this.expectIdent('system name');
+        this.skipTrivia();
+        const description = this.parseOptionalString();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        const modules = [];
+        const interfaceMethods = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Modules)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+                    this.skipTrivia();
+                    if (this.check(token_1.TokenType.PascalIdent)) {
+                        modules.push(this.advance().value);
+                    }
+                    else if (!this.check(token_1.TokenType.RParen)) {
+                        this.error(diagnostics_1.DiagnosticCode.P_MISSING_IDENTIFIER, `Expected module name`, this.current());
+                        this.advance();
+                    }
+                }
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (this.check(token_1.TokenType.Interface)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+                    this.skipTrivia();
+                    if (this.check(token_1.TokenType.CamelIdent)) {
+                        interfaceMethods.push(this.parseMethod());
+                    }
+                    else if (!this.check(token_1.TokenType.RParen)) {
+                        this.advance();
+                    }
+                }
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (!this.check(token_1.TokenType.RParen)) {
+                this.advance();
+            }
+        }
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'System', token: tok, name, description, modules, interfaceMethods };
+    }
+    // ── Module ─────────────────────────────────────────────────────────────────
+    /**
+     * Parses:
+     *   module ModuleName "description" (
+     *     process ... ( when ... )
+     *     start StateName
+     *     implements Module.Handler ( methodName param(Type) ( if ... ) )
+     *     system.Module.subscribeRoute ...
+     *     interface HandlerName ( ... )
+     *   )
+     */
+    parseModule() {
+        const tok = this.expect(token_1.TokenType.Module);
+        this.skipTrivia();
+        const name = this.expectIdent('module name');
+        this.skipTrivia();
+        const description = this.parseOptionalString();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        const processes = [];
+        let startState = null;
+        const implementations = [];
+        const subscriptions = [];
+        const inlineInterfaces = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Process)) {
+                processes.push(this.parseProcess());
+            }
+            else if (this.check(token_1.TokenType.Start)) {
+                this.advance();
+                this.skipTrivia();
+                startState = this.expectIdent('start state name');
+            }
+            else if (this.check(token_1.TokenType.Implements)) {
+                implementations.push(this.parseImplements());
+            }
+            else if (this.check(token_1.TokenType.Interface)) {
+                inlineInterfaces.push(this.parseInterface());
+            }
+            else if (this.checkSystemCall()) {
+                subscriptions.push(this.parseSystemCall());
+            }
+            else if (!this.check(token_1.TokenType.RParen)) {
+                this.advance();
+            }
+        }
+        this.expect(token_1.TokenType.RParen);
+        return {
+            kind: 'Module', token: tok, name, description,
+            processes, startState,
+            implements: implementations,
+            subscriptions, inlineInterfaces,
+        };
+    }
+    // ── Process ────────────────────────────────────────────────────────────────
+    /**
+     * Parses:
+     *   process ProcessName "description" (
+     *     when State returns Context
+     *       enter NextState "narrative"
+     *     ...
+     *   )
+     */
+    parseProcess() {
+        const tok = this.expect(token_1.TokenType.Process);
+        this.skipTrivia();
+        const name = this.expectIdent('process name');
+        this.skipTrivia();
+        const description = this.parseOptionalString();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        const rules = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.When)) {
+                rules.push(this.parseWhenRule());
+            }
+            else if (!this.check(token_1.TokenType.RParen)) {
+                this.advance();
+            }
+        }
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'Process', token: tok, name, description, rules };
+    }
+    /**
+     * Parses:
+     *   when CurrentState returns ProducedContext
+     *     enter NextState "narrative" ( inlineContext? )
+     */
+    parseWhenRule() {
+        const tok = this.expect(token_1.TokenType.When);
+        this.skipTrivia();
+        const currentState = this.expectIdent('state name in when rule');
+        this.skipTrivia();
+        if (!this.check(token_1.TokenType.Returns)) {
+            this.error(diagnostics_1.DiagnosticCode.P_MISSING_RETURNS, `Expected 'returns' in when rule`, this.current());
+        }
+        else {
+            this.advance();
+        }
+        this.skipTrivia();
+        const producedContext = this.expectIdent('context name in when rule');
+        this.skipTrivia();
+        if (!this.check(token_1.TokenType.Enter)) {
+            this.error(diagnostics_1.DiagnosticCode.P_MISSING_ENTER, `Expected 'enter' in when rule`, this.current());
+        }
+        else {
+            this.advance();
+        }
+        this.skipTrivia();
+        const nextState = this.expectIdent('next state name in when rule');
+        this.skipTrivia();
+        const narrative = this.parseOptionalString();
+        this.skipTrivia();
+        // Optional inline context construction block
+        let inlineContext = null;
+        if (this.check(token_1.TokenType.LParen)) {
+            inlineContext = this.parseInlineContext();
+        }
+        return { kind: 'WhenRule', token: tok, currentState, producedContext, nextState, narrative, inlineContext };
+    }
+    /**
+     * Parses an inline context construction block:
+     *   ( reason is "..." code is "..." )
+     */
+    parseInlineContext() {
+        const tok = this.expect(token_1.TokenType.LParen);
+        const args = this.parseArguments();
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'InlineContext', token: tok, args };
+    }
+    // ── Implements ─────────────────────────────────────────────────────────────
+    /**
+     * Parses:
+     *   implements Module.HandlerInterface (
+     *     methodName param(Type) (
+     *       if param is "/path"
+     *         enter State "narrative"
+     *     )
+     *   )
+     *
+     * The method name (e.g. `switch`) is a plain camelCase identifier chosen
+     * by the designer on the handler interface — it is not a reserved keyword.
+     */
+    parseImplements() {
+        const tok = this.expect(token_1.TokenType.Implements);
+        this.skipTrivia();
+        const interfaceName = this.parseQualifiedName();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        this.skipTrivia();
+        // handler method name param(Type) ( ... )
+        // The method name (e.g. `switch`) is a plain camelCase name chosen by the
+        // designer on the handler interface — it is not a reserved keyword.
+        // We consume the method name then the parameter name and its type.
+        this.expectIdent('handler method name'); // e.g. 'switch' — consumed but not stored
+        this.skipTrivia();
+        const switchParam = this.expectIdent('handler method parameter name');
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        const switchParamType = this.parseType();
+        this.expect(token_1.TokenType.RParen);
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        const branches = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.If)) {
+                branches.push(this.parseImplementsBranch());
+            }
+            else if (!this.check(token_1.TokenType.RParen)) {
+                this.advance();
+            }
+        }
+        this.expect(token_1.TokenType.RParen); // close method body
+        this.skipTrivia();
+        this.expect(token_1.TokenType.RParen); // close implements body
+        return { kind: 'ImplementsHandler', token: tok, interfaceName, switchParam, switchParamType, branches };
+    }
+    /**
+     * Parses one branch inside an implements handler body:
+     *   if param is "/path"
+     *     enter State "narrative"
+     */
+    parseImplementsBranch() {
+        const tok = this.expect(token_1.TokenType.If);
+        this.skipTrivia();
+        const condition = this.parseCondition();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.Enter);
+        this.skipTrivia();
+        const targetState = this.expectIdent('target state name');
+        this.skipTrivia();
+        const narrative = this.parseOptionalString();
+        return { kind: 'ImplementsBranch', token: tok, condition, targetState, narrative };
+    }
+    // ── State ──────────────────────────────────────────────────────────────────
+    /**
+     * Parses:
+     *   state StateName receives ?ContextName (
+     *     returns ContextA, ContextB
+     *     uses screen ScreenName
+     *   )
+     */
+    parseState() {
+        const tok = this.expect(token_1.TokenType.State);
+        this.skipTrivia();
+        const name = this.expectIdent('state name');
+        this.skipTrivia();
+        // Optional receives clause
+        let receives = null;
+        let receivesOptional = false;
+        if (this.check(token_1.TokenType.Receives)) {
+            this.advance();
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Question)) {
+                receivesOptional = true;
+                this.advance();
+            }
+            receives = this.expectIdent('context name in receives clause');
+            this.skipTrivia();
+        }
+        this.expect(token_1.TokenType.LParen);
+        let returns = null;
+        const uses = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Returns)) {
+                returns = this.parseReturns();
+            }
+            else if (this.check(token_1.TokenType.Uses)) {
+                uses.push(...this.parseUsesBlock());
+            }
+            else if (!this.check(token_1.TokenType.RParen)) {
+                this.advance();
+            }
+        }
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'State', token: tok, module: '', name, receives, receivesOptional, returns, uses };
+    }
+    // ── Context ────────────────────────────────────────────────────────────────
+    /**
+     * Parses:
+     *   context ContextName (
+     *     field(Type),
+     *     field(Type)
+     *   )
+     */
+    parseContext() {
+        const tok = this.expect(token_1.TokenType.Context);
+        this.skipTrivia();
+        const name = this.expectIdent('context name');
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        const fields = this.parsePropList();
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'Context', token: tok, module: '', name, fields };
+    }
+    // ── Screen ─────────────────────────────────────────────────────────────────
+    /**
+     * Parses:
+     *   screen ScreenName "description" (
+     *     uses ( ... )
+     *   )
+     */
+    parseScreen() {
+        const tok = this.expect(token_1.TokenType.Screen);
+        this.skipTrivia();
+        const name = this.expectIdent('screen name');
+        this.skipTrivia();
+        const description = this.parseOptionalString();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        const uses = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Uses)) {
+                uses.push(...this.parseUsesBlock());
+            }
+            else if (!this.check(token_1.TokenType.RParen)) {
+                this.advance();
+            }
+        }
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'Screen', token: tok, module: '', name, description, uses };
+    }
+    // ── View ───────────────────────────────────────────────────────────────────
+    /**
+     * Parses:
+     *   view ViewName "description" (
+     *     props ( ... )
+     *     state ( ... )
+     *     uses ( ... )
+     *   )
+     */
+    parseView() {
+        const tok = this.expect(token_1.TokenType.View);
+        this.skipTrivia();
+        const name = this.expectIdent('view name');
+        this.skipTrivia();
+        const description = this.parseOptionalString();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        let props = [];
+        let stateFields = [];
+        const uses = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Props)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                props = this.parsePropList();
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (this.check(token_1.TokenType.State)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                stateFields = this.parsePropList();
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (this.check(token_1.TokenType.Uses)) {
+                uses.push(...this.parseUsesBlock());
+            }
+            else if (!this.check(token_1.TokenType.RParen)) {
+                this.advance();
+            }
+        }
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'View', token: tok, module: '', name, description, props, state: stateFields, uses };
+    }
+    // ── Provider ───────────────────────────────────────────────────────────────
+    /**
+     * Parses:
+     *   provider ProviderName "description" (
+     *     props ( ... )
+     *     state ( ... )
+     *     interface ( methods... )
+     *   )
+     */
+    parseProvider() {
+        const tok = this.expect(token_1.TokenType.Provider);
+        this.skipTrivia();
+        const name = this.expectIdent('provider name');
+        this.skipTrivia();
+        const description = this.parseOptionalString();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        let props = [];
+        let stateFields = [];
+        const methods = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Props)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                props = this.parsePropList();
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (this.check(token_1.TokenType.State)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                stateFields = this.parsePropList();
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (this.check(token_1.TokenType.Interface)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+                    this.skipTrivia();
+                    if (this.check(token_1.TokenType.CamelIdent)) {
+                        methods.push(this.parseMethod());
+                    }
+                    else if (!this.check(token_1.TokenType.RParen)) {
+                        this.advance();
+                    }
+                }
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (!this.check(token_1.TokenType.RParen)) {
+                this.advance();
+            }
+        }
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'Provider', token: tok, module: '', name, description, props, state: stateFields, methods };
+    }
+    // ── Adapter ────────────────────────────────────────────────────────────────
+    /**
+     * Parses:
+     *   adapter AdapterName "description" (
+     *     props ( ... )
+     *     state ( ... )
+     *     interface ( methods... )
+     *   )
+     */
+    parseAdapter() {
+        const tok = this.expect(token_1.TokenType.Adapter);
+        this.skipTrivia();
+        const name = this.expectIdent('adapter name');
+        this.skipTrivia();
+        const description = this.parseOptionalString();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        let props = [];
+        let stateFields = [];
+        const methods = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Props)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                props = this.parsePropList();
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (this.check(token_1.TokenType.State)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                stateFields = this.parsePropList();
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (this.check(token_1.TokenType.Interface)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+                    this.skipTrivia();
+                    if (this.check(token_1.TokenType.CamelIdent)) {
+                        methods.push(this.parseMethod());
+                    }
+                    else if (!this.check(token_1.TokenType.RParen)) {
+                        this.advance();
+                    }
+                }
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (!this.check(token_1.TokenType.RParen)) {
+                this.advance();
+            }
+        }
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'Adapter', token: tok, module: '', name, description, props, state: stateFields, methods };
+    }
+    // ── Interface ──────────────────────────────────────────────────────────────
+    /**
+     * Parses:
+     *   interface InterfaceName "description" (
+     *     props ( ... )
+     *     state ( ... )
+     *     uses ( ... )
+     *     methodName param(Type) returns(Type) "description"
+     *     ...
+     *   )
+     *
+     * When used as a module-level handler interface, the body contains a
+     * method declaration whose body is a series of `if` branches. The method
+     * name (e.g. `switch`) is a plain camelCase identifier — not a keyword.
+     */
+    parseInterface() {
+        const tok = this.expect(token_1.TokenType.Interface);
+        this.skipTrivia();
+        const name = this.expectIdent('interface name');
+        this.skipTrivia();
+        const description = this.parseOptionalString();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        let props = [];
+        let stateFields = [];
+        const methods = [];
+        const uses = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Props)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                props = this.parsePropList();
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (this.check(token_1.TokenType.State)) {
+                this.advance();
+                this.skipTrivia();
+                this.expect(token_1.TokenType.LParen);
+                stateFields = this.parsePropList();
+                this.expect(token_1.TokenType.RParen);
+            }
+            else if (this.check(token_1.TokenType.Uses)) {
+                uses.push(...this.parseUsesBlock());
+            }
+            else if (this.check(token_1.TokenType.CamelIdent)) {
+                // Methods appear directly in the body after props.
+                // This includes handler interface method declarations whose body
+                // contains if-branches (e.g. `switch path(string) ( if ... )`).
+                methods.push(this.parseInterfaceMethod());
+            }
+            else if (!this.check(token_1.TokenType.RParen)) {
+                this.advance();
+            }
+        }
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'Interface', token: tok, module: '', name, description, props, state: stateFields, methods, uses };
+    }
+    // ── Returns clause ─────────────────────────────────────────────────────────
+    /**
+     * Parses either the simple or expanded form of a returns clause.
+     *
+     * Simple:   returns ContextA, ContextB
+     * Expanded: returns ( ContextA ( sideEffects ) ContextB ( sideEffects ) )
+     */
+    parseReturns() {
+        const tok = this.expect(token_1.TokenType.Returns);
+        this.skipTrivia();
+        // Expanded form starts with '('
+        if (this.check(token_1.TokenType.LParen)) {
+            this.advance();
+            const entries = [];
+            while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+                this.skipTrivia();
+                if (this.check(token_1.TokenType.PascalIdent)) {
+                    const ctxTok = this.current();
+                    const contextName = this.advance().value;
+                    this.skipTrivia();
+                    const sideEffects = [];
+                    if (this.check(token_1.TokenType.LParen)) {
+                        this.advance();
+                        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+                            this.skipTrivia();
+                            if (this.checkSystemCall()) {
+                                const callTok = this.current();
+                                const call = this.parseQualifiedName();
+                                this.skipTrivia();
+                                const args = this.parseInlineArgList();
+                                sideEffects.push({ kind: 'SideEffect', token: callTok, call, args });
+                            }
+                            else if (!this.check(token_1.TokenType.RParen)) {
+                                this.advance();
+                            }
+                        }
+                        this.expect(token_1.TokenType.RParen);
+                    }
+                    entries.push({ kind: 'ExpandedReturn', token: ctxTok, contextName, sideEffects });
+                }
+                else if (!this.check(token_1.TokenType.RParen)) {
+                    this.advance();
+                }
+            }
+            this.expect(token_1.TokenType.RParen);
+            return { kind: 'ExpandedReturns', token: tok, entries };
+        }
+        // Simple form — comma-separated list of context names
+        const contexts = [];
+        if (this.check(token_1.TokenType.PascalIdent)) {
+            contexts.push(this.advance().value);
+            while (this.check(token_1.TokenType.Comma)) {
+                this.advance();
+                this.skipTrivia();
+                if (this.check(token_1.TokenType.PascalIdent)) {
+                    contexts.push(this.advance().value);
+                }
+            }
+        }
+        return { kind: 'SimpleReturns', token: tok, contexts };
+    }
+    // ── Uses block ─────────────────────────────────────────────────────────────
+    /**
+     * Parses a `uses` block and returns its entries.
+     * Handles both the single-entry form and the parenthesised list form.
+     *
+     * Single: `uses screen LoginScreen`
+     * List:   `uses ( view A, view B, if ... )`
+     */
+    parseUsesBlock() {
+        this.expect(token_1.TokenType.Uses);
+        this.skipTrivia();
+        if (this.check(token_1.TokenType.LParen)) {
+            this.advance();
+            const entries = this.parseUseEntries();
+            this.expect(token_1.TokenType.RParen);
+            return entries;
+        }
+        // Single entry without parentheses
+        const entry = this.parseUseEntry();
+        return entry ? [entry] : [];
+    }
+    /**
+     * Parses a comma-separated sequence of use entries inside a `uses ( ... )` block.
+     */
+    parseUseEntries() {
+        const entries = [];
+        let lastPos = -1;
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            if (this.pos === lastPos) {
+                this.advance();
+                continue;
+            }
+            lastPos = this.pos;
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.RParen))
+                break;
+            const entry = this.parseUseEntry();
+            if (entry)
+                entries.push(entry);
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Comma))
+                this.advance();
+        }
+        return entries;
+    }
+    /**
+     * Parses a single use entry — a component use, a conditional block, or
+     * an iteration block.
+     */
+    parseUseEntry() {
+        this.skipTrivia();
+        const tok = this.current();
+        if (this.check(token_1.TokenType.If))
+            return this.parseConditionalBlock();
+        if (this.check(token_1.TokenType.For))
+            return this.parseIterationBlock();
+        // Component kinds: screen, view, adapter, provider, interface
+        if (this.check(token_1.TokenType.Screen) ||
+            this.check(token_1.TokenType.View) ||
+            this.check(token_1.TokenType.Adapter) ||
+            this.check(token_1.TokenType.Provider) ||
+            this.check(token_1.TokenType.Interface)) {
+            return this.parseComponentUse();
+        }
+        this.error(diagnostics_1.DiagnosticCode.P_INVALID_CONSTRUCT_POSITION, `Unexpected token '${tok.value}' inside uses block`, tok);
+        this.advance();
+        return null;
+    }
+    /**
+     * Parses a single component use:
+     *   view UIModule.LoginForm ( args... uses... )
+     *   adapter SessionAdapter.checkSession
+     *   screen LoginScreen
+     */
+    parseComponentUse() {
+        const tok = this.current();
+        const componentKind = tok.value;
+        this.advance();
+        this.skipTrivia();
+        const name = this.parseQualifiedName();
+        this.skipTrivia();
+        const args = [];
+        const uses = [];
+        // Arguments and nested uses can appear either inline or in a paren block
+        if (this.check(token_1.TokenType.LParen)) {
+            this.advance();
+            // Inside the paren block: arguments and nested use entries
+            while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+                this.skipTrivia();
+                if (this.check(token_1.TokenType.Uses)) {
+                    uses.push(...this.parseUsesBlock());
+                }
+                else if (this.checkArgumentStart()) {
+                    args.push(...this.parseArguments());
+                }
+                else if (this.isUseEntry()) {
+                    const entry = this.parseUseEntry();
+                    if (entry)
+                        uses.push(entry);
+                }
+                else if (!this.check(token_1.TokenType.RParen)) {
+                    this.advance();
+                }
+            }
+            this.expect(token_1.TokenType.RParen);
+        }
+        else {
+            // Inline arguments without parens: view X key is value, key is value
+            if (this.checkArgumentStart()) {
+                args.push(...this.parseInlineArgList());
+            }
+        }
+        return { kind: 'ComponentUse', token: tok, componentKind, name, args, uses };
+    }
+    /**
+     * Parses:
+     *   if condition ( useEntries... )
+     */
+    parseConditionalBlock() {
+        const tok = this.expect(token_1.TokenType.If);
+        this.skipTrivia();
+        const condition = this.parseCondition();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.LParen);
+        const body = this.parseUseEntries();
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'ConditionalBlock', token: tok, condition, body };
+    }
+    /**
+     * Parses:
+     *   for collection as binding ( useEntries... )
+     *   for collection as key, value ( useEntries... )
+     */
+    parseIterationBlock() {
+        const tok = this.expect(token_1.TokenType.For);
+        this.skipTrivia();
+        const collection = this.parseAccessExpression();
+        this.skipTrivia();
+        this.expect(token_1.TokenType.As);
+        this.skipTrivia();
+        const bindings = [];
+        bindings.push(this.expectIdent('iteration binding'));
+        this.skipTrivia();
+        // Map iteration: two bindings separated by comma
+        if (this.check(token_1.TokenType.Comma)) {
+            this.advance();
+            this.skipTrivia();
+            bindings.push(this.expectIdent('second iteration binding'));
+            this.skipTrivia();
+        }
+        this.expect(token_1.TokenType.LParen);
+        const body = this.parseUseEntries();
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'IterationBlock', token: tok, collection, bindings, body };
+    }
+    // ── Condition ──────────────────────────────────────────────────────────────
+    /**
+     * Parses a condition expression:
+     *   state.context is AccountDeauthenticated
+     *   state.context.status is "pending"
+     *   state.context is not AccountRecovered
+     */
+    parseCondition() {
+        const tok = this.current();
+        const left = this.parseAccessExpression();
+        this.skipTrivia();
+        let operator = 'is';
+        if (this.check(token_1.TokenType.IsNot)) {
+            operator = 'is not';
+            this.advance();
+        }
+        else if (this.check(token_1.TokenType.Is)) {
+            this.advance();
+        }
+        else {
+            this.error(diagnostics_1.DiagnosticCode.P_MISSING_IS, `Expected 'is' or 'is not' in condition`, this.current());
+        }
+        this.skipTrivia();
+        const right = this.parseExpression();
+        return { kind: 'Condition', token: tok, left, operator, right };
+    }
+    // ── Arguments ──────────────────────────────────────────────────────────────
+    /**
+     * Parses a comma-separated list of `name is value` arguments.
+     * Used inside parenthesised component use bodies and system calls.
+     */
+    parseArguments() {
+        const args = [];
+        let lastPos = -1;
+        while (this.checkArgumentStart()) {
+            if (this.pos === lastPos)
+                break;
+            lastPos = this.pos;
+            args.push(this.parseArgument());
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Comma))
+                this.advance();
+            this.skipTrivia();
+        }
+        return args;
+    }
+    /**
+     * Parses a comma-separated list of inline `name is value` arguments
+     * without an enclosing paren block. Stops at newline, `)`, or EOF.
+     */
+    parseInlineArgList() {
+        const args = [];
+        while (this.checkArgumentStart()) {
+            args.push(this.parseArgument());
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Comma)) {
+                this.advance();
+                this.skipTrivia();
+            }
+            else {
+                break;
+            }
+        }
+        return args;
+    }
+    /**
+     * Parses a single argument: `name is value`
+     */
+    parseArgument() {
+        const tok = this.current();
+        const name = this.expectIdent('argument name');
+        this.skipTrivia();
+        if (!this.check(token_1.TokenType.Is)) {
+            this.error(diagnostics_1.DiagnosticCode.P_MISSING_IS, `Expected 'is' after argument name '${name}'`, this.current());
+        }
+        else {
+            this.advance();
+        }
+        this.skipTrivia();
+        const value = this.parseExpression();
+        return { kind: 'Argument', token: tok, name, value };
+    }
+    // ── Expressions ────────────────────────────────────────────────────────────
+    /**
+     * Parses an expression — a value on the right-hand side of an `is` assignment
+     * or a condition operand.
+     *
+     * Handles:
+     *   - Block expressions:          `( state.return(x) )`
+     *   - state.return():             `state.return(contextName)`
+     *   - Access expressions:         `state.context.fullName`, `props.items`
+     *   - Call expressions:           `system.getContext(SystemUser)`
+     *   - Literals:                   `"string"`, `42`, `3.14`, `true`, `false`, `[]`, `{}`
+     *   - PascalCase type references: `SystemUser` (e.g. in system.getContext(SystemUser))
+     */
+    parseExpression() {
+        const tok = this.current();
+        // Block expression: ( ... )
+        if (this.check(token_1.TokenType.LParen)) {
+            return this.parseBlockExpression();
+        }
+        // Literals
+        if (this.check(token_1.TokenType.StringLit))
+            return this.parseStringLiteral();
+        if (this.check(token_1.TokenType.IntegerLit))
+            return this.parseIntegerLiteral();
+        if (this.check(token_1.TokenType.FloatLit))
+            return this.parseFloatLiteral();
+        if (this.check(token_1.TokenType.BooleanLit))
+            return this.parseBooleanLiteral();
+        if (this.checkListLiteral())
+            return this.parseListLiteral();
+        if (this.checkMapLiteral())
+            return this.parseMapLiteral();
+        // PascalCase identifier — type reference as argument value
+        // e.g. system.getContext(SystemUser)
+        if (this.check(token_1.TokenType.PascalIdent)) {
+            return {
+                kind: 'AccessExpression',
+                token: tok,
+                path: [this.advance().value],
+            };
+        }
+        // Access expression or call expression starting with a camelCase name,
+        // 'state', or 'system'
+        if (this.check(token_1.TokenType.CamelIdent) ||
+            this.check(token_1.TokenType.State) ||
+            this.check(token_1.TokenType.System)) {
+            return this.parseAccessOrCall();
+        }
+        // Fallback — emit error and return a dummy access expression
+        this.error(diagnostics_1.DiagnosticCode.P_UNEXPECTED_TOKEN, `Unexpected token '${tok.value}' in expression`, tok);
+        this.advance();
+        return { kind: 'AccessExpression', token: tok, path: ['?'] };
+    }
+    /**
+     * Parses a block expression: `( statements... )`
+     * The body contains either state.return() calls or assignment statements.
+     */
+    parseBlockExpression() {
+        const tok = this.expect(token_1.TokenType.LParen);
+        const statements = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.RParen))
+                break;
+            const stmt = this.parseStatement();
+            if (stmt)
+                statements.push(stmt);
+            this.skipTrivia();
+        }
+        this.expect(token_1.TokenType.RParen);
+        return { kind: 'BlockExpression', token: tok, statements };
+    }
+    /**
+     * Parses a statement inside a block expression body.
+     *
+     * `state.return(contextName)` → StateReturnStatement
+     * `state.fieldName is value`  → AssignmentStatement
+     */
+    parseStatement() {
+        const tok = this.current();
+        if (this.check(token_1.TokenType.State)) {
+            this.advance(); // consume 'state'
+            this.skipTrivia();
+            this.expect(token_1.TokenType.Dot);
+            this.skipTrivia();
+            // state.return(contextName)
+            if (this.check(token_1.TokenType.CamelIdent) && this.current().value === 'return') {
+                this.advance(); // consume 'return'
+                this.expect(token_1.TokenType.LParen);
+                this.skipTrivia();
+                const contextName = this.expectIdent('context name in state.return()');
+                this.skipTrivia();
+                this.expect(token_1.TokenType.RParen);
+                return { kind: 'StateReturnStatement', token: tok, contextName };
+            }
+            // state.fieldName is value — assignment
+            const fieldName = this.expectIdent('state field name');
+            this.skipTrivia();
+            this.expect(token_1.TokenType.Is);
+            this.skipTrivia();
+            const value = this.parseExpression();
+            const target = { kind: 'AccessExpression', token: tok, path: ['state', fieldName] };
+            return { kind: 'AssignmentStatement', token: tok, target, value };
+        }
+        // Unknown statement — skip
+        this.error(diagnostics_1.DiagnosticCode.P_UNEXPECTED_TOKEN, `Unexpected token '${tok.value}' in block`, tok);
+        this.advance();
+        return null;
+    }
+    /**
+     * Parses an access expression or call expression starting with a camelCase
+     * name, 'state', or 'system'.
+     *
+     * If the path ends with `(...)`, it becomes a CallExpression.
+     * If the path ends with `return(...)`, it becomes a StateReturnExpression.
+     */
+    parseAccessOrCall() {
+        const tok = this.current();
+        const path = [];
+        // Consume the first segment
+        path.push(this.advance().value);
+        // Follow dot-separated segments
+        while (this.check(token_1.TokenType.Dot)) {
+            this.advance(); // consume '.'
+            if (this.check(token_1.TokenType.CamelIdent) ||
+                this.check(token_1.TokenType.PascalIdent) ||
+                this.check(token_1.TokenType.State) ||
+                this.check(token_1.TokenType.System) ||
+                this.check(token_1.TokenType.Context) ||
+                this.check(token_1.TokenType.Returns)) {
+                path.push(this.advance().value);
+            }
+            else {
+                break;
+            }
+        }
+        // state.return(contextName) — special form
+        if (path[0] === 'state' && path[1] === 'return' && this.check(token_1.TokenType.LParen)) {
+            this.advance(); // consume '('
+            this.skipTrivia();
+            const contextName = this.expectIdent('context name in state.return()');
+            this.skipTrivia();
+            this.expect(token_1.TokenType.RParen);
+            return { kind: 'StateReturnExpression', token: tok, contextName };
+        }
+        // Call expression: path(args...)
+        // Supports both keyword-style args (`name is value`) and a single positional
+        // PascalIdent type reference (e.g. `system.getContext(SystemUser)`).
+        if (this.check(token_1.TokenType.LParen)) {
+            this.advance(); // consume '('
+            const args = this.parseArguments();
+            if (args.length === 0 && this.check(token_1.TokenType.PascalIdent)) {
+                const valTok = this.current();
+                const valName = this.advance().value;
+                const value = { kind: 'AccessExpression', token: valTok, path: [valName] };
+                args.push({ kind: 'Argument', token: valTok, name: '', value });
+            }
+            this.expect(token_1.TokenType.RParen);
+            const callee = { kind: 'AccessExpression', token: tok, path };
+            return { kind: 'CallExpression', token: tok, callee, args };
+        }
+        // Plain access expression
+        return { kind: 'AccessExpression', token: tok, path };
+    }
+    /**
+     * Parses a dot-separated access path — always returns an AccessExpressionNode.
+     * Used in conditions and iteration blocks where a call is not expected.
+     */
+    parseAccessExpression() {
+        const tok = this.current();
+        const path = [];
+        path.push(this.advance().value);
+        while (this.check(token_1.TokenType.Dot)) {
+            this.advance();
+            if (this.check(token_1.TokenType.CamelIdent) ||
+                this.check(token_1.TokenType.PascalIdent) ||
+                this.check(token_1.TokenType.State) ||
+                this.check(token_1.TokenType.System) ||
+                this.check(token_1.TokenType.Context)) {
+                path.push(this.advance().value);
+            }
+            else {
+                break;
+            }
+        }
+        return { kind: 'AccessExpression', token: tok, path };
+    }
+    // ── Literals ───────────────────────────────────────────────────────────────
+    parseStringLiteral() {
+        const tok = this.advance();
+        // Strip surrounding quotes from the raw token value
+        const value = tok.value.slice(1, -1);
+        return { kind: 'StringLiteral', token: tok, value };
+    }
+    parseIntegerLiteral() {
+        const tok = this.advance();
+        return { kind: 'IntegerLiteral', token: tok, value: parseInt(tok.value, 10) };
+    }
+    parseFloatLiteral() {
+        const tok = this.advance();
+        return { kind: 'FloatLiteral', token: tok, value: parseFloat(tok.value) };
+    }
+    parseBooleanLiteral() {
+        const tok = this.advance();
+        return { kind: 'BooleanLiteral', token: tok, value: tok.value === 'true' };
+    }
+    parseListLiteral() {
+        const tok = this.current();
+        this.advance(); // '['
+        this.advance(); // ']'
+        return { kind: 'ListLiteral', token: tok, elements: [] };
+    }
+    parseMapLiteral() {
+        const tok = this.current();
+        this.advance(); // '{'
+        this.advance(); // '}'
+        return { kind: 'MapLiteral', token: tok, entries: [] };
+    }
+    // ── Props ──────────────────────────────────────────────────────────────────
+    /**
+     * Parses a comma-separated list of prop declarations inside a `props` or
+     * `state` or `context` block. Stops at `)` or EOF.
+     *
+     * Forms:
+     *   `name(Type)`                  — typed data prop
+     *   `name(Type) is default`       — typed prop with default value
+     *   `name argName(Type)`          — interaction prop with argument variable
+     *   `name`                        — interaction prop with no payload
+     *   `?name(Type)`                 — optional typed prop (in context fields)
+     */
+    parsePropList() {
+        const props = [];
+        while (!this.check(token_1.TokenType.RParen) && !this.check(token_1.TokenType.EOF)) {
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.RParen))
+                break;
+            const tok = this.current();
+            let optional = false;
+            if (this.check(token_1.TokenType.Question)) {
+                optional = true;
+                this.advance();
+            }
+            if (!this.check(token_1.TokenType.CamelIdent))
+                break;
+            const name = this.advance().value;
+            this.skipTrivia();
+            let type = null;
+            let argName = null;
+            let defaultValue = null;
+            if (this.check(token_1.TokenType.LParen)) {
+                // name(Type) — direct type annotation
+                this.advance();
+                type = this.parseType();
+                this.expect(token_1.TokenType.RParen);
+                optional = optional || (type.kind === 'NamedType' && type.optional);
+            }
+            else if (this.check(token_1.TokenType.CamelIdent)) {
+                // name argName(Type) — interaction prop with argument variable
+                argName = this.advance().value;
+                this.skipTrivia();
+                if (this.check(token_1.TokenType.LParen)) {
+                    this.advance();
+                    type = this.parseType();
+                    this.expect(token_1.TokenType.RParen);
+                }
+            }
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Is)) {
+                this.advance();
+                this.skipTrivia();
+                defaultValue = this.parseLiteralValue();
+            }
+            props.push({ kind: 'Prop', token: tok, name, type, optional, defaultValue, argName });
+            this.skipTrivia();
+            if (this.check(token_1.TokenType.Comma))
+                this.advance();
+        }
+        return props;
+    }
+    // ── Types ──────────────────────────────────────────────────────────────────
+    /**
+     * Parses a type annotation. Called when the cursor is on the type keyword or name.
+     */
+    parseType() {
+        const tok = this.current();
+        if (this.check(token_1.TokenType.TList)) {
+            this.advance();
+            this.expect(token_1.TokenType.LParen);
+            const elementType = this.parseType();
+            this.expect(token_1.TokenType.RParen);
+            return { kind: 'ListType', token: tok, elementType };
+        }
+        if (this.check(token_1.TokenType.TMap)) {
+            this.advance();
+            this.expect(token_1.TokenType.LParen);
+            const keyType = this.parseType();
+            this.expect(token_1.TokenType.Comma);
+            this.skipTrivia();
+            const valueType = this.parseType();
+            this.expect(token_1.TokenType.RParen);
+            return { kind: 'MapType', token: tok, keyType, valueType };
+        }
+        // Primitive types
+        // Note: the lexer maps the word 'context' to TokenType.Context (the construct
+        // keyword token), never to TContext. We accept both here so 'context' works
+        // as a type in system interface methods (e.g. returns(context)).
+        const primitiveMap = {
+            [token_1.TokenType.TString]: 'string',
+            [token_1.TokenType.TInteger]: 'integer',
+            [token_1.TokenType.TFloat]: 'float',
+            [token_1.TokenType.TBoolean]: 'boolean',
+            [token_1.TokenType.TContext]: 'context',
+            [token_1.TokenType.Context]: 'context',
+        };
+        if (tok.type in primitiveMap) {
+            this.advance();
+            return { kind: 'PrimitiveType', token: tok, name: primitiveMap[tok.type] };
+        }
+        // Optional named type: ?Product
+        let optional = false;
+        if (this.check(token_1.TokenType.Question)) {
+            optional = true;
+            this.advance();
+        }
+        if (this.check(token_1.TokenType.PascalIdent)) {
+            const name = this.advance().value;
+            return { kind: 'NamedType', token: tok, name, optional };
+        }
+        this.error(diagnostics_1.DiagnosticCode.P_MISSING_TYPE, `Expected a type`, tok);
+        return { kind: 'NamedType', token: tok, name: '?', optional: false };
+    }
+    // ── Methods ────────────────────────────────────────────────────────────────
+    /**
+     * Parses a standard method declaration in a provider, adapter, or interface body.
+     * Delegates to `parseInterfaceMethod` which also handles handler method bodies.
+     */
+    parseMethod() {
+        return this.parseInterfaceMethod();
+    }
+    /**
+     * Parses a method declaration that may optionally have a body block of
+     * `if` branches — used for handler interface method declarations.
+     *
+     * Forms:
+     *   `methodName "description"`
+     *   `methodName param(Type) returns(Type) "description"`
+     *   `methodName param(Type) ( if param is "/path" enter State "narrative" )`
+     */
+    parseInterfaceMethod() {
+        const tok = this.current();
+        const name = this.advance().value; // camelIdent
+        this.skipTrivia();
+        const params = [];
+        let returnType = null;
+        let description = null;
+        // Parse parameters: paramName(Type) ...
+        while (this.check(token_1.TokenType.CamelIdent)) {
+            const paramTok = this.current();
+            const paramName = this.advance().value;
+            this.skipTrivia();
+            let paramType = null;
+            if (this.check(token_1.TokenType.LParen)) {
+                this.advance();
+                paramType = this.parseType();
+                this.expect(token_1.TokenType.RParen);
+            }
+            params.push({ kind: 'Prop', token: paramTok, name: paramName, type: paramType, optional: false, defaultValue: null, argName: null });
+            this.skipTrivia();
+        }
+        // Handler interface method body: ( if ... enter ... )
+        // Consume and discard — the body is structural metadata, not executable logic.
+        if (this.check(token_1.TokenType.LParen)) {
+            this.advance();
+            let depth = 1;
+            while (!this.check(token_1.TokenType.EOF) && depth > 0) {
+                if (this.check(token_1.TokenType.LParen))
+                    depth++;
+                else if (this.check(token_1.TokenType.RParen))
+                    depth--;
+                if (depth > 0)
+                    this.advance();
+            }
+            this.expect(token_1.TokenType.RParen);
+            return { kind: 'Method', token: tok, name, params, returnType: null, description: null };
+        }
+        // Optional returns(Type)
+        if (this.check(token_1.TokenType.Returns)) {
+            this.advance();
+            this.expect(token_1.TokenType.LParen);
+            returnType = this.parseType();
+            this.expect(token_1.TokenType.RParen);
+            this.skipTrivia();
+        }
+        // Optional description string
+        if (this.check(token_1.TokenType.StringLit)) {
+            description = this.advance().value.slice(1, -1);
+        }
+        return { kind: 'Method', token: tok, name, params, returnType, description };
+    }
+    // ── Qualified name ─────────────────────────────────────────────────────────
+    /**
+     * Parses a dot-separated qualified name.
+     * e.g. `UIModule.LoginForm`, `system.setContext`, `SessionAdapter.checkSession`
+     */
+    parseQualifiedName() {
+        const tok = this.current();
+        const parts = [];
+        if (this.check(token_1.TokenType.PascalIdent) ||
+            this.check(token_1.TokenType.CamelIdent) ||
+            this.check(token_1.TokenType.System) ||
+            this.check(token_1.TokenType.State)) {
+            parts.push(this.advance().value);
+        }
+        while (this.check(token_1.TokenType.Dot)) {
+            this.advance();
+            if (this.check(token_1.TokenType.PascalIdent) ||
+                this.check(token_1.TokenType.CamelIdent) ||
+                this.check(token_1.TokenType.State) ||
+                this.check(token_1.TokenType.System)) {
+                parts.push(this.advance().value);
+            }
+            else {
+                break;
+            }
+        }
+        return { kind: 'QualifiedName', token: tok, parts };
+    }
+    // ── Literal value (for defaults) ───────────────────────────────────────────
+    /**
+     * Parses a literal value used as a default in a prop or state declaration.
+     * Handles strings, integers, floats, booleans, `[]`, and `{}`.
+     */
+    parseLiteralValue() {
+        const tok = this.current();
+        if (this.check(token_1.TokenType.StringLit))
+            return this.parseStringLiteral();
+        if (this.check(token_1.TokenType.IntegerLit))
+            return this.parseIntegerLiteral();
+        if (this.check(token_1.TokenType.FloatLit))
+            return this.parseFloatLiteral();
+        if (this.check(token_1.TokenType.BooleanLit))
+            return this.parseBooleanLiteral();
+        if (this.checkListLiteral())
+            return this.parseListLiteral();
+        if (this.checkMapLiteral())
+            return this.parseMapLiteral();
+        this.error(diagnostics_1.DiagnosticCode.P_UNEXPECTED_TOKEN, `Expected a literal value`, tok);
+        this.advance();
+        return { kind: 'StringLiteral', token: tok, value: '' };
+    }
+    // ── Token stream helpers ───────────────────────────────────────────────────
+    /** Returns the token at the current position. */
+    current() {
+        return this.tokens[this.pos] ?? this.tokens[this.tokens.length - 1];
+    }
+    /** Returns true if the current token has the given type. */
+    check(type) {
+        return this.current().type === type;
+    }
+    /**
+     * Consumes and returns the current token, advancing the position.
+     */
+    advance() {
+        const tok = this.current();
+        if (tok.type !== token_1.TokenType.EOF)
+            this.pos++;
+        return tok;
+    }
+    /**
+     * Consumes the current token if it matches `type` and returns it.
+     * If it does not match, emits a diagnostic and returns null without advancing.
+     */
+    expect(type) {
+        if (this.check(type))
+            return this.advance();
+        const tok = this.current();
+        this.error(diagnostics_1.DiagnosticCode.P_UNEXPECTED_TOKEN, `Expected '${type}' but found '${tok.value}'`, tok);
+        return null;
+    }
+    /**
+     * Consumes a PascalIdent or CamelIdent and returns its value.
+     * Emits a diagnostic if neither is present.
+     */
+    expectIdent(context) {
+        if (this.check(token_1.TokenType.PascalIdent) || this.check(token_1.TokenType.CamelIdent)) {
+            return this.advance().value;
+        }
+        const tok = this.current();
+        this.error(diagnostics_1.DiagnosticCode.P_MISSING_IDENTIFIER, `Expected identifier (${context}) but found '${tok.value}'`, tok);
+        return '?';
+    }
+    /**
+     * Consumes and returns the string value if the current token is a StringLit.
+     * Returns null without advancing if it is not.
+     */
+    parseOptionalString() {
+        if (this.check(token_1.TokenType.StringLit)) {
+            const val = this.advance().value;
+            return val.slice(1, -1);
+        }
+        return null;
+    }
+    /**
+     * Skips comment tokens only.
+     */
+    skipComments() {
+        while (this.check(token_1.TokenType.Comment))
+            this.advance();
+    }
+    /**
+     * Skips comments and newlines — the whitespace between meaningful tokens.
+     */
+    skipTrivia() {
+        while (this.check(token_1.TokenType.Comment) || this.check(token_1.TokenType.Newline))
+            this.advance();
+    }
+    /**
+     * Returns true if the current token looks like a system.* call.
+     */
+    checkSystemCall() {
+        return this.check(token_1.TokenType.System);
+    }
+    /**
+     * Returns true if the current token can start an argument (`name is value`).
+     * Arguments start with a camelCase identifier.
+     */
+    checkArgumentStart() {
+        return this.check(token_1.TokenType.CamelIdent);
+    }
+    /**
+     * Returns true if the current token can start a use entry (component kind,
+     * if, or for).
+     */
+    isUseEntry() {
+        return (this.check(token_1.TokenType.View) ||
+            this.check(token_1.TokenType.Screen) ||
+            this.check(token_1.TokenType.Adapter) ||
+            this.check(token_1.TokenType.Provider) ||
+            this.check(token_1.TokenType.Interface) ||
+            this.check(token_1.TokenType.If) ||
+            this.check(token_1.TokenType.For));
+    }
+    /**
+     * Returns true if the current two tokens form a `[` `]` list literal.
+     * The lexer does not produce bracket tokens — `[]` is detected by checking
+     * for an Unknown token with value `[` followed by one with value `]`.
+     */
+    checkListLiteral() {
+        return (this.current().type === token_1.TokenType.Unknown &&
+            this.current().value === '[' &&
+            this.tokens[this.pos + 1]?.value === ']');
+    }
+    /**
+     * Returns true if the current two tokens form a `{` `}` map literal.
+     */
+    checkMapLiteral() {
+        return (this.current().type === token_1.TokenType.Unknown &&
+            this.current().value === '{' &&
+            this.tokens[this.pos + 1]?.value === '}');
+    }
+    /**
+     * Parses a system.* call expression appearing at the statement level
+     * (e.g. inside a module body or a uses block).
+     */
+    parseSystemCall() {
+        const tok = this.current();
+        const callee = this.parseAccessExpression();
+        this.skipTrivia();
+        const args = this.parseInlineArgList();
+        return { kind: 'CallExpression', token: tok, callee, args };
+    }
+    // ── Error recovery ─────────────────────────────────────────────────────────
+    /**
+     * Emits a diagnostic at the given token's position.
+     */
+    error(code, message, tok) {
+        const range = (0, diagnostics_1.rangeFromToken)(tok.line, tok.column, tok.value.length || 1);
+        this.diagnostics.push((0, diagnostics_1.parseDiagnostic)(code, message, 'error', range));
+    }
+    /**
+     * Advances past tokens until a safe synchronisation point is found.
+     * Used after an unrecoverable parse error to resume at the next construct.
+     * Synchronisation points: top-level keyword, closing paren, or EOF.
+     */
+    synchronise() {
+        while (!this.check(token_1.TokenType.EOF)) {
+            switch (this.current().type) {
+                case token_1.TokenType.System:
+                case token_1.TokenType.Module:
+                case token_1.TokenType.State:
+                case token_1.TokenType.Context:
+                case token_1.TokenType.Screen:
+                case token_1.TokenType.View:
+                case token_1.TokenType.Provider:
+                case token_1.TokenType.Adapter:
+                case token_1.TokenType.Interface:
+                case token_1.TokenType.RParen:
+                    return;
+                default:
+                    this.advance();
+            }
+        }
+    }
+}
+exports.Parser = Parser;
+//# sourceMappingURL=parser.js.map