@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,89 @@
+/********************************************************************************
+ * 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 { URI } from '@hydranium/langium';
+/**
+ * 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}).
+ */
+export const VIRTUAL_SCHEME = 'virtual';
+/**
+ * Build a URI for a virtual document — one whose content is provided in code
+ * rather than read from disk, either as a parsed string
+ * (`LangiumDocumentFactory.fromString`) or a code-built AST
+ * (`LangiumDocumentFactory.fromModel`).
+ *
+ * The URI uses the {@link VIRTUAL_SCHEME} scheme. The first segment carries
+ * contributor identity for diagnostics, telemetry, and "go to source" UI;
+ * additional segments scope sub-documents within one contributor.
+ *
+ * Pair with a `LangiumDocumentFactory` to construct a document whose content
+ * lives in memory. The resulting document is suitable as the `document`
+ * argument to the tier factories on `HydraniumAstNodeDescriptionProvider`
+ * (`createLocal` / `createProject` / `createPublic` / `createUniversal`).
+ *
+ * # End the URI with a registered file extension
+ *
+ * Called with a contributor and no further segments this yields
+ * `virtual:<contributor>`, which has no extension and so matches no registered
+ * language — a trap. Every per-language service is resolved per URI, and a
+ * virtual document is never open in `TextDocuments`, so the declared-languageId
+ * lookup rung cannot serve it either: the document is indexed but inert,
+ * contributing nothing to the scopes it was written to populate, with no error
+ * anywhere. Pass the extension as the last segment,
+ * `virtualUri(contributor, 'name.<ext>')`. `HydraniumWorkspaceManager` warns
+ * when a seeded additional document fails to route, which is where this
+ * usually surfaces.
+ *
+ * # Relationship to the `$synthetic` node marker
+ *
+ * The URI scheme tags the *document* as not-from-disk; the `$synthetic` node
+ * marker (see `markSynthetic` / `isSyntheticNode`) tags an individual *node* as
+ * not user-authored. A virtual document may contain non-synthetic nodes and
+ * vice versa.
+ *
+ * Both axes are read by `HydraniumDocumentValidator`, at different
+ * granularities: the scheme skips the WHOLE document
+ * (`validateVirtualDocuments`, default `false`, so the walk is avoided
+ * entirely), the marker skips a node and its children
+ * (`validateSyntheticNodes`, default `false`).
+ */
+export function virtualUri(contributor, ...segments) {
+    const tail = segments.length > 0 ? '/' + segments.join('/') : '';
+    return URI.parse(`${VIRTUAL_SCHEME}:${contributor}${tail}`);
+}
+/** True iff `uri` uses the {@link VIRTUAL_SCHEME} scheme produced by {@link virtualUri}. */
+export function isVirtualUri(uri) {
+    const scheme = typeof uri === 'string' ? URI.parse(uri).scheme : uri.scheme;
+    return scheme === VIRTUAL_SCHEME;
+}
+/**
+ * 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 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.
+ */
+export function serveVirtualDocument(services, uri) {
+    if (!isVirtualUri(uri)) {
+        return undefined;
+    }
+    const document = services.workspace.LangiumDocuments.getDocument(uri);
+    return document ? document.textDocument.getText() : undefined;
+}
+//# sourceMappingURL=virtual-document.js.map

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

@@ -0,0 +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"}

package/lib/langium/workspace/write-lock-scope.d.ts

