@valbuild/language-server 0.98.0

package/dist/valbuild-language-server.esm.js

@@ -0,0 +1,2451 @@
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+import { Internal, FILE_REF_PROP, DEFAULT_VAL_REMOTE_HOST } from '@valbuild/core';
+import { createService, analyzeValModule, createFixPatch, patchSourceFile, extractImageMetadata, extractFileMetadata, findAndEvalValConfigFile } from '@valbuild/server';
+import { DiagnosticSeverity, CodeAction, CodeActionKind, CompletionItemKind } from 'vscode-languageserver';
+import { TextDocuments, TextDocumentSyncKind, createConnection, ProposedFeatures } from 'vscode-languageserver/node';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+import crypto from 'crypto';
+import { createRequire } from 'node:module';
+import { resolveSchemaSourceFixes, getRoutesWithModulePaths } from '@valbuild/shared/internal';
+import { result } from '@valbuild/core/fp';
+
+/**
+ * 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.
+ */
+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`.
+ */
+const SUPPORTED_PROTOCOL_VERSIONS = {
+  min: 1,
+  max: PROTOCOL_VERSION
+};
+/**
+ * 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.
+ */
+const VAL_ENV_OVERRIDE_KEYS = ["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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+const VAL_FEATURES = ["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"];
+
+/**
+ * Announced by the server as
+ * `InitializeResult.capabilities.experimental.val`.
+ */
+
+// ---------------------------------------------------------------------------
+// Custom requests: server -> client
+//
+// Standard LSP already covers applying edits (`workspace/applyEdit`), opening a
+// URL in a browser (`window/showDocument` with `external: true`), progress
+// (`$/progress`) and confirmations (`window/showMessageRequest`). The two
+// requests below are the only UI primitives LSP lacks that Val needs.
+//
+// Both are deliberately content-agnostic: they carry no Val types, so they do
+// not change when Val changes.
+// ---------------------------------------------------------------------------
+
+/** Ask the user to choose one of a list of options (a "quick pick"). */
+const VAL_PICK_REQUEST = "val/pick";
+
+/** `null` when the user dismissed the picker. */
+
+/** Ask the user to type a value (an "input box"). */
+const VAL_INPUT_REQUEST = "val/input";
+
+/** `null` when the user dismissed the input box. */
+
+// ---------------------------------------------------------------------------
+// Version negotiation
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+function negotiateProtocolVersion(client, server = SUPPORTED_PROTOCOL_VERSIONS) {
+  const min = Math.max(client.min, server.min);
+  const max = Math.min(client.max, server.max);
+  if (min <= max) {
+    return {
+      status: "ok",
+      protocolVersion: max
+    };
+  }
+  if (server.max < client.min) {
+    return {
+      status: "server-too-old",
+      server,
+      client
+    };
+  }
+  return {
+    status: "client-too-old",
+    server,
+    client
+  };
+}
+
+/**
+ * Version of this package, read from its own package.json.
+ *
+ * Mirrors how `@valbuild/core` reports `Internal.VERSION.core`
+ * (see `packages/core/src/index.ts`): the built output lives one directory
+ * below the package root, so `../package.json` resolves correctly. Returns
+ * `null` rather than throwing if the file cannot be read — the version is only
+ * ever used for display, never for behaviour.
+ */
+function getLanguageServerVersion() {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require("../package.json").version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+
+/** An {@link OpenDocuments} backed by a plain map. Useful for tests. */
+function mapOpenDocuments(entries = new Map()) {
+  const normalized = new Map();
+  for (const [k, v] of entries) {
+    normalized.set(path.normalize(k), v);
+  }
+  return {
+    read: fsPath => normalized.get(path.normalize(fsPath)),
+    set: (fsPath, content) => normalized.set(path.normalize(fsPath), content)
+  };
+}
+
+/**
+ * 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`.
+ */
+function createEditorFsHost(open) {
+  return {
+    ...ts.sys,
+    fileExists(fileName) {
+      // A file open in the editor but not yet written to disk still exists as
+      // far as validation is concerned.
+      if (open.read(fileName) !== undefined) {
+        return true;
+      }
+      return ts.sys.fileExists(fileName);
+    },
+    readFile(fileName, encoding) {
+      const overlay = open.read(fileName);
+      if (overlay !== undefined) {
+        return overlay;
+      }
+      return ts.sys.readFile(fileName, encoding);
+    },
+    readBuffer(fileName) {
+      const overlay = open.read(fileName);
+      if (overlay !== undefined) {
+        return Buffer.from(overlay, "utf8");
+      }
+      try {
+        return fs.readFileSync(fileName);
+      } catch {
+        return undefined;
+      }
+    },
+    /**
+     * Deliberately unimplemented. A language server must never write to the
+     * user's files behind their back — every change goes through the editor as
+     * a `workspace/applyEdit` so it lands in the undo stack and respects dirty
+     * buffers. Throwing here turns an accidental write into a loud failure
+     * rather than silent data loss.
+     */
+    writeFile(fileName) {
+      throw Error(`The Val language server must not write files directly (attempted: '${fileName}'). ` + `Produce a workspace edit instead.`);
+    },
+    rmFile(fileName) {
+      throw Error(`The Val language server must not delete files directly (attempted: '${fileName}'). ` + `Produce a workspace edit instead.`);
+    }
+  };
+}
+
+/**
+ * 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. */
+
+const DEFAULT_OPTIONS = {
+  validate: true
+};
+
+/** Cheap cache key. Not security-sensitive, so sha1 over the source is fine. */
+function fingerprint(content) {
+  return content === undefined ? "<missing>" : crypto.createHash("sha1").update(content).digest("hex");
+}
+
+/**
+ * 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.
+ */
+
+const defaultCoreResolver = valRoot => {
+  try {
+    createRequire(path.join(valRoot, "package.json")).resolve("@valbuild/core/package.json");
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Check up front that `@valbuild/core` resolves from the Val root.
+ *
+ * Val modules import `@valbuild/core`, and so does the `val.modules` file that
+ * the service evaluates. When it is not resolvable, every module fails with a fatal
+ * "Could not resolve module: '@valbuild/core'" — which reads like a Val bug
+ * rather than a missing dependency.
+ *
+ * This is easy to hit: `@valbuild/core` must be a *direct* dependency (which is
+ * what `valbuild-init` enforces), but under pnpm's isolated node_modules a
+ * project that only declares `@valbuild/next` has no resolvable core, whereas
+ * under npm's hoisting the same project works by accident. Detecting it once
+ * here turns N cryptic per-module fatals into one actionable message.
+ */
+function checkCoreIsResolvable(valRoot, isCoreResolvable) {
+  if (isCoreResolvable(valRoot)) {
+    return null;
+  }
+  return {
+    code: "missing-core",
+    message: `Could not resolve '@valbuild/core' from '${valRoot}'. ` + `Val requires @valbuild/core as a direct dependency of your project — ` + `add it with your package manager (for example: npm install @valbuild/core).`
+  };
+}
+
+/**
+ * Find every Val module under the Val root.
+ *
+ * Globs rather than reading `val.modules`, matching what the CLI does: it is a
+ * superset, and it keeps working while `val.modules` is mid-edit or broken.
+ */
+function findValModuleFilePaths(valRoot) {
+  const found = [];
+  function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, {
+        withFileTypes: true
+      });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) {
+        continue;
+      }
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(absolute);
+      } else if (/\.val\.(ts|js|tsx|jsx)$/.test(entry.name)) {
+        found.push(`/${path.relative(valRoot, absolute).split(path.sep).join("/")}`);
+      }
+    }
+  }
+  walk(valRoot);
+  return found.sort();
+}
+function createValProject({
+  valRoot,
+  open,
+  isCoreResolvable = defaultCoreResolver
+}) {
+  const host = createEditorFsHost(open);
+
+  // `createService` calls getCompilerOptions, which THROWS when the Val root has
+  // neither tsconfig.json nor jsconfig.json. Initialise lazily and keep the
+  // failure as a value so a misconfigured project degrades to "no diagnostics"
+  // instead of taking the server down.
+  let servicePromise;
+
+  /**
+   * Forget the current `Service` so the next request builds a new one.
+   *
+   * A `Service` evaluates the whole `val.modules` graph when it is created and
+   * then answers `get` from that evaluation, so it is a snapshot of the project
+   * at one point in time and cannot re-read a single module. Dropping it is what
+   * makes the next request see an edit. `Service.dispose()` is a no-op, so the
+   * only cost is the re-evaluation itself.
+   */
+  function discardService() {
+    servicePromise = undefined;
+  }
+  function startService() {
+    const coreProblem = checkCoreIsResolvable(valRoot, isCoreResolvable);
+    if (coreProblem) {
+      return Promise.resolve({
+        status: "error",
+        error: coreProblem
+      });
+    }
+    return createService(valRoot, host).then(service => ({
+      status: "ok",
+      service
+    })).catch(e => {
+      const message = e instanceof Error ? e.message : String(e);
+      return {
+        status: "error",
+        error: {
+          code: /Could not read config from/.test(message) ? "no-config" : "service-failed",
+          message
+        }
+      };
+    });
+  }
+  function getService() {
+    if (!servicePromise) {
+      const attempt = startService();
+      servicePromise = attempt;
+      // Only a *successful* evaluation is worth keeping. Everything that makes
+      // one fail can be fixed without any Val module's content changing -- add a
+      // tsconfig, install @valbuild/core, fix the module that throws, fix
+      // val.modules -- so memoizing the failure would leave the session
+      // permanently broken. Retrying is cheap: a failing evaluation throws early.
+      void attempt.then(resolved => {
+        if (resolved.status === "error" && servicePromise === attempt) {
+          servicePromise = undefined;
+        }
+      });
+    }
+    return servicePromise;
+  }
+  const cache = new Map();
+
+  // Snapshot entries are kept across edits and refreshed individually: a
+  // keystroke should cost one module evaluation, not one per module.
+  const snapshot = {
+    schemas: {},
+    sources: {}
+  };
+  let snapshotStale;
+
+  // One in-flight snapshot build, shared by concurrent callers.
+  let snapshotPromise;
+  async function buildSnapshot() {
+    // First call: everything is stale. Later calls: only what changed.
+    if (snapshotStale === undefined) {
+      snapshotStale = new Set(findValModuleFilePaths(valRoot));
+    }
+    // Claim the work list *before* the first await, and leave a fresh set
+    // behind. An `invalidate()` that lands while we are evaluating then lands in
+    // that fresh set and is refreshed on the next call, instead of being cleared
+    // as though this call had handled it.
+    const refreshing = [...snapshotStale];
+    snapshotStale = new Set();
+    const resolved = await getService();
+    if (resolved.status === "error") {
+      // Nothing was refreshed, so put the work back — unless a full invalidation
+      // landed meanwhile, which re-lists everything anyway.
+      if (snapshotStale !== undefined) {
+        for (const moduleFilePath of refreshing) {
+          snapshotStale.add(moduleFilePath);
+        }
+      }
+      return {
+        status: "error",
+        error: resolved.error
+      };
+    }
+    for (const moduleFilePath of refreshing) {
+      const content = await resolved.service.get(moduleFilePath, "",
+      // Validation is not needed to answer "what keys/routes exist", and
+      // skipping it keeps the snapshot cheap.
+      {
+        validate: false
+      });
+      if (content.schema) {
+        snapshot.schemas[moduleFilePath] = content.schema;
+      } else {
+        delete snapshot.schemas[moduleFilePath];
+      }
+      if (content.source !== undefined) {
+        // Same conversion the CLI does when building its snapshot; Source is
+        // JSON-shaped once serialized.
+        snapshot.sources[moduleFilePath] = content.source;
+      } else {
+        delete snapshot.sources[moduleFilePath];
+      }
+    }
+    return {
+      status: "ok",
+      snapshot
+    };
+  }
+  return {
+    valRoot,
+    async getModule(moduleFilePath, options = DEFAULT_OPTIONS) {
+      // Cache on the module's own content as seen by the editor. This covers the
+      // common case -- repeated requests while the user edits one file -- but
+      // NOT edits to a module's imports; `invalidate()` is how the server
+      // handles that.
+      const absolute = path.join(valRoot, moduleFilePath);
+      const current = fingerprint(host.readFile(absolute));
+      const optionsKey = `${+options.validate}`;
+      const hit = cache.get(moduleFilePath);
+      if (hit) {
+        if (hit.fingerprint === current && hit.optionsKey === optionsKey) {
+          return {
+            status: "ok",
+            content: hit.content,
+            cached: true
+          };
+        }
+        if (hit.fingerprint !== current) {
+          // The content we last evaluated at is gone, so the Service's
+          // whole-project evaluation is stale as well. Callers do not have to
+          // call `invalidate()` first for this to be correct.
+          discardService();
+        }
+      }
+      const resolved = await getService();
+      if (resolved.status === "error") {
+        return {
+          status: "error",
+          error: resolved.error
+        };
+      }
+      const content = await resolved.service.get(moduleFilePath, "", options);
+      cache.set(moduleFilePath, {
+        fingerprint: current,
+        optionsKey,
+        content
+      });
+      return {
+        status: "ok",
+        content,
+        cached: false
+      };
+    },
+    listModuleFilePaths: () => findValModuleFilePaths(valRoot),
+    getSnapshot() {
+      // `snapshot` is one shared object handed to every caller, so a second
+      // concurrent build must not be allowed to return it half-filled: the
+      // in-flight build is shared instead. Without this, two callers see 1 and 6
+      // schemas respectively, and a partial snapshot makes keyOf/route resolution
+      // report references that are perfectly valid as broken.
+      if (!snapshotPromise) {
+        const attempt = buildSnapshot();
+        snapshotPromise = attempt;
+        void attempt.finally(() => {
+          if (snapshotPromise === attempt) {
+            snapshotPromise = undefined;
+          }
+        });
+      }
+      return snapshotPromise;
+    },
+    invalidate(moduleFilePath) {
+      discardService();
+      if (moduleFilePath === undefined) {
+        cache.clear();
+        snapshotStale = undefined;
+        for (const key of Object.keys(snapshot.schemas)) {
+          delete snapshot.schemas[key];
+        }
+        for (const key of Object.keys(snapshot.sources)) {
+          delete snapshot.sources[key];
+        }
+      } else {
+        cache.delete(moduleFilePath);
+        // Refresh just this module in the snapshot next time it is read.
+        if (snapshotStale !== undefined) {
+          snapshotStale.add(moduleFilePath);
+        }
+      }
+    },
+    cacheSize: () => cache.size,
+    async dispose() {
+      if (!servicePromise) {
+        return;
+      }
+      const resolved = await servicePromise;
+      if (resolved.status === "ok") {
+        resolved.service.dispose();
+      }
+      discardService();
+      cache.clear();
+    }
+  };
+}
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+function getModulePathRange(modulePath, modulePathMap) {
+  if (!modulePath || typeof modulePath !== "string") {
+    return undefined;
+  }
+  let segments;
+  try {
+    // Val's own splitter: handles quoted segments and escaped quotes, which a
+    // naive modulePath.split(".").map(JSON.parse) does not.
+    segments = Internal.splitModulePath(modulePath);
+  } catch {
+    return undefined;
+  }
+  if (segments.length === 0) {
+    return undefined;
+  }
+  let entry = modulePathMap[segments[0]];
+  for (const segment of segments.slice(1)) {
+    if (!entry) {
+      break;
+    }
+    entry = entry.children?.[segment];
+  }
+  if (!entry?.start || !entry?.end) {
+    return undefined;
+  }
+  return {
+    start: entry.start,
+    end: entry.end
+  };
+}
+
+/**
+ * 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.
+ */
+function findModulePathAtPosition(modulePathMap, position) {
+  const segments = [];
+  function descend(map) {
+    for (const [segment, entry] of Object.entries(map)) {
+      // `val` is synthetic (it marks where a property's value sits) and `""`
+      // marks a bare literal. Both have no children, and `val` spans the entire
+      // value — so descending into either would match first and stop the walk
+      // before it reached the real nested key. They are skipped as descent
+      // targets, and used only for containment below.
+      if (segment === "val" || segment === "") {
+        continue;
+      }
+      // An entry's own range covers only its key, so also accept a cursor inside
+      // its value; otherwise nothing nested would ever match its parents.
+      const valChild = entry.children?.val;
+      if (!contains(entry, position) && !(valChild && contains(valChild, position))) {
+        continue;
+      }
+      segments.push(segment);
+      descend(entry.children);
+      return true;
+    }
+    return false;
+  }
+  if (!descend(modulePathMap)) {
+    return undefined;
+  }
+  return Internal.patchPathToModulePath(segments);
+}
+function contains(range, position) {
+  const afterStart = position.line > range.start.line || position.line === range.start.line && position.character >= range.start.character;
+  const beforeEnd = position.line < range.end.line || position.line === range.end.line && position.character <= range.end.character;
+  return afterStart && beforeEnd;
+}
+
+/**
+ * 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(...)`).
+ */
+function createModulePathMap(sourceFile) {
+  const source = findSourceExpression(sourceFile);
+  if (!source) {
+    return undefined;
+  }
+  return traverse(source, sourceFile);
+}
+
+/**
+ * Locate the third argument of `c.define(...)` — the module's content.
+ *
+ * Uses Val's own `analyzeValModule`, which validates that the default export
+ * really is a `c.define` call with a string-literal path, rather than blindly
+ * taking `arguments[2]` of whatever the default export happens to call.
+ */
+function findSourceExpression(sourceFile) {
+  let analysis;
+  try {
+    analysis = analyzeValModule(sourceFile);
+  } catch {
+    // analyzeValModule throws when there is no default export at all.
+    return undefined;
+  }
+  if (result.isErr(analysis)) {
+    return undefined;
+  }
+  return analysis.value.source;
+}
+function traverse(node, sourceFile) {
+  if (ts.isStringLiteral(node) || ts.isNumericLiteral(node)) {
+    return {
+      "": {
+        children: {},
+        ...rangeOfNode(node, sourceFile)
+      }
+    };
+  }
+  if (ts.isObjectLiteralExpression(node)) {
+    return traverseObjectLiteral(node, sourceFile);
+  }
+  if (ts.isArrayLiteralExpression(node)) {
+    return traverseArrayLiteral(node, sourceFile);
+  }
+  if (ts.isCallExpression(node)) {
+    return traverseCallExpression(node, sourceFile);
+  }
+}
+
+/**
+ * The line/character range of `node`'s own text (leading trivia excluded).
+ *
+ * NOTE: do not compute the start as `end.character - node.getWidth()`. That
+ * identity only holds while the node stays on a single line - for a multi-line
+ * node (an object inside an array, a `c.image` metadata argument, ...) it
+ * reports the *closing* line and a negative character. `getStart(sourceFile)`
+ * needs no parent pointers as long as the source file is passed explicitly,
+ * which is why it is safe here.
+ */
+function rangeOfNode(node, sourceFile) {
+  return {
+    start: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)),
+    end: sourceFile.getLineAndCharacterOfPosition(node.getEnd())
+  };
+}
+
+/**
+ * `c.image(...)` / `c.file(...)` expose three addressable paths: the call itself
+ * (`val`), the reference argument (`_ref`) and the metadata argument
+ * (`metadata`). Validation errors about a missing file point at `_ref`, and
+ * errors about metadata point at `metadata`, so both need their own range.
+ */
+function traverseCallExpression(node, sourceFile) {
+  if (!ts.isPropertyAccessExpression(node.expression)) {
+    return undefined;
+  }
+  const isValFileConstructor = node.expression.expression.getText(sourceFile) === "c" && (node.expression.name.getText(sourceFile) === "file" || node.expression.name.getText(sourceFile) === "image");
+  if (!isValFileConstructor || !node.arguments[0]) {
+    return undefined;
+  }
+  const val = {
+    children: {},
+    ...rangeOfNode(node, sourceFile)
+  };
+  const _ref = {
+    children: {},
+    ...rangeOfNode(node.arguments[0], sourceFile)
+  };
+  if (!node.arguments[1]) {
+    return {
+      val,
+      _ref
+    };
+  }
+  return {
+    val,
+    _ref,
+    metadata: {
+      children: {},
+      ...rangeOfNode(node.arguments[1], sourceFile)
+    }
+  };
+}
+function traverseArrayLiteral(node, sourceFile) {
+  const map = {};
+  node.elements.forEach((element, index) => {
+    if (!ts.isExpression(element)) {
+      return;
+    }
+    map[index] = {
+      children: traverse(element, sourceFile) ?? {},
+      ...rangeOfNode(element, sourceFile)
+    };
+  });
+  return map;
+}
+function traverseObjectLiteral(node, sourceFile) {
+  const map = {};
+  for (const property of node.properties) {
+    if (!ts.isPropertyAssignment(property)) {
+      continue;
+    }
+    const key = property.name && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) && property.name.text;
+    // NOTE: this also skips `""`, which is what a gallery key looks like the
+    // moment the user opens the quote. That is deliberate, not an oversight: a
+    // module path cannot address an empty segment, because
+    // `Internal.splitModulePath('""')` returns `[]`, and `""` already means
+    // "bare literal" in this map (see findModulePathAtPosition). Supporting it
+    // needs a change in @valbuild/core first.
+    if (!key) {
+      continue;
+    }
+    map[key] = {
+      children: {
+        // `val` addresses the property's value, whereas the key's own range is
+        // what a diagnostic about the field itself should highlight.
+        val: {
+          children: {},
+          ...rangeOfNode(property.initializer, sourceFile)
+        },
+        ...traverse(property.initializer, sourceFile)
+      },
+      ...rangeOfNode(property.name, sourceFile)
+    };
+  }
+  return map;
+}
+
+/** Marks diagnostics as ours, so a client can filter on it. */
+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}.
+ */
+const VAL_DIAGNOSTIC_CODES = [/** Content does not satisfy the schema. */
+"val/validation", /** The schema itself is invalid. */
+"val/schema", /** The module could not be evaluated at all. */
+"val/fatal", /** A referenced image or file is not on disk. */
+"val/file-not-found", /** The module is not registered in `val.modules`, so Val will not serve it. */
+"val/missing-module"];
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+function severityFor({
+  code,
+  fixes
+}) {
+  if (code === "val/validation" && fixes && fixes.length > 0) {
+    return DiagnosticSeverity.Warning;
+  }
+  return DiagnosticSeverity.Error;
+}
+
+/** Range covering the start of the file, used when a path cannot be located. */
+const FALLBACK_RANGE = {
+  start: {
+    line: 0,
+    character: 0
+  },
+  end: {
+    line: 0,
+    character: 0
+  }
+};
+
+/** Fixes that operate on a file or image reference. */
+const FILE_FIXES = ["image:add-metadata", "image:check-metadata", "image:upload-remote", "image:download-remote", "image:check-remote", "file:add-metadata", "file:check-metadata", "file:upload-remote", "file:download-remote", "file:check-remote"];
+function build(range, message, data) {
+  return {
+    range,
+    severity: severityFor(data),
+    source: VAL_DIAGNOSTIC_SOURCE,
+    code: data.code,
+    message,
+    data
+  };
+}
+function createValDiagnostics({
+  moduleFilePath,
+  content,
+  text,
+  valRoot,
+  snapshot
+}) {
+  if (content.errors === false) {
+    return [];
+  }
+  const diagnostics = [];
+
+  // A fatal error means the module could not be evaluated, so there is no
+  // reliable path information: report it on the whole file.
+  for (const fatal of content.errors.fatal ?? []) {
+    diagnostics.push(build(FALLBACK_RANGE, fatal.message, {
+      code: "val/fatal",
+      sourcePath: moduleFilePath
+    }));
+  }
+  const rawValidation = content.errors.validation;
+  if (!rawValidation) {
+    return diagnostics;
+  }
+
+  // Resolve the deferred keyOf/route placeholders against the rest of the
+  // project. This is the same call `val validate` and the Val UI make, so all
+  // three agree on which references are actually broken.
+  const validation = snapshot ? resolveSchemaSourceFixes(rawValidation, snapshot) : dropDeferredPlaceholders(rawValidation);
+
+  // Only parse the source file if there is something to place in it.
+  const modulePathMap = createModulePathMap(ts.createSourceFile(moduleFilePath, text, ts.ScriptTarget.ES2020));
+  for (const [sourcePath, errors] of Object.entries(validation)) {
+    for (const error of errors) {
+      const fixes = error.fixes;
+
+      // A file-related fix cannot succeed if the file is not there, and
+      // "metadata is incorrect" is a misleading way to say "the file is
+      // missing". Report the real problem instead, exactly as the CLI's fix
+      // handlers do when their precondition fails.
+      const missing = valRoot && fixes?.some(fix => FILE_FIXES.includes(fix)) ? missingFileRef({
+        sourcePath,
+        content,
+        valRoot
+      }) : undefined;
+      if (missing) {
+        diagnostics.push(build(rangeOf(sourcePath, modulePathMap, "_ref"), `File ${missing} does not exist`, {
+          code: "val/file-not-found",
+          sourcePath,
+          filePath: missing
+        }));
+        continue;
+      }
+      diagnostics.push(build(rangeOf(sourcePath, modulePathMap), error.message, {
+        code: error.schemaError ? "val/schema" : "val/validation",
+        sourcePath,
+        ...(fixes ? {
+          fixes
+        } : {}),
+        ...(error.value !== undefined ? {
+          value: error.value
+        } : {})
+      }));
+    }
+  }
+  return diagnostics;
+}
+
+/**
+ * Resolve a source path to its file reference and report the absolute path when
+ * it is not on disk.
+ *
+ * Mirrors the precondition check in `handleFileMetadata`
+ * (`packages/cli/src/runValidation.ts`): resolve the path, read `FILE_REF_PROP`,
+ * check the file exists.
+ */
+function missingFileRef({
+  sourcePath,
+  content,
+  valRoot
+}) {
+  if (!content.source || !content.schema) {
+    return undefined;
+  }
+  try {
+    const [, modulePath] = Internal.splitModuleFilePathAndModulePath(sourcePath);
+    const resolved = Internal.resolvePath(modulePath, content.source, content.schema);
+    const ref = resolved.source?.[FILE_REF_PROP];
+    if (typeof ref !== "string") {
+      return undefined;
+    }
+    // Remote references are URLs and are not expected on disk.
+    if (Internal.remote.splitRemoteRef(ref).status === "success") {
+      return undefined;
+    }
+    const filePath = path.join(valRoot, ref);
+    return fs.existsSync(filePath) ? undefined : filePath;
+  } catch {
+    // Resolution can fail when the schema failed to serialize; skip the check
+    // rather than dropping the underlying validation error.
+    return undefined;
+  }
+}
+
+/**
+ * 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.
+ */
+function createProjectErrorDiagnostic({
+  moduleFilePath,
+  message
+}) {
+  return build(FALLBACK_RANGE, `Val could not evaluate this project, so no module is validated: ${message}`, {
+    code: "val/fatal",
+    sourcePath: moduleFilePath
+  });
+}
+
+/**
+ * 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.
+ */
+function createMissingModuleDiagnostic({
+  moduleFilePath
+}) {
+  return build(FALLBACK_RANGE, `${moduleFilePath} is not registered in val.modules, so Val will not serve it.`, {
+    code: "val/missing-module",
+    sourcePath: moduleFilePath
+  });
+}
+function rangeOf(sourcePath, modulePathMap, /** Optional child segment to prefer, for example `_ref`. */
+preferChild) {
+  if (!modulePathMap) {
+    return FALLBACK_RANGE;
+  }
+  let modulePath;
+  try {
+    [, modulePath] = Internal.splitModuleFilePathAndModulePath(sourcePath);
+  } catch {
+    // A path we cannot split is still worth reporting, just on the whole file.
+    return FALLBACK_RANGE;
+  }
+  // Module-level errors have an empty module path.
+  if (!modulePath) {
+    return FALLBACK_RANGE;
+  }
+  if (preferChild) {
+    const child = getModulePathRange(`${modulePath}.${JSON.stringify(preferChild)}`, modulePathMap);
+    if (child) {
+      return {
+        start: child.start,
+        end: child.end
+      };
+    }
+  }
+  const range = getModulePathRange(modulePath, modulePathMap);
+  return range ? {
+    start: range.start,
+    end: range.end
+  } : FALLBACK_RANGE;
+}
+
+/** Fixes core cannot resolve without a project-wide snapshot. */
+const DEFERRED_FIXES = ["keyof:check-keys", "router:check-route"];
+
+/**
+ * Fallback for when no snapshot is available: drop the placeholders rather than
+ * show their developer-facing text.
+ */
+function dropDeferredPlaceholders(validation) {
+  const out = {};
+  for (const [sourcePath, errors] of Object.entries(validation)) {
+    const kept = errors.filter(error => !(error.fixes?.length && error.fixes.every(fix => DEFERRED_FIXES.includes(fix))));
+    if (kept.length > 0) {
+      out[sourcePath] = kept;
+    }
+  }
+  return out;
+}
+
+/**
+ * Quick fixes, built by running Val's own fix machinery.
+ *
+ * The pipeline is deliberately the same one `val validate --fix` uses:
+ *
+ *   ValidationError -> createFixPatch -> Patch -> patchSourceFile -> TextEdit
+ *
+ * so an editor fix and a CLI fix cannot diverge. The previous VS Code extension
+ * hand-wrote AST edits per fix kind, which is how the two drifted apart.
+ */
+
+/**
+ * Fixes that can be computed locally, without network access or credentials.
+ *
+ * Remote upload/download need a logged-in session and are handled by a separate
+ * flow, so they are not offered as plain quick fixes: a code action that
+ * silently required auth would just fail.
+ */
+const LOCAL_FIXES = ["image:add-metadata", "image:check-metadata", "file:add-metadata", "file:check-metadata",
+// Gallery metadata: createFixPatch reads each entry's file and corrects the
+// stored metadata, dropping entries whose file has gone. Filesystem only.
+"images:check-all-files", "files:check-all-files"];
+
+/** Human-readable titles; falls back to the fix name for anything unknown. */
+const FIX_TITLES = {
+  "image:add-metadata": "Val: add image metadata",
+  "image:check-metadata": "Val: update image metadata",
+  "file:add-metadata": "Val: add file metadata",
+  "file:check-metadata": "Val: update file metadata",
+  "images:check-all-files": "Val: update gallery image metadata",
+  "files:check-all-files": "Val: update gallery file metadata"
+};
+function isLocalFix(fix) {
+  return LOCAL_FIXES.includes(fix);
+}
+
+/**
+ * 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.
+ */
+async function createValCodeActions({
+  document,
+  diagnostics,
+  content,
+  valRoot,
+  remoteHost = process.env.VAL_REMOTE_HOST || DEFAULT_VAL_REMOTE_HOST
+}) {
+  const actions = [];
+  for (const diagnostic of diagnostics) {
+    const data = diagnostic.data;
+    if (!data?.fixes?.length) {
+      continue;
+    }
+    for (const fix of data.fixes) {
+      if (!isLocalFix(fix)) {
+        continue;
+      }
+      const edit = await computeFixEdit({
+        document,
+        sourcePath: data.sourcePath,
+        // createFixPatch works one fix at a time; give it exactly this one so a
+        // failing sibling fix cannot suppress this action.
+        validationError: {
+          message: diagnostic.message,
+          value: data.value,
+          fixes: [fix]
+        },
+        content,
+        valRoot,
+        remoteHost
+      });
+      if (!edit) {
+        continue;
+      }
+      actions.push(CodeAction.create(FIX_TITLES[fix] ?? `Val: ${fix}`, {
+        changes: {
+          [document.uri]: [edit]
+        }
+      }, CodeActionKind.QuickFix));
+    }
+  }
+  return actions;
+}
+async function computeFixEdit({
+  document,
+  sourcePath,
+  validationError,
+  content,
+  valRoot,
+  remoteHost
+}) {
+  let fixed;
+  try {
+    fixed = await createFixPatch({
+      projectRoot: valRoot,
+      remoteHost
+    },
+    // `true` means "produce the patch"; nothing is written to disk here, the
+    // patch is applied to the editor's text and returned as an edit.
+    true, sourcePath, validationError, {}, content.source, content.schema);
+  } catch {
+    return undefined;
+  }
+  if (!fixed || fixed.patch.length === 0) {
+    return undefined;
+  }
+  const before = document.getText();
+  const patched = patchSourceFile(before, fixed.patch);
+  if (result.isErr(patched)) {
+    return undefined;
+  }
+  return minimalTextEdit(before, patched.value.text, document);
+}
+
+/**
+ * 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.
+ */
+function minimalTextEdit(before, after, document) {
+  if (before === after) {
+    return undefined;
+  }
+  let prefix = 0;
+  const maxPrefix = Math.min(before.length, after.length);
+  while (prefix < maxPrefix && before[prefix] === after[prefix]) {
+    prefix++;
+  }
+  let suffix = 0;
+  const maxSuffix = Math.min(before.length, after.length) - prefix;
+  while (suffix < maxSuffix && before[before.length - 1 - suffix] === after[after.length - 1 - suffix]) {
+    suffix++;
+  }
+  const range = {
+    start: document.positionAt(prefix),
+    end: document.positionAt(before.length - suffix)
+  };
+  return {
+    range,
+    newText: after.slice(prefix, after.length - suffix)
+  };
+}
+
+/**
+ * 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.
+ */
+
+/** The cursor is inside a plain string in the module's content. */
+
+/**
+ * The offsets of a string literal's contents, excluding its quotes.
+ *
+ * A client that does not auto-close quotes leaves `c.image("` unterminated while
+ * the user types. TypeScript still produces a string-literal node for it, but the
+ * node ends *at* the cursor rather than one character past it, so the usual
+ * `getEnd() - 1` bound excludes every position inside the literal and no
+ * completions are offered at all. The closing quote is therefore counted rather
+ * than assumed.
+ */
+function contentRangeOf(node, sourceFile) {
+  const raw = node.getText(sourceFile);
+  const quote = raw[0];
+  let closing = 0;
+  if (raw.length >= 2 && raw[raw.length - 1] === quote) {
+    // A quote preceded by an odd number of backslashes is escaped, so it is part
+    // of the contents rather than the terminator.
+    let backslashes = 0;
+    for (let i = raw.length - 2; i >= 1 && raw[i] === "\\"; i--) {
+      backslashes++;
+    }
+    closing = backslashes % 2 === 0 ? 1 : 0;
+  }
+  return {
+    contentStart: node.getStart(sourceFile) + 1,
+    contentEnd: node.getEnd() - closing
+  };
+}
+
+/**
+ * Find the innermost `c.image(...)` / `c.file(...)` call whose first argument
+ * contains `offset`.
+ */
+function getValCompletionContext(sourceFile, offset) {
+  let found;
+  let innermostString;
+  let innermostStringContent;
+  // Tracked explicitly: `ts.createSourceFile` does not set parent pointers
+  // unless asked, so `node.parent` cannot be relied on here.
+  let innermostStringParent;
+  function visit(node, parent) {
+    if (offset < node.getStart(sourceFile) || offset > node.getEnd()) {
+      return;
+    }
+    if (ts.isCallExpression(node)) {
+      const subType = fileConstructorSubType(node, sourceFile);
+      const [refArg] = node.arguments;
+      const refContent = refArg && ts.isStringLiteralLike(refArg) ? contentRangeOf(refArg, sourceFile) : undefined;
+      if (subType && refArg && ts.isStringLiteralLike(refArg) && refContent &&
+      // Inside the quotes, inclusive of both ends so completion works on an
+      // empty string and at either edge.
+      offset >= refContent.contentStart && offset <= refContent.contentEnd) {
+        const metadataArg = node.arguments[1];
+        found = {
+          kind: "file-ref",
+          subType,
+          currentText: refArg.text,
+          ...refContent,
+          refArgStart: refArg.getStart(sourceFile),
+          refArgEnd: refArg.getEnd(),
+          ...(metadataArg ? {
+            metadataStart: metadataArg.getStart(sourceFile),
+            metadataEnd: metadataArg.getEnd()
+          } : {})
+        };
+      }
+    }
+    if (ts.isStringLiteralLike(node)) {
+      const content = contentRangeOf(node, sourceFile);
+      if (offset >= content.contentStart && offset <= content.contentEnd) {
+        innermostString = node;
+        innermostStringContent = content;
+        innermostStringParent = parent;
+      }
+    }
+    ts.forEachChild(node, child => visit(child, node));
+  }
+  visit(sourceFile, undefined);
+  if (found) {
+    return found;
+  }
+  // Not a file reference, but still inside a string: schema-driven completions
+  // (keyOf keys, route paths) decide whether they apply.
+  if (innermostString && innermostStringContent) {
+    return {
+      kind: "string-value",
+      currentText: innermostString.text,
+      ...innermostStringContent,
+      // Uses the parent tracked during the walk, not `node.parent`, which
+      // `ts.createSourceFile` leaves unset unless asked to populate it.
+      isPropertyName: Boolean(innermostStringParent && ts.isPropertyAssignment(innermostStringParent) && innermostStringParent.name === innermostString),
+      ...(innermostStringParent && ts.isPropertyAssignment(innermostStringParent) && innermostStringParent.name !== innermostString && (ts.isIdentifier(innermostStringParent.name) || ts.isStringLiteral(innermostStringParent.name)) ? {
+        valueOfProperty: innermostStringParent.name.text
+      } : {})
+    };
+  }
+  return 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.
+ */
+function findFileRefArgument(sourceFile, refArgStart) {
+  let found;
+  function visit(node) {
+    if (found) {
+      return;
+    }
+    if (ts.isCallExpression(node) && fileConstructorSubType(node, sourceFile)) {
+      const [refArg] = node.arguments;
+      if (refArg && ts.isStringLiteralLike(refArg) && refArg.getStart(sourceFile) === refArgStart) {
+        const metadataArg = node.arguments[1];
+        found = {
+          refArgEnd: refArg.getEnd(),
+          ...(metadataArg ? {
+            metadataStart: metadataArg.getStart(sourceFile),
+            metadataEnd: metadataArg.getEnd()
+          } : {})
+        };
+        return;
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return found;
+}
+function fileConstructorSubType(node, sourceFile) {
+  if (!ts.isPropertyAccessExpression(node.expression)) {
+    return undefined;
+  }
+  if (node.expression.expression.getText(sourceFile) !== "c") {
+    return undefined;
+  }
+  const name = node.expression.name.getText(sourceFile);
+  return name === "image" || name === "file" ? name : undefined;
+}
+
+/**
+ * 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. */
+
+function createValCompletions({
+  document,
+  offset,
+  files,
+  moduleFilePath,
+  snapshot
+}) {
+  const sourceFile = ts.createSourceFile(document.uri, document.getText(), ts.ScriptTarget.ES2020);
+  const context = getValCompletionContext(sourceFile, offset);
+  if (!context) {
+    return [];
+  }
+  if (context.kind === "string-value") {
+    if (!moduleFilePath || !snapshot) {
+      return [];
+    }
+    return createSchemaDrivenCompletions({
+      document,
+      sourceFile,
+      offset,
+      moduleFilePath,
+      snapshot,
+      files,
+      isPropertyName: context.isPropertyName,
+      valueOfProperty: context.valueOfProperty,
+      contentStart: context.contentStart,
+      contentEnd: context.contentEnd
+    });
+  }
+
+  // `c.image()` only accepts images; `c.file()` accepts anything.
+  const candidates = context.subType === "image" ? files.images() : files.list();
+
+  // Replace the whole string contents rather than inserting at the cursor, so
+  // completing over an existing path does not concatenate the two.
+  const replaceRange = {
+    start: document.positionAt(context.contentStart),
+    end: document.positionAt(context.contentEnd)
+  };
+  return candidates.map((file, index) => {
+    const data = {
+      kind: "file-ref",
+      uri: document.uri,
+      ref: file.ref,
+      filePath: file.filePath,
+      subType: context.subType,
+      refArgStart: context.refArgStart
+    };
+    return {
+      label: file.ref,
+      kind: CompletionItemKind.File,
+      detail: file.mimeType,
+      textEdit: {
+        range: replaceRange,
+        newText: file.ref
+      },
+      // Preserve directory ordering rather than letting the client sort
+      // alphabetically on the full path.
+      sortText: String(index).padStart(5, "0"),
+      data
+    };
+  });
+}
+
+/**
+ * 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.
+ */
+async function resolveValCompletion({
+  item,
+  documents
+}) {
+  const data = item.data;
+  if (data?.kind !== "file-ref") {
+    return item;
+  }
+  const document = documents.get(data.uri);
+  if (!document) {
+    return item;
+  }
+
+  // Re-derive the argument offsets against the document as it is *now*: the user
+  // may have typed to filter the list since it was computed, which moves
+  // everything after the reference string. `additionalTextEdits` are applied
+  // verbatim by the client, so a stale offset here corrupts the file.
+  const args = findFileRefArgument(ts.createSourceFile(data.uri, document.getText(), ts.ScriptTarget.ES2020, false, ts.ScriptKind.TS), data.refArgStart);
+  if (!args) {
+    // The anchor no longer resolves, so there is no safe place to put the
+    // metadata. `val validate --fix` and the metadata quick fix still cover it.
+    return item;
+  }
+  const metadata = await readMetadata(data);
+  if (!metadata) {
+    return item;
+  }
+  const edit = args.metadataStart !== undefined && args.metadataEnd !== undefined ? {
+    // Replace an existing metadata argument.
+    range: {
+      start: document.positionAt(args.metadataStart),
+      end: document.positionAt(args.metadataEnd)
+    },
+    newText: metadata
+  } : {
+    // Insert one after the reference argument.
+    range: {
+      start: document.positionAt(args.refArgEnd),
+      end: document.positionAt(args.refArgEnd)
+    },
+    newText: `, ${metadata}`
+  };
+  return {
+    ...item,
+    additionalTextEdits: [edit]
+  };
+}
+
+/**
+ * Read metadata for the chosen file and render it as source.
+ *
+ * Uses `@valbuild/server`'s extractors, the same ones `val validate --fix` uses,
+ * so a completed reference and a fixed one agree.
+ */
+async function readMetadata(data) {
+  try {
+    const buffer = fs.readFileSync(data.filePath);
+    if (data.subType === "image") {
+      const metadata = await extractImageMetadata(data.filePath, buffer);
+      if (metadata.width === undefined || metadata.height === undefined || !metadata.mimeType) {
+        return undefined;
+      }
+      return `{ width: ${metadata.width}, height: ${metadata.height}, mimeType: ${JSON.stringify(metadata.mimeType)} }`;
+    }
+    const metadata = await extractFileMetadata(data.filePath, buffer);
+    if (!metadata.mimeType) {
+      return undefined;
+    }
+    return `{ mimeType: ${JSON.stringify(metadata.mimeType)} }`;
+  } catch {
+    // An unreadable or unrecognised file just means no metadata to offer.
+    return undefined;
+  }
+}
+
+/**
+ * Completions whose candidates come from the schema at the cursor.
+ *
+ * Handles `keyOf` (the keys of the record or object it points at) and `route`
+ * (the pages that exist in the project). Both need to look at other modules,
+ * hence the snapshot.
+ *
+ * The schema at the cursor is found by mapping the cursor position back to a
+ * module path and resolving the schema there with `Internal.resolvePath`, rather
+ * than walking the serialized schema by hand.
+ */
+function createSchemaDrivenCompletions({
+  document,
+  sourceFile,
+  offset,
+  moduleFilePath,
+  snapshot,
+  files,
+  isPropertyName,
+  valueOfProperty,
+  contentStart,
+  contentEnd
+}) {
+  const schema = snapshot.schemas[moduleFilePath];
+  const source = snapshot.sources[moduleFilePath];
+  if (!schema || source === undefined) {
+    return [];
+  }
+  const modulePathMap = createModulePathMap(sourceFile);
+  if (!modulePathMap) {
+    return [];
+  }
+  const modulePath = findModulePathAtPosition(modulePathMap, document.positionAt(offset));
+  if (modulePath === undefined) {
+    return [];
+  }
+  const range = {
+    start: document.positionAt(contentStart),
+    end: document.positionAt(contentEnd)
+  };
+
+  // A key is described by its container, not by itself: a gallery record is
+  // keyed by file reference, so the candidates come from the record's schema.
+  if (isPropertyName) {
+    const container = resolveSchemaAt(parentModulePath(modulePath), source, schema);
+    if (!container || typeof container !== "object" || !("type" in container) || container.type !== "record" || !("mediaType" in container) || !container.mediaType) {
+      return [];
+    }
+    const directory = "directory" in container && typeof container.directory === "string" ? container.directory : undefined;
+    const galleryFiles = container.mediaType === "images" ? files.images(directory) : files.list(directory);
+    return items(galleryFiles.map(file => file.ref), CompletionItemKind.File, range);
+  }
+  const fieldSchema = resolveSchemaAt(modulePath, source, schema);
+
+  // Checked before the schema is required, because Val describes richtext content
+  // as a whole rather than node by node: a link is a plain
+  // `{ tag: "a", href: ... }` object, so resolving the href's own path fails and
+  // there is no field schema to branch on. Walk out to the enclosing richtext and
+  // check that it permits inline links instead.
+  if (valueOfProperty === "href") {
+    const richtext = findEnclosingRichtext(modulePath, source, schema);
+    if (richtext && permitsInlineLinks(richtext)) {
+      return routeItems(snapshot, range);
+    }
+  }
+  if (!fieldSchema || typeof fieldSchema !== "object" || !("type" in fieldSchema)) {
+    return [];
+  }
+  if (fieldSchema.type === "keyOf") {
+    return items(keysOfKeyOf(fieldSchema, snapshot), CompletionItemKind.EnumMember, range);
+  }
+  if (fieldSchema.type === "route") {
+    return routeItems(snapshot, range);
+  }
+  return [];
+}
+
+/** The routes the project defines, as completion items. */
+function routeItems(snapshot, range) {
+  // The routes that exist are the keys of the project's router modules, which is
+  // exactly what getRoutesWithModulePaths reads out of the snapshot.
+  const routes = getRoutesWithModulePaths(snapshot.schemas, snapshot.sources);
+  return routes.map((route, index) => ({
+    label: route.route,
+    kind: CompletionItemKind.Value,
+    // Say which module defines the page, so an ambiguous route is
+    // distinguishable.
+    detail: route.moduleFilePath,
+    textEdit: {
+      range,
+      newText: route.route
+    },
+    sortText: String(index).padStart(5, "0")
+  }));
+}
+
+/**
+ * Walk out from a module path until a richtext schema is found.
+ *
+ * Resolving a path *inside* richtext content fails, since Val does not describe
+ * individual nodes with schemas, so the walk drops segments until it lands on the
+ * richtext field itself.
+ */
+function findEnclosingRichtext(modulePath, source, schema) {
+  let segments = Internal.splitModulePath(modulePath);
+  // Tests the cursor's own path first, then walks outwards: the path may already
+  // be the richtext field if the cursor is not inside a nested node.
+  for (;;) {
+    const candidate = resolveSchemaAt(Internal.patchPathToModulePath(segments), source, schema);
+    if (candidate && typeof candidate === "object" && "type" in candidate && candidate.type === "richtext") {
+      return candidate;
+    }
+    if (segments.length === 0) {
+      return undefined;
+    }
+    segments = segments.slice(0, -1);
+  }
+}
+
+/** Whether a richtext schema allows inline `a` links. */
+function permitsInlineLinks(richtext) {
+  if (!("options" in richtext)) {
+    return false;
+  }
+  const options = richtext.options;
+  // `inline.a` is either `true` or the schema the href must satisfy; both mean
+  // links are allowed.
+  return Boolean(options?.inline?.a);
+}
+
+/** Schema at a module path, or undefined when it cannot be resolved. */
+function resolveSchemaAt(modulePath, source, schema) {
+  try {
+    // Val's own resolver, rather than a hand-rolled serialized-schema walker.
+    return Internal.resolvePath(modulePath, source, schema).schema;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Drop the last segment of a module path; `""` is the module root. */
+function parentModulePath(modulePath) {
+  const segments = Internal.splitModulePath(modulePath);
+  return Internal.patchPathToModulePath(segments.slice(0, -1));
+}
+function items(labels, kind, range) {
+  return labels.map((label, index) => ({
+    label,
+    kind,
+    textEdit: {
+      range,
+      newText: label
+    },
+    // Preserve the source ordering rather than letting the client re-sort.
+    sortText: String(index).padStart(5, "0")
+  }));
+}
+function keysOfKeyOf(schema, snapshot) {
+  // Object targets serialize their keys directly.
+  if (Array.isArray(schema.values)) {
+    return schema.values;
+  }
+  // Record targets say "string"; the keys are whatever the target module holds.
+  if (!schema.path) {
+    return [];
+  }
+  try {
+    const [targetModuleFilePath, targetModulePath] = Internal.splitModuleFilePathAndModulePath(schema.path);
+    const targetSchema = snapshot.schemas[targetModuleFilePath];
+    const targetSource = snapshot.sources[targetModuleFilePath];
+    if (!targetSchema || targetSource === undefined) {
+      return [];
+    }
+    const resolved = Internal.resolvePath(targetModulePath, targetSource, targetSchema);
+    const value = resolved.source;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return [];
+    }
+    return Object.keys(value);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Lists the files a Val module may reference.
+ *
+ * Val stores referenced files under `/public/val` by convention (configurable
+ * via `files.directory` in val.config), and a reference is written as the path
+ * *including* the `/public` prefix — so this returns Val-style refs directly.
+ */
+
+/** Default directory, matching `files.directory` in val.config. */
+const DEFAULT_FILES_DIRECTORY = "/public/val";
+
+/**
+ * How long a directory listing is reused.
+ *
+ * Completions are requested per keystroke, so re-walking the tree every time is
+ * wasteful; a short window keeps newly added files appearing promptly without a
+ * filesystem watcher to invalidate and tear down.
+ */
+const CACHE_TTL_MS = 2000;
+function createPublicValFiles({
+  valRoot,
+  directory = DEFAULT_FILES_DIRECTORY,
+  now = () => Date.now()
+}) {
+  // Keyed by directory: a project has one files directory, but each gallery
+  // declares its own, and completions need whichever one is in scope.
+  const cache = new Map();
+  function read(directory) {
+    const root = path.join(valRoot, directory);
+    const files = [];
+    function walk(dir) {
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, {
+          withFileTypes: true
+        });
+      } catch {
+        // Directory does not exist yet, or is not readable: no candidates.
+        return;
+      }
+      for (const entry of entries) {
+        // Skip dotfiles: .DS_Store and friends are never valid references.
+        if (entry.name.startsWith(".")) {
+          continue;
+        }
+        const absolute = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(absolute);
+          continue;
+        }
+        const relative = path.relative(path.join(valRoot, directory), absolute).split(path.sep).join("/");
+        files.push({
+          ref: `${directory}/${relative}`,
+          filePath: absolute,
+          // Val's own extension -> mime table, rather than a vendored copy.
+          mimeType: Internal.filenameToMimeType(entry.name)
+        });
+      }
+    }
+    walk(root);
+    files.sort((a, b) => a.ref.localeCompare(b.ref));
+    return files;
+  }
+  function list(dir = directory) {
+    const at = now();
+    const hit = cache.get(dir);
+    if (hit && at - hit.at < CACHE_TTL_MS) {
+      return hit.files;
+    }
+    const files = read(dir);
+    cache.set(dir, {
+      at,
+      files
+    });
+    return files;
+  }
+  return {
+    list,
+    images: dir => list(dir).filter(f => f.mimeType?.startsWith("image/")),
+    invalidate: () => {
+      cache.clear();
+    }
+  };
+}
+
+/**
+ * Works out which Val modules a `val.modules.{ts,js}` file registers.
+ *
+ * Val only serves modules listed there, so an unregistered `.val.ts` file
+ * silently does nothing.
+ *
+ * Rather than pattern-matching the accepted authoring shapes — `config.modules([…])`
+ * vs `modules(config, […])`, bare `import("./x.val")` vs
+ * `{ def: () => import("./x.val") }` — this collects *every* dynamic import
+ * specifier in the file. That is deliberate:
+ *
+ *  - it covers all current shapes with one rule, and any shape added later;
+ *  - when in doubt it over-reports registration, so a new authoring form makes
+ *    the diagnostic go quiet rather than firing a false "missing module" on
+ *    every file, which is the failure mode that actually hurts.
+ */
+function findRegisteredModuleSpecifiers(sourceFile) {
+  const specifiers = [];
+  function visit(node) {
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+      const [arg] = node.arguments;
+      if (arg && ts.isStringLiteralLike(arg)) {
+        specifiers.push(arg.text);
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return specifiers;
+}
+
+/**
+ * Whether `moduleFilePath` is registered by the given `val.modules` file.
+ *
+ * @param valModulesDir directory containing the val.modules file, relative to
+ *   the Val root (`""` when it sits at the root).
+ * @param moduleFilePath the module's path, Val-style: root-relative, leading
+ *   slash, with extension (for example `/content/page.val.ts`).
+ */
+function isModuleRegistered({
+  sourceFile,
+  valModulesDir,
+  moduleFilePath
+}) {
+  const target = stripValModuleExtension(moduleFilePath);
+  return findRegisteredModuleSpecifiers(sourceFile).some(specifier => {
+    // Specifiers are written relative to the val.modules file and normally omit
+    // the extension ("./content/page.val").
+    const resolved = specifier.startsWith(".") ? path.posix.normalize(path.posix.join("/", valModulesDir, stripValModuleExtension(specifier))) : stripValModuleExtension(specifier);
+    return resolved === target;
+  });
+}
+
+/** `/content/page.val.ts` -> `/content/page.val` (also handles `.val` already). */
+function stripValModuleExtension(specifier) {
+  return specifier.replace(/\.val\.(ts|js|tsx|jsx)$/, ".val");
+}
+
+/**
+ * Conversions between LSP document URIs and the paths Val uses.
+ *
+ * Deliberately minimal rather than pulling in `vscode-uri`: the server only ever
+ * deals with local `file:` URIs, and keeping this small makes the assumptions
+ * visible.
+ */
+
+/** Matches the Val module files the server validates. */
+const VAL_MODULE_RE = /\.val\.(ts|js|tsx|jsx)$/;
+
+/** `file:` with an optional authority, capturing authority and path apart. */
+const FILE_URI_RE = /^file:\/\/([^/?#]*)([^?#]*)/i;
+
+/** A `/c:/...` prefix, i.e. a Windows drive letter as it appears in a URI. */
+const URI_DRIVE_LETTER_RE = /^\/([a-zA-Z]:)(\/|$)/;
+function isValModuleUri(uri) {
+  return VAL_MODULE_RE.test(uri);
+}
+
+/**
+ * `decodeURIComponent` throws on malformed escapes (`%zz`). A client that sends
+ * one is broken, but that should not take the server down: fall back to the
+ * undecoded text so the path is at worst not found.
+ */
+function decodeSafely(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * `file:///a/b.val.ts` -> `/a/b.val.ts`
+ *
+ * Percent escapes are decoded, Windows drive letters lose the leading slash
+ * (`file:///c%3A/a` -> `c:/a`), and a URI with an authority is read as a UNC
+ * path (`file://host/share/a` -> `//host/share/a`). Anything that is not a
+ * `file:` URI is passed through unchanged, since callers also hand us plain
+ * paths.
+ */
+function uriToPath(uri) {
+  const match = FILE_URI_RE.exec(uri);
+  if (!match) {
+    return uri;
+  }
+  const authority = decodeSafely(match[1]);
+  const fsPath = decodeSafely(match[2] || "/");
+  if (authority) {
+    return `//${authority}${fsPath}`;
+  }
+  return fsPath.replace(URI_DRIVE_LETTER_RE, "$1$2");
+}
+
+/**
+ * `/a/b.val.ts` -> `file:///a/b.val.ts`
+ *
+ * The escaping matches what VS Code produces (drive-letter colons included), so
+ * that a URI built here can be looked up in the open-document map keyed by the
+ * URIs the client sent.
+ */
+function pathToUri(fsPath) {
+  const normalized = fsPath.split(path.sep).join("/");
+  const rooted = normalized.startsWith("/") ? normalized : `/${normalized}`;
+  return `file://${rooted.split("/").map(segment => encodeURIComponent(segment)).join("/")}`;
+}
+
+/**
+ * Convert a document URI into the `ModuleFilePath` Val addresses it by: a
+ * POSIX-style path relative to the Val root, with a leading slash.
+ *
+ * Returns `undefined` when the file lies outside the Val root — one server
+ * serves exactly one root, so another root's files are not its business.
+ */
+function toModuleFilePath(valRoot, uri) {
+  const fsPath = uriToPath(uri);
+  const relative = path.relative(valRoot, fsPath);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return undefined;
+  }
+  return `/${relative.split(path.sep).join("/")}`;
+}
+
+/**
+ * How long to wait after an edit before re-evaluating.
+ *
+ * Evaluation is ~15ms per module (see scripts/evalLatency.bench.js), so this is
+ * about avoiding pointless work mid-keystroke rather than about hiding latency.
+ */
+const VALIDATION_DEBOUNCE_MS = 200;
+
+/**
+ * Everything resolved during `initialize` that the rest of the server needs.
+ * Held in one object so that later phases (diagnostics, completions, commands)
+ * have a single place to read session state from.
+ */
+
+/**
+ * Read and sanity-check the client's `initializationOptions`.
+ *
+ * A client that predates these options, or a bare LSP client such as a
+ * hand-written Neovim config, may send nothing useful. Rather than failing, we
+ * fall back to the workspace root and to the narrowest protocol range, so the
+ * server still starts.
+ */
+function parseInitializationOptions(params) {
+  const raw = params.initializationOptions;
+  const workspaceFolderUri = params.workspaceFolders?.[0]?.uri;
+  const fallbackRoot = (workspaceFolderUri !== undefined ? uriToPath(workspaceFolderUri) : null) ?? params.rootPath ?? process.cwd();
+  return {
+    client: {
+      name: raw?.client?.name ?? params.clientInfo?.name ?? "unknown",
+      version: raw?.client?.version ?? params.clientInfo?.version ?? null
+    },
+    supportedProtocolVersions: parseVersionRange(raw?.supportedProtocolVersions),
+    valRoot: raw?.valRoot ?? fallbackRoot,
+    env: pickEnvOverrides(raw?.env)
+  };
+}
+
+/**
+ * Read the protocol range a client claims to speak.
+ *
+ * Falls back to `{min: 1, max: 1}` for anything that is not a pair of finite
+ * numbers. A half-filled object would otherwise produce `NaN` bounds, and every
+ * comparison against `NaN` is false — which `negotiateProtocolVersion` reads as
+ * "client too old" and refuses to serve, rather than as the graceful default a
+ * bare LSP client is meant to get.
+ */
+function parseVersionRange(raw) {
+  const fallback = {
+    min: 1,
+    max: 1
+  };
+  if (!raw || typeof raw !== "object") {
+    return fallback;
+  }
+  const {
+    min,
+    max
+  } = raw;
+  if (typeof min !== "number" || typeof max !== "number" || !Number.isFinite(min) || !Number.isFinite(max) || max < min) {
+    return fallback;
+  }
+  return {
+    min,
+    max
+  };
+}
+
+/**
+ * Keep only the environment variables Val documents.
+ *
+ * `initializationOptions` is untyped JSON at runtime, so a client can send any
+ * key at all. Dropping the rest here means neither this server nor anything
+ * reading {@link ValInitializationOptions.env} downstream can be talked into
+ * setting `PATH` or `NODE_OPTIONS`.
+ *
+ * Returns `undefined` when the client sent nothing usable, so that "no
+ * overrides" stays distinguishable from "an empty set of overrides".
+ */
+function pickEnvOverrides(env) {
+  if (!env || typeof env !== "object") {
+    return undefined;
+  }
+  const record = {
+    ...env
+  };
+  const picked = {};
+  let any = false;
+  for (const key of VAL_ENV_OVERRIDE_KEYS) {
+    const value = record[key];
+    if (typeof value === "string") {
+      picked[key] = value;
+      any = true;
+    }
+  }
+  return any ? picked : undefined;
+}
+
+/**
+ * Apply `VAL_*` overrides the client forwarded, so an editor session can be
+ * pointed at a non-production Val backend without restarting the editor with a
+ * modified environment.
+ */
+function applyEnvOverrides(options) {
+  const env = options.env;
+  if (!env) {
+    return;
+  }
+  // Iterate the allowlist rather than what was sent: `options` may have been
+  // built by a caller that did not go through `parseInitializationOptions`.
+  for (const key of VAL_ENV_OVERRIDE_KEYS) {
+    const value = env[key];
+    if (typeof value === "string" && value) {
+      process.env[key] = value;
+    }
+  }
+}
+
+/**
+ * Files that every Val module is evaluated through, so an edit to one makes every
+ * module's result stale rather than just its own.
+ *
+ * `val.modules` decides which modules Val serves at all; `val.config` is what the
+ * modules import `c` and `s` from.
+ */
+const PROJECT_WIDE_FILE_RE = /[/\\]val\.(modules|config)\.(ts|js)$/;
+
+/**
+ * Report a Val module that `val.modules` does not register.
+ *
+ * Reads `val.modules.{ts,js}` on demand, through the editor's buffer when it is
+ * open: adding a module to the registry must clear the diagnostic straight away,
+ * not only once the user saves. Returns `undefined` when no such file exists —
+ * that is a project-level problem, not something to blame on an individual
+ * module.
+ */
+function findMissingModuleDiagnostic(valRoot, moduleFilePath, read) {
+  for (const candidate of ["val.modules.ts", "val.modules.js"]) {
+    const file = path.join(valRoot, candidate);
+    let text = read(file);
+    if (text === undefined) {
+      try {
+        text = fs.readFileSync(file, "utf8");
+      } catch {
+        continue;
+      }
+    }
+    const registered = isModuleRegistered({
+      sourceFile: ts.createSourceFile(file, text, ts.ScriptTarget.ES2020),
+      valModulesDir: "",
+      moduleFilePath
+    });
+    return registered ? undefined : createMissingModuleDiagnostic({
+      moduleFilePath
+    });
+  }
+  return undefined;
+}
+
+/**
+ * Wire up a Val language server on an existing connection.
+ *
+ * Split out from {@link main} so `main` stays a thin transport choice.
+ */
+function createValLanguageServer(connection) {
+  const documents = new TextDocuments(TextDocument);
+
+  /**
+   * The editor's view of a file, by absolute path, or `undefined` when the file
+   * is not open.
+   *
+   * Found by comparing paths rather than by rebuilding the client's URI: URI
+   * escaping is not something two serializers agree on byte for byte (`!`, `'`,
+   * `(`, `)`, `*` and drive-letter colons all vary), and a near-miss would
+   * silently fall back to disk — exactly the bug this server exists to avoid.
+   * The number of open documents is small, so a scan is cheaper than keeping an
+   * index in sync.
+   */
+  function readOpenDocument(fsPath) {
+    const wanted = path.normalize(fsPath);
+    for (const document of documents.all()) {
+      if (path.normalize(uriToPath(document.uri)) === wanted) {
+        return document.getText();
+      }
+    }
+    return undefined;
+  }
+  let session;
+  let project;
+  let publicFiles;
+  const pending = new Map();
+
+  /**
+   * Re-evaluate a module and publish its diagnostics.
+   *
+   * Evaluation costs ~15ms, so this is debounced rather than run on every
+   * keystroke, and a newer edit supersedes an in-flight timer for the same file.
+   */
+  function scheduleValidation(uri) {
+    const existing = pending.get(uri);
+    if (existing) {
+      clearTimeout(existing);
+    }
+    pending.set(uri, setTimeout(() => {
+      pending.delete(uri);
+      void validate(uri);
+    }, VALIDATION_DEBOUNCE_MS));
+  }
+  async function validate(uri) {
+    const document = documents.get(uri);
+    if (!project || !document || !isValModuleUri(uri)) {
+      return;
+    }
+    const moduleFilePath = toModuleFilePath(project.valRoot, uri);
+    if (!moduleFilePath) {
+      return;
+    }
+    try {
+      // The module's own content changed, so any cached result is stale.
+      project.invalidate(moduleFilePath);
+      const result = await project.getModule(moduleFilePath);
+      if (result.status === "error") {
+        // A project-level problem (no tsconfig, missing @valbuild/core, a module
+        // that throws while `val.modules` is evaluated) is not a property of this
+        // file. It still has to be visible: publishing nothing would silently
+        // drop every Val diagnostic and look like "all good".
+        connection.console.warn(`Val: ${result.error.code}: ${result.error.message}`);
+        connection.sendDiagnostics({
+          uri,
+          diagnostics: [createProjectErrorDiagnostic({
+            moduleFilePath,
+            message: result.error.message
+          })]
+        });
+        return;
+      }
+      // Needed to resolve keyOf/route validation, which has to look at other
+      // modules. Built once and refreshed per changed module.
+      const snapshotResult = await project.getSnapshot();
+      const diagnostics = createValDiagnostics({
+        moduleFilePath,
+        content: result.content,
+        text: document.getText(),
+        valRoot: project.valRoot,
+        ...(snapshotResult.status === "ok" ? {
+          snapshot: snapshotResult.snapshot
+        } : {})
+      });
+      const unregistered = findMissingModuleDiagnostic(project.valRoot, moduleFilePath, readOpenDocument);
+      if (unregistered) {
+        diagnostics.push(unregistered);
+      }
+      connection.sendDiagnostics({
+        uri,
+        diagnostics
+      });
+    } catch (e) {
+      // Never let a single bad module take the server down.
+      connection.console.error(`Val: failed to validate ${uri}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  connection.onInitialize(params => {
+    const options = parseInitializationOptions(params);
+    applyEnvOverrides(options);
+    const negotiation = negotiateProtocolVersion(options.supportedProtocolVersions, SUPPORTED_PROTOCOL_VERSIONS);
+    const versions = {
+      core: Internal.VERSION.core,
+      languageServer: getLanguageServerVersion()
+    };
+    if (negotiation.status !== "ok") {
+      // Still return a valid InitializeResult: the client needs the payload
+      // below to tell the user *which* side to update. It is the client's job
+      // to stop the server after reading `incompatible`.
+      const val = {
+        protocolVersion: SUPPORTED_PROTOCOL_VERSIONS.max,
+        incompatible: negotiation,
+        versions,
+        valRoot: options.valRoot,
+        features: [],
+        commands: []
+      };
+      return {
+        capabilities: {
+          experimental: {
+            val
+          }
+        }
+      };
+    }
+    const clientCapabilities = params.capabilities.experimental?.val ?? {};
+
+    // Announce only what this version actually serves: a client hides UI for
+    // anything missing here, and ignores anything it does not recognise.
+    // Completions and commands land in later phases.
+    const features = ["diagnostics", "fix/metadata", "completions/mediaPath", "completions/keyOf", "completions/route", "fix/gallery", "completions/galleryKey", "completions/richtextLink"];
+    const commands = [];
+    publicFiles = createPublicValFiles({
+      valRoot: options.valRoot
+    });
+    // A project can point `files.directory` somewhere other than /public/val, and
+    // media-path completions would list nothing if we assumed the default.
+    // Reading val.config is async and `initialize` is not, so the default stands
+    // until the real value arrives — completions cannot be requested before
+    // `initialize` returns anyway.
+    void findAndEvalValConfigFile(options.valRoot).then(config => {
+      const directory = config?.files?.directory;
+      if (directory && directory !== DEFAULT_FILES_DIRECTORY) {
+        publicFiles = createPublicValFiles({
+          valRoot: options.valRoot,
+          directory
+        });
+      }
+    }).catch(e => {
+      // A broken or unreadable val.config is reported per module by the
+      // service; here it only means "keep the default directory".
+      connection.console.warn(`Val: could not read val.config: ${e instanceof Error ? e.message : String(e)}`);
+    });
+    project = createValProject({
+      valRoot: options.valRoot,
+      open: {
+        // Prefer the editor's buffer; fall back to disk for files the user has
+        // not opened.
+        read: readOpenDocument
+      }
+    });
+    session = {
+      valRoot: options.valRoot,
+      clientCapabilities,
+      protocolVersion: negotiation.protocolVersion,
+      features
+    };
+    connection.console.log(`Val language server ${versions.languageServer ?? "?"} ` + `(@valbuild/core ${versions.core ?? "?"}, protocol v${negotiation.protocolVersion}) ` + `serving ${options.valRoot} for ${options.client.name} ${options.client.version ?? "?"}`);
+    const val = {
+      protocolVersion: negotiation.protocolVersion,
+      versions,
+      valRoot: options.valRoot,
+      features,
+      commands
+    };
+    return {
+      capabilities: {
+        textDocumentSync: TextDocumentSyncKind.Incremental,
+        codeActionProvider: {
+          codeActionKinds: [CodeActionKind.QuickFix]
+        },
+        completionProvider: {
+          resolveProvider: true,
+          // Completing a path involves "/" and "." characters.
+          triggerCharacters: ["/", "."]
+        },
+        executeCommandProvider: commands.length > 0 ? {
+          commands
+        } : undefined,
+        experimental: {
+          val
+        }
+      }
+    };
+  });
+  connection.onCompletion(async params => {
+    const document = documents.get(params.textDocument.uri);
+    if (!publicFiles || !project || !document || !isValModuleUri(params.textDocument.uri)) {
+      return [];
+    }
+    try {
+      const moduleFilePath = toModuleFilePath(project.valRoot, params.textDocument.uri);
+      // Only needed for schema-driven completions; file references do not use it.
+      const snapshotResult = await project.getSnapshot();
+      return createValCompletions({
+        document,
+        offset: document.offsetAt(params.position),
+        files: publicFiles,
+        ...(moduleFilePath ? {
+          moduleFilePath
+        } : {}),
+        ...(snapshotResult.status === "ok" ? {
+          snapshot: snapshotResult.snapshot
+        } : {})
+      });
+    } catch (e) {
+      connection.console.error(`Val: failed to build completions: ${e instanceof Error ? e.message : String(e)}`);
+      return [];
+    }
+  });
+  connection.onCompletionResolve(async item => {
+    if (!project) {
+      return item;
+    }
+    try {
+      return await resolveValCompletion({
+        item,
+        documents
+      });
+    } catch (e) {
+      connection.console.error(`Val: failed to resolve completion: ${e instanceof Error ? e.message : String(e)}`);
+      return item;
+    }
+  });
+  connection.onCodeAction(async params => {
+    const document = documents.get(params.textDocument.uri);
+    if (!project || !document || !isValModuleUri(params.textDocument.uri)) {
+      return [];
+    }
+    const moduleFilePath = toModuleFilePath(project.valRoot, params.textDocument.uri);
+    if (!moduleFilePath) {
+      return [];
+    }
+    try {
+      const result = await project.getModule(moduleFilePath);
+      if (result.status === "error") {
+        return [];
+      }
+      return await createValCodeActions({
+        document,
+        diagnostics: params.context.diagnostics,
+        content: result.content,
+        valRoot: project.valRoot
+      });
+    } catch (e) {
+      connection.console.error(`Val: failed to build code actions for ${params.textDocument.uri}: ${e instanceof Error ? e.message : String(e)}`);
+      return [];
+    }
+  });
+
+  // Validate when a module is opened and whenever it changes. `didChange` fires
+  // per keystroke, which scheduleValidation debounces.
+  documents.onDidOpen(({
+    document
+  }) => scheduleValidation(document.uri));
+  documents.onDidChangeContent(({
+    document
+  }) => {
+    if (PROJECT_WIDE_FILE_RE.test(uriToPath(document.uri))) {
+      // A project-wide fact changed, so every module's cached result is stale --
+      // not just this file's. `invalidate()` with no argument clears the content
+      // cache too, which the per-module fingerprint check would not.
+      project?.invalidate();
+      for (const open of documents.all()) {
+        if (isValModuleUri(open.uri)) {
+          scheduleValidation(open.uri);
+        }
+      }
+      return;
+    }
+    scheduleValidation(document.uri);
+  });
+  documents.onDidClose(({
+    document
+  }) => {
+    const timer = pending.get(document.uri);
+    if (timer) {
+      clearTimeout(timer);
+      pending.delete(document.uri);
+    }
+    // Clear our diagnostics so they do not linger for a file the user closed.
+    connection.sendDiagnostics({
+      uri: document.uri,
+      diagnostics: []
+    });
+  });
+  connection.onShutdown(() => {
+    for (const timer of pending.values()) {
+      clearTimeout(timer);
+    }
+    pending.clear();
+    void project?.dispose();
+    project = undefined;
+    publicFiles = undefined;
+    session = undefined;
+  });
+  documents.listen(connection);
+  connection.listen();
+  return {
+    documents,
+    getSession: () => session
+  };
+}
+
+/**
+ * Entry point used by `bin.js`.
+ *
+ * `createConnection` picks its transport from argv (`--stdio`, `--node-ipc`,
+ * `--socket=`), so the same binary serves VS Code (IPC) and any other LSP
+ * client (stdio).
+ */
+function main() {
+  createValLanguageServer(createConnection(ProposedFeatures.all));
+}
+
+export { DEFAULT_FILES_DIRECTORY, PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, VAL_DIAGNOSTIC_CODES, VAL_DIAGNOSTIC_SOURCE, VAL_FEATURES, VAL_INPUT_REQUEST, VAL_PICK_REQUEST, createEditorFsHost, createMissingModuleDiagnostic, createModulePathMap, createProjectErrorDiagnostic, createPublicValFiles, createValCodeActions, createValCompletions, createValDiagnostics, createValLanguageServer, createValProject, defaultCoreResolver, findModulePathAtPosition, findRegisteredModuleSpecifiers, getLanguageServerVersion, getModulePathRange, getValCompletionContext, isLocalFix, isModuleRegistered, isValModuleUri, main, mapOpenDocuments, minimalTextEdit, negotiateProtocolVersion, pathToUri, resolveValCompletion, severityFor, toModuleFilePath, uriToPath };