redscript-mc 2.5.0 → 2.6.2

package/dist/src/lsp/server.js

@@ -9,9 +9,45 @@
  *   - Go-to-definition (functions, variables)
  *   - Completion (keywords, functions, builtins)
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_1 = require("vscode-languageserver/node");
 const vscode_languageserver_textdocument_1 = require("vscode-languageserver-textdocument");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const url_1 = require("url");
 const lexer_1 = require("../lexer");
 const parser_1 = require("../parser");
 const typechecker_1 = require("../typechecker");
@@ -22,6 +58,90 @@ const metadata_1 = require("../builtins/metadata");
 // ---------------------------------------------------------------------------
 const connection = (0, node_1.createConnection)(node_1.ProposedFeatures.all);
 const documents = new node_1.TextDocuments(vscode_languageserver_textdocument_1.TextDocument);
+// ---------------------------------------------------------------------------
+// Builtin metadata: augment BUILTIN_METADATA from builtins.d.mcrs if present
+// ---------------------------------------------------------------------------
+/**
+ * Parse builtins.d.mcrs for `declare fn` entries and extract doc/param info.
+ * This ensures LSP hover covers every declared builtin even if metadata.ts
+ * is not yet updated.
+ */
+function loadBuiltinsFromDeclFile() {
+    const extra = {};
+    // Candidate paths: next to server.ts (dev), or next to the package root
+    const candidates = [
+        path.resolve(__dirname, '../../builtins.d.mcrs'),
+        path.resolve(__dirname, '../../../builtins.d.mcrs'),
+        path.resolve(__dirname, '../../../../builtins.d.mcrs'),
+    ];
+    let src = '';
+    for (const p of candidates) {
+        if (fs.existsSync(p)) {
+            src = fs.readFileSync(p, 'utf-8');
+            break;
+        }
+    }
+    if (!src)
+        return extra;
+    const lines = src.split('\n');
+    let docLines = [];
+    let paramDocs = {};
+    for (const line of lines) {
+        const tripleDoc = line.match(/^\/\/\/\s?(.*)$/);
+        if (tripleDoc) {
+            const content = tripleDoc[1];
+            const paramMatch = content.match(/^@param\s+(\w+)\s+(.+)$/);
+            if (paramMatch) {
+                paramDocs[paramMatch[1]] = paramMatch[2];
+            }
+            else if (!content.startsWith('@example')) {
+                docLines.push(content);
+            }
+            continue;
+        }
+        const declMatch = line.match(/^declare fn (\w+)\(([^)]*)\):\s*(\w+);?$/);
+        if (declMatch) {
+            const [, fnName, paramsStr, retType] = declMatch;
+            // Only add if not already in BUILTIN_METADATA
+            if (!ALL_BUILTINS[fnName]) {
+                const params = paramsStr.trim()
+                    ? paramsStr.split(',').map(p => {
+                        const [pname, ptype] = p.trim().split(':').map(s => s.trim());
+                        return {
+                            name: pname ?? '',
+                            type: ptype ?? 'string',
+                            required: true,
+                            doc: paramDocs[pname ?? ''] ?? '',
+                            docZh: '',
+                        };
+                    })
+                    : [];
+                extra[fnName] = {
+                    name: fnName,
+                    params,
+                    returns: (retType === 'void' || retType === 'int' || retType === 'bool' || retType === 'string')
+                        ? retType : 'void',
+                    doc: docLines.join(' ').trim(),
+                    docZh: '',
+                    examples: [],
+                    category: 'builtin',
+                };
+            }
+            docLines = [];
+            paramDocs = {};
+            continue;
+        }
+        // Non-comment, non-declare line resets doc accumulator
+        if (line.trim() && !line.startsWith('//')) {
+            docLines = [];
+            paramDocs = {};
+        }
+    }
+    return extra;
+}
+const EXTRA_BUILTINS = loadBuiltinsFromDeclFile();
+/** Combined lookup: metadata.ts entries + anything declared in builtins.d.mcrs */
+const ALL_BUILTINS = { ...EXTRA_BUILTINS, ...metadata_1.BUILTIN_METADATA };
 const parsedDocs = new Map();
 // ---------------------------------------------------------------------------
 // Helpers
