@hydranium/core 1.0.0-next.10 → 1.0.0-next.103

package/lib/lsp/index.js

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 export * from './completion/hydranium-completion-provider.js';
-export * from './instrument-connection.js';
+export * from './lsp-latency.js';
 export * from './semantic-token-provider.js';
 export * from './language-module.js';
 export * from './shared-module.js';

package/lib/lsp/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lsp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,+CAA+C,CAAC;AAC9D,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wCAAwC,CAAC;AAEvD;;;;;;GAMG;AACH,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lsp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,+CAA+C,CAAC;AAC9D,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wCAAwC,CAAC;AAEvD;;;;;;GAMG;AACH,cAAc,4BAA4B,CAAC"}

package/lib/lsp/lsp-latency.d.ts

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

package/lib/lsp/lsp-latency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lsp-latency.d.ts","sourceRoot":"","sources":["../../src/lsp/lsp-latency.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAW,MAAM,gBAAgB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAiBtG"}

package/lib/lsp/lsp-latency.js

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

package/lib/lsp/lsp-latency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lsp-latency.js","sourceRoot":"","sources":["../../src/lsp/lsp-latency.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAKlF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAqC;IACpE,IAAI,CAAC,OAAO,EAAE,CAAC;QACZ,OAAO,SAAS,CAAC;IACpB,CAAC;IACD,OAAO;QACJ,eAAe,EAAE;YACd,aAAa,EAAE,CAAC,OAAgB,EAAE,IAAgD,EAAE,EAAE;gBACnF,oEAAoE;gBACpE,kEAAkE;gBAClE,qDAAqD;gBACrD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;oBACvB,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;gBACxB,CAAC;gBACD,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YAC5D,CAAC;SACH;KACH,CAAC;AACL,CAAC;AAED,kFAAkF;AAClF,SAAS,SAAS,CAAC,OAAgB;IAChC,OAAO,OAAQ,OAAgC,CAAC,MAAM,KAAK,QAAQ,CAAC;AACvE,CAAC"}

package/lib/lsp/semantic-token-provider.d.ts

@@ -6,7 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { type AstNode, type AstReflection, type LangiumDocument, type ReferenceInfo } from '@hydranium/langium';
+import { type AstNode, type AstReflection, type LangiumDocument, type LeafCstNode, type ReferenceInfo } from '@hydranium/langium';
 import { AbstractSemanticTokenProvider, type SemanticTokenAcceptor } from '@hydranium/langium/lsp';
 import { type CancellationToken } from 'vscode-languageserver';
 import { type NameProvider } from '../langium/naming/name-provider.js';
@@ -37,6 +37,22 @@ export interface HydraniumSemanticTokenProviderOptions {
      * render in the editor's default foreground.
      */
     readonly highlightKeywords?: boolean;
+    /**
+     * Also emit a `comment` token for every comment leaf of the CST.
+     *
+     * OFF by default for the same reason as {@link highlightKeywords}, and the
+     * loss is larger: a TextMate grammar distinguishes `comment.line` from
+     * `comment.block` and scopes the delimiters separately, where a semantic
+     * token carries one flat `comment` that overrides all of them. It exists
+     * for the host that ships no client-side grammar, where a comment otherwise
+     * renders in the editor's default foreground.
+     *
+     * What counts as a comment is every hidden terminal the lexer retains,
+     * which is every hidden terminal whose pattern is not whitespace. A grammar
+     * whose hidden non-whitespace terminal means something other than a comment
+     * is miscoloured, and this option is the place to say no.
+     */
+    readonly highlightComments?: boolean;
 }
 /**
  * Semantic-token provider that derives highlighting from ONE adopter-supplied
@@ -102,6 +118,23 @@ export declare abstract class AbstractHydraniumSemanticTokenProvider extends Abs
      * drops anything outside `currentRange` on its own.
      */
     protected computeHighlighting(document: LangiumDocument, acceptor: SemanticTokenAcceptor, cancelToken: CancellationToken): Promise<void>;
