@hydranium/glsp-server 1.0.0-next.10

package/lib/launcher/hydranium-glsp-server.js

@@ -0,0 +1,101 @@
+/********************************************************************************
+ * 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 __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { DefaultGLSPServer, GLSPServerError, RejectAction } from '@eclipse-glsp/server';
+import { injectable } from 'inversify';
+/**
+ * The GLSP server the framework binds in place of upstream's
+ * {@link DefaultGLSPServer}, so a failed REQUEST reaches its reader with the
+ * text the thrower wrote.
+ *
+ * **What breaks without it.** Upstream projects a failing request's detail as
+ * `error.cause?.toString()` whenever the error is a {@link GLSPServerError},
+ * and that one value feeds both the server log and the client's
+ * {@link RejectAction}. A {@link GLSPServerError} carrying no `cause` therefore
+ * reaches no reader at all — not the toast, not the details pane, not the log —
+ * while a plain `Error` survives, because the other branch reads the error
+ * itself. The typed error is the trap, and it is the one upstream's own
+ * `getOrThrow` helper raises: that helper's signature cannot pass a `cause`, so
+ * an adopter using the sanctioned helper has no fix available on their side.
+ * Restating the cause at each throw site is the alternative, and it costs
+ * every adopter a rule they must know and cannot apply to `getOrThrow`.
+ *
+ * Only the REQUEST path needs this. Non-request actions fail through
+ * upstream's `handleProcessError`, which reads `message` directly.
+ *
+ * Adopters who bind their own GLSP server should extend this class rather than
+ * {@link DefaultGLSPServer}; the framework's server-container override replaces
+ * whatever the adopter's `ServerModule` bound, so a subclass of upstream's
+ * server would be discarded.
+ */
+let HydraniumGlspServer = class HydraniumGlspServer extends DefaultGLSPServer {
+    /**
+     * The detail projected into the client's {@link RejectAction} and the server
+     * log when a request fails.
+     *
+     * A {@link GLSPServerError} with no `cause` falls back to its `message`; a
+     * nullish `cause` counts as absent, matching the optional chaining upstream
+     * applies. Anything else stringifies as upstream does, so a plain `Error`
+     * keeps its `"Error: …"` prefix and callers that match on it still match.
+     */
+    requestFailureDetail(error) {
+        if (error instanceof GLSPServerError) {
+            return error.cause === undefined || error.cause === null ? error.message : String(error.cause);
+        }
+        return error === undefined || error === null ? undefined : String(error);
+    }
+    /**
+     * Lifted verbatim from `@eclipse-glsp/server` 2.7.0's
+     * {@link DefaultGLSPServer.handleClientRequest}, with the detail computation
+     * delegated to {@link requestFailureDetail}. Nothing else here — the
+     * timeout branch, the response dispatch, the nested send-failure handling —
+     * relates to that fallback.
+     *
+     * **This body does not track upstream.** A release that changes request
+     * handling would silently not apply, on the path every request takes. There
+     * is no narrower seam to override: upstream computes the detail inline. The
+     * accompanying test pins upstream's own source for this method, so a bump
+     * that changes it fails rather than diverging quietly; re-lift the body when
+     * it does.
+     */
+    async handleClientRequest(clientSession, action, clientId) {
+        try {
+            const response = action.timeout !== undefined
+                ? await clientSession.actionDispatcher.requestUntil(action, action.timeout, true)
+                : await clientSession.actionDispatcher.request(action);
+            if (response) {
+                this.sendResponseToClient(clientId, response);
+            }
+        }
+        catch (error) {
+            const detail = this.requestFailureDetail(error);
+            this.logger.error(`Failed to handle request '${action.kind}' (${action.requestId}):`, detail);
+            try {
+                const reject = RejectAction.create(`Failed to handle request '${action.kind}' (${action.requestId})`, {
+                    responseId: action.requestId,
+                    detail
+                });
+                this.sendResponseToClient(clientId, reject);
+            }
+            catch (sendError) {
+                this.logger.error(`Failed to send rejection for request '${action.requestId}':`, sendError);
+            }
+        }
+    }
+};
+HydraniumGlspServer = __decorate([
+    injectable()
+], HydraniumGlspServer);
+export { HydraniumGlspServer };
+//# sourceMappingURL=hydranium-glsp-server.js.map

