@hydranium/client-theia 1.0.0-next.10

package/src/browser/channel-logger.ts

@@ -0,0 +1,160 @@
+/********************************************************************************
+ * 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 { AbstractLogger, DefaultTracer, type LogLevel, type MemoryReader, SystemClock } from '@hydranium/protocol';
+import { injectable, type interfaces, unmanaged, inject } from '@theia/core/shared/inversify';
+import { type OutputChannel, OutputChannelManager } from '@theia/output/lib/browser/output-channel';
+
+/**
+ * Configuration for a {@link ChannelLogger}, supplied once at bind time via
+ * {@link bindChannelLogger} (the framework's `(deps, options)` constructor
+ * shape — the only piece an adopter must provide is the channel name).
+ *
+ * Note there is no log-threshold option here: the threshold is not a per-logger
+ * concern. See {@link ChannelLogger} for why, and
+ * `LogLevelPreferenceContribution` for the owner.
+ */
+export interface ChannelLoggerOptions {
+   /** Name of the Theia Output channel lines are written to. */
+   readonly channelName: string;
+   /** Initial logger component prefix (see `Logger.for`). */
+   readonly component?: string;
+}
+
+/** Inversify token for the {@link ChannelLoggerOptions} constant (merged with the
+ *  interface name — the standard Theia "type + token under one identifier" idiom). */
+export const ChannelLoggerOptions = Symbol('ChannelLoggerOptions');
+
+/**
+ * Writes client-side lines to a Theia Output channel, formatted to align with
+ * the server-side `LspLogger` so both sides of the conversation interleave
+ * cleanly under the same Output panel entry. Cross-head: the data, LSP, and
+ * GLSP Theia integrations can all reuse it — nothing here is GLSP-specific.
+ *
+ * Concrete and options-configured: adopters wire it with
+ * {@link bindChannelLogger}, supplying {@link ChannelLoggerOptions}, rather
+ * than subclassing to pin a channel name.
+ *
+ * It deliberately owns **no** threshold logic. The threshold is a process-global
+ * shared by every `AbstractLogger`, whereas this class's singleton scope is
+ * whichever container bound it (for a GLSP head, one per diagram) — so applying a
+ * global from here would subscribe a preference listener per container and never
+ * dispose one. `LogLevelPreferenceContribution` owns it instead, at application
+ * scope. This class only formats and appends.
+ */
+@injectable()
+export class ChannelLogger extends AbstractLogger {
+   protected _channel?: OutputChannel;
+
+   constructor(
+      @inject(OutputChannelManager) protected readonly outputChannels: OutputChannelManager,
+      @inject(ChannelLoggerOptions) protected readonly options: ChannelLoggerOptions,
+      @unmanaged() component: string | undefined = options.component
+   ) {
+      super(component);
+   }
+
+   protected get channel(): OutputChannel {
+      return (this._channel ??= this.outputChannels.getChannel(this.options.channelName));
+   }
+
+   protected emit(_level: LogLevel, label: string, message: string, args: readonly unknown[]): void {
+      const componentSegment = this.component ? ` [${this.component}]` : '';
+      const formattedArgs = args.length > 0 ? ' ' + args.map(stringifyArg).join(' ') : '';
+      // Pad to match the server's 5-char label width so timestamps align across sources.
+      this.channel.appendLine(`[${label.padEnd(5)} - ${this.timestamp()}]${componentSegment} ${message}${formattedArgs}`);
+   }
+
+   /**
+    * Allocates a free instance bypassing Inversify, so a derived logger inherits
+    * the same OutputChannelManager + options without going through the container
+    * singleton. Subclasses with additional constructor dependencies must
+    * override and pass the extra args along.
+    */
+   protected derive(component: string): this {
+      const Ctor = this.constructor as new (
+         outputChannels: OutputChannelManager,
+         options: ChannelLoggerOptions,
+         component?: string
+      ) => this;
+      return new Ctor(this.outputChannels, this.options, component);
+   }
+}
+
+/** Private token for the un-tagged singleton base that the per-class dynamic
+ *  binding derives from. Kept module-internal so the only public token is the
+ *  {@link ChannelLogger} class itself. */
+const ChannelLoggerBase = Symbol('ChannelLoggerBase');
+
+/**
+ * Inversify token for the browser `Tracer` — a {@link DefaultTracer} over
+ * the {@link ChannelLogger} (emit sink) + a {@link SystemClock} + a browser
+ * heap reader. The browser head has no Langium `services.Tracer` slot, so this
+ * is how frontend services that time obtain a tracer: `@inject(ChannelTracer)`.
+ * Bound by {@link bindChannelLogger}.
+ */
+export const ChannelTracer = Symbol('ChannelTracer');
+
+/** Reads the requesting class's name from an Inversify context, by walking the
+ *  current request up to its parent binding. */
+export function getRequestParentName(context: interfaces.Context): string | undefined {
+   const parent = context.currentRequest.parentRequest;
+   if (!parent || parent.bindings.length === 0) {
+      return undefined;
+   }
+   const binding = parent.bindings[0] as interfaces.Binding<{ name?: string }>;
+   return binding.implementationType?.name;
+}
+
+/**
+ * Bind the {@link ChannelLogger} for an adopter's Theia frontend:
+ *
+ *   - `bind(ChannelLoggerOptions).toConstantValue(options)` — the config
+ *   - the un-tagged singleton base (private token), constructed by Inversify
+ *   - `bind(ChannelLogger).toDynamicValue(...)` — class-scoped per request, so
+ *     every `@inject(ChannelLogger)` site gets a logger pre-tagged with the
+ *     requesting class name
+ *
+ * Adopters that compose their own module (bypassing a head's module helper)
+ * call this directly; head module helpers (`createGlspClientTheiaModule`)
+ * forward to it.
+ */
+export function bindChannelLogger(bind: interfaces.Bind, options: ChannelLoggerOptions): void {
+   bind(ChannelLoggerOptions).toConstantValue(options);
+   bind(ChannelLoggerBase).to(ChannelLogger).inSingletonScope();
+   bind(ChannelLogger).toDynamicValue(ctx => {
+      const base = ctx.container.get<ChannelLogger>(ChannelLoggerBase);
+      const parentName = getRequestParentName(ctx);
+      return parentName ? base.for(parentName) : base;
+   });
+   bind(ChannelTracer)
+      .toDynamicValue(ctx => new DefaultTracer(ctx.container.get<ChannelLogger>(ChannelLoggerBase), new SystemClock(), readBrowserMemory))
+      .inSingletonScope();
+}
+
+interface ChromiumPerformance {
+   memory?: { usedJSHeapSize: number; totalJSHeapSize: number; jsHeapSizeLimit: number };
+}
+
+/** Browser heap reader for {@link ChannelTracer}, backed by Chromium's non-standard `performance.memory`. */
+const readBrowserMemory: MemoryReader = () => {
+   const mem = (performance as unknown as ChromiumPerformance).memory;
+   return mem ? { usedBytes: mem.usedJSHeapSize, totalBytes: mem.totalJSHeapSize } : undefined;
+};
+
+function stringifyArg(arg: unknown): string {
+   if (typeof arg === 'string') {
+      return arg;
+   }
+   try {
+      return JSON.stringify(arg);
+   } catch {
+      return String(arg);
+   }
+}

