@hydranium/client-theia 1.0.0-next.10

package/lib/browser/log-level-preference.js

@@ -0,0 +1,146 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogLevelPreferenceContribution = exports.LogLevelPreference = void 0;
+exports.bindLogLevelPreference = bindLogLevelPreference;
+const protocol_1 = require("@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.
+const frontend_application_contribution_1 = require("@theia/core/lib/browser/frontend-application-contribution");
+const logger_1 = require("@theia/core/lib/common/logger");
+const preference_service_1 = require("@theia/core/lib/common/preferences/preference-service");
+const inversify_1 = require("@theia/core/shared/inversify");
+/** Inversify token for the preference id {@link LogLevelPreferenceContribution} watches. */
+exports.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.
+ */
+let LogLevelPreferenceContribution = class LogLevelPreferenceContribution {
+    preferenceName;
+    preferences;
+    logger;
+    /** 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. */
+    toDispose = new protocol_1.DisposableCollection();
+    /** Guards against a second subscription if `onStart` is ever invoked twice —
+     *  a duplicated listener is exactly the failure this contribution exists to
+     *  prevent. */
+    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 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. */
+    async applyWhenReady() {
+        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() {
+        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.
+     */
+    applyLevel() {
+        const level = (0, protocol_1.parseLogLevel)(this.preferences.get(this.preferenceName));
+        if (level) {
+            protocol_1.Logger.setLevel(level);
+        }
+    }
+};
+exports.LogLevelPreferenceContribution = LogLevelPreferenceContribution;
+__decorate([
+    (0, inversify_1.inject)(exports.LogLevelPreference),
+    __metadata("design:type", String)
+], LogLevelPreferenceContribution.prototype, "preferenceName", void 0);
+__decorate([
+    (0, inversify_1.inject)(preference_service_1.PreferenceService),
+    __metadata("design:type", Object)
+], LogLevelPreferenceContribution.prototype, "preferences", void 0);
+__decorate([
+    (0, inversify_1.inject)(logger_1.ILogger),
+    __metadata("design:type", Object)
+], LogLevelPreferenceContribution.prototype, "logger", void 0);
+exports.LogLevelPreferenceContribution = LogLevelPreferenceContribution = __decorate([
+    (0, inversify_1.injectable)()
+], LogLevelPreferenceContribution);
+/**
+ * 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.
+ */
+function bindLogLevelPreference(bind, preferenceName) {
+    bind(exports.LogLevelPreference).toConstantValue(preferenceName);
+    bind(LogLevelPreferenceContribution).toSelf().inSingletonScope();
+    bind(frontend_application_contribution_1.FrontendApplicationContribution).toService(LogLevelPreferenceContribution);
+}
+//# sourceMappingURL=log-level-preference.js.map

package/lib/browser/log-level-preference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-level-preference.js","sourceRoot":"","sources":["../../src/browser/log-level-preference.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;AAmHlF,wDAIC;AArHD,kDAAkF;AAClF,gFAAgF;AAChF,gFAAgF;AAChF,6EAA6E;AAC7E,iHAA4G;AAC5G,0DAAwD;AACxD,8FAA0F;AAC1F,4DAAmF;AAEnF,4FAA4F;AAC/E,QAAA,kBAAkB,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;GAoBG;AAEI,IAAM,8BAA8B,GAApC,MAAM,8BAA8B;IACO,cAAc,CAAU;IACzB,WAAW,CAAqB;IAC1C,MAAM,CAAW;IAErD;;gEAE4D;IACzC,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC1D;;mBAEe;IACL,UAAU,GAAG,KAAK,CAAC;IAE7B;;;;;;;;;;OAUG;IACH,OAAO;QACJ,KAAK,IAAI,CAAC,cAAc,EAAE,CAAC;IAC9B,CAAC;IAED;yEACqE;IAC3D,KAAK,CAAC,cAAc;QAC3B,IAAI,CAAC;YACF,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;YAC7B,IAAI,CAAC,UAAU,EAAE,CAAC;YAClB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACnB,OAAO;YACV,CAAC;YACD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,IAAI,CAAC,SAAS,CAAC,IAAI,CAChB,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE;gBAC1C,IAAI,KAAK,CAAC,cAAc,KAAK,IAAI,CAAC,cAAc,EAAE,CAAC;oBAChD,IAAI,CAAC,UAAU,EAAE,CAAC;gBACrB,CAAC;YACJ,CAAC,CAAC,CACJ,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACZ,uEAAuE;YACvE,wEAAwE;YACxE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,2CAA2C,IAAI,CAAC,cAAc,GAAG,EAAE,GAAG,CAAC,CAAC;QAC7F,CAAC;IACJ,CAAC;IAED,MAAM;QACH,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;OAMG;IACO,UAAU;QACjB,MAAM,KAAK,GAAG,IAAA,wBAAa,EAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAS,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;QAC/E,IAAI,KAAK,EAAE,CAAC;YACT,iBAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;IACJ,CAAC;CACH,CAAA;AAtEY,wEAA8B;AACO;IAA9C,IAAA,kBAAM,EAAC,0BAAkB,CAAC;;sEAA4C;AACzB;IAA7C,IAAA,kBAAM,EAAC,sCAAiB,CAAC;;mEAAoD;AAC1C;IAAnC,IAAA,kBAAM,EAAC,gBAAO,CAAC;;8DAAqC;yCAH3C,8BAA8B;IAD1C,IAAA,sBAAU,GAAE;GACA,8BAA8B,CAsE1C;AAED;;;;;;GAMG;AACH,SAAgB,sBAAsB,CAAC,IAAqB,EAAE,cAAsB;IACjF,IAAI,CAAC,0BAAkB,CAAC,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;IACzD,IAAI,CAAC,8BAA8B,CAAC,CAAC,MAAM,EAAE,CAAC,gBAAgB,EAAE,CAAC;IACjE,IAAI,CAAC,mEAA+B,CAAC,CAAC,SAAS,CAAC,8BAA8B,CAAC,CAAC;AACnF,CAAC"}

package/lib/browser/memory-diagnostics-contribution.d.ts

@@ -0,0 +1,105 @@
+/********************************************************************************
+ * 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 DataServerDiagnosticsProtocol, type HostDiagnosticsProtocol, type StartProfilingArgs } from '@hydranium/protocol';
+import { CommandContribution, MessageService, type Command, type CommandRegistry } from '@theia/core';
+import { 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 declare const MemoryDiagnosticsOptions: unique symbol;
+/**
+ * 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 declare const MemoryDiagnosticsService: unique symbol;
+/**
+ * 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 declare const HostMemoryDiagnosticsService: unique symbol;
+/**
+ * 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}.
+ */
+export declare class MemoryDiagnosticsContribution implements CommandContribution {
+    protected readonly diagnostics: MemoryDiagnosticsService;
+    protected readonly options: MemoryDiagnosticsOptions;
+    protected readonly messageService: MessageService;
+    protected readonly channels: OutputChannelManager;
+    protected readonly hostDiagnostics?: HostMemoryDiagnosticsService;
+    /** Dimensions the profiling commands capture — the server samples only what is named. */
+    protected readonly profileDimensions: StartProfilingArgs;
+    /** Window length for the "Record Performance Profile" command. */
+    protected readonly recordDurationMs = 10000;
+    /**
+     * 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;
+    registerCommands(registry: CommandRegistry): void;
+    protected command(id: string, label: string, category: string): Command;
+    /** Run a snapshot call, append the full result to the channel, toast the first matching summary line. */
+    protected report(what: string, produce: () => Promise<string>, summaryKeys: string[]): Promise<void>;
+    protected writeSnapshot(target: string, produce: (label: string) => Promise<string>): Promise<void>;
+    /** Begin an open-ended capture; the toast's stop action ends it and reports. */
+    protected startProfiling(): Promise<void>;
+    /** End the capture and report it. Shared, so the toast action and the command cannot diverge in behaviour. */
+    protected stopProfiling(): Promise<void>;
+    /** Capture a fixed-length window: start, wait, stop, and report the result. */
+    protected recordProfile(): Promise<void>;
+    /** Isolated so tests can drive the record window without a real timer. */
+    protected delay(ms: number): Promise<void>;
+    protected dumpFrontendState(): Promise<void>;
+    protected channel(): OutputChannel;
+    /** 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;
+    protected errorMessage(error: unknown): string;
+}
+/**
+ * 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 declare function bindMemoryDiagnostics(bind: interfaces.Bind, options: MemoryDiagnosticsOptions): void;
+//# sourceMappingURL=memory-diagnostics-contribution.d.ts.map

package/lib/browser/memory-diagnostics-contribution.d.ts.map

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

package/lib/browser/memory-diagnostics-contribution.js

@@ -0,0 +1,229 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryDiagnosticsContribution = exports.HostMemoryDiagnosticsService = exports.MemoryDiagnosticsService = exports.MemoryDiagnosticsOptions = void 0;
+exports.bindMemoryDiagnostics = bindMemoryDiagnostics;
+const protocol_1 = require("@hydranium/protocol");
+const browser_capture_1 = require("./browser-capture");
+const core_1 = require("@theia/core");
+const inversify_1 = require("@theia/core/shared/inversify");
+const output_channel_1 = require("@theia/output/lib/browser/output-channel");
+exports.MemoryDiagnosticsOptions = Symbol('MemoryDiagnosticsOptions');
+exports.MemoryDiagnosticsService = Symbol('MemoryDiagnosticsService');
+exports.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}.
+ */
+let MemoryDiagnosticsContribution = class MemoryDiagnosticsContribution {
+    diagnostics;
+    options;
+    messageService;
+    channels;
+    hostDiagnostics;
+    /** Dimensions the profiling commands capture — the server samples only what is named. */
+    profileDimensions = { cpu: true, allocation: true, gc: true, eventLoopDelay: true };
+    /** Window length for the "Record Performance Profile" command. */
+    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.
+     */
+    stopProfilingLabel = 'Stop Profiling (Server)';
+    registerCommands(registry) {
+        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 () => (0, protocol_1.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 }))
+            });
+        }
+    }
+    command(id, label, category) {
+        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. */
+    async report(what, produce, summaryKeys) {
+        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)}`);
+        }
+    }
+    async writeSnapshot(target, produce) {
+        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. */
+    async startProfiling() {
+        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. */
+    stopProfiling() {
+        return this.report('profile', () => this.diagnostics.stopProfiling({ label: new Date().toISOString() }), ['duration']);
+    }
+    /** Capture a fixed-length window: start, wait, stop, and report the result. */
+    async recordProfile() {
+        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. */
+    delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    async dumpFrontendState() {
+        const text = (0, browser_capture_1.formatBrowserRuntime)(await (0, browser_capture_1.captureBrowserRuntime)());
+        this.channel().appendLine(text);
+        this.messageService.info(text, { timeout: 6000 });
+    }
+    channel() {
+        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. */
+    summarize(snapshot, what, keys) {
+        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)`;
+    }
+    errorMessage(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+};
+exports.MemoryDiagnosticsContribution = MemoryDiagnosticsContribution;
+__decorate([
+    (0, inversify_1.inject)(exports.MemoryDiagnosticsService),
+    __metadata("design:type", Object)
+], MemoryDiagnosticsContribution.prototype, "diagnostics", void 0);
+__decorate([
+    (0, inversify_1.inject)(exports.MemoryDiagnosticsOptions),
+    __metadata("design:type", Object)
+], MemoryDiagnosticsContribution.prototype, "options", void 0);
+__decorate([
+    (0, inversify_1.inject)(core_1.MessageService),
+    __metadata("design:type", core_1.MessageService)
+], MemoryDiagnosticsContribution.prototype, "messageService", void 0);
+__decorate([
+    (0, inversify_1.inject)(output_channel_1.OutputChannelManager),
+    __metadata("design:type", output_channel_1.OutputChannelManager)
+], MemoryDiagnosticsContribution.prototype, "channels", void 0);
+__decorate([
+    (0, inversify_1.inject)(exports.HostMemoryDiagnosticsService),
+    (0, inversify_1.optional)(),
+    __metadata("design:type", Object)
+], MemoryDiagnosticsContribution.prototype, "hostDiagnostics", void 0);
+exports.MemoryDiagnosticsContribution = MemoryDiagnosticsContribution = __decorate([
+    (0, inversify_1.injectable)()
+], MemoryDiagnosticsContribution);
+/**
+ * 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`.
+ */
+function bindMemoryDiagnostics(bind, options) {
+    bind(exports.MemoryDiagnosticsOptions).toConstantValue(options);
+    bind(MemoryDiagnosticsContribution).toSelf().inSingletonScope();
+    bind(core_1.CommandContribution).toService(MemoryDiagnosticsContribution);
+}
+//# sourceMappingURL=memory-diagnostics-contribution.js.map