package/lib/launcher/hydranium-glsp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-glsp-server.js","sourceRoot":"","sources":["../../src/launcher/hydranium-glsp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;;;;;;;AAElF,OAAO,EAEJ,iBAAiB,EACjB,eAAe,EACf,YAAY,EAGd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAoB,SAAQ,iBAAiB;IACvD;;;;;;;;OAQG;IACO,oBAAoB,CAAC,KAAc;QAC1C,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;YACpC,OAAO,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClG,CAAC;QACD,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5E,CAAC;IAED;;;;;;;;;;;;;OAaG;IACgB,KAAK,CAAC,mBAAmB,CACzC,aAA4B,EAC5B,MAAqC,EACrC,QAAgB;QAEhB,IAAI,CAAC;YACF,MAAM,QAAQ,GACX,MAAM,CAAC,OAAO,KAAK,SAAS;gBACzB,CAAC,CAAC,MAAM,aAAa,CAAC,gBAAgB,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC;gBACjF,CAAC,CAAC,MAAM,aAAa,CAAC,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC7D,IAAI,QAAQ,EAAE,CAAC;gBACZ,IAAI,CAAC,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YACjD,CAAC;QACJ,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;YAChD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,MAAM,CAAC,IAAI,MAAM,MAAM,CAAC,SAAS,IAAI,EAAE,MAAM,CAAC,CAAC;YAC9F,IAAI,CAAC;gBACF,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,6BAA6B,MAAM,CAAC,IAAI,MAAM,MAAM,CAAC,SAAS,GAAG,EAAE;oBACnG,UAAU,EAAE,MAAM,CAAC,SAAS;oBAC5B,MAAM;iBACR,CAAC,CAAC;gBACH,IAAI,CAAC,oBAAoB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC/C,CAAC;YAAC,OAAO,SAAkB,EAAE,CAAC;gBAC3B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,yCAAyC,MAAM,CAAC,SAAS,IAAI,EAAE,SAAS,CAAC,CAAC;YAC/F,CAAC;QACJ,CAAC;IACJ,CAAC;CACH,CAAA;AA1DY,mBAAmB;IAD/B,UAAU,EAAE;GACA,mBAAmB,CA0D/B"}

package/lib/launcher/index.d.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
+ ********************************************************************************/
+export * from './glsp-app-module.js';
+export * from './abstract-hydranium-glsp-diagram-module.js';
+export * from './hydranium-glsp-server.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/launcher/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,sBAAsB,CAAC;AACrC,cAAc,6CAA6C,CAAC;AAI5D,cAAc,4BAA4B,CAAC"}

package/lib/launcher/index.js

@@ -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
+ ********************************************************************************/
+export * from './glsp-app-module.js';
+export * from './abstract-hydranium-glsp-diagram-module.js';
+// Exported so an adopter binding their own GLSP server extends the framework's
+// rather than upstream's — the server-container override discards a subclass of
+// `DefaultGLSPServer`.
+export * from './hydranium-glsp-server.js';
+// The socket bringup lives in `@hydranium/glsp-server/node` and the worker
+// bringup in `@hydranium/glsp-server/browser`, not here: each pulls the
+// upstream build for its platform, which the portable `.` entry must stay free
+// of. `glsp-framework-overrides.js` and `glsp-server-overrides.js` are
+// deliberately NOT re-exported — they are the bindings those two bringups share,
+// reached by relative import, and an adopter composing a container by hand wants
+// the launcher rather than its internals.
+//# sourceMappingURL=index.js.map

package/lib/launcher/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/launcher/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,sBAAsB,CAAC;AACrC,cAAc,6CAA6C,CAAC;AAC5D,+EAA+E;AAC/E,gFAAgF;AAChF,uBAAuB;AACvB,cAAc,4BAA4B,CAAC;AAC3C,2EAA2E;AAC3E,wEAAwE;AACxE,+EAA+E;AAC/E,uEAAuE;AACvE,iFAAiF;AACjF,iFAAiF;AACjF,0CAA0C"}

