@nvl/sveltex-math-language-server 0.2.0

package/dist/core/describe.js

@@ -0,0 +1,144 @@
+// File description: Human-readable descriptions and hover text for TeX
+// commands, used in both completion-item documentation and hover.
+//
+// A command's one-line description is the first available of three sources:
+// the documentation metadata merged into `data/commands.generated.ts` from
+// each engine's reference docs (the richest, but not exhaustive); a small
+// curated map of hand-written glosses for high-frequency commands; and finally
+// a generic, category-driven sentence, so EVERY supported command gets *some*
+// description. Hover additionally shows the command's signature, the Unicode
+// glyph it stands for (when any), and a backend/package/category footer.
+// Nothing here claims a command exists: the command set itself is sourced from
+// the backend in `data/commands.generated.ts`.
+/**
+ * A small, curated map of bare command name → one-line gloss, for the commands
+ * a description sentence alone would not usefully explain.
+ */
+const GLOSSES = {
+    frac: 'Typesets a fraction with the given numerator and denominator.',
+    dfrac: 'Display-style fraction (always full size).',
+    tfrac: 'Text-style fraction (always small).',
+    sqrt: 'Square root; an optional argument gives the index (e.g. cube root).',
+    sum: 'Summation operator (∑), commonly used with sub/superscript limits.',
+    prod: 'Product operator (∏).',
+    int: 'Integral operator (∫).',
+    iint: 'Double integral operator (∬).',
+    iiint: 'Triple integral operator (∭).',
+    oint: 'Contour integral operator (∮).',
+    lim: 'Limit operator, typically with an underscript (e.g. x → 0).',
+    text: 'Typesets its argument as upright text inside math mode.',
+    mathrm: 'Upright (roman) math font.',
+    mathbf: 'Bold math font.',
+    mathit: 'Italic math font.',
+    mathsf: 'Sans-serif math font.',
+    mathtt: 'Monospace (typewriter) math font.',
+    mathcal: 'Calligraphic math font (uppercase letters).',
+    mathbb: 'Blackboard-bold math font (e.g. ℝ, ℕ, ℤ).',
+    mathfrak: 'Fraktur math font.',
+    boldsymbol: 'Bold version of its argument, including symbols.',
+    hat: 'Places a hat accent over its argument.',
+    bar: 'Places a bar accent over its argument.',
+    vec: 'Places a vector arrow over its argument.',
+    dot: 'Places a single dot accent over its argument.',
+    ddot: 'Places a double dot accent over its argument.',
+    tilde: 'Places a tilde accent over its argument.',
+    overline: 'Draws a line over its argument.',
+    underline: 'Draws a line under its argument.',
+    overbrace: 'Draws a horizontal brace over its argument.',
+    underbrace: 'Draws a horizontal brace under its argument.',
+    left: 'Opens an auto-sized delimiter; pair with \\right.',
+    right: 'Closes an auto-sized delimiter; pair with \\left.',
+    begin: 'Opens an environment, e.g. \\begin{matrix}.',
+    end: 'Closes an environment opened with \\begin.',
+    binom: 'Typesets a binomial coefficient.',
+    cdot: 'Centred multiplication dot (⋅).',
+    times: 'Multiplication cross (×).',
+    div: 'Division sign (÷).',
+    pm: 'Plus-or-minus sign (±).',
+    mp: 'Minus-or-plus sign (∓).',
+    leq: 'Less-than-or-equal sign (≤).',
+    geq: 'Greater-than-or-equal sign (≥).',
+    neq: 'Not-equal sign (≠).',
+    approx: 'Approximately-equal sign (≈).',
+    equiv: 'Equivalence / identity sign (≡).',
+    infty: 'Infinity symbol (∞).',
+    partial: 'Partial-derivative symbol (∂).',
+    nabla: 'Nabla / del operator (∇).',
+    forall: 'Universal quantifier (∀).',
+    exists: 'Existential quantifier (∃).',
+    in: 'Set-membership sign (∈).',
+    subset: 'Subset sign (⊂).',
+    cup: 'Set union (∪).',
+    cap: 'Set intersection (∩).',
+    rightarrow: 'Rightward arrow (→).',
+    leftarrow: 'Leftward arrow (←).',
+    Rightarrow: 'Rightward double arrow (⇒).',
+    Leftarrow: 'Leftward double arrow (⇐).',
+    operatorname: 'Typesets its argument as a named operator (upright).',
+    color: 'Sets the colour of the following material.',
+    textcolor: 'Typesets its argument in the given colour.',
+    ce: 'mhchem: typesets a chemical equation or formula.',
+    pu: 'mhchem: typesets a physical unit.',
+};
+/** Category-driven fallback sentences. */
+const CATEGORY_SENTENCE = {
+    function: 'A TeX command that takes one or more arguments.',
+    symbol: 'A TeX symbol command (produces a single glyph).',
+    macro: 'A TeX macro (defined in terms of other commands).',
+    environment: 'A TeX environment, used with \\begin{...} and \\end{...}.',
+};
+/** Human-readable backend names for hover text. */
+const BACKEND_LABEL = {
+    katex: 'KaTeX',
+    mathjax: 'MathJax',
+};
+/**
+ * Returns the one-line description of a command: the documentation-sourced
+ * description when the generator merged one in, else a curated gloss, else the
+ * generic category sentence (which is always available).
+ *
+ * @param command - The command to describe.
+ */
+export function describeCommand(command) {
+    return (command.description ??
+        GLOSSES[command.name] ??
+        CATEGORY_SENTENCE[command.category]);
+}
+/**
+ * Builds the Markdown body shown on hover for a command.
+ *
+ * The body is, in order: a fenced `latex` block with the command's signature
+ * (its arguments spelled out when it takes any); for a command that stands for
+ * a Unicode glyph, that glyph and its Unicode standard name; the one-line
+ * description; and a dimmed footer naming the backend, the providing package
+ * (when known) and the category.
+ *
+ * @param command - The command being hovered.
+ * @param backend - The active backend, named in the footer so the user knows
+ * which engine's support they are seeing.
+ * @returns A Markdown string.
+ */
+export function hoverMarkdown(command, backend) {
+    const lines = [];
+    // The signature comes first: how the command is actually used. A merged-in
+    // `signature` spells out the arguments; otherwise the bare `\name` (or a
+    // `\begin…\end` pair for an environment) stands in.
+    const usage = command.signature ??
+        (command.category === 'environment'
+            ? `\\begin{${command.name}} … \\end{${command.name}}`
+            : `\\${command.name}`);
+    lines.push('```latex', usage, '```', '');
+    // For a command that denotes a Unicode glyph, show the glyph and its
+    // Unicode standard name — e.g. `∮ (contour integral)`.
+    if (command.unicode) {
+        const named = command.unicodeName ? ` (${command.unicodeName})` : '';
+        lines.push(`**${command.unicode}**${named}`, '');
+    }
+    lines.push(describeCommand(command), '');
+    // A dimmed footer: backend · package (when known) · category.
+    const footer = [BACKEND_LABEL[backend], command.package, command.category]
+        .filter((part) => Boolean(part))
+        .join(' · ');
+    lines.push(`_${footer}_`);
+    return lines.join('\n');
+}

