@valbuild/language-server 0.98.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2025 Fredrik Ekholdt and Blank AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+"use strict";
+require(".").main();

package/dist/declarations/src/EditorFsHost.d.ts

@@ -0,0 +1,30 @@
+import type { IValFSHost } from "@valbuild/server";
+/**
+ * Access to the editor's in-memory view of a file.
+ *
+ * An editor holds unsaved ("dirty") buffers that differ from disk. Validation
+ * must see what the user is looking at, not what was last saved, so every read
+ * goes through this first.
+ */
+export type OpenDocuments = {
+    /**
+     * Latest editor content for an absolute filesystem path, or `undefined` if the
+     * file is not open in the editor.
+     */
+    read(fsPath: string): string | undefined;
+};
+/** An {@link OpenDocuments} backed by a plain map. Useful for tests. */
+export declare function mapOpenDocuments(entries?: Map<string, string>): OpenDocuments & {
+    set(fsPath: string, content: string): void;
+};
+/**
+ * An `IValFSHost` that overlays the editor's unsaved buffers on top of the real
+ * filesystem.
+ *
+ * `IValFSHost` is the filesystem seam that `createService`, `loadValModules`
+ * and `ValSourceFileHandler` all read through, so overriding it here is what
+ * makes Val evaluate the user's *current* editor state. Everything else
+ * delegates to `ts.sys`, exactly like the default host in
+ * `@valbuild/server`'s `createService`.
+ */
+export declare function createEditorFsHost(open: OpenDocuments): IValFSHost;

package/dist/declarations/src/ValProject.d.ts

@@ -0,0 +1,76 @@
+import type { ModuleFilePath } from "@valbuild/core";
+import type { SchemaSourceSnapshot } from "@valbuild/shared/internal";
+import { type Service } from "@valbuild/server";
+import { type OpenDocuments } from "./EditorFsHost.js";
+/**
+ * A single Val root, and everything needed to evaluate its modules.
+ *
+ * One of these per Val root — never one shared across roots. Different roots in
+ * a monorepo can pin different versions of Val, and each gets its own
+ * `Service` (and therefore its own evaluated `val.modules` and module cache).
+ */
+/** What `Service.get` returns; re-declared to avoid depending on an internal type. */
+export type ValModuleContent = Awaited<ReturnType<Service["get"]>>;
+export type ValProjectInitError = {
+    /**
+     * - `no-config`    — no tsconfig.json/jsconfig.json at the Val root.
+     * - `missing-core` — `@valbuild/core` is not resolvable from the Val root.
+     * - `service-failed` — anything else that stopped the service starting.
+     */
+    code: "no-config" | "missing-core" | "service-failed";
+    message: string;
+};
+export type ValProject = {
+    readonly valRoot: string;
+    /**
+     * Evaluate a module and return its schema, source and validation errors.
+     * Resolves to an init error instead of throwing if the project could not be
+     * set up at all.
+     */
+    getModule(moduleFilePath: ModuleFilePath, options?: {
+        validate: boolean;
+    }): Promise<{
+        status: "ok";
+        content: ValModuleContent;
+        cached: boolean;
+    } | {
+        status: "error";
+        error: ValProjectInitError;
+    }>;
+    /**
+     * Schemas and sources for every Val module in the project.
+     *
+     * Needed for anything that has to look across modules: resolving `keyOf` and
+     * `route` validation, and offering route/key completions. Built once and then
+     * updated per module, so an edit costs one re-evaluation rather than N.
+     */
+    getSnapshot(): Promise<{
+        status: "ok";
+        snapshot: SchemaSourceSnapshot;
+    } | {
+        status: "error";
+        error: ValProjectInitError;
+    }>;
+    /** Val module file paths found under the Val root. */
+    listModuleFilePaths(): ModuleFilePath[];
+    /** Drop cached results. Pass a path to invalidate one module. */
+    invalidate(moduleFilePath?: ModuleFilePath): void;
+    /** Number of cached module results — for tests and diagnostics. */
+    cacheSize(): number;
+    dispose(): Promise<void>;
+};
+/**
+ * Whether `@valbuild/core` is resolvable from a Val root.
+ *
+ * Injectable because jest's module registry intercepts `createRequire` and
+ * resolves against the repo regardless of the base path given, so the real
+ * implementation always reports success under test.
+ */
+export type CoreResolver = (valRoot: string) => boolean;
+export declare const defaultCoreResolver: CoreResolver;
+export declare function createValProject({ valRoot, open, isCoreResolvable, }: {
+    valRoot: string;
+    open: OpenDocuments;
+    /** Override for tests; see {@link CoreResolver}. */
+    isCoreResolvable?: CoreResolver;
+}): ValProject;

