@hydranium/glsp-client-theia 1.0.0-next.10

package/lib/testing/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Subpath barrel for `@hydranium/glsp-client-theia/testing` — the
+// GLSP-module-specific Inversify test double. The cross-head doubles
+// (`makeStubOutputChannelManager`, `makeStubInversifyContext`) live in
+// `@hydranium/client-theia/testing`, alongside the logger they double for.
+__exportStar(require("./bind-recorder"), exports);
+//# sourceMappingURL=index.js.map

package/lib/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,kEAAkE;AAClE,qEAAqE;AACrE,uEAAuE;AACvE,2EAA2E;AAE3E,kDAAgC"}

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@hydranium/glsp-client-theia",
+  "version": "1.0.0-next.10",
+  "description": "Theia-coupled client primitives for GLSP heads built on @hydranium/glsp-server. Provides the action dispatcher, channel logger, and connection-handler bases that Theia-based adopters extend; companion of @hydranium/glsp-server.",
+  "keywords": [
+    "hydranium",
+    "langium",
+    "language-server",
+    "lsp",
+    "glsp",
+    "diagram",
+    "theia"
+  ],
+  "homepage": "https://github.com/eclipse-emfcloud/hydranium/tree/main/packages/glsp-client-theia",
+  "bugs": {
+    "url": "https://github.com/eclipse-emfcloud/hydranium/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-emfcloud/hydranium.git",
+    "directory": "packages/glsp-client-theia"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Hydranium Team"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./browser": {
+      "types": "./lib/browser/index.d.ts",
+      "default": "./lib/browser/index.js"
+    },
+    "./node": {
+      "types": "./lib/node/index.d.ts",
+      "default": "./lib/node/index.js"
+    },
+    "./testing": {
+      "types": "./lib/testing/index.d.ts",
+      "default": "./lib/testing/index.js"
+    },
+    "./lib/browser": {
+      "types": "./lib/browser/index.d.ts",
+      "default": "./lib/browser/index.js"
+    },
+    "./lib/node": {
+      "types": "./lib/node/index.d.ts",
+      "default": "./lib/node/index.js"
+    },
+    "./lib/testing": {
+      "types": "./lib/testing/index.d.ts",
+      "default": "./lib/testing/index.js"
+    },
+    "./style/diagram-loading.css": "./style/diagram-loading.css"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "src",
+    "style",
+    "!lib/**/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rimraf lib tsconfig.tsbuildinfo",
+    "lint": "eslint src test --max-warnings 0",
+    "prepack": "node -e \"const m=require('./package.json'),fs=require('node:fs');const missing=[m.main,...Object.values(m.bin||{})].filter(entry=>entry&&!fs.existsSync(entry));if(missing.length){console.error('prepack '+m.name+': not built ('+missing.join(', ')+' missing). Run the build before packing: a files entry that matches nothing is skipped silently, so the tarball would ship src only.');process.exit(1);}\"",
+    "test": "npm run typecheck:test && vitest run",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "watch": "tsc -b -w --preserveWatchOutput"
+  },
+  "devDependencies": {
+    "@eclipse-glsp/client": "2.7.0",
+    "@eclipse-glsp/theia-integration": "2.7.0",
+    "@hydranium/client-theia": "1.0.0-next.10",
+    "@hydranium/protocol": "1.0.0-next.10",
+    "@theia/core": "^1.71.0",
+    "@theia/output": "^1.71.0",
+    "@theia/process": "^1.71.0",
+    "@theia/workspace": "^1.71.0",
+    "@types/node": "^22.0.0",
+    "inversify": "6.2.2",
+    "rimraf": "^5.0.0",
+    "snabbdom": "3.5.1",
+    "typescript": "^5.8.0"
+  },
+  "peerDependencies": {
+    "@eclipse-glsp/client": "^2.6.0",
+    "@eclipse-glsp/theia-integration": "^2.6.0",
+    "@hydranium/client-theia": "1.0.0-next.10",
+    "@hydranium/protocol": "1.0.0-next.10",
+    "@theia/core": "^1.71.0",
+    "@theia/output": "^1.71.0",
+    "@theia/process": "^1.71.0",
+    "@theia/workspace": "^1.71.0",
+    "inversify": "^6.0.0",
+    "snabbdom": "^3.5.1"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "//exports": "The stylesheet key is an ASSET entry, not a module subpath, and it is spelled as the exact filename rather than `./style/*` so nothing becomes reachable automatically — the same no-wildcard property every other key here has. It exists because the widget's own import is package-RELATIVE, which `exports` does not gate, so the map's silence broke nobody inside the package while blocking every adopter who wants to `@import` the sheet, re-bundle it or override it by specifier; that failure reads as \"not exported under the conditions\" rather than as a missing entry. It has NO `./lib/style/...` twin, and must not grow one: the twin rule exists so a bare subpath is reachable from a node10 MODULE resolver, `tsc` emits no assets so there is no `lib/style/` to point at, and a bundler — which is what resolves a stylesheet — reads the map. `check:exports` carves out exactly this shape and asserts instead that the target file exists and is covered by `files`, which is the pair of mistakes an asset key can actually make.",
+  "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
+  "//sideEffects": "A stylesheet IS the side effect: `style/diagram-loading.css` is pulled in by a bare import in `browser/diagram-widget.js`, and a CSS module exports nothing, so under a blanket `false` a bundler drops the import as unused and the diagram loading overlay renders unstyled. Nothing fails at build time. The glob rather than the importing module, so a second stylesheet is covered without another edit; the widget itself is reached through its exported class and needs no flag."
+}

