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

package/src/hidden-bounds-updater.ts

@@ -0,0 +1,210 @@
+/********************************************************************************
+ * 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 { type Clock, type Logger, SystemClock } from '@hydranium/protocol';
+import { inject, injectable, optional } from 'inversify';
+import { type VNode } from 'snabbdom';
+import { HydraniumClientTypes } from './types';
+
+/** 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 log. */
+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 `createGlspClientModule` via `rebind(GLSPHiddenBoundsUpdater)`.
+ */
+@injectable()
+export class HydraniumHiddenBoundsUpdater extends GLSPHiddenBoundsUpdater {
+   @inject(HydraniumClientTypes.Logger) protected readonly hydraniumLogger!: Logger;
+
+   /** The diagram container's {@link Clock}, or a `SystemClock`; it only measures. */
+   @inject(HydraniumClientTypes.Clock) @optional() 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.hydraniumLogger.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/index.ts

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+// The host-neutral GLSP client classes and the binder that mounts them. This
+// root is browser-bound, not neutral: it loads `@eclipse-glsp/client`, whose
+// graph imports stylesheets, so it needs a bundler with a CSS loader. It is
+// free of Node and of any host platform, which is the claim `check:neutral`
+// gates.
+export * from './action-dispatcher';
+export * from './diagram-load-failed';
+export * from './diagram-loader';
+export * from './edge';
+export * from './glsp-client';
+export * from './glsp-client-module';
+export * from './hidden-bounds-updater';
+export * from './select-mouse-listener';
+export * from './sprotty-logger-adapter';
+export * from './status-overlay';
+export * from './types';

package/src/messages/index.ts

@@ -0,0 +1,17 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+// Every user-facing message `@hydranium/glsp-client` raises. The client tier
+// renders only its own messages, which fire when no server could have worded
+// them: the loader formats the English, and a host that knows the reading
+// user's locale renders the code through its own mechanism instead, as the
+// Theia loader does through `nls`. The barrel is how an adopter rendering their
+// own diagram chrome discovers the codes exist.
+
+export { DIAGRAM_LOAD_FAILED } from '../diagram-load-failed';

package/src/select-mouse-listener.ts

@@ -0,0 +1,54 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import {
+   type Action,
+   BringToFrontAction,
+   type GModelElement,
+   GRoutingHandle,
+   isCtrlOrCmd,
+   RankedSelectMouseListener,
+   SelectAction,
+   type SelectableElement
+} from '@eclipse-glsp/client';
+import { injectable } from 'inversify';
+
+/**
+ * GLSP's select mouse listener, with a plain click on an unselected element
+ * replacing whatever is selected when its action executes.
+ *
+ * The listener names the elements a click deselects from each element's
+ * `selected` flag, which the feedback the previous click's command queues
+ * writes only when that feedback runs; a click landing before then names
+ * nothing, and both elements end up selected. A plain click sends
+ * `deselectAll` instead, which `SelectCommand` resolves against the selection
+ * service as it executes. Reading the service from the listener would still
+ * race the previous click's command, since dispatch is asynchronous.
+ * Ctrl/Cmd-click keeps GLSP's add to the selection; a routing handle keeps
+ * GLSP's path, since `deselectAll` cannot spare the handle's own edge.
+ *
+ * Bound by `createGlspClientModule` via `rebind(RankedSelectMouseListener)`.
+ */
+@injectable()
+export class HydraniumSelectMouseListener extends RankedSelectMouseListener {
+   protected override handleSelectTarget(
+      selectableTarget: SelectableElement,
+      deselectedElements: GModelElement[],
+      event: MouseEvent
+   ): (Action | Promise<Action>)[] {
+      if (isCtrlOrCmd(event) || selectableTarget instanceof GRoutingHandle) {
+         return super.handleSelectTarget(selectableTarget, deselectedElements, event);
+      }
+      return [SelectAction.setSelection([selectableTarget.id]), BringToFrontAction.create([selectableTarget.id])];
+   }
+
+   protected override handleDeselectAll(): (Action | Promise<Action>)[] {
+      return [SelectAction.setSelection([])];
+   }
+}

package/src/sprotty-logger-adapter.ts

@@ -0,0 +1,121 @@
+/********************************************************************************
+ * 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 ILogger, LogLevel } from '@eclipse-glsp/client';
+import { Logger } from '@hydranium/protocol';
+import { inject, injectable } from 'inversify';
+import { HydraniumClientTypes } from './types';
+
+/** GLSP's wording for a request it resolved silently after its timeout. If
+ *  upstream rewords it, the notice degrades to `debug` with the rest of `info`. */
+const REQUEST_TIMED_OUT = /\btime out after \d+ms\b/;
+
+/**
+ * sprotty's `ILogger` over the host's {@link Logger}, so sprotty's own lines
+ * reach the same sink as the framework's: a view-registration failure lands in
+ * the Theia Output channel beside the action traffic, or on a page's console.
+ * sprotty binds a `NullLogger` by default, which drops those failures.
+ *
+ * sprotty's `error` and `warn` keep their levels and their parameters, where
+ * the parameter is the useful part, such as the element type that has no view.
+ *
+ * Its `info` is diagnosis, chatty on every hover's feedback, so it goes to
+ * `debug`; the one anomaly reported there, a request GLSP resolved silently
+ * after its timeout, goes to `warn`, where a default threshold shows it.
+ *
+ * Its `log` fires per action, per command and per render with the whole action
+ * or model as a parameter, so it goes to `trace`, where the framework
+ * dispatcher logs that traffic. **At `info` and `log` a parameter is reduced to
+ * its name**, an action's `kind` or an object's class, never forwarded whole:
+ * the Theia channel logger stringifies every parameter as JSON, so forwarding
+ * them would write the model into the Output channel on every action.
+ *
+ * Each line goes through a logger nested under the host's for the calling
+ * class, cached per class, so the origin is a tag the host renders inside its
+ * own, `[GLSP client :: Viewer]`, not a prefix inside the message. Where
+ * sprotty passes a sentence instead of the caller, as its layout registries
+ * do, the sentence prefixes the message. The adapter's own `logLevel` is
+ * sprotty's most verbose, so only the framework threshold filters; `info` and
+ * `log` check it first, since they run on every action and render and would
+ * otherwise format a line the threshold drops.
+ *
+ * Bound by `createGlspClientModule` via `rebind(TYPES.ILogger)`.
+ */
+@injectable()
+export class SprottyLoggerAdapter implements ILogger {
+   @inject(HydraniumClientTypes.Logger) protected readonly logger!: Logger;
+
+   logLevel: LogLevel = LogLevel.log;
+
+   /** Loggers derived per calling class; sprotty logs from a few dozen classes. */
+   protected readonly loggers = new Map<string, Logger>();
+
+   error(thisArg: unknown, message: string, ...params: unknown[]): void {
+      this.loggerFor(thisArg).error(this.formatMessage(thisArg, message), ...params);
+   }
+
+   warn(thisArg: unknown, message: string, ...params: unknown[]): void {
+      this.loggerFor(thisArg).warn(this.formatMessage(thisArg, message), ...params);
+   }
+
+   info(thisArg: unknown, message: string, ...params: unknown[]): void {
+      if (REQUEST_TIMED_OUT.test(message)) {
+         this.loggerFor(thisArg).warn(this.formatMessage(thisArg, message, params));
+      } else if (Logger.isLevelEnabled('debug')) {
+         this.loggerFor(thisArg).debug(this.formatMessage(thisArg, message, params));
+      }
+   }
+
+   log(thisArg: unknown, message: string, ...params: unknown[]): void {
+      if (Logger.isLevelEnabled('trace')) {
+         this.loggerFor(thisArg).trace(this.formatMessage(thisArg, message, params));
+      }
+   }
+
+   /** The host's logger with the calling class nested under its tag, or the
+    *  host's own when the caller is not an object. */
+   protected loggerFor(thisArg: unknown): Logger {
+      const caller = typeof thisArg === 'object' && thisArg !== null ? this.nameOf(thisArg) : undefined;
+      if (caller === undefined) {
+         return this.logger;
+      }
+      let derived = this.loggers.get(caller);
+      if (derived === undefined) {
+         derived = this.logger.sub(caller);
+         this.loggers.set(caller, derived);
+      }
+      return derived;
+   }
+
+   /** The message, behind the sentence sprotty sometimes passes as the caller,
+    *  followed by the parameters' names. */
+   protected formatMessage(thisArg: unknown, message: string, params: readonly unknown[] = []): string {
+      const text = typeof thisArg === 'string' ? `${thisArg}${message}` : message;
+      return [text, ...params.map(param => this.nameOf(param)).filter(name => name !== undefined)].join(' ');
+   }
+
+   /** An action's `kind`, also inside the message GLSP sends an action in, a
+    *  string as it is, any other object's class, else nothing. */
+   protected nameOf(value: unknown): string | undefined {
+      if (typeof value === 'string') {
+         return value;
+      }
+      if (typeof value !== 'object' || value === null) {
+         return undefined;
+      }
+      const { kind, action } = value as { kind?: unknown; action?: { kind?: unknown } };
+      if (typeof kind === 'string') {
+         return kind;
+      }
+      if (typeof action?.kind === 'string') {
+         return action.kind;
+      }
+      return value.constructor?.name;
+   }
+}

package/src/status-overlay.ts

@@ -0,0 +1,43 @@
+/********************************************************************************
+ * 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 StatusAction, StatusOverlay } from '@eclipse-glsp/client';
+import { injectable } from 'inversify';
+
+/**
+ * GLSP's status overlay, kept on the page.
+ *
+ * It inserts its element into the diagram's base div when the diagram starts,
+ * and sprotty's first render then replaces that div with its own, so the element
+ * is left detached and no status it shows is ever seen. This puts the element
+ * back into the current base div before it shows anything.
+ */
+@injectable()
+export class HydraniumStatusOverlay extends StatusOverlay {
+   override handle(action: StatusAction): void {
+      this.reattach();
+      super.handle(action);
+   }
+
+   override show(...args: Parameters<StatusOverlay['show']>): void {
+      super.show(...args);
+      this.reattach();
+   }
+
+   protected reattach(): void {
+      const container = this.containerElement as HTMLElement | undefined;
+      if (!container || container.isConnected) {
+         return;
+      }
+      const parent = this.getParentContainer();
+      if (parent) {
+         this.insertContainerIntoParent(container, parent);
+      }
+   }
+}

package/src/testing/bind-recorder.ts

@@ -0,0 +1,126 @@
+/********************************************************************************
+ * 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 { interfaces } from 'inversify';
+
+/**
+ * One captured `bind(...)` or `rebind(...)` call on a {@link BindRecorder}.
+ *
+ * `chain` holds the follow-up methods in invocation order, one string per call,
+ * rendered as `name(arg, …)`. Arguments are stringified inline so assertions
+ * can compare structure without re-resolving service identifiers.
+ */
+export interface BindRecorderEntry {
+   readonly kind: 'bind' | 'rebind';
+   readonly token: unknown;
+   readonly chain: string[];
+}
+
+/**
+ * A spy set of Inversify binding hooks that records every call and its chain.
+ * Hand them to a module-factory under test — they satisfy Inversify's
+ * `interfaces.Bind` / `interfaces.Rebind` / `interfaces.Unbind` /
+ * `interfaces.IsBound` shapes at the call site but never resolve real services.
+ *
+ * Together they match GLSP's `BindingContext`, so a factory taking the whole
+ * context is called as `factory(recorder, options)` — the recorder *is*
+ * structurally a context.
+ *
+ * Use {@link captured} to assert which tokens were touched and with what
+ * fluent chain. {@link find} is a small ergonomic helper for the common
+ * lookup pattern.
+ */
+export interface BindRecorder {
+   readonly bind: interfaces.Bind;
+   readonly rebind: interfaces.Rebind;
+   readonly unbind: interfaces.Unbind;
+   readonly isBound: interfaces.IsBound;
+   readonly captured: readonly BindRecorderEntry[];
+   /** Convenience lookup — returns the first entry matching both `kind` and `token`, or `undefined`. */
+   find(kind: 'bind' | 'rebind', token: unknown): BindRecorderEntry | undefined;
+}
+
+/** Options for {@link makeBindRecorder}. */
+export interface BindRecorderOptions {
+   /**
+    * What `isBound` answers. Defaults to `true` for every token, matching
+    * production: a head registers its own module *after* the GLSP default
+    * modules, so the tokens a framework module rebinds are already bound. Pass a
+    * list to model a container where only those tokens are bound — e.g. to
+    * exercise a factory's bind-instead-of-rebind fallback.
+    */
+   readonly boundTokens?: readonly unknown[];
+}
+
+/** Methods on Inversify's binding builder that the recorder traps verbatim. */
+const RECORDED_CHAIN_METHODS = [
+   'toSelf',
+   'to',
+   'toService',
+   'toConstantValue',
+   'toDynamicValue',
+   'toFactory',
+   'toFunction',
+   'toAutoFactory',
+   'toProvider',
+   'inSingletonScope',
+   'inTransientScope',
+   'inRequestScope',
+   'whenTargetNamed',
+   'whenTargetTagged',
+   'whenInjectedInto',
+   'onActivation',
+   'onDeactivation'
+] as const;
+
+/**
+ * Build a {@link BindRecorder} for testing Inversify module factories without a
+ * real container: hand it to the factory, then assert over {@link BindRecorder.find}.
+ *
+ * The `bind` / `rebind` functions return a chained proxy that ignores its
+ * arguments structurally but records every method invocation as a string.
+ * Stringification: functions → `<className>`, symbols → `Symbol(desc).toString()`,
+ * everything else → `String(value)`. This is enough to assert which tokens are
+ * involved without dragging real service resolution into the test.
+ */
+export function makeBindRecorder(options: BindRecorderOptions = {}): BindRecorder {
+   const captured: BindRecorderEntry[] = [];
+
+   const stringifyArg = (value: unknown): string => {
+      if (typeof value === 'function') {
+         return `<${value.name || 'fn'}>`;
+      }
+      if (typeof value === 'symbol') {
+         return value.toString();
+      }
+      return String(value);
+   };
+
+   const beginEntry = (kind: 'bind' | 'rebind', token: unknown): unknown => {
+      const entry: BindRecorderEntry = { kind, token, chain: [] };
+      captured.push(entry);
+      const proxy: Record<string, (...args: unknown[]) => unknown> = {};
+      for (const method of RECORDED_CHAIN_METHODS) {
+         proxy[method] = (...args: unknown[]): unknown => {
+            entry.chain.push(`${method}(${args.map(stringifyArg).join(', ')})`);
+            return proxy;
+         };
+      }
+      return proxy;
+   };
+
+   const bind = ((token: unknown) => beginEntry('bind', token)) as interfaces.Bind;
+   const rebind = ((token: unknown) => beginEntry('rebind', token)) as interfaces.Rebind;
+   const unbind = (() => undefined) as unknown as interfaces.Unbind;
+   const isBound = ((token: unknown) => options.boundTokens?.includes(token) ?? true) as interfaces.IsBound;
+   const find = (kind: 'bind' | 'rebind', token: unknown): BindRecorderEntry | undefined =>
+      captured.find(entry => entry.kind === kind && entry.token === token);
+
+   return { bind, rebind, unbind, isBound, captured, find };
+}

package/src/testing/index.ts

@@ -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
+ ********************************************************************************/
+
+// Subpath barrel for `@hydranium/glsp-client/testing` — the Inversify binding
+// recorder for testing a module factory without a container.
+
+export * from './bind-recorder';

package/src/types.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 type { Clock, Logger, Tracer } from '@hydranium/protocol';
+import type { interfaces } from 'inversify';
+
+/** A fresh `Symbol` cast to inversify's typed identifier, so `bind` and
+ *  `@inject` sites type-check against `T` rather than `any`. */
+function serviceIdentifier<T>(description: string): interfaces.ServiceIdentifier<T> {
+   return Symbol(description) as interfaces.ServiceIdentifier<T>;
+}
+
+/**
+ * The DI tokens the framework's client classes inject, typed by the protocol
+ * interfaces so a host binds whatever implementation it has: a Theia frontend
+ * binds its Output-channel logger, a page or webview a console logger. Kept in
+ * a registry so a token's name cannot collide with the type it injects.
+ *
+ * `Logger` and `Tracer` are required, so a host that binds neither fails at
+ * resolution rather than running silent; `createGlspClientModule` binds
+ * defaults for a host that passes none. `Clock` is optional: the classes fall
+ * back to a `SystemClock`.
+ */
+export const HydraniumClientTypes = {
+   Logger: serviceIdentifier<Logger>('HydraniumClientLogger'),
+   Tracer: serviceIdentifier<Tracer>('HydraniumClientTracer'),
+   Clock: serviceIdentifier<Clock>('HydraniumClientClock')
+} as const;