spark-html-language-server 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# spark-html-language-server
+
+Language server (LSP) for [Spark](https://github.com/wilkinnovo/spark) single-file
+`.html` components. Zero dependencies, speaks LSP over stdio.
+
+## What you get
+
+- **Diagnostics**, live as you type:
+  - `{binding}` used in the template but never declared in `<script>`
+  - JS imports that are never used
+  - script syntax errors (the exact code the runtime would execute)
+  - `<div import="…">` pointing at a component file that doesn't exist
+  - `each` without `key=` (hint — keyed reconciliation is opt-in)
+  - malformed `each` expressions
+- **Go-to-definition** — jump from `<div import="components/card">` to
+  `card.html`, and from any `{symbol}` to its `let` / `function` / `$:` /
+  `export let` declaration.
+- **Autocomplete**
+  - props on import placeholders, read from the target component's
+    `export let` declarations
+  - every template directive (`each`, `if`/`else-if`/`else`, `await`/`then`/`catch`,
+    `bind:value|checked|group|form`, `:hidden`-style dynamic attributes, `key`,
+    `route`, `transition:fade|slide|scale`, `spark-ignore`)
+  - script symbols and Spark builtins (`useStore`, `onMount`, `props`) inside
+    `{…}` and `<script>`
+- **Hover docs** for every directive and declaration.
+
+## Install
+
+```bash
+npm install -g spark-html-language-server
+```
+
+The `spark-html-language-server` binary starts the server on stdio — the
+transport every LSP client speaks.
+
+## VS Code
+
+Install the **Spark (spark-html)** extension from
+[`editors/vscode`](https://github.com/wilkinnovo/spark/tree/main/editors/vscode) —
+it bundles syntax highlighting and launches this server automatically (globally
+installed binary, or `node_modules/.bin` in your project).
+
+## Programmatic use
+
+The analyzer is exported for tooling:
+
+```js
+import { analyze } from 'spark-html-language-server';
+
+const { declarations, props, diagnostics } = analyze(componentSource);
+```
+
+## Scope (v0.x)
+
+The server analyzes one component at a time — the same boundary the runtime
+has. It does not type-check across files (props completion reads the target
+file's `export let` names, not their types), and remote URL imports are not
+resolved.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// spark-html-language-server — LSP over stdio. Editors launch this binary;
+// see the package README for VS Code setup.
+import { connectStdio } from '../src/server.js';
+connectStdio();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "spark-html-language-server",
+  "version": "0.1.0",
+  "description": "Language server (LSP) for spark-html single-file components — diagnostics (undefined bindings, unused imports, script errors, missing key), go-to-definition for component imports and symbols, prop autocomplete from export let, and hover docs for every directive. Zero dependencies.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "homepage": "https://wilkinnovo.github.io/spark",
+  "bin": {
+    "spark-html-language-server": "bin/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node test/lsp.js"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wilkinnovo/spark.git",
+    "directory": "packages/spark-html-language-server"
+  },
+  "keywords": [
+    "spark-html",
+    "lsp",
+    "language-server",
+    "ide",
+    "vscode",
+    "diagnostics",
+    "autocomplete"
+  ],
+  "license": "MIT"
+}

package/src/analyze.js

@@ -0,0 +1,488 @@
+/**
+ * spark-html-language-server — component analyzer.
+ *
+ * Parses a single-file Spark component (.html) the same way the runtime does
+ * (regex + string scanning, no AST) and produces everything the LSP features
+ * need: declarations with offsets, template references, import placeholders,
+ * each/await scopes, and diagnostics.
+ *
+ * All positions are absolute character offsets into the original text; the
+ * server converts them to LSP line/character positions.
+ */
+
+// Identifiers never flagged as "undefined" — JS/browser globals plus the
+// builtins Spark injects into every component scope (see spark-html/globals).
+export const KNOWN_GLOBALS = new Set([
+  // Spark component builtins
+  'useStore', 'onMount', 'props', 'await',
+  // literals & keywords that the identifier regex can catch
+  'true', 'false', 'null', 'undefined', 'NaN', 'Infinity',
+  'new', 'typeof', 'instanceof', 'in', 'of', 'this', 'void', 'delete',
+  'if', 'else', 'return', 'function', 'async', 'arguments',
+  // ubiquitous browser/JS globals
+  'window', 'document', 'console', 'Math', 'JSON', 'Date', 'Number',
+  'String', 'Boolean', 'Array', 'Object', 'Promise', 'Map', 'Set',
+  'RegExp', 'Error', 'Intl', 'Symbol', 'BigInt', 'Reflect', 'Proxy',
+  'parseInt', 'parseFloat', 'isNaN', 'isFinite', 'structuredClone',
+  'fetch', 'localStorage', 'sessionStorage', 'navigator', 'location',
+  'history', 'alert', 'confirm', 'prompt', 'crypto', 'performance',
+  'setTimeout', 'setInterval', 'clearTimeout', 'clearInterval',
+  'requestAnimationFrame', 'cancelAnimationFrame', 'queueMicrotask',
+  'URL', 'URLSearchParams', 'FormData', 'Blob', 'File', 'AbortController',
+  'CustomEvent', 'Event', 'KeyboardEvent', 'MouseEvent', 'Audio', 'Image',
+  'WebSocket', 'Notification', 'IntersectionObserver', 'ResizeObserver',
+  'MutationObserver', 'matchMedia', 'getComputedStyle', 'globalThis',
+]);
+
+const IDENT = /[A-Za-z_$][\w$]*/g;
+
+// ── masking helpers ────────────────────────────────────────────────────────
+// Replace comments and string/template-literal contents with spaces so regex
+// scans can't match inside them — same length, so offsets stay valid.
+
+export function maskJs(code) {
+  let out = '';
+  let i = 0;
+  const n = code.length;
+  while (i < n) {
+    const c = code[i];
+    const two = code.slice(i, i + 2);
+    if (two === '//') {
+      const end = code.indexOf('\n', i);
+      const stop = end === -1 ? n : end;
+      out += ' '.repeat(stop - i);
+      i = stop;
+    } else if (two === '/*') {
+      const end = code.indexOf('*/', i + 2);
+      const stop = end === -1 ? n : end + 2;
+      out += ' '.repeat(stop - i);
+      i = stop;
+    } else if (c === "'" || c === '"' || c === '`') {
+      let j = i + 1;
+      while (j < n) {
+        if (code[j] === '\\') { j += 2; continue; }
+        if (code[j] === c) break;
+        j++;
+      }
+      const stop = Math.min(j + 1, n);
+      out += c + ' '.repeat(Math.max(0, stop - i - 2)) + (stop - i >= 2 ? c : '');
+      i = stop;
+    } else {
+      out += c;
+      i++;
+    }
+  }
+  return out;
+}
+
+// Index of the `}` matching the `{` at openIdx (quote-aware), or -1.
+function matchingBrace(text, openIdx) {
+  let depth = 0;
+  let quote = null;
+  for (let i = openIdx; i < text.length; i++) {
+    const c = text[i];
+    if (quote) {
+      if (c === '\\') i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') quote = c;
+    else if (c === '{') depth++;
+    else if (c === '}' && --depth === 0) return i;
+  }
+  return -1;
+}
+
+// ── script extraction ──────────────────────────────────────────────────────
+
+function findScript(text) {
+  // The component's script is the first <script> without src=.
+  const re = /<script\b([^>]*)>/gi;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    if (/\bsrc\s*=/i.test(m[1])) continue;
+    const start = m.index + m[0].length;
+    const end = text.indexOf('</script', start);
+    return { start, end: end === -1 ? text.length : end, attrs: m[1] };
+  }
+  return null;
+}
+
+function blankRange(chars, start, end) {
+  for (let i = start; i < end && i < chars.length; i++) {
+    if (chars[i] !== '\n') chars[i] = ' ';
+  }
+}
+
+// Template text = source minus <script>/<style> contents minus spark-ignore
+// subtrees (never patched by Spark, so never analyzed).
+function templateMask(text, script) {
+  const chars = [...text];
+  if (script) blankRange(chars, script.start - 8, script.end); // include "<script>" tag itself
+  const styleRe = /<style\b[^>]*>/gi;
+  let m;
+  while ((m = styleRe.exec(text)) !== null) {
+    const close = text.indexOf('</style', m.index);
+    blankRange(chars, m.index, close === -1 ? text.length : close + 8);
+  }
+  // spark-ignore: blank from the opening tag to the matching close tag.
+  const ignoreRe = /<([a-zA-Z][\w-]*)\b[^>]*\bspark-ignore[\s>=/]/g;
+  while ((m = ignoreRe.exec(text)) !== null) {
+    const tag = m[1].toLowerCase();
+    let depth = 1;
+    const tagRe = new RegExp(`</?${tag}\\b`, 'gi');
+    tagRe.lastIndex = m.index + m[0].length;
+    let end = text.length;
+    let t;
+    while ((t = tagRe.exec(text)) !== null) {
+      depth += t[0][1] === '/' ? -1 : 1;
+      if (depth === 0) { end = text.indexOf('>', t.index) + 1 || text.length; break; }
+    }
+    blankRange(chars, m.index, end);
+  }
+  return chars.join('');
+}
+
+// Content range of the <template …> whose open tag starts at tagIdx.
+function templateContentRange(text, tagIdx) {
+  const open = text.indexOf('>', tagIdx);
+  if (open === -1) return null;
+  let depth = 1;
+  const re = /<\/?template\b/gi;
+  re.lastIndex = open;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    depth += m[0][1] === '/' ? -1 : 1;
+    if (depth === 0) return { start: open + 1, end: m.index };
+  }
+  return { start: open + 1, end: text.length };
+}
+
+// ── expression scanning ────────────────────────────────────────────────────
+
+// Identifiers referenced by a JS expression (masked for strings), each with
+// its absolute offset. Skips property accesses (`.foo`, `?.foo`), object keys
+// (`{ foo: … }`), and locals declared by arrow params inside the expression.
+export function exprRefs(expr, baseOffset) {
+  const masked = maskJs(expr);
+  const locals = new Set();
+  // arrow params: `e =>` and `(a, b) =>`
+  for (const m of masked.matchAll(/(?:\(([^)]*)\)|([A-Za-z_$][\w$]*))\s*=>/g)) {
+    for (const p of (m[1] ?? m[2] ?? '').split(',')) {
+      const name = p.trim().match(/^[A-Za-z_$][\w$]*/);
+      if (name) locals.add(name[0]);
+    }
+  }
+  const refs = [];
+  let m;
+  IDENT.lastIndex = 0;
+  while ((m = IDENT.exec(masked)) !== null) {
+    const name = m[0];
+    const before = masked.slice(0, m.index).match(/[\s\S]?$/)[0];
+    const prev = masked.slice(0, m.index).replace(/\s+$/, '').slice(-2);
+    if (before === '.' || prev.endsWith('.') ) continue;      // property access
+    const after = masked.slice(m.index + name.length).match(/^\s*./)?.[0]?.trim();
+    if (after === ':' && !prev.endsWith('?')) continue;        // object key / label
+    if (locals.has(name) || KNOWN_GLOBALS.has(name)) continue;
+    refs.push({ name, offset: baseOffset + m.index });
+  }
+  return refs;
+}
+
+// ── script analysis ────────────────────────────────────────────────────────
+
+function analyzeScript(text, script) {
+  const declarations = new Map(); // name -> { kind, offset }
+  const imports = [];
+  const diagnostics = [];
+  if (!script) return { declarations, imports, diagnostics, refs: [] };
+
+  const code = text.slice(script.start, script.end);
+  const masked = maskJs(code);
+  const declare = (name, kind, offset) => {
+    if (!declarations.has(name)) declarations.set(name, { kind, offset: script.start + offset });
+  };
+
+  // JS imports (Spark replays them as dynamic import()).
+  const importRe = /(^|[\n;])\s*import\s+(?:([^'"\n;]+?)\s+from\s+)?(['"])([^'"\n]*)\3/g;
+  let m;
+  while ((m = importRe.exec(masked)) !== null) {
+    const clause = m[2] || '';
+    const spec = code.slice(m.index, m.index + m[0].length).match(/['"]([^'"]*)['"]/)?.[1] ?? '';
+    const entry = { spec, locals: [], start: script.start + m.index, end: script.start + m.index + m[0].length };
+    const clauseBase = m.index + m[0].indexOf(clause);
+    const named = clause.match(/\{([^}]*)\}/);
+    let rest = clause;
+    if (named) {
+      for (const part of named[1].split(',')) {
+        const asM = part.match(/^\s*([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?\s*$/);
+        if (!asM) continue;
+        const local = asM[2] || asM[1];
+        const off = clauseBase + clause.indexOf(local, named.index);
+        entry.locals.push({ name: local, offset: script.start + off });
+      }
+      rest = clause.slice(0, named.index) + clause.slice(named.index + named[0].length);
+    }
+    const ns = rest.match(/\*\s*as\s+([A-Za-z_$][\w$]*)/);
+    if (ns) entry.locals.push({ name: ns[1], offset: script.start + clauseBase + rest.indexOf(ns[1]) });
+    const def = rest.replace(/\*\s*as\s+[A-Za-z_$][\w$]*/, '').match(/[A-Za-z_$][\w$]*/);
+    if (def) entry.locals.push({ name: def[0], offset: script.start + clauseBase + clause.indexOf(def[0]) });
+    for (const l of entry.locals) declare(l.name, 'import', l.offset - script.start + 0);
+    for (const l of entry.locals) declarations.get(l.name).offset = l.offset;
+    imports.push(entry);
+  }
+
+  // `export let x` = prop; plain let/const/var = state (comma chains too).
+  const declRe = /(^|[\n;{}])\s*(export\s+)?(let|const|var)\s+([A-Za-z_$][\w$]*)/g;
+  while ((m = declRe.exec(masked)) !== null) {
+    const name = m[4];
+    const offset = m.index + m[0].length - name.length;
+    declare(name, m[2] ? 'prop' : 'let', offset);
+    // comma-chained names at the same nesting depth: `let a = 1, b = 2`
+    let i = m.index + m[0].length;
+    let depth = 0;
+    while (i < masked.length) {
+      const c = masked[i];
+      if ('([{'.includes(c)) depth++;
+      else if (')]}'.includes(c)) { if (--depth < 0) break; }
+      else if ((c === ';' || c === '\n') && depth === 0) break;
+      else if (c === ',' && depth === 0) {
+        const next = masked.slice(i + 1).match(/^\s*([A-Za-z_$][\w$]*)/);
+        if (next) declare(next[1], m[2] ? 'prop' : 'let', i + 1 + next[0].length - next[1].length);
+      }
+      i++;
+    }
+  }
+
+  // function declarations
+  const funcRe = /(^|[\n;{}])\s*(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g;
+  while ((m = funcRe.exec(masked)) !== null) {
+    declare(m[2], 'function', m.index + m[0].length - m[2].length);
+  }
+
+  // `$: x = …` implicitly declares x
+  const reactiveRe = /(^|\n)\s*\$:\s*([A-Za-z_$][\w$]*)\s*=(?!=)/g;
+  while ((m = reactiveRe.exec(masked)) !== null) {
+    declare(m[2], 'reactive', m.index + m[0].indexOf(m[2]));
+  }
+
+  // Syntax check: what the runtime would execute. `$:` is a valid JS label;
+  // `import`/`export` are not valid inside Function, so strip them the way
+  // the runtime lifts them out.
+  let checkable = code;
+  for (const imp of imports) {
+    const s = imp.start - script.start;
+    const e = imp.end - script.start;
+    checkable = checkable.slice(0, s) + checkable.slice(s, e).replace(/\S/g, ' ') + checkable.slice(e);
+  }
+  checkable = checkable.replace(/(^|[\n;{}])(\s*)export(\s+)(?=let|const|var)/g, '$1$2      $3');
+  try {
+    new Function(checkable); // eslint-disable-line no-new-func
+  } catch (e) {
+    let offset = script.start;
+    const loc = e.stack?.match(/<anonymous>:(\d+):(\d+)/);
+    if (loc) {
+      // new Function() prepends two lines before the body.
+      const line = Math.max(0, Number(loc[1]) - 3);
+      const lines = code.split('\n');
+      offset = script.start + lines.slice(0, line).reduce((s, l) => s + l.length + 1, 0) + Number(loc[2]) - 1;
+    }
+    diagnostics.push({
+      start: offset,
+      end: Math.min(offset + 1, script.end),
+      severity: 1,
+      message: `Script error: ${e.message}`,
+      code: 'script-syntax',
+    });
+  }
+
+  // References inside the script (for unused-import detection): identifiers
+  // outside each import's own statement.
+  const refs = [];
+  IDENT.lastIndex = 0;
+  while ((m = IDENT.exec(masked)) !== null) {
+    const abs = script.start + m.index;
+    if (imports.some((imp) => abs >= imp.start && abs < imp.end)) continue;
+    if (masked[m.index - 1] === '.') continue;
+    refs.push({ name: m[0], offset: abs });
+  }
+
+  return { declarations, imports, diagnostics, refs };
+}
+
+// ── template analysis ──────────────────────────────────────────────────────
+
+function analyzeTemplate(text, tpl) {
+  const refs = [];          // { name, offset, scopes: [names visible here] }
+  const eachBlocks = [];    // { itemVar, indexVar, arrayExpr, attrOffset, content: {start,end}, hasKey }
+  const awaitBlocks = [];   // { content: {start,end} }
+  const importTags = [];    // { path, valueStart, valueEnd, tagStart, tagEnd }
+  let m;
+
+  // <template each="item, i in expr" key="…">
+  const eachRe = /<template\b[^>]*\beach\s*=\s*"([^"]*)"/gi;
+  while ((m = eachRe.exec(tpl)) !== null) {
+    const spec = m[1];
+    const specStart = m.index + m[0].length - spec.length - 1;
+    const parts = spec.match(/^(\w+)(?:\s*,\s*(\w+))?\s+in\s+([\s\S]+)$/);
+    const tagEnd = tpl.indexOf('>', m.index);
+    const tag = tpl.slice(m.index, tagEnd === -1 ? tpl.length : tagEnd);
+    const content = templateContentRange(tpl, m.index);
+    if (!parts) {
+      eachBlocks.push({ itemVar: null, indexVar: null, arrayExpr: spec, attrOffset: specStart, content, hasKey: true, malformed: true });
+      continue;
+    }
+    eachBlocks.push({
+      itemVar: parts[1],
+      indexVar: parts[2] || null,
+      arrayExpr: parts[3].trim(),
+      attrOffset: specStart,
+      exprOffset: specStart + spec.indexOf(parts[3]),
+      content,
+      hasKey: /\bkey\s*=\s*"/.test(tag),
+    });
+  }
+
+  // <template await="expr"> — `await` is in scope inside (then/catch included).
+  const awaitRe = /<template\b[^>]*\bawait\s*=\s*"([^"]*)"/gi;
+  while ((m = awaitRe.exec(tpl)) !== null) {
+    const content = templateContentRange(tpl, m.index);
+    if (content) awaitBlocks.push({ content });
+    let expr = m[1];
+    let exprOffset = m.index + m[0].length - m[1].length - 1;
+    const once = expr.match(/^once\(([\s\S]*)\)$/);
+    if (once) { expr = once[1]; exprOffset += 5; }
+    refs.push(...exprRefs(expr, exprOffset));
+  }
+
+  // {interpolations} — quote-aware matching, `\{` escapes skipped.
+  for (let i = 0; i < tpl.length; i++) {
+    if (tpl[i] !== '{' || tpl[i - 1] === '\\' || tpl[i - 1] === '$') continue;
+    const close = matchingBrace(tpl, i);
+    if (close === -1) continue;
+    refs.push(...exprRefs(tpl.slice(i + 1, close), i + 1));
+    i = close;
+  }
+
+  // :attr="expr" dynamic attributes + template if/else-if/key
+  const dynRe = /(?<=\s):([\w-]+)\s*=\s*"([^"]*)"/g;
+  while ((m = dynRe.exec(tpl)) !== null) {
+    refs.push(...exprRefs(m[2], m.index + m[0].length - m[2].length - 1));
+  }
+  const condRe = /<template\b[^>]*\b(if|else-if|key)\s*=\s*"([^"]*)"/gi;
+  while ((m = condRe.exec(tpl)) !== null) {
+    refs.push(...exprRefs(m[2], m.index + m[0].length - m[2].length - 1));
+  }
+  // key= on the each tag itself (evaluated per item)
+  const keyRe = /<template\b[^>]*\beach\s*=[^>]*\bkey\s*=\s*"([^"]*)"/gi;
+  while ((m = keyRe.exec(tpl)) !== null) {
+    refs.push(...exprRefs(m[1], m.index + m[0].length - m[1].length - 1));
+  }
+
+  // bind:x="target" — target must be writable state.
+  const bindRe = /(?<=\s)bind:([\w-]+)\s*=\s*"([^"]*)"/g;
+  while ((m = bindRe.exec(tpl)) !== null) {
+    refs.push(...exprRefs(m[2], m.index + m[0].length - m[2].length - 1));
+  }
+
+  // <div import="path" …> placeholders.
+  const impRe = /<[a-zA-Z][\w-]*\b[^>]*\bimport\s*=\s*"([^"]*)"/g;
+  while ((m = impRe.exec(tpl)) !== null) {
+    const valueStart = m.index + m[0].length - m[1].length - 1;
+    importTags.push({
+      path: m[1],
+      valueStart,
+      valueEnd: valueStart + m[1].length,
+      tagStart: m.index,
+      tagEnd: tpl.indexOf('>', m.index),
+    });
+  }
+
+  return { refs, eachBlocks, awaitBlocks, importTags };
+}
+
+// ── entry point ────────────────────────────────────────────────────────────
+
+export function analyze(text) {
+  const script = findScript(text);
+  const tpl = templateMask(text, script);
+  const s = analyzeScript(text, script);
+  const t = analyzeTemplate(text, tpl);
+  const diagnostics = [...s.diagnostics];
+
+  const declared = (name, offset) => {
+    if (s.declarations.has(name)) return true;
+    for (const b of t.eachBlocks) {
+      if (!b.content || offset < b.content.start || offset >= b.content.end) continue;
+      if (name === b.itemVar || name === b.indexVar) return true;
+    }
+    // the each/key expressions on the tag itself also see the loop vars
+    for (const b of t.eachBlocks) {
+      if (b.content && offset < b.content.start && offset >= b.attrOffset &&
+          (name === b.itemVar || name === b.indexVar)) return true;
+    }
+    return false;
+  };
+
+  // Undefined template bindings.
+  for (const ref of t.refs) {
+    if (!declared(ref.name, ref.offset)) {
+      diagnostics.push({
+        start: ref.offset,
+        end: ref.offset + ref.name.length,
+        severity: 2,
+        message: `'${ref.name}' is not declared in this component's <script> (no let/function/$:/export let matches).`,
+        code: 'undefined-binding',
+      });
+    }
+  }
+
+  // each without key= — index-matched patching; keyed is opt-in, so a hint.
+  for (const b of t.eachBlocks) {
+    if (!b.hasKey && !b.malformed) {
+      diagnostics.push({
+        start: b.attrOffset,
+        end: b.attrOffset + 4,
+        severity: 4,
+        message: `each without key= — rows are matched by index. Add key="${b.itemVar}.id" (or another stable expression) for keyed reconciliation.`,
+        code: 'each-no-key',
+      });
+    }
+    if (b.malformed) {
+      diagnostics.push({
+        start: b.attrOffset,
+        end: b.attrOffset + b.arrayExpr.length,
+        severity: 1,
+        message: `Malformed each — expected "item in items" or "item, i in items".`,
+        code: 'each-malformed',
+      });
+    }
+  }
+
+  // Unused JS imports: local never referenced in script or template.
+  const usedNames = new Set([...s.refs.map((r) => r.name), ...t.refs.map((r) => r.name)]);
+  for (const imp of s.imports) {
+    for (const local of imp.locals) {
+      if (!usedNames.has(local.name)) {
+        diagnostics.push({
+          start: local.offset,
+          end: local.offset + local.name.length,
+          severity: 2,
+          message: `'${local.name}' is imported but never used.`,
+          code: 'unused-import',
+        });
+      }
+    }
+  }
+
+  return {
+    script,
+    declarations: s.declarations,
+    imports: s.imports,
+    props: [...s.declarations].filter(([, d]) => d.kind === 'prop').map(([name, d]) => ({ name, offset: d.offset })),
+    templateRefs: t.refs,
+    eachBlocks: t.eachBlocks,
+    importTags: t.importTags,
+    diagnostics,
+  };
+}