package/src/browser/index.ts

@@ -0,0 +1,14 @@
+/********************************************************************************
+ * 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 cross-head Theia client primitives shared by the protocol heads.
+export * from './channel-logger';
+export * from './log-level-preference';
+export * from './browser-capture';
+export * from './memory-diagnostics-contribution';

package/src/browser/log-level-preference.ts

@@ -0,0 +1,127 @@
+/********************************************************************************
+ * 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 { DisposableCollection, Logger, parseLogLevel } from '@hydranium/protocol';
+// Narrow import paths, not the `@theia/core/lib/browser` barrel: it touches DOM
+// globals at module load, which breaks node-environment unit tests. This module
+// only needs the contribution token (a bare Symbol) and two common services.
+import { FrontendApplicationContribution } from '@theia/core/lib/browser/frontend-application-contribution';
+import { ILogger } from '@theia/core/lib/common/logger';
+import { PreferenceService } from '@theia/core/lib/common/preferences/preference-service';
+import { inject, injectable, type interfaces } from '@theia/core/shared/inversify';
+
+/** Inversify token for the preference id {@link LogLevelPreferenceContribution} watches. */
+export const LogLevelPreference = Symbol('LogLevelPreference');
+
+/**
+ * Applies the framework log threshold from a Theia preference, once per
+ * application.
+ *
+ * **Why this is a `FrontendApplicationContribution` and not a logger concern.**
+ * The threshold is a process-global (`Logger.setLevel`, read by every
+ * `AbstractLogger` at emit time), so applying it is an *application* lifecycle
+ * event. Applying it from a logger's `@postConstruct` instead puts a global side
+ * effect on the construction of an object whose singleton scope is the
+ * per-diagram container, which costs two things:
+ *
+ *  - the `onPreferenceChanged` subscription is never disposed AND is re-created
+ *    for every diagram container, so opening N diagrams leaves N live listeners
+ *    holding N loggers;
+ *  - with no diagram open the preference is never applied at all, so anything
+ *    logging before the first diagram runs at the default threshold.
+ *
+ * Bound by {@link bindLogLevelPreference} in the **frontend** container — a
+ * diagram container is a child and cannot contribute to the parent's
+ * multi-binding.
+ */
+@injectable()
+export class LogLevelPreferenceContribution implements FrontendApplicationContribution {
+   @inject(LogLevelPreference) protected readonly preferenceName!: string;
+   @inject(PreferenceService) protected readonly preferences!: PreferenceService;
+   @inject(ILogger) protected readonly logger!: ILogger;
+
+   /** Holds the single preference subscription. `DisposableCollection` disposes a
+    *  push-after-dispose immediately, so a subscription that lands after
+    *  {@link onStop} cannot outlive the application either. */
+   protected readonly toDispose = new DisposableCollection();
+   /** Guards against a second subscription if `onStart` is ever invoked twice —
+    *  a duplicated listener is exactly the failure this contribution exists to
+    *  prevent. */
+   protected subscribed = false;
+
+   /**
+    * Returns `void` rather than the promise, so `FrontendApplication.start` does
+    * NOT await it.
+    *
+    * This is load-bearing: `PreferenceService.ready` resolves only once the
+    * preference providers are initialised, which happens as part of the same
+    * startup sequence that runs the contributions, so awaiting it here deadlocks
+    * the frontend on its preload splash. The threshold is therefore applied as
+    * soon as preferences are ready, which is early but not synchronously before
+    * the first possible log line.
+    */
+   onStart(): void {
+      void this.applyWhenReady();
+   }
+
+   /** The awaited body of {@link onStart}, separated so it can be driven directly
+    *  in tests without going through the non-awaited lifecycle hook. */
+   protected async applyWhenReady(): Promise<void> {
+      try {
+         await this.preferences.ready;
+         this.applyLevel();
+         if (this.subscribed) {
+            return;
+         }
+         this.subscribed = true;
+         this.toDispose.push(
+            this.preferences.onPreferenceChanged(event => {
+               if (event.preferenceName === this.preferenceName) {
+                  this.applyLevel();
+               }
+            })
+         );
+      } catch (err) {
+         // Reported, not swallowed: an unapplied threshold silently hides every
+         // diagnostic below the default, which reads as "the feature is broken".
+         this.logger.error(`Failed to apply the log threshold from '${this.preferenceName}'`, err);
+      }
+   }
+
+   onStop(): void {
+      this.toDispose.dispose();
+   }
+
+   /**
+    * Read the preference and apply it. An unparseable or unset value leaves the
+    * current threshold alone rather than resetting it to a default — the value may
+    * legitimately have been set by another source (an env baseline, a test).
+    *
+    * Override for a custom preference→level mapping.
+    */
+   protected applyLevel(): void {
+      const level = parseLogLevel(this.preferences.get<string>(this.preferenceName));
+      if (level) {
+         Logger.setLevel(level);
+      }
+   }
+}
+
+/**
+ * Bind {@link LogLevelPreferenceContribution} for `preferenceName`.
+ *
+ * Call from a **frontend** container module. Adopters using
+ * `AbstractHydraniumGlspTheiaFrontendModule` set its `logLevelPreference` field
+ * instead and the base calls this for them.
+ */
+export function bindLogLevelPreference(bind: interfaces.Bind, preferenceName: string): void {
+   bind(LogLevelPreference).toConstantValue(preferenceName);
+   bind(LogLevelPreferenceContribution).toSelf().inSingletonScope();
+   bind(FrontendApplicationContribution).toService(LogLevelPreferenceContribution);
+}