package/dist/declarations/src/codeActions.d.ts

@@ -0,0 +1,26 @@
+import { type ValidationFix } from "@valbuild/core";
+import { CodeAction, type Diagnostic, type TextEdit } from "vscode-languageserver";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import type { ValModuleContent } from "./ValProject.js";
+export declare function isLocalFix(fix: string): fix is ValidationFix;
+/**
+ * Build quick fixes for the diagnostics the client sent back.
+ *
+ * The client returns our `Diagnostic.data` verbatim, which is where the source
+ * path and available fixes come from — no re-deriving them from a code string.
+ */
+export declare function createValCodeActions({ document, diagnostics, content, valRoot, remoteHost, }: {
+    document: TextDocument;
+    diagnostics: Diagnostic[];
+    content: ValModuleContent;
+    valRoot: string;
+    remoteHost?: string;
+}): Promise<CodeAction[]>;
+/**
+ * Narrow an edit down to the region that actually changed.
+ *
+ * A whole-document replacement would work, but it moves the cursor and shows up
+ * as a full-file change in review. Trimming the common prefix and suffix keeps
+ * the edit tight without needing a real diff algorithm.
+ */
+export declare function minimalTextEdit(before: string, after: string, document: TextDocument): TextEdit | undefined;

package/dist/declarations/src/completionContext.d.ts

@@ -0,0 +1,77 @@
+import ts from "typescript";
+/**
+ * Works out what the cursor is sitting in, so completions can be offered for it.
+ *
+ * AST-based rather than text/regex-based: `c.image(` can be nested, wrapped or
+ * multi-line, and matching on text gets that wrong in exactly the cases where a
+ * user most wants help.
+ */
+export type ValCompletionContext = ValFileRefContext | ValStringValueContext;
+/** The cursor is inside a plain string in the module's content. */
+export type ValStringValueContext = {
+    kind: "string-value";
+    currentText: string;
+    contentStart: number;
+    contentEnd: number;
+    /**
+     * True when the string is an object key rather than a value.
+     *
+     * The distinction decides which schema to consult: a value is described by the
+     * schema at its own path, whereas a key is described by its *container* — a
+     * gallery record, for instance, is keyed by file reference.
+     */
+    isPropertyName: boolean;
+    /**
+     * Name of the property this string is the value of, when it is one.
+     *
+     * Used for structures Val treats as opaque: a richtext link node is a plain
+     * object with `href`, so there is no schema at that path to consult.
+     */
+    valueOfProperty?: string;
+};
+export type ValFileRefContext = {
+    kind: "file-ref";
+    /** Which constructor: `c.image(...)` or `c.file(...)`. */
+    subType: "image" | "file";
+    /** The string literal being edited, without quotes. */
+    currentText: string;
+    /** Offsets of the string literal's contents, excluding the quotes. */
+    contentStart: number;
+    contentEnd: number;
+    /**
+     * Start offset of the reference argument, including its opening quote.
+     *
+     * Stable while the user types to filter the completion list, because every
+     * such keystroke lands *inside* the literal. That makes it the anchor
+     * {@link findFileRefArgument} re-locates the call by at resolve time.
+     */
+    refArgStart: number;
+    /** End offset of the reference argument, where a metadata argument follows. */
+    refArgEnd: number;
+    /** Offsets of an existing metadata argument, when there is one. */
+    metadataStart?: number;
+    metadataEnd?: number;
+};
+/**
+ * Find the innermost `c.image(...)` / `c.file(...)` call whose first argument
+ * contains `offset`.
+ */
+export declare function getValCompletionContext(sourceFile: ts.SourceFile, offset: number): ValCompletionContext | undefined;
+/**
+ * Re-find the `c.image(...)` / `c.file(...)` call whose reference argument starts
+ * at `refArgStart`, and report where its arguments are *now*.
+ *
+ * `completionItem/resolve` runs against a document the user may have typed into
+ * since the list was computed, so the offsets captured back then have moved.
+ * Applying them anyway inserts the metadata object into the middle of the string
+ * literal and corrupts the file, so the offsets are re-derived here instead.
+ *
+ * Returns `undefined` when no such call is found — the document changed in some
+ * way this anchor does not survive, and the caller must then offer no edit
+ * rather than a wrong one.
+ */
+export declare function findFileRefArgument(sourceFile: ts.SourceFile, refArgStart: number): {
+    refArgEnd: number;
+    metadataStart?: number;
+    metadataEnd?: number;
+} | undefined;