package/src/docs.js

@@ -0,0 +1,161 @@
+/**
+ * Hover documentation + completion entries for Spark's template directives.
+ * One source of truth: `DIRECTIVES` drives both features.
+ *
+ * `match` is what the cursor word/attribute must look like; entries with
+ * `insert` differing from `label` use LSP insertText (e.g. snippets-lite).
+ */
+
+export const DIRECTIVES = [
+  {
+    label: 'import',
+    match: /^import$/,
+    detail: 'component placeholder',
+    doc: 'Import a component: `<div import="components/card"></div>`. The path resolves against the importing file (`.html` optional). Extra attributes become props (`export let` in the target). Full URLs work too: `<div import="https://…/card.html">`.',
+  },
+  {
+    label: 'each',
+    match: /^each$/,
+    detail: 'loop — <template each="item in items">',
+    doc: 'Repeat the template content per array item: `<template each="todo in todos">`. With index: `each="todo, i in todos"`. Add `key="todo.id"` for keyed reconciliation (rows move instead of being rewritten).',
+  },
+  {
+    label: 'key',
+    match: /^key$/,
+    detail: 'keyed reconciliation for each',
+    doc: 'Stable identity per row: `<template each="row in rows" key="row.id">`. Evaluated per item; rows with the same key are reused in place when the array reorders.',
+  },
+  {
+    label: 'if',
+    match: /^if$/,
+    detail: 'conditional — <template if="expr">',
+    doc: 'Mount the content while the expression is truthy: `<template if="show">…</template>`. Real DOM is added/removed, not hidden. Chain `<template else-if>` / `<template else>` directly after.',
+  },
+  {
+    label: 'else-if',
+    match: /^else-if$/,
+    detail: 'conditional chain branch',
+    doc: 'A branch chained directly after `<template if>`: `<template else-if="score > 60">`. The first truthy branch in the chain renders.',
+  },
+  {
+    label: 'else',
+    match: /^else$/,
+    detail: 'conditional fallback branch',
+    doc: 'The fallback chained directly after `<template if>` / `<template else-if>`. Renders when no earlier branch matched.',
+  },
+  {
+    label: 'await',
+    match: /^await$/,
+    detail: 'async block — <template await="promise">',
+    doc: 'Declarative loading states: `<template await="loadUser(id)">` shows its content while pending, `<template then>` when resolved (value available as `{await}`), `<template catch>` on rejection (`{await.message}`). Re-evaluates when dependencies change; wrap in `once(…)` to fire only on mount.',
+  },
+  {
+    label: 'then',
+    match: /^then$/,
+    detail: 'await resolved branch',
+    doc: 'Inside `<template await>`: renders when the promise resolves. The resolved value is `{await}` — e.g. `{await.name}`.',
+  },
+  {
+    label: 'catch',
+    match: /^catch$/,
+    detail: 'await rejected branch',
+    doc: 'Inside `<template await>`: renders when the promise rejects. The error is `{await}` — e.g. `{await.message}`.',
+  },
+  {
+    label: 'route',
+    match: /^route$/,
+    detail: 'spark-html-router — <template route="/path">',
+    doc: 'A router outlet: `<template route="/docs">` mounts its content when the URL matches. Params: `route="/post/:id"` → `useStore(\'route\').params.id`; query via `route.query`; `route="*"` is the 404 catch-all. Requires `router()` from `spark-html-router`.',
+  },
+  {
+    label: 'bind:value',
+    match: /^bind:value$/,
+    detail: 'two-way binding — inputs, selects, textareas',
+    doc: 'Two-way binding: `<input bind:value="draft">` keeps the element and the variable in sync both ways.',
+  },
+  {
+    label: 'bind:checked',
+    match: /^bind:checked$/,
+    detail: 'two-way binding — checkboxes',
+    doc: 'Two-way binding for checkboxes: `<input type="checkbox" bind:checked="done">`.',
+  },
+  {
+    label: 'bind:group',
+    match: /^bind:group$/,
+    detail: 'two-way binding — radio groups / checkbox arrays',
+    doc: 'Bind a set of inputs to one variable: radios write the selected value, checkbox groups collect an array. `<input type="radio" bind:group="size" value="L">`.',
+  },
+  {
+    label: 'bind:form',
+    match: /^bind:form$/,
+    detail: 'two-way binding — whole form as an object',
+    doc: 'Bind an entire form to one object keyed by field names: `<form bind:form="signup">`.',
+  },
+  {
+    label: 'transition',
+    match: /^transition(:(fade|slide|scale))?$/,
+    detail: 'spark-html-motion — enter/leave animation',
+    doc: 'Animate elements as `if`/`each` blocks add or remove them: `transition="fade"` (or `slide`/`scale`; directive form `transition:fade` works too). Tune with `transition-duration="300"` (ms) and `transition-easing="ease-out"`. Requires `motion()` from `spark-html-motion`. Honors prefers-reduced-motion.',
+  },
+  {
+    label: 'transition-duration',
+    match: /^transition-duration$/,
+    detail: 'spark-html-motion — duration in ms',
+    doc: 'Duration of the enter/leave transition in milliseconds: `transition-duration="300"`.',
+  },
+  {
+    label: 'transition-easing',
+    match: /^transition-easing$/,
+    detail: 'spark-html-motion — CSS easing',
+    doc: 'Easing for the enter/leave transition: `transition-easing="ease-out"` (any CSS easing).',
+  },
+  {
+    label: 'spark-ignore',
+    match: /^spark-ignore$/,
+    detail: 'escape hatch — subtree never patched',
+    doc: 'Spark never touches this element or its children — no interpolation, no patching. For third-party widgets and code samples containing literal `{braces}`.',
+  },
+  {
+    label: ':hidden',
+    match: /^:[\w-]+$/,
+    detail: 'dynamic attribute — :attr="expr"',
+    doc: 'Any attribute prefixed with `:` is re-evaluated on every state change: `<button :disabled="count >= 10">`, `<div :class="active ? \'on\' : \'off\'">`, `<p :hidden="!open">`. Boolean results toggle the attribute; other values are set as strings.',
+  },
+];
+
+// Script-side builtins (hover inside <script>).
+export const SCRIPT_BUILTINS = {
+  useStore: 'Subscribe this component to a named store and return its reactive proxy: `const cart = useStore(\'cart\')`. The store must be created with `store(name, initial)` before `mount()`.',
+  onMount: 'Run a callback after the component is mounted and painted: `onMount(() => { …; return () => cleanup(); })`. The returned function runs when the component is destroyed.',
+  props: 'The raw props object passed from the import placeholder\'s attributes. Prefer `export let name = default` for individual declared props.',
+  '$:': 'Reactive statement: `$: doubled = count * 2` re-runs whenever any variable it reads changes, before the DOM patch. The assigned variable is implicitly declared.',
+};
+
+export function directiveDoc(word) {
+  for (const d of DIRECTIVES) if (d.match.test(word)) return d;
+  return null;
+}
+
+// Completion list for attribute position (label, detail, doc).
+export function directiveCompletions() {
+  const items = DIRECTIVES.filter((d) => d.label !== ':hidden').map((d) => ({
+    label: d.label,
+    detail: d.detail,
+    documentation: d.doc,
+  }));
+  for (const attr of [':hidden', ':disabled', ':class', ':style']) {
+    items.push({
+      label: attr,
+      detail: 'dynamic attribute — re-evaluated on every state change',
+      documentation: DIRECTIVES.find((d) => d.label === ':hidden').doc,
+    });
+  }
+  for (const t of ['transition:fade', 'transition:slide', 'transition:scale']) {
+    items.push({
+      label: t,
+      detail: 'spark-html-motion — enter/leave animation',
+      documentation: DIRECTIVES.find((d) => d.label === 'transition').doc,
+    });
+  }
+  return items;
+}