package/src/browser/action-dispatcher.ts

@@ -0,0 +1,257 @@
+/********************************************************************************
+ * 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 Action,
+   ComputedBoundsAction,
+   GLSPActionDispatcher,
+   GLSPModelSource,
+   LocalComputedBoundsAction,
+   MessageAction,
+   RejectAction,
+   RequestAction,
+   RequestBoundsAction,
+   RequestContextActions,
+   RequestModelAction,
+   RequestTypeHintsAction,
+   ResponseAction,
+   ServerAction,
+   SetDirtyStateAction,
+   SetEditModeAction,
+   SetMarkersAction,
+   SetModelAction,
+   SetTypeHintsAction,
+   StatusAction,
+   UpdateModelAction
+} from '@eclipse-glsp/client';
+import { ChannelLogger, ChannelTracer } from '@hydranium/client-theia/lib/browser';
+import { type Tracer } from '@hydranium/protocol';
+import { inject, injectable, unmanaged } from '@theia/core/shared/inversify';
+
+/** Default subset of action kinds the framework dispatcher will log: the GLSP
+ *  traffic an observer reading the Output channel typically wants to see. All
+ *  are standard `@eclipse-glsp/client` kinds; adopters with custom action kinds
+ *  extend via `extraLoggedKinds`. */
+export const HYDRANIUM_DEFAULT_LOGGED_KINDS: ReadonlySet<string> = new Set<string>([
+   SetModelAction.KIND,
+   UpdateModelAction.KIND,
+   RequestBoundsAction.KIND,
+   ComputedBoundsAction.KIND,
+   SetDirtyStateAction.KIND,
+   SetEditModeAction.KIND,
+   SetMarkersAction.KIND,
+   SetTypeHintsAction.KIND,
+   StatusAction.KIND,
+   MessageAction.KIND,
+   RejectAction.KIND,
+   RequestContextActions.KIND,
+   RequestModelAction.KIND,
+   RequestTypeHintsAction.KIND
+]);
+
+/** Default request → response kind pairs for GLSP 'flow' actions that do NOT
+ *  carry a requestId/responseId — so the dispatcher matches by kind (FIFO).
+ *  Id-based matching still wins when a requestId is present. */
+export const HYDRANIUM_DEFAULT_KIND_PAIRS: ReadonlyMap<string, string> = new Map<string, string>([
+   [RequestModelAction.KIND, SetModelAction.KIND],
+   [RequestTypeHintsAction.KIND, SetTypeHintsAction.KIND],
+   [RequestBoundsAction.KIND, ComputedBoundsAction.KIND]
+]);
+
+/** Additive options. Adopters with custom action kinds pass extras here; the
+ *  framework defaults always apply (you cannot un-log a kind the framework
+ *  considers worth logging — subclass + override `dispatch` if you must). */
+export interface HydraniumGlspActionDispatcherOptions {
+   readonly extraLoggedKinds?: Iterable<string>;
+   readonly extraKindPairs?: Iterable<readonly [string, string]>;
+   /** Replaces the default `summarize` body entirely. Use for adopter-domain
+    *  action kinds where the framework default returns ''. */
+   readonly summarize?: (action: Action) => string;
+}
+
+/**
+ * Wraps every dispatch so action traffic appears in the framework Output
+ * channel, interleaved with server log lines. Instrumenting the dispatcher
+ * (rather than per-kind handlers) catches ResponseActions that bypass the
+ * handler pipeline.
+ *
+ * The framework defaults cover the standard GLSP kinds worth logging, not every
+ * kind the protocol defines. Adopters with custom kinds either pass
+ * `extraLoggedKinds` / `extraKindPairs` to the constructor (via a
+ * `toDynamicValue` binding) or subclass and override.
+ */
+@injectable()
+export class HydraniumGlspActionDispatcher extends GLSPActionDispatcher {
+   @inject(ChannelLogger) protected readonly channel!: ChannelLogger;
+   @inject(ChannelTracer) protected readonly tracer!: Tracer;
+
+   protected readonly loggedKinds: ReadonlySet<string>;
+   protected readonly kindPairs: ReadonlyMap<string, string>;
+   protected readonly kindPairsReverse: ReadonlyMap<string, string>;
+
+   protected pairCounter = 0;
+   /** Pending requests keyed by requestId (for actions that carry one). */
+   protected pendingById = new Map<string, { id: number; start: number }>();
+   /** FIFO queue per response kind, used for `flow` pairs without requestId/responseId. */
+   protected pendingByKind = new Map<string, Array<{ id: number; start: number }>>();
+
+   constructor(@unmanaged() options?: HydraniumGlspActionDispatcherOptions) {
+      super();
+      const extraLogged = options?.extraLoggedKinds ? Array.from(options.extraLoggedKinds) : [];
+      this.loggedKinds = new Set<string>([...HYDRANIUM_DEFAULT_LOGGED_KINDS, ...extraLogged]);
+      const extraPairs = options?.extraKindPairs ? Array.from(options.extraKindPairs) : [];
+      const pairs = new Map<string, string>([...HYDRANIUM_DEFAULT_KIND_PAIRS, ...extraPairs]);
+      this.kindPairs = pairs;
+      this.kindPairsReverse = new Map<string, string>(Array.from(pairs, ([req, res]) => [res, req]));
+      if (options?.summarize) {
+         this.summarize = options.summarize;
+      }
+   }
+
+   override initialize(): Promise<void> {
+      // `initialize()` is called many times; super is idempotent, but our callback registration
+      // isn't. Register the timing log only on the first call (when super.initialized is unset).
+      if (!this.initialized) {
+         this.registerInitTiming();
+      }
+      return super.initialize();
+   }
+
+   /**
+    * Register the one-shot 'model initialized' timing line. Instrumentation
+    * only — guarded so a tracer failure degrades logging rather than aborting
+    * diagram init. `initialize()` runs inside `DiagramLoader.load()`, whose
+    * caller (`GLSPDiagramWidget.onAfterAttach`) neither awaits nor catches the
+    * returned promise; an error thrown here would therefore escape as an
+    * uncaught rejection that blanks the diagram with no server-side signal.
+    */
+   protected registerInitTiming(): void {
+      try {
+         this.tracer.time('Model initialized', () => this.onceModelInitialized(), 'info', { logAfterMs: 0 });
+      } catch (err) {
+         this.channel.error('Failed to register model-initialized timing instrumentation', err);
+      }
+   }
+
+   override dispatch(action: Action): Promise<void> {
+      if (this.loggedKinds.has(action.kind)) {
+         this.logAction(action);
+      }
+      return super.dispatch(action);
+   }
+
+   protected logAction(action: Action): void {
+      const { verb, direction } = this.classify(action);
+      const summary = this.summarize(action);
+      const timing = this.trackPair(action);
+      const parts = [`${verb} action '${action.kind}'`, `[${direction}]`];
+      if (summary) {
+         parts.push(`[${summary}]`);
+      }
+      if (timing) {
+         parts.push(timing);
+      }
+      this.channel.trace(parts.join(' '));
+   }
+
+   protected classify(action: Action): { verb: string; direction: string } {
+      // GLSP marks client-produced computedBounds as ServerAction to suppress forwarding; stays local.
+      if (LocalComputedBoundsAction.is(action)) {
+         return { verb: 'Process', direction: 'client → client' };
+      }
+      // Marked by GLSPModelSource.messageReceived — arrived from the server.
+      if (ServerAction.is(action)) {
+         return { verb: 'Receive', direction: 'server → client' };
+      }
+      // GLSPModelSource is registered as handler for every server-handled kind (configureServeActions),
+      // so its presence means the action will be forwarded to the server.
+      const handlers = this.actionHandlerRegistry.get(action.kind);
+      if (handlers.some(handler => handler instanceof GLSPModelSource)) {
+         return { verb: 'Send', direction: 'client → server' };
+      }
+      return { verb: 'Process', direction: 'client → client' };
+   }
+
+   /** Emit `[request #N]` on the request side, `[response #N, Xms]` on the matching response side.
+    *  Match first by requestId/responseId, then by known kind pairs (FIFO). */
+   protected trackPair(action: Action): string {
+      // Response side.
+      if (ResponseAction.hasValidResponseId(action)) {
+         const entry = this.pendingById.get(action.responseId);
+         if (entry) {
+            this.pendingById.delete(action.responseId);
+            return this.formatResponse(entry);
+         }
+      }
+      if (this.kindPairsReverse.has(action.kind)) {
+         const queue = this.pendingByKind.get(action.kind);
+         const entry = queue?.shift();
+         if (entry) {
+            return this.formatResponse(entry);
+         }
+      }
+      // Request side.
+      if (RequestAction.is(action) && action.requestId) {
+         const entry = { id: ++this.pairCounter, start: performance.now() };
+         this.pendingById.set(action.requestId, entry);
+         return `[request #${entry.id}]`;
+      }
+      if (this.kindPairs.has(action.kind)) {
+         const responseKind = this.kindPairs.get(action.kind)!;
+         const entry = { id: ++this.pairCounter, start: performance.now() };
+         const queue = this.pendingByKind.get(responseKind) ?? [];
+         queue.push(entry);
+         this.pendingByKind.set(responseKind, queue);
+         return `[request #${entry.id}]`;
+      }
+      return '';
+   }
+
+   protected formatResponse(entry: { id: number; start: number }): string {
+      const elapsed = Math.round(performance.now() - entry.start);
+      return `[response #${entry.id}, ${elapsed}ms]`;
+   }
+
+   protected summarize(action: Action): string {
+      if (SetModelAction.is(action) || UpdateModelAction.is(action)) {
+         const root = action.newRoot;
+         return `rootType=${root?.type ?? 'none'} children=${root?.children?.length ?? 0}`;
+      }
+      if (RequestBoundsAction.is(action)) {
+         return `rootType=${action.newRoot.type} children=${action.newRoot.children?.length ?? 0}`;
+      }
+      if (ComputedBoundsAction.is(action)) {
+         return `bounds=${action.bounds.length}`;
+      }
+      if (SetDirtyStateAction.is(action)) {
+         return `isDirty=${action.isDirty} reason=${action.reason ?? 'n/a'}`;
+      }
+      if (SetEditModeAction.is(action)) {
+         return `editMode=${action.editMode}`;
+      }
+      if (SetMarkersAction.is(action)) {
+         return `markers=${action.markers.length}`;
+      }
+      if (StatusAction.is(action) || MessageAction.is(action)) {
+         // severity=NONE with empty message is the conventional 'clear' signal.
+         const clear = action.severity === 'NONE' && !action.message ? ' (clear)' : '';
+         return `severity=${action.severity} message="${action.message.slice(0, 160)}"${clear}`;
+      }
+      if (RejectAction.is(action)) {
+         return `reason="${action.message.slice(0, 160)}"`;
+      }
+      if (SetTypeHintsAction.is(action)) {
+         return `shapes=${action.shapeHints.length} edges=${action.edgeHints.length}`;
+      }
+      if (RequestContextActions.is(action)) {
+         return `contextId=${action.contextId}`;
+      }
+      return '';
+   }
+}