@@ -0,0 +1,69 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Tracks whether the currently-executing code is running inside a holder of the
+ * workspace WRITE lock.
+ *
+ * The question matters because `WorkspaceLock` is not reentrant: acquiring the
+ * write lock calls `cancelWrite()` on the running holder, so a caller that
+ * reaches the model facade from inside a build has its ENCLOSING build cancelled
+ * and may then stall in the follow-up phase wait. That is a latent deadlock with
+ * no static signature — the call looks ordinary at every layer — so the only way
+ * to surface it is to know, at the moment of acquisition, whether the lock is
+ * already held further up the same async stack.
+ *
+ * Answering it needs async-context propagation, which has no browser-neutral
+ * implementation: Node's `AsyncLocalStorage` is a `node:async_hooks` import (so
+ * it cannot appear on the portable `.` entry, which `check:neutral` gates), and
+ * TC39's `AsyncContext` is unshipped. Hence the same seam shape the log file-tee
+ * uses: this module declares the contract and defaults to inert, and
+ * `@hydranium/core/node` installs a real implementation at entry load. A browser
+ * bundle therefore gets NO detection rather than a broken approximation, which
+ * is the right degradation — the reentrant shape is a server-side build concern,
+ * and a false negative costs the pre-existing stall while a false positive would
+ * reject a legitimate write.
+ */
+export interface WriteLockScope {
+    /** Run `fn` marked as executing inside a write-lock holder. */
+    run<T>(fn: () => T): T;
+    /** Whether the caller is already inside a {@link run} scope. */
+    isInside(): boolean;
+}
+/** Install (or clear, with `undefined`) the write-lock scope tracker. Idempotent. */
+export declare function setWriteLockScope(scope: WriteLockScope | undefined): void;
+/**
+ * Run `fn` inside the write-lock scope, if a tracker is installed. Without one
+ * this is a plain call, so the wrapper is safe to apply unconditionally on the
+ * neutral path.
+ */
+export declare function runInWriteLockScope<T>(fn: () => T): T;
+/**
+ * Whether the caller is executing inside a workspace write-lock holder.
+ *
+ * Returns `false` when no tracker is installed, so every guard reading this
+ * fails OPEN — an un-instrumented host keeps its current behaviour rather than
+ * gaining spurious rejections.
+ */
+export declare 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.
+ *
+ * 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.
+ */
+export declare class ReentrantWriteLockError extends Error {
+    readonly uri: string;
+    constructor(uri: string);
+}
+//# sourceMappingURL=write-lock-scope.d.ts.map

package/lib/langium/workspace/write-lock-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-lock-scope.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/write-lock-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,cAAc;IAC5B,+DAA+D;IAC/D,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACvB,gEAAgE;IAChE,QAAQ,IAAI,OAAO,CAAC;CACtB;AAID,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM;CASlC"}

package/lib/langium/workspace/write-lock-scope.js

