@hydranium/core 1.0.0-next.16 → 1.0.0-next.168

package/src/langium/workspace/initialize-workspace.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { UriUtils, URI } from '@hydranium/langium';
+import type { Locale } from '@hydranium/protocol';
 // Bare `'path'` (not `node:path`) so a browser bundle can alias it to a POSIX
 // shim — this is the only filesystem-path use left on the portable `.` entry,
 // and it's the headless/CLI string-input convenience of `toWorkspaceFolders`.
@@ -18,6 +19,33 @@ import type { ServerSharedServicesMinimal } from '../shared-services.js';
 /** A workspace folder root accepted by the headless init seams: a filesystem path or a {@link URI}. */
 export type WorkspaceFolderInput = string | URI;
 
+/**
+ * Options for the headless init seams.
+ *
+ * **Optional, and the parameter is optional too**, so that no existing caller
+ * has to change to gain a field it does not set.
+ */
+export interface ProgrammaticInitOptions {
+   /**
+    * The locale to render user-facing server messages in — the headless
+    * equivalent of LSP `initialize`'s `locale`, for a head with no LSP
+    * connection (`startStdioServer`, the CLI subcommands, a test harness).
+    *
+    * Omitted means no locale, which the default renderer resolves as the
+    * framework's English. That is the correct answer for a headless tool: it
+    * has no reading user to have a language.
+    *
+    * **An IETF language tag, hyphenated — `de`, `de-CH`, `zh-Hant-TW` — and
+    * not the POSIX or Java spelling.** An LSP client is held to that syntax by
+    * the protocol, while a headless caller supplies the string itself and the
+    * obvious source is an environment variable holding `de_DE` or
+    * `en_US.UTF-8`. Neither is a tag, and the string is passed through
+    * unchecked, so a renderer that parses it finds nothing to match and every
+    * message renders in English.
+    */
+   readonly locale?: Locale;
+}
+
 /**
  * Normalize the seam's flexible folder argument to LSP {@link WorkspaceFolder}s.
  * A `string` is resolved to an absolute filesystem path and wrapped as a
@@ -58,17 +86,25 @@ function toWorkspaceFolders(folders: WorkspaceFolderInput | ReadonlyArray<Worksp
  *
  * @param services the shared services tree the workspace manager lives on
  * @param folders one or more workspace roots (filesystem paths or URIs)
+ * @param options the message locale, when the caller has one
  */
 export async function initializeWorkspaceProgrammatically(
    services: ServerSharedServicesMinimal,
-   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>,
+   options: ProgrammaticInitOptions = {}
 ): Promise<void> {
    const workspaceFolders = toWorkspaceFolders(folders);
    const manager = services.workspace.WorkspaceManager;
-   // `initialize` records the folders (DefaultWorkspaceManager reads only this
+   // `locale` goes through the synthesized params rather than a direct
+   // `acceptLocale` call, so this seam and a real LSP `initialize` reach the
+   // slot by the SAME path — an adopter overriding the capture in
+   // `HydraniumWorkspaceManager.initialize` is honoured headlessly too, which a
+   // second write site here would silently bypass.
+   //
+   // `initialize` records the folders (DefaultWorkspaceManager reads only that
    // field); `initialized` runs `mutex.write(initializeWorkspace)` and resolves
    // once discovery + the init build settle, so awaiting it is the ready gate.
-   manager.initialize({ workspaceFolders } as InitializeParams);
+   manager.initialize({ workspaceFolders, locale: options.locale } as InitializeParams);
    await manager.initialized({} as InitializedParams);
 }
 