package/lib/browser/memory-diagnostics-contribution.js.map

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

package/lib/index.d.ts

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

package/lib/index.d.ts.map

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

package/lib/index.js

@@ -0,0 +1,11 @@
+"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 });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/lib/node/abstract-socket-forwarding-connection-handler.d.ts

@@ -0,0 +1,96 @@
+/********************************************************************************
+ * 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 Channel, CommandService, type ConnectionHandler, type Disposable, ILogger, type MessageProvider, MessageService } from '@theia/core';
+import * as net from 'node:net';
+/** Resolved configuration for a {@link AbstractSocketForwardingConnectionHandler}.
+ *  A head-specific subclass derives these from its own (adopter-facing) options
+ *  and passes them to `super(...)`. */
+export interface SocketForwardingConnectionHandlerOptions {
+    /** Theia service path the browser frontend opens a channel to. */
+    readonly path: string;
+    /** Command id whose return value is the target server's listening port (the
+     *  server publishes it on the LSP connection at startup). */
+    readonly portCommand: string;
+    /** Short bracket prefix for this head's diagnostic logs, rendered as
+     *  `[<logComponent>] …`. */
+    readonly logComponent: string;
+    /** Human-readable name of the server this head connects to — used in log and
+     *  error messages. */
+    readonly serverName: string;
+    readonly findPortTimeout?: number;
+    readonly findPortAttempts?: number;
+    readonly connectTimeoutMs?: number;
+    /**
+     * Optional diagnostic hook called immediately after the outbound
+     * `net.Socket` to the server is created, BEFORE `socket.connect()` is
+     * invoked. Adopters attach `'data'` / `'close'` listeners here for
+     * byte-level observability when debugging wire-level issues; attaching
+     * before `connect()` guarantees the very first bytes are observed.
+     */
+    readonly onSocketCreated?: (socket: net.Socket) => void;
+}
+/**
+ * Cross-head base for the Theia backend half of a protocol head's transport:
+ * it bridges a Theia browser-frontend {@link Channel} to a server's TCP socket
+ * by relaying bytes between the two.
+ *
+ * Theia delivers each frontend connection to a registered `ConnectionHandler`
+ * keyed by its `path`. The handler asks the language server (via a registered
+ * command) for the target server's listening port, opens a `net.Socket` to that
+ * port, and forwards the Theia channel onto the socket. The frontend terminates
+ * the same wire protocol the server speaks, so the backend performs no semantic
+ * re-proxy — it relays bytes only and stays oblivious to the server's method set.
+ *
+ * The single per-head variation — *which* byte forwarder bridges the channel and
+ * the socket — is the abstract {@link forwardToSocketConnection} hook: the GLSP
+ * head plugs in `@eclipse-glsp/theia-integration`'s `SocketConnectionForwarder`,
+ * the data-server head its own `SocketChannelForwarder`. Keeping the forwarder
+ * behind the hook is what lets the data head stay GLSP-free while sharing the
+ * port-discovery + buffer-and-replay race fix + connect orchestration here.
+ */
+export declare abstract class AbstractSocketForwardingConnectionHandler implements ConnectionHandler {
+    protected messageService: MessageService;
+    protected commandService: CommandService;
+    protected readonly logger: ILogger;
+    readonly path: string;
+    protected readonly portCommand: string;
+    protected readonly logComponent: string;
+    protected readonly serverName: string;
+    protected readonly findPortTimeout: number;
+    protected readonly findPortAttempts: number;
+    protected readonly connectTimeoutMs: number;
+    protected readonly onSocketCreated?: (socket: net.Socket) => void;
+    constructor(options: SocketForwardingConnectionHandlerOptions);
+    onConnection(connection: Channel): void;
+    protected initializeServerConnection(channel: Channel): Promise<void>;
+    protected findPort(): Promise<number>;
+    protected connectToServer(channel: Channel, port: number, preForwardBuffer?: {
+        bufferSub: Disposable;
+        buffered: MessageProvider[];
+    }): Promise<void>;
+    /**
+     * Bridge the Theia frontend `clientChannel` and the server `socket` so bytes
+     * relay both ways. Called once, after the socket is created and the
+     * pre-forward buffer is about to be replayed.
+     */
+    protected abstract forwardToSocketConnection(clientChannel: Channel, socket: net.Socket): Disposable;
+    /**
+     * Re-fire pre-forward buffered `MessageProvider`s on the channel's internal
+     * `onMessageEmitter` so the now-subscribed forwarder picks them up in arrival
+     * order. `MessageProvider` is a thunk (`() => ReadBuffer`) — buffering does
+     * not consume the read position, so replay produces the same bytes the
+     * forwarder would have seen if wired earlier.
+     *
+     * `AbstractChannel.onMessageEmitter` is `protected` in `@theia/core` but
+     * reachable at runtime; the cast is the workaround. A future Theia rename
+     * surfaces as a clear warning here.
+     */
+    protected replayBufferedMessages(channel: Channel, buffered: MessageProvider[]): void;
+}
+//# sourceMappingURL=abstract-socket-forwarding-connection-handler.d.ts.map