package/lib/logging/glsp-client-logger.d.ts

@@ -0,0 +1,110 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 Logger as GlspLogger, LogLevel } from '@eclipse-glsp/server';
+import { LspLogger, type LspLoggerOptions, type ServerSharedServices } from '@hydranium/core';
+import { type LogThreshold } from '@hydranium/protocol';
+/**
+ * Options accepted by {@link GlspClientLogger}. Extends
+ * {@link LspLoggerOptions} (which carries the optional `component`
+ * label) with the GLSP-specific per-instance {@link logLevel} threshold.
+ */
+export interface GlspClientLoggerOptions extends LspLoggerOptions {
+    /**
+     * Per-instance NARROWING of the framework threshold. Omit it — the default
+     * tracks `Logger.getLevel()` live, which is what makes one
+     * `HYDRANIUM_LOG_LEVEL` / one LSP setting govern GLSP output too.
+     *
+     * It can only narrow, never widen, and that is not a policy choice:
+     * `AbstractLogger.send` gates every emission on the process-wide threshold
+     * before it reaches the output channel, so a value more verbose than the
+     * global is silently ineffective. Set it only to make ONE component quieter
+     * than the rest.
+     */
+    readonly logLevel?: LogLevel;
+}
+/**
+ * Map the framework's {@link LogThreshold} onto GLSP's numeric enum.
+ *
+ * Two vocabularies have to meet here: ours is a string union with `'off'` and
+ * `'trace'`, GLSP's a numeric enum whose most verbose tier is `debug`. `'off'`
+ * becomes `none`, and **`'trace'` also becomes `debug`** — GLSP has no finer
+ * tier, and mapping it to `none` would silence GLSP at the most verbose
+ * framework setting, which is the opposite of what asking for `trace` means.
+ */
+export declare function glspLogLevelOf(threshold: LogThreshold): LogLevel;
+/**
+ * Adapter from {@link LspLogger} (the framework's LSP-bound logger in
+ * `@hydranium/core`) to GLSP's server-side {@link GlspLogger}
+ * abstract base. Lets the GLSP container resolve a logger whose output
+ * lines interleave with the LSP head's existing log channel — the only
+ * way to debug request/response flow across the two heads in one place.
+ *
+ * GLSP-specific concerns layered on top of {@link LspLogger}:
+ *
+ * - A {@link logLevel} field, because GLSP's `Logger` contract declares one.
+ *   **It tracks the framework's process-wide threshold by default**, resolving
+ *   `Logger.getLevel()` through {@link glspLogLevelOf} on every read — so
+ *   `HYDRANIUM_LOG_LEVEL`, the LSP log-level setting and the Theia preference
+ *   all reach GLSP output without a second knob. Assigning the field (or
+ *   passing `logLevel`) pins an explicit per-instance NARROWING; see
+ *   {@link GlspClientLoggerOptions.logLevel} for why it cannot widen.
+ *   Resolved lazily rather than captured in the constructor: the root logger is
+ *   built during container setup, before the LSP client has sent its
+ *   configuration, so a captured value would freeze the launch-time default.
+ * - The {@link caller} accessor satisfies GLSP's abstract `Logger.caller`
+ *   contract; it is backed by {@link LspLogger}'s `component` field.
+ * - {@link info} / {@link warn} / {@link error} / {@link debug} accept GLSP's
+ *   `(message, ...params)` shape and {@link combine} the params into the
+ *   message via {@link formatParam} so objects render as JSON and errors
+ *   render with stack. GLSP server code routinely calls
+ *   `logger.error('Failed', error)` expecting the second argument to be
+ *   surfaced in the log line.
+ *
+ * Subclasses can override {@link withUri} to render workspace-relative
+ * paths instead of stringified URIs (the typical adopter customisation,
+ * mirroring what an adopter does in its LSP-side logger).
+ */
+export declare class GlspClientLogger extends LspLogger implements GlspLogger {
+    /**
+     * Explicit per-instance narrowing, or `undefined` to track the framework
+     * threshold. Kept separate from the resolved value so {@link derive} can pass
+     * the OVERRIDE to children rather than the resolution — passing the resolved
+     * level would pin every child at whatever the global happened to be when the
+     * parent was derived, and container-time derivation is exactly when that
+     * value is still the launch-time default.
+     */
+    protected logLevelOverride?: LogLevel;
+    constructor(services: ServerSharedServices, options?: GlspClientLoggerOptions);
+    /** GLSP's `Logger.logLevel` contract; the framework threshold unless pinned. */
+    get logLevel(): LogLevel;
+    set logLevel(level: LogLevel);
+    /** GLSP's `Logger.caller` contract; reads {@link LspLogger.component}. */
+    get caller(): string | undefined;
+    info(message: string, ...params: unknown[]): this;
+    warn(message: string, ...params: unknown[]): this;
+    error(message: string, ...params: unknown[]): this;
+    debug(message: string, ...params: unknown[]): this;
+    /** True when {@link logLevel} permits emission at the given level. */
+    protected enabled(level: LogLevel): boolean;
+    /** Concatenate a message with its varargs, formatting each via {@link formatParam}. */
+    protected combine(message: string, params: readonly unknown[]): string;
+    /** Format a single param: errors → `message\nstack`; everything else → JSON.stringify(p, undefined, 4). */
+    protected formatParam(param: unknown): string;
+    /**
+     * Override of {@link LspLogger.derive} that carries the per-instance
+     * narrowing. The base `derive(component)` constructs the subclass with
+     * `{ component }` only, which would drop it.
+     *
+     * It passes {@link logLevelOverride}, NOT `this.logLevel`: an unpinned parent
+     * must yield an unpinned child, or every derived logger freezes at the
+     * threshold in force when the container was built.
+     */
+    protected derive(component: string): this;
+}
+//# sourceMappingURL=glsp-client-logger.d.ts.map

