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

package/src/browser/glsp-theia-frontend-module.ts

@@ -0,0 +1,157 @@
+/********************************************************************************
+ * 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 ContainerContext,
+   DiagramConfiguration,
+   GLSPClientContribution,
+   type GLSPDiagramManager,
+   GLSPDiagramWidget,
+   GLSPTheiaFrontendModule,
+   registerDiagramManager
+} from '@eclipse-glsp/theia-integration';
+import { type GLSPDiagramLanguage } from '@eclipse-glsp/theia-integration/lib/common';
+import { bindLogLevelPreference } from '@hydranium/client-theia/lib/browser';
+import type { interfaces } from '@theia/core/shared/inversify';
+import { HydraniumGlspDiagramWidget } from './diagram-widget';
+
+/**
+ * Sentinel returned from {@link AbstractHydraniumGlspTheiaFrontendModule.bindClientContribution}
+ * to mean "this module deliberately does not bind a GLSPClientContribution"
+ * — used for secondary diagram types that share a GLSP server with a
+ * primary diagram type whose module already bound the contribution. The
+ * override becomes a no-op rather than the framework default.
+ */
+export const SkipClientContribution = Symbol.for('@hydranium/glsp-client-theia#SkipClientContribution');
+export type SkipClientContribution = typeof SkipClientContribution;
+
+/**
+ * `GLSPTheiaFrontendModule` subclass that factors out the method overrides
+ * every adopter writes verbatim (`bindDiagramConfiguration` /
+ * `bindGLSPClientContribution` / `configureDiagramManager`) into hook methods
+ * reading from abstract fields.
+ *
+ * Adopters subclass and provide:
+ *  - {@link diagramLanguage} (declared `abstract` on the base class but
+ *    `readonly` on the base type — `GLSPTheiaFrontendModule` requires it)
+ *  - {@link diagramConfiguration} — the adopter's `DiagramConfiguration`
+ *  - {@link diagramManager} — the adopter's `GLSPDiagramManager` subclass
+ *
+ * Optional override hook:
+ *  - {@link bindClientContribution} — return a `Newable<GLSPClientContribution>`
+ *    to bind it (the common case), {@link SkipClientContribution} to
+ *    bypass binding entirely (secondary diagrams), or `undefined` to
+ *    defer to `super.bindGLSPClientContribution(context)`. Default
+ *    returns `undefined` (framework default).
+ *
+ * Adopter-specific customisation that stays as `override` on the subclass:
+ *  - `bindDiagramWidgetFactory` — custom `GLSPDiagramWidget` rebinds
+ *  - `configure` — LibAvoid initialiser, color contribution, startup hooks
+ *  - `enableLayoutCommands` / `enableMarkerNavigationCommands` — flags
+ *
+ * Abstract base class + adopter subclass with concrete fields, following the
+ * GLSP module convention. No `Default*` concrete sibling because the abstract
+ * fields have no sane defaults — every adopter must provide them.
+ */
+export abstract class AbstractHydraniumGlspTheiaFrontendModule extends GLSPTheiaFrontendModule {
+   /** Wire-format identifiers + file routing — required by the base. */
+   abstract override readonly diagramLanguage: GLSPDiagramLanguage;
+
+   /** Adopter's `DiagramConfiguration` class. Bound via `bindDiagramConfiguration`. */
+   protected abstract readonly diagramConfiguration: interfaces.Newable<DiagramConfiguration>;
+
+   /** Adopter's `GLSPDiagramManager` class. Bound + registered via `configureDiagramManager`. */
+   protected abstract readonly diagramManager: interfaces.Newable<GLSPDiagramManager>;
+
+   /**
+    * Theia preference id driving the framework log threshold, e.g.
+    * `'my-language.log.level'`. When set, {@link initialize} binds
+    * `LogLevelPreferenceContribution` so the level is applied at
+    * application start and kept in sync on change.
+    *
+    * It belongs here rather than beside the channel name in
+    * `createGlspClientTheiaModule`'s options because the two have different
+    * scopes: the channel is per diagram container, while the threshold is a
+    * process-global and must be applied once, from the frontend container.
+    */
+   protected readonly logLevelPreference?: string;
+
+   /**
+    * Hook returning the {@link GLSPClientContribution} class the framework
+    * should bind for this diagram module:
+    *  - `undefined` (default) — invoke `super.bindGLSPClientContribution(context)`
+    *  - a `Newable<GLSPClientContribution>` — bind it to-self singleton + bind
+    *    `GLSPClientContribution` to the service
+    *  - {@link SkipClientContribution} — no-op (secondary diagrams sharing
+    *    a GLSP server with a primary diagram whose module already bound
+    *    the contribution)
+    */
+   protected bindClientContribution(): interfaces.Newable<GLSPClientContribution> | SkipClientContribution | undefined {
+      return undefined;
+   }
+
+   /**
+    * Adds the framework's frontend-scoped bindings on top of the base wiring.
+    *
+    * Overrides `initialize` — the base's own orchestrator — rather than
+    * `configure`, which is documented as the *adopter's* hook: a subclass that
+    * overrides `configure` and forgets `super.configure(context)` would otherwise
+    * silently lose these bindings.
+    */
+   override initialize(context: ContainerContext): void {
+      super.initialize(context);
+      if (this.logLevelPreference) {
+         bindLogLevelPreference(context.bind, this.logLevelPreference);
+      }
+   }
+
+   override bindDiagramConfiguration(context: ContainerContext): void {
+      context.bind(DiagramConfiguration).to(this.diagramConfiguration);
+   }
+
+   override bindGLSPClientContribution(context: ContainerContext): void {
+      const contribution = this.bindClientContribution();
+      if (contribution === SkipClientContribution) {
+         return;
+      }
+      if (contribution === undefined) {
+         super.bindGLSPClientContribution(context);
+         return;
+      }
+      context.bind(contribution).toSelf().inSingletonScope();
+      context.bind(GLSPClientContribution).toService(contribution);
+   }
+
+   override configureDiagramManager(context: ContainerContext): void {
+      context.bind(this.diagramManager).toSelf().inSingletonScope();
+      registerDiagramManager(context.bind, this.diagramManager, false);
+   }
+
+   /**
+    * Binds the framework diagram widget on top of the base factory wiring, so
+    * every hydranium head gets the loading overlay.
+    *
+    * `super` binds `GLSPDiagramWidget` to itself (via `lazyBind`, a no-op when
+    * already bound) plus the `DiagramWidgetFactory`; the rebind then points the
+    * same token at the subclass, leaving the factory untouched.
+    *
+    * Unconditional on purpose. {@link HydraniumGlspDiagramWidget} differs from
+    * GLSP's widget only by the overlay, so there is no flag here: an adopter that
+    * wants different behaviour overrides the widget (opt out of the overlay by
+    * no-op'ing `showLoadingOverlay`), and one that wants its own subclass rebinds
+    * this token again after calling `super`. A module-level flag gating the
+    * rebind would be worse than useless: it decides which CLASS to bind, so an
+    * adopter subclassing the framework widget and setting the flag to `false`
+    * still gets the overlay, and the flag's name lies.
+    */
+   override bindDiagramWidgetFactory(context: ContainerContext): void {
+      super.bindDiagramWidgetFactory(context);
+      context.rebind(GLSPDiagramWidget).to(HydraniumGlspDiagramWidget);
+   }
+}