package/lib/node/abstract-socket-forwarding-connection-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-socket-forwarding-connection-handler.d.ts","sourceRoot":"","sources":["../../src/node/abstract-socket-forwarding-connection-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,KAAK,OAAO,EACZ,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,OAAO,EACP,KAAK,eAAe,EACpB,cAAc,EAChB,MAAM,aAAa,CAAC;AAIrB,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC;;uCAEuC;AACvC,MAAM,WAAW,wCAAwC;IACtD,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;iEAC6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;gCAC4B;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;0BACsB;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,8BACsB,yCAA0C,YAAW,iBAAiB;IACjE,SAAS,CAAC,cAAc,EAAG,cAAc,CAAC;IAC1C,SAAS,CAAC,cAAc,EAAG,cAAc,CAAC;IAIjD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAG,OAAO,CAAC;IAErD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IACvC,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IACxC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IACtC,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAC3C,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAC5C,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAC5C,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC;gBAEtD,OAAO,EAAE,wCAAwC;IAW7D,YAAY,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI;cAIvB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;cAyB3D,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;cAwB3B,eAAe,CAC5B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,gBAAgB,CAAC,EAAE;QAAE,SAAS,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,eAAe,EAAE,CAAA;KAAE,GACzE,OAAO,CAAC,IAAI,CAAC;IAyBhB;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,yBAAyB,CAAC,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,GAAG,UAAU;IAEpG;;;;;;;;;;OAUG;IACH,SAAS,CAAC,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,GAAG,IAAI;CAiBvF"}