@nvl/sveltex-language-server 0.2.0

package/dist/core/frontmatter.js

@@ -0,0 +1,348 @@
+// File description: Hover and completion for a `.sveltex` frontmatter block.
+//
+// A `.sveltex` document may open with a YAML / TOML / JSON frontmatter block.
+// SvelTeX reads it and renders the recognised keys into the document's
+// `<svelte:head>` — `title` becomes `<title>`, `meta` becomes `<meta>` tags,
+// and so on. This module documents that mapping, surfacing it as hover text
+// and as completion suggestions.
+//
+// Both are *context-aware*: which keys are valid depends on the block the
+// caret sits in — the top level, or inside `meta` / `base` / `link` — so e.g.
+// `title` is documented and suggested at the top level but not inside `meta`,
+// where SvelTeX would not render it as a title.
+//
+// Frontmatter is a non-delegated region: the embedded Svelte language server
+// never sees it. Hover and completion here are therefore computed natively.
+// They need no position mapping — a frontmatter region is verbatim `.sveltex`
+// source, so a token's line/character already are its source coordinates —
+// and no real YAML/TOML/JSON parse: the line a key sits on, and which block
+// encloses it, are recognised by small line-shaped patterns that cover all
+// three syntaxes.
+import { CompletionItemKind, MarkupKind, } from 'vscode-languageserver-protocol';
+import { keysForContext, metaHeadEffect, metaRenderedHtml, META_HTTP_EQUIV, META_NAMES, } from './frontmatter-data.js';
+/**
+ * Splits a single frontmatter line into its key and first value token.
+ *
+ * Recognises all three frontmatter syntaxes with one shape: `key: value`
+ * (YAML / JSON), `key = value` (TOML), optionally quoted tokens, an optional
+ * leading YAML list-item dash, and a TOML `[table]` / `[[array]]` header
+ * (which has a key but no value).
+ *
+ * @param line - A single line of frontmatter text.
+ * @returns The key and value tokens found on the line (either may be absent).
+ */
+function parseFrontmatterLine(line) {
+    // `key: value` / `key = value` / `"key": "value"`, with an optional `- `
+    // list-item prefix. The value is the first token after the separator.
+    const keyValue = /^(\s*(?:-\s+)?)(['"]?)([A-Za-z_][\w-]*)\2(\s*[:=]\s*)(['"]?)([\w-][\w./-]*)?/u.exec(line);
+    if (keyValue) {
+        const [, indent = '', kq = '', key = '', sep = '', vq = '', value] = keyValue;
+        const keyStart = indent.length + kq.length;
+        const key_ = {
+            name: key,
+            start: keyStart,
+            end: keyStart + key.length,
+        };
+        if (value === undefined || value.length === 0)
+            return { key: key_ };
+        // The closing key quote is `\2`, i.e. another `kq`.
+        const valueStart = indent.length + kq.length * 2 + key.length + sep.length + vq.length;
+        return {
+            key: key_,
+            value: {
+                name: value,
+                start: valueStart,
+                end: valueStart + value.length,
+            },
+        };
+    }
+    // TOML table header: `[base]`, `[[meta]]` — a key with no value.
+    const table = /^(\s*\[+\s*)([A-Za-z_][\w-]*)/u.exec(line);
+    if (table) {
+        const [, prefix = '', name = ''] = table;
+        return {
+            key: {
+                name,
+                start: prefix.length,
+                end: prefix.length + name.length,
+            },
+        };
+    }
+    return {};
+}
+/** Whether the caret column falls on (or just past the end of) `token`. */
+function caretOn(caret, token) {
+    return caret >= token.start && caret <= token.end;
+}
+/**
+ * Finds which block a caret line sits inside — `meta`, `base` or `link` — by
+ * walking up to the nearest enclosing key: a less-indented YAML/JSON key, or
+ * a TOML `[table]` header. `undefined` means the frontmatter top level.
+ *
+ * @param lines - The `.sveltex` document split into lines.
+ * @param lineIndex - The caret's line index.
+ */
+function frontmatterContext(lines, lineIndex) {
+    const indentOf = (s) => (/^\s*/u.exec(s)?.[0] ?? '').length;
+    let minIndent = indentOf(lines[lineIndex] ?? '');
+    for (let i = lineIndex - 1; i >= 0; i -= 1) {
+        const raw = lines[i] ?? '';
+        const trimmed = raw.trim();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        // The frontmatter fence — the top of the block has been reached.
+        if (/^[-+]{3,}$/u.test(trimmed))
+            break;
+        // A TOML `[table]` / `[[table]]` header is the enclosing table.
+        const toml = /^\[+\s*([A-Za-z_][\w-]*)/u.exec(trimmed);
+        if (toml) {
+            const name = toml[1];
+            return name === 'meta' || name === 'base' || name === 'link'
+                ? name
+                : undefined;
+        }
+        // YAML / JSON: an ancestor is any line indented less than the caret.
+        const indent = indentOf(raw);
+        if (indent < minIndent) {
+            minIndent = indent;
+            const keyName = parseFrontmatterLine(raw).key?.name;
+            if (keyName === 'meta' ||
+                keyName === 'base' ||
+                keyName === 'link') {
+                return keyName;
+            }
+        }
+    }
+    return undefined;
+}
+/** Top-level keys whose value SvelTeX expects to be an object or array. */
+const STRUCTURED_VALUE_KEYS = new Set([
+    'base',
+    'meta',
+    'link',
+    'imports',
+]);
+/**
+ * The shape of a JavaScript identifier — used to decide whether a key
+ * needs quoting when written as an object-literal key in the rendered
+ * `metadata` example.
+ */
+const identifierRegExp = /^[A-Za-z_$][\w$]*$/u;
+/**
+ * Build the per-effect sections appended to the hover of a top-level
+ * frontmatter key — one per frontmatter-processing step the key takes
+ * part in. Each section names the step's `frontmatter: { … }` toggle so
+ * the reader learns how to switch it off.
+ *
+ * @param key - The bare key text — used to format the `metadata` object
+ * key in the rendered example.
+ * @param doc - The key's entry doc; `headEffect` / `element` decide the
+ * head section's sentence.
+ */
+function effectSections(key, doc) {
+    const sections = [];
+    const placeholder = STRUCTURED_VALUE_KEYS.has(key)
+        ? '〈value〉'
+        : '"〈value〉"';
+    const disableHint = (toggle) => `To turn this off, set \`frontmatter: { ${toggle}: false }\` in ` +
+        'your SvelTeX configuration.';
+    // <svelte:head> — structural keys supply `headEffect` explicitly,
+    // `<meta>` / `<meta http-equiv>` / `<meta charset>` keys derive it.
+    const head = doc.headEffect ??
+        (doc.element !== undefined ? metaHeadEffect(doc.element) : undefined);
+    if (head !== undefined) {
+        sections.push('---', '', head, '', disableHint('head'), '');
+    }
+    // `import` statements — only for the special `imports` key.
+    if (key === 'imports') {
+        sections.push('---', '', "Adds an `import` statement to the page's `<script>` for " +
+            'each entry — each key is the module path, each value ' +
+            'the binding(s) to import.', '', disableHint('imports'), '');
+    }
+    // `export const metadata` module-script export — the original key is
+    // preserved, quoted when it isn't a valid identifier.
+    const metaKey = identifierRegExp.test(key) ? key : JSON.stringify(key);
+    sections.push('---', '', `Adds \`${metaKey}: ${placeholder}\` to the page's \`metadata\` ` +
+        'export.', '', disableHint('metadata'), '');
+    return sections;
+}
+/**
+ * Builds the Markdown body shown when hovering a frontmatter key or value.
+ *
+ * @param name - The bare token text.
+ * @param doc - The token's {@link FrontmatterEntryDoc}.
+ * @param topLevelKey - The bare key text when the hover is over a top-level
+ * frontmatter key (not a nested-block key, not a value). When supplied,
+ * per-effect sections are appended describing what the key inserts into
+ * the page's `<svelte:head>` / `<script>` / `metadata` export, each with
+ * the `frontmatter: { … }` toggle that switches that step off.
+ */
+function entryHoverMarkdown(name, doc, topLevelKey) {
+    const rendered = doc.rendersAs ??
+        (doc.element !== undefined ? metaRenderedHtml(doc.element) : undefined);
+    const heading = rendered
+        ? `**\`${name}\`** — renders \`${rendered}\``
+        : `**\`${name}\`**`;
+    const linkLabel = doc.element
+        ? `\`${doc.element}\` on MDN`
+        : 'SvelTeX documentation';
+    const parts = [
+        heading,
+        '',
+        doc.summary,
+        '',
+        `[${linkLabel}](${doc.docUrl})`,
+        '',
+    ];
+    if (topLevelKey !== undefined) {
+        parts.push(...effectSections(topLevelKey, doc));
+    }
+    parts.push('_SvelTeX frontmatter_');
+    return parts.join('\n');
+}
+/**
+ * Wraps an entry doc and its token into an LSP {@link Hover}.
+ *
+ * @param topLevelKey - Forwarded to {@link entryHoverMarkdown}; supplied
+ * for hovers over a top-level frontmatter key so the markdown body is
+ * followed by per-effect sections.
+ */
+function entryHover(token, doc, line, topLevelKey) {
+    return {
+        contents: {
+            kind: MarkupKind.Markdown,
+            value: entryHoverMarkdown(token.name, doc, topLevelKey),
+        },
+        range: {
+            start: { line, character: token.start },
+            end: { line, character: token.end },
+        },
+    };
+}
+/**
+ * Computes the hover for a caret inside a `.sveltex` frontmatter region.
+ *
+ * @param source - Full text of the `.sveltex` document.
+ * @param position - The caret position, in `.sveltex` coordinates. The caller
+ * guarantees it falls inside a `frontmatter` region.
+ * @returns A {@link Hover} describing the frontmatter key — or, on a `name:` /
+ * `http-equiv:` line, the standard `<meta>` value — under the caret, or `null`
+ * when the caret is not on a token recognised in that block.
+ */
+export function computeFrontmatterHover(source, position) {
+    const lines = source.split(/\r\n?|\n/u);
+    const line = lines[position.line];
+    if (line === undefined)
+        return null;
+    const { key, value } = parseFrontmatterLine(line);
+    const caret = position.character;
+    // Caret on the key — describe it, but only if the key is valid in the
+    // block the caret sits in. `title` inside `meta`, say, is left
+    // undocumented because SvelTeX would not render it as the page title
+    // there. For top-level keys the body is followed by per-effect
+    // sections naming each frontmatter-processing step the key takes part
+    // in and the `frontmatter: { … }` toggle that switches it off.
+    if (key && caretOn(caret, key)) {
+        const context = frontmatterContext(lines, position.line);
+        const doc = keysForContext(context)[key.name];
+        if (doc === undefined)
+            return null;
+        const topLevelKey = context === undefined ? key.name : undefined;
+        return entryHover(key, doc, position.line, topLevelKey);
+    }
+    // Caret on the value of a `name:` / `http-equiv:` entry — describe the
+    // standard metadata name or pragma directive it selects.
+    if (key && value && caretOn(caret, value)) {
+        const schema = key.name === 'name'
+            ? META_NAMES
+            : key.name === 'http-equiv'
+                ? META_HTTP_EQUIV
+                : undefined;
+        const doc = schema?.[value.name];
+        if (doc)
+            return entryHover(value, doc, position.line);
+    }
+    return null;
+}
+/**
+ * Classifies a caret on a frontmatter line as completing a key or a value.
+ *
+ * The caret is in value position once it is past the `:` / `=` separator of a
+ * `key:` / `key =` pair; everywhere else a key is being typed.
+ *
+ * @param line - The frontmatter line the caret is on.
+ * @param caret - The caret's character offset within the line.
+ */
+function completionContext(line, caret) {
+    const pair = /^(\s*(?:-\s+)?)(['"]?)([A-Za-z_][\w-]*)\2(\s*)([:=])/u.exec(line);
+    if (pair) {
+        const [match = '', , , key = ''] = pair;
+        if (caret > match.length - 1)
+            return { kind: 'value', ofKey: key };
+    }
+    return { kind: 'key' };
+}
+/**
+ * Computes the completion list for a caret inside a `.sveltex` frontmatter
+ * region: the keys valid in the enclosing block when a key is being typed, or
+ * the standard `<meta>` `name` / `http-equiv` values when the caret is on the
+ * value of such an entry.
+ *
+ * @param source - Full text of the `.sveltex` document.
+ * @param position - The caret position, in `.sveltex` coordinates. The caller
+ * guarantees it falls inside a `frontmatter` region.
+ * @returns A {@link CompletionList} — empty (but never `null`) when nothing
+ * sensible can be suggested.
+ */
+export function computeFrontmatterCompletion(source, position) {
+    const empty = { isIncomplete: false, items: [] };
+    const lines = source.split(/\r\n?|\n/u);
+    const line = lines[position.line];
+    if (line === undefined)
+        return empty;
+    const context = completionContext(line, position.character);
+    let entries;
+    let kind;
+    if (context.kind === 'key') {
+        // Offer only the keys valid in the block the caret sits in — so e.g.
+        // `title` is not suggested inside a `meta` block.
+        entries = keysForContext(frontmatterContext(lines, position.line));
+        kind = CompletionItemKind.Property;
+    }
+    else if (context.ofKey === 'name') {
+        entries = META_NAMES;
+        kind = CompletionItemKind.EnumMember;
+    }
+    else if (context.ofKey === 'http-equiv') {
+        entries = META_HTTP_EQUIV;
+        kind = CompletionItemKind.EnumMember;
+    }
+    else {
+        // The value of any other key is free-form — nothing to suggest.
+        return empty;
+    }
+    // The inserted text replaces the partial identifier already typed.
+    const typed = /[A-Za-z0-9_-]*$/u.exec(line.slice(0, position.character));
+    const range = {
+        start: {
+            line: position.line,
+            character: position.character - (typed?.[0] ?? '').length,
+        },
+        end: { line: position.line, character: position.character },
+    };
+    const items = Object.entries(entries).map(([name, doc]) => {
+        const item = {
+            label: name,
+            kind,
+            documentation: {
+                kind: MarkupKind.Markdown,
+                value: doc.summary,
+            },
+            textEdit: { range, newText: name },
+        };
+        if (doc.element)
+            item.detail = doc.element;
+        return item;
+    });
+    return { isIncomplete: false, items };
+}

package/dist/core/lsp-proxy.d.ts

@@ -0,0 +1,77 @@
+import { type InitializeParams, type InitializeResult } from 'vscode-languageserver-protocol';
+/**
+ * How a child language server is launched.
+ *
+ * - `fork`: run a Node module (`module`) with `child_process.fork` and a
+ *   `--stdio` argument — used for the bundled math language server.
+ * - `spawn`: run a native executable (`command`) with `child_process.spawn` —
+ *   used for the TexLab binary.
+ */
+export type LspSpawnSpec = {
+    kind: 'fork';
+    module: string;
+    args?: readonly string[];
+} | {
+    kind: 'spawn';
+    command: string;
+    args?: readonly string[];
+};
+/**
+ * Handlers for messages a child sends back unprompted (diagnostics, log
+ * messages, server-to-client requests). Both are optional: a proxy whose child
+ * never pushes notifications needs neither.
+ */
+export interface LspProxyHandlers {
+    /** Invoked for every notification the child sends. */
+    onNotification?: (method: string, params: unknown) => void;
+    /** Invoked for every server-to-client request the child sends. */
+    onRequest?: (method: string, params: unknown) => Promise<unknown>;
+}
+/**
+ * A live connection to a child language server.
+ *
+ * Lifecycle: {@link LspProxy.start} launches the child and performs the LSP
+ * `initialize` handshake; {@link LspProxy.sendRequest} /
+ * {@link LspProxy.sendNotification} forward messages; {@link LspProxy.stop}
+ * shuts it down gracefully.
+ */
+export declare class LspProxy {
+    #private;
+    /**
+     * @param spec - How to launch the child language server.
+     * @param label - A short name for the server, used to tag its stderr.
+     * @param handlers - Optional handlers for child-originated traffic.
+     */
+    constructor(spec: LspSpawnSpec, label: string, handlers?: LspProxyHandlers);
+    /** The `InitializeResult` the child returned (available after `start`). */
+    get initializeResult(): InitializeResult | undefined;
+    /** Whether the child process is running and initialized. */
+    get isRunning(): boolean;
+    /**
+     * Launches the child language server and completes the `initialize`
+     * handshake.
+     *
+     * @param initializeParams - The `initialize` params to send the child.
+     * @returns The child's `InitializeResult`.
+     * @throws If the child cannot be spawned or its stdio is unavailable.
+     */
+    start(initializeParams: InitializeParams): Promise<InitializeResult>;
+    /**
+     * Forwards a request to the child and resolves with its response.
+     *
+     * @throws If the proxy is not running.
+     */
+    sendRequest<R = unknown>(method: string, params: unknown): Promise<R>;
+    /**
+     * Forwards a notification to the child.
+     *
+     * No-op if the proxy is not running — notifications are fire-and-forget and
+     * a not-yet-started child must not crash the host.
+     */
+    sendNotification(method: string, params: unknown): Promise<void>;
+    /**
+     * Gracefully shuts the child down: LSP `shutdown` + `exit`, then disposes
+     * the connection and kills the process if it has not exited.
+     */
+    stop(): Promise<void>;
+}

package/dist/core/lsp-proxy.js

@@ -0,0 +1,165 @@
+// File description: `LspProxy` — a generic JSON-RPC client to a child language
+// server, spawned over stdio.
+//
+// `svelte-proxy.ts` already proxies the embedded `svelte-language-server`, but
+// it is specific to that one server (it resolves its `bin/server.js`). The math
+// language server (`@nvl/sveltex-math-language-server`) and TexLab need the same
+// "spawn a child, speak LSP over stdio" treatment, so this module factors that
+// out behind a small, server-agnostic API.
+//
+// Two flavours of child are supported:
+//
+//   - a Node module run with `child_process.fork` (`--stdio`), for the bundled
+//     math language server, and
+//   - a native executable run with `child_process.spawn`, for the TexLab
+//     binary found on `PATH`.
+//
+// Both end up as a `ChildProcessWithoutNullStreams`-like object exposing
+// `stdin`/`stdout`/`stderr`; the proxy speaks LSP over those pipes.
+import { fork, spawn } from 'node:child_process';
+// `vscode-languageserver-protocol`'s `./node` subpath alias is not resolvable
+// under `Node16` resolution (the package predates the npm `exports` field), so
+// the Node entry point is imported via its concrete file path — the same
+// approach `svelte-proxy.ts` uses.
+import { StreamMessageReader, StreamMessageWriter, createProtocolConnection, } from 'vscode-languageserver-protocol/lib/node/main.js';
+import { ExitNotification, InitializedNotification, InitializeRequest, ShutdownRequest, } from 'vscode-languageserver-protocol';
+/**
+ * A live connection to a child language server.
+ *
+ * Lifecycle: {@link LspProxy.start} launches the child and performs the LSP
+ * `initialize` handshake; {@link LspProxy.sendRequest} /
+ * {@link LspProxy.sendNotification} forward messages; {@link LspProxy.stop}
+ * shuts it down gracefully.
+ */
+export class LspProxy {
+    #child;
+    #connection;
+    #initializeResult;
+    #spec;
+    #handlers;
+    /** A short label used to prefix the child's stderr in host logs. */
+    #label;
+    /**
+     * @param spec - How to launch the child language server.
+     * @param label - A short name for the server, used to tag its stderr.
+     * @param handlers - Optional handlers for child-originated traffic.
+     */
+    constructor(spec, label, handlers = {}) {
+        this.#spec = spec;
+        this.#label = label;
+        this.#handlers = handlers;
+    }
+    /** The `InitializeResult` the child returned (available after `start`). */
+    get initializeResult() {
+        return this.#initializeResult;
+    }
+    /** Whether the child process is running and initialized. */
+    get isRunning() {
+        return this.#connection !== undefined;
+    }
+    /**
+     * Launches the child language server and completes the `initialize`
+     * handshake.
+     *
+     * @param initializeParams - The `initialize` params to send the child.
+     * @returns The child's `InitializeResult`.
+     * @throws If the child cannot be spawned or its stdio is unavailable.
+     */
+    async start(initializeParams) {
+        const child = this.#spawnChild();
+        this.#child = child;
+        if (!child.stdout || !child.stdin) {
+            throw new Error(`Failed to obtain stdio streams for ${this.#label} child process.`);
+        }
+        // Surface the child's stderr for debugging without crashing the host.
+        child.stderr?.on('data', (chunk) => {
+            process.stderr.write(`[${this.#label}] ${chunk.toString()}`);
+        });
+        const connection = createProtocolConnection(new StreamMessageReader(child.stdout), new StreamMessageWriter(child.stdin));
+        this.#connection = connection;
+        // Route child-originated traffic to the host's handlers. The catch-all
+        // `onNotification`/`onRequest` overloads live on `MessageConnection`
+        // but are not surfaced by the narrower `ProtocolConnection` type; the
+        // runtime object is a `MessageConnection`, so this view is sound.
+        const starConnection = connection;
+        const onChildNotification = (method, params) => {
+            this.#handlers.onNotification?.(method, params);
+        };
+        const onChildRequest = async (method, params) => {
+            if (this.#handlers.onRequest) {
+                return this.#handlers.onRequest(method, params);
+            }
+            return null;
+        };
+        starConnection.onNotification(onChildNotification);
+        starConnection.onRequest(onChildRequest);
+        connection.onClose(() => {
+            this.#connection = undefined;
+        });
+        connection.onError(() => {
+            // Errors are logged by the reader; nothing actionable here.
+        });
+        connection.listen();
+        const result = await connection.sendRequest(InitializeRequest.type, initializeParams);
+        this.#initializeResult = result;
+        await connection.sendNotification(InitializedNotification.type, {});
+        return result;
+    }
+    /** Spawns the child process per {@link LspSpawnSpec}. */
+    #spawnChild() {
+        if (this.#spec.kind === 'fork') {
+            return fork(this.#spec.module, [...(this.#spec.args ?? [])], {
+                stdio: ['pipe', 'pipe', 'pipe', 'ipc'],
+                execArgv: [],
+            });
+        }
+        return spawn(this.#spec.command, [...(this.#spec.args ?? [])], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    /**
+     * Forwards a request to the child and resolves with its response.
+     *
+     * @throws If the proxy is not running.
+     */
+    async sendRequest(method, params) {
+        if (!this.#connection) {
+            throw new Error(`${this.#label} proxy is not running.`);
+        }
+        return this.#connection.sendRequest(method, params);
+    }
+    /**
+     * Forwards a notification to the child.
+     *
+     * No-op if the proxy is not running — notifications are fire-and-forget and
+     * a not-yet-started child must not crash the host.
+     */
+    async sendNotification(method, params) {
+        if (!this.#connection)
+            return;
+        await this.#connection.sendNotification(method, params);
+    }
+    /**
+     * Gracefully shuts the child down: LSP `shutdown` + `exit`, then disposes
+     * the connection and kills the process if it has not exited.
+     */
+    async stop() {
+        const connection = this.#connection;
+        const child = this.#child;
+        this.#connection = undefined;
+        this.#child = undefined;
+        if (connection) {
+            try {
+                await connection.sendRequest(ShutdownRequest.method);
+                await connection.sendNotification(ExitNotification.method);
+            }
+            catch {
+                // The child may already be gone; fall through to kill it.
+            }
+            connection.dispose();
+        }
+        if (child && child.exitCode === null) {
+            child.kill();
+        }
+    }
+}

package/dist/core/mapper.d.ts

@@ -0,0 +1,86 @@
+import { type Position, type Range } from 'vscode-languageserver-textdocument';
+import type { Mapping, MappingFeatures } from './mapping.js';
+/** A which-way-round selector for {@link SourceMap}'s feature queries. */
+export type MapDirection = 'toGenerated' | 'toSource';
+/**
+ * Bidirectional mapper between a source document and its generated counterpart.
+ *
+ * Construct one per open `.sveltex` file (rebuilt on every debounced re-parse).
+ * The mappings must be sorted by `sourceOffset`; {@link SourceMap.create}
+ * enforces this so callers need not.
+ */
+export declare class SourceMap {
+    #private;
+    private constructor();
+    /**
+     * Builds a {@link SourceMap}.
+     *
+     * @param mappings - The span pairs linking the two documents. Order does
+     * not matter; they are sorted internally.
+     * @param sourceText - Full text of the source `.sveltex` document.
+     * @param generatedText - Full text of the generated `.svelte` document.
+     */
+    static create(mappings: Mapping[], sourceText: string, generatedText: string): SourceMap;
+    /** The generated virtual document's full text. */
+    get generatedText(): string;
+    /** The source document's full text. */
+    get sourceText(): string;
+    /**
+     * Translates a source-document offset to a generated-document offset.
+     *
+     * @param sourceOffset - Offset in the `.sveltex` document.
+     * @returns The corresponding generated offset, or `undefined` if the offset
+     * falls outside every mapped span (i.e. inside a non-delegated region).
+     */
+    sourceOffsetToGenerated(sourceOffset: number): number | undefined;
+    /**
+     * Translates a generated-document offset to a source-document offset.
+     *
+     * @param generatedOffset - Offset in the virtual `.svelte` document.
+     * @returns The corresponding source offset, or `undefined` if the offset
+     * falls outside every mapped span.
+     */
+    generatedOffsetToSource(generatedOffset: number): number | undefined;
+    /**
+     * Translates a source-document {@link Position} to a generated-document
+     * position.
+     *
+     * @returns The mapped position, or `undefined` if it lies in an unmapped
+     * region.
+     */
+    sourcePositionToGenerated(position: Position): Position | undefined;
+    /**
+     * Translates a generated-document {@link Position} to a source-document
+     * position.
+     *
+     * @returns The mapped position, or `undefined` if it lies in an unmapped
+     * region.
+     */
+    generatedPositionToSource(position: Position): Position | undefined;
+    /**
+     * Translates a source-document {@link Range} to a generated-document range.
+     *
+     * @returns The mapped range, or `undefined` if either endpoint is unmapped.
+     *
+     * @remarks
+     * A range is only translated when _both_ endpoints land in mapped spans.
+     * This is the conservative choice: a half-mapped range would produce a
+     * nonsensical generated range and confuse the embedded server.
+     */
+    sourceRangeToGenerated(range: Range): Range | undefined;
+    /**
+     * Translates a generated-document {@link Range} to a source-document range.
+     *
+     * @returns The mapped range, or `undefined` if either endpoint is unmapped.
+     */
+    generatedRangeToSource(range: Range): Range | undefined;
+    /**
+     * Returns the {@link MappingFeatures} governing a given offset.
+     *
+     * @param offset - The offset to query.
+     * @param direction - `'toGenerated'` to interpret `offset` as a source
+     * offset, `'toSource'` to interpret it as a generated offset.
+     * @returns The feature flags, or `undefined` if the offset is unmapped.
+     */
+    featuresAt(offset: number, direction: MapDirection): MappingFeatures | undefined;
+}