package/src/browser/hidden-bounds-updater.ts

@@ -0,0 +1,212 @@
+/********************************************************************************
+ * 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,
+   type ElementAndRoutingPoints,
+   type GModelElement,
+   type GRoutableElement,
+   GLSPHiddenBoundsUpdater,
+   type LocalRequestBoundsAction,
+   Point,
+   RequestBoundsAction,
+   ServerAction,
+   isRoutable
+} from '@eclipse-glsp/client';
+import { ChannelLogger } from '@hydranium/client-theia/lib/browser';
+import { type Clock, SystemClock } from '@hydranium/protocol';
+import { inject, injectable } from '@theia/core/shared/inversify';
+import { type VNode } from 'snabbdom';
+
+/** How many scoped element ids the log line names before summarising the rest.
+ *  A scoped request names one element in practice; the cap only stops a
+ *  pathological caller from writing a thousand ids into the channel. */
+const SCOPE_ID_CAP = 3;
+
+/**
+ * Instruments sprotty's hidden-bounds pass and repairs degenerate routes before
+ * they go on the wire.
+ *
+ * **Why the framework owns this.** Every GLSP head runs the hidden-bounds pass on
+ * every model update, and it is the one client-side phase that scales with the
+ * *rendered element count* rather than the model size — labels, compartments and
+ * edge decorations expand a modest node count into orders of magnitude more DOM
+ * elements. Without a timing line there is no way to tell a slow measurement pass
+ * apart from slow edge routing or a slow server round trip; with one,
+ * `bounds-request` either exonerates the client in a sentence or names the
+ * dominant cost.
+ *
+ * Emits exactly one `trace` line per bounds request — `trace` because the
+ * frequency matches the per-action traffic `HydraniumGlspActionDispatcher` logs
+ * there (a bounds request is driven by those actions), so it belongs with them
+ * rather than above them. The line carries:
+ *
+ *  - `server` / `local` — whether the request came from the server or from a
+ *    client-local {@link LocalRequestBoundsAction}
+ *  - `scope=<ids>` — the elements a scoped request named; absent when the request
+ *    covers the whole diagram
+ *  - `measured=N` — DOM elements whose bounds were read. Exceeds the scoped id
+ *    count because the base class expands each requested element to its
+ *    descendants
+ *  - `getBBox=Nms` — {@link getBoundsFromDOM} **only**: the layout pass and the
+ *    `ComputedBoundsAction` assembly stay outside it, so the number isolates raw
+ *    measurement cost
+ *
+ * Composed from {@link Clock.measure} rather than `Tracer.time`, matching
+ * `HydraniumDocumentBuilder`'s phase instrumentation. `Tracer.time` is for "tell
+ * me when this is slow" and is deliberately silent on a fast success, which would
+ * drop the element count on every normal pass — and forcing it to emit costs a
+ * paired `[#N start]` line per request. This is a per-occurrence record, so it
+ * measures and composes its own line.
+ *
+ * Bound by `createGlspClientTheiaModule` via `rebind(GLSPHiddenBoundsUpdater)`.
+ */
+@injectable()
+export class HydraniumHiddenBoundsUpdater extends GLSPHiddenBoundsUpdater {
+   @inject(ChannelLogger) protected readonly channel!: ChannelLogger;
+
+   /** Not injected: the browser container binds no {@link Clock}, and this only
+    *  measures — no logic is gated on time, so there is nothing to fake in
+    *  production. Overridden in tests for a deterministic elapsed value. */
+   protected readonly clock: Clock = new SystemClock();
+
+   /**
+    * Scope description for the in-flight request, read from the `cause` in
+    * {@link postUpdate} and consumed by {@link getBoundsFromDOM} — which the base
+    * class calls with no arguments, so the cause cannot be threaded through.
+    */
+   protected currentScope?: string;
+
+   override decorate(vnode: VNode, element: GModelElement): VNode {
+      super.decorate(vnode, element);
+      if (isRoutable(element)) {
+         this.repairLastRoute(element);
+      }
+      return vnode;
+   }
+
+   /**
+    * Replace the routing entry the base class just pushed when it carries fewer
+    * than two points, which is not a valid route for any edge.
+    *
+    * `calcElementAndRoute` already guards the case where the registered router
+    * returns *nothing* — it falls back to source + own routing points + target.
+    * The hole is one step further in: `calcRoute` filters duplicate points at
+    * `Number.EPSILON`, so while obstacles still carry sprotty's unmeasured-bounds
+    * sentinel `(100, 100, -1, -1)` the source and target coincide and a valid
+    * two-point route collapses to a single point. That result is defined, so the
+    * upstream truthiness guard never fires and the single point ships.
+    *
+    * The substitute is deliberately upstream's own fallback shape rather than a
+    * new invention, so a repaired route is indistinguishable from a route the
+    * base class would have produced had it noticed. Only already-invalid payloads
+    * are touched, so a head with a working router is unaffected.
+    */
+   protected repairLastRoute(element: GRoutableElement): void {
+      const addedRoute = this.element2route.pop();
+      if (addedRoute === undefined) {
+         return;
+      }
+      this.element2route.push(this.hasValidRoute(addedRoute) ? addedRoute : this.toSourceTargetRoute(element));
+   }
+
+   /** A route needs at least a start and an end point to describe an edge. */
+   protected hasValidRoute(route: ElementAndRoutingPoints): boolean {
+      return route.newRoutingPoints !== undefined && route.newRoutingPoints.length >= 2;
+   }
+
+   /** Upstream's `calcElementAndRoute` no-router fallback: the element's own
+    *  bendpoints framed by its source and target anchor positions. */
+   protected toSourceTargetRoute(element: GRoutableElement): ElementAndRoutingPoints {
+      return {
+         elementId: element.id,
+         newRoutingPoints: [element.source?.position ?? Point.ORIGIN, ...element.routingPoints, element.target?.position ?? Point.ORIGIN]
+      };
+   }
+
+   protected override getBoundsFromDOM(): void {
+      if (this.currentScope === undefined) {
+         // Not inside an instrumented `postUpdate` (a subclass calling directly);
+         // with no cause there is nothing to attribute a measurement to.
+         super.getBoundsFromDOM();
+         return;
+      }
+      // Read before the pass: the base class clears the map on its way out.
+      const measured = this.getElement2BoundsData().size;
+      const { elapsedMs } = this.clock.measure(() => super.getBoundsFromDOM());
+      this.channel.trace(this.formatBoundsRequest(this.currentScope, measured, elapsedMs));
+   }
+
+   /** Format the per-request line. Override to change the wording. */
+   protected formatBoundsRequest(scope: string, measured: number, elapsedMs: number): string {
+      return `bounds-request[${scope}] measured=${measured} getBBox=${elapsedMs.toFixed(0)}ms`;
+   }
+
+   override postUpdate(cause?: Action): void {
+      if (cause?.kind !== RequestBoundsAction.KIND) {
+         super.postUpdate(cause);
+         return;
+      }
+      this.currentScope = this.formatCause(cause);
+      try {
+         super.postUpdate(cause);
+      } finally {
+         this.currentScope = undefined;
+      }
+   }
+
+   /**
+    * Scope facts for the log line: where the request came from, and which
+    * elements it asked for.
+    *
+    * Origin is read from {@link ServerAction}, the `__receivedFromServer` marker
+    * `GLSPModelSource` stamps on inbound actions, rather than from
+    * `LocalRequestBoundsAction.is`. The latter would answer the same today, but
+    * only incidentally: its `elementIDs` check is declared optional, so it is
+    * really just "a bounds request that did not come from the server". Keying on
+    * the marker states that directly, and keeps an *unscoped* local request from
+    * being mislabelled `server` if GLSP ever tightens that guard.
+    */
+   protected formatCause(cause: Action): string {
+      const origin = ServerAction.is(cause) ? 'server' : 'local';
+      const scope = this.formatScope(cause as RequestBoundsAction);
+      return scope ? `${origin} scope=${scope}` : origin;
+   }
+
+   /**
+    * Name the elements a scoped request asked for, or `undefined` when it covers
+    * the whole diagram.
+    *
+    * Deliberately the ids and not their count. A scoped request in practice names
+    * a single element, so a count is always `1` and says nothing, while the id
+    * says *which* element was re-measured — and it is the only part of the line
+    * that distinguishes one such request from the next. It also stops the line
+    * reading as a contradiction: `scope=node0, measured=6` is coherent (the base
+    * class expands a requested element to its descendants, so one id measures six
+    * DOM elements), where `scoped=1, measured=6` invites the reader to wonder
+    * which number is wrong.
+    *
+    * A request naming only the root is treated as unscoped: it measures
+    * everything, so the id adds nothing over the absence of a `scope` tag.
+    */
+   protected formatScope(cause: RequestBoundsAction): string | undefined {
+      const scopedIds = (cause as LocalRequestBoundsAction).elementIDs;
+      if (!scopedIds || scopedIds.length === 0) {
+         return undefined;
+      }
+      const named = scopedIds.filter(id => id !== cause.newRoot?.id);
+      if (named.length === 0) {
+         return undefined;
+      }
+      if (named.length > SCOPE_ID_CAP) {
+         return `${named.slice(0, SCOPE_ID_CAP).join(',')},+${named.length - SCOPE_ID_CAP} more`;
+      }
+      return named.join(',');
+   }
+}