+    /**
+     * Emit a comment as ONE TOKEN PER LINE, never as one multi-line range.
+     *
+     * A block comment is the first token this provider emits that can span
+     * lines, and the upstream encoder mishandles that for a client which does
+     * not advertise `multilineTokenSupport` — the split path computes the first
+     * line's length as `nextLineOffset - range.start.character - 1`, subtracting
+     * a COLUMN from a document OFFSET, so the length is right only for a token
+     * starting on line 0 and overruns its line everywhere else. No client in
+     * this repository advertises that capability, so the broken path is the one
+     * taken. Splitting here means every range handed over starts and ends on one
+     * line and the arithmetic is never reached.
+     *
+     * Lines come from the leaf's own text rather than from the document, so
+     * nothing has to re-derive where the comment ends.
+     */
+    protected acceptComment(cst: LeafCstNode, acceptor: SemanticTokenAcceptor): void;
     protected highlightElement(node: AstNode, acceptor: SemanticTokenAcceptor): void | undefined | 'prune';
     /** Colour the node's own name, at whichever property the NameProvider reads it from. */
     protected highlightDeclaration(node: AstNode, acceptor: SemanticTokenAcceptor): void;

package/lib/lsp/semantic-token-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-token-provider.d.ts","sourceRoot":"","sources":["../../src/lsp/semantic-token-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,KAAK,OAAO,EACZ,KAAK,aAAa,EAKlB,KAAK,eAAe,EACpB,KAAK,aAAa,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,6BAA6B,EAAE,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACnG,OAAO,EAAE,KAAK,iBAAiB,EAA8C,MAAM,uBAAuB,CAAC;AAC3G,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAAE,CAAC;AAU1G,6EAA6E;AAC7E,MAAM,WAAW,qCAAqC;IACnD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8BAAsB,sCAAuC,SAAQ,6BAA6B;IAC/F,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IAC9C,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IAC7C,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,qCAAqC,CAAC;IAElE;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAsC;gBAEpF,QAAQ,EAAE,sBAAsB,EAAE,OAAO,GAAE,qCAA0C;IAOjG;;;;;;;;;;;;;;;OAeG;cACsB,mBAAmB,CACzC,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,qBAAqB,EAC/B,WAAW,EAAE,iBAAiB,GAC9B,OAAO,CAAC,IAAI,CAAC;cAsBG,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO;IAM/G,wFAAwF;IACxF,SAAS,CAAC,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAYpF,kFAAkF;IAClF,SAAS,CAAC,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAUnF;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAE5E,0FAA0F;IAC1F,SAAS,CAAC,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS;IAI1E,4GAA4G;IAC5G,SAAS,CAAC,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,iBAAiB,GAAG,SAAS;IAI9E,uFAAuF;IACvF,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;CAG9D"}
+{"version":3,"file":"semantic-token-provider.d.ts","sourceRoot":"","sources":["../../src/lsp/semantic-token-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,KAAK,OAAO,EACZ,KAAK,aAAa,EAMlB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,6BAA6B,EAAE,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACnG,OAAO,EAAE,KAAK,iBAAiB,EAA8C,MAAM,uBAAuB,CAAC;AAC3G,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAAE,CAAC;AAU1G,6EAA6E;AAC7E,MAAM,WAAW,qCAAqC;IACnD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAErC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8BAAsB,sCAAuC,SAAQ,6BAA6B;IAC/F,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IAC9C,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IAC7C,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,qCAAqC,CAAC;IAElE;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAsC;gBAEpF,QAAQ,EAAE,sBAAsB,EAAE,OAAO,GAAE,qCAA0C;IAOjG;;;;;;;;;;;;;;;OAeG;cACsB,mBAAmB,CACzC,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,qBAAqB,EAC/B,WAAW,EAAE,iBAAiB,GAC9B,OAAO,CAAC,IAAI,CAAC;IAoChB;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI;cAkB7D,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO;IAM/G,wFAAwF;IACxF,SAAS,CAAC,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAYpF,kFAAkF;IAClF,SAAS,CAAC,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAUnF;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAE5E,0FAA0F;IAC1F,SAAS,CAAC,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS;IAI1E,4GAA4G;IAC5G,SAAS,CAAC,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,iBAAiB,GAAG,SAAS;IAI9E,uFAAuF;IACvF,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;CAG9D"}

package/lib/lsp/semantic-token-provider.js

@@ -6,7 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { AstUtils, CstUtils, GrammarAST, interruptAndCheck } from '@hydranium/langium';
+import { AstUtils, CstUtils, GrammarAST, interruptAndCheck, isLeafCstNode } from '@hydranium/langium';
 import { AbstractSemanticTokenProvider } from '@hydranium/langium/lsp';
 import { SemanticTokenModifiers, SemanticTokenTypes } from 'vscode-languageserver';
 /** Normalise both {@link SemanticTokenKind} forms to the acceptor's shape. */
@@ -86,7 +86,9 @@ export class AbstractHydraniumSemanticTokenProvider extends AbstractSemanticToke
      */
     async computeHighlighting(document, acceptor, cancelToken) {
         await super.computeHighlighting(document, acceptor, cancelToken);
-        if (this.options.highlightKeywords !== true) {
+        const keywords = this.options.highlightKeywords === true;
+        const comments = this.options.highlightComments === true;
+        if (!keywords && !comments) {
             return;
         }
         const root = document.parseResult.value.$cstNode;
@@ -95,14 +97,59 @@ export class AbstractHydraniumSemanticTokenProvider extends AbstractSemanticToke
         }
         for (const cst of CstUtils.streamCst(root)) {
             await interruptAndCheck(cancelToken);
-            // The grammar source is the whole filter. A keyword is always a leaf,
-            // and the hidden leaves a comment or a run of whitespace contributes
-            // are sourced from a terminal rule rather than a `Keyword` — so
-            // neither a composite-node check nor a hidden-token check adds
-            // anything here.
-            if (GrammarAST.isKeyword(cst.grammarSource)) {
+            // A keyword is always a leaf with a `Keyword` grammar source, so that
+            // check alone separates it from everything else in the walk.
+            if (keywords && GrammarAST.isKeyword(cst.grammarSource)) {
                 acceptor({ cst, type: SemanticTokenTypes.keyword });
             }
+            // A comment leaf cannot be recognised the same way — the CST builder
+            // adds hidden nodes from the token alone, so `grammarSource` is
+            // undefined, which is also why the keyword filter never matches one.
+            //
+            // `hidden` alone IS the comment test, and nothing narrower is needed:
+            // the token builder groups a hidden terminal as `Lexer.SKIPPED` when
+            // its pattern matches whitespace and as `hidden` otherwise, so the
+            // lexer discards whitespace before a CST node is ever built and every
+            // hidden leaf that survives is a comment. Classifying the terminal
+            // again here would be a second guard for the same property, which no
+            // test could then distinguish. An adopter whose token builder RETAINS
+            // whitespace breaks that equivalence and would colour its gaps.
+            if (comments && isLeafCstNode(cst) && cst.hidden) {
+                this.acceptComment(cst, acceptor);
+            }
+        }
+    }
+    /**
+     * Emit a comment as ONE TOKEN PER LINE, never as one multi-line range.
+     *
+     * A block comment is the first token this provider emits that can span
+     * lines, and the upstream encoder mishandles that for a client which does
+     * not advertise `multilineTokenSupport` — the split path computes the first
+     * line's length as `nextLineOffset - range.start.character - 1`, subtracting
+     * a COLUMN from a document OFFSET, so the length is right only for a token
+     * starting on line 0 and overruns its line everywhere else. No client in
+     * this repository advertises that capability, so the broken path is the one
+     * taken. Splitting here means every range handed over starts and ends on one
+     * line and the arithmetic is never reached.
+     *
+     * Lines come from the leaf's own text rather than from the document, so
+     * nothing has to re-derive where the comment ends.
+     */
+    acceptComment(cst, acceptor) {
+        const lines = cst.text.split('\n');
+        for (let index = 0; index < lines.length; index++) {
+            // A `\r\n` document leaves the carriage return on the line's end;
+            // colouring it would extend the token past the visible text.
+            const length = lines[index].replace(/\r$/, '').length;
+            const character = index === 0 ? cst.range.start.character : 0;
+            if (length === 0) {
+                continue;
+            }
+            const line = cst.range.start.line + index;
+            acceptor({
+                range: { start: { line, character }, end: { line, character: character + length } },
+                type: SemanticTokenTypes.comment
+            });
         }
     }
     highlightElement(node, acceptor) {

package/lib/lsp/semantic-token-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-token-provider.js","sourceRoot":"","sources":["../../src/lsp/semantic-token-provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"semantic-token-provider.js","sourceRoot":"","sources":["../../src/lsp/semantic-token-provider.ts"],"names":[],"mappings":"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"}

package/lib/messages/carriers.d.ts

@@ -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
+ ********************************************************************************/
+import { type MessageDefinition, type ParamsArg, type ResolvedMessage } from '@hydranium/protocol';
+import type { AstNode, DiagnosticData, DiagnosticInfo, Properties, ValidationAcceptor } from '@hydranium/langium';
+import { Diagnostic } from 'vscode-languageserver-protocol';
+/**
+ * Raise a validation diagnostic from a declaration, so the call site never
+ * restates the code or the sentence.
+ *
+ * `code` is omitted from `info` because this owns it — the framework claims LSP
+ * `Diagnostic.code` for framework codes, which collides with no adopter today
+ * and is a stated rule rather than an accident. `data` is deliberately NOT
+ * omitted: Langium owns `data.code` for code-action dispatch, so a caller has to
+ * be able to request a quick fix. The identity is merged OVER whatever they
+ * pass, which makes the two conventions co-exist rather than compete.
+ *
+ * `data` admits adopter-owned keys beside Langium's, which is why the index
+ * signature is there rather than a bare `Partial<DiagnosticData>`. Langium's
+ * shape is closed, and a diagnostic that carries a COMPANION payload for its own
+ * surface to read — the field a form must highlight, say — has nowhere else to
+ * put it: an encoder projecting that payload reads `diagnostic.data`, so the
+ * narrower type made the identity and the companion mutually exclusive.
+ *
+ * The identity lands in both `code` and `data.hydranium` on purpose. `code` is
+ * what survives to the editor surface; Theia's converter drops `data` before the
+ * squiggle, so a parameterised diagnostic falls back to the server's English
+ * there while any adopter-owned surface can still render the parameterised form
+ * from the marker store.
+ *
+ * `DiagnosticInfo` must be Langium's own type: a `Parameters<ValidationAcceptor>[2]`
+ * shortcut compiles but loses the `property?: Properties<N>` relation. The `data`
+ * re-type has to be an intersection rather than an `Omit` alone, because Langium
+ * declares `data?: unknown` and an `unknown` cannot be spread.
+ */
+export declare function acceptMessage<S extends string, N extends AstNode, P extends Properties<N> = Properties<N>>(accept: ValidationAcceptor, severity: 'error' | 'warning' | 'info' | 'hint', message: MessageDefinition<S>, info: Omit<DiagnosticInfo<N, P>, 'code' | 'data'> & {
+    data?: Partial<DiagnosticData> & Record<string, unknown>;
+}, ...params: ParamsArg<S>): void;
+/**
+ * Recover the identity from a published diagnostic, for a surface that
+ * identifies or renders diagnostics itself.
+ *
+ * `Diagnostic.message` is `string | MarkupContent` in LSP 3.17+, so the text
+ * comes from upstream's own `Diagnostic.getMessageString` rather than a
+ * hand-rolled narrowing — consuming the library in its style, and one fewer
+ * place restating the union.
+ */
+export declare function resolvedFromDiagnostic(diagnostic: Diagnostic): ResolvedMessage | undefined;
+//# sourceMappingURL=carriers.d.ts.map

package/lib/messages/carriers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carriers.d.ts","sourceRoot":"","sources":["../../src/messages/carriers.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAIJ,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,eAAe,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAClH,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,EACvG,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,EAC/C,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC7B,IAAI,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAChH,GAAG,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GACvB,IAAI,CAMN;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,UAAU,GAAG,eAAe,GAAG,SAAS,CAK1F"}

package/lib/messages/carriers.js

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { hasMessageIdentity, messageData } from '@hydranium/protocol';
+import { Diagnostic } from 'vscode-languageserver-protocol';
+/**
+ * Raise a validation diagnostic from a declaration, so the call site never
+ * restates the code or the sentence.
+ *
+ * `code` is omitted from `info` because this owns it — the framework claims LSP
+ * `Diagnostic.code` for framework codes, which collides with no adopter today
+ * and is a stated rule rather than an accident. `data` is deliberately NOT
+ * omitted: Langium owns `data.code` for code-action dispatch, so a caller has to
+ * be able to request a quick fix. The identity is merged OVER whatever they
+ * pass, which makes the two conventions co-exist rather than compete.
+ *
+ * `data` admits adopter-owned keys beside Langium's, which is why the index
+ * signature is there rather than a bare `Partial<DiagnosticData>`. Langium's
+ * shape is closed, and a diagnostic that carries a COMPANION payload for its own
+ * surface to read — the field a form must highlight, say — has nowhere else to
+ * put it: an encoder projecting that payload reads `diagnostic.data`, so the
+ * narrower type made the identity and the companion mutually exclusive.
+ *
+ * The identity lands in both `code` and `data.hydranium` on purpose. `code` is
+ * what survives to the editor surface; Theia's converter drops `data` before the
+ * squiggle, so a parameterised diagnostic falls back to the server's English
+ * there while any adopter-owned surface can still render the parameterised form
+ * from the marker store.
+ *
+ * `DiagnosticInfo` must be Langium's own type: a `Parameters<ValidationAcceptor>[2]`
+ * shortcut compiles but loses the `property?: Properties<N>` relation. The `data`
+ * re-type has to be an intersection rather than an `Omit` alone, because Langium
+ * declares `data?: unknown` and an `unknown` cannot be spread.
+ */
+export function acceptMessage(accept, severity, message, info, ...params) {
+    const data = {
+        ...info.data,
+        ...messageData(message, ...params)
+    };
+    accept(severity, message.format(...params), { ...info, code: message.code, data });
+}
+/**
+ * Recover the identity from a published diagnostic, for a surface that
+ * identifies or renders diagnostics itself.
+ *
+ * `Diagnostic.message` is `string | MarkupContent` in LSP 3.17+, so the text
+ * comes from upstream's own `Diagnostic.getMessageString` rather than a
+ * hand-rolled narrowing — consuming the library in its style, and one fewer
+ * place restating the union.
+ */
+export function resolvedFromDiagnostic(diagnostic) {
+    if (!hasMessageIdentity(diagnostic.data)) {
+        return undefined;
+    }
+    return { ...diagnostic.data.hydranium, text: Diagnostic.getMessageString(diagnostic) };
+}
+//# sourceMappingURL=carriers.js.map

package/lib/messages/carriers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"carriers.js","sourceRoot":"","sources":["../../src/messages/carriers.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,kBAAkB,EAClB,WAAW,EAKb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,aAAa,CAC1B,MAA0B,EAC1B,QAA+C,EAC/C,OAA6B,EAC7B,IAAgH,EAChH,GAAG,MAAoB;IAEvB,MAAM,IAAI,GAA6E;QACpF,GAAG,IAAI,CAAC,IAAI;QACZ,GAAG,WAAW,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC;KACpC,CAAC;IACF,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AACtF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAsB;IAC1D,IAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,OAAO,SAAS,CAAC;IACpB,CAAC;IACD,OAAO,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,UAAU,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC;AAC1F,CAAC"}

package/lib/messages/index.d.ts

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Every user-facing message `@hydranium/core` raises, plus the carrier helpers
+ * that attach an identity to one.
+ *
+ * Declarations stay beside their call sites and are re-exported here, so this is
+ * enumeration rather than centralization: a code's package segment has to name
+ * the package that raises it. The English is a fallback, not a contract; the
+ * code is the contract, and renaming one is a breaking change.
+ */
+export * from './carriers.js';
+export * from './renderer.js';
+export { MODEL_UPDATE_EDIT } from '../langium/model-service/model-service.js';
+export { SEPARATOR_IN_NAME } from '../langium/naming/name-separator-validation.js';
+export { INVALID_DEDENT, UNEXPECTED_CHARACTER, MISSING_ITERATION, NO_VIABLE_ALTERNATIVE, TRAILING_INPUT, UNEXPECTED_TOKEN, UNPOPPABLE_LEXER_MODE, UNRESOLVED_REFERENCE } from '../langium/validation/document-validator.js';
+export { NO_LOADABLE_CONTENT } from '../langium/workspace/langium-documents.js';
+export { NO_SUCH_FILE, NO_SUCH_PATH, UNSUPPORTED_WRITE } from '../langium/workspace/in-memory-file-system-provider.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;GAQG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAE9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,EACJ,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACtB,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,wDAAwD,CAAC"}

package/lib/messages/index.js

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Every user-facing message `@hydranium/core` raises, plus the carrier helpers
+ * that attach an identity to one.
+ *
+ * Declarations stay beside their call sites and are re-exported here, so this is
+ * enumeration rather than centralization: a code's package segment has to name
+ * the package that raises it. The English is a fallback, not a contract; the
+ * code is the contract, and renaming one is a breaking change.
+ */
+export * from './carriers.js';
+export * from './renderer.js';
+export { MODEL_UPDATE_EDIT } from '../langium/model-service/model-service.js';
+export { SEPARATOR_IN_NAME } from '../langium/naming/name-separator-validation.js';
+export { INVALID_DEDENT, UNEXPECTED_CHARACTER, MISSING_ITERATION, NO_VIABLE_ALTERNATIVE, TRAILING_INPUT, UNEXPECTED_TOKEN, UNPOPPABLE_LEXER_MODE, UNRESOLVED_REFERENCE } from '../langium/validation/document-validator.js';
+export { NO_LOADABLE_CONTENT } from '../langium/workspace/langium-documents.js';
+export { NO_SUCH_FILE, NO_SUCH_PATH, UNSUPPORTED_WRITE } from '../langium/workspace/in-memory-file-system-provider.js';
+//# sourceMappingURL=index.js.map

package/lib/messages/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;GAQG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAE9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,EACJ,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACtB,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,wDAAwD,CAAC"}

package/lib/messages/renderer.d.ts

@@ -0,0 +1,136 @@
+/********************************************************************************
+ * 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 MessageDefinition, type ParamsArg, type ResolvedMessage, type Tracer } from '@hydranium/protocol';
+import { SimpleCache } from '@hydranium/langium';
+import type { ResponseError } from 'vscode-jsonrpc';
+import { Diagnostic } from 'vscode-languageserver-protocol';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import type { ServerLocale } from '../locale/server-locale.js';
+/** Construction options for {@link DefaultMessageRenderer}. */
+export type MessageRendererOptions = LogNameOptions;
+/**
+ * The render contract the `MessageRenderer` slot holds, implemented by
+ * {@link DefaultMessageRenderer}.
+ *
+ * An interface rather than the class, so the slot is compared STRUCTURALLY. A
+ * class-typed slot carries its `protected` members into every assignability
+ * check and TypeScript compares those nominally — which makes the slot
+ * unsatisfiable by a subclass declared against a second physical copy of this
+ * package, which any duplicated install produces. It also
+ * lets an adopter REPLACE this declaration rather than intersect with it, so
+ * slot resolution does not depend on the order a services type is written in.
+ *
+ * Every method carries a no-throw contract; see the implementation.
+ */
+export interface MessageRenderer {
+    renderDiagnostic(diagnostic: Diagnostic): string;
+    renderError(error: ResponseError<unknown>): string;
+    renderMessage<S extends string>(message: MessageDefinition<S>, ...params: ParamsArg<S>): string;
+}
+/**
+ * Renders every user-facing message the server sends, in the locale the server
+ * was handed at init. The framework ships no catalogue, so its own behaviour is
+ * a pass-through.
+ *
+ * Adopters override {@link translationsFor}: the public render methods carry
+ * the no-throw contract, and the catalogue lookup they wrap is what can fail.
+ *
+ * Two render methods rather than one, because what is useful to an adopter is
+ * the carrier's structured fields and the two carriers have different ones. A
+ * single `render(text)` would force an adopter to match English prose, which
+ * breaks on the first Langium reword.
+ */
+export declare class DefaultMessageRenderer implements MessageRenderer {
+    protected readonly tracer: Tracer;
+    protected readonly serverLocale: ServerLocale;
+    /**
+     * {@link translationsFor}'s answer per locale, `undefined` answers included —
+     * a `SimpleCache` distinguishes "absent" from "cached as none", which matters
+     * because shipping no catalogue is the framework's own hot path.
+     *
+     * `SimpleCache` rather than Langium's `WorkspaceCache`: the eviction axis
+     * there is document change, and a catalogue does not depend on documents, so
+     * it would evict on every build AND put a `DocumentBuilder` dependency on a
+     * service the shared tier declares free of one. Nothing evicts this: the
+     * locale arrives once per process. A subclass whose catalogue can change
+     * clears it.
+     */
+    protected readonly catalogues: SimpleCache<string | undefined, Record<string, string> | undefined>;
+    constructor(services: ServerSharedServicesMinimal, options?: MessageRendererOptions);
+    /**
+     * The sentence to publish for `diagnostic`, replacing its current `message`.
+     * Sees lexer and parser errors too, which Langium pushes onto the document
+     * without routing them through `toDiagnostic`.
+     *
+     * **Must not throw**, which is why the guard is here and not at the call
+     * site: this runs inside the `Validated` phase, and Langium's
+     * `notifyDocumentPhase` rethrows anything that is not a cancellation — so an
+     * escaping error leaves the document AT `Validated` with the phase's
+     * listeners never run, and the client receives no diagnostics for that file.
+     * A subclass overriding this method takes that contract on itself.
+     */
+    renderDiagnostic(diagnostic: Diagnostic): string;
+    /**
+     * The sentence to send for `error`, replacing its current `message`. Same
+     * no-throw contract as {@link renderDiagnostic}: an escaping error replaces a
+     * typed rejection the caller can handle with one it cannot.
+     */
+    renderError(error: ResponseError<unknown>): string;
+    /**
+     * The sentence for a declaration the caller holds directly, for a carrier
+     * with no slot to put an identity in.
+     *
+     * GLSP's action protocol is the case: every member of its message, status
+     * and reject actions is prose or an enum, so a code cannot travel and the
+     * raise site is the last place that still knows which message this is.
+     * Prefer {@link renderDiagnostic} / {@link renderError} wherever a carrier
+     * does hold the identity — they keep the render off the raise site, so an
+     * adopter's own messages ride the same one binding.
+     *
+     * Same no-throw contract as the carrier methods.
+     */
+    renderMessage<S extends string>(message: MessageDefinition<S>, ...params: ParamsArg<S>): string;
+    /**
+     * The catalogue for the current locale, or `undefined` for none — the
+     * framework's answer, shipping none. Overriding this leaves every identity
+     * decision, every pass-through and the no-throw guard in place.
+     *
+     * **Called once per locale, not once per message**, so an override may load
+     * a file or build a map without that cost landing per diagnostic. The
+     * corollary is that a catalogue mutated in place afterwards is not seen;
+     * clear {@link catalogues} to invalidate.
+     *
+     * An adopter wanting Langium's own uncoded sentences instead matches
+     * `Diagnostic.data.code` from an overridden {@link renderDiagnostic}, never
+     * the sentence.
+     */
+    protected translationsFor(_locale: string | undefined): Record<string, string> | undefined;
+    /**
+     * Resolve one identity against the current locale's catalogue.
+     *
+     * Reads the locale per call. Copying it into a field at construction pins
+     * whatever was there before init ran, which is always `undefined` — services
+     * compose first.
+     *
+     * The catalogue behind it is memoized, because a workspace-wide validation
+     * renders once per diagnostic and the naive override — parse a JSON file,
+     * build a map — then pays that per diagnostic rather than per locale.
+     */
+    protected render(message: ResolvedMessage): string;
+    /**
+     * Emit a failed render. Logged rather than swallowed: the fallback output is
+     * byte-identical to a correctly-configured default, so a throwing catalogue
+     * is otherwise invisible.
+     */
+    protected reportFailure(err: unknown, carrier: string): void;
+    /** Format the failed-render line. Override to name the adopter's catalogue entry. */
+    protected formatRenderFailure(err: unknown, carrier: string): string;
+}
+//# sourceMappingURL=renderer.d.ts.map

package/lib/messages/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/messages/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAKJ,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,MAAM,EACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAC5D,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG/D,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG,cAAc,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC7B,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAAC;IACjD,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;IACnD,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;CAClG;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAC3D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IAC9C;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,sEAA6E;gBAE9F,QAAQ,EAAE,2BAA2B,EAAE,OAAO,GAAE,sBAA2B;IAKvF;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM;IAUhD;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,MAAM;IAUlD;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,MAAM;IAkB/F;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS;IAI1F;;;;;;;;;;OAUG;IACH,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM;IAQlD;;;;OAIG;IACH,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5D,qFAAqF;IACrF,SAAS,CAAC,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;CAGtE"}