@@ -46,14 +166,21 @@ function parseDocument(uri, source) {
     const errors = [];
     let program = null;
     try {
-        const lexer = new lexer_1.Lexer(source);
+        // Strip path-based imports ("import "stdlib/xxx.mcrs"") before parsing,
+        // since the Parser only understands import module::symbol syntax.
+        // These are handled at compile time by pre-processing, not by the parser.
+        const strippedSource = source.replace(/^import\s+"[^"]*"\s*;?\s*$/gm, '// (import stripped for LSP)');
+        const lexer = new lexer_1.Lexer(strippedSource);
         const tokens = lexer.tokenize();
-        const parser = new parser_1.Parser(tokens, source, uri);
+        const parser = new parser_1.Parser(tokens, strippedSource, uri);
         program = parser.parse('redscript');
         // Type-check (warn mode — collects errors but doesn't throw)
-        const checker = new typechecker_1.TypeChecker(source, uri);
-        const typeErrors = checker.check(program);
-        errors.push(...typeErrors);
+        try {
+            const checker = new typechecker_1.TypeChecker(source, uri);
+            const typeErrors = checker.check(program);
+            errors.push(...typeErrors);
+        }
+        catch { /* type errors are non-fatal; keep the parsed program */ }
     }
     catch (err) {
         if (err instanceof diagnostics_1.DiagnosticError) {
@@ -86,18 +213,18 @@ function toDiagnostic(err) {
 // Decorator hover docs
 // ---------------------------------------------------------------------------
 const DECORATOR_DOCS = {
-    tick: 'Runs every MC game tick (~20 Hz). No arguments.',
-    load: 'Runs on `/reload`. Use for initialization logic.',
-    coroutine: 'Splits loops into tick-spread continuations. Arg: `batch=N` (steps per tick, default 1).',
-    schedule: 'Schedules the function to run after N ticks. Arg: `ticks=N`.',
-    on_trigger: 'Runs when a trigger scoreboard objective is set by a player. Arg: trigger name.',
-    keep: 'Prevents the compiler from dead-code-eliminating this function.',
-    on: 'Generic event handler decorator.',
-    on_advancement: 'Runs when a player earns an advancement. Arg: advancement id.',
-    on_craft: 'Runs when a player crafts an item. Arg: item id.',
-    on_death: 'Runs when a player dies.',
-    on_join_team: 'Runs when a player joins a team. Arg: team name.',
-    on_login: 'Runs when a player logs in.',
+    tick: 'Runs every game tick.\n\n**Optional args:** `rate=N` (every N ticks, e.g. `@tick(rate=20)` = once per second)\n\nExample: `@tick fn every_tick() {}` or `@tick(rate=20) fn every_second() {}`',
+    load: 'Runs once on `/reload`. Use for initialization.\n\nExample: `@load fn init() { scoreboard_create(...) }`',
+    coroutine: 'Wraps a loop to spread execution across multiple ticks.\n\n**Required arg:** `batch=N` — iterations per tick.\n\nExample: `@coroutine(batch=10) fn scan_blocks() { for i in 0..1000 { ... } }`',
+    schedule: 'Schedules the function to run after a delay.\n\n**Required arg:** `ticks=N`\n\nExample: `@schedule(ticks=100) fn delayed() {}`',
+    on_trigger: 'Runs when a player executes `/trigger <name>`.\n\n**Required arg:** trigger objective name.\n\nExample: `@on_trigger("shop") fn open_shop() {}`',
+    keep: 'Prevents dead-code elimination. Use for exported entry points not referenced in the same file.\n\nExample: `@keep fn public_api() {}`',
+    on: 'Generic event handler. Arg: event name.\n\nExample: `@on("custom:event") fn handler() {}`',
+    on_advancement: 'Runs when a player earns an advancement.\n\n**Arg:** advancement id (e.g. `"story/mine_diamond"`).\n\nExample: `@on_advancement("story/mine_diamond") fn reward() {}`',
+    on_craft: 'Runs when a player crafts an item.\n\n**Arg:** item id (e.g. `"minecraft:diamond_sword"`).\n\nExample: `@on_craft("minecraft:diamond_sword") fn on_craft_sword() {}`',
+    on_death: 'Runs when a player dies.\n\nExample: `@on_death fn on_player_death() {}`',
+    on_join_team: 'Runs when a player joins a team.\n\n**Arg:** team name.\n\nExample: `@on_join_team("red") fn joined_red() {}`',
+    on_login: 'Runs when a player logs into the server.\n\nExample: `@on_login fn welcome() { tell(@s, f"Welcome back!") }`',
 };
 // ---------------------------------------------------------------------------
 // Hover helpers
@@ -142,6 +269,63 @@ function formatFnSignature(fn) {
 // Go-to-definition helpers
 // ---------------------------------------------------------------------------
 /** Build a mapping from identifier name → definition location. */
+/**
+ * Extract the leading doc comment (/** ... *\/) immediately before a function
+ * declaration, returning it as plain text (tags stripped).
+ */
+function extractDocComment(source, fn) {
+    if (!fn.span)
+        return null;
+    const lines = source.split('\n');
+    // fn.span.line is 1-based; scan upward from fn declaration line
+    let endLine = fn.span.line - 2; // 0-based index of line before fn
+    if (endLine < 0)
+        return null;
+    // Skip blank lines
+    while (endLine >= 0 && lines[endLine].trim() === '')
+        endLine--;
+    if (endLine < 0)
+        return null;
+    // Case 1: /** ... */ block comment
+    if (lines[endLine].trim().endsWith('*/')) {
+        let startLine = endLine;
+        while (startLine >= 0 && !lines[startLine].trim().startsWith('/**'))
+            startLine--;
+        if (startLine < 0)
+            return null;
+        const commentLines = lines.slice(startLine, endLine + 1);
+        return commentLines
+            .map(l => l.replace(/^\s*\/\*\*\s?/, '').replace(/^\s*\*\/\s?$/, '').replace(/^\s*\*\s?/, '').trimEnd())
+            .filter(l => l.length > 0)
+            .join('\n') || null;
+    }
+    // Case 2: consecutive // or /// line comments
+    if (lines[endLine].trim().startsWith('//')) {
+        let startLine = endLine;
+        while (startLine > 0 && lines[startLine - 1].trim().startsWith('//'))
+            startLine--;
+        return lines.slice(startLine, endLine + 1)
+            .map(l => l.replace(/^\s*\/\/\/?\/?\s?/, '').trimEnd())
+            .filter(l => l.length > 0)
+            .join('\n') || null;
+    }
+    return null;
+}
+/**
+ * Find which function declaration contains the given 1-based line number.
+ * Uses the next fn's start line as the implicit end when span.endLine is missing.
+ */
+function findEnclosingFn(program, curLine) {
+    const fns = program.declarations.filter(f => f.span);
+    for (let i = 0; i < fns.length; i++) {
+        const fn = fns[i];
+        const startLine = fn.span.line;
+        const endLine = fn.span.endLine ?? (fns[i + 1]?.span?.line ? fns[i + 1].span.line - 1 : Infinity);
+        if (curLine >= startLine && curLine <= endLine)
+            return fn;
+    }
+    return null;
+}
 function buildDefinitionMap(program, source) {
     const map = new Map();
     for (const fn of program.declarations) {
@@ -184,19 +368,41 @@ const KEYWORD_COMPLETIONS = [
     kind: node_1.CompletionItemKind.Keyword,
 }));
 const TYPE_COMPLETIONS = [
-    'int', 'bool', 'float', 'string', 'void', 'BlockPos', 'byte', 'short', 'long', 'double',
+    'int', 'bool', 'fixed', 'float', 'string', 'void', 'BlockPos', 'byte', 'short', 'long', 'double',
     'entity', 'Player', 'Mob', 'HostileMob', 'PassiveMob',
     'Zombie', 'Skeleton', 'Creeper', 'Spider', 'Enderman',
 ].map(t => ({
     label: t,
     kind: node_1.CompletionItemKind.TypeParameter,
 }));
+// Decorator completions — triggered when '@' is typed at line start context.
+// insertText is the full token WITHOUT '@' because '@' is already on screen.
+// VSCode will keep the completion open as user types more letters (filter by label).
 const DECORATOR_COMPLETIONS = [
-    '@tick', '@load', '@on', '@coroutine', '@keep',
-].map(d => ({
-    label: d,
-    kind: node_1.CompletionItemKind.Event,
-}));
+    { label: '@tick', detail: 'Run every game tick (~20 Hz)', insertText: 'tick' },
+    { label: '@load', detail: 'Run on /reload (initialization)', insertText: 'load' },
+    { label: '@on_trigger', detail: 'Run when a player uses /trigger', insertText: 'on_trigger' },
+    { label: '@schedule', detail: 'Schedule function after N ticks', insertText: 'schedule' },
+    { label: '@coroutine', detail: 'Spread loop across ticks (batch=N)', insertText: 'coroutine' },
+    { label: '@keep', detail: 'Prevent dead-code elimination', insertText: 'keep' },
+    { label: '@on', detail: 'Generic event handler', insertText: 'on' },
+    { label: '@on_advancement', detail: 'Run on advancement earned', insertText: 'on_advancement' },
+    { label: '@on_craft', detail: 'Run on item craft', insertText: 'on_craft' },
+    { label: '@on_death', detail: 'Run on player death', insertText: 'on_death' },
+    { label: '@on_join_team', detail: 'Run on team join', insertText: 'on_join_team' },
+    { label: '@on_login', detail: 'Run on player login', insertText: 'on_login' },
+    { label: '@require_on_load', detail: 'Ensure a fn runs on load (stdlib)', insertText: 'require_on_load' },
+].map(d => ({ ...d, kind: node_1.CompletionItemKind.Event }));
+/** Entity selector completions triggered by @ inside expressions.
+ *  insertText is without '@' (already typed). label has '@' for display. */
+const SELECTOR_COMPLETIONS = [
+    { label: '@a', insertText: 'a', kind: node_1.CompletionItemKind.Value, detail: 'All players', documentation: 'Targets all online players.' },
+    { label: '@p', insertText: 'p', kind: node_1.CompletionItemKind.Value, detail: 'Nearest player', documentation: 'Targets the nearest player to the command source.' },
+    { label: '@s', insertText: 's', kind: node_1.CompletionItemKind.Value, detail: 'Executing entity', documentation: 'Targets the entity currently executing the command.' },
+    { label: '@e', insertText: 'e', kind: node_1.CompletionItemKind.Value, detail: 'All entities', documentation: 'Targets all entities (use [type=...] to filter).' },
+    { label: '@r', insertText: 'r', kind: node_1.CompletionItemKind.Value, detail: 'Random player', documentation: 'Targets a random online player.' },
+    { label: '@n', insertText: 'n', kind: node_1.CompletionItemKind.Value, detail: 'Nearest entity', documentation: 'Targets the nearest entity (any type).' },
+];
 const BUILTIN_FN_COMPLETIONS = [
     'say', 'tell', 'give', 'kill', 'teleport', 'summon', 'setblock',
     'fill', 'clone', 'effect', 'enchant', 'experience', 'gamemode',
@@ -220,6 +426,12 @@ connection.onInitialize((_params) => {
                 triggerCharacters: ['.', '@'],
                 resolveProvider: false,
             },
+            signatureHelpProvider: {
+                triggerCharacters: ['(', ','],
+            },
+            referencesProvider: true,
+            renameProvider: true,
+            inlayHintProvider: true,
         },
         serverInfo: {
             name: 'redscript-lsp',
@@ -253,35 +465,77 @@ connection.onHover((params) => {
     if (!doc)
         return null;
     const source = doc.getText();
-    const cached = parsedDocs.get(params.textDocument.uri);
-    const program = cached?.program ?? null;
-    if (!program)
-        return null;
-    // Check if cursor is on a decorator (@tick, @load, etc.)
+    // ── Decorator hover: works even if program is null (parse errors elsewhere) ──
     const lines = source.split('\n');
     const lineText = lines[params.position.line] ?? '';
-    const decoratorMatch = lineText.match(/@([a-zA-Z_][a-zA-Z0-9_]*)/);
-    if (decoratorMatch) {
-        const ch = params.position.character;
-        const atIdx = lineText.indexOf('@');
-        const decoratorEnd = atIdx + 1 + decoratorMatch[1].length;
-        if (ch >= atIdx && ch <= decoratorEnd) {
-            const decoratorName = decoratorMatch[1];
+    const ch = params.position.character;
+    // Find all @xxx on this line and check if cursor is inside one
+    const decorRe = /@([a-zA-Z_][a-zA-Z0-9_]*)/g;
+    let dm;
+    while ((dm = decorRe.exec(lineText)) !== null) {
+        const atIdx = dm.index;
+        const decorEnd = atIdx + dm[0].length;
+        if (ch >= atIdx && ch <= decorEnd) {
+            const decoratorName = dm[1];
             const decoratorDoc = DECORATOR_DOCS[decoratorName];
             if (decoratorDoc) {
-                const content = {
-                    kind: node_1.MarkupKind.Markdown,
-                    value: `**@${decoratorName}** — ${decoratorDoc}`,
+                return {
+                    contents: {
+                        kind: node_1.MarkupKind.Markdown,
+                        value: `**@${decoratorName}** — ${decoratorDoc}`,
+                    },
                 };
-                return { contents: content };
             }
         }
     }
+    // ── Selector hover: @a, @p, @s etc ─────────────────────────────────────────
+    const SELECTOR_DOCS = {
+        '@a': 'All online players',
+        '@p': 'Nearest player to the command source',
+        '@s': 'The entity currently executing the command (self)',
+        '@e': 'All entities (use [type=...] to filter)',
+        '@r': 'A random online player',
+        '@n': 'The nearest entity of any type',
+    };
+    // Match @x or @x[...] token at cursor
+    const selRe = /@([a-zA-Z])/g;
+    let sm;
+    while ((sm = selRe.exec(lineText)) !== null) {
+        const selStart = sm.index;
+        const selEnd = selStart + sm[0].length;
+        if (ch >= selStart && ch <= selEnd) {
+            const selKey = sm[0]; // e.g. '@a'
+            const selDoc = SELECTOR_DOCS[selKey];
+            if (selDoc) {
+                return {
+                    contents: {
+                        kind: node_1.MarkupKind.Markdown,
+                        value: `**${selKey}** — ${selDoc}`,
+                    },
+                };
+            }
+        }
+    }
+    const cached = parsedDocs.get(params.textDocument.uri);
+    const program = cached?.program ?? null;
+    if (!program)
+        return null;
     const word = wordAt(source, params.position);
     if (!word)
         return null;
+    // If cursor is on a selector like @s/@a/@p, the word is just 's'/'a'/'p'.
+    // Detect this by checking the character before the word start.
+    const hovLines = source.split('\n');
+    const hovLine = hovLines[params.position.line] ?? '';
+    const hovCh = params.position.character;
+    // Find start of current word
+    let hovWordStart = hovCh;
+    while (hovWordStart > 0 && /\w/.test(hovLine[hovWordStart - 1]))
+        hovWordStart--;
+    if (hovWordStart > 0 && hovLine[hovWordStart - 1] === '@')
+        return null; // It's a selector, no hover
     // Check builtins
-    const builtin = metadata_1.BUILTIN_METADATA[word];
+    const builtin = ALL_BUILTINS[word];
     if (builtin) {
         const paramStr = builtin.params
             .map(p => `${p.name}: ${p.type}${p.required ? '' : '?'}`)
@@ -332,16 +586,181 @@ connection.onHover((params) => {
         };
         return { contents: content };
     }
+    // Check globals
+    const globalDecl = program.globals?.find(g => g.name === word);
+    if (globalDecl) {
+        const content = {
+            kind: node_1.MarkupKind.Markdown,
+            value: `\`\`\`redscript\nlet ${globalDecl.name}: ${typeToString(globalDecl.type)}\n\`\`\`\n*global variable*`,
+        };
+        return { contents: content };
+    }
+    // Check locals and params in the enclosing function
+    {
+        const curLine = params.position.line + 1;
+        const fn = findEnclosingFn(program, curLine);
+        if (fn) {
+            // Check params
+            const param = fn.params.find(p => p.name === word);
+            if (param) {
+                return {
+                    contents: {
+                        kind: node_1.MarkupKind.Markdown,
+                        value: `\`\`\`redscript\n(param) ${param.name}: ${typeToString(param.type)}\n\`\`\``,
+                    },
+                };
+            }
+            // Check locals
+            if (fn.body) {
+                const locals = collectLocals(fn.body);
+                const localType = locals.get(word);
+                if (localType) {
+                    return {
+                        contents: {
+                            kind: node_1.MarkupKind.Markdown,
+                            value: `\`\`\`redscript\nlet ${word}: ${typeToString(localType)}\n\`\`\``,
+                        },
+                    };
+                }
+            }
+        }
+    }
+    // ── Check imported files (import "stdlib/xxx.mcrs" and import xxx::*) ──────
+    try {
+        const importedPrograms = getImportedPrograms(source, params.textDocument.uri);
+        for (const { prog, filePath } of importedPrograms) {
+            const importedFn = findFunction(prog, word);
+            if (importedFn) {
+                const sig = formatFnSignature(importedFn);
+                // Extract leading /** ... */ comment from the source file
+                const docComment = extractDocComment(fs.readFileSync(filePath, 'utf-8'), importedFn);
+                const docLine = docComment ? `\n\n${docComment}` : '';
+                const content = {
+                    kind: node_1.MarkupKind.Markdown,
+                    value: `\`\`\`redscript\n${sig}\n\`\`\`${docLine}\n\n*from ${path.basename(filePath)}*`,
+                };
+                return { contents: content };
+            }
+            const importedStruct = prog.structs?.find(s => s.name === word);
+            if (importedStruct) {
+                const fields = importedStruct.fields.map(f => `  ${f.name}: ${typeToString(f.type)}`).join('\n');
+                const content = {
+                    kind: node_1.MarkupKind.Markdown,
+                    value: `\`\`\`redscript\nstruct ${importedStruct.name} {\n${fields}\n}\n\`\`\`\n\n*from ${path.basename(filePath)}*`,
+                };
+                return { contents: content };
+            }
+        }
+    }
+    catch { /* ignore */ }
     return null;
 });
 // ---------------------------------------------------------------------------
 // Go-to-definition
 // ---------------------------------------------------------------------------
+/**
+ * Parse all import declarations in `source` (both path-based and module::*
+ * forms) and return parsed Program objects for each resolved file.
+ */
+function getImportedPrograms(source, fromUri) {
+    const result = [];
+    // 1. Path-based: import "stdlib/math.mcrs"
+    const FILE_IMPORT_RE = /^import\s+"([^"]+)"/gm;
+    let m;
+    while ((m = FILE_IMPORT_RE.exec(source)) !== null) {
+        const resolved = resolveImportPath(m[1], fromUri);
+        if (!resolved || !fs.existsSync(resolved))
+            continue;
+        try {
+            const src = fs.readFileSync(resolved, 'utf-8');
+            const tokens = new lexer_1.Lexer(src).tokenize();
+            const prog = new parser_1.Parser(tokens).parse(path.basename(resolved, '.mcrs'));
+            result.push({ prog, filePath: resolved });
+        }
+        catch { /* skip */ }
+    }
+    // 2. Module-star: import random::* or import random::fn_name
+    const MOD_IMPORT_RE = /^import\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*::/gm;
+    while ((m = MOD_IMPORT_RE.exec(source)) !== null) {
+        const modName = m[1];
+        // Try to resolve as stdlib/modName.mcrs
+        const resolved = resolveImportPath(`stdlib/${modName}.mcrs`, fromUri);
+        if (!resolved || !fs.existsSync(resolved))
+            continue;
+        // Avoid duplicates if already resolved above
+        if (result.some(r => r.filePath === resolved))
+            continue;
+        try {
+            const src = fs.readFileSync(resolved, 'utf-8');
+            const tokens = new lexer_1.Lexer(src).tokenize();
+            const prog = new parser_1.Parser(tokens).parse(modName);
+            result.push({ prog, filePath: resolved });
+        }
+        catch { /* skip */ }
+    }
+    return result;
+}
+/** Resolve a relative or stdlib import path to an absolute file path. */
+function resolveImportPath(importStr, fromUri) {
+    try {
+        const fromFile = (0, url_1.fileURLToPath)(fromUri);
+        const fromDir = path.dirname(fromFile);
+        if (importStr.startsWith('.')) {
+            // Relative path: import "../stdlib/math.mcrs"
+            const resolved = path.resolve(fromDir, importStr);
+            if (fs.existsSync(resolved))
+                return resolved;
+            // Try adding .mcrs extension
+            if (!resolved.endsWith('.mcrs') && fs.existsSync(resolved + '.mcrs'))
+                return resolved + '.mcrs';
+        }
+        else {
+            // stdlib path: import "stdlib/math" or "stdlib/math.mcrs"
+            // Walk up to find package root (contains package.json)
+            let dir = fromDir;
+            for (let i = 0; i < 10; i++) {
+                if (fs.existsSync(path.join(dir, 'package.json'))) {
+                    const candidate = path.join(dir, 'src', importStr);
+                    if (fs.existsSync(candidate))
+                        return candidate;
+                    if (fs.existsSync(candidate + '.mcrs'))
+                        return candidate + '.mcrs';
+                    // also try without 'src/'
+                    const candidate2 = path.join(dir, importStr);
+                    if (fs.existsSync(candidate2))
+                        return candidate2;
+                    if (fs.existsSync(candidate2 + '.mcrs'))
+                        return candidate2 + '.mcrs';
+                    break;
+                }
+                dir = path.dirname(dir);
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return null;
+}
 connection.onDefinition((params) => {
     const doc = documents.get(params.textDocument.uri);
     if (!doc)
         return null;
     const source = doc.getText();
+    const lines = source.split('\n');
+    const lineText = lines[params.position.line] ?? '';
+    const ch = params.position.character;
+    // ── import "path/to/file.mcrs" ─────────────────────────────────────────────
+    // Cursor is anywhere on the line that starts with `import "..."`
+    const fileImportMatch = lineText.match(/^import\s+"([^"]+)"/);
+    if (fileImportMatch) {
+        const importStr = fileImportMatch[1];
+        const resolved = resolveImportPath(importStr, params.textDocument.uri);
+        if (resolved) {
+            return {
+                uri: (0, url_1.pathToFileURL)(resolved).toString(),
+                range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
+            };
+        }
+    }
     const cached = parsedDocs.get(params.textDocument.uri);
     const program = cached?.program ?? null;
     if (!program)
@@ -349,37 +768,234 @@ connection.onDefinition((params) => {
     const word = wordAt(source, params.position);
     if (!word)
         return null;
+    // If cursor is on a selector like @s/@a, the word is 's'/'a' — no F12.
+    let defWordStart = params.position.character;
+    while (defWordStart > 0 && /\w/.test(lineText[defWordStart - 1]))
+        defWordStart--;
+    if (defWordStart > 0 && lineText[defWordStart - 1] === '@')
+        return null;
+    // ── Normal in-file definition (top-level fn/struct/const/global) ────────────
     const defMap = buildDefinitionMap(program, source);
     const span = defMap.get(word);
-    if (!span)
-        return null;
-    const line = Math.max(0, span.line - 1);
-    const col = Math.max(0, span.col - 1);
-    return {
-        uri: params.textDocument.uri,
-        range: {
-            start: { line, character: col },
-            end: { line, character: col + word.length },
-        },
-    };
+    if (span) {
+        const line = Math.max(0, span.line - 1);
+        const col = Math.max(0, span.col - 1);
+        return {
+            uri: params.textDocument.uri,
+            range: {
+                start: { line, character: col },
+                end: { line, character: col + word.length },
+            },
+        };
+    }
+    // ── If word is a local/param in the enclosing fn, don't fall through to imports ──
+    const defCurLine = params.position.line + 1; // 1-based
+    const enclosingFn = findEnclosingFn(program, defCurLine);
+    if (enclosingFn) {
+        if (enclosingFn.params.some(p => p.name === word))
+            return null;
+        if (enclosingFn.body) {
+            const locals = collectLocals(enclosingFn.body);
+            if (locals.has(word))
+                return null;
+        }
+    }
+    // Struct fields — clicking on .phase, .active etc. should not jump to stdlib
+    for (const s of program.structs ?? []) {
+        if (s.fields.some(f => f.name === word))
+            return null;
+    }
+    // ── Imported symbol F12 — jump to definition inside the imported file ────────
+    // Only reached if word is not a local. Avoids false matches for short names like 'p', 'k'.
+    try {
+        const importedPrograms = getImportedPrograms(source, params.textDocument.uri);
+        for (const { prog, filePath } of importedPrograms) {
+            const importedDefMap = buildDefinitionMap(prog, fs.readFileSync(filePath, 'utf-8'));
+            const importedSpan = importedDefMap.get(word);
+            if (importedSpan) {
+                const line = Math.max(0, importedSpan.line - 1);
+                const col = Math.max(0, importedSpan.col - 1);
+                return {
+                    uri: (0, url_1.pathToFileURL)(filePath).toString(),
+                    range: {
+                        start: { line, character: col },
+                        end: { line, character: col + word.length },
+                    },
+                };
+            }
+        }
+    }
+    catch { /* ignore */ }
+    // ── import module::symbol (legacy AST imports) — open module file ONLY for explicit symbols ──
+    // NOTE: do NOT match im.symbol === '*' — that would cause any word to jump to the first import!
+    const importDecl = program.imports?.find(im => im.symbol === word);
+    if (importDecl) {
+        const resolved = resolveImportPath(`stdlib/${importDecl.moduleName}.mcrs`, params.textDocument.uri)
+            ?? resolveImportPath(importDecl.moduleName, params.textDocument.uri)
+            ?? resolveImportPath(importDecl.moduleName + '.mcrs', params.textDocument.uri);
+        if (resolved) {
+            return {
+                uri: (0, url_1.pathToFileURL)(resolved).toString(),
+                range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
+            };
+        }
+    }
+    return null;
 });
 // ---------------------------------------------------------------------------
+// Completion helpers
+// ---------------------------------------------------------------------------
+/** int[] built-in methods */
+const ARRAY_METHOD_COMPLETIONS = [
+    { label: 'push', kind: node_1.CompletionItemKind.Method, detail: '(value: int): void', documentation: 'Append an element to the array.' },
+    { label: 'pop', kind: node_1.CompletionItemKind.Method, detail: '(): int', documentation: 'Remove and return the last element.' },
+    { label: 'length', kind: node_1.CompletionItemKind.Property, detail: 'int', documentation: 'Number of elements in the array.' },
+];
+/** Collect (name → TypeNode) for all let bindings visible in the function body at offset. */
+function collectLocals(body) {
+    const map = new Map();
+    // Sentinel type for variables whose type is unknown (e.g. foreach bindings)
+    const ENTITY_TYPE = { kind: 'named', name: 'int' }; // placeholder for entity/selector binding
+    function walk(stmts) {
+        for (const s of stmts) {
+            if (s.kind === 'let' && s.type) {
+                map.set(s.name, s.type);
+            }
+            else if (s.kind === 'foreach') {
+                // foreach binding is an entity/selector variable
+                map.set(s.binding, ENTITY_TYPE);
+                if (Array.isArray(s.body))
+                    walk(s.body);
+                continue;
+            }
+            else if (s.kind === 'for') {
+                // for i in range — binding is int
+                if (s.binding)
+                    map.set(s.binding, { kind: 'named', name: 'int' });
+            }
+            // Recurse into sub-blocks
+            const sub = s;
+            if (Array.isArray(sub['body']))
+                walk(sub['body']);
+            if (Array.isArray(sub['then']))
+                walk(sub['then']);
+            if (Array.isArray(sub['else_']))
+                walk(sub['else_']);
+        }
+    }
+    walk(body);
+    return map;
+}
+/** Determine if line at cursor is a dot-access context: `<expr>.` */
+function getDotReceiver(lineText, charPos) {
+    // Check that the character just before cursor is '.'
+    if (lineText[charPos - 1] !== '.')
+        return null;
+    // Scan left to collect the identifier before '.'
+    let end = charPos - 2;
+    while (end >= 0 && /\s/.test(lineText[end]))
+        end--;
+    if (end < 0)
+        return null;
+    let start = end;
+    while (start > 0 && /[a-zA-Z0-9_]/.test(lineText[start - 1]))
+        start--;
+    return lineText.slice(start, end + 1) || null;
+}
+// ---------------------------------------------------------------------------
 // Completion
 // ---------------------------------------------------------------------------
 connection.onCompletion((params) => {
     const doc = documents.get(params.textDocument.uri);
+    if (!doc) {
+        return [...KEYWORD_COMPLETIONS, ...TYPE_COMPLETIONS, ...BUILTIN_FN_COMPLETIONS, ...DECORATOR_COMPLETIONS];
+    }
+    const source = doc.getText();
+    const lines = source.split('\n');
+    const lineText = lines[params.position.line] ?? '';
+    const charPos = params.position.character;
+    const cached = parsedDocs.get(params.textDocument.uri);
+    const program = cached?.program ?? null;
+    // ── @ trigger: selector (@a/@p/@s/@e/@r/@n) vs decorator (@tick etc) ────────
+    // Only fires when the character just typed is '@' (triggerCharacter).
+    // insertText includes the full @xxx so VSCode replaces the '@' already on screen.
+    const prevChar = lineText[charPos - 1];
+    if (prevChar === '@') {
+        const before = lineText.slice(0, charPos - 1).trim();
+        const isExprContext = before.length > 0 && !/^(fn|let|if|while|for|return|@)/.test(before.split(/\s+/).pop() ?? '');
+        if (isExprContext) {
+            return SELECTOR_COMPLETIONS;
+        }
+        return DECORATOR_COMPLETIONS;
+    }
+    // ── Dot-access completion ──────────────────────────────────────────────────
+    const dotReceiver = getDotReceiver(lineText, charPos);
+    if (dotReceiver !== null) {
+        const items = [];
+        if (program) {
+            // Find which function body contains this line (by span)
+            const curLine = params.position.line + 1; // spans are 1-based
+            const encFn = findEnclosingFn(program, curLine);
+            const locals = encFn?.body
+                ? collectLocals(encFn.body)
+                : null;
+            // Determine type of receiver
+            const receiverType = locals?.get(dotReceiver)
+                ?? program.consts?.find(c => c.name === dotReceiver)?.type
+                ?? program.globals?.find(g => g.name === dotReceiver)?.type;
+            if (receiverType) {
+                if (receiverType.kind === 'array') {
+                    // int[] → push / pop / length
+                    items.push(...ARRAY_METHOD_COMPLETIONS);
+                }
+                else if (receiverType.kind === 'named' || receiverType.kind === 'struct') {
+                    const typeName = receiverType.name;
+                    // Struct fields
+                    const structDecl = program.structs?.find(s => s.name === typeName);
+                    if (structDecl) {
+                        for (const f of structDecl.fields) {
+                            items.push({
+                                label: f.name,
+                                kind: node_1.CompletionItemKind.Field,
+                                detail: typeToString(f.type),
+                            });
+                        }
+                    }
+                    // Impl methods
+                    const implBlock = program.implBlocks?.find(ib => ib.typeName === typeName);
+                    if (implBlock) {
+                        for (const m of implBlock.methods) {
+                            const params_ = m.params.map(p => `${p.name}: ${typeToString(p.type)}`).join(', ');
+                            items.push({
+                                label: m.name,
+                                kind: node_1.CompletionItemKind.Method,
+                                detail: `(${params_}): ${typeToString(m.returnType)}`,
+                            });
+                        }
+                    }
+                }
+            }
+            else {
+                // Unknown type — offer all struct fields + impl methods as fallback
+                for (const ib of program.implBlocks ?? []) {
+                    for (const m of ib.methods) {
+                        items.push({ label: m.name, kind: node_1.CompletionItemKind.Method });
+                    }
+                }
+                items.push(...ARRAY_METHOD_COMPLETIONS);
+            }
+        }
+        return items;
+    }
+    // ── Global / normal completion ─────────────────────────────────────────────
     const items = [
         ...KEYWORD_COMPLETIONS,
         ...TYPE_COMPLETIONS,
         ...BUILTIN_FN_COMPLETIONS,
         ...DECORATOR_COMPLETIONS,
     ];
-    if (!doc)
-        return items;
-    // Add user-defined functions from the parsed doc
-    const cached = parsedDocs.get(params.textDocument.uri);
-    const program = cached?.program ?? null;
     if (program) {
+        // User-defined top-level symbols
         for (const fn of program.declarations) {
             items.push({ label: fn.name, kind: node_1.CompletionItemKind.Function });
         }
@@ -392,10 +1008,250 @@ connection.onCompletion((params) => {
         for (const c of program.consts ?? []) {
             items.push({ label: c.name, kind: node_1.CompletionItemKind.Constant });
         }
+        for (const g of program.globals ?? []) {
+            items.push({ label: g.name, kind: node_1.CompletionItemKind.Variable });
+        }
+        // Locals from the enclosing function
+        const curLine2 = params.position.line + 1;
+        const encFn2 = findEnclosingFn(program, curLine2);
+        if (encFn2?.body) {
+            for (const [name, typ] of collectLocals(encFn2.body)) {
+                items.push({
+                    label: name,
+                    kind: node_1.CompletionItemKind.Variable,
+                    detail: typeToString(typ),
+                });
+            }
+        }
+    }
+    // ── Functions from imported files (both "path" and module::* forms) ────────
+    try {
+        const importedPrograms = getImportedPrograms(source, params.textDocument.uri);
+        for (const { prog, filePath } of importedPrograms) {
+            for (const fn of prog.declarations) {
+                const paramList = fn.params.map(p => `${p.name}: ${typeToString(p.type)}`).join(', ');
+                items.push({
+                    label: fn.name,
+                    kind: node_1.CompletionItemKind.Function,
+                    detail: `(${paramList}) → ${typeToString(fn.returnType ?? { kind: 'named', name: 'void' })}`,
+                    documentation: `from ${path.basename(filePath)}`,
+                });
+            }
+            for (const s of prog.structs ?? []) {
+                items.push({ label: s.name, kind: node_1.CompletionItemKind.Struct, documentation: `from ${path.basename(filePath)}` });
+            }
+        }
     }
+    catch { /* ignore import completion errors */ }
     return items;
 });
 // ---------------------------------------------------------------------------
+// Helpers for word-at-position (used by references and rename)
+// ---------------------------------------------------------------------------
+function getWordRangeAtPosition(doc, position) {
+    const text = doc.getText();
+    const offset = doc.offsetAt(position);
+    let start = offset;
+    let end = offset;
+    while (start > 0 && /[a-zA-Z0-9_]/.test(text[start - 1]))
+        start--;
+    while (end < text.length && /[a-zA-Z0-9_]/.test(text[end]))
+        end++;
+    if (start === end)
+        return null;
+    return { start: doc.positionAt(start), end: doc.positionAt(end) };
+}
+// ---------------------------------------------------------------------------
+// Signature Help
+// ---------------------------------------------------------------------------
+connection.onSignatureHelp((params) => {
+    const doc = documents.get(params.textDocument.uri);
+    if (!doc)
+        return null;
+    const parsed = parsedDocs.get(params.textDocument.uri);
+    if (!parsed?.program)
+        return null;
+    const text = doc.getText();
+    const offset = doc.offsetAt(params.position);
+    // Walk backwards to find the opening '(' and count active parameter
+    let depth = 0;
+    let i = offset - 1;
+    let activeParam = 0;
+    while (i >= 0) {
+        const ch = text[i];
+        if (ch === ')')
+            depth++;
+        else if (ch === '(') {
+            if (depth === 0)
+                break;
+            depth--;
+        }
+        else if (ch === ',' && depth === 0)
+            activeParam++;
+        i--;
+    }
+    if (i < 0)
+        return null;
+    // Extract function name before '('
+    let nameEnd = i - 1;
+    while (nameEnd >= 0 && /\s/.test(text[nameEnd]))
+        nameEnd--;
+    let nameStart = nameEnd;
+    while (nameStart > 0 && /[a-zA-Z0-9_]/.test(text[nameStart - 1]))
+        nameStart--;
+    const fnName = text.slice(nameStart, nameEnd + 1);
+    if (!fnName)
+        return null;
+    // Find function declaration in parsed program
+    const fn = parsed.program.declarations.find(s => s.name === fnName);
+    // Also check builtins (BUILTIN_METADATA is a Record<string, BuiltinDef>)
+    const builtin = ALL_BUILTINS[fnName];
+    if (!fn && !builtin)
+        return null;
+    let label;
+    let paramsList;
+    if (fn) {
+        paramsList = fn.params.map(p => `${p.name}: ${typeToString(p.type)}`);
+        label = `fn ${fn.name}(${paramsList.join(', ')}): ${typeToString(fn.returnType)}`;
+    }
+    else {
+        paramsList = builtin.params?.map(p => `${p.name}: ${p.type}`) ?? [];
+        label = `${builtin.name}(${paramsList.join(', ')}): ${builtin.returns ?? 'void'}`;
+    }
+    const paramInfos = paramsList.map(p => ({ label: p }));
+    return {
+        signatures: [
+            {
+                label,
+                parameters: paramInfos,
+                activeParameter: Math.min(activeParam, Math.max(0, paramInfos.length - 1)),
+            },
+        ],
+        activeSignature: 0,
+        activeParameter: Math.min(activeParam, Math.max(0, paramInfos.length - 1)),
+    };
+});
+// ---------------------------------------------------------------------------
+// Inlay Hints
+// ---------------------------------------------------------------------------
+connection.onRequest('textDocument/inlayHint', (params) => {
+    const parsed = parsedDocs.get(params.textDocument.uri);
+    if (!parsed?.program)
+        return [];
+    const doc = documents.get(params.textDocument.uri);
+    if (!doc)
+        return [];
+    const hints = [];
+    // Walk all let declarations with no explicit type annotation and emit inlay hints.
+    // Since TypeChecker doesn't attach inferredType to AST nodes, we use collectLocals
+    // which already infers types from init expressions.
+    function walkBlock(stmts) {
+        // Build a locals map for this block (includes inferred types)
+        const locals = collectLocals(stmts);
+        for (const stmt of stmts) {
+            if (stmt.kind === 'let' && !stmt.type) {
+                // No explicit type annotation — show inferred type as inlay hint
+                const inferredType = locals.get(stmt.name);
+                if (!inferredType)
+                    continue;
+                const spanVal = stmt.span;
+                if (!spanVal)
+                    continue;
+                // Position hint after the variable name: line is 1-based in span, col is 1-based
+                const line = Math.max(0, spanVal.line - 1);
+                // Find the position after the variable name on that line
+                const lineText = source.split('\n')[line] ?? '';
+                const nameEnd = lineText.indexOf(stmt.name) + stmt.name.length;
+                hints.push({
+                    position: { line, character: nameEnd },
+                    label: `: ${typeToString(inferredType)}`,
+                    kind: node_1.InlayHintKind.Type,
+                    paddingLeft: false,
+                });
+            }
+            // Recurse into nested blocks
+            if (stmt.kind === 'if' || stmt.kind === 'while' || stmt.kind === 'for') {
+                const s = stmt;
+                const then_ = s['then'];
+                if (Array.isArray(then_))
+                    walkBlock(then_);
+                const else_ = s['else_'];
+                if (Array.isArray(else_))
+                    walkBlock(else_);
+                const body = s['body'];
+                if (Array.isArray(body))
+                    walkBlock(body);
+            }
+            if (stmt.kind === 'foreach') {
+                const s = stmt;
+                const body = s['body'];
+                if (Array.isArray(body))
+                    walkBlock(body);
+            }
+        }
+    }
+    const source = doc.getText();
+    parsed.program.declarations.forEach(top => {
+        if (top.body)
+            walkBlock(top.body);
+    });
+    return hints;
+});
+// ---------------------------------------------------------------------------
+// Find References
+// ---------------------------------------------------------------------------
+connection.onReferences((params) => {
+    const doc = documents.get(params.textDocument.uri);
+    if (!doc)
+        return [];
+    const parsed = parsedDocs.get(params.textDocument.uri);
+    if (!parsed?.program)
+        return [];
+    const wordRange = getWordRangeAtPosition(doc, params.position);
+    if (!wordRange)
+        return [];
+    const word = doc.getText(wordRange);
+    if (!word)
+        return [];
+    const text = doc.getText();
+    const locations = [];
+    const regex = new RegExp(`\\b${word}\\b`, 'g');
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+        const start = doc.positionAt(match.index);
+        const end = doc.positionAt(match.index + word.length);
+        locations.push({
+            uri: params.textDocument.uri,
+            range: { start, end },
+        });
+    }
+    return locations;
+});
+// ---------------------------------------------------------------------------
+// Rename Symbol
+// ---------------------------------------------------------------------------
+connection.onRenameRequest((params) => {
+    const doc = documents.get(params.textDocument.uri);
+    if (!doc)
+        return null;
+    const wordRange = getWordRangeAtPosition(doc, params.position);
+    if (!wordRange)
+        return null;
+    const word = doc.getText(wordRange);
+    if (!word)
+        return null;
+    const text = doc.getText();
+    const edits = [];
+    const regex = new RegExp(`\\b${word}\\b`, 'g');
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+        const start = doc.positionAt(match.index);
+        const end = doc.positionAt(match.index + word.length);
+        edits.push({ range: { start, end }, newText: params.newName });
+    }
+    return { changes: { [params.textDocument.uri]: edits } };
+});
+// ---------------------------------------------------------------------------
 // Start
 // ---------------------------------------------------------------------------
 documents.listen(connection);