@@ -0,0 +1,54 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+let writeLockScope;
+/** Install (or clear, with `undefined`) the write-lock scope tracker. Idempotent. */
+export function setWriteLockScope(scope) {
+    writeLockScope = scope;
+}
+/**
+ * Run `fn` inside the write-lock scope, if a tracker is installed. Without one
+ * this is a plain call, so the wrapper is safe to apply unconditionally on the
+ * neutral path.
+ */
+export function runInWriteLockScope(fn) {
+    return writeLockScope ? writeLockScope.run(fn) : fn();
+}
+/**
+ * Whether the caller is executing inside a workspace write-lock holder.
+ *
+ * Returns `false` when no tracker is installed, so every guard reading this
+ * fails OPEN — an un-instrumented host keeps its current behaviour rather than
+ * gaining spurious rejections.
+ */
+export function isInsideWriteLock() {
+    return writeLockScope?.isInside() ?? false;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export class ReentrantWriteLockError extends Error {
+    uri;
+    constructor(uri) {
+        super(`Model facade reached for '${uri}' from inside a workspace write-lock holder. ` +
+            'Acquiring the write lock would cancel the enclosing build and may stall this call. ' +
+            'Write through FileSystemProvider.writeFile from a build-phase pass, or set ' +
+            'ModelServiceOptions.serializeBuilds: false to opt out of build serialisation.');
+        this.uri = uri;
+        this.name = 'ReentrantWriteLockError';
+    }
+}
+//# sourceMappingURL=write-lock-scope.js.map

package/lib/langium/workspace/write-lock-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-lock-scope.js","sourceRoot":"","sources":["../../../src/langium/workspace/write-lock-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAgClF,IAAI,cAA0C,CAAC;AAE/C,qFAAqF;AACrF,MAAM,UAAU,iBAAiB,CAAC,KAAiC;IAChE,cAAc,GAAG,KAAK,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAI,EAAW;IAC/C,OAAO,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAC9B,OAAO,cAAc,EAAE,QAAQ,EAAE,IAAI,KAAK,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAC1B;IAArB,YAAqB,GAAW;QAC7B,KAAK,CACF,6BAA6B,GAAG,+CAA+C;YAC5E,qFAAqF;YACrF,6EAA6E;YAC7E,+EAA+E,CACpF,CAAC;QANgB,QAAG,GAAH,GAAG,CAAQ;QAO7B,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACzC,CAAC;CACH"}

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

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

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

package/lib/launcher/index.js

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * 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 './integrated-server.js';
+// Only the transport-agnostic handle belongs here: `socket-launcher` pulls
+// `node:net` and therefore ships from `@hydranium/core/node` instead.
+//# sourceMappingURL=index.js.map

package/lib/launcher/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/launcher/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,wBAAwB,CAAC;AACvC,2EAA2E;AAC3E,sEAAsE"}

package/lib/launcher/integrated-server.d.ts

@@ -0,0 +1,28 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Lifecycle handle for a protocol-head server (socket-based, stdio-based,
+ * or otherwise) that the adopter starts during language-server bootstrap.
+ *
+ * The two promises encode the canonical two-phase startup pattern:
+ * - {@link started} resolves once the head is accepting traffic — for a
+ *   socket server, this means `net.Server.listen` resolved AND the bound
+ *   port is known. Adopter bootstrap code awaits this before publishing
+ *   the port and announcing readiness over the LSP connection.
+ * - {@link stopped} resolves once the head has shut down cleanly — used
+ *   primarily by tests waiting for tidy teardown.
+ *
+ * Either promise may reject if startup or shutdown encounters an error
+ * the head can't recover from.
+ */
+export interface IntegratedServer {
+    readonly started: Promise<void>;
+    readonly stopped: Promise<void>;
+}
+//# sourceMappingURL=integrated-server.d.ts.map

package/lib/launcher/integrated-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrated-server.d.ts","sourceRoot":"","sources":["../../src/launcher/integrated-server.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC"}

package/lib/launcher/integrated-server.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 {};
+//# sourceMappingURL=integrated-server.js.map

package/lib/launcher/integrated-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrated-server.js","sourceRoot":"","sources":["../../src/launcher/integrated-server.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF"}

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

@@ -0,0 +1,89 @@
+/********************************************************************************
+ * 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 AstNodeDescription, type ReferenceInfo, type Stream } from '@hydranium/langium';
+import { DefaultCompletionProvider, type CompletionContext, type CompletionValueItem } from '@hydranium/langium/lsp';
+import type { CompletionItem } from 'vscode-languageserver';
+import { type ReferenceCandidateProvider } from '../../langium/scope/reference-candidate-provider.js';
+import { type ServerLanguageServices } from '../../langium/language-module.js';
+/**
+ * Completion provider that upgrades Langium's default `TextEdit` to
+ * {@link InsertReplaceEdit} so accepting a suggestion over an existing token
+ * replaces that token rather than inserting alongside it.
+ *
+ * **Why this exists.** `DefaultCompletionProvider.buildCompletionTextEdit`
+ * returns a range ending at the cursor position, so accepting a suggestion
+ * with the caret inside a token leaves the token's tail standing after the
+ * inserted text. By widening the `replace` range to the token's end while
+ * keeping the original `insert` range at the cursor, LSP clients honour the
+ * user's `editor.suggest.insertMode` preference (`insert` = Langium's narrow
+ * range, `replace` = overwrite the whole token).
+ *
+ * **Two cursor positions need widening and Langium's context only describes
+ * one of them.** Inside a token, `tokenEndOffset` points past the token and the
+ * widening reads straight off it. Sitting at a token's START — right after `= `
+ * in `writes Order.status = PAID`, say — the cursor is on whitespace as far as
+ * the completion context is concerned, so `tokenEndOffset` describes the
+ * whitespace and not the name that follows it. Without {@link getReplaceEndOffset}
+ * the item goes out with an EMPTY range and accepting it produces
+ * `SHIPPEDPAID`: the suggestion inserted in front of the word it was meant to
+ * replace. A `tsserver` in the same position returns a range covering the
+ * following word, which is the behaviour matched here.
+ *
+ * **Capability gating.** {@link InsertReplaceEdit} requires LSP 3.16+
+ * (`completionItem.insertReplaceSupport`). Older clients that ignore the
+ * wider range fall back to the narrower `insert` range, which matches
+ * Langium's original behaviour. A defensive capability check is
+ * intentionally not added so the framework default stays simple —
+ * consumers that need to support pre-3.16 clients can override and emit a
+ * plain `TextEdit`.
+ *
+ * **Candidate gathering is delegated.** Cross-reference completion reuses
+ * the {@link ReferenceCandidateProvider} pipeline (filter, canonical
+ * tier-sibling collapse, name-dedup, sort) by overriding
+ * {@link getReferenceCandidates} to return the candidate provider's scope
+ * 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.
+ */
+export declare class HydraniumCompletionProvider extends DefaultCompletionProvider {
+    protected readonly candidateProvider: ReferenceCandidateProvider;
+    constructor(services: ServerLanguageServices);
+    /**
+     * Delegate cross-reference candidate gathering to the candidate provider
+     * so the LSP completion dropdown applies the same filter / canonical
+     * tier-sibling collapse / name-dedup / sort as the protocol candidate
+     * picker. Langium hands us the built {@link ReferenceInfo}, which the
+     * candidate provider's `getCandidateScope` accepts directly, so the
+     * merged path walks the scope exactly once.
+     */
+    protected getReferenceCandidates(refInfo: ReferenceInfo, _context: CompletionContext): Stream<AstNodeDescription>;
+    protected fillCompletionItem(context: CompletionContext, item: CompletionValueItem): CompletionItem | undefined;
+    /**
+     * Offset the `replace` range should end at: the end of the text a suggestion
+     * accepted here would stand in for, or `context.offset` when there is none.
+     *
+     * Two sources, because Langium's completion context describes the token the
+     * completion is FOR and that is not always the text under the cursor:
+     *
+     * - **Cursor inside a token** — `tokenEndOffset` already points past it.
+     * - **Cursor at a token's start** — the context describes the preceding
+     *   whitespace, so `tokenEndOffset` is at or behind the cursor and the name
+     *   to the right has to be measured from the document text.
+     *
+     * Scanning stops at the first character `GrammarConfig.nameRegexp` rejects, so
+     * a run only ever covers one name: a cursor before `Order` in `Order.status`
+     * widens to the end of `Order` and not through the dot.
+     *
+     * Adopters whose grammar has a wider notion of a replaceable token than
+     * "consecutive name characters" — a quoted or dotted identifier — override
+     * this rather than {@link fillCompletionItem}.
+     */
+    protected getReplaceEndOffset(context: CompletionContext): number;
+}
+//# sourceMappingURL=hydranium-completion-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-completion-provider.d.ts","sourceRoot":"","sources":["../../../src/lsp/completion/hydranium-completion-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC9F,OAAO,EAAE,yBAAyB,EAAE,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACrH,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,qDAAqD,CAAC;AACtG,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,2BAA4B,SAAQ,yBAAyB;IACvE,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAE,0BAA0B,CAAC;gBAErD,QAAQ,EAAE,sBAAsB;IAK5C;;;;;;;OAOG;cACgB,sBAAsB,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAAC,kBAAkB,CAAC;cAIvG,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,mBAAmB,GAAG,cAAc,GAAG,SAAS;IAsBxH;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM;CAcnE"}

package/lib/lsp/completion/hydranium-completion-provider.js

@@ -0,0 +1,123 @@
+/********************************************************************************
+ * 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 { DefaultCompletionProvider } from '@hydranium/langium/lsp';
+/**
+ * Completion provider that upgrades Langium's default `TextEdit` to
+ * {@link InsertReplaceEdit} so accepting a suggestion over an existing token
+ * replaces that token rather than inserting alongside it.
+ *
+ * **Why this exists.** `DefaultCompletionProvider.buildCompletionTextEdit`
+ * returns a range ending at the cursor position, so accepting a suggestion
+ * with the caret inside a token leaves the token's tail standing after the
+ * inserted text. By widening the `replace` range to the token's end while
+ * keeping the original `insert` range at the cursor, LSP clients honour the
+ * user's `editor.suggest.insertMode` preference (`insert` = Langium's narrow
+ * range, `replace` = overwrite the whole token).
+ *
+ * **Two cursor positions need widening and Langium's context only describes
+ * one of them.** Inside a token, `tokenEndOffset` points past the token and the
+ * widening reads straight off it. Sitting at a token's START — right after `= `
+ * in `writes Order.status = PAID`, say — the cursor is on whitespace as far as
+ * the completion context is concerned, so `tokenEndOffset` describes the
+ * whitespace and not the name that follows it. Without {@link getReplaceEndOffset}
+ * the item goes out with an EMPTY range and accepting it produces
+ * `SHIPPEDPAID`: the suggestion inserted in front of the word it was meant to
+ * replace. A `tsserver` in the same position returns a range covering the
+ * following word, which is the behaviour matched here.
+ *
+ * **Capability gating.** {@link InsertReplaceEdit} requires LSP 3.16+
+ * (`completionItem.insertReplaceSupport`). Older clients that ignore the
+ * wider range fall back to the narrower `insert` range, which matches
+ * Langium's original behaviour. A defensive capability check is
+ * intentionally not added so the framework default stays simple —
+ * consumers that need to support pre-3.16 clients can override and emit a
+ * plain `TextEdit`.
+ *
+ * **Candidate gathering is delegated.** Cross-reference completion reuses
+ * the {@link ReferenceCandidateProvider} pipeline (filter, canonical
+ * tier-sibling collapse, name-dedup, sort) by overriding
+ * {@link getReferenceCandidates} to return the candidate provider's scope
+ * 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.
+ */
+export class HydraniumCompletionProvider extends DefaultCompletionProvider {
+    candidateProvider;
+    constructor(services) {
+        super(services);
+        this.candidateProvider = services.references.CandidateProvider;
+    }
+    /**
+     * Delegate cross-reference candidate gathering to the candidate provider
+     * so the LSP completion dropdown applies the same filter / canonical
+     * tier-sibling collapse / name-dedup / sort as the protocol candidate
+     * picker. Langium hands us the built {@link ReferenceInfo}, which the
+     * candidate provider's `getCandidateScope` accepts directly, so the
+     * merged path walks the scope exactly once.
+     */
+    getReferenceCandidates(refInfo, _context) {
+        return this.candidateProvider.getCandidateScope(refInfo).elementScope.getAllElements();
+    }
+    fillCompletionItem(context, item) {
+        const completionItem = super.fillCompletionItem(context, item);
+        if (!completionItem?.textEdit || 'insert' in completionItem.textEdit) {
+            return completionItem;
+        }
+        const replaceEndOffset = this.getReplaceEndOffset(context);
+        // Nothing to the right of the cursor that a suggestion would stand in for
+        // (completion on whitespace, on punctuation, at end of file) — the
+        // parent's narrow range is already correct.
+        if (replaceEndOffset <= context.offset) {
+            return completionItem;
+        }
+        const baseEdit = completionItem.textEdit;
+        const insertReplaceEdit = {
+            newText: baseEdit.newText,
+            insert: baseEdit.range,
+            replace: { start: baseEdit.range.start, end: context.textDocument.positionAt(replaceEndOffset) }
+        };
+        completionItem.textEdit = insertReplaceEdit;
+        return completionItem;
+    }
+    /**
+     * Offset the `replace` range should end at: the end of the text a suggestion
+     * accepted here would stand in for, or `context.offset` when there is none.
+     *
+     * Two sources, because Langium's completion context describes the token the
+     * completion is FOR and that is not always the text under the cursor:
+     *
+     * - **Cursor inside a token** — `tokenEndOffset` already points past it.
+     * - **Cursor at a token's start** — the context describes the preceding
+     *   whitespace, so `tokenEndOffset` is at or behind the cursor and the name
+     *   to the right has to be measured from the document text.
+     *
+     * Scanning stops at the first character `GrammarConfig.nameRegexp` rejects, so
+     * a run only ever covers one name: a cursor before `Order` in `Order.status`
+     * widens to the end of `Order` and not through the dot.
+     *
+     * Adopters whose grammar has a wider notion of a replaceable token than
+     * "consecutive name characters" — a quoted or dotted identifier — override
+     * this rather than {@link fillCompletionItem}.
+     */
+    getReplaceEndOffset(context) {
+        if (context.tokenEndOffset > context.offset) {
+            return context.tokenEndOffset;
+        }
+        // `getText()` with no range returns the document's stored string rather
+        // than a copy, so reading it per item costs nothing.
+        const text = context.textDocument.getText();
+        const nameRegexp = this.grammarConfig.nameRegexp;
+        let end = context.offset;
+        while (end < text.length && nameRegexp.test(text.charAt(end))) {
+            end++;
+        }
+        return end;
+    }
+}
+//# sourceMappingURL=hydranium-completion-provider.js.map

package/lib/lsp/completion/hydranium-completion-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-completion-provider.js","sourceRoot":"","sources":["../../../src/lsp/completion/hydranium-completion-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAE,yBAAyB,EAAoD,MAAM,wBAAwB,CAAC;AAKrH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,OAAO,2BAA4B,SAAQ,yBAAyB;IACpD,iBAAiB,CAA6B;IAEjE,YAAY,QAAgC;QACzC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChB,IAAI,CAAC,iBAAiB,GAAG,QAAQ,CAAC,UAAU,CAAC,iBAAiB,CAAC;IAClE,CAAC;IAED;;;;;;;OAOG;IACgB,sBAAsB,CAAC,OAAsB,EAAE,QAA2B;QAC1F,OAAO,IAAI,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,cAAc,EAAE,CAAC;IAC1F,CAAC;IAEkB,kBAAkB,CAAC,OAA0B,EAAE,IAAyB;QACxF,MAAM,cAAc,GAAG,KAAK,CAAC,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC/D,IAAI,CAAC,cAAc,EAAE,QAAQ,IAAI,QAAQ,IAAI,cAAc,CAAC,QAAQ,EAAE,CAAC;YACpE,OAAO,cAAc,CAAC;QACzB,CAAC;QACD,MAAM,gBAAgB,GAAG,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC3D,0EAA0E;QAC1E,mEAAmE;QACnE,4CAA4C;QAC5C,IAAI,gBAAgB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACtC,OAAO,cAAc,CAAC;QACzB,CAAC;QACD,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAQ,CAAC;QACzC,MAAM,iBAAiB,GAAsB;YAC1C,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,MAAM,EAAE,QAAQ,CAAC,KAAK;YACtB,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE;SAClG,CAAC;QACF,cAAc,CAAC,QAAQ,GAAG,iBAAiB,CAAC;QAC5C,OAAO,cAAc,CAAC;IACzB,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACO,mBAAmB,CAAC,OAA0B;QACrD,IAAI,OAAO,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAC3C,OAAO,OAAO,CAAC,cAAc,CAAC;QACjC,CAAC;QACD,wEAAwE;QACxE,qDAAqD;QACrD,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;QAC5C,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC;QACjD,IAAI,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;QACzB,OAAO,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,EAAE,CAAC;QACT,CAAC;QACD,OAAO,GAAG,CAAC;IACd,CAAC;CACH"}