package/src/browser/hydranium-glsp-diagram-configuration.ts

@@ -0,0 +1,63 @@
+/********************************************************************************
+ * 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 ExternalMarkerManager } from '@eclipse-glsp/client';
+import { GLSPDiagramConfiguration, connectTheiaContextMenuService, connectTheiaMarkerManager } from '@eclipse-glsp/theia-integration';
+import { type Container, injectable } from '@theia/core/shared/inversify';
+import { NoOpExternalMarkerManager } from './diagram-only-marker-manager.js';
+
+/**
+ * `GLSPDiagramConfiguration` base for hydranium adopters. By default GLSP
+ * validation markers propagate into Theia's Problems view (the stock
+ * `@eclipse-glsp/theia-integration` behaviour); a head that already publishes
+ * the same diagnostics over LSP suppresses that propagation by setting
+ * {@link propagateMarkersToProblemsView} to `false`.
+ *
+ * **When to suppress.** A head with a co-resident LSP that publishes its
+ * diagnostics over standard LSP `publishDiagnostics` would otherwise list each
+ * error twice: GLSP's `TheiaMarkerManager` pushes the *same* errors again under
+ * a different marker owner, and Theia shows the union across owners. The GLSP
+ * path is also open-diagram-scoped (markers clear when the diagram closes), so
+ * for such a head it cannot reproduce the LSP head's persistent, cross-file
+ * Problems entries — it is only ever a flickering duplicate. A graphical-only
+ * head (no LSP diagnostics, or markers the LSP never produces) keeps the
+ * default so its markers reach the Problems view. The on-diagram decoration is
+ * a separate client feedback path (`ApplyMarkersCommand`), unaffected either
+ * way.
+ *
+ * **How.** {@link initializeContainer} hands {@link connectTheiaMarkerManager}
+ * the Theia marker-manager factory by default; when suppression is enabled it
+ * hands a no-op {@link ExternalMarkerManager} factory instead, so the
+ * per-diagram container binds a manager that renders-but-does-not-forward and
+ * the real `TheiaMarkerManager` (with its `@postConstruct`
+ * `ProblemManager`/shell subscriptions) is never constructed.
+ *
+ * NB: this overrides `GLSPDiagramConfiguration.initializeContainer` rather than
+ * calling `super`. It mirrors the base body (context-menu + marker-manager
+ * wiring); revisit if a future `@eclipse-glsp/theia-integration` adds further
+ * setup there.
+ */
+@injectable()
+export abstract class AbstractHydraniumGlspDiagramConfiguration extends GLSPDiagramConfiguration {
+   /**
+    * Whether GLSP markers propagate into Theia's Problems view. `true` (the
+    * framework default) keeps the stock Theia propagation; set `false` for a
+    * head with a co-resident LSP that already publishes the same diagnostics,
+    * to render markers on the diagram only and avoid double-listing.
+    */
+   protected propagateMarkersToProblemsView = true;
+
+   protected override initializeContainer(container: Container): void {
+      connectTheiaContextMenuService(container, this.contextMenuServiceFactory);
+      const markerManagerFactory = this.propagateMarkersToProblemsView
+         ? this.theiaMarkerManager
+         : (): ExternalMarkerManager => new NoOpExternalMarkerManager();
+      connectTheiaMarkerManager(container, markerManagerFactory, this.diagramType);
+   }
+}

