@hydranium/core 1.0.0-next.27 → 1.0.0-next.271

package/src/lsp/hydranium-document-update-handler.ts

@@ -7,30 +7,35 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Debouncer, type Logger, ObservableValue, type MaybeObservableValue } from '@hydranium/protocol';
+import {
+   Debouncer,
+   Deferred,
+   type Logger,
+   ObservableValue,
+   type MaybeObservableValue,
+   TIMED_OUT,
+   describeErrorWithStack
+} from '@hydranium/protocol';
 import { URI, UriUtils } from '@hydranium/langium';
 import { DefaultDocumentUpdateHandler } from '@hydranium/langium/lsp';
-import { type HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
+import { HYDRANIUM_BUILD_REASONS, type HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
 import { type ServerSharedServices } from '../langium/module.js';
 import { LANGUAGE_CLIENT_ID } from '../documents/client-ids.js';
-import { type SelfSaveRegistry } from '../documents/self-save-registry.js';
-import { type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import { type SelfSaveRegistry } from '../langium/workspace/self-save-registry.js';
+import { type WritableFileSystemProvider } from '../langium/workspace/file-system-provider.js';
 import { type HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
-import { type DidChangeWatchedFilesParams, type FileEvent, FileChangeType, type TextDocumentChangeEvent } from 'vscode-languageserver';
+import { isConnectionGoneError } from '../util/connection-liveness.js';
+import {
+   type DidChangeWatchedFilesParams,
+   type FileEvent,
+   FileChangeType,
+   type TextDocumentChangeEvent,
+   type TextDocumentWillSaveEvent,
+   type TextEdit
+} from 'vscode-languageserver';
 import { type TextDocument } from 'vscode-languageserver-textdocument';
 
-/**
- * Default LSP-event reasons stamped by {@link HydraniumDocumentUpdateHandler}
- * onto the next `documentBuilder.update` call via `markNextReason`. Exposed
- * so adopters subclassing the handler can layer additional reasons or rename
- * existing ones without losing the canonical names the framework emits.
- */
-export const HYDRANIUM_BUILD_REASONS = Object.freeze({
-   didOpen: 'didOpen',
-   didChangeContent: 'didChangeContent',
-   didChangeWatchedFiles: 'didChangeWatchedFiles',
-   didClose: 'didClose'
-} as const);
+export { HYDRANIUM_BUILD_REASONS };
 
 /**
  * Construction options for {@link HydraniumDocumentUpdateHandler}.
@@ -56,6 +61,17 @@ export interface HydraniumDocumentUpdateHandlerOptions {
     * load tests).
     */
    readonly bypassNonLanguageClientChanges?: boolean;
+   /**
+    * Longest an editor's save waits on the server, in milliseconds, at each of
+    * its two steps: the `willSaveWaitUntil` answer waits for the server's disk
+    * writes of the document already queued, and server writes queued after the
+    * answer wait for the editor's `didSave`. Either wait that runs out is
+    * logged, and the editor's write and the server's can then land in either
+    * order. Default `1000`: VS Code gives up on an answer after about 1.5 s,
+    * and switches the listener off for the session once four answers, over
+    * all documents, timed out or failed.
+    */
+   readonly willSaveGateMs?: number;
 }
 
 /**
@@ -71,30 +87,36 @@ export interface HydraniumDocumentUpdateHandlerOptions {
  *     changes and watched-file changes bypass the debounce (their
  *     producers are already coalesced).
  *  3. **Build-reason stamping** — the LSP event overrides
- *     (`didOpenDocument`, `didChangeContent`, `didChangeWatchedFiles`,
- *     `didCloseDocument`) populate {@link nextReason} with a canonical
- *     reason string. {@link fireDocumentUpdate} captures the reason;
- *     {@link dispatch} stages it on the builder via
- *     {@link HydraniumDocumentBuilder.markNextReason}, so a subclass that
- *     formats build logs can tag its line with the event that caused the
- *     build without per-adopter wiring to capture it.
- *  4. **Last-client-close rebuild trigger** ({@link didCloseDocument}) —
- *     when the final client closes a document, dispatch a build so the
- *     LangiumDocument's `textDocument` is refreshed (from disk for `file:`
- *     URIs, or removed from the index for ephemeral URIs). Langium's
- *     default handler does not implement `didCloseDocument`, so the
- *     in-memory text of the last writer would otherwise persist.
+ *     (`didOpenDocument`, `didChangeContent`, `didChangeWatchedFiles`)
+ *     populate {@link nextReason} with a canonical reason string.
+ *     {@link fireDocumentUpdate} captures the reason; {@link dispatch} hands
+ *     it to {@link HydraniumDocumentBuilder.scheduleUpdate}, which stages it
+ *     through {@link HydraniumDocumentBuilder.markNextReason} when the build
+ *     runs, so a subclass that formats build logs can tag its line with the
+ *     event that caused the build without per-adopter wiring to capture it.
+ *  4. **Editor save gate** ({@link willSaveDocumentWaitUntil}) — the editor
+ *     writes the file itself, so the server's disk writes of that document
+ *     are ordered around it: the editor's save waits for the ones already
+ *     queued, and the ones queued during its save wait for its `didSave`.
+ *     Both waits are capped by
+ *     {@link HydraniumDocumentUpdateHandlerOptions.willSaveGateMs}.
+ *
+ * What the build keeps after a document's last close is not dispatched here:
+ * the store hands the released document to the `DocumentReleaseHandler` for
+ * every head, the LSP head included, so a `didCloseDocument` added in a
+ * subclass would build the document twice. A change still debounced for the
+ * document is dropped when the store releases it: the release handler rebuilds
+ * the document from the file system provider or removes it.
  *
  * Adopters with their own handler subclass should extend this class
  * (not Langium's `DefaultDocumentUpdateHandler`) so all of them are
  * preserved. The {@link dispatch} hook is the canonical override
- * point for adopters that need to stamp additional per-build metadata
- * inside the workspace-lock callback.
+ * point for adopters that need to stamp additional per-build metadata.
  */
 export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler {
    /**
     * Narrow Langium's `DefaultDocumentUpdateHandler.documentBuilder` typing to
-    * the framework subclass: `markNextReason` is the only method this handler
+    * the framework subclass: `scheduleUpdate` is the only method this handler
     * reaches for beyond the Langium interface.
     */
    declare protected readonly documentBuilder: HydraniumDocumentBuilder;
@@ -126,13 +148,27 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
    protected nextReason?: string;
    /**
     * Build-reason captured at `fireDocumentUpdate` time, drained by
-    * {@link dispatch} into `markNextReason`. Survives across debounced
-    * batches (`?? pendingReason` in `fireDocumentUpdate` retains the
-    * first reason in a coalesced burst).
+    * {@link dispatch} into the scheduled build. Survives across debounced
+    * batches: `fireDocumentUpdate` replaces it with each event's reason, so a
+    * coalesced burst carries its latest.
     */
    protected pendingReason?: string;
 
-   constructor(services: ServerSharedServices, options: HydraniumDocumentUpdateHandlerOptions = {}) {
+   protected readonly willSaveGateMs: number;
+   /**
+    * Per document URI, the release of the hold an editor's save in progress
+    * keeps on the document's disk queue. A second save of the document
+    * releases the first: its hold would otherwise keep the second's answer
+    * waiting until the cap. The key is the document, not the save, so for a
+    * client that sends its next `willSaveWaitUntil` before the previous
+    * `didSave`, that late `didSave` releases the next save's hold.
+    */
+   protected readonly editorSaves = new Map<string, () => void>();
+
+   constructor(
+      protected readonly services: ServerSharedServices,
+      options: HydraniumDocumentUpdateHandlerOptions = {}
+   ) {
       super(services);
       this.logger = services.Logger;
       this.selfSaveRegistry = services.workspace.SelfSaveRegistry;
@@ -141,6 +177,21 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
       this.debounce = ObservableValue.from(options.debounceMs ?? 0);
       this.flushDebouncer = new Debouncer(services.Clock, () => this.flushPending(), { delayMs: this.debounce });
       this.bypassNonLanguageClientChanges = options.bypassNonLanguageClientChanges ?? true;
+      this.willSaveGateMs = options.willSaveGateMs ?? 1000;
+      this.textDocuments.onDidSaveInLanguageClient(event => this.editorSaves.get(event.uri)?.());
+      services.workspace.VersionSyncService.registerDeferredBuilds(
+         uri => this.pendingChanged.has(uri.toString()) || this.pendingDeleted.has(uri.toString())
+      );
+      // A change still debounced for a document the store has released would
+      // build it once more after the release handler's build: from the
+      // provider again, or, for a document the release removed, by reading a
+      // file that is not there.
+      this.textDocuments.onDidReleaseDocument(event => {
+         this.pendingChanged.delete(URI.parse(event.uri).toString());
+         if (this.pendingChanged.size === 0 && this.pendingDeleted.size === 0) {
+            this.pendingReason = undefined;
+         }
+      });
    }
 
    didOpenDocument(_change: TextDocumentChangeEvent<TextDocument>): void {
@@ -165,61 +216,23 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
       super.didChangeContent(change);
    }
 
-   /**
-    * Last-client close is the missing rebuild trigger in Langium's
-    * `DefaultDocumentUpdateHandler`: `documents.onDidClose` fires on every
-    * per-client close, but the default handler ignores the event entirely.
-    * For multi-client servers this leaves the LangiumDocument carrying the
-    * unsaved in-memory `textDocument` of the last writer until something
-    * else triggers a rebuild — integrity rules walking `langiumDocuments.all`
-    * then see stale text long after the user discarded their edits.
-    *
-    * We funnel the last-client transition through the same dispatch path
-    * the other LSP events use, so the rebuild gets debouncing, workspace
-    * locking, build-reason stamping, and `markNextReason` for free. The
-    * scheme split governs the `DocumentBuilder.update` shape:
-    *
-    *  - **`file:` URI** → `update([uri], [])`. Routes through
-    *    `LangiumDocuments.invalidateDocument` (doc stays in the trie) and
-    *    `LangiumDocumentFactory.update`, which consults the LSP-tracked
-    *    open-documents map first. That map is cleared LATER in the same
-    *    synchronous `notifyDidCloseTextDocument` call that fires this event,
-    *    and {@link dispatch} defers the build behind `workspaceManager.ready`
-    *    — so by the time the factory looks, the URI is gone: it falls back to
-    *    `FileSystemProvider.readFile` and the doc rebuilds from disk,
-    *    Langium's canonical close-without-save semantic. A dispatch made
-    *    synchronously here would still see the open document and re-read the
-    *    in-memory text instead.
-    *  - **non-`file:` URI** (`builtin:`, `untitled:`) → no dispatch.
-    *    Adopter-loaded schemes — documents pulled in via
-    *    `loadAdditionalDocuments` — need to stay in the workspace index;
-    *    dropping them on close would break every cross-reference that
-    *    targets them. The framework cannot enumerate adopter schemes, so the
-    *    safe default is "leave alone unless it's a file." Adopters that need
-    *    ephemeral-URI cleanup handle it explicitly.
-    *
-    * Per-client closes (where other clients still hold the URI) are
-    * suppressed via {@link HydraniumTextDocuments.isOpenInAnyClient}.
-    */
-   didCloseDocument(change: TextDocumentChangeEvent<TextDocument>): void {
-      if (this.textDocuments.isOpenInAnyClient(change.document.uri)) {
-         return;
-      }
-      const uri = URI.parse(change.document.uri);
-      if (uri.scheme !== 'file') {
-         return;
-      }
-      this.nextReason = HYDRANIUM_BUILD_REASONS.didClose;
-      this.immediateFlush = true;
-      this.fireDocumentUpdate([uri], []);
-   }
-
    override didChangeWatchedFiles(params: DidChangeWatchedFilesParams): void {
       void this.filterSelfSaves(params)
          .then(filtered => {
             if (filtered.changes.length === 0) {
                return;
             }
+            // Only an open document keeps the file's text as its disk
+            // baseline; the store ignores the rest. The self-save filter has
+            // dropped the server's own writes, which set the baseline when
+            // they wrote.
+            for (const change of filtered.changes) {
+               this.textDocuments
+                  .reloadDiskBaseline(change.uri)
+                  .catch((err: unknown) =>
+                     this.logger.error(`Disk baseline not reloaded for ${change.uri}. ${describeErrorWithStack(err)}`)
+                  );
+            }
             // External file-system changes are authoritative — overwrite any
             // pending reason (typically empty here; could be `didChangeContent`
             // if a watcher event raced an in-flight Monaco edit, in which case
@@ -235,12 +248,81 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             // `unhandledRejection` listener, which reports neither the URIs nor
             // the fact that a watched-file rebuild was dropped — leaving the
             // workspace diverged from disk with no diagnostic and no retry.
-            const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+            const detail = describeErrorWithStack(err);
             const uris = params.changes.map(change => change.uri).join(', ');
             this.logger.error(`Watched-file update dropped for ${uris}. ${detail}`);
          });
    }
 
+   /**
+    * Answer an editor's `willSaveWaitUntil` with no edits once the server's
+    * disk writes of the document already queued have landed, or after
+    * {@link willSaveGateMs}, whichever is first. From the moment the queue
+    * reaches this save, disk tasks of the document queued behind it wait for
+    * the editor's `didSave`, reported through
+    * `HydraniumTextDocuments.onDidSaveInLanguageClient`, or for
+    * {@link willSaveGateMs} more.
+    *
+    * The hold is a disk task that waits only for that signal or its timer:
+    * waiting on a build, a save or anything else queued for the document would
+    * wedge its queue. Resolves in every case, since a failed request counts
+    * against the listener in VS Code; Langium drops the request's cancellation,
+    * so an abandoned request still runs to the cap. A hold that runs out is
+    * logged at debug only: an editor skips `didSave` for a save it cancels or
+    * that changed nothing.
+    */
+   willSaveDocumentWaitUntil(event: TextDocumentWillSaveEvent<TextDocument>): Promise<TextEdit[]> {
+      const uri = event.document.uri;
+      this.editorSaves.get(uri)?.();
+      const hold = new Deferred();
+      const release = (): void => {
+         if (this.editorSaves.get(uri) === release) {
+            this.editorSaves.delete(uri);
+         }
+         hold.resolve();
+      };
+      this.editorSaves.set(uri, release);
+      return new Promise<TextEdit[]>(resolve => {
+         const clock = this.services.Clock;
+         const cap = clock.setTimer(() => {
+            this.logger.warn(
+               `willSaveWaitUntil for ${uri} answered after ${this.willSaveGateMs} ms with server writes of it still queued; the editor's save may race them.`
+            );
+            resolve([]);
+         }, this.willSaveGateMs);
+         try {
+            void this.services.workspace.FileSystemTaskQueue.enqueue(uri, async () => {
+               cap.dispose();
+               resolve([]);
+               if ((await clock.raceTimer(hold.promise, this.willSaveGateMs)) === TIMED_OUT) {
+                  this.logger.debug(
+                     `No didSave for ${uri} within ${this.willSaveGateMs} ms; server writes of it no longer wait for the editor's save.`
+                  );
+                  release();
+               }
+            });
+         } catch (err) {
+            cap.dispose();
+            this.logger.error(`willSaveWaitUntil for ${uri} answered without waiting. ${describeErrorWithStack(err)}`);
+            release();
+            resolve([]);
+         }
+      });
+   }
+
+   /**
+    * Present so that Langium advertises `save` and editors send `didSave`;
+    * without it every hold of {@link willSaveDocumentWaitUntil} waits out its
+    * cap. The hold is released on
+    * `HydraniumTextDocuments.onDidSaveInLanguageClient` instead: it fires as
+    * soon as the editor reports the save, while `onDidSave`, and so this
+    * method, follows only once the file has been read back, and not at all
+    * when the file does not hold the store's text.
+    */
+   didSaveDocument(_event: TextDocumentChangeEvent<TextDocument>): void {
+      // Nothing to do; see the doc comment.
+   }
+
    /**
     * Drop watched-file changes whose path + mtime match a recent self-save
     * record. Deletions always pass (no mtime); stat failures pass (the
@@ -257,7 +339,7 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             }
             const uri = UriUtils.toUri(change.uri);
             const mtimeMs = await this.fileSystemProvider.mtimeMs?.(uri);
-            if (mtimeMs !== undefined && this.selfSaveRegistry.matches(uri.fsPath, mtimeMs)) {
+            if (mtimeMs !== undefined && this.selfSaveRegistry.isRegistered(uri.fsPath, mtimeMs)) {
                return undefined;
             }
             return change;
@@ -271,15 +353,13 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
     * flush immediately (`immediateFlush` or `debounceMs <= 0`) or restart
     * the trailing-edge timer. Subclasses that need to stamp per-build
     * metadata can override and inspect the merged sets — but the canonical
-    * override point for the workspace-lock callback is {@link dispatch},
-    * not this method.
+    * override point for the build is {@link dispatch}, not this method.
     */
    protected override fireDocumentUpdate(changed: URI[], deleted: URI[]): void {
       // Capture the reason set by the LSP event handler immediately before
-      // we merge into the pending sets. `?? pendingReason` keeps the
-      // first reason in a coalesced burst (LSP events arriving inside an
-      // active debounce window all stamp the same `pendingReason` once,
-      // because subsequent stamps see the field already non-undefined).
+      // we merge into the pending sets. Each event stamps its own reason, so
+      // a coalesced burst carries its latest; `?? pendingReason` keeps the
+      // earlier one only for a call no event stamped.
       this.pendingReason = this.nextReason ?? this.pendingReason;
       this.nextReason = undefined;
       for (const uri of changed) {
@@ -317,28 +397,35 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
    }
 
    /**
-    * Workspace-lock + `documentBuilder.update` call for the merged sets.
-    * Mirrors Langium's `super.fireDocumentUpdate` body plus
-    * `markNextReason(pendingReason)` inside the write-lock callback, so the
-    * build the lock is about to run carries the LSP event that triggered it.
-    * Adopters override to stamp additional per-build metadata — the canonical
-    * pattern is to read the reason via `this.pendingReason`, call
-    * `super.dispatch(...)` or replicate the
-    * `workspaceManager.ready -> workspaceLock.write` block, and add
-    * adopter-specific behaviour inside the write callback.
+    * Build the merged sets once the workspace is ready, through
+    * {@link HydraniumDocumentBuilder.scheduleUpdate} with the pending reason,
+    * so the build carries the LSP event that triggered it. A session's write
+    * fires the store's change event before the session rebuilds the document
+    * itself, and the scheduled build is what the two share.
+    *
+    * Adopters override to stamp additional per-build metadata: read the reason
+    * via `this.pendingReason` and call `super.dispatch(...)`; the build may
+    * be shared with other requests, so metadata stamped for it describes
+    * theirs too. An override that needs code inside the write action takes
+    * `workspaceLock.write` itself, as Langium's `fireDocumentUpdate` does, and
+    * stages the reason through `markNextReason` there; its build then cancels
+    * a scheduled one it coincides with rather than sharing it.
     */
    protected dispatch(changed: URI[], deleted: URI[]): void {
       const reason = this.pendingReason;
       this.pendingReason = undefined;
       this.workspaceManager.ready
-         .then(() =>
-            this.workspaceLock.write(token => {
-               this.documentBuilder.markNextReason(reason);
-               return this.documentBuilder.update(changed, deleted, token);
-            })
-         )
+         .then(() => this.documentBuilder.scheduleUpdate(changed, deleted, reason))
          .catch(err => {
-            const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+            // A deferred rebuild can finish after the LSP peer has gone away.
+            // Unless the head was started through `startLanguageServer`, whose
+            // guard absorbs it, the diagnostics publish then fails this build:
+            // a routine teardown race, not a failed workspace update. Keep
+            // genuine update failures visible.
+            if (isConnectionGoneError(err)) {
+               return;
+            }
+            const detail = describeErrorWithStack(err);
             this.logger.error(`Workspace initialization failed. Could not perform document update. ${detail}`);
          });
    }

package/src/lsp/index.ts

@@ -8,7 +8,9 @@
  ********************************************************************************/
 
 export * from './completion/hydranium-completion-provider.js';
-export * from './instrument-connection.js';
+export * from './lsp-latency.js';
+export * from './connection-features.js';
+export * from './diagnostics-connection.js';
 export * from './semantic-token-provider.js';
 export * from './language-module.js';
 export * from './shared-module.js';

package/src/lsp/lsp-latency.ts

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import type { LatencyCollector } from '@hydranium/protocol';
+import type { ConnectionOptions, Message } from 'vscode-jsonrpc';
+
+/**
+ * Connection options that time every inbound LSP message into `latency` under
+ * its method name — the LSP analog of the data-server RPC chokepoint.
+ *
+ * Pass the result to `createConnection` where the head builds its connection:
+ * `createConnection(ProposedFeatures.all, lspLatencyOptions(latency))`. The
+ * transport is untouched, so a head keeps whatever `--stdio` / `--socket`
+ * selection its arguments make.
+ *
+ * **`messageStrategy` is the seam because it is the only one the handlers
+ * actually pass through.** `vscode-languageserver` builds its `Connection` as an
+ * object whose `onHover`, `onCompletion` and every other named helper register
+ * against the inner protocol connection captured in their closure — not against
+ * the returned object's own `onRequest`. Langium registers exclusively through
+ * those helpers, so decorating the `Connection` reaches none of them and reports
+ * an empty LSP half no matter how much traffic ran. `handleMessage` sits on the
+ * dispatch path itself, which every request and notification crosses, so it also
+ * catches `initialize` — special-cased into `onInitialize` and invisible to any
+ * `onRequest` decoration.
+ *
+ * What it measures is **dispatch plus handler**, not handler alone: the wait a
+ * client actually experiences, including time queued behind other work.
+ *
+ * When `latency` is `undefined` the seam is off and this returns `undefined`, so
+ * a head can pass the result of an env-gated factory (`latencyFromEnv()`)
+ * straight through and pay nothing when timing is not enabled.
+ */
+export function lspLatencyOptions(latency: LatencyCollector | undefined): ConnectionOptions | undefined {
+   if (!latency) {
+      return undefined;
+   }
+   return {
+      messageStrategy: {
+         handleMessage: (message: Message, next: (message: Message) => void | Promise<void>) => {
+            // Responses to requests the SERVER sent carry no method and are not
+            // work this head performed; timing them would report the client's
+            // latency under a name this collector cannot supply.
+            if (!hasMethod(message)) {
+               return next(message);
+            }
+            return latency.time(message.method, () => next(message));
+         }
+      }
+   };
+}
+
+/** Narrow to the messages that name an operation — requests and notifications. */
+function hasMethod(message: Message): message is Message & { method: string } {
+   return typeof (message as { method?: unknown }).method === 'string';
+}

package/src/lsp/semantic-token-provider.ts

@@ -14,7 +14,9 @@ import {
    CstUtils,
    GrammarAST,
    interruptAndCheck,
+   isLeafCstNode,
    type LangiumDocument,
+   type LeafCstNode,
    type ReferenceInfo
 } from '@hydranium/langium';
 import { AbstractSemanticTokenProvider, type SemanticTokenAcceptor } from '@hydranium/langium/lsp';
@@ -54,6 +56,23 @@ export interface HydraniumSemanticTokenProviderOptions {
     * render in the editor's default foreground.
     */
    readonly highlightKeywords?: boolean;
+
+   /**
+    * Also emit a `comment` token for every comment leaf of the CST.
+    *
+    * OFF by default for the same reason as {@link highlightKeywords}, and the
+    * loss is larger: a TextMate grammar distinguishes `comment.line` from
+    * `comment.block` and scopes the delimiters separately, where a semantic
+    * token carries one flat `comment` that overrides all of them. It exists
+    * for the host that ships no client-side grammar, where a comment otherwise
+    * renders in the editor's default foreground.
+    *
+    * What counts as a comment is every hidden terminal the lexer retains,
+    * which is every hidden terminal whose pattern is not whitespace. A grammar
+    * whose hidden non-whitespace terminal means something other than a comment
+    * is miscoloured, and this option is the place to say no.
+    */
+   readonly highlightComments?: boolean;
 }
 
 /**
@@ -133,7 +152,9 @@ export abstract class AbstractHydraniumSemanticTokenProvider extends AbstractSem
       cancelToken: CancellationToken
    ): Promise<void> {
       await super.computeHighlighting(document, acceptor, cancelToken);
-      if (this.options.highlightKeywords !== true) {
+      const keywords = this.options.highlightKeywords === true;
+      const comments = this.options.highlightComments === true;
+      if (!keywords && !comments) {
          return;
       }
       const root = document.parseResult.value.$cstNode;
@@ -142,14 +163,60 @@ export abstract class AbstractHydraniumSemanticTokenProvider extends AbstractSem
       }
       for (const cst of CstUtils.streamCst(root)) {
          await interruptAndCheck(cancelToken);
-         // The grammar source is the whole filter. A keyword is always a leaf,
-         // and the hidden leaves a comment or a run of whitespace contributes
-         // are sourced from a terminal rule rather than a `Keyword` — so
-         // neither a composite-node check nor a hidden-token check adds
-         // anything here.
-         if (GrammarAST.isKeyword(cst.grammarSource)) {
+         // A keyword is always a leaf with a `Keyword` grammar source, so that
+         // check alone separates it from everything else in the walk.
+         if (keywords && GrammarAST.isKeyword(cst.grammarSource)) {
             acceptor({ cst, type: SemanticTokenTypes.keyword });
          }
+         // A comment leaf cannot be recognised the same way — the CST builder
+         // adds hidden nodes from the token alone, so `grammarSource` is
+         // undefined, which is also why the keyword filter never matches one.
+         //
+         // `hidden` alone IS the comment test, and nothing narrower is needed:
+         // the token builder groups a hidden terminal as `Lexer.SKIPPED` when
+         // its pattern matches whitespace and as `hidden` otherwise, so the
+         // lexer discards whitespace before a CST node is ever built and every
+         // hidden leaf that survives is a comment. Classifying the terminal
+         // again here would be a second guard for the same property, which no
+         // test could then distinguish. An adopter whose token builder RETAINS
+         // whitespace breaks that equivalence and would colour its gaps.
+         if (comments && isLeafCstNode(cst) && cst.hidden) {
+            this.acceptComment(cst, acceptor);
+         }
+      }
+   }
+
+   /**
+    * Emit a comment as ONE TOKEN PER LINE, never as one multi-line range.
+    *
+    * A block comment is the first token this provider emits that can span
+    * lines, and the upstream encoder mishandles that for a client which does
+    * not advertise `multilineTokenSupport` — the split path computes the first
+    * line's length as `nextLineOffset - range.start.character - 1`, subtracting
+    * a COLUMN from a document OFFSET, so the length is right only for a token
+    * starting on line 0 and overruns its line everywhere else. No client in
+    * this repository advertises that capability, so the broken path is the one
+    * taken. Splitting here means every range handed over starts and ends on one
+    * line and the arithmetic is never reached.
+    *
+    * Lines come from the leaf's own text rather than from the document, so
+    * nothing has to re-derive where the comment ends.
+    */
+   protected acceptComment(cst: LeafCstNode, acceptor: SemanticTokenAcceptor): void {
+      const lines = cst.text.split('\n');
+      for (let index = 0; index < lines.length; index++) {
+         // A `\r\n` document leaves the carriage return on the line's end;
+         // colouring it would extend the token past the visible text.
+         const length = lines[index].replace(/\r$/, '').length;
+         const character = index === 0 ? cst.range.start.character : 0;
+         if (length === 0) {
+            continue;
+         }
+         const line = cst.range.start.line + index;
+         acceptor({
+            range: { start: { line, character }, end: { line, character: character + length } },
+            type: SemanticTokenTypes.comment
+         });
       }
    }
 

package/src/lsp/shared-module.ts

@@ -28,14 +28,10 @@ import { HydraniumDocumentUpdateHandler } from './hydranium-document-update-hand
  *   (an output channel, a structured logger) override the slot after this
  *   module.
  *
- * - {@link HydraniumDocumentUpdateHandler} wraps `didChangeWatchedFiles` to
- *   suppress echo events for the server's own writes via the shared
- *   `SelfSaveRegistry` slot, debounces `didChangeContent`, stamps build
- *   reasons through `markNextReason`, and dispatches a rebuild when the last
- *   client closes a document.
- *   Adopters with their own update-handler subclass should extend
- *   `HydraniumDocumentUpdateHandler` (not Langium's
- *   `DefaultDocumentUpdateHandler`) to preserve those behaviours.
+ * - {@link HydraniumDocumentUpdateHandler} carries the framework's handling of
+ *   the LSP document events. Adopters with their own update-handler subclass
+ *   should extend it (not Langium's `DefaultDocumentUpdateHandler`) to keep
+ *   that handling.
  *
  * **Why this is a shared slot and not a per-language one.** Langium declares
  * `DocumentUpdateHandler` in `LangiumSharedLSPServices` — there is exactly one