@hydranium/core 1.0.0-next.10

package/lib/langium/keys/name-based-key-provider.d.ts

@@ -0,0 +1,99 @@
+/********************************************************************************
+ * 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 Tracer } from '@hydranium/protocol';
+import { type AstNode } from '@hydranium/langium';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerLanguageServices } from '../language-module.js';
+import { type ElementKeyProvider } from './element-key-provider.js';
+import { type NameProvider } from '../naming/name-provider.js';
+/**
+ * Name-based {@link ElementKeyProvider} — walks named ancestors stopping at the
+ * semantic root, joining segments with `NameProvider.nameSeparator`.
+ *
+ * **The framework's default key strategy.** Optimised for interactive
+ * editing workloads where reorder/insert/delete are frequent and renames
+ * of intermediate ancestors are rare.
+ *
+ * # Stability profile
+ *
+ * **The bullets below hold for nodes that HAVE a name.** A node with no
+ * name — and any node below one — is keyed through
+ * {@link unidentifiedSegment}, which encodes `$containerIndex`; see the
+ * caveat below.
+ *
+ * - **Stable across sibling reorder** — segments are names, not indices,
+ *   so reordering siblings of a named node does not change its key.
+ * - **Stable across mid-array insert / delete** — same reason: indices
+ *   are not encoded.
+ * - **Stable across semantic-root rename** — the predicate excludes the
+ *   semantic root from the key by construction.
+ * - **Flips on rename of any named segment** within the walked path.
+ *
+ * # Caveat: unnamed nodes are keyed positionally
+ *
+ * {@link unidentifiedSegment} falls back to
+ * `` `${$containerProperty}@${$containerIndex}` `` for a node the
+ * `NameProvider` gives no name. For grammars with unnamed element types the
+ * reorder / insert / delete stability above does NOT apply to those nodes:
+ * their keys move when their index moves, so a mid-array insert or delete
+ * renumbers every later sibling.
+ *
+ * Two consequences for a caller creating such nodes programmatically
+ * (a GLSP operation handler is the usual case):
+ *
+ * - A node appended with a bare `array.push` has no `$containerProperty` /
+ *   `$containerIndex`, so `getElementKey` returns `undefined` and the node
+ *   has no key at all. The containment plumbing has to be stamped.
+ * - After a removal, surviving siblings need their `$containerIndex`
+ *   renumbered, or a key derived afterwards addresses the wrong node.
+ *
+ * Adopters that need insert / delete stability for unnamed types should
+ * give those types a name in the grammar, or bind a key provider whose
+ * fallback is content-derived rather than positional.
+ *
+ * Override {@link isSemanticRoot} if the grammar's root structure does not
+ * match either shape that predicate handles.
+ */
+export declare class NameBasedKeyProvider implements ElementKeyProvider {
+    protected readonly services: ServerLanguageServices;
+    protected readonly nameProvider: NameProvider;
+    protected readonly tracer: Tracer;
+    constructor(services: ServerLanguageServices, options?: LogNameOptions);
+    getElementKey(node?: AstNode): string | undefined;
+    /**
+     * No structural inverse — keys are name-paths, not addressable locations —
+     * so resolve by scanning `context`'s subtree for the first node whose key
+     * matches. O(subtree); the GLSP index keeps its own key-to-node map, so
+     * this is the canonical / testable inverse rather than a hot path. See
+     * {@link ElementKeyProvider.resolveElement} for the scope and uniqueness
+     * contract.
+     */
+    resolveElement(key: string, context: AstNode): AstNode | undefined;
+    /**
+     * Semantic-root predicate. Default implementation matches two common
+     * grammar shapes; override for non-standard structures:
+     *
+     * - **Document root with no container**: the root itself is the
+     *   semantic root iff it has a name (covers unwrapped grammars whose
+     *   named root element IS the semantic root).
+     * - **Direct child of an unnamed wrapper**: the child is the semantic
+     *   root (covers wrapper grammars with an unnamed root node).
+     *
+     * A node more than one container below the document root is never a
+     * semantic root in the default heuristic.
+     */
+    protected isSemanticRoot(node: AstNode): boolean;
+    /**
+     * Fallback segment for unnamed intermediate ancestors —
+     * `containerProperty@containerIndex`. Returns `undefined` when the
+     * node has no container position, which short-circuits the walk.
+     */
+    protected unidentifiedSegment(node: AstNode): string | undefined;
+}
+//# sourceMappingURL=name-based-key-provider.d.ts.map