package/src/browser/index.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
+ ********************************************************************************/
+
+// Browser-side framework primitives for GLSP-on-Theia adopters.
+// The cross-head Output-channel logger lives in `@hydranium/client-theia/browser`.
+export * from './action-dispatcher';
+export * from './client-contribution';
+export * from './diagram-loader';
+export * from './diagram-only-marker-manager';
+export * from './diagram-widget';
+export * from './glsp-client-theia-module';
+export * from './glsp-diagram-manager';
+export * from './glsp-message-service';
+export * from './glsp-theia-frontend-module';
+export * from './hidden-bounds-updater';
+export * from './hydranium-glsp-diagram-configuration';

package/src/index.ts

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Root barrel re-exports the browser-side surface, mirroring the root entry of
+// the package this one integrates: `@eclipse-glsp/theia-integration`'s own
+// `main` is its browser tier, so an adopter importing the bare specifier
+// expects the same surface here.
+//
+// That makes this root BROWSER-BOUND, not neutral, and not merely
+// DOM-avoiding: the re-exported tier value-imports `@theia/workspace`'s and
+// `@theia/output`'s browser modules, which touch `document` at module load, and
+// its dependency graph imports stylesheets, so loading it needs a bundler with a
+// CSS loader. It is a frontend entry and nothing else. Node-side primitives
+// (connection-handler wiring) stay behind
+// `@hydranium/glsp-client-theia/node` so the `@theia/core/lib/node/...`
+// imports don't leak into a browser bundle.
+export * from './browser/index';