package/dist/declarations/src/completions.d.ts

@@ -0,0 +1,50 @@
+import { type SchemaSourceSnapshot } from "@valbuild/shared/internal";
+import { CompletionItem } from "vscode-languageserver";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import type { PublicValFiles } from "./publicValFiles.js";
+/**
+ * Completions for file and image references.
+ *
+ * Offers the files that actually exist under the project's files directory, and
+ * — when the item is accepted — fills in the metadata argument by reading the
+ * chosen file. Getting width/height/mimeType right by hand is tedious and a
+ * frequent source of the very validation errors this server reports.
+ */
+/** Stashed on the item so `resolve` can do the expensive work lazily. */
+export type ValCompletionItemData = {
+    kind: "file-ref";
+    uri: string;
+    /** Val-style ref of the chosen file. */
+    ref: string;
+    /** Absolute path of the chosen file. */
+    filePath: string;
+    subType: "image" | "file";
+    /** Where a metadata argument goes, or what it replaces. */
+    /**
+     * Start offset of the reference argument, used to re-find the call at resolve
+     * time. Offsets captured now cannot be replayed later: see
+     * {@link findFileRefArgument}.
+     */
+    refArgStart: number;
+};
+export declare function createValCompletions({ document, offset, files, moduleFilePath, snapshot, }: {
+    document: TextDocument;
+    offset: number;
+    files: PublicValFiles;
+    /** This module's path, needed to look its schema up in the snapshot. */
+    moduleFilePath?: string;
+    /** Project-wide schemas and sources, for schema-driven completions. */
+    snapshot?: SchemaSourceSnapshot;
+}): CompletionItem[];
+/**
+ * Fill in the metadata argument for an accepted file reference.
+ *
+ * Done at resolve time because it reads the file from disk, and an editor
+ * requests completions far more often than it accepts one.
+ */
+export declare function resolveValCompletion({ item, documents, }: {
+    item: CompletionItem;
+    documents: {
+        get(uri: string): TextDocument | undefined;
+    };
+}): Promise<CompletionItem>;

package/dist/declarations/src/diagnostics.d.ts