package/lib/langium/keys/name-based-key-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"name-based-key-provider.d.ts","sourceRoot":"","sources":["../../../src/langium/keys/name-based-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,KAAK,kBAAkB,EAAwB,MAAM,2BAA2B,CAAC;AAC1F,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,oBAAqB,YAAW,kBAAkB;IAKzD,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB;IAJtD,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IAC9C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,sBAAsB,EACnD,OAAO,GAAE,cAAmB;IAM/B,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAuBjD;;;;;;;OAOG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS;IAIlE;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO;IAUhD;;;;OAIG;IACH,SAAS,CAAC,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;CAMlE"}

package/lib/langium/keys/name-based-key-provider.js

@@ -0,0 +1,134 @@
+/********************************************************************************
+ * 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 { resolveElementByScan } from './element-key-provider.js';
+/**
+ * Name-based {@link ElementKeyProvider} — walks named ancestors stopping at the
+ * semantic root, joining segments with `NameProvider.nameSeparator`.
+ *
+ * **The framework's default key strategy.** Optimised for interactive
+ * editing workloads where reorder/insert/delete are frequent and renames
+ * of intermediate ancestors are rare.
+ *
+ * # Stability profile
+ *
+ * **The bullets below hold for nodes that HAVE a name.** A node with no
+ * name — and any node below one — is keyed through
+ * {@link unidentifiedSegment}, which encodes `$containerIndex`; see the
+ * caveat below.
+ *
+ * - **Stable across sibling reorder** — segments are names, not indices,
+ *   so reordering siblings of a named node does not change its key.
+ * - **Stable across mid-array insert / delete** — same reason: indices
+ *   are not encoded.
+ * - **Stable across semantic-root rename** — the predicate excludes the
+ *   semantic root from the key by construction.
+ * - **Flips on rename of any named segment** within the walked path.
+ *
+ * # Caveat: unnamed nodes are keyed positionally
+ *
+ * {@link unidentifiedSegment} falls back to
+ * `` `${$containerProperty}@${$containerIndex}` `` for a node the
+ * `NameProvider` gives no name. For grammars with unnamed element types the
+ * reorder / insert / delete stability above does NOT apply to those nodes:
+ * their keys move when their index moves, so a mid-array insert or delete
+ * renumbers every later sibling.
+ *
+ * Two consequences for a caller creating such nodes programmatically
+ * (a GLSP operation handler is the usual case):
+ *
+ * - A node appended with a bare `array.push` has no `$containerProperty` /
+ *   `$containerIndex`, so `getElementKey` returns `undefined` and the node
+ *   has no key at all. The containment plumbing has to be stamped.
+ * - After a removal, surviving siblings need their `$containerIndex`
+ *   renumbered, or a key derived afterwards addresses the wrong node.
+ *
+ * Adopters that need insert / delete stability for unnamed types should
+ * give those types a name in the grammar, or bind a key provider whose
+ * fallback is content-derived rather than positional.
+ *
+ * Override {@link isSemanticRoot} if the grammar's root structure does not
+ * match either shape that predicate handles.
+ */
+export class NameBasedKeyProvider {
+    services;
+    nameProvider;
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.nameProvider = services.references.NameProvider;
+        this.tracer = services.shared.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+    }
+    getElementKey(node) {
+        if (!node) {
+            return undefined;
+        }
+        let id = this.nameProvider.getOwnName(node) ?? this.unidentifiedSegment(node);
+        if (!id) {
+            return undefined;
+        }
+        if (this.isSemanticRoot(node)) {
+            return id;
+        }
+        const separator = this.nameProvider.nameSeparator;
+        let parent = node.$container;
+        while (parent && !this.isSemanticRoot(parent)) {
+            const segment = this.nameProvider.getOwnName(parent) ?? this.unidentifiedSegment(parent);
+            if (segment) {
+                id = segment + separator + id;
+            }
+            parent = parent.$container;
+        }
+        return id;
+    }
+    /**
+     * No structural inverse — keys are name-paths, not addressable locations —
+     * so resolve by scanning `context`'s subtree for the first node whose key
+     * matches. O(subtree); the GLSP index keeps its own key-to-node map, so
+     * this is the canonical / testable inverse rather than a hot path. See
+     * {@link ElementKeyProvider.resolveElement} for the scope and uniqueness
+     * contract.
+     */
+    resolveElement(key, context) {
+        return resolveElementByScan(node => this.getElementKey(node), key, context);
+    }
+    /**
+     * Semantic-root predicate. Default implementation matches two common
+     * grammar shapes; override for non-standard structures:
+     *
+     * - **Document root with no container**: the root itself is the
+     *   semantic root iff it has a name (covers unwrapped grammars whose
+     *   named root element IS the semantic root).
+     * - **Direct child of an unnamed wrapper**: the child is the semantic
+     *   root (covers wrapper grammars with an unnamed root node).
+     *
+     * A node more than one container below the document root is never a
+     * semantic root in the default heuristic.
+     */
+    isSemanticRoot(node) {
+        if (!node.$container) {
+            return this.nameProvider.hasName(node);
+        }
+        if (!node.$container.$container) {
+            return !this.nameProvider.hasName(node.$container);
+        }
+        return false;
+    }
+    /**
+     * Fallback segment for unnamed intermediate ancestors —
+     * `containerProperty@containerIndex`. Returns `undefined` when the
+     * node has no container position, which short-circuits the walk.
+     */
+    unidentifiedSegment(node) {
+        if (node.$containerProperty === undefined || node.$containerIndex === undefined) {
+            return undefined;
+        }
+        return `${node.$containerProperty}@${node.$containerIndex}`;
+    }
+}
+//# sourceMappingURL=name-based-key-provider.js.map