package/src/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * spark-html-language-server — LSP for single-file Spark components.
+ *
+ * Most users never import this module: editors launch the
+ * `spark-html-language-server` binary (LSP over stdio). The programmatic API
+ * exists for tests and tooling that want the analyzer directly.
+ */
+
+export interface Declaration {
+  kind: 'prop' | 'let' | 'function' | 'reactive' | 'import';
+  offset: number;
+}
+
+export interface Diagnostic {
+  start: number;
+  end: number;
+  /** LSP severity: 1 error, 2 warning, 3 info, 4 hint */
+  severity: 1 | 2 | 3 | 4;
+  message: string;
+  code: string;
+}
+
+export interface Analysis {
+  script: { start: number; end: number } | null;
+  declarations: Map<string, Declaration>;
+  props: { name: string; offset: number }[];
+  imports: { spec: string; locals: { name: string; offset: number }[] }[];
+  templateRefs: { name: string; offset: number }[];
+  importTags: { path: string; valueStart: number; valueEnd: number; tagStart: number; tagEnd: number }[];
+  diagnostics: Diagnostic[];
+}
+
+/** Analyze a component source string (offsets are into that string). */
+export function analyze(text: string): Analysis;
+
+/** The LSP server core — transport-agnostic; feed it decoded JSON-RPC messages. */
+export class SparkLanguageServer {
+  constructor(options: { send: (message: object) => void });
+  handle(message: { id?: number | string; method: string; params?: any }): void;
+}
+
+/** Start the server on stdio with Content-Length framing (what the bin runs). */
+export function connectStdio(): SparkLanguageServer;
+
+export function offsetToPosition(text: string, offset: number): { line: number; character: number };
+export function positionToOffset(text: string, pos: { line: number; character: number }): number;