package/src/node/connection-container-module.ts

@@ -0,0 +1,34 @@
+/********************************************************************************
+ * 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 { ConnectionHandler } from '@theia/core';
+import { ConnectionContainerModule } from '@theia/core/lib/node/messaging/connection-container-module';
+import { ContainerModule, type interfaces } from '@theia/core/shared/inversify';
+
+/**
+ * Creates the frontend-scoped Theia backend module that registers a GLSP
+ * `ConnectionHandler` per browser-frontend connection. Returns a ready-to-
+ * export `ContainerModule` so adopters can `export default createGlspConnectionContainerModule(MyHandler)`
+ * from their backend-module entry point.
+ *
+ * The wrapping `ContainerModule + ConnectionContainerModule.create` pattern
+ * mirrors the boilerplate every Theia GLSP adopter writes by hand; lifted so
+ * adopters declare only the handler class.
+ */
+export function createGlspConnectionContainerModule(handlerClass: interfaces.Newable<ConnectionHandler>): ContainerModule {
+   const frontendScopedConnectionModule = ConnectionContainerModule.create(({ bind }) => {
+      bind(handlerClass).toSelf().inSingletonScope();
+      bind(ConnectionHandler)
+         .toDynamicValue(context => context.container.get(handlerClass))
+         .inSingletonScope();
+   });
+   return new ContainerModule(bind => {
+      bind(ConnectionContainerModule).toConstantValue(frontendScopedConnectionModule);
+   });
+}