@@ -0,0 +1,105 @@
+import { type ModuleFilePath, type ValidationFix } from "@valbuild/core";
+import { type SchemaSourceSnapshot } from "@valbuild/shared/internal";
+import { Diagnostic, DiagnosticSeverity } from "vscode-languageserver";
+import type { ValModuleContent } from "./ValProject.js";
+/** Marks diagnostics as ours, so a client can filter on it. */
+export declare const VAL_DIAGNOSTIC_SOURCE = "val";
+/**
+ * Every diagnostic this server can produce.
+ *
+ * One naming convention, deliberately: `val/` followed by kebab-case. The
+ * VS Code extension this replaces had accumulated three conventions at once
+ * (`file-not-found`, `val:missing-module`, `image:add-to-gallery`), which made
+ * codes impossible to match on reliably.
+ *
+ * These are *diagnostic* codes and are distinct from *fix* names, which come
+ * from `ValidationFix` in `@valbuild/core` and keep Val's own `image:`/`file:`
+ * vocabulary. A diagnostic says what is wrong; a fix says what can be done
+ * about it, and travels in {@link ValDiagnosticData.fixes}.
+ */
+export declare const VAL_DIAGNOSTIC_CODES: readonly ["val/validation", "val/schema", "val/fatal", "val/file-not-found", "val/missing-module"];
+export type ValDiagnosticCode = (typeof VAL_DIAGNOSTIC_CODES)[number];
+/**
+ * Structured payload attached to every Val diagnostic.
+ *
+ * Carried in `Diagnostic.data` (LSP 3.16), which is round-tripped back to the
+ * server on `textDocument/codeAction`. This replaces encoding information into
+ * the diagnostic's `code` string and parsing it out again — that approach could
+ * not carry anything but strings and broke whenever the format shifted.
+ */
+export type ValDiagnosticData = {
+    code: ValDiagnosticCode;
+    /** Full source path the problem was reported at. */
+    sourcePath: string;
+    /**
+     * Fixes Val says are available, from `ValidationFix` in `@valbuild/core` —
+     * so this always reflects the installed Val rather than a list copied into a
+     * client, which is how the previous list drifted to 13 of 18 fixes.
+     */
+    fixes?: ValidationFix[];
+    /** Fix-specific payload, for example the offending value or route. */
+    value?: unknown;
+    /** Absolute path of the missing file, for `val/file-not-found`. */
+    filePath?: string;
+};
+/**
+ * Severity policy, in one place.
+ *
+ * - **Warning** — Val can fix it automatically. Mirrors the CLI, which prints
+ *   these with `⚠` (its `validation-fixable-error` event) rather than `✘`. In an
+ *   editor a one-click-fixable metadata mismatch should not shout as loudly as a
+ *   type error.
+ * - **Error** — everything else: the content is wrong, the schema is wrong, or
+ *   the module does not work at all.
+ *
+ * Note that `val validate` still exits non-zero for fixable errors, so Warning
+ * here is about presentation, not about the problem being optional.
+ */
+export declare function severityFor({ code, fixes, }: {
+    code: ValDiagnosticCode;
+    fixes?: ValidationFix[];
+}): DiagnosticSeverity;
+export declare function createValDiagnostics({ moduleFilePath, content, text, valRoot, snapshot, }: {
+    moduleFilePath: ModuleFilePath;
+    content: ValModuleContent;
+    /** Current text of the module, as the editor sees it. */
+    text: string;
+    /**
+     * Val root, used to resolve file references. When omitted, file existence is
+     * not checked.
+     */
+    valRoot?: string;
+    /**
+     * Project-wide schemas and sources.
+     *
+     * `keyOf` and `route` validation cannot be completed by core alone — it has to
+     * look at other modules — so core emits a placeholder error carrying the fix
+     * name and a developer-facing message. Given a snapshot, those are resolved
+     * here: valid references drop out, invalid ones become real messages. Without
+     * one they are suppressed, since showing the placeholder would put
+     * unactionable noise on correct code.
+     */
+    snapshot?: SchemaSourceSnapshot;
+}): Diagnostic[];
+/**
+ * Diagnostic for a project that could not be evaluated at all.
+ *
+ * `createService` evaluates the whole `val.modules` graph, so one module that
+ * throws stops every module from being evaluated — as do a missing tsconfig and
+ * an unresolvable `@valbuild/core`. Reporting it on the file the user is looking
+ * at is imprecise, but the alternative is that all Val diagnostics silently
+ * disappear the moment a project stops evaluating.
+ */
+export declare function createProjectErrorDiagnostic({ moduleFilePath, message, }: {
+    moduleFilePath: ModuleFilePath;
+    message: string;
+}): Diagnostic;
+/**
+ * Diagnostic for a Val module that is not registered in `val.modules`.
+ *
+ * Val only serves modules listed there, so an unregistered module silently does
+ * nothing — worth surfacing even though it is not a validation error.
+ */
+export declare function createMissingModuleDiagnostic({ moduleFilePath, }: {
+    moduleFilePath: ModuleFilePath;
+}): Diagnostic;

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,13 @@
+export { main, createValLanguageServer, type ValSession } from "./server.js";
+export { getLanguageServerVersion } from "./version.js";
+export { createEditorFsHost, mapOpenDocuments, type OpenDocuments, } from "./EditorFsHost.js";
+export { createValProject, defaultCoreResolver, type CoreResolver, type ValProject, type ValProjectInitError, type ValModuleContent, } from "./ValProject.js";
+export { createValDiagnostics, createMissingModuleDiagnostic, createProjectErrorDiagnostic, severityFor, VAL_DIAGNOSTIC_SOURCE, VAL_DIAGNOSTIC_CODES, type ValDiagnosticCode, type ValDiagnosticData, } from "./diagnostics.js";
+export { findRegisteredModuleSpecifiers, isModuleRegistered, } from "./valModulesRegistry.js";
+export { createValCodeActions, isLocalFix, minimalTextEdit, } from "./codeActions.js";
+export { createValCompletions, resolveValCompletion, type ValCompletionItemData, } from "./completions.js";
+export { getValCompletionContext, type ValCompletionContext, type ValFileRefContext, type ValStringValueContext, } from "./completionContext.js";
+export { createPublicValFiles, DEFAULT_FILES_DIRECTORY, type PublicValFile, type PublicValFiles, } from "./publicValFiles.js";
+export { createModulePathMap, findModulePathAtPosition, getModulePathRange, type ModulePathMap, type ModulePathRange, type ModulePosition, } from "./modulePathMap.js";
+export { isValModuleUri, pathToUri, toModuleFilePath, uriToPath } from "./uri.js";
+export { PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, VAL_FEATURES, VAL_PICK_REQUEST, VAL_INPUT_REQUEST, negotiateProtocolVersion, type ProtocolVersionRange, type ProtocolNegotiationResult, type ValClientCapabilities, type ValClientInfo, type ValEnvOverrides, type ValFeature, type ValInitializationOptions, type ValInputParams, type ValInputResult, type ValPickItem, type ValPickParams, type ValPickResult, type ValServerCapabilities, } from "./protocol.js";

