@hydranium/core 1.0.0-next.11 → 1.0.0-next.112

package/lib/langium/workspace/langium-documents.d.ts

@@ -6,13 +6,41 @@
  *
  * 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 } from '@hydranium/langium';
 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 declare const NO_LOADABLE_CONTENT: import("@hydranium/protocol").MessageDefinition<"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 declare const NO_LANGUAGE_FOR_STAND_IN: import("@hydranium/protocol").MessageDefinition<"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
@@ -22,26 +50,60 @@ 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 declare abstract class AbstractHydraniumLangiumDocuments extends DefaultLangiumDocuments {
+export declare class HydraniumLangiumDocuments extends DefaultLangiumDocuments implements HydraniumDocumentRegistry {
     protected readonly services: ServerSharedServicesMinimal;
     /** 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.
+     */
+    protected readonly langiumDocumentFactory: HydraniumLangiumDocumentFactory;
     constructor(services: ServerSharedServicesMinimal);
     /**
-     * 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>;
     getOrCreateDocument(uri: URI): Promise<LangiumDocument<AstNode>>;
 }
 //# sourceMappingURL=langium-documents.d.ts.map

package/lib/langium/workspace/langium-documents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"langium-documents.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/langium-documents.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,KAAK,OAAO,EAAE,uBAAuB,EAAE,KAAK,eAAe,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC3G,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8BAAsB,iCAAkC,SAAQ,uBAAuB;uBAK5C,QAAQ,EAAE,2BAA2B;IAJ7E,sFAAsF;IACtF,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAChD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEM,QAAQ,EAAE,2BAA2B;IAM7E;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC;IAEjD,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;CAyCjF"}
+{"version":3,"file":"langium-documents.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/langium-documents.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,OAAO,EAAE,uBAAuB,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAElI,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,KAAK,+BAA+B,EAAE,MAAM,yCAAyC,CAAC;AAE/F;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,kFAAuF,CAAC;AAExH;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,+IAGpC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IAChE,mBAAmB,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;CAC/E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,yBAA0B,SAAQ,uBAAwB,YAAW,yBAAyB;uBAWhE,QAAQ,EAAE,2BAA2B;IAV7E,sFAAsF;IACtF,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAEhD;;;;OAIG;IACH,mBAA2B,sBAAsB,EAAE,+BAA+B,CAAC;gBAE3C,QAAQ,EAAE,2BAA2B;IAK7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,mBAAmB,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC;IAe7D,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;CAgCjF"}

package/lib/langium/workspace/langium-documents.js

@@ -7,9 +7,28 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { DefaultLangiumDocuments } from '@hydranium/langium';
+import { defineMessage } from '@hydranium/protocol';
 /**
- * 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');
+/**
+ * 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
@@ -19,25 +38,70 @@ import { DefaultLangiumDocuments } from '@hydranium/langium';
  *    `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 class AbstractHydraniumLangiumDocuments extends DefaultLangiumDocuments {
+export class HydraniumLangiumDocuments extends DefaultLangiumDocuments {
     services;
     /** Document-identity seam, shared with the text store, event filters, and builder. */
     uriPolicy;
-    tracer;
     constructor(services) {
         super(services);
         this.services = services;
         this.uriPolicy = services.workspace.DocumentUriPolicy;
-        this.tracer = services.Tracer.for('LangiumDocuments');
+    }
+    /**
+     * 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.
+     */
+    createEmptyDocument(uri, languageId) {
+        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);
     }
     async getOrCreateDocument(uri) {
         const resolved = this.uriPolicy.loadUri(uri);
@@ -58,28 +122,19 @@ export class AbstractHydraniumLangiumDocuments extends DefaultLangiumDocuments {
             }
             catch (error) {
                 // 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);
+        // 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() }));
     }
 }
 //# sourceMappingURL=langium-documents.js.map

package/lib/langium/workspace/langium-documents.js.map

@@ -1 +1 @@
-{"version":3,"file":"langium-documents.js","sourceRoot":"","sources":["../../../src/langium/workspace/langium-documents.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAgB,uBAAuB,EAAkC,MAAM,oBAAoB,CAAC;AAI3G;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAgB,iCAAkC,SAAQ,uBAAuB;IAK5C;IAJxC,sFAAsF;IACnE,SAAS,CAAoB;IAC7B,MAAM,CAAS;IAElC,YAAwC,QAAqC;QAC1E,KAAK,CAAC,QAAQ,CAAC,CAAC;QADqB,aAAQ,GAAR,QAAQ,CAA6B;QAE1E,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,iBAAiB,CAAC;QACtD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACzD,CAAC;IAQQ,KAAK,CAAC,mBAAmB,CAAC,GAAQ;QACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,QAAQ,EAAE,CAAC;YACZ,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,QAAQ,EAAE,CAAC;gBACZ,iEAAiE;gBACjE,kEAAkE;gBAClE,sEAAsE;gBACtE,kEAAkE;gBAClE,uDAAuD;gBACvD,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,mBAAmB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;gBAChE,OAAO,QAAQ,CAAC;YACnB,CAAC;YACD,IAAI,CAAC;gBACF,4DAA4D;gBAC5D,OAAO,MAAM,KAAK,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YACpD,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACvB,oEAAoE;gBACpE,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;gBAC7C,IAAI,SAAS,EAAE,CAAC;oBACb,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,mBAAmB,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;oBACjE,OAAO,SAAS,CAAC;gBACpB,CAAC;gBACD,qEAAqE;gBACrE,oEAAoE;gBACpE,mEAAmE;gBACnE,qEAAqE;gBACrE,mEAAmE;gBACnE,iEAAiE;gBACjE,kEAAkE;gBAClE,4DAA4D;gBAC5D,4CAA4C;gBAC5C,IAAI,CAAC,MAAM;qBACP,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;qBACzB,KAAK,CAAC,mDAAmD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC1H,CAAC;QACJ,CAAC;QACD,2EAA2E;QAC3E,4EAA4E;QAC5E,OAAO,IAAI,CAAC,mBAAmB,CAAC,QAAQ,IAAI,GAAG,CAAC,CAAC;IACpD,CAAC;CACH"}
+{"version":3,"file":"langium-documents.js","sourceRoot":"","sources":["../../../src/langium/workspace/langium-documents.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAgB,uBAAuB,EAAyD,MAAM,oBAAoB,CAAC;AAClI,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAKpD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAC,oCAAoC,EAAE,+BAA+B,CAAC,CAAC;AAExH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,aAAa,CAClD,yCAAyC,EACzC,4FAA4F,CAC9F,CAAC;AAaF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,yBAA0B,SAAQ,uBAAuB;IAW3B;IAVxC,sFAAsF;IACnE,SAAS,CAAoB;IAShD,YAAwC,QAAqC;QAC1E,KAAK,CAAC,QAAQ,CAAC,CAAC;QADqB,aAAQ,GAAR,QAAQ,CAA6B;QAE1E,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,iBAAiB,CAAC;IACzD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,mBAAmB,CAAC,GAAQ,EAAE,UAAmB;QAC9C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,sBAAsB,CAAC,oBAAoB,CAAC,EAAE,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;YACtD,uEAAuE;YACvE,oEAAoE;YACpE,YAAY;YACZ,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;QAC7E,CAAC;QACD,yEAAyE;QACzE,uEAAuE;QACvE,OAAO,IAAI,CAAC,sBAAsB,CAAC,UAAU,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1D,CAAC;IAEQ,KAAK,CAAC,mBAAmB,CAAC,GAAQ;QACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,QAAQ,EAAE,CAAC;YACZ,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,QAAQ,EAAE,CAAC;gBACZ,iEAAiE;gBACjE,kEAAkE;gBAClE,sEAAsE;gBACtE,kEAAkE;gBAClE,uDAAuD;gBACvD,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,mBAAmB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;gBAChE,OAAO,QAAQ,CAAC;YACnB,CAAC;YACD,IAAI,CAAC;gBACF,4DAA4D;gBAC5D,OAAO,MAAM,KAAK,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YACpD,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACvB,oEAAoE;gBACpE,6DAA6D;gBAC7D,oEAAoE;gBACpE,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;gBAC7C,IAAI,SAAS,EAAE,CAAC;oBACb,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,mBAAmB,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;oBACjE,OAAO,SAAS,CAAC;gBACpB,CAAC;gBACD,MAAM,KAAK,CAAC;YACf,CAAC;QACJ,CAAC;QACD,wEAAwE;QACxE,iCAAiC;QACjC,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;IACxE,CAAC;CACH"}

package/lib/langium/workspace/virtual-document.d.ts

@@ -6,7 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { URI } from '@hydranium/langium';
+import { type FileSystemNode, URI } from '@hydranium/langium';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 /**
  * URI scheme for virtual documents — LangiumDocuments that have no backing
@@ -65,14 +65,29 @@ export declare function isVirtualUri(uri: URI | string): boolean;
  * is not virtual or no document is registered for it (so a FileSystemProvider
  * delegates to its real backing).
  *
- * The framework's FileSystemProvider defaults call this at the top of
- * `readFile` / `readFileSync` so a virtual document survives a re-read:
+ * The framework's FileSystemProvider defaults consult this across their whole
+ * read surface, 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.
+ *
+ * **Every read method has to agree.** Serving only the text methods leaves one
+ * provider answering "here is the content" and "nothing is there" about one
+ * URI, which is a worse contract than answering neither: a caller cannot probe
+ * before reading.
  */
 export declare function serveVirtualDocument(services: ServerSharedServicesMinimal, uri: URI): string | undefined;
+/**
+ * The filesystem node a registered virtual document presents as, or `undefined`
+ * on the same terms as {@link serveVirtualDocument}.
+ *
+ * Always a FILE: a virtual document is a leaf carrying text, and nothing is
+ * addressable beneath it. Reporting it as a directory instead would put it in
+ * front of a workspace walk that would then try to enumerate children it has
+ * none of.
+ */
+export declare function serveVirtualNode(services: ServerSharedServicesMinimal, uri: URI): FileSystemNode | undefined;
 //# sourceMappingURL=virtual-document.d.ts.map

package/lib/langium/workspace/virtual-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"virtual-document.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/virtual-document.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,CAG1E;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAGvD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,2BAA2B,EAAE,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAMxG"}
+{"version":3,"file":"virtual-document.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/virtual-document.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,cAAc,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,CAG1E;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAGvD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,2BAA2B,EAAE,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAMxG;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,2BAA2B,EAAE,GAAG,EAAE,GAAG,GAAG,cAAc,GAAG,SAAS,CAE5G"}

package/lib/langium/workspace/virtual-document.js

@@ -70,14 +70,19 @@ export function isVirtualUri(uri) {
  * is not virtual or no document is registered for it (so a FileSystemProvider
  * delegates to its real backing).
  *
- * The framework's FileSystemProvider defaults call this at the top of
- * `readFile` / `readFileSync` so a virtual document survives a re-read:
+ * The framework's FileSystemProvider defaults consult this across their whole
+ * read surface, 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.
+ *
+ * **Every read method has to agree.** Serving only the text methods leaves one
+ * provider answering "here is the content" and "nothing is there" about one
+ * URI, which is a worse contract than answering neither: a caller cannot probe
+ * before reading.
  */
 export function serveVirtualDocument(services, uri) {
     if (!isVirtualUri(uri)) {
@@ -86,4 +91,16 @@ export function serveVirtualDocument(services, uri) {
     const document = services.workspace.LangiumDocuments.getDocument(uri);
     return document ? document.textDocument.getText() : undefined;
 }
+/**
+ * The filesystem node a registered virtual document presents as, or `undefined`
+ * on the same terms as {@link serveVirtualDocument}.
+ *
+ * Always a FILE: a virtual document is a leaf carrying text, and nothing is
+ * addressable beneath it. Reporting it as a directory instead would put it in
+ * front of a workspace walk that would then try to enumerate children it has
+ * none of.
+ */
+export function serveVirtualNode(services, uri) {
+    return serveVirtualDocument(services, uri) === undefined ? undefined : { isFile: true, isDirectory: false, uri };
+}
 //# sourceMappingURL=virtual-document.js.map

package/lib/langium/workspace/virtual-document.js.map

@@ -1 +1 @@
-{"version":3,"file":"virtual-document.js","sourceRoot":"","sources":["../../../src/langium/workspace/virtual-document.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAGzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,UAAU,CAAC,WAAmB,EAAE,GAAG,QAAkB;IAClE,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,cAAc,IAAI,WAAW,GAAG,IAAI,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,YAAY,CAAC,GAAiB;IAC3C,MAAM,MAAM,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;IAC5E,OAAO,MAAM,KAAK,cAAc,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAqC,EAAE,GAAQ;IACjF,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACpB,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,gBAAgB,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACtE,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACjE,CAAC"}
+{"version":3,"file":"virtual-document.js","sourceRoot":"","sources":["../../../src/langium/workspace/virtual-document.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAuB,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAG9D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,UAAU,CAAC,WAAmB,EAAE,GAAG,QAAkB;IAClE,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,cAAc,IAAI,WAAW,GAAG,IAAI,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,YAAY,CAAC,GAAiB;IAC3C,MAAM,MAAM,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;IAC5E,OAAO,MAAM,KAAK,cAAc,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAqC,EAAE,GAAQ;IACjF,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACpB,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,gBAAgB,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACtE,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACjE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAqC,EAAE,GAAQ;IAC7E,OAAO,oBAAoB,CAAC,QAAQ,EAAE,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AACpH,CAAC"}

package/lib/locale/index.d.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';
+//# sourceMappingURL=index.d.ts.map

package/lib/locale/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/locale/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,oBAAoB,CAAC"}

package/lib/locale/index.js

@@ -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';
+//# sourceMappingURL=index.js.map

package/lib/locale/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/locale/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,oBAAoB,CAAC"}

package/lib/locale/server-locale.d.ts

@@ -0,0 +1,73 @@
+/********************************************************************************
+ * 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 declare class DefaultServerLocale implements ServerLocale {
+    protected readonly tracer: Tracer;
+    protected current: Locale | undefined;
+    constructor(services: ServerSharedServicesMinimal, options?: ServerLocaleOptions);
+    /** The locale, or `undefined` when no init supplied one — which means the framework's English. */
+    get value(): Locale | undefined;
+    /**
+     * 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;
+}
+//# sourceMappingURL=server-locale.d.ts.map

package/lib/locale/server-locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-locale.d.ts","sourceRoot":"","sources":["../../src/locale/server-locale.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAEjF,qDAAqD;AACrD,MAAM,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IACrD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE1B,QAAQ,EAAE,2BAA2B,EAAE,OAAO,GAAE,mBAAwB;IAIpF,kGAAkG;IAClG,IAAI,KAAK,IAAI,MAAM,GAAG,SAAS,CAE9B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAI9B"}

package/lib/locale/server-locale.js

@@ -0,0 +1,61 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * 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 {
+    tracer;
+    current;
+    constructor(services, options = {}) {
+        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() {
+        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) {
+        this.current = locale;
+        this.tracer.info(`rendering messages in locale '${locale}'`);
+    }
+}
+//# sourceMappingURL=server-locale.js.map

package/lib/locale/server-locale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-locale.js","sourceRoot":"","sources":["../../src/locale/server-locale.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAwBlF;;;;;;;;GAQG;AACH,MAAM,OAAO,mBAAmB;IACV,MAAM,CAAS;IACxB,OAAO,CAAqB;IAEtC,YAAY,QAAqC,EAAE,UAA+B,EAAE;QACjF,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,cAAc,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9F,CAAC;IAED,kGAAkG;IAClG,IAAI,KAAK;QACN,OAAO,IAAI,CAAC,OAAO,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,MAAc;QAClB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iCAAiC,MAAM,GAAG,CAAC,CAAC;IAChE,CAAC;CACH"}

package/lib/lsp/completion/hydranium-completion-provider.d.ts

@@ -6,9 +6,9 @@
  *
  * 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 } from 'vscode-languageserver';
+import { CompletionList, type CancellationToken, type CompletionItem, type CompletionParams, type Position } from 'vscode-languageserver';
 import { type ReferenceCandidateProvider } from '../../langium/scope/reference-candidate-provider.js';
 import { type ServerLanguageServices } from '../../langium/language-module.js';
 /**
@@ -50,10 +50,52 @@ 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 declare class HydraniumCompletionProvider extends DefaultCompletionProvider {
     protected readonly candidateProvider: ReferenceCandidateProvider;
     constructor(services: ServerLanguageServices);
+    /**
+     * 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.
+     */
+    getCompletion(document: LangiumDocument, params: CompletionParams, cancelToken?: CancellationToken): Promise<CompletionList | undefined>;
+    /**
+     * 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;
     /**
      * Delegate cross-reference candidate gathering to the candidate provider
      * so the LSP completion dropdown applies the same filter / canonical