package/src/browser/memory-diagnostics-contribution.ts

@@ -0,0 +1,248 @@
+/********************************************************************************
+ * 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 {
+   formatLatencyReport,
+   type DataServerDiagnosticsProtocol,
+   type HostDiagnosticsProtocol,
+   type StartProfilingArgs
+} from '@hydranium/protocol';
+import { captureBrowserRuntime, formatBrowserRuntime } from './browser-capture';
+import { CommandContribution, MessageService, type Command, type CommandRegistry } from '@theia/core';
+import { inject, injectable, optional, type interfaces } from '@theia/core/shared/inversify';
+import { OutputChannelManager, type OutputChannel } from '@theia/output/lib/browser/output-channel';
+
+/**
+ * Per-product branding for {@link MemoryDiagnosticsContribution}. Bound by the
+ * adopter so the command ids, palette category, and output channel carry the
+ * product name. The framework supplies the behaviour; only these strings vary.
+ */
+export interface MemoryDiagnosticsOptions {
+   /** Prefix for the registered command ids: `<commandIdPrefix>.dumpServerState`. */
+   readonly commandIdPrefix: string;
+   /** Command-palette category. */
+   readonly category: string;
+   /** Output channel the full snapshots are appended to (View > Output). */
+   readonly channelName: string;
+}
+export const MemoryDiagnosticsOptions = Symbol('MemoryDiagnosticsOptions');
+
+/**
+ * The server-process diagnostics the commands call. Equals
+ * {@link DataServerDiagnosticsProtocol} (`dumpServerState` / `writeHeapSnapshot`
+ * / `dumpPodMemory`); the adopter binds its data-server frontend proxy (which
+ * exposes those methods after connecting) to this symbol. Kept as a distinct
+ * symbol so the contribution stays decoupled from any concrete frontend type.
+ */
+export type MemoryDiagnosticsService = DataServerDiagnosticsProtocol;
+export const MemoryDiagnosticsService = Symbol('MemoryDiagnosticsService');
+
+/**
+ * Optional host (parent) process diagnostics — the Theia backend itself, reached
+ * by an ordinary in-process RPC service ({@link HostDiagnosticsProtocol}), NOT
+ * the data-server socket. When bound, the contribution adds the "Dump Backend
+ * State" and "Write Heap Snapshot (Backend)" commands; left unbound, those two
+ * commands are simply not registered. `@hydranium/data-client-theia`'s
+ * `bindHostDiagnostics` binds the frontend proxy.
+ */
+export type HostMemoryDiagnosticsService = HostDiagnosticsProtocol;
+export const HostMemoryDiagnosticsService = Symbol('HostMemoryDiagnosticsService');
+
+/**
+ * Memory-diagnostics commands, one per layer reachable from the frontend. Full
+ * multi-line snapshots are appended to the configured output channel; a one-line
+ * summary is toasted.
+ *  - "Dump Server State"      - the data-server process (heap/rss/event-loop/CPU/documents), via RPC.
+ *  - "Dump Pod Memory"        - cgroup current/peak/limit + process-tree RSS (the figure that OOMs a pod), via RPC.
+ *  - "Dump Frontend State"    - the browser tab's JS heap (Chrome `performance.memory`), client-side.
+ *  - "Write Heap Snapshot"    - a V8 heap snapshot of the data-server process, via RPC.
+ *  - "Start/Stop Profiling"   - a windowed CPU/allocation/GC/event-loop sampled profile of the data-server, via RPC.
+ *  - "Record Performance Profile" - the same, wrapped over a fixed window (start, wait, stop, report).
+ *  - "Dump RPC/LSP Latency"   - per-method latency/throughput collected on the server, via RPC.
+ *
+ * Generic: the adopter binds {@link MemoryDiagnosticsOptions} (branding) and
+ * {@link MemoryDiagnosticsService} (its connected data-server frontend) and adds
+ * this class as a `CommandContribution` — see {@link bindMemoryDiagnostics}.
+ */
+@injectable()
+export class MemoryDiagnosticsContribution implements CommandContribution {
+   @inject(MemoryDiagnosticsService) protected readonly diagnostics: MemoryDiagnosticsService;
+   @inject(MemoryDiagnosticsOptions) protected readonly options: MemoryDiagnosticsOptions;
+   @inject(MessageService) protected readonly messageService: MessageService;
+   @inject(OutputChannelManager) protected readonly channels: OutputChannelManager;
+   @inject(HostMemoryDiagnosticsService) @optional() protected readonly hostDiagnostics?: HostMemoryDiagnosticsService;
+
+   /** Dimensions the profiling commands capture — the server samples only what is named. */
+   protected readonly profileDimensions: StartProfilingArgs = { cpu: true, allocation: true, gc: true, eventLoopDelay: true };
+   /** Window length for the "Record Performance Profile" command. */
+   protected readonly recordDurationMs = 10_000;
+   /**
+    * Label of the stop-profiling command, and of the action its start toast
+    * offers. One field for both: two literals naming one command can be
+    * localized apart, leaving a button or an instruction that names a command
+    * the user cannot find.
+    */
+   protected readonly stopProfilingLabel: string = 'Stop Profiling (Server)';
+
+   registerCommands(registry: CommandRegistry): void {
+      const { category } = this.options;
+      registry.registerCommand(this.command('dumpServerState', 'Dump Server State', category), {
+         execute: () => this.report('server state', () => this.diagnostics.dumpServerState({ label: new Date().toISOString() }), ['heap'])
+      });
+      registry.registerCommand(this.command('dumpPodMemory', 'Dump Pod Memory', category), {
+         execute: () => this.report('pod memory', () => this.diagnostics.dumpPodMemory(), ['current', 'rss sum'])
+      });
+      registry.registerCommand(this.command('dumpFrontendState', 'Dump Frontend State', category), {
+         execute: () => this.dumpFrontendState()
+      });
+      registry.registerCommand(this.command('writeHeapSnapshot', 'Write Heap Snapshot (Server)', category), {
+         execute: () => this.writeSnapshot('server', label => this.diagnostics.writeHeapSnapshot({ label }))
+      });
+      // Sampled profiling of the server process — sampling does NOT pause it (unlike
+      // the heap snapshot). Start/Stop are the manual pair; Record wraps a fixed window.
+      registry.registerCommand(this.command('startProfiling', 'Start Profiling (Server)', category), {
+         execute: () => this.startProfiling()
+      });
+      registry.registerCommand(this.command('stopProfiling', this.stopProfilingLabel, category), {
+         execute: () => this.stopProfiling()
+      });
+      registry.registerCommand(
+         this.command('recordProfile', `Record Performance Profile (Server, ${Math.round(this.recordDurationMs / 1000)}s)`, category),
+         {
+            execute: () => this.recordProfile()
+         }
+      );
+      registry.registerCommand(this.command('dumpLatency', 'Dump RPC/LSP Latency (Server)', category), {
+         execute: () => this.report('RPC/LSP latency', async () => formatLatencyReport(await this.diagnostics.getLatency()), ['window'])
+      });
+      // Host (Theia backend) process commands — registered only when the
+      // optional host-diagnostics service is bound (see HostMemoryDiagnosticsService).
+      const hostDiagnostics = this.hostDiagnostics;
+      if (hostDiagnostics) {
+         registry.registerCommand(this.command('dumpBackendState', 'Dump Backend State', category), {
+            execute: () => this.report('backend state', () => hostDiagnostics.dumpHostState({ label: new Date().toISOString() }), ['heap'])
+         });
+         registry.registerCommand(this.command('writeBackendHeapSnapshot', 'Write Heap Snapshot (Backend)', category), {
+            execute: () => this.writeSnapshot('backend', label => hostDiagnostics.writeHostHeapSnapshot({ label }))
+         });
+      }
+   }
+
+   protected command(id: string, label: string, category: string): Command {
+      return { id: `${this.options.commandIdPrefix}.${id}`, label, category };
+   }
+
+   /** Run a snapshot call, append the full result to the channel, toast the first matching summary line. */
+   protected async report(what: string, produce: () => Promise<string>, summaryKeys: string[]): Promise<void> {
+      try {
+         const snapshot = await produce();
+         this.channel().appendLine(snapshot);
+         this.channel().appendLine('');
+         this.messageService.info(this.summarize(snapshot, what, summaryKeys), { timeout: 5000 });
+      } catch (error) {
+         this.messageService.error(`Failed to dump ${what}: ${this.errorMessage(error)}`);
+      }
+   }
+
+   protected async writeSnapshot(target: string, produce: (label: string) => Promise<string>): Promise<void> {
+      try {
+         this.messageService.info(`Writing ${target} heap snapshot — this briefly pauses that process...`, { timeout: 3000 });
+         const filePath = await produce(new Date().toISOString());
+         this.channel().appendLine(`Heap snapshot (${target}) written to ${filePath}`);
+         this.messageService.info(`Heap snapshot (${target}) written to ${filePath}`, { timeout: 8000 });
+      } catch (error) {
+         this.messageService.error(`Failed to write ${target} heap snapshot: ${this.errorMessage(error)}`);
+      }
+   }
+
+   /** Begin an open-ended capture; the toast's stop action ends it and reports. */
+   protected async startProfiling(): Promise<void> {
+      try {
+         await this.diagnostics.startProfiling(this.profileDimensions);
+      } catch (error) {
+         this.messageService.error(`Failed to start profiling: ${this.errorMessage(error)}`);
+         return;
+      }
+      // No timeout: the capture runs as long as the user wants it to, and an
+      // auto-dismissing toast takes the stop affordance with it. Awaiting the
+      // toast is what keeps the action live, so this resolves only once the
+      // user acts on it or dismisses it.
+      const chosen = await this.messageService.info(
+         'Server profiling started — sampling does not stop the process.',
+         { timeout: 0 },
+         this.stopProfilingLabel
+      );
+      if (chosen === this.stopProfilingLabel) {
+         await this.stopProfiling();
+      }
+   }
+
+   /** End the capture and report it. Shared, so the toast action and the command cannot diverge in behaviour. */
+   protected stopProfiling(): Promise<void> {
+      return this.report('profile', () => this.diagnostics.stopProfiling({ label: new Date().toISOString() }), ['duration']);
+   }
+
+   /** Capture a fixed-length window: start, wait, stop, and report the result. */
+   protected async recordProfile(): Promise<void> {
+      try {
+         await this.diagnostics.startProfiling(this.profileDimensions);
+      } catch (error) {
+         this.messageService.error(`Failed to start profiling: ${this.errorMessage(error)}`);
+         return;
+      }
+      this.messageService.info(`Recording a ${Math.round(this.recordDurationMs / 1000)}s server performance profile...`, { timeout: 4000 });
+      await this.delay(this.recordDurationMs);
+      await this.stopProfiling();
+   }
+
+   /** Isolated so tests can drive the record window without a real timer. */
+   protected delay(ms: number): Promise<void> {
+      return new Promise(resolve => setTimeout(resolve, ms));
+   }
+
+   protected async dumpFrontendState(): Promise<void> {
+      const text = formatBrowserRuntime(await captureBrowserRuntime());
+      this.channel().appendLine(text);
+      this.messageService.info(text, { timeout: 6000 });
+   }
+
+   protected channel(): OutputChannel {
+      const channel = this.channels.getChannel(this.options.channelName);
+      channel.show({ preserveFocus: true });
+      return channel;
+   }
+
+   /** Pull the first line starting with one of `keys` for a one-line toast; full text is in the channel. */
+   protected summarize(snapshot: string, what: string, keys: string[]): string {
+      const lines = snapshot.split('\n');
+      for (const key of keys) {
+         const line = lines.find(entry => entry.trim().startsWith(key));
+         if (line) {
+            return `Captured ${what} —${line.replace(new RegExp(`^\\s*${key}\\s*`), ` ${key} `)}`;
+         }
+      }
+      return `Captured ${what} (see the ${this.options.channelName} output channel)`;
+   }
+
+   protected errorMessage(error: unknown): string {
+      return error instanceof Error ? error.message : String(error);
+   }
+}
+
+/**
+ * Bind {@link MemoryDiagnosticsContribution} as a `CommandContribution` with the
+ * given branding. The adopter still binds {@link MemoryDiagnosticsService} to its
+ * connected data-server frontend separately (the framework cannot — the concrete
+ * frontend is adopter-defined). Call from a Theia frontend `ContainerModule`.
+ */
+export function bindMemoryDiagnostics(bind: interfaces.Bind, options: MemoryDiagnosticsOptions): void {
+   bind(MemoryDiagnosticsOptions).toConstantValue(options);
+   bind(MemoryDiagnosticsContribution).toSelf().inSingletonScope();
+   bind(CommandContribution).toService(MemoryDiagnosticsContribution);
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/********************************************************************************
+ * 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. Every surface this package has is environment-bound, so the root
+// exposes nothing directly rather than privileging one tier: node-side
+// primitives (the socket-forwarding connection-handler base, which imports
+// `node:net`) via `@hydranium/client-theia/node`; browser-side primitives (the
+// preference-driven Output-channel logger, the renderer-runtime capture, the
+// memory-diagnostics contribution) via `@hydranium/client-theia/browser`;
+// shared test doubles via `@hydranium/client-theia/testing`. Re-exporting
+// either tier here would drag a `node:net` import or a DOM type into the entry
+// a consumer of the *other* tier resolves first.
+export {};