package/dist/declarations/src/modulePathMap.d.ts

@@ -0,0 +1,60 @@
+import ts from "typescript";
+import { type ModulePath } from "@valbuild/core";
+/**
+ * Maps Val module paths onto positions in the module's TypeScript source.
+ *
+ * Validation errors come back keyed by `SourcePath` (for example
+ * `/content/page.val.ts?p="hero"."image"`), but an editor needs a line/column
+ * range. This walks the source expression passed to `c.define(...)` and records
+ * where each addressable path lands in the file.
+ *
+ * This is version-sensitive by nature: it encodes how Val's module paths
+ * correspond to source syntax, which is why it lives with Val rather than in an
+ * editor extension.
+ *
+ * NOTE: `@valbuild/server` has a near-identical `modulePathMap.ts`, used for the
+ * CLI's code frames and the Val UI. This copy differs in locating the source
+ * expression via `analyzeValModule` and in exposing
+ * {@link findModulePathAtPosition}. Fix traversal bugs in both, or fold them
+ * together.
+ */
+export type ModulePosition = {
+    line: number;
+    character: number;
+};
+export type ModulePathRange = {
+    start: ModulePosition;
+    end: ModulePosition;
+};
+export type ModulePathMap = {
+    [modulePath: string]: ModulePathRange & {
+        children: ModulePathMap;
+    };
+};
+/**
+ * Look up the source range for a module path.
+ *
+ * Returns `undefined` when the path cannot be resolved — an unparseable path, or
+ * one that does not correspond to any node. That happens legitimately when
+ * schema serialization failed upstream, so callers should treat a missing range
+ * as "report this diagnostic on the module instead" rather than as a bug.
+ */
+export declare function getModulePathRange(modulePath: string, modulePathMap: ModulePathMap): ModulePathRange | undefined;
+/**
+ * Find the module path of the innermost entry whose range contains `position`.
+ *
+ * The inverse of the map's normal use: given where the cursor is, work out which
+ * part of the module it addresses, so the schema there can be looked up. Used by
+ * schema-driven completions.
+ *
+ * Segments are encoded with `Internal.patchPathToModulePath`, so the result is
+ * addressable by the same functions that consume validation error paths.
+ */
+export declare function findModulePathAtPosition(modulePathMap: ModulePathMap, position: ModulePosition): ModulePath | undefined;
+/**
+ * Build a {@link ModulePathMap} for a Val module source file.
+ *
+ * Returns `undefined` when the file is not a recognisable Val module (no
+ * `export default c.define(...)`).
+ */
+export declare function createModulePathMap(sourceFile: ts.SourceFile): ModulePathMap | undefined;

