@hydranium/glsp-client 0.0.0-stage → 1.0.0-next.298

package/src/action-dispatcher.ts

@@ -0,0 +1,273 @@
+/********************************************************************************
+ * 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,
+   CheckEdgeResultAction,
+   ComputedBoundsAction,
+   GLSPActionDispatcher,
+   GLSPModelSource,
+   LocalComputedBoundsAction,
+   MessageAction,
+   RejectAction,
+   RequestAction,
+   RequestBoundsAction,
+   RequestCheckEdgeAction,
+   RequestContextActions,
+   RequestModelAction,
+   RequestTypeHintsAction,
+   ResponseAction,
+   ServerAction,
+   SetDirtyStateAction,
+   SetEditModeAction,
+   SetMarkersAction,
+   SetModelAction,
+   SetTypeHintsAction,
+   StatusAction,
+   UpdateModelAction
+} from '@eclipse-glsp/client';
+import { type Clock, type Logger, type Stopwatch, SystemClock, type Tracer } from '@hydranium/protocol';
+import { inject, injectable, optional, unmanaged } from 'inversify';
+import { HydraniumClientTypes } from './types';
+
+/** Default subset of action kinds the framework dispatcher will log: the GLSP
+ *  traffic an observer reading the log 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,
+   RequestCheckEdgeAction.KIND,
+   CheckEdgeResultAction.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 host's log, the Theia
+ * Output channel or a page's console, interleaved with server log lines where
+ * the host shows both. 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(HydraniumClientTypes.Logger) protected readonly hydraniumLogger!: Logger;
+   @inject(HydraniumClientTypes.Tracer) protected readonly tracer!: Tracer;
+   /** Times each request to its response: the diagram container's {@link Clock}, or a `SystemClock`. */
+   @inject(HydraniumClientTypes.Clock) @optional() protected readonly clock: Clock = new SystemClock();
+
+   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; sinceRequest: Stopwatch }>();
+   /** FIFO queue per response kind, used for `flow` pairs without requestId/responseId. */
+   protected pendingByKind = new Map<string, Array<{ id: number; sinceRequest: Stopwatch }>>();
+
+   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.hydraniumLogger.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.hydraniumLogger.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, sinceRequest: this.clock.stopwatch() };
+         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, sinceRequest: this.clock.stopwatch() };
+         const queue = this.pendingByKind.get(responseKind) ?? [];
+         queue.push(entry);
+         this.pendingByKind.set(responseKind, queue);
+         return `[request #${entry.id}]`;
+      }
+      return '';
+   }
+
+   protected formatResponse(entry: { id: number; sinceRequest: Stopwatch }): string {
+      const elapsed = Math.round(entry.sinceRequest.elapsedMs);
+      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}`;
+      }
+      if (RequestCheckEdgeAction.is(action) || CheckEdgeResultAction.is(action)) {
+         return this.formatEdgeCheck(action);
+      }
+      return '';
+   }
+
+   /** An edge check and, on the result, its verdict, so the log shows why an edge tool refused a target. */
+   protected formatEdgeCheck(action: RequestCheckEdgeAction | CheckEdgeResultAction): string {
+      const verdict = CheckEdgeResultAction.is(action) ? ` isValid=${action.isValid}` : '';
+      return `edgeType=${action.edgeType} source=${action.sourceElementId} target=${action.targetElementId ?? 'none'}${verdict}`;
+   }
+}

package/src/diagram-load-failed.ts

@@ -0,0 +1,22 @@
+/********************************************************************************
+ * 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 { defineMessage } from '@hydranium/protocol';
+
+/**
+ * What a user reads when a diagram load fails: `reason` is the described
+ * error. Formatted in English by `HydraniumDiagramLoader`; a host that knows
+ * the reading user's locale renders the same sentence under a key of its own
+ * by overriding its `loadFailureLabel`, as the Theia loader does.
+ *
+ * In a module of its own, apart from the loader that raises it, so the
+ * `./messages` barrel loads no `@eclipse-glsp/client`: a bundle that only
+ * translates the code must not need GLSP's stylesheets.
+ */
+export const DIAGRAM_LOAD_FAILED = defineMessage('hydranium/glsp-client/diagram-load-failed', 'Diagram failed to load: {reason}');

package/src/diagram-loader.ts

@@ -0,0 +1,173 @@
+/********************************************************************************
+ * 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 { DiagramLoader, type DiagramLoadingOptions, StatusAction } from '@eclipse-glsp/client';
+import { Deferred, describeError, type Logger } from '@hydranium/protocol';
+import { inject, injectable } from 'inversify';
+import { DIAGRAM_LOAD_FAILED } from './diagram-load-failed';
+import { HydraniumClientTypes } from './types';
+
+/**
+ * How a diagram load ended. A discriminated union rather than a boolean or a
+ * string: a consumer showing a pending indicator has to distinguish "not settled
+ * yet" (`undefined`) from either terminal state, and the failed arm has to carry
+ * enough for that consumer to decide whether *it* is now the only thing that can
+ * report the failure — see {@link DiagramLoadFailure.surfaced}.
+ */
+export type DiagramLoadOutcome = DiagramLoadSuccess | DiagramLoadFailure;
+
+export interface DiagramLoadSuccess {
+   readonly status: 'loaded';
+}
+
+export interface DiagramLoadFailure {
+   readonly status: 'failed';
+   /** The thrown value, verbatim. `unknown` because a rejection can be anything. */
+   readonly error: unknown;
+   /**
+    * Whether the `severity: 'ERROR'` {@link StatusAction} reached the action
+    * dispatcher. It says nothing about whether a status overlay shows it.
+    *
+    * `false` means the report itself failed, which happens when the action
+    * dispatcher is the thing that could not initialize. A consumer that covers
+    * the canvas must then render the failure itself: it is the only surface
+    * left, and removing its overlay would leave a blank diagram whose only
+    * explanation is a line in the log — the exact failure mode this loader
+    * exists to prevent.
+    */
+   readonly surfaced: boolean;
+}
+
+/**
+ * Diagram loader that never lets a load failure vanish.
+ *
+ * `DiagramLoader.load()` orchestrates the full diagram-init path — action
+ * dispatcher init, GLSP-client connect + server `initialize`, the first
+ * `RequestModelAction`, and the model-initialization constraint. Of these only
+ * the `IDiagramStartup` hooks are wrapped by the base loader (it logs them to
+ * `console.error`); the dispatcher-init / connection / request-model steps are
+ * not. The Theia widget that drives loading
+ * (`@eclipse-glsp/theia-integration`'s `GLSPDiagramWidget.onAfterAttach`)
+ * calls `load()` *without awaiting or catching it*, so any rejection becomes an
+ * uncaught promise rejection visible only in the browser devtools console —
+ * nothing reaches the e2e output, the server log, or a Theia log sink, and the
+ * diagram just stays blank.
+ *
+ * This subclass closes that gap: it catches every load failure, routes it to
+ * the host's logger (in Theia the Output channel the server log and action
+ * traffic share, so it is discoverable where a developer already looks), and
+ * surfaces a persistent error to the user via a `severity: 'ERROR'`
+ * {@link StatusAction} on the diagram's status overlay. It deliberately does
+ * **not** rethrow — the caller drops the promise, so rethrowing would only
+ * reproduce the uncaught rejection this exists to prevent.
+ *
+ * It also publishes the load's terminal state ({@link loadOutcome} /
+ * {@link onceLoadSettled}) so a pending indicator has one authority to key on.
+ * The Theia diagram widget uses it to cover the canvas while loading; see
+ * {@link settle} for why the signal cannot be derived from the error
+ * `StatusAction` instead.
+ *
+ * Bound by `createGlspClientModule` via `rebind(DiagramLoader)`.
+ */
+@injectable()
+export class HydraniumDiagramLoader extends DiagramLoader {
+   @inject(HydraniumClientTypes.Logger) protected readonly hydraniumLogger!: Logger;
+
+   protected readonly settled = new Deferred<DiagramLoadOutcome>();
+   protected outcome?: DiagramLoadOutcome;
+
+   /** Terminal state of the load, or `undefined` while it is still in flight.
+    *  The synchronous companion of {@link onceLoadSettled}, for a consumer that
+    *  must decide something in the same tick (e.g. whether to show an indicator
+    *  at all when re-attaching an already-loaded diagram). */
+   get loadOutcome(): DiagramLoadOutcome | undefined {
+      return this.outcome;
+   }
+
+   /** Resolves once the load reaches a terminal state — on success **and** on
+    *  failure, so a caller awaiting it cannot hang. Never rejects. */
+   onceLoadSettled(): Promise<DiagramLoadOutcome> {
+      return this.settled.promise;
+   }
+
+   override async load(options?: DiagramLoadingOptions): Promise<void> {
+      try {
+         await super.load(options);
+         this.settle({ status: 'loaded' });
+      } catch (err) {
+         // Report first, settle second, and carry whether the report landed.
+         const surfaced = await this.reportLoadFailure(err);
+         this.settle({ status: 'failed', error: err, surfaced });
+      }
+   }
+
+   /**
+    * Record the terminal state and release {@link onceLoadSettled}. Idempotent —
+    * the first outcome wins, so a reload cannot flip a settled indicator.
+    *
+    * This runs unconditionally after {@link reportLoadFailure}, *including* when
+    * the status dispatch inside it threw. That is the load-bearing property: when
+    * the action dispatcher is itself the thing that failed to initialize — the
+    * exact failure this class exists for — no `StatusAction` ever lands, so a
+    * consumer observing actions would wait forever. Settling here means a pending
+    * indicator always comes down, and `surfaced: false` tells that consumer it is
+    * now the only thing that can report the failure.
+    */
+   protected settle(outcome: DiagramLoadOutcome): void {
+      if (this.outcome !== undefined) {
+         return;
+      }
+      this.outcome = outcome;
+      this.settled.resolve(outcome);
+   }
+
+   /**
+    * Route a diagram-load failure to the host's logger and the status overlay.
+    * The status dispatch is itself guarded: when the action dispatcher is the
+    * thing that failed to initialize, dispatching may throw too, and a failure
+    * to *report* the failure must not re-escape as an uncaught rejection.
+    *
+    * @returns whether the `StatusAction` reached the dispatcher — i.e. whether the
+    * user can see this failure on the diagram. The log line always happens, so
+    * the return value is specifically about the *user-visible* report; a `false`
+    * makes {@link DiagramLoadFailure.surfaced} false and hands the job to whoever
+    * is covering the canvas.
+    */
+   protected async reportLoadFailure(err: unknown): Promise<boolean> {
+      const label = this.loadFailureLabel(err);
+      this.hydraniumLogger.error(label, err);
+      try {
+         await this.actionDispatcher.dispatch(StatusAction.create(label, { severity: 'ERROR' }));
+         return true;
+      } catch (statusErr) {
+         this.hydraniumLogger.error('Failed to surface the diagram-load failure on the status overlay', statusErr);
+         return false;
+      }
+   }
+
+   /**
+    * The sentence a failed load is reported with, on every surface that reports
+    * it. Public because the canvas overlay is one of those surfaces and lives in
+    * another class, where a second copy of the sentence would drift.
+    *
+    * English, formatted from {@link DIAGRAM_LOAD_FAILED}: this tier knows no
+    * locale. A host that does renders the code through its own mechanism by
+    * overriding this method, so every surface, the log line included, carries
+    * the one sentence the user reads.
+    */
+   loadFailureLabel(err: unknown): string {
+      return DIAGRAM_LOAD_FAILED.format({ reason: this.formatError(err) });
+   }
+
+   /** Render a thrown value as a message. Shared so the log line, the status
+    *  overlay and any consumer rendering {@link DiagramLoadFailure.error} agree. */
+   protected formatError(err: unknown): string {
+      return describeError(err);
+   }
+}

package/src/edge.ts

@@ -0,0 +1,65 @@
+/********************************************************************************
+ * 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 BindingContext,
+   type Bounds,
+   configureDefaultModelElements,
+   DefaultTypes,
+   GEdge,
+   GEdgeView,
+   isBounds,
+   overrideModelElement,
+   type Point
+} from '@eclipse-glsp/client';
+
+/**
+ * GLSP's edge, with an empty route transforming its children through the
+ * origin.
+ *
+ * `GEdge` offsets a child by the bounds of its routing points, and sprotty's
+ * `getRouteBounds` answers `NaN` for an empty route, which an edge without
+ * bendpoints always has. An edge label's bounds then come out `NaN`, and a
+ * fit-to-screen over every element lands the viewport at `translate(NaN,NaN)`,
+ * where every shape fails its visibility check and the canvas goes blank.
+ *
+ * Register your own edge types with this class in place of `GEdge`; sprotty
+ * fixes a type's class when it is registered, so an edge type registered with
+ * `GEdge` keeps the defect. Patching `GEdge`'s prototype would reach those
+ * types too, and is not done: it is no extension point of GLSP's.
+ */
+export class HydraniumGEdge extends GEdge {
+   override localToParent(point: Point | Bounds): Bounds {
+      return this.routingPoints.length === 0 ? asBounds(point) : super.localToParent(point);
+   }
+
+   override parentToLocal(point: Point | Bounds): Bounds {
+      return this.routingPoints.length === 0 ? asBounds(point) : super.parentToLocal(point);
+   }
+}
+
+/** The shape `GEdge` returns: a point gains the size `-1`, bounds keep theirs. */
+function asBounds(point: Point | Bounds): Bounds {
+   return { x: point.x, y: point.y, width: isBounds(point) ? point.width : -1, height: isBounds(point) ? point.height : -1 };
+}
+
+/**
+ * GLSP's default model elements, with `DefaultTypes.EDGE` built as a
+ * {@link HydraniumGEdge}.
+ *
+ * Call it from your diagram module in place of GLSP's
+ * `configureDefaultModelElements`. The replacement cannot come from the
+ * binder: a diagram module is loaded after the host's, and GLSP's model
+ * registry gives a type to whichever registration came last, so a replacement
+ * bound before the defaults is the one overwritten.
+ */
+export function configureHydraniumModelElements(context: Pick<BindingContext, 'bind' | 'isBound'>): void {
+   configureDefaultModelElements(context);
+   overrideModelElement(context, DefaultTypes.EDGE, HydraniumGEdge, GEdgeView);
+}

package/src/glsp-client-module.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 BindingContext,
+   DiagramLoader,
+   GLSPActionDispatcher,
+   GLSPHiddenBoundsUpdater,
+   RankedSelectMouseListener,
+   StatusOverlay,
+   TYPES
+} from '@eclipse-glsp/client';
+import { type Clock, ConsoleLogger, DefaultTracer, type Logger, SystemClock } from '@hydranium/protocol';
+import { HydraniumGlspActionDispatcher } from './action-dispatcher';
+import { HydraniumDiagramLoader } from './diagram-loader';
+import { HydraniumHiddenBoundsUpdater } from './hidden-bounds-updater';
+import { HydraniumSelectMouseListener } from './select-mouse-listener';
+import { SprottyLoggerAdapter } from './sprotty-logger-adapter';
+import { HydraniumStatusOverlay } from './status-overlay';
+import { HydraniumClientTypes } from './types';
+
+/** Options for {@link createGlspClientModule}. */
+export interface GlspClientModuleOptions {
+   /** The host's logger, bound on `HydraniumClientTypes.Logger` in place of any
+    *  binding the host made. Absent, the token keeps the host's own binding, or
+    *  gets a `ConsoleLogger` when it has none. */
+   readonly logger?: Logger;
+}
+
+/**
+ * Binds the framework's client classes into a GLSP diagram container, whatever
+ * hosts it: the instrumented action dispatcher, the failure-reporting diagram
+ * loader, the route-repairing hidden-bounds updater, the status overlay that
+ * stays on the page, the select listener whose plain click replaces a pending
+ * selection, and a sprotty logger that reports through the host's.
+ *
+ * Call it from the module a host adds AFTER GLSP's defaults, since every class
+ * here replaces a token those defaults bind; `rebind` on an unbound token
+ * throws. A host that wants one GLSP default back rebinds that token after
+ * this call, the same one-line move this function makes.
+ *
+ * The logger and tracer tokens are bound only when the host has not bound
+ * them, so a host with a richer logger binds `HydraniumClientTypes.Logger`
+ * first and passes no option. The tracer composes the bound logger and clock.
+ * Bind the tokens in the container this runs in: `isBound` sees a parent
+ * container's binding, which `rebind` cannot replace.
+ */
+export function createGlspClientModule(context: BindingContext, options: GlspClientModuleOptions = {}): void {
+   const { bind, isBound, rebind } = context;
+   if (options.logger) {
+      (isBound(HydraniumClientTypes.Logger) ? rebind : bind)(HydraniumClientTypes.Logger).toConstantValue(options.logger);
+   } else if (!isBound(HydraniumClientTypes.Logger)) {
+      bind(HydraniumClientTypes.Logger).toConstantValue(new ConsoleLogger());
+   }
+   if (!isBound(HydraniumClientTypes.Tracer)) {
+      bind(HydraniumClientTypes.Tracer)
+         .toDynamicValue(ctx => {
+            const logger = ctx.container.get<Logger>(HydraniumClientTypes.Logger);
+            const clock = ctx.container.isBound(HydraniumClientTypes.Clock)
+               ? ctx.container.get<Clock>(HydraniumClientTypes.Clock)
+               : new SystemClock();
+            return new DefaultTracer(logger, clock);
+         })
+         .inSingletonScope();
+   }
+   bind(HydraniumGlspActionDispatcher).toSelf().inSingletonScope();
+   rebind(GLSPActionDispatcher).toService(HydraniumGlspActionDispatcher);
+   rebind(DiagramLoader).to(HydraniumDiagramLoader).inSingletonScope();
+   rebind(GLSPHiddenBoundsUpdater).to(HydraniumHiddenBoundsUpdater).inSingletonScope();
+   rebind(StatusOverlay).to(HydraniumStatusOverlay).inSingletonScope();
+   rebind(RankedSelectMouseListener).to(HydraniumSelectMouseListener).inSingletonScope();
+   rebind(TYPES.ILogger).to(SprottyLoggerAdapter).inSingletonScope();
+}

package/src/glsp-client.ts

@@ -0,0 +1,20 @@
+/********************************************************************************
+ * 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 { BaseJsonrpcGLSPClient, type DisposeClientSessionParameters } from '@eclipse-glsp/client';
+
+/** The GLSP client a host builds over its connection to the GLSP head. */
+export class HydraniumGlspClient extends BaseJsonrpcGLSPClient {
+   /** Resolves at once when the connection is gone: the session went with its
+    *  server, and upstream would throw, which a diagram disposed after its
+    *  client was lost logs as an error. */
+   override disposeClientSession(params: DisposeClientSessionParameters): Promise<void> {
+      return this.isConnectionActive() ? super.disposeClientSession(params) : Promise.resolve();
+   }
+}