package/lib/langium/keys/name-based-key-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"name-based-key-provider.js","sourceRoot":"","sources":["../../../src/langium/keys/name-based-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAMlF,OAAO,EAA2B,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAG1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,OAAO,oBAAoB;IAKR;IAJH,YAAY,CAAe;IAC3B,MAAM,CAAS;IAElC,YACsB,QAAgC,EACnD,UAA0B,EAAE;QADT,aAAQ,GAAR,QAAQ,CAAwB;QAGnD,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC;QACrD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC5G,CAAC;IAED,aAAa,CAAC,IAAc;QACzB,IAAI,CAAC,IAAI,EAAE,CAAC;YACT,OAAO,SAAS,CAAC;QACpB,CAAC;QACD,IAAI,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAC9E,IAAI,CAAC,EAAE,EAAE,CAAC;YACP,OAAO,SAAS,CAAC;QACpB,CAAC;QACD,IAAI,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,CAAC;QACb,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC;QAClD,IAAI,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;QAC7B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;YACzF,IAAI,OAAO,EAAE,CAAC;gBACX,EAAE,GAAG,OAAO,GAAG,SAAS,GAAG,EAAE,CAAC;YACjC,CAAC;YACD,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC;QAC9B,CAAC;QACD,OAAO,EAAE,CAAC;IACb,CAAC;IAED;;;;;;;OAOG;IACH,cAAc,CAAC,GAAW,EAAE,OAAgB;QACzC,OAAO,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAC/E,CAAC;IAED;;;;;;;;;;;;OAYG;IACO,cAAc,CAAC,IAAa;QACnC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;YAC/B,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACtD,CAAC;QACD,OAAO,KAAK,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACO,mBAAmB,CAAC,IAAa;QACxC,IAAI,IAAI,CAAC,kBAAkB,KAAK,SAAS,IAAI,IAAI,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;YAC/E,OAAO,SAAS,CAAC;QACpB,CAAC;QACD,OAAO,GAAG,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;IAC/D,CAAC;CACH"}