package/src/node/glsp-server-connection-handler.ts

@@ -0,0 +1,69 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { GLSPContribution } from '@eclipse-glsp/theia-integration/lib/common';
+import { SocketConnectionForwarder } from '@eclipse-glsp/theia-integration/lib/node';
+import { AbstractSocketForwardingConnectionHandler } from '@hydranium/client-theia/lib/node';
+import { type Channel, type Disposable } from '@theia/core';
+import { injectable, unmanaged } from '@theia/core/shared/inversify';
+import type * as net from 'net';
+
+/** Options for `GlspServerConnectionHandler`. The language contribution
+ *  id determines the per-language servicePath that Theia routes browser-frontend
+ *  connections to; the port command is the Theia/VS Code command id whose return
+ *  value is the GLSP server's listening port. */
+export interface GlspServerConnectionHandlerOptions {
+   readonly languageContributionId: string;
+   readonly portCommand: string;
+   readonly findPortTimeout?: number;
+   readonly findPortAttempts?: number;
+   readonly connectTimeoutMs?: number;
+   /**
+    * Optional diagnostic hook called immediately after the outbound
+    * `net.Socket` to the GLSP server is created, BEFORE `socket.connect()`
+    * is invoked. Adopters use this to attach `'data'` / `'close'` listeners
+    * for byte-level observability when debugging wire-level handshake
+    * issues; attaching listeners before `connect()` is what guarantees the
+    * very first bytes are observed.
+    */
+   readonly onSocketCreated?: (socket: net.Socket) => void;
+}
+
+/**
+ * Bridges a Theia browser-frontend channel to a GLSP server's TCP socket.
+ *
+ * The port-discovery + buffer-and-replay race fix + connect orchestration live
+ * on the cross-head {@link AbstractSocketForwardingConnectionHandler} base; this
+ * subclass supplies only the GLSP specifics — the per-language servicePath
+ * (`GLSPContribution.servicePath + '/' + languageContributionId`), the port
+ * command, the log labels — and plugs in `@eclipse-glsp/theia-integration`'s
+ * `SocketConnectionForwarder` as the byte relay. Adopters with different
+ * language ids or command names subclass with a one-line `super({...})` call.
+ * Sibling of `@hydranium/data-client-theia`'s `DataServerConnectionHandler`,
+ * which subclasses the same base with its own GLSP-free forwarder.
+ */
+@injectable()
+export class GlspServerConnectionHandler extends AbstractSocketForwardingConnectionHandler {
+   constructor(@unmanaged() options: GlspServerConnectionHandlerOptions) {
+      super({
+         path: GLSPContribution.servicePath + '/' + options.languageContributionId,
+         portCommand: options.portCommand,
+         logComponent: 'GLSP',
+         serverName: 'Graphical Server',
+         findPortTimeout: options.findPortTimeout,
+         findPortAttempts: options.findPortAttempts,
+         connectTimeoutMs: options.connectTimeoutMs,
+         onSocketCreated: options.onSocketCreated
+      });
+   }
+
+   protected forwardToSocketConnection(clientChannel: Channel, socket: net.Socket): Disposable {
+      return new SocketConnectionForwarder(clientChannel, socket);
+   }
+}

package/src/node/index.ts

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+// Node-side framework primitives for GLSP-on-Theia adopters.
+export * from './connection-container-module';
+export * from './glsp-server-connection-handler';