package/dist/declarations/src/protocol.d.ts

@@ -0,0 +1,200 @@
+/**
+ * The Val language server protocol.
+ *
+ * This module is the contract between an editor client (for example the Val
+ * VS Code extension) and the language server that ships with the Val version
+ * installed in the user's project.
+ *
+ * The whole point of this package is that ONE editor client works against MANY
+ * versions of Val. That means:
+ *
+ *  - Clients MUST NOT assume they can import this module. They resolve the
+ *    server from the user's `node_modules` at runtime, and the constants below
+ *    are intentionally small and pure so a client can vendor a copy of them.
+ *    A client may take a type-only devDependency on this package for the types.
+ *  - Anything added here must degrade gracefully. New capabilities are
+ *    announced through `features` / `commands` so that a client which has never
+ *    heard of them simply does not offer them, instead of breaking.
+ *
+ * Deliberately dependency-free: no `vscode-languageserver` import, no Val
+ * imports, no I/O.
+ */
+/**
+ * The current protocol version.
+ *
+ * Bump this ONLY for a breaking change to the client/server contract — a
+ * removed or renamed request, a changed payload shape, or changed semantics
+ * that an older client would misinterpret. Additive changes (a new feature
+ * flag, a new command, a new optional field) do NOT need a bump: they are
+ * negotiated through `features` and `commands`.
+ *
+ * This is a hand-maintained literal on purpose. Deriving it from package.json
+ * (as `Internal.VERSION.core` does) breaks under bundling, and build-time
+ * string substitution (as `@valbuild/ui`'s VERSION does) is easy to get wrong.
+ */
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * The range of protocol versions this server can speak. Kept separate from
+ * {@link PROTOCOL_VERSION} so that a future server can continue to serve older
+ * clients by lowering `min`.
+ */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: ProtocolVersionRange;
+export type ProtocolVersionRange = {
+    min: number;
+    max: number;
+};
+export type ValClientInfo = {
+    /** For example `"vscode-val-build"`. Used for logging and telemetry only. */
+    name: string;
+    version: string | null;
+};
+/**
+ * The only environment variables a client may override. `initializationOptions`
+ * is untyped JSON at runtime, so this list is what the server enforces: without
+ * it a client could set `PATH` or `NODE_OPTIONS` on the server process.
+ */
+export declare const VAL_ENV_OVERRIDE_KEYS: readonly ["VAL_CONTENT_URL", "VAL_REMOTE_HOST", "VAL_BUILD_URL"];
+/**
+ * Environment overrides forwarded from the client. These mirror the
+ * `VAL_*` environment variables so that an editor can point a session at a
+ * non-production Val backend without the user having to restart their editor
+ * with a modified environment.
+ */
+export type ValEnvOverrides = Partial<Record<(typeof VAL_ENV_OVERRIDE_KEYS)[number], string>>;
+/**
+ * Sent by the client as `InitializeParams.initializationOptions`.
+ *
+ * One server instance serves exactly one Val root. A workspace containing
+ * several Val roots (a monorepo) gets one server per root, because different
+ * roots may pin different versions of Val.
+ */
+export type ValInitializationOptions = {
+    client: ValClientInfo;
+    /** Protocol versions the client can speak. */
+    supportedProtocolVersions: ProtocolVersionRange;
+    /** Absolute path to the directory containing this project's `package.json`. */
+    valRoot: string;
+    env?: ValEnvOverrides;
+};
+/**
+ * Optional capabilities a client may implement, announced by the client under
+ * `capabilities.experimental.val`.
+ *
+ * The server uses this to decide whether it can offer flows that need user
+ * interaction. A client that implements neither still gets diagnostics and
+ * completions.
+ */
+export type ValClientCapabilities = {
+    /** Client implements the {@link VAL_PICK_REQUEST} request. */
+    pick?: boolean;
+    /** Client implements the {@link VAL_INPUT_REQUEST} request. */
+    input?: boolean;
+};
+/**
+ * Feature flags announced by the server under
+ * `capabilities.experimental.val.features`.
+ *
+ * A client should treat an unknown string as "something this Val version can do
+ * that I do not know about" and ignore it, and a missing string as "not
+ * available in this Val version" and hide the corresponding UI.
+ */
+export declare const VAL_FEATURES: readonly ["diagnostics", "diagnostics/gallery", "completions/route", "completions/keyOf", "completions/mediaPath", "completions/galleryKey", "completions/richtextLink", "fix/metadata", "fix/upload-remote", "fix/download-remote", "fix/missing-module", "fix/gallery", "login"];
+export type ValFeature = (typeof VAL_FEATURES)[number];
+/**
+ * Announced by the server as
+ * `InitializeResult.capabilities.experimental.val`.
+ */
+export type ValServerCapabilities = {
+    /**
+     * The negotiated protocol version — within the client's range unless
+     * {@link ValServerCapabilities.incompatible} is set, in which case this is
+     * the highest version the server itself can speak.
+     */
+    protocolVersion: number;
+    /**
+     * Present only when version negotiation failed. `features` and `commands`
+     * are then empty; the client should stop the server and tell the user which
+     * side to update. Checking this first is what turns an "incompatible
+     * versions" dead end into an actionable message.
+     */
+    incompatible?: Exclude<ProtocolNegotiationResult, {
+        status: "ok";
+    }>;
+    versions: {
+        /** Version of `@valbuild/core` resolved in the user's project. */
+        core: string | null;
+        /** Version of this package. */
+        languageServer: string | null;
+    };
+    /** Echoed back so the client can label the session (status bar, logs). */
+    valRoot: string;
+    /**
+     * Features this server actually serves. Narrower than {@link VAL_FEATURES}
+     * when a capability could not be initialised for this project.
+     */
+    features: ValFeature[];
+    /** `workspace/executeCommand` names this server offers. */
+    commands: string[];
+};
+/** Ask the user to choose one of a list of options (a "quick pick"). */
+export declare const VAL_PICK_REQUEST = "val/pick";
+export type ValPickItem = {
+    label: string;
+    /** Rendered next to the label. */
+    description?: string;
+    /** Rendered below the label. */
+    detail?: string;
+    /** Opaque to the client; returned verbatim in {@link ValPickResult}. */
+    value: string;
+};
+export type ValPickParams = {
+    title: string;
+    placeholder?: string;
+    items: ValPickItem[];
+};
+/** `null` when the user dismissed the picker. */
+export type ValPickResult = {
+    value: string;
+} | null;
+/** Ask the user to type a value (an "input box"). */
+export declare const VAL_INPUT_REQUEST = "val/input";
+export type ValInputParams = {
+    title: string;
+    prompt?: string;
+    /** Pre-filled value. */
+    value?: string;
+    placeholder?: string;
+    password?: boolean;
+};
+/** `null` when the user dismissed the input box. */
+export type ValInputResult = {
+    value: string;
+} | null;
+export type ProtocolNegotiationResult = {
+    status: "ok";
+    /** Highest version both sides can speak. */
+    protocolVersion: number;
+} | {
+    /**
+     * The server is newer than anything the client understands: the user
+     * should update their editor client.
+     */
+    status: "client-too-old";
+    server: ProtocolVersionRange;
+    client: ProtocolVersionRange;
+} | {
+    /**
+     * The server is older than anything the client understands: the user
+     * should update Val in their project.
+     */
+    status: "server-too-old";
+    server: ProtocolVersionRange;
+    client: ProtocolVersionRange;
+};
+/**
+ * Pick the highest protocol version both sides can speak.
+ *
+ * Returns a *directional* failure so the client can tell the user which side to
+ * update, rather than showing a generic "incompatible versions" error.
+ */
+export declare function negotiateProtocolVersion(client: ProtocolVersionRange, server?: ProtocolVersionRange): ProtocolNegotiationResult;