package/src/index.js

@@ -0,0 +1,3 @@
+export { analyze, exprRefs, maskJs, KNOWN_GLOBALS } from './analyze.js';
+export { SparkLanguageServer, connectStdio, offsetToPosition, positionToOffset } from './server.js';
+export { DIRECTIVES, directiveDoc, directiveCompletions, SCRIPT_BUILTINS } from './docs.js';

package/src/server.js

@@ -0,0 +1,343 @@
+/**
+ * spark-html-language-server — the LSP server.
+ *
+ * Speaks Language Server Protocol over JSON-RPC. Transport-agnostic: the
+ * class handles decoded messages and emits replies through `send`; the CLI
+ * (bin/cli.js) wires it to stdio with Content-Length framing. Tests drive
+ * `handle()` directly — no child process, no flakiness.
+ *
+ * Features: publishDiagnostics (on open/change), completion (component props
+ * from the target's `export let`, template directives, script symbols),
+ * hover (directive + builtin docs, declaration info), and go-to-definition
+ * (component imports → file, identifiers → their declaration).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { analyze } from './analyze.js';
+import { directiveDoc, directiveCompletions, SCRIPT_BUILTINS } from './docs.js';
+
+// ── position mapping ───────────────────────────────────────────────────────
+
+export function offsetToPosition(text, offset) {
+  let line = 0;
+  let last = 0;
+  for (let i = 0; i < offset && i < text.length; i++) {
+    if (text[i] === '\n') { line++; last = i + 1; }
+  }
+  return { line, character: Math.min(offset, text.length) - last };
+}
+
+export function positionToOffset(text, pos) {
+  let line = 0;
+  let i = 0;
+  while (line < pos.line && i < text.length) {
+    if (text[i] === '\n') line++;
+    i++;
+  }
+  return Math.min(i + pos.character, text.length);
+}
+
+const range = (text, start, end) => ({
+  start: offsetToPosition(text, start),
+  end: offsetToPosition(text, end),
+});
+
+// Word under the cursor, including the directive charset (`bind:value`,
+// `:hidden`, `else-if`, `$:`).
+function wordAt(text, offset) {
+  const chars = /[\w$:.-]/;
+  let s = offset;
+  let e = offset;
+  while (s > 0 && chars.test(text[s - 1])) s--;
+  while (e < text.length && chars.test(text[e])) e++;
+  return { word: text.slice(s, e), start: s, end: e };
+}
+
+// ── server ─────────────────────────────────────────────────────────────────
+
+export class SparkLanguageServer {
+  constructor({ send }) {
+    this.send = send;
+    this.docs = new Map(); // uri -> { text, analysis }
+    this.rootPath = null;
+  }
+
+  handle(msg) {
+    const { id, method, params } = msg;
+    const respond = (result) => this.send({ jsonrpc: '2.0', id, result });
+    try {
+      switch (method) {
+        case 'initialize':
+          this.rootPath = params?.rootUri ? fileURLToPath(params.rootUri)
+            : params?.rootPath || null;
+          return respond({
+            capabilities: {
+              textDocumentSync: 1, // full
+              completionProvider: { triggerCharacters: ['{', ':', '"', ' ', '.'] },
+              hoverProvider: true,
+              definitionProvider: true,
+            },
+            serverInfo: { name: 'spark-html-language-server' },
+          });
+        case 'initialized':
+        case 'exit':
+          return;
+        case 'shutdown':
+          return respond(null);
+        case 'textDocument/didOpen':
+          return this.open(params.textDocument.uri, params.textDocument.text);
+        case 'textDocument/didChange':
+          return this.open(params.textDocument.uri, params.contentChanges[0].text);
+        case 'textDocument/didClose':
+          this.docs.delete(params.textDocument.uri);
+          return this.send({
+            jsonrpc: '2.0',
+            method: 'textDocument/publishDiagnostics',
+            params: { uri: params.textDocument.uri, diagnostics: [] },
+          });
+        case 'textDocument/completion':
+          return respond(this.completion(params));
+        case 'textDocument/hover':
+          return respond(this.hover(params));
+        case 'textDocument/definition':
+          return respond(this.definition(params));
+        default:
+          // Respond to unknown requests (they have an id) so clients don't hang.
+          if (id !== undefined) respond(null);
+      }
+    } catch (e) {
+      if (id !== undefined) {
+        this.send({ jsonrpc: '2.0', id, error: { code: -32603, message: e.message } });
+      }
+    }
+  }
+
+  open(uri, text) {
+    const analysis = analyze(text);
+    this.docs.set(uri, { text, analysis });
+    const diagnostics = analysis.diagnostics.map((d) => ({
+      range: range(text, d.start, d.end),
+      severity: d.severity,
+      message: d.message,
+      code: d.code,
+      source: 'spark',
+      ...(d.code === 'unused-import' ? { tags: [1] } : {}), // Unnecessary
+    }));
+    // Component placeholders pointing at files that don't exist.
+    for (const tag of analysis.importTags) {
+      const file = this.resolveImport(uri, tag.path);
+      if (file === undefined) continue; // remote / unresolvable — not checked
+      if (!file) {
+        diagnostics.push({
+          range: range(text, tag.valueStart, tag.valueEnd),
+          severity: 2,
+          message: `Component file not found: "${tag.path}" (looked for it relative to this file${this.rootPath ? ' and the workspace root' : ''}).`,
+          code: 'component-not-found',
+          source: 'spark',
+        });
+      }
+    }
+    this.send({
+      jsonrpc: '2.0',
+      method: 'textDocument/publishDiagnostics',
+      params: { uri, diagnostics },
+    });
+  }
+
+  // Resolve a placeholder path to an existing file. Returns the path, null
+  // (checked, missing), or undefined (remote URL — out of scope).
+  resolveImport(docUri, path) {
+    if (/^[a-z]+:\/\//i.test(path)) return undefined;
+    let docDir;
+    try { docDir = dirname(fileURLToPath(docUri)); } catch { return undefined; }
+    const bases = path.startsWith('/')
+      ? [this.rootPath, resolve(this.rootPath || docDir, 'public')].filter(Boolean)
+      : [docDir];
+    for (const base of bases) {
+      const target = path.startsWith('/') ? resolve(base, path.slice(1)) : resolve(base, path);
+      for (const candidate of [target, `${target}.html`]) {
+        if (existsSync(candidate)) return candidate;
+      }
+    }
+    // Components often live under public/ (served from the web root).
+    if (!path.startsWith('/')) {
+      for (const extra of ['public', '.']) {
+        if (!this.rootPath) break;
+        const target = resolve(this.rootPath, extra, path);
+        for (const candidate of [target, `${target}.html`]) {
+          if (existsSync(candidate)) return candidate;
+        }
+      }
+    }
+    return null;
+  }
+
+  // ── completion ───────────────────────────────────────────────────────────
+
+  completion({ textDocument, position }) {
+    const doc = this.docs.get(textDocument.uri);
+    if (!doc) return null;
+    const { text, analysis } = doc;
+    const offset = positionToOffset(text, position);
+
+    const symbolItems = () => {
+      const items = [];
+      for (const [name, d] of analysis.declarations) {
+        items.push({
+          label: name,
+          kind: d.kind === 'function' ? 3 : d.kind === 'prop' ? 5 : 6,
+          detail: { prop: 'prop (export let)', let: 'state (let)', function: 'function', reactive: 'reactive ($:)', import: 'import' }[d.kind],
+        });
+      }
+      for (const [name, doc_] of Object.entries(SCRIPT_BUILTINS)) {
+        if (name === '$:') continue;
+        items.push({ label: name, kind: 3, detail: 'spark builtin', documentation: doc_ });
+      }
+      return items;
+    };
+
+    // Inside the component <script>? Complete script symbols.
+    const s = analysis.script;
+    if (s && offset >= s.start && offset <= s.end) return { isIncomplete: false, items: symbolItems() };
+
+    // Inside a tag (a `<` after the last `>`)?
+    const lastOpen = text.lastIndexOf('<', offset - 1);
+    const lastClose = text.lastIndexOf('>', offset - 1);
+    if (lastOpen > lastClose) {
+      const tagText = text.slice(lastOpen, offset);
+      const quotes = (tagText.match(/"/g) || []).length;
+      if (quotes % 2 === 0) {
+        // Attribute-name position. On a placeholder, offer the target's props.
+        const impM = tagText.match(/\bimport\s*=\s*"([^"]*)"/);
+        const items = [];
+        if (impM) {
+          const file = this.resolveImport(textDocument.uri, impM[1]);
+          if (file) {
+            try {
+              const target = analyze(readFileSync(file, 'utf8'));
+              for (const p of target.props) {
+                items.push({ label: p.name, kind: 5, detail: `prop of ${impM[1]}`, sortText: `0${p.name}` });
+              }
+            } catch { /* unreadable target — just skip props */ }
+          }
+        }
+        items.push(...directiveCompletions().map((c) => ({ ...c, kind: 14 })));
+        return { isIncomplete: false, items };
+      }
+      return null; // inside an attribute value — no completions
+    }
+
+    // After an unclosed `{` in text? Complete script symbols.
+    const braceOpen = text.lastIndexOf('{', offset - 1);
+    if (braceOpen > -1 && braceOpen > text.lastIndexOf('}', offset - 1) && offset - braceOpen < 200) {
+      return { isIncomplete: false, items: symbolItems() };
+    }
+    return null;
+  }
+
+  // ── hover ────────────────────────────────────────────────────────────────
+
+  hover({ textDocument, position }) {
+    const doc = this.docs.get(textDocument.uri);
+    if (!doc) return null;
+    const { text, analysis } = doc;
+    const offset = positionToOffset(text, position);
+    const { word, start, end } = wordAt(text, offset);
+    if (!word) return null;
+    const md = (value) => ({
+      contents: { kind: 'markdown', value },
+      range: range(text, start, end),
+    });
+
+    const s = analysis.script;
+    const inScript = s && offset >= s.start && offset <= s.end;
+
+    if (inScript) {
+      if (word === '$' || word.startsWith('$:')) return md(`**\`$:\`** — ${SCRIPT_BUILTINS['$:']}`);
+      if (SCRIPT_BUILTINS[word]) return md(`**\`${word}\`** — ${SCRIPT_BUILTINS[word]}`);
+    } else {
+      const d = directiveDoc(word.replace(/=.*$/, ''));
+      if (d) return md(`**\`${d.label}\`** · ${d.detail}\n\n${d.doc}`);
+    }
+
+    const bare = word.match(/[A-Za-z_$][\w$]*/)?.[0];
+    const decl = bare && analysis.declarations.get(bare);
+    if (decl) {
+      const label = {
+        prop: `prop — \`export let ${bare}\` (overridable from the import placeholder)`,
+        let: `component state — \`let ${bare}\` (reactive)`,
+        function: `function \`${bare}()\``,
+        reactive: `derived — \`$: ${bare} = …\` (recomputed on every change)`,
+        import: `imported binding \`${bare}\``,
+      }[decl.kind];
+      return md(label);
+    }
+    return null;
+  }
+
+  // ── definition ───────────────────────────────────────────────────────────
+
+  definition({ textDocument, position }) {
+    const doc = this.docs.get(textDocument.uri);
+    if (!doc) return null;
+    const { text, analysis } = doc;
+    const offset = positionToOffset(text, position);
+
+    // On an import="…" value → the component file.
+    for (const tag of analysis.importTags) {
+      if (offset >= tag.tagStart && offset <= (tag.tagEnd === -1 ? text.length : tag.tagEnd)) {
+        const file = this.resolveImport(textDocument.uri, tag.path);
+        if (file) {
+          return {
+            uri: pathToFileURL(file).href,
+            range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
+          };
+        }
+      }
+    }
+
+    // On an identifier → its declaration in this component.
+    const { word } = wordAt(text, offset);
+    const bare = word.match(/[A-Za-z_$][\w$]*/)?.[0];
+    const decl = bare && analysis.declarations.get(bare);
+    if (decl && decl.offset !== undefined) {
+      return {
+        uri: textDocument.uri,
+        range: range(text, decl.offset, decl.offset + bare.length),
+      };
+    }
+    return null;
+  }
+}
+
+// ── stdio transport (Content-Length framing) ───────────────────────────────
+
+export function connectStdio() {
+  const server = new SparkLanguageServer({
+    send: (msg) => {
+      const body = JSON.stringify(msg);
+      process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+    },
+  });
+  let buffer = Buffer.alloc(0);
+  process.stdin.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    for (;;) {
+      const headerEnd = buffer.indexOf('\r\n\r\n');
+      if (headerEnd === -1) return;
+      const header = buffer.slice(0, headerEnd).toString();
+      const length = Number(header.match(/Content-Length:\s*(\d+)/i)?.[1]);
+      if (!length || buffer.length < headerEnd + 4 + length) return;
+      const body = buffer.slice(headerEnd + 4, headerEnd + 4 + length).toString();
+      buffer = buffer.slice(headerEnd + 4 + length);
+      let msg;
+      try { msg = JSON.parse(body); } catch { continue; }
+      if (msg.method === 'exit') process.exit(0);
+      server.handle(msg);
+    }
+  });
+  process.stdin.on('end', () => process.exit(0));
+  return server;
+}