package/src/browser/client-contribution.ts

@@ -0,0 +1,100 @@
+/********************************************************************************
+ * 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 GLSPClient } from '@eclipse-glsp/client';
+import { BaseGLSPClientContribution } from '@eclipse-glsp/theia-integration';
+import { Deferred } from '@theia/core/lib/common/promise-util';
+import { inject, injectable, unmanaged } from '@theia/core/shared/inversify';
+import { OutputChannelManager } from '@theia/output/lib/browser/output-channel';
+import { WorkspaceService } from '@theia/workspace/lib/browser';
+
+/** Options for `HydraniumGlspClientContribution`. The channel name is the
+ *  Theia Output channel both the LSP and GLSP sides write to (so log lines
+ *  interleave); the ready marker is a server-printed substring that signals
+ *  "the GLSP server is accepting client connections". */
+export interface ClientContributionOptions {
+   readonly languageContributionId: string;
+   readonly channelName: string;
+   readonly readyMarker: string;
+}
+
+/**
+ * Theia GLSP client contribution for adopters whose GLSP server runs in a
+ * sideloaded VS Code extension process (or any other deferred-start setup).
+ * The behaviours adopters reliably need are lifted:
+ *
+ *   1. `waitForBackendConnected`: tail the OutputChannel for a server-printed
+ *      ready marker. While a socket connection might open earlier, the GLSP
+ *      server typically does internal initialisation before it can accept
+ *      client connections — we wait for it to say so.
+ *   2. `start`: defer until a workspace is opened. If Theia starts without a
+ *      workspace, this prevents the frontend-backend connection (and its
+ *      "connecting" progress spinner) from firing prematurely.
+ *
+ * A `GLSPClient` override filtering inbound messages by clientId is
+ * deliberately NOT provided: upstream's `BaseJsonrpcGLSPClient.onActionMessage`
+ * already filters by clientId, so the `TheiaJsonrpcGLSPClient` returned by
+ * `BaseGLSPClientContribution.createGLSPClient` is correct as-is.
+ */
+@injectable()
+export class HydraniumGlspClientContribution extends BaseGLSPClientContribution {
+   @inject(OutputChannelManager) protected outputChannelManager!: OutputChannelManager;
+   @inject(WorkspaceService) protected readonly workspaceService!: WorkspaceService;
+
+   readonly id: string;
+   protected readonly channelName: string;
+   protected readonly readyMarker: string;
+
+   constructor(@unmanaged() options: ClientContributionOptions) {
+      super();
+      this.id = options.languageContributionId;
+      this.channelName = options.channelName;
+      this.readyMarker = options.readyMarker;
+   }
+
+   /** Wait for the server to print its ready marker into the OutputChannel.
+    *  Resolves immediately if the marker is already present (server started
+    *  before the client contribution mounted). */
+   protected async waitForBackendConnected(): Promise<void> {
+      const channel = this.outputChannelManager.getChannel(this.channelName);
+      const channelText =
+         (channel as unknown as { resource?: { textModel?: { getValue(): string } } }).resource?.textModel?.getValue() ?? '';
+      if (channelText.includes(this.readyMarker)) {
+         return;
+      }
+      const deferred = new Deferred<void>();
+      const channelListener = channel.onContentChange(() => {
+         const text = (channel as unknown as { resource?: { textModel?: { getValue(): string } } }).resource?.textModel?.getValue() ?? '';
+         if (text.includes(this.readyMarker)) {
+            channelListener.dispose();
+            deferred.resolve();
+         }
+      });
+      return deferred.promise;
+   }
+
+   protected override async start(glspClient: GLSPClient): Promise<void> {
+      // Defer starting the GLSP client until a workspace is opened. If Theia
+      // starts without a workspace, this prevents creating the frontend-
+      // backend connection (and showing the "connecting" progress) prematurely.
+      const roots = this.workspaceService.tryGetRoots();
+      if (!roots || roots.length === 0) {
+         await new Promise<void>(resolve => {
+            const disposable = this.workspaceService.onWorkspaceChanged(changedRoots => {
+               if (changedRoots && changedRoots.length > 0) {
+                  disposable.dispose();
+                  resolve();
+               }
+            });
+         });
+      }
+      await this.waitForBackendConnected();
+      return super.start(glspClient);
+   }
+}