@@ -91,12 +127,14 @@ export async function initializeWorkspaceProgrammatically(
  *
  * @param services the shared services tree the workspace manager lives on
  * @param folders one or more workspace roots (filesystem paths or URIs)
+ * @param options the message locale, when the caller has one
  */
 export async function buildWorkspaceProgrammatically(
    services: ServerSharedServicesMinimal,
-   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>,
+   options: ProgrammaticInitOptions = {}
 ): Promise<void> {
-   await initializeWorkspaceProgrammatically(services, folders);
+   await initializeWorkspaceProgrammatically(services, folders, options);
    const documents = services.workspace.LangiumDocuments.all.toArray();
    await services.workspace.DocumentBuilder.build(documents, { validation: true });
 }

package/src/langium/workspace/langium-documents.ts

@@ -7,14 +7,49 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Tracer } from '@hydranium/protocol';
-import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type LangiumDocuments, type URI, UriUtils } from '@hydranium/langium';
+import { defineMessage } from '@hydranium/protocol';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type DocumentUriPolicy } from './document-uri-policy.js';
+import { type HydraniumLangiumDocumentFactory } from './hydranium-langium-document-factory.js';
 
 /**
- * Default `LangiumDocuments` for `@hydranium/core` consumers. Layers two
- * extensions on top of Langium's {@link DefaultLangiumDocuments}:
+ * The document a caller asked to load is not there.
+ *
+ * User-facing, and the Node host's spelling of it: `loadUri` returns `undefined`
+ * exactly when the URI policy's `realpath` reports the path absent. A host whose
+ * provider has no `realpath` never reaches this — the miss surfaces from the
+ * provider instead, so the same condition has one declaration per host.
+ */
+export const NO_LOADABLE_CONTENT = defineMessage('hydranium/core/no-loadable-content', 'No loadable content for {uri}');
+
+/**
+ * A stand-in was asked for at a URI that routes to no grammar, and no language
+ * id was given to route it instead.
+ *
+ * User-facing, and raised BEFORE the parse: left to Langium's ladder the same
+ * condition surfaces as `no services for the extension ''`, which names neither
+ * the URI nor the argument that would have answered.
+ */
+export const NO_LANGUAGE_FOR_STAND_IN = defineMessage(
+   'hydranium/core/no-language-for-stand-in',
+   'No grammar routes {uri}; pass a languageId to say which one the stand-in should parse with'
+);
+
+/**
+ * The registry surface the framework adds on top of Langium's
+ * {@link LangiumDocuments}. Declared separately from the implementing class so
+ * the shared-services slot can narrow to it: the class takes the services tree
+ * as its constructor parameter, so naming the CLASS there would make that type
+ * depend on itself.
+ */
+export interface HydraniumDocumentRegistry extends LangiumDocuments {
+   createEmptyDocument(uri: URI, languageId?: string): LangiumDocument<AstNode>;
+}
+
+/**
+ * Default `LangiumDocuments` for `@hydranium/core` consumers, extending
+ * Langium's {@link DefaultLangiumDocuments} with:
  *
  * 1. **Identity via the {@link DocumentUriPolicy} seam.**
  *    `getOrCreateDocument` resolves the requested URI through the seam — the
@@ -24,31 +59,78 @@ import { type DocumentUriPolicy } from './document-uri-policy.js';
  *    `LangiumDocuments` override. The default resolves to the URI unchanged
  *    (`DefaultDocumentUriPolicy`), matching Langium's own keying.
  *
- * 2. **`createEmptyDocument(uri)` — synchronous** factory for a transient
- *    document with no loadable on-disk content. `getOrCreateDocument` falls
- *    back to it when the seam reports no loadable URI, or when `super` cannot
- *    load it, so callers always receive a document. Abstract because the
- *    parse-result root is grammar-specific (each grammar returns its own
- *    root node type). The fallback document is deliberately
- *    **not** registered: a transient placeholder must not mask the real
- *    document once it appears.
+ * 2. **A load that finds nothing rejects**, rather than answering with a
+ *    transient empty document. An empty AST validates clean, so a placeholder
+ *    hands the caller something that silently is not the file, and a caller
+ *    that wants a document for a URI with no content on disk cannot use one
+ *    anyway: it is unregistered, so no build, index or save can see it, and
+ *    `LangiumDocumentFactory.update` reads from disk. Content that legitimately
+ *    lives outside the filesystem belongs in a virtual document, which carries
+ *    real source text.
  */