package/dist/core/features.d.ts

@@ -0,0 +1,24 @@
+import { type CompletionList, type Hover, type Position } from 'vscode-languageserver-protocol';
+import type { CommandTable, MathLspBackend } from './commands.js';
+/**
+ * Computes the completion result for a caret in a TeX math document.
+ *
+ * @param text - Full text of the (virtual) TeX math document.
+ * @param position - The caret position.
+ * @param table - The active backend's command table.
+ * @returns A {@link CompletionList}. The list is empty (but never `null`) when
+ * the caret is not in a command-typing context, so the editor caches the
+ * "nothing here" answer rather than re-asking on every keystroke.
+ */
+export declare function computeCompletion(text: string, position: Position, table: CommandTable): CompletionList;
+/**
+ * Computes the hover result for a caret in a TeX math document.
+ *
+ * @param text - Full text of the (virtual) TeX math document.
+ * @param position - The caret position.
+ * @param table - The active backend's command table.
+ * @param backend - The active backend (named in the hover text).
+ * @returns A {@link Hover}, or `null` when the caret is not on a command the
+ * backend supports.
+ */
+export declare function computeHover(text: string, position: Position, table: CommandTable, backend: MathLspBackend): Hover | null;

package/dist/core/features.js

@@ -0,0 +1,140 @@
+// File description: The pure language-feature layer — turning a TeX document +
+// caret position into LSP completion and hover results.
+//
+// Everything here is deterministic and side-effect-free: it takes the document
+// text, a caret offset, and the active backend's `CommandTable`, and returns
+// plain LSP payloads. The transport/connection wiring lives in `server.ts`;
+// keeping the features pure makes them trivial to unit-test.
+import { CompletionItemKind, InsertTextFormat, MarkupKind, } from 'vscode-languageserver-protocol';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+import { commandAtCaret, completionContextAt } from './context.js';
+import { describeCommand, hoverMarkdown } from './describe.js';
+/** Maps a {@link CommandCategory} to the LSP completion-item icon. */
+function completionKind(category) {
+    switch (category) {
+        case 'function':
+            return CompletionItemKind.Function;
+        case 'macro':
+            return CompletionItemKind.Method;
+        case 'environment':
+            return CompletionItemKind.Module;
+        case 'symbol':
+            return CompletionItemKind.Constant;
+        default:
+            return CompletionItemKind.Text;
+    }
+}
+/** A short, fixed sort prefix so functions/symbols rank above rare macros. */
+function sortPrefix(category) {
+    switch (category) {
+        case 'function':
+            return '0';
+        case 'symbol':
+            return '1';
+        case 'environment':
+            return '2';
+        case 'macro':
+            return '3';
+        default:
+            return '4';
+    }
+}
+/**
+ * Builds the {@link CompletionItem} for one command.
+ *
+ * @param command - The command to offer.
+ * @param replaceRange - The source range the inserted text replaces (from the
+ * opening backslash, or the start of the environment name, to the caret).
+ * @param isEnvironmentName - When `true` the caret is inside `\begin{...}`, so
+ * the inserted text is the bare environment name; otherwise it is
+ * `\command`.
+ */
+function buildCompletionItem(command, replaceRange, isEnvironmentName) {
+    // Inside `\begin{...}` the slot holds a bare environment name; everywhere
+    // else a command is `\name`. The label mirrors what is inserted.
+    const insertText = isEnvironmentName ? command.name : `\\${command.name}`;
+    const label = insertText;
+    return {
+        label,
+        kind: completionKind(command.category),
+        detail: command.category,
+        documentation: {
+            kind: MarkupKind.Markdown,
+            value: describeCommand(command),
+        },
+        // A fixed sort group keeps categories clustered; the name disambiguates
+        // within a group, so completion order is stable and predictable.
+        sortText: `${sortPrefix(command.category)}${command.name}`,
+        // No `filterText` — it defaults to `label`. `textEdit.range` starts at
+        // the `\`, so the editor's filter query is the typed text *including*
+        // that `\` (`\alp`); it must be matched against `\alpha` (the label),
+        // not the bare `alpha`, or the item is filtered out and never shown.
+        insertTextFormat: InsertTextFormat.PlainText,
+        textEdit: { range: replaceRange, newText: insertText },
+    };
+}
+/** Upper bound on how many completion items are returned in one response. */
+const MAX_COMPLETION_ITEMS = 500;
+/**
+ * Computes the completion result for a caret in a TeX math document.
+ *
+ * @param text - Full text of the (virtual) TeX math document.
+ * @param position - The caret position.
+ * @param table - The active backend's command table.
+ * @returns A {@link CompletionList}. The list is empty (but never `null`) when
+ * the caret is not in a command-typing context, so the editor caches the
+ * "nothing here" answer rather than re-asking on every keystroke.
+ */
+export function computeCompletion(text, position, table) {
+    const doc = TextDocument.create('mem://tex', 'latex', 0, text);
+    const offset = doc.offsetAt(position);
+    const context = completionContextAt(text, offset);
+    if (!context) {
+        return { isIncomplete: false, items: [] };
+    }
+    const matches = table.withPrefix(context.prefix, context.isEnvironmentName);
+    const replaceRange = {
+        start: doc.positionAt(context.backslashOffset),
+        end: position,
+    };
+    const limited = matches.slice(0, MAX_COMPLETION_ITEMS);
+    return {
+        // `isIncomplete` is set when the list was truncated, so the editor
+        // re-queries as the user narrows the prefix.
+        isIncomplete: matches.length > limited.length,
+        items: limited.map((command) => buildCompletionItem(command, replaceRange, context.isEnvironmentName)),
+    };
+}
+/**
+ * Computes the hover result for a caret in a TeX math document.
+ *
+ * @param text - Full text of the (virtual) TeX math document.
+ * @param position - The caret position.
+ * @param table - The active backend's command table.
+ * @param backend - The active backend (named in the hover text).
+ * @returns A {@link Hover}, or `null` when the caret is not on a command the
+ * backend supports.
+ */
+export function computeHover(text, position, table, backend) {
+    const doc = TextDocument.create('mem://tex', 'latex', 0, text);
+    const offset = doc.offsetAt(position);
+    const found = commandAtCaret(text, offset);
+    if (!found)
+        return null;
+    // A hovered control word might be an environment name without the
+    // surrounding `\begin{}`; try the command form first, then accept an
+    // environment of the same name.
+    const command = table.get(found.name);
+    if (!command)
+        return null;
+    return {
+        contents: {
+            kind: MarkupKind.Markdown,
+            value: hoverMarkdown(command, backend),
+        },
+        range: {
+            start: doc.positionAt(found.start),
+            end: doc.positionAt(found.end),
+        },
+    };
+}