package/lib/langium/keys/positional-key-provider.d.ts

@@ -0,0 +1,41 @@
+/********************************************************************************
+ * 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 Tracer } from '@hydranium/protocol';
+import { type AstNode } from '@hydranium/langium';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type HydraniumLanguageServices } from '../language-module.js';
+import { type ElementKeyProvider } from './element-key-provider.js';
+/**
+ * Positional {@link ElementKeyProvider} — delegates to Langium's
+ * `AstNodeLocator.getAstNodePath` for a path like
+ * `/elements@0/children@2`.
+ *
+ * Use when the adopter is read-only / LSP-only with no diagram editor,
+ * or when sibling order is semantically meaningful and reorder is rare.
+ *
+ * # Stability profile
+ *
+ * - **Stable across all renames** — no names appear in the path.
+ * - **Always unique within a document** — positional segments are
+ *   unique by AST construction.
+ * - **Flips on sibling reorder / mid-array insert / mid-array delete**.
+ */
+export declare class PositionalKeyProvider implements ElementKeyProvider {
+    protected readonly services: HydraniumLanguageServices;
+    protected readonly tracer: Tracer;
+    constructor(services: HydraniumLanguageServices, options?: LogNameOptions);
+    getElementKey(node?: AstNode): string | undefined;
+    /**
+     * Self-resolving: `getAstNodePath` is invertible via `getAstNode`. The
+     * path is document-absolute, so `context` only identifies the document —
+     * resolution runs from its root regardless of where `context` sits.
+     */
+    resolveElement(key: string, context: AstNode): AstNode | undefined;
+}
+//# sourceMappingURL=positional-key-provider.d.ts.map

package/lib/langium/keys/positional-key-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"positional-key-provider.d.ts","sourceRoot":"","sources":["../../../src/langium/keys/positional-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,KAAK,OAAO,EAAY,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,qBAAsB,YAAW,kBAAkB;IAI1D,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,yBAAyB;IAHzD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,yBAAyB,EACtD,OAAO,GAAE,cAAmB;IAK/B,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAOjD;;;;OAIG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS;CAIpE"}

package/lib/langium/keys/positional-key-provider.js

@@ -0,0 +1,48 @@
+/********************************************************************************
+ * 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 { AstUtils } from '@hydranium/langium';
+/**
+ * Positional {@link ElementKeyProvider} — delegates to Langium's
+ * `AstNodeLocator.getAstNodePath` for a path like
+ * `/elements@0/children@2`.
+ *
+ * Use when the adopter is read-only / LSP-only with no diagram editor,
+ * or when sibling order is semantically meaningful and reorder is rare.
+ *
+ * # Stability profile
+ *
+ * - **Stable across all renames** — no names appear in the path.
+ * - **Always unique within a document** — positional segments are
+ *   unique by AST construction.
+ * - **Flips on sibling reorder / mid-array insert / mid-array delete**.
+ */
+export class PositionalKeyProvider {
+    services;
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.tracer = services.shared.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+    }
+    getElementKey(node) {
+        if (!node) {
+            return undefined;
+        }
+        return this.services.workspace.AstNodeLocator.getAstNodePath(node);
+    }
+    /**
+     * Self-resolving: `getAstNodePath` is invertible via `getAstNode`. The
+     * path is document-absolute, so `context` only identifies the document —
+     * resolution runs from its root regardless of where `context` sits.
+     */
+    resolveElement(key, context) {
+        const root = AstUtils.findRootNode(context);
+        return this.services.workspace.AstNodeLocator.getAstNode(root, key);
+    }
+}
+//# sourceMappingURL=positional-key-provider.js.map