-export abstract class AbstractHydraniumLangiumDocuments extends DefaultLangiumDocuments {
+export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implements HydraniumDocumentRegistry {
    /** Document-identity seam, shared with the text store, event filters, and builder. */
    protected readonly uriPolicy: DocumentUriPolicy;
-   protected readonly tracer: Tracer;
+
+   /**
+    * Narrows the inherited Langium factory field to the framework's, so the
+    * language-explicit `fromStringInLanguage` below needs no cast. The
+    * framework's shared module binds that class.
+    */
+   declare protected readonly langiumDocumentFactory: HydraniumLangiumDocumentFactory;
 
    constructor(protected override readonly services: ServerSharedServicesMinimal) {
       super(services);
       this.uriPolicy = services.workspace.DocumentUriPolicy;
-      this.tracer = services.Tracer.for('LangiumDocuments');
    }
 
    /**
-    * Build a transient empty document for `uri`. Implemented by consumers
-    * because the parse-result root is grammar-specific.
+    * Build a transient document for `uri` by parsing empty text with the
+    * grammar `languageId` names, or the one `uri` routes to when it is
+    * omitted, so the root is that language's entry type with every containment
+    * list initialised.
+    *
+    * For callers that need a document at a URI with no content on disk — the
+    * scope provider querying before a file exists is the case it was added for.
+    * `getOrCreateDocument` deliberately does NOT fall back to this: fabricating
+    * a document behind a caller that asked to LOAD one hands back something
+    * that silently is not the file, whereas calling this is a caller saying it
+    * wants a stand-in.
+    *
+    * **Pass `languageId` whenever the URI names no file.** The create-element
+    * flow this exists for asks at the DIRECTORY a file is about to be written
+    * into, and a directory URI has no extension for the routing ladder to end
+    * on — so omitting the id there fails inside the parse, on an empty
+    * extension rather than on the URI. A caller in that position always knows
+    * its language: {@link HydraniumScopeProvider} is bound per grammar, and a
+    * request that names no document at all still carries the AST type
+    * `ExtendedServiceRegistry.soleServicesByType` routes on.
+    *
+    * The result is not registered, so nothing downstream can see it, and
+    * `LangiumDocumentFactory.update` would read from disk. It is a probe, not a
+    * document under construction; content that must survive belongs in a
+    * virtual document, which carries real source text.
+    *
+    * Building the root by hand instead needs the entry type name and a cast
+    * past the generated types, and leaves those lists `undefined`. A grammar
+    * whose entry rule opens with mandatory syntax yields a parse error here,
+    * and it is kept: `AstReflection.isComplete` is `false` for such a root
+    * however it is built, so the error states the same thing.
     */
-   abstract createEmptyDocument(uri: URI): LangiumDocument<AstNode>;
+   createEmptyDocument(uri: URI, languageId?: string): LangiumDocument<AstNode> {
+      if (languageId !== undefined) {
+         return this.langiumDocumentFactory.fromStringInLanguage('', uri, languageId);
+      }
+      if (!this.services.ServiceRegistry.getServicesFor(uri)) {
+         // Reported here rather than left to the parse, which ends on the empty
+         // extension and so names neither the URI nor the id that would have
+         // answered.
+         throw new Error(NO_LANGUAGE_FOR_STAND_IN.format({ uri: uri.toString() }));
+      }
+      // The two-argument overload is synchronous; passing a cancellation token
+      // selects the promise-returning one, which this contract cannot await.
+      return this.langiumDocumentFactory.fromString('', uri);
+   }
 
    override async getOrCreateDocument(uri: URI): Promise<LangiumDocument<AstNode>> {
       const resolved = this.uriPolicy.loadUri(uri);
@@ -68,27 +150,25 @@ export abstract class AbstractHydraniumLangiumDocuments extends DefaultLangiumDo
             return await super.getOrCreateDocument(resolved);
          } catch (error: unknown) {
             // Load lost a race with a concurrent create — return that document.
+            // Checked before propagating, so a race is not reported as a
+            // missing file; cancellation carries no document and falls through.
             const reentrant = this.getDocument(resolved);
             if (reentrant) {
                this.services.workspace.CstResidencyService.rehydrate(reentrant);
                return reentrant;
             }
-            // No concurrent document, so the load genuinely failed. The fallback
-            // below still runs, because the file-not-found case is the ordinary
-            // one here and no provider-independent way to recognise it exists:
-            // Node's provider throws `ENOENT`, the in-memory one a bare `Error`,
-            // and the provider is a seam an adopter rebinds. Discriminating on
-            // message text across that seam would be a worse defect than the
-            // one it fixes. So the failure is TRACED rather than propagated —
-            // an unreadable-but-present file still degrades to an empty
-            // document, but it stops doing so silently.
-            this.tracer
-               .with(resolved.toString())
-               .debug(`Load failed, falling back to an empty document: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
          }
       }
-      // No loadable content (missing / synthetic / not yet written): a transient
-      // empty placeholder keyed canonically — not registered (see the class doc).
-      return this.createEmptyDocument(resolved ?? uri);
+      // No file, but possibly a document: one created and not yet saved is
+      // built from its text and registered under its canonical URI.
+      const created = this.getDocument(UriUtils.toUri(this.uriPolicy.canonicalUri(uri)));
+      if (created) {
+         this.services.workspace.CstResidencyService.rehydrate(created);
+         return created;
+      }
+      // The seam reports no loadable content, so there is nothing to read and
+      // no error from a read to carry.
+      throw new Error(NO_LOADABLE_CONTENT.format({ uri: uri.toString() }));
    }
 }

package/src/langium/workspace/persistent-file-system-provider.ts

@@ -125,13 +125,6 @@ export interface PersistentFileSystemOptions extends InMemoryFileSystemOptions {
  * restored as deleted, which is why the marker is NUL-wrapped and text a grammar
  * can parse is not.
  *
- * # A registered virtual document still wins
- *
- * `readFileSync` consults the virtual-document seam before the map, so a stdlib
- * contributed in code keeps answering for its URI whether or not the store holds
- * one. The store cannot shadow it, which is what keeps a rebuild that re-reads
- * that URI from losing the stdlib.
- *
  * # What it deliberately does not answer
  *
  * The store is scoped to the ORIGIN, not to the page: two pages on the same

package/src/langium/workspace/virtual-document.ts

@@ -7,15 +7,20 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { URI } from '@hydranium/langium';
+import { type FileSystemNode, URI } from '@hydranium/langium';
+import { type Tracer } from '@hydranium/protocol';
+import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
+import { NO_SUCH_FILE, NO_SUCH_PATH, UNSUPPORTED_WRITE } from './in-memory-file-system-provider.js';
+import { notFound } from './file-not-found.js';
 
 /**
  * URI scheme for virtual documents — LangiumDocuments that have no backing
  * file on disk (a language's stdlib, library types, built-in definitions,
  * mirrors, generated views). Chosen so it cannot collide with on-disk `file:`
- * URIs, and so the framework's FileSystemProvider can recognise and serve them
- * on re-read (see {@link serveVirtualDocument}).
+ * URIs, and so the framework can serve them on re-read through its own
+ * provider for the scheme (see {@link VirtualFileSystemProvider}).
  */
 export const VIRTUAL_SCHEME = 'virtual';
 
@@ -72,23 +77,95 @@ export function isVirtualUri(uri: URI | string): boolean {
 }
 
 /**
- * Serve the text of a registered virtual document, or `undefined` when `uri`
- * is not virtual or no document is registered for it (so a FileSystemProvider
- * delegates to its real backing).
+ * The file system provider for the {@link VIRTUAL_SCHEME} scheme, registered by
+ * the framework in the shared `fileSystemProviders` group so every host serves
+ * `virtual:` whatever provider it binds for its own files.
  *
- * The framework's FileSystemProvider defaults call this at the top of
- * `readFile` / `readFileSync` so a virtual document survives a re-read:
- * `DocumentBuilder.update` / `LangiumDocumentFactory.update` re-read a changed
- * URI from the FileSystemProvider, and nothing on disk backs a virtual URI. The
- * text comes from the registered document — the original source for a
- * `fromString` document, or the serialized form retained by the framework's
- * `fromModel` (which fills in the text Langium leaves empty). No serializer is
- * consulted here; the text is already on the document.
+ * A virtual document has no backing outside the index, and a re-read still has
+ * to find it: `DocumentBuilder.update` and `LangiumDocumentFactory.update`
+ * re-read a changed URI from the provider, and the last close rebuilds a
+ * released document the provider says `exists`. So the text comes from the
+ * document `LangiumDocuments` holds — the original source for a `fromString`
+ * document, or the serialized form the framework's `fromModel` retains. An
+ * edited one answers with its edited text.
+ *
+ * **Every read method agrees.** Serving only the text methods would leave one
+ * provider answering "here is the content" and "nothing is there" about one
+ * URI, so a caller could not probe before reading. A registered document is
+ * always a FILE with no children: a workspace walk handed a directory would try
+ * to enumerate children it has none of.
+ *
+ * Read-only: a write is refused, since nothing backs the scheme.
  */
-export function serveVirtualDocument(services: ServerSharedServicesMinimal, uri: URI): string | undefined {
-   if (!isVirtualUri(uri)) {
-      return undefined;
+export class VirtualFileSystemProvider implements WritableFileSystemProvider {
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerSharedServicesMinimal,
+      options: LogNameOptions = {}
+   ) {
+      this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+   }
+
+   async writeFile(uri: URI, _content: string): Promise<void> {
+      throw new Error(UNSUPPORTED_WRITE.format({ uri: uri.toString() }));
+   }
+
+   async readFile(uri: URI): Promise<string> {
+      return this.readFileSync(uri);
+   }
+
+   readFileSync(uri: URI): string {
+      const text = this.text(uri);
+      if (text === undefined) {
+         throw notFound(NO_SUCH_FILE.format({ uri: uri.toString() }), uri);
+      }
+      return text;
+   }
+
+   async readBinary(uri: URI): Promise<Uint8Array> {
+      return this.readBinarySync(uri);
+   }
+
+   readBinarySync(uri: URI): Uint8Array {
+      return new TextEncoder().encode(this.readFileSync(uri));
+   }
+
+   async stat(uri: URI): Promise<FileSystemNode> {
+      return this.statSync(uri);
+   }
+
+   statSync(uri: URI): FileSystemNode {
+      if (this.text(uri) === undefined) {
+         throw notFound(NO_SUCH_PATH.format({ uri: uri.toString() }), uri);
+      }
+      return { isFile: true, isDirectory: false, uri };
+   }
+
+   async exists(uri: URI): Promise<boolean> {
+      return this.existsSync(uri);
+   }
+
+   existsSync(uri: URI): boolean {
+      return this.text(uri) !== undefined;
+   }
+
+   async readDirectory(_uri: URI): Promise<FileSystemNode[]> {
+      return [];
+   }
+
+   readDirectorySync(_uri: URI): FileSystemNode[] {
+      return [];
+   }
+
+   /**
+    * Text of the document registered at `uri`, if there is one.
+    *
+    * `LangiumDocuments` is resolved per call, not in the constructor: it reaches
+    * this provider back through the document factory, so resolving it eagerly
+    * is a construction cycle.
+    */
+   protected text(uri: URI): string | undefined {
+      return this.services.workspace.LangiumDocuments.getDocument(uri)?.textDocument.getText();
    }
-   const document = services.workspace.LangiumDocuments.getDocument(uri);
-   return document ? document.textDocument.getText() : undefined;
 }

package/src/langium/workspace/write-lock-scope.ts

@@ -67,13 +67,14 @@ export function isInsideWriteLock(): boolean {
 /**
  * Thrown when the model facade is reached from inside a workspace write-lock
  * holder — typically an integrity rule or build-phase pass writing through
- * `ModelService.update` / `save` / `rebuild` during a build.
+ * a session's `update` / `save` or `ModelService.rebuild` during a build.
  *
  * Named rather than a bare `Error` because the remedy is specific and worth
  * pointing at: either move the write out of the build (integrity rules that
  * persist repairs should write through `FileSystemProvider.writeFile`, which
- * takes no lock), or set `ModelServiceOptions.serializeBuilds: false` to accept
- * unserialised builds in exchange for the reentrancy.
+ * takes no lock), or set `ModelServiceOptions.serializeBuilds: false`, which
+ * keeps the facade's build from cancelling the holder but not its wait from
+ * stalling on a document that needs a re-queue.
  */
 export class ReentrantWriteLockError extends Error {
    constructor(readonly uri: string) {

package/src/locale/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './server-locale.js';

package/src/locale/server-locale.ts

@@ -0,0 +1,86 @@
+/********************************************************************************
+ * 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 { Locale, Tracer } from '@hydranium/protocol';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+
+/** Construction options for {@link ServerLocale}. */
+export type ServerLocaleOptions = LogNameOptions;
+
+/**
+ * The locale contract the `ServerLocale` slot holds, implemented by
+ * {@link DefaultServerLocale}.
+ *
+ * An interface rather than the class, so the slot is compared STRUCTURALLY —
+ * a class-typed slot carries its `protected` members into every assignability
+ * check, compared nominally, which makes it unsatisfiable across two physical
+ * copies of this package and unreplaceable by an adopter's own declaration.
+ */
+export interface ServerLocale {
+   /** The locale, or `undefined` when no init supplied one — the framework's English. */
+   readonly value: Locale | undefined;
+   accept(locale: Locale): void;
+}
+
+/**
+ * The locale the server was handed at init, for whoever needs to render in the
+ * reading user's language. Held apart from the message renderer that reads it,
+ * so replacing the renderer cannot drop locale handling.
+ *
+ * A plain string in and out. A consumer that must react to a change rather than
+ * read the current value wraps this itself — nothing does today, and both real
+ * hosts respawn the server on a display-language switch.
+ */
+export class DefaultServerLocale implements ServerLocale {
+   protected readonly tracer: Tracer;
+   protected current: Locale | undefined;
+
+   constructor(services: ServerSharedServicesMinimal, options: ServerLocaleOptions = {}) {
+      this.tracer = services.Tracer.for(options.logName ?? 'ServerLocale').trace('instantiated');
+   }
+
+   /** The locale, or `undefined` when no init supplied one — which means the framework's English. */
+   get value(): Locale | undefined {
+      return this.current;
+   }
+
+   /**
+    * Take the locale an init declared.
+    *
+    * **One locale per process, and the reason the OTHER heads need none of
+    * their own.** The data and GLSP heads publish a port over the LSP
+    * connection and are reached by forwarding a socket to it, so they are the
+    * same process as the LSP head that was handed this locale — there is no
+    * topology in which one of them serves a second frontend. The Theia backend
+    * is the case that would break it, and it holds no locale precisely because
+    * it serves every frontend at once; nothing there writes here.
+    *
+    * The framework accepts a locale and never sources one, and neither
+    * validates nor normalises the tag: rejecting an unfamiliar one would be
+    * selecting a locale.
+    *
+    * Override to ignore the argument, which is how a host pins a locale it
+    * already knows but has no LSP client to declare.
+    *
+    * **The line is at `info`, which is a deliberate exception to the
+    * per-service default.** A locale is written once per process and it is the
+    * one setting that silently changes every user-facing sentence the server
+    * produces, so a reader trying to explain an unexpected language has nothing
+    * else to look at: the framework ships no catalogue, so "no entry for this
+    * code" and "no locale declared" both render the English and are
+    * indistinguishable in the output. At `debug` the line is below the default
+    * threshold and therefore absent from exactly the log someone would be
+    * reading.
+    */
+   accept(locale: Locale): void {
+      this.current = locale;
+      this.tracer.info(`rendering messages in locale '${locale}'`);
+   }
+}

package/src/lsp/completion/hydranium-completion-provider.ts

@@ -7,9 +7,16 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type AstNodeDescription, type ReferenceInfo, type Stream } from '@hydranium/langium';
+import { type AstNodeDescription, type LangiumDocument, type ReferenceInfo, type Stream } from '@hydranium/langium';
 import { DefaultCompletionProvider, type CompletionContext, type CompletionValueItem } from '@hydranium/langium/lsp';
-import type { CompletionItem, InsertReplaceEdit } from 'vscode-languageserver';
+import {
+   CompletionList,
+   type CancellationToken,
+   type CompletionItem,
+   type CompletionParams,
+   type InsertReplaceEdit,
+   type Position
+} from 'vscode-languageserver';
 import { type ReferenceCandidateProvider } from '../../langium/scope/reference-candidate-provider.js';
 import { type ServerLanguageServices } from '../../langium/language-module.js';
 
@@ -52,6 +59,14 @@ import { type ServerLanguageServices } from '../../langium/language-module.js';
  * elements. The provider owns that pipeline in one place, so the
  * text-editor dropdown and the protocol candidate picker stay in sync; this
  * class keeps only the LSP-specific {@link fillCompletionItem} upgrade.
+ *
+ * **A comment is not a completion site.** Langium's context builder reads the
+ * non-hidden token stream alone, so a cursor in a comment is indistinguishable
+ * from one in the whitespace between the tokens surrounding it: the grammar's
+ * follow-set goes out as keyword proposals, and none of them is filtered,
+ * because the characters the user typed belong to the hidden token and the
+ * prefix matched against is therefore empty. {@link isInsideComment} suppresses
+ * the request instead.
  */
 export class HydraniumCompletionProvider extends DefaultCompletionProvider {
    protected readonly candidateProvider: ReferenceCandidateProvider;
@@ -61,6 +76,71 @@ export class HydraniumCompletionProvider extends DefaultCompletionProvider {
       this.candidateProvider = services.references.CandidateProvider;
    }
 
+   /**
+    * Answer no proposals at all when the cursor is inside a comment.
+    *
+    * Suppressing the whole request is what makes the rule hold for every
+    * proposal kind at once. Filtering the built contexts instead has to catch
+    * each context kind the base builds separately, and a kind added upstream
+    * arrives unguarded.
+    *
+    * The list is marked incomplete so the client re-asks on the next keystroke
+    * and proposals resume the moment the cursor leaves the comment.
+    */
+   override async getCompletion(
+      document: LangiumDocument,
+      params: CompletionParams,
+      cancelToken?: CancellationToken
+   ): Promise<CompletionList | undefined> {
+      if (this.isInsideComment(document, params.position)) {
+         return CompletionList.create([], true);
+      }
+      return super.getCompletion(document, params, cancelToken);
+   }
+
+   /**
+    * Whether `position` falls in text a comment terminal claims.
+    *
+    * The two comment kinds part company at their far edge. A single-line
+    * comment runs to the line break, so a cursor at its end offset is still in
+    * prose and that offset counts as inside. A multi-line comment is
+    * terminated, so a cursor at its end offset has passed the terminator and is
+    * back in code. A cursor ON the opening delimiter is outside either way,
+    * that offset being a legal position for whatever token the comment
+    * displaced.
+    *
+    * The hidden token stream decides rather than the CST. A leaf lookup by
+    * offset misses the position a cursor reaches by typing prose into a
+    * trailing comment, because that comment ends AT the line break and
+    * whitespace is discarded before a CST node is built over it — so the
+    * lookup answers nothing exactly where proposals are least wanted.
+    *
+    * An adopter whose comment syntax carries completable content — a
+    * documentation tag naming a type — narrows this to return `false` over that
+    * region rather than replacing {@link getCompletion}.
+    */
+   protected isInsideComment(document: LangiumDocument, position: Position): boolean {
+      const text = document.textDocument.getText();
+      const offset = document.textDocument.offsetAt(position);
+      const multilineCommentRules = this.grammarConfig.multilineCommentRules;
+      for (const token of this.lexer.tokenize(text).hidden) {
+         if (token.startOffset >= offset) {
+            // Hidden tokens arrive in document order, so no later one reaches back over the cursor.
+            return false;
+         }
+         // `endOffset` is optional on the token type and the image is not, so
+         // the width comes from the image and needs no absent-value branch.
+         const endOffset = token.startOffset + token.image.length;
+         if (offset < endOffset) {
+            return true;
+         }
+         if (offset === endOffset && !multilineCommentRules.includes(token.tokenType.name)) {
+            return true;
+         }
+      }
+      return false;
+   }
+
    /**
     * Delegate cross-reference candidate gathering to the candidate provider
     * so the LSP completion dropdown applies the same filter / canonical