@hydranium/client-theia 1.0.0-next.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# `@hydranium/client-theia`
+
+Cross-head Theia client primitives for the
+[Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework.
+
+This is the host-coupled layer every hydranium head shares when it runs inside a
+Theia application: the Output-channel logger, the log-threshold preference
+binding, the memory-diagnostics command set, and the backend base class that
+bridges a Theia frontend channel to a server socket. It carries no head-specific
+dependency — `@hydranium/data-client-theia` and `@hydranium/glsp-client-theia`
+both build on it. Install it if you are assembling a Theia extension around a
+hydranium server; a non-Theia host does not need it.
+
+## What it gives you
+
+- **`ChannelLogger`** with `bindChannelLogger` — writes frontend log lines into a
+  Theia Output channel, formatted to interleave with the server's own log so both
+  sides of the conversation read as one transcript. The same call also binds
+  `ChannelTracer`, the `Tracer` token frontend services inject when they time
+  something.
+- **`LogLevelPreferenceContribution`** with `bindLogLevelPreference` — applies the
+  framework log threshold from a Theia preference once per application, and keeps
+  it in sync on change. It is a `FrontendApplicationContribution` on purpose: the
+  threshold is process-global, so applying it from a per-diagram container would
+  leak one preference listener per container.
+- **`MemoryDiagnosticsContribution`** with `bindMemoryDiagnostics` — the whole
+  diagnostics command set, parameterised by three branding strings
+  (`MemoryDiagnosticsOptions`: `commandIdPrefix`, `category`, `channelName`):
+  Dump Server State, Dump Pod Memory, Dump Frontend State, Write Heap Snapshot
+  (Server), Start / Stop Profiling (Server), Record Performance Profile, and Dump
+  RPC/LSP Latency. Two more — Dump Backend State and Write Heap Snapshot
+  (Backend) — register only when the optional `HostMemoryDiagnosticsService` is
+  bound. You bind `MemoryDiagnosticsService` to your own connected data-server
+  frontend; the framework cannot, because that class is yours.
+- **`captureBrowserRuntime` / `formatBrowserRuntime`** — the renderer's own memory
+  reading as a `BrowserRuntimeReport`, preferring the standardized
+  `performance.measureUserAgentSpecificMemory()` and falling back to Chromium's
+  coarse `performance.memory`.
+- **`AbstractSocketForwardingConnectionHandler`** (Node side) — the abstract base for the
+  Theia _backend_ half of a head's transport. It discovers the server's listening
+  port by executing a registered command, opens a `net.Socket`, and relays bytes
+  between the frontend channel and it. The one abstract hook is which byte
+  forwarder bridges the two; port discovery, connect orchestration, and the
+  buffer-and-replay fix for frontend writes that arrive before the forwarder is
+  wired all live here.
+- **`./testing`** — `makeStubOutputChannelManager` and `makeStubInversifyContext`,
+  the doubles that let the pieces above be unit-tested without a Theia
+  application.
+
+## Install
+
+```bash
+npm install @hydranium/client-theia
+```
+
+You must already have a Theia application (or a Theia extension inside one). The
+declared peer dependencies are:
+
+| Peer                  | Range         |
+| --------------------- | ------------- |
+| `@hydranium/protocol` | `^1.0.0-next` |
+| `@theia/core`         | `^1.71.0`     |
+| `@theia/output`       | `^1.71.0`     |
+| `inversify`           | `^6.0.0`      |
+
+`@theia/output` is easy to miss: the memory-diagnostics commands and the channel
+logger both write to an Output channel, so a host that does not already depend on
+it has to add it.
+
+## Wiring
+
+This package is a **library, not a Theia extension** — it declares no
+`theiaExtensions`, so dropping it into an application wires nothing on its own.
+Your own extension package declares the `theiaExtensions` entries and imports
+from here:
+
+- a **frontend** module (a `ContainerModule` in the extension's `browser/` tier)
+  calls the `bind*` helpers — `bindChannelLogger`, `bindLogLevelPreference`,
+  `bindMemoryDiagnostics` — and binds `MemoryDiagnosticsService` to your
+  data-server frontend;
+- a **backend** module (the extension's `node/` tier) registers a
+  `AbstractSocketForwardingConnectionHandler` subclass as a Theia `ConnectionHandler`. In
+  practice you subclass one of the head-specific subclasses shipped by
+  `@hydranium/data-client-theia` or `@hydranium/glsp-client-theia` rather than
+  this base directly.
+
+## Entry points
+
+| Subpath     | Holds                                                                                                                                                                                                            | Environment                      |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| `.`         | Nothing. Deliberately empty, so an environment-specific import cannot reach the wrong bundle through a barrel.                                                                                                    | browser-neutral (gated)          |
+| `./browser` | `ChannelLogger`, `ChannelTracer`, `LogLevelPreferenceContribution`, `MemoryDiagnosticsContribution`, the `bind*` helpers, `captureBrowserRuntime`                                                                 | browser / Theia frontend (gated) |
+| `./node`    | `AbstractSocketForwardingConnectionHandler` and its options — imports `node:net`                                                                                                                                          | Node / Theia backend             |
+| `./testing` | `makeStubOutputChannelManager`, `makeStubInversifyContext`                                                                                                                                                        | browser-neutral (gated)          |
+
+Every subpath also has a `./lib/<name>` twin, so a consumer on
+`moduleResolution: "Node"` can reach it. "Gated" means the entry is enforced
+browser-neutral by the repository's neutral-bundle check: it must bundle for the
+browser with no `node:*` import, including transitive ones — and [what "gated neutral" does and does not promise](../../docs/concepts/browser-hosting.md#a-note-on-what-gated-neutral-does-and-does-not-promise).
+`./node` is deliberately not gated — that tier is where Node-only code belongs.
+
+## Status
+
+Alpha — pre-v0, not yet published. The API is not stable and may change without a
+deprecation cycle. See [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md) for
+how the Theia client tier relates to the heads, and the
+[repository README](../../README.md) for current status and known limitations.
+
+## License
+
+`MIT` — see this package's [`LICENSE`](./LICENSE). Third-party notices for the
+runtime dependency closure are collected in the repository
+[`NOTICE.md`](../../NOTICE.md).

package/lib/browser/browser-capture.d.ts

@@ -0,0 +1,21 @@
+/********************************************************************************
+ * 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 { BrowserRuntimeReport } from '@hydranium/protocol';
+/**
+ * Capture the renderer runtime as a single-point {@link BrowserRuntimeReport}
+ * (`after`-only — the live gauge read). Prefers the standardized
+ * `performance.measureUserAgentSpecificMemory()` (precise, by type + container, but
+ * requires cross-origin isolation and is rate-limited), falling back to Chrome's
+ * coarse `performance.memory` (JS-heap gauge), then to `unavailable`. The two-point
+ * CDP source (`nodes`/`jsEventListeners`/… + delta) is the e2e bridge's job.
+ */
+export declare function captureBrowserRuntime(): Promise<BrowserRuntimeReport>;
+/** Render a {@link BrowserRuntimeReport} as a one-line summary for a channel / toast. */
+export declare function formatBrowserRuntime(report: BrowserRuntimeReport): string;
+//# sourceMappingURL=browser-capture.d.ts.map

package/lib/browser/browser-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-capture.d.ts","sourceRoot":"","sources":["../../src/browser/browser-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAYlF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAOhE;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAqB3E;AAMD,yFAAyF;AACzF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAYzE"}

package/lib/browser/browser-capture.js

@@ -0,0 +1,61 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureBrowserRuntime = captureBrowserRuntime;
+exports.formatBrowserRuntime = formatBrowserRuntime;
+/**
+ * Capture the renderer runtime as a single-point {@link BrowserRuntimeReport}
+ * (`after`-only — the live gauge read). Prefers the standardized
+ * `performance.measureUserAgentSpecificMemory()` (precise, by type + container, but
+ * requires cross-origin isolation and is rate-limited), falling back to Chrome's
+ * coarse `performance.memory` (JS-heap gauge), then to `unavailable`. The two-point
+ * CDP source (`nodes`/`jsEventListeners`/… + delta) is the e2e bridge's job.
+ */
+async function captureBrowserRuntime() {
+    const perf = globalThis.performance;
+    if (perf?.measureUserAgentSpecificMemory) {
+        try {
+            const result = await perf.measureUserAgentSpecificMemory();
+            return { source: 'measureUserAgentSpecificMemory', after: { totalBytes: result.bytes, breakdown: result.breakdown } };
+        }
+        catch {
+            // COI missing or rate-limited — fall through to the coarse fallback.
+        }
+    }
+    if (perf?.memory) {
+        return {
+            source: 'performance.memory',
+            after: {
+                jsHeapUsedBytes: perf.memory.usedJSHeapSize,
+                jsHeapTotalBytes: perf.memory.totalJSHeapSize,
+                jsHeapLimitBytes: perf.memory.jsHeapSizeLimit
+            }
+        };
+    }
+    return { source: 'unavailable', after: {} };
+}
+function mb(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** Render a {@link BrowserRuntimeReport} as a one-line summary for a channel / toast. */
+function formatBrowserRuntime(report) {
+    const { after } = report;
+    if (report.source === 'measureUserAgentSpecificMemory' && after.totalBytes !== undefined) {
+        return `Browser renderer memory (precise): ${mb(after.totalBytes)} total across JS/DOM/workers.`;
+    }
+    if (report.source === 'performance.memory' && after.jsHeapUsedBytes !== undefined) {
+        const used = after.jsHeapUsedBytes;
+        const total = after.jsHeapTotalBytes ?? 0;
+        const limit = after.jsHeapLimitBytes ?? 0;
+        return `Browser JS heap: ${mb(used)} used / ${mb(total)} total / ${mb(limit)} limit (JS heap only, not the full renderer).`;
+    }
+    return 'Browser memory info unavailable (non-Chromium, or performance.memory disabled / cross-origin isolation off).';
+}
+//# sourceMappingURL=browser-capture.js.map

package/lib/browser/browser-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-capture.js","sourceRoot":"","sources":["../../src/browser/browser-capture.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;AA2BlF,sDAqBC;AAOD,oDAYC;AAhDD;;;;;;;GAOG;AACI,KAAK,UAAU,qBAAqB;IACxC,MAAM,IAAI,GAAG,UAAU,CAAC,WAAmE,CAAC;IAC5F,IAAI,IAAI,EAAE,8BAA8B,EAAE,CAAC;QACxC,IAAI,CAAC;YACF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,8BAA8B,EAAE,CAAC;YAC3D,OAAO,EAAE,MAAM,EAAE,gCAAgC,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;QACzH,CAAC;QAAC,MAAM,CAAC;YACN,qEAAqE;QACxE,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QAChB,OAAO;YACJ,MAAM,EAAE,oBAAoB;YAC5B,KAAK,EAAE;gBACJ,eAAe,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;gBAC3C,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAAC,eAAe;gBAC7C,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAAC,eAAe;aAC/C;SACH,CAAC;IACL,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAC/C,CAAC;AAED,SAAS,EAAE,CAAC,KAAa;IACtB,OAAO,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;AACrD,CAAC;AAED,yFAAyF;AACzF,SAAgB,oBAAoB,CAAC,MAA4B;IAC9D,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACzB,IAAI,MAAM,CAAC,MAAM,KAAK,gCAAgC,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACxF,OAAO,sCAAsC,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,+BAA+B,CAAC;IACpG,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,oBAAoB,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACjF,MAAM,IAAI,GAAG,KAAK,CAAC,eAAe,CAAC;QACnC,MAAM,KAAK,GAAG,KAAK,CAAC,gBAAgB,IAAI,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,KAAK,CAAC,gBAAgB,IAAI,CAAC,CAAC;QAC1C,OAAO,oBAAoB,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,+CAA+C,CAAC;IAC/H,CAAC;IACD,OAAO,8GAA8G,CAAC;AACzH,CAAC"}

package/lib/browser/channel-logger.d.ts

@@ -0,0 +1,87 @@
+/********************************************************************************
+ * 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, type LogLevel } from '@hydranium/protocol';
+import { type interfaces } 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 declare const ChannelLoggerOptions: unique symbol;
+/**
+ * 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.
+ */
+export declare class ChannelLogger extends AbstractLogger {
+    protected readonly outputChannels: OutputChannelManager;
+    protected readonly options: ChannelLoggerOptions;
+    protected _channel?: OutputChannel;
+    constructor(outputChannels: OutputChannelManager, options: ChannelLoggerOptions, component?: string | undefined);
+    protected get channel(): OutputChannel;
+    protected emit(_level: LogLevel, label: string, message: string, args: readonly unknown[]): void;
+    /**
+     * 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;
+}
+/**
+ * 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 declare const ChannelTracer: unique symbol;
+/** Reads the requesting class's name from an Inversify context, by walking the
+ *  current request up to its parent binding. */
+export declare function getRequestParentName(context: interfaces.Context): string | undefined;
+/**
+ * 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 declare function bindChannelLogger(bind: interfaces.Bind, options: ChannelLoggerOptions): void;
+//# sourceMappingURL=channel-logger.d.ts.map

package/lib/browser/channel-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-logger.d.ts","sourceRoot":"","sources":["../../src/browser/channel-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,cAAc,EAAiB,KAAK,QAAQ,EAAkC,MAAM,qBAAqB,CAAC;AACnH,OAAO,EAAc,KAAK,UAAU,EAAqB,MAAM,8BAA8B,CAAC;AAC9F,OAAO,EAAE,KAAK,aAAa,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAEpG;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;sFACsF;AACtF,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;;;;;;;;;;GAgBG;AACH,qBACa,aAAc,SAAQ,cAAc;IAIb,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,oBAAoB;IACvD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB;IAJjF,SAAS,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;gBAGiB,cAAc,EAAE,oBAAoB,EACpC,OAAO,EAAE,oBAAoB,EACjE,SAAS,GAAE,MAAM,GAAG,SAA6B;IAKjE,SAAS,KAAK,OAAO,IAAI,aAAa,CAErC;IAED,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAOhG;;;;;OAKG;IACH,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAQ3C;AAOD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,eAA0B,CAAC;AAErD;gDACgD;AAChD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,GAAG,MAAM,GAAG,SAAS,CAOpF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAW5F"}

package/lib/browser/channel-logger.js

@@ -0,0 +1,149 @@
+"use strict";
+/********************************************************************************
+ * 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;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChannelTracer = exports.ChannelLogger = exports.ChannelLoggerOptions = void 0;
+exports.getRequestParentName = getRequestParentName;
+exports.bindChannelLogger = bindChannelLogger;
+const protocol_1 = require("@hydranium/protocol");
+const inversify_1 = require("@theia/core/shared/inversify");
+const output_channel_1 = require("@theia/output/lib/browser/output-channel");
+/** Inversify token for the {@link ChannelLoggerOptions} constant (merged with the
+ *  interface name — the standard Theia "type + token under one identifier" idiom). */
+exports.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.
+ */
+let ChannelLogger = class ChannelLogger extends protocol_1.AbstractLogger {
+    outputChannels;
+    options;
+    _channel;
+    constructor(outputChannels, options, component = options.component) {
+        super(component);
+        this.outputChannels = outputChannels;
+        this.options = options;
+    }
+    get channel() {
+        return (this._channel ??= this.outputChannels.getChannel(this.options.channelName));
+    }
+    emit(_level, label, message, args) {
+        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.
+     */
+    derive(component) {
+        const Ctor = this.constructor;
+        return new Ctor(this.outputChannels, this.options, component);
+    }
+};
+exports.ChannelLogger = ChannelLogger;
+exports.ChannelLogger = ChannelLogger = __decorate([
+    (0, inversify_1.injectable)(),
+    __param(0, (0, inversify_1.inject)(output_channel_1.OutputChannelManager)),
+    __param(1, (0, inversify_1.inject)(exports.ChannelLoggerOptions)),
+    __param(2, (0, inversify_1.unmanaged)()),
+    __metadata("design:paramtypes", [output_channel_1.OutputChannelManager, Object, Object])
+], ChannelLogger);
+/** 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}.
+ */
+exports.ChannelTracer = Symbol('ChannelTracer');
+/** Reads the requesting class's name from an Inversify context, by walking the
+ *  current request up to its parent binding. */
+function getRequestParentName(context) {
+    const parent = context.currentRequest.parentRequest;
+    if (!parent || parent.bindings.length === 0) {
+        return undefined;
+    }
+    const binding = parent.bindings[0];
+    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.
+ */
+function bindChannelLogger(bind, options) {
+    bind(exports.ChannelLoggerOptions).toConstantValue(options);
+    bind(ChannelLoggerBase).to(ChannelLogger).inSingletonScope();
+    bind(ChannelLogger).toDynamicValue(ctx => {
+        const base = ctx.container.get(ChannelLoggerBase);
+        const parentName = getRequestParentName(ctx);
+        return parentName ? base.for(parentName) : base;
+    });
+    bind(exports.ChannelTracer)
+        .toDynamicValue(ctx => new protocol_1.DefaultTracer(ctx.container.get(ChannelLoggerBase), new protocol_1.SystemClock(), readBrowserMemory))
+        .inSingletonScope();
+}
+/** Browser heap reader for {@link ChannelTracer}, backed by Chromium's non-standard `performance.memory`. */
+const readBrowserMemory = () => {
+    const mem = performance.memory;
+    return mem ? { usedBytes: mem.usedJSHeapSize, totalBytes: mem.totalJSHeapSize } : undefined;
+};
+function stringifyArg(arg) {
+    if (typeof arg === 'string') {
+        return arg;
+    }
+    try {
+        return JSON.stringify(arg);
+    }
+    catch {
+        return String(arg);
+    }
+}
+//# sourceMappingURL=channel-logger.js.map

package/lib/browser/channel-logger.js.map

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

package/lib/browser/index.d.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
+ ********************************************************************************/
+export * from './channel-logger';
+export * from './log-level-preference';
+export * from './browser-capture';
+export * from './memory-diagnostics-contribution';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mCAAmC,CAAC"}

package/lib/browser/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/********************************************************************************
+ * 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 __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Browser-side cross-head Theia client primitives shared by the protocol heads.
+__exportStar(require("./channel-logger"), exports);
+__exportStar(require("./log-level-preference"), exports);
+__exportStar(require("./browser-capture"), exports);
+__exportStar(require("./memory-diagnostics-contribution"), exports);
+//# sourceMappingURL=index.js.map

package/lib/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,gFAAgF;AAChF,mDAAiC;AACjC,yDAAuC;AACvC,oDAAkC;AAClC,oEAAkD"}

package/lib/browser/log-level-preference.d.ts

@@ -0,0 +1,82 @@
+/********************************************************************************
+ * 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 } from '@hydranium/protocol';
+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 { type interfaces } from '@theia/core/shared/inversify';
+/** Inversify token for the preference id {@link LogLevelPreferenceContribution} watches. */
+export declare const LogLevelPreference: unique symbol;
+/**
+ * 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.
+ */
+export declare class LogLevelPreferenceContribution implements FrontendApplicationContribution {
+    protected readonly preferenceName: string;
+    protected readonly preferences: PreferenceService;
+    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: 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: boolean;
+    /**
+     * 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;
+    /** The awaited body of {@link onStart}, separated so it can be driven directly
+     *  in tests without going through the non-awaited lifecycle hook. */
+    protected applyWhenReady(): Promise<void>;
+    onStop(): void;
+    /**
+     * 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;
+}
+/**
+ * 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 declare function bindLogLevelPreference(bind: interfaces.Bind, preferenceName: string): void;
+//# sourceMappingURL=log-level-preference.d.ts.map

package/lib/browser/log-level-preference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-level-preference.d.ts","sourceRoot":"","sources":["../../src/browser/log-level-preference.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,oBAAoB,EAAyB,MAAM,qBAAqB,CAAC;AAIlF,OAAO,EAAE,+BAA+B,EAAE,MAAM,2DAA2D,CAAC;AAC5G,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAEnF,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBACa,8BAA+B,YAAW,+BAA+B;IACvD,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAG,MAAM,CAAC;IAC5C,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAG,iBAAiB,CAAC;IAC7D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAG,OAAO,CAAC;IAErD;;gEAE4D;IAC5D,SAAS,CAAC,QAAQ,CAAC,SAAS,uBAA8B;IAC1D;;mBAEe;IACf,SAAS,CAAC,UAAU,UAAS;IAE7B;;;;;;;;;;OAUG;IACH,OAAO,IAAI,IAAI;IAIf;yEACqE;cACrD,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB/C,MAAM,IAAI,IAAI;IAId;;;;;;OAMG;IACH,SAAS,CAAC,UAAU,IAAI,IAAI;CAM9B;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAI1F"}