package/lib/langium/keys/positional-key-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"positional-key-provider.js","sourceRoot":"","sources":["../../../src/langium/keys/positional-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAgB,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAK5D;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,qBAAqB;IAIT;IAHH,MAAM,CAAS;IAElC,YACsB,QAAmC,EACtD,UAA0B,EAAE;QADT,aAAQ,GAAR,QAAQ,CAA2B;QAGtD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC5G,CAAC;IAED,aAAa,CAAC,IAAc;QACzB,IAAI,CAAC,IAAI,EAAE,CAAC;YACT,OAAO,SAAS,CAAC;QACpB,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,GAAW,EAAE,OAAgB;QACzC,MAAM,IAAI,GAAG,QAAQ,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,cAAc,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACvE,CAAC;CACH"}

package/lib/langium/labeling/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 './label-provider.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/langium/labeling/index.d.ts.map

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

package/lib/langium/labeling/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 './label-provider.js';
+//# sourceMappingURL=index.js.map

package/lib/langium/labeling/index.js.map

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

package/lib/langium/labeling/label-provider.d.ts

@@ -0,0 +1,79 @@
+/********************************************************************************
+ * 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 Tracer } from '@hydranium/protocol';
+import { type AstNode } from '@hydranium/langium';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type HydraniumLanguageServices } from '../language-module.js';
+import { type NameProvider } from '../naming/name-provider.js';
+/** Construction-time options for {@link DefaultLabelProvider}. */
+export interface LabelProviderOptions extends LogNameOptions {
+    /**
+     * Property names checked, in order, when reading a node's own label.
+     * Default `['name']` — matches the common case where the grammar's
+     * `name` property is the human-readable label. Adopters whose grammar
+     * carries the display string on a different property override here;
+     * the property is deliberately separate from the
+     * {@link NameProvider}'s `nameProperties` (identifier axis).
+     */
+    readonly labelProperties?: readonly string[];
+}
+/**
+ * Labeling service — **the UI axis**, sibling to {@link NameProvider}.
+ *
+ * `NameProvider` answers "what identifier does the language engine index /
+ * resolve this node by" (read from `nameProperties`); `LabelProvider` answers
+ * "what string do we show a human for this node" (read from
+ * `labelProperties`). For the common adopter the two coincide (`['name']`),
+ * but they are genuinely distinct concerns — an adopter might resolve by an
+ * `id` field yet label by `name` — so the framework keeps them on separate
+ * services. Folding labeling back into `NameProvider` would mean a method that
+ * bypasses `nameProperties`, which is the thing that makes the identifier axis
+ * predictable.
+ *
+ * Depends one-way on {@link NameProvider}: {@link getLabelOrName} falls back
+ * to the identifier when no label exists, which is the only method that
+ * reaches across the two axes.
+ *
+ * **No total method on purpose.** "Produce a non-empty string come what may"
+ * is a per-call-site presentation decision, so both methods may return
+ * `undefined` and every caller owns its own tail `??`.
+ */
+export interface LabelProvider {
+    /**
+     * The node's own label from {@link LabelProviderOptions.labelProperties},
+     * or `undefined` when none is present (or for `undefined` input). The
+     * primitive — callers compose their own fallback.
+     */
+    getLabel(node?: AstNode): string | undefined;
+    /** Predicate form of {@link getLabel}. */
+    hasLabel(node?: AstNode): boolean;
+    /**
+     * The label, falling back to the identifier when no label exists:
+     * `getLabel(node) ?? NameProvider.getOwnName(node)`. May still be
+     * `undefined` (a fully anonymous node) — the caller supplies the final
+     * placeholder. The one method that bridges the label and name axes, so a UI
+     * site need inject only this service.
+     */
+    getLabelOrName(node?: AstNode): string | undefined;
+}
+/**
+ * Default {@link LabelProvider}. Reads a node's label from the configured
+ * {@link LabelProviderOptions.labelProperties} (default `['name']`).
+ */
+export declare class DefaultLabelProvider implements LabelProvider {
+    protected readonly services: HydraniumLanguageServices;
+    protected readonly labelProperties: readonly string[];
+    protected readonly nameProvider: NameProvider;
+    protected readonly tracer: Tracer;
+    constructor(services: HydraniumLanguageServices, options?: LabelProviderOptions);
+    getLabel(node?: AstNode): string | undefined;
+    hasLabel(node?: AstNode): boolean;
+    getLabelOrName(node?: AstNode): string | undefined;
+}
+//# sourceMappingURL=label-provider.d.ts.map