package/dist/core/server.d.ts

@@ -0,0 +1,24 @@
+import { type Connection, type InitializeParams } from 'vscode-languageserver';
+import { type MathLspBackend } from './commands.js';
+/**
+ * Parses the math backend out of the `initialize` request's
+ * `initializationOptions`.
+ *
+ * @param params - The LSP `initialize` params.
+ * @returns `'katex'` or `'mathjax'`. Defaults to `'mathjax'` when the option is
+ * absent or unrecognised — MathJax is SvelTeX's default math backend, so an
+ * unconfigured client gets the most representative behaviour.
+ */
+export declare function resolveBackend(params: InitializeParams): MathLspBackend;
+/**
+ * Wires a SvelTeX math language server onto the given connection.
+ *
+ * @param connection - An LSP {@link Connection}, already created for whatever
+ * transport the host uses. This function never calls `listen()`; the caller
+ * owns the connection lifecycle.
+ *
+ * @remarks
+ * Transport-agnostic by construction (no `vscode` import, no stdio access), so
+ * the same core backs `bin/server.js` and any in-process host.
+ */
+export declare function createServer(connection: Connection): void;

package/dist/core/server.js

@@ -0,0 +1,93 @@
+// File description: `createServer` — the transport-agnostic core of the
+// SvelTeX math language server.
+//
+// This server is small and standalone: it provides command completion and
+// hover for TeX math, for one of two backends — KaTeX or MathJax — chosen via
+// the LSP `initialize` request's `initializationOptions.backend`. It is spawned
+// (one child per backend) by `@nvl/sveltex-language-server`, which feeds it the
+// math regions of a `.sveltex` file as tiny virtual TeX documents, but it is a
+// perfectly ordinary LSP and could equally be launched directly by any editor.
+//
+// `createServer(connection)` takes an already-built LSP `Connection` and never
+// touches the transport — exactly the core/wrapper split used by
+// `@nvl/sveltex-language-server`, so the same core backs the stdio `bin/server.js`
+// and any in-process host.
+import { TextDocuments, TextDocumentSyncKind, } from 'vscode-languageserver';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+import { createCommandTable, } from './commands.js';
+import { computeCompletion, computeHover } from './features.js';
+/**
+ * Parses the math backend out of the `initialize` request's
+ * `initializationOptions`.
+ *
+ * @param params - The LSP `initialize` params.
+ * @returns `'katex'` or `'mathjax'`. Defaults to `'mathjax'` when the option is
+ * absent or unrecognised — MathJax is SvelTeX's default math backend, so an
+ * unconfigured client gets the most representative behaviour.
+ */
+export function resolveBackend(params) {
+    const options = params.initializationOptions;
+    if (options && typeof options === 'object' && 'backend' in options) {
+        const backend = options.backend;
+        if (backend === 'katex' || backend === 'mathjax')
+            return backend;
+    }
+    return 'mathjax';
+}
+/**
+ * Wires a SvelTeX math language server onto the given connection.
+ *
+ * @param connection - An LSP {@link Connection}, already created for whatever
+ * transport the host uses. This function never calls `listen()`; the caller
+ * owns the connection lifecycle.
+ *
+ * @remarks
+ * Transport-agnostic by construction (no `vscode` import, no stdio access), so
+ * the same core backs `bin/server.js` and any in-process host.
+ */
+export function createServer(connection) {
+    // Open documents are tracked with the standard `TextDocuments` manager,
+    // which applies incremental sync for us — math regions are small, but a
+    // shared manager keeps the server simple and correct.
+    const documents = new TextDocuments(TextDocument);
+    /** The backend selected at `initialize`; until then, the default. */
+    let backend = 'mathjax';
+    /** The command table for {@link backend}, rebuilt when the backend is set. */
+    let table = createCommandTable(backend);
+    connection.onInitialize((params) => {
+        backend = resolveBackend(params);
+        table = createCommandTable(backend);
+        return {
+            capabilities: {
+                textDocumentSync: TextDocumentSyncKind.Incremental,
+                // `\` opens a command; `{` opens the environment-name slot of
+                // a `\begin{...}` — both should re-trigger completion.
+                completionProvider: {
+                    triggerCharacters: ['\\', '{'],
+                    resolveProvider: false,
+                },
+                hoverProvider: true,
+            },
+            serverInfo: {
+                name: 'sveltex-math-language-server',
+            },
+        };
+    });
+    connection.onCompletion((params) => {
+        const doc = documents.get(params.textDocument.uri);
+        if (!doc)
+            return { isIncomplete: false, items: [] };
+        return computeCompletion(doc.getText(), params.position, table);
+    });
+    connection.onHover((params) => {
+        const doc = documents.get(params.textDocument.uri);
+        if (!doc)
+            return null;
+        return computeHover(doc.getText(), params.position, table, backend);
+    });
+    // `TextDocuments` needs the connection to receive `didOpen`/`didChange`/
+    // `didClose`; `listen` only registers handlers, it does not start the
+    // transport (that is the caller's job). Completion and hover read the
+    // current document text on demand, so no change listener is needed.
+    documents.listen(connection);
+}

package/dist/data/commands.generated.d.ts

@@ -0,0 +1,13 @@
+import type { CommandCategory, MathCommand } from '../core/commands.js';
+/**
+ * Every TeX command KaTeX supports (1059 entries), extracted from
+ * `katex`'s `functions`, `symbols` and `macros` tables.
+ */
+export declare const KATEX_COMMANDS: readonly MathCommand[];
+/**
+ * Every TeX command the default MathJax `input/tex` configuration supports
+ * (946 entries), extracted from `@mathjax/src`'s registered token maps
+ * for the always-loaded and `autoload`-reachable packages.
+ */
+export declare const MATHJAX_COMMANDS: readonly MathCommand[];
+export type { CommandCategory, MathCommand };