package/lib/logging/glsp-client-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glsp-client-logger.d.ts","sourceRoot":"","sources":["../../src/logging/glsp-client-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,MAAM,IAAI,UAAU,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC9D;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,YAAY,GAAG,QAAQ,CAchE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,gBAAiB,SAAQ,SAAU,YAAW,UAAU;IAClE;;;;;;;OAOG;IACH,SAAS,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC;gBAE1B,QAAQ,EAAE,oBAAoB,EAAE,OAAO,GAAE,uBAA4B;IAKjF,gFAAgF;IAChF,IAAI,QAAQ,IAAI,QAAQ,CAEvB;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAE3B;IAED,0EAA0E;IAC1E,IAAI,MAAM,IAAI,MAAM,GAAG,SAAS,CAE/B;IAEQ,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IAOjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IAOjD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IAOlD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IAO3D,sEAAsE;IACtE,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;IAI3C,uFAAuF;IACvF,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM;IAItE,2GAA2G;IAC3G,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAW7C;;;;;;;;OAQG;cACgB,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAIpD"}

package/lib/logging/glsp-client-logger.js

@@ -0,0 +1,151 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 { LogLevel } from '@eclipse-glsp/server';
+import { LspLogger } from '@hydranium/core';
+import { Logger } from '@hydranium/protocol';
+/**
+ * Map the framework's {@link LogThreshold} onto GLSP's numeric enum.
+ *
+ * Two vocabularies have to meet here: ours is a string union with `'off'` and
+ * `'trace'`, GLSP's a numeric enum whose most verbose tier is `debug`. `'off'`
+ * becomes `none`, and **`'trace'` also becomes `debug`** — GLSP has no finer
+ * tier, and mapping it to `none` would silence GLSP at the most verbose
+ * framework setting, which is the opposite of what asking for `trace` means.
+ */
+export function glspLogLevelOf(threshold) {
+    switch (threshold) {
+        case 'off':
+            return LogLevel.none;
+        case 'error':
+            return LogLevel.error;
+        case 'warn':
+            return LogLevel.warn;
+        case 'info':
+            return LogLevel.info;
+        case 'debug':
+        case 'trace':
+            return LogLevel.debug;
+    }
+}
+/**
+ * Adapter from {@link LspLogger} (the framework's LSP-bound logger in
+ * `@hydranium/core`) to GLSP's server-side {@link GlspLogger}
+ * abstract base. Lets the GLSP container resolve a logger whose output
+ * lines interleave with the LSP head's existing log channel — the only
+ * way to debug request/response flow across the two heads in one place.
+ *
+ * GLSP-specific concerns layered on top of {@link LspLogger}:
+ *
+ * - A {@link logLevel} field, because GLSP's `Logger` contract declares one.
+ *   **It tracks the framework's process-wide threshold by default**, resolving
+ *   `Logger.getLevel()` through {@link glspLogLevelOf} on every read — so
+ *   `HYDRANIUM_LOG_LEVEL`, the LSP log-level setting and the Theia preference
+ *   all reach GLSP output without a second knob. Assigning the field (or
+ *   passing `logLevel`) pins an explicit per-instance NARROWING; see
+ *   {@link GlspClientLoggerOptions.logLevel} for why it cannot widen.
+ *   Resolved lazily rather than captured in the constructor: the root logger is
+ *   built during container setup, before the LSP client has sent its
+ *   configuration, so a captured value would freeze the launch-time default.
+ * - The {@link caller} accessor satisfies GLSP's abstract `Logger.caller`
+ *   contract; it is backed by {@link LspLogger}'s `component` field.
+ * - {@link info} / {@link warn} / {@link error} / {@link debug} accept GLSP's
+ *   `(message, ...params)` shape and {@link combine} the params into the
+ *   message via {@link formatParam} so objects render as JSON and errors
+ *   render with stack. GLSP server code routinely calls
+ *   `logger.error('Failed', error)` expecting the second argument to be
+ *   surfaced in the log line.
+ *
+ * Subclasses can override {@link withUri} to render workspace-relative
+ * paths instead of stringified URIs (the typical adopter customisation,
+ * mirroring what an adopter does in its LSP-side logger).
+ */
+export class GlspClientLogger extends LspLogger {
+    /**
+     * Explicit per-instance narrowing, or `undefined` to track the framework
+     * threshold. Kept separate from the resolved value so {@link derive} can pass
+     * the OVERRIDE to children rather than the resolution — passing the resolved
+     * level would pin every child at whatever the global happened to be when the
+     * parent was derived, and container-time derivation is exactly when that
+     * value is still the launch-time default.
+     */
+    logLevelOverride;
+    constructor(services, options = {}) {
+        super(services, options);
+        this.logLevelOverride = options.logLevel;
+    }
+    /** GLSP's `Logger.logLevel` contract; the framework threshold unless pinned. */
+    get logLevel() {
+        return this.logLevelOverride ?? glspLogLevelOf(Logger.getLevel());
+    }
+    set logLevel(level) {
+        this.logLevelOverride = level;
+    }
+    /** GLSP's `Logger.caller` contract; reads {@link LspLogger.component}. */
+    get caller() {
+        return this.component;
+    }
+    info(message, ...params) {
+        if (this.enabled(LogLevel.info)) {
+            super.info(this.combine(message, params));
+        }
+        return this;
+    }
+    warn(message, ...params) {
+        if (this.enabled(LogLevel.warn)) {
+            super.warn(this.combine(message, params));
+        }
+        return this;
+    }
+    error(message, ...params) {
+        if (this.enabled(LogLevel.error)) {
+            super.error(this.combine(message, params));
+        }
+        return this;
+    }
+    debug(message, ...params) {
+        if (this.enabled(LogLevel.debug)) {
+            super.debug(this.combine(message, params));
+        }
+        return this;
+    }
+    /** True when {@link logLevel} permits emission at the given level. */
+    enabled(level) {
+        return this.logLevel !== LogLevel.none && level <= this.logLevel;
+    }
+    /** Concatenate a message with its varargs, formatting each via {@link formatParam}. */
+    combine(message, params) {
+        return params.length === 0 ? message : `${message} ${params.map(p => this.formatParam(p)).join(',\n')}`;
+    }
+    /** Format a single param: errors → `message\nstack`; everything else → JSON.stringify(p, undefined, 4). */
+    formatParam(param) {
+        if (param instanceof Error) {
+            return `${param.message}\n${param.stack ?? ''}`;
+        }
+        try {
+            return JSON.stringify(param, undefined, 4);
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Override of {@link LspLogger.derive} that carries the per-instance
+     * narrowing. The base `derive(component)` constructs the subclass with
+     * `{ component }` only, which would drop it.
+     *
+     * It passes {@link logLevelOverride}, NOT `this.logLevel`: an unpinned parent
+     * must yield an unpinned child, or every derived logger freezes at the
+     * threshold in force when the container was built.
+     */
+    derive(component) {
+        const Subclass = this.constructor;
+        return new Subclass(this.services, { logLevel: this.logLevelOverride, component });
+    }
+}
+//# sourceMappingURL=glsp-client-logger.js.map

package/lib/logging/glsp-client-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glsp-client-logger.js","sourceRoot":"","sources":["../../src/logging/glsp-client-logger.ts"],"names":[],"mappings":"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"}

package/lib/logging/index.d.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export * from './glsp-client-logger.js';
+//# sourceMappingURL=index.d.ts.map

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

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

package/lib/logging/index.js

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export * from './glsp-client-logger.js';
+//# sourceMappingURL=index.js.map

package/lib/logging/index.js.map

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

package/lib/node/index.d.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export * from './start-glsp-server.js';
+//# sourceMappingURL=index.d.ts.map

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

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

package/lib/node/index.js

@@ -0,0 +1,13 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+// Server-only entry (`@hydranium/glsp-server/node`). Holds the socket launcher,
+// which binds GLSP's node `SocketServerLauncher` (`@eclipse-glsp/server/node`).
+// The portable `.` entry stays free of that import so it bundles for the browser.
+export * from './start-glsp-server.js';
+//# sourceMappingURL=index.js.map

package/lib/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,gFAAgF;AAChF,gFAAgF;AAChF,kFAAkF;AAClF,cAAc,wBAAwB,CAAC"}

package/lib/node/start-glsp-server.d.ts

@@ -0,0 +1,122 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 Logger as GlspLogger, type ServerModule } from '@eclipse-glsp/server/node.js';
+import { type ContainerModule } from 'inversify';
+import type { Logger } from '@hydranium/protocol';
+import type * as net from 'node:net';
+import type { IntegratedServer } from '@hydranium/core';
+import type { LspConnectionLike } from '@hydranium/core/node';
+/**
+ * Options for {@link startGlspServer}.
+ *
+ * @see {@link startGlspServer} for the lifecycle semantics.
+ */
+export interface GlspServerOptions {
+    /**
+     * Port to bind. Default `0` — OS-assigned ephemeral. Resolve the
+     * actual port off {@link StartedGlspServer.port} once `started`
+     * resolves (only then is the address info available).
+     */
+    readonly port?: number;
+    /**
+     * Host to bind. Default `'127.0.0.1'` (LOCAL ONLY) — the GLSP head is
+     * traffic-only-from-the-companion-client by design; rebinding to a
+     * routable address is an explicit opt-in that adopters must do
+     * deliberately.
+     */
+    readonly host?: string;
+    /**
+     * Adopter-supplied logger factory. Called once per Inversify resolution
+     * (with `caller` set to the requesting parent's class name) AND once
+     * per `LoggerFactory` invocation.
+     *
+     * **The threshold belongs in here, not beside it.** GLSP's own log level is
+     * a property of the logger this factory returns — e.g.
+     * `GlspClientLogger` filters
+     * each call against its own `logLevel` option. There is deliberately no
+     * launcher-level `logLevel`: the framework replaces GLSP's `Logger` binding
+     * outright, so anything passed to GLSP's app module would be discarded, and
+     * an option that looks authoritative and is discarded is worse than none.
+     */
+    readonly createLogger: (caller?: string) => GlspLogger;
+    /**
+     * The GLSP {@link ServerModule} with per-diagram modules
+     * pre-configured via `new ServerModule().configureDiagramModule(...)`.
+     */
+    readonly serverModule: ServerModule;
+    /**
+     * Additional Inversify modules to load on the app container AFTER GLSP's
+     * own app module (via `createAppModule`, which binds `InjectionContainer`
+     * plus the GLSP-version-specific app bindings) and the framework overrides
+     * that route GLSP's logger and logger factory through the adopter logger
+     * and add the shared Tracer. Adopters wire language-services bindings
+     * (e.g. their own shared-services symbol) here.
+     */
+    readonly appModules?: ReadonlyArray<ContainerModule>;
+    /**
+     * Optional LSP connection used to register a port-discovery request
+     * handler. When both `lspConnection` and `portCommand` are set, the
+     * framework registers `lspConnection.onRequest(portCommand, () => port)`
+     * after the GLSP socket is listening — the standard handshake adopters
+     * use to bridge LSP clients to the GLSP head.
+     */
+    readonly lspConnection?: LspConnectionLike;
+    /**
+     * LSP request method name to register. Required when `lspConnection` is
+     * set. Adopters define this constant in their own protocol package.
+     */
+    readonly portCommand?: string;
+    /**
+     * Optional framework-lifecycle logger. Receives `listening` / `error`
+     * lifecycle messages from the launcher itself (the GLSP container's
+     * own logger handles application-level GLSP logs).
+     */
+    readonly logger?: Logger;
+    /**
+     * Optional diagnostic hook called for every incoming `net.Socket` the
+     * GLSP server's `net.Server` accepts. Fires as a side-effect of the
+     * framework's own `'connection'` listener — GLSP's per-connection setup
+     * runs independently from its own listener registered by
+     * `SocketServerLauncher`. Adopters typically attach `'data'` / `'close'`
+     * listeners inside the hook for byte-level observability when debugging
+     * wire-level handshake issues.
+     */
+    readonly onClientConnection?: (socket: net.Socket) => void;
+}
+/**
+ * Live GLSP server handle returned by {@link startGlspServer}.
+ *
+ * - {@link IntegratedServer.started} resolves once the GLSP socket is
+ *   listening AND (if configured) the port-discovery handler has been
+ *   registered on the LSP connection.
+ * - {@link IntegratedServer.stopped} resolves once GLSP's
+ *   `SocketServerLauncher.start` promise settles (i.e. the underlying
+ *   `net.Server` has closed).
+ * - {@link port} is `undefined` until `started` resolves.
+ */
+export interface StartedGlspServer extends IntegratedServer {
+    readonly port: number | undefined;
+}
+/**
+ * Start a GLSP socket head. Builds the GLSP app container with framework-
+ * default `Logger` / `LoggerFactory` bindings, layers adopter modules,
+ * resolves {@link SocketServerLauncher}, configures the adopter
+ * {@link ServerModule}, and starts listening.
+ *
+ * **GLSP launcher coupling.** GLSP's {@link SocketServerLauncher} owns the
+ * `net.Server` and per-connection `MessageConnection` construction;
+ * the framework wrapper composes ABOVE that launcher rather than replacing
+ * it. The framework's own `startSocketServer`
+ * helper is NOT used here — it's designed for stdio/raw-JSON-RPC heads
+ * (data-server's pattern), not GLSP's Inversify-driven per-connection
+ * server-instance model. Bridging the two would lose GLSP's action-handler
+ * registry plumbing.
+ */
+export declare function startGlspServer(options: GlspServerOptions): StartedGlspServer;
+//# sourceMappingURL=start-glsp-server.d.ts.map

package/lib/node/start-glsp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-glsp-server.d.ts","sourceRoot":"","sources":["../../src/node/start-glsp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,KAAK,MAAM,IAAI,UAAU,EACzB,KAAK,YAAY,EAKnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,KAAK,GAAG,MAAM,UAAU,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACrD;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CA+E7E"}