package/lib/langium/labeling/label-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-provider.d.ts","sourceRoot":"","sources":["../../../src/langium/labeling/label-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,kEAAkE;AAClE,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IACzD;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,aAAa;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAE7C,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAElC;;;;;;OAMG;IACH,cAAc,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CACrD;AAED;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IAMpD,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,yBAAyB;IALzD,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACtD,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IAC9C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,yBAAyB,EACtD,OAAO,GAAE,oBAAyB;IAOrC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAc5C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO;IAIjC,cAAc,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;CAGpD"}

package/lib/langium/labeling/label-provider.js

@@ -0,0 +1,44 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Default {@link LabelProvider}. Reads a node's label from the configured
+ * {@link LabelProviderOptions.labelProperties} (default `['name']`).
+ */
+export class DefaultLabelProvider {
+    services;
+    labelProperties;
+    nameProvider;
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.labelProperties = options.labelProperties ?? ['name'];
+        this.nameProvider = services.references.NameProvider;
+        this.tracer = services.shared.Tracer.for(options.logName ?? 'LabelProvider').trace('instantiated');
+    }
+    getLabel(node) {
+        if (!node) {
+            return undefined;
+        }
+        const indexed = node;
+        for (const property of this.labelProperties) {
+            const value = indexed[property];
+            if (typeof value === 'string') {
+                return value;
+            }
+        }
+        return undefined;
+    }
+    hasLabel(node) {
+        return this.getLabel(node) !== undefined;
+    }
+    getLabelOrName(node) {
+        return this.getLabel(node) ?? this.nameProvider.getOwnName(node);
+    }
+}
+//# sourceMappingURL=label-provider.js.map

package/lib/langium/labeling/label-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-provider.js","sourceRoot":"","sources":["../../../src/langium/labeling/label-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AA+DlF;;;GAGG;AACH,MAAM,OAAO,oBAAoB;IAMR;IALH,eAAe,CAAoB;IACnC,YAAY,CAAe;IAC3B,MAAM,CAAS;IAElC,YACsB,QAAmC,EACtD,UAAgC,EAAE;QADf,aAAQ,GAAR,QAAQ,CAA2B;QAGtD,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3D,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC;QACrD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACtG,CAAC;IAED,QAAQ,CAAC,IAAc;QACpB,IAAI,CAAC,IAAI,EAAE,CAAC;YACT,OAAO,SAAS,CAAC;QACpB,CAAC;QACD,MAAM,OAAO,GAAG,IAA0C,CAAC;QAC3D,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC;YAChB,CAAC;QACJ,CAAC;QACD,OAAO,SAAS,CAAC;IACpB,CAAC;IAED,QAAQ,CAAC,IAAc;QACpB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;IAC5C,CAAC;IAED,cAAc,CAAC,IAAc;QAC1B,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACpE,CAAC;CACH"}