@hydranium/protocol 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,81 @@
+# `@hydranium/protocol`
+
+Generic, language-agnostic types, constants, and pure utilities for the
+[Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework.
+
+This package is the contract surface shared between hydranium servers and
+their clients. It contains:
+
+- Cross-reference and reference-resolution types.
+- The `TransferDocument<TTransfer, TDiagnostic>` transfer-document wrapper.
+- The generic `DataServerProtocol` and `DataClientProtocol` RPC interfaces.
+- Pure utility functions and version constants.
+
+**Dependency budget:** one runtime dependency, `fast-json-patch`. Anything
+heavier (transport, Inversify, Theia, Langium runtime) lives in consuming
+packages.
+
+## Install
+
+```bash
+npm install @hydranium/protocol
+```
+
+This is the only hydranium package a pure client needs. A form editor, a tree
+view or a code generator talking to the data head depends on this and on
+`vscode-jsonrpc` for the transport — never on `@hydranium/core`, which carries
+the Langium runtime and does not bundle for a client.
+
+## The RPC pattern
+
+The data head is not a bespoke wire format — it is a TypeScript interface, bound
+on one side and proxied on the other. An adopter declares a contract `T`, binds
+it with `bindRpcMethods`, and consumes it with `createRpcProxy<T>`; nothing
+between the two is hand-written, and the compiler is what keeps the ends
+agreeing.
+
+```
+   adopter contract T                   adopter contract T
+        │                                     │
+        ▼                                     ▼
+   bindRpcMethods                       createRpcProxy<T>
+   (server side)                         (caller side)
+        │                                     │
+        └──── MessageConnection ──────────────┘
+              (vscode-jsonrpc)
+```
+
+The two helpers are deliberately symmetric — the same wire-name composition
+rule, the same notification heuristic, the same deferred-connection support — so
+a contract written once works on both ends with no per-method configuration.
+Both are exported from the package root; there is no `/rpc` subpath.
+
+Full reference — the options both ends must agree on, the reserved property
+names, a worked example — is in
+[`src/rpc/README.md`](./src/rpc/README.md), which ships in the tarball.
+
+## Subpaths
+
+```bash
+@hydranium/protocol               # transfer documents, references, RPC machinery
+@hydranium/protocol/data          # DataServerProtocol / DataClientProtocol
+@hydranium/protocol/client        # the host-neutral client tier
+@hydranium/protocol/testing       # test doubles and waiters
+@hydranium/protocol/testing/node  # the Node-only doubles
+```
+
+The root barrel re-exports `data` and `client`, so those two subpaths buy a
+narrower surface rather than reach; `testing` is only reachable by its own
+specifier, which is what keeps the doubles out of a production bundle. The RPC
+machinery documents itself in [`src/rpc/README.md`](./src/rpc/README.md).
+
+## Status
+
+Alpha — pre-v0. The package is being populated incrementally, and its API is
+not yet stable. See the [repository README](../../README.md) for the current
+status and known limitations.
+
+## License
+
+`MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
+[`NOTICE.md`](../../NOTICE.md) for third-party notices.

package/lib/abstract-logger.d.ts

@@ -0,0 +1,66 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type Clock } from './clock';
+import { type LogLevel, Logger, type LogThreshold } from './logger';
+/**
+ * Cross-side abstract base for the {@link Logger} family. Centralises:
+ *  - the {@link LogLevel}/{@link LogThreshold} contract and threshold gating;
+ *  - public `error`/`warn`/`info`/`debug`/`trace`/`log` methods;
+ *  - component-prefix derivation ({@link for}, {@link sub}, {@link with}, {@link withUri}).
+ *
+ * Emission only — measuring (timing, memory, profiling) lives on the
+ * `Tracer`, which composes a Logger for its output.
+ * Subclasses provide platform-specific output via {@link emit} and instance
+ * creation via {@link derive}. Format is `[<Label> - HH:MM:SS.mmm]
+ * [<component>] <message>` so client and server lines interleave cleanly under
+ * one Output panel entry.
+ */
+export declare abstract class AbstractLogger implements Logger {
+    protected component?: string | undefined;
+    constructor(component?: string | undefined);
+    /**
+     * Time source for this logger's timing helpers and timestamps. The base
+     * returns the process-wide {@link SystemClock}; subclasses with access to
+     * an injected {@link Clock} override this so logger time goes through the
+     * same fake-clock axis as the rest of the framework's gated logic. Inherited
+     * by derived loggers ({@link derive}), so a subclass override applies to its
+     * children without any extra wiring.
+     */
+    protected clock(): Clock;
+    /** Render the current wall-clock instant as `HH:MM:SS.mmm`, sourced from {@link clock}. */
+    protected timestamp(): string;
+    error(message?: string, ...args: unknown[]): this;
+    warn(message?: string, ...args: unknown[]): this;
+    info(message?: string, ...args: unknown[]): this;
+    debug(message?: string, ...args: unknown[]): this;
+    /** High-volume diagnostic lines, only emitted when the log level is set to 'trace'. */
+    trace(message?: string, ...args: unknown[]): this;
+    /** Info-level threshold rendered with the `Log` label instead of `Info`. */
+    log(message?: string, ...args: unknown[]): this;
+    /** Emit `message` at `threshold`, or do nothing when `threshold === 'off'`. */
+    logAt(threshold: LogThreshold, message: string): this;
+    /** Replace the component prefix with `component`. */
+    for(component: string): this;
+    /** Append `component` to the existing prefix as a nested `parent :: child` segment. */
+    sub(component: string): this;
+    /** Append `component` as a separate bracket: `[a] [b]` rather than `[a :: b]`. */
+    with(component: string): this;
+    /**
+     * Default URI labelling: stringify the URI. Subclasses with workspace
+     * awareness override to render workspace-relative paths.
+     */
+    withUri(uri: string): this;
+    /** Threshold-gated send. Subclasses can override the label by passing one explicitly. */
+    protected send(level: LogLevel, message?: string, args?: readonly unknown[], label?: string): void;
+    /** Subclasses implement platform-specific output (console + file sink, OutputChannel, etc.). */
+    protected abstract emit(level: LogLevel, label: string, message: string, args: readonly unknown[]): void;
+    /** Subclasses construct a new instance preserving their constructor dependencies. */
+    protected abstract derive(component: string): this;
+}
+//# sourceMappingURL=abstract-logger.d.ts.map

package/lib/abstract-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-logger.d.ts","sourceRoot":"","sources":["../src/abstract-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,SAAS,CAAC;AAClD,OAAO,EAAwB,KAAK,QAAQ,EAAE,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAK1F;;;;;;;;;;;;GAYG;AACH,8BAAsB,cAAe,YAAW,MAAM;IACvC,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM;gBAAlB,SAAS,CAAC,EAAE,MAAM,YAAA;IAExC;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,IAAI,KAAK;IAIxB,2FAA2F;IAC3F,SAAS,CAAC,SAAS,IAAI,MAAM;IAI7B,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIjD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIhD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIhD,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIjD,uFAAuF;IACvF,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIjD,4EAA4E;IAC5E,GAAG,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAK/C,+EAA+E;IAC/E,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAOrD,qDAAqD;IACrD,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI5B,uFAAuF;IACvF,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI5B,kFAAkF;IAClF,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI7B;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI1B,yFAAyF;IACzF,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,OAAO,EAAO,EAAE,KAAK,SAAsB,GAAG,IAAI;IAOnH,gGAAgG;IAChG,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAExG,qFAAqF;IACrF,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CACpD"}

package/lib/abstract-logger.js

@@ -0,0 +1,110 @@
+"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.AbstractLogger = void 0;
+const clock_1 = require("./clock");
+const logger_1 = require("./logger");
+/** Default time source for every {@link AbstractLogger}; overridable per subclass via {@link AbstractLogger.clock}. */
+const systemClock = new clock_1.SystemClock();
+/**
+ * Cross-side abstract base for the {@link Logger} family. Centralises:
+ *  - the {@link LogLevel}/{@link LogThreshold} contract and threshold gating;
+ *  - public `error`/`warn`/`info`/`debug`/`trace`/`log` methods;
+ *  - component-prefix derivation ({@link for}, {@link sub}, {@link with}, {@link withUri}).
+ *
+ * Emission only — measuring (timing, memory, profiling) lives on the
+ * `Tracer`, which composes a Logger for its output.
+ * Subclasses provide platform-specific output via {@link emit} and instance
+ * creation via {@link derive}. Format is `[<Label> - HH:MM:SS.mmm]
+ * [<component>] <message>` so client and server lines interleave cleanly under
+ * one Output panel entry.
+ */
+class AbstractLogger {
+    component;
+    constructor(component) {
+        this.component = component;
+    }
+    /**
+     * Time source for this logger's timing helpers and timestamps. The base
+     * returns the process-wide {@link SystemClock}; subclasses with access to
+     * an injected {@link Clock} override this so logger time goes through the
+     * same fake-clock axis as the rest of the framework's gated logic. Inherited
+     * by derived loggers ({@link derive}), so a subclass override applies to its
+     * children without any extra wiring.
+     */
+    clock() {
+        return systemClock;
+    }
+    /** Render the current wall-clock instant as `HH:MM:SS.mmm`, sourced from {@link clock}. */
+    timestamp() {
+        return logger_1.Format.timestamp(new Date(this.clock().now()));
+    }
+    error(message, ...args) {
+        this.send('error', message, args);
+        return this;
+    }
+    warn(message, ...args) {
+        this.send('warn', message, args);
+        return this;
+    }
+    info(message, ...args) {
+        this.send('info', message, args);
+        return this;
+    }
+    debug(message, ...args) {
+        this.send('debug', message, args);
+        return this;
+    }
+    /** High-volume diagnostic lines, only emitted when the log level is set to 'trace'. */
+    trace(message, ...args) {
+        this.send('trace', message, args);
+        return this;
+    }
+    /** Info-level threshold rendered with the `Log` label instead of `Info`. */
+    log(message, ...args) {
+        this.send('info', message, args, 'Log');
+        return this;
+    }
+    /** Emit `message` at `threshold`, or do nothing when `threshold === 'off'`. */
+    logAt(threshold, message) {
+        if (threshold === 'off') {
+            return this;
+        }
+        return this[threshold](message);
+    }
+    /** Replace the component prefix with `component`. */
+    for(component) {
+        return this.derive(component);
+    }
+    /** Append `component` to the existing prefix as a nested `parent :: child` segment. */
+    sub(component) {
+        return this.derive(this.component ? `${this.component} :: ${component}` : component);
+    }
+    /** Append `component` as a separate bracket: `[a] [b]` rather than `[a :: b]`. */
+    with(component) {
+        return this.derive(this.component ? `${this.component}] [${component}` : component);
+    }
+    /**
+     * Default URI labelling: stringify the URI. Subclasses with workspace
+     * awareness override to render workspace-relative paths.
+     */
+    withUri(uri) {
+        return this.with(uri);
+    }
+    /** Threshold-gated send. Subclasses can override the label by passing one explicitly. */
+    send(level, message, args = [], label = logger_1.LEVEL_LABELS[level]) {
+        if (!message || !logger_1.Logger.isLevelEnabled(level)) {
+            return;
+        }
+        this.emit(level, label, message, args);
+    }
+}
+exports.AbstractLogger = AbstractLogger;
+//# sourceMappingURL=abstract-logger.js.map

package/lib/abstract-logger.js.map

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

package/lib/browser-runtime.d.ts

@@ -0,0 +1,124 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * One renderer-runtime reading — JS-heap + precise-renderer-memory + object/render
+ * counters, every field optional (a counter a source cannot produce is omitted).
+ */
+export interface BrowserRuntimeSample {
+    /** JS heap used (CDP `JSHeapUsedSize` / `performance.memory.usedJSHeapSize`). */
+    jsHeapUsedBytes?: number;
+    /** JS heap total (CDP `JSHeapTotalSize` / `performance.memory.totalJSHeapSize`). */
+    jsHeapTotalBytes?: number;
+    /** JS heap limit (`performance.memory.jsHeapSizeLimit`; CDP does not report it). */
+    jsHeapLimitBytes?: number;
+    /** Total renderer memory across JS/DOM/workers (`measureUserAgentSpecificMemory` only). */
+    totalBytes?: number;
+    /** The precise API's per-type/per-container breakdown, passed through verbatim. */
+    breakdown?: unknown;
+    /** DOM node count (CDP `Nodes`) — a rising count is the classic Theia leak tell. */
+    nodes?: number;
+    /** Registered JS event listeners (CDP `JSEventListeners`) — the other leak tell. */
+    jsEventListeners?: number;
+    /** Live `Document` count (CDP `Documents`). */
+    documents?: number;
+    /** Frame count (CDP `Frames`). */
+    frames?: number;
+    /** Cumulative layout operations (CDP `LayoutCount`). */
+    layoutCount?: number;
+    /** Cumulative style recalculations (CDP `RecalcStyleCount`). */
+    recalcStyleCount?: number;
+}
+/**
+ * The `browser-runtime.json` artefact — renderer memory + object/render counters,
+ * graded by `source`. `before`/`after`/`delta` are present for a two-point source
+ * (CDP, before vs after the scenario — the delta is the leak signal); `after`-only
+ * for a single gauge read (the live "Dump Frontend State" command).
+ *
+ *  - `cdp-performance` — full: JS heap + `nodes`/`jsEventListeners`/`documents`/
+ *    `frames`/`layoutCount`/`recalcStyleCount`; two-point.
+ *  - `measureUserAgentSpecificMemory` — precise renderer bytes by type/container
+ *    (`totalBytes`/`breakdown`; cross-origin isolation only); after-only.
+ *  - `performance.memory` — JS-heap gauge only (used/total/limit); after-only.
+ *  - `unavailable` — neither API; `after` is empty.
+ */
+export interface BrowserRuntimeReport {
+    /**
+     * Which API produced the reading, and therefore which sample fields CAN be
+     * populated — a reader must branch on it rather than assume a field is
+     * missing because the value was zero. Not a caller preference: each producer
+     * tries its best source and degrades, so the same code path can emit any of
+     * the four across runs.
+     */
+    source: 'cdp-performance' | 'measureUserAgentSpecificMemory' | 'performance.memory' | 'unavailable';
+    /**
+     * The pre-scenario reading, present only for a two-point capture. Its absence
+     * is what marks a report as a single gauge read, and {@link delta} is then
+     * absent with it.
+     */
+    before?: BrowserRuntimeSample;
+    /**
+     * The post-scenario reading, or the only reading for a single-point capture.
+     * Always present — an `unavailable` source yields an EMPTY object here rather
+     * than omitting the field, so presence proves nothing about content.
+     */
+    after: BrowserRuntimeSample;
+    /**
+     * Per-field `after − before`, computed only for the numeric CDP counters and
+     * only where both samples carry the field, so a counter can appear in
+     * {@link after} and be absent here. Positive means growth over the scenario,
+     * which on `nodes` or `jsEventListeners` is the leak signal the two-point
+     * capture exists for.
+     */
+    delta?: BrowserRuntimeSample;
+}
+/** One main-thread timeline entry — a `longtask` (jank) or a user-timing `measure` span. */
+export interface BrowserTimelineEntry {
+    /**
+     * The runtime's own label — an attribution name for a long task, the app's
+     * mark name for a user-timing span. Not unique: one name recurs once per
+     * occurrence.
+     */
+    name: string;
+    /**
+     * The `PerformanceEntry` type. Only `longtask` and `measure` are observed,
+     * and only where the runtime lists them as supported — but the field is left
+     * open rather than a union, because it carries whatever the entry reported.
+     */
+    entryType: string;
+    /**
+     * Milliseconds from the PAGE's time origin (the `performance.now` domain).
+     * Not wall-clock: it cannot be compared with a server timestamp, with a
+     * `Date.now` reading, or with an entry captured from another page.
+     */
+    startTimeMs: number;
+    /**
+     * Milliseconds the entry spanned — main-thread blocking time for a long
+     * task, which the platform only reports above 50ms, and the mark-to-mark
+     * span for a `measure`.
+     */
+    durationMs: number;
+}
+/** Both browser-origin signals of one capture — the runtime report and the main-thread timeline. */
+export interface BrowserStateReport {
+    /**
+     * The page-side single-point read taken at capture time. A caller holding a
+     * CDP session is expected to supersede it with the richer two-point report
+     * before writing `browser-runtime.json`, so this field is the floor rather
+     * than the final artefact.
+     */
+    runtime: BrowserRuntimeReport;
+    /**
+     * Entries in observer-delivery order, covering the span between starting the
+     * recorder and this capture. Empty carries two meanings this shape cannot
+     * separate — nothing janked, or the recorder was never started and the
+     * runtime supports neither entry type.
+     */
+    timeline: BrowserTimelineEntry[];
+}
+//# sourceMappingURL=browser-runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browser-runtime.d.ts","sourceRoot":"","sources":["../src/browser-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAUlF;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IAClC,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IAClC;;;;;;OAMG;IACH,MAAM,EAAE,iBAAiB,GAAG,gCAAgC,GAAG,oBAAoB,GAAG,aAAa,CAAC;IACpG;;;;OAIG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;;OAIG;IACH,KAAK,EAAE,oBAAoB,CAAC;IAC5B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IAClC;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACrB;AAED,oGAAoG;AACpG,MAAM,WAAW,kBAAkB;IAChC;;;;;OAKG;IACH,OAAO,EAAE,oBAAoB,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CACnC"}

package/lib/browser-runtime.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=browser-runtime.js.map

package/lib/browser-runtime.js.map

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

package/lib/client/data-events.d.ts

@@ -0,0 +1,49 @@
+/********************************************************************************
+ * 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 { Emitter, type Event } from 'vscode-jsonrpc';
+import type { DataClientProtocol, ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from '../data';
+import type { Project } from '../project';
+import type { TransferDiagnostic } from '../transfer-diagnostic';
+import type { TransferElement } from '../transfer-element';
+/**
+ * The inbound half of a data connection, fanned out to local listeners.
+ *
+ * A connection has exactly one `DataClientProtocol` bound to it, so whoever
+ * that is becomes the only thing able to see server pushes. That does not suit
+ * a host with more than one interested party — a properties panel, a tree, a
+ * status contribution — so this sits in the slot instead and re-emits.
+ *
+ * The `on*` methods are the WIRE names, matched against
+ * `DATA_CLIENT_PROTOCOL_METHODS`; the `onDid*` events are the local ones.
+ * Keeping the two sets of names distinct is what makes it obvious which side of
+ * the boundary a given member belongs to.
+ *
+ * **Relationship to `@hydranium/data-client-theia`'s `EmitterDataClient`: two
+ * host flavours of one idea, not a duplicate to be collapsed.** The difference
+ * is the event type: `EmitterDataClient` fans out to a `@theia/core` `Event`,
+ * which is what a Theia frontend's `@injectable()` client wants, while this one
+ * uses vscode-jsonrpc's and is therefore usable from a webview or a plain
+ * browser client too. Pick by host; neither is deprecated.
+ */
+export declare class DataEvents<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TProject extends Project = Project> implements DataClientProtocol<TTransfer, TDiagnostic, TProject> {
+    protected readonly documentUpdatedEmitter: Emitter<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>;
+    protected readonly documentSavedEmitter: Emitter<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>;
+    protected readonly projectsChangedEmitter: Emitter<ProjectsChangedEvent<TProject>>;
+    /** A build-phase event for a watched document. Carries the originating `sourceClientId`. */
+    readonly onDidUpdateDocument: Event<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>;
+    /** A watched document was persisted to disk. */
+    readonly onDidSaveDocument: Event<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>;
+    /** The project set changed. */
+    readonly onDidChangeProjects: Event<ProjectsChangedEvent<TProject>>;
+    onDocumentUpdated(event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>): void;
+    onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void;
+    onProjectsChanged(event: ProjectsChangedEvent<TProject>): void;
+    dispose(): void;
+}
+//# sourceMappingURL=data-events.d.ts.map

package/lib/client/data-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-events.d.ts","sourceRoot":"","sources":["../../src/client/data-events.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAClI,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,UAAU,CACpB,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO,CACnC,YAAW,kBAAkB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC;IAC9D,SAAS,CAAC,QAAQ,CAAC,sBAAsB,gEAAuE;IAChH,SAAS,CAAC,QAAQ,CAAC,oBAAoB,8DAAqE;IAC5G,SAAS,CAAC,QAAQ,CAAC,sBAAsB,0CAAiD;IAE1F,4FAA4F;IAC5F,QAAQ,CAAC,mBAAmB,EAAE,KAAK,CAAC,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAqC;IAC9H,gDAAgD;IAChD,QAAQ,CAAC,iBAAiB,EAAE,KAAK,CAAC,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAmC;IACxH,+BAA+B;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,KAAK,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAqC;IAIxG,iBAAiB,CAAC,KAAK,EAAE,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,IAAI;IAIpF,eAAe,CAAC,KAAK,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,IAAI;IAIhF,iBAAiB,CAAC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GAAG,IAAI;IAI9D,OAAO,IAAI,IAAI;CAKjB"}

package/lib/client/data-events.js

@@ -0,0 +1,60 @@
+"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.DataEvents = void 0;
+const vscode_jsonrpc_1 = require("vscode-jsonrpc");
+/**
+ * The inbound half of a data connection, fanned out to local listeners.
+ *
+ * A connection has exactly one `DataClientProtocol` bound to it, so whoever
+ * that is becomes the only thing able to see server pushes. That does not suit
+ * a host with more than one interested party — a properties panel, a tree, a
+ * status contribution — so this sits in the slot instead and re-emits.
+ *
+ * The `on*` methods are the WIRE names, matched against
+ * `DATA_CLIENT_PROTOCOL_METHODS`; the `onDid*` events are the local ones.
+ * Keeping the two sets of names distinct is what makes it obvious which side of
+ * the boundary a given member belongs to.
+ *
+ * **Relationship to `@hydranium/data-client-theia`'s `EmitterDataClient`: two
+ * host flavours of one idea, not a duplicate to be collapsed.** The difference
+ * is the event type: `EmitterDataClient` fans out to a `@theia/core` `Event`,
+ * which is what a Theia frontend's `@injectable()` client wants, while this one
+ * uses vscode-jsonrpc's and is therefore usable from a webview or a plain
+ * browser client too. Pick by host; neither is deprecated.
+ */
+class DataEvents {
+    documentUpdatedEmitter = new vscode_jsonrpc_1.Emitter();
+    documentSavedEmitter = new vscode_jsonrpc_1.Emitter();
+    projectsChangedEmitter = new vscode_jsonrpc_1.Emitter();
+    /** A build-phase event for a watched document. Carries the originating `sourceClientId`. */
+    onDidUpdateDocument = this.documentUpdatedEmitter.event;
+    /** A watched document was persisted to disk. */
+    onDidSaveDocument = this.documentSavedEmitter.event;
+    /** The project set changed. */
+    onDidChangeProjects = this.projectsChangedEmitter.event;
+    // --- DataClientProtocol (wire names) ---
+    onDocumentUpdated(event) {
+        this.documentUpdatedEmitter.fire(event);
+    }
+    onDocumentSaved(event) {
+        this.documentSavedEmitter.fire(event);
+    }
+    onProjectsChanged(event) {
+        this.projectsChangedEmitter.fire(event);
+    }
+    dispose() {
+        this.documentUpdatedEmitter.dispose();
+        this.documentSavedEmitter.dispose();
+        this.projectsChangedEmitter.dispose();
+    }
+}
+exports.DataEvents = DataEvents;
+//# sourceMappingURL=data-events.js.map

package/lib/client/data-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-events.js","sourceRoot":"","sources":["../../src/client/data-events.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,mDAAqD;AAMrD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,UAAU;IAKD,sBAAsB,GAAG,IAAI,wBAAO,EAAwD,CAAC;IAC7F,oBAAoB,GAAG,IAAI,wBAAO,EAAsD,CAAC;IACzF,sBAAsB,GAAG,IAAI,wBAAO,EAAkC,CAAC;IAE1F,4FAA4F;IACnF,mBAAmB,GAAgE,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC;IAC9H,gDAAgD;IACvC,iBAAiB,GAA8D,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC;IACxH,+BAA+B;IACtB,mBAAmB,GAA0C,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC;IAExG,0CAA0C;IAE1C,iBAAiB,CAAC,KAA2D;QAC1E,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,eAAe,CAAC,KAAyD;QACtE,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,iBAAiB,CAAC,KAAqC;QACpD,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO;QACJ,IAAI,CAAC,sBAAsB,CAAC,OAAO,EAAE,CAAC;QACtC,IAAI,CAAC,oBAAoB,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,CAAC,sBAAsB,CAAC,OAAO,EAAE,CAAC;IACzC,CAAC;CACH;AAnCD,gCAmCC"}

package/lib/client/data-port.d.ts

@@ -0,0 +1,95 @@
+/********************************************************************************
+ * 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 { Event, MessageConnection } from 'vscode-jsonrpc';
+/**
+ * The one thing a host has to supply for the data head: a live JSON-RPC
+ * connection to the data server, plus the identity and failure sink that go
+ * with it.
+ *
+ * "Port" in the hexagonal sense — the host implements it, `DataSession`
+ * consumes it, and nothing on either side of the boundary imports the other.
+ *
+ * **This deliberately does NOT wrap the protocol methods.** `createRpcProxy`
+ * already takes a promise of a connection and produces the whole typed
+ * `DataServerProtocol` surface, so wrapping it would re-derive the framework's
+ * pass-throughs in a second place and lose the `as const satisfies keyof`
+ * method allowlists, which cannot drift. Everything a form or a tree actually
+ * does — the wire contract, the open/watch/update/close sequence, `baseVersion`
+ * conflict handling, echo filtering by `sourceClientId` — is host-invariant and
+ * lives above this interface. What varies between hosts is exactly the four
+ * members below.
+ *
+ * **Why the transport hop and not merely the protocol.** In a Theia frontend
+ * the client *is* the RPC endpoint and holds a `MessageConnection` directly. In
+ * a VS Code webview the client is a browser sandbox with no `net`, no reach into
+ * the extension host's connection, and only structured-clone `postMessage`. So
+ * the port abstracts *establishing* the connection, which lets a webview
+ * implementation ride the extension↔webview hop (see
+ * `createPostMessageTransport`) while a Theia one opens a channel — and
+ * lets both hand back the same `MessageConnection` the RPC machinery expects.
+ *
+ * Two constraints on an implementation:
+ *
+ * - **A webview implementation must import `vscode-jsonrpc/browser`**, not the
+ *   package root. vscode-jsonrpc 9's root ships no runtime abstraction layer
+ *   and throws `No runtime abstraction layer installed` on the first message.
+ * - **Return a connection that is already `listen()`ing.** The proxy queues
+ *   calls on the promise but never calls `listen` itself.
+ */
+export interface DataPort {
+    /**
+     * Stable identity of this client on the data server, passed as `clientId`
+     * on every document request.
+     *
+     * It has to be stable for the session because it is the echo key: an
+     * inbound `onDocumentUpdated` carries the originating mutation's
+     * `clientId` as `sourceClientId`, and a client that cannot recognise its
+     * own echo treats its own write as a concurrent third-party one. It also
+     * has to be distinct per client, since it keys the server's per-
+     * `(uri, clientId)` watch bucket.
+     *
+     * Avoid the three values the framework itself uses as sentinels —
+     * `'language-client'`, `'unknown'` and `'revert-on-close'`.
+     */
+    readonly clientId: string;
+    /**
+     * Open the transport and hand back a listening `MessageConnection`.
+     *
+     * Called at most once per connection generation. A rejection is a
+     * transport-construction failure and is reported through
+     * {@link reportError} by the consumer; it must leave the port reusable, so
+     * that a later generation can retry.
+     */
+    connect(): Promise<MessageConnection>;
+    /**
+     * Surface a failure to the user in whatever way the host does that — a
+     * notification, an output channel, a status entry.
+     *
+     * It exists because the alternative is worse in both directions: this tier
+     * cannot import a host's UI, and swallowing the error makes a dead
+     * connection look like an empty model. `context` names what was being
+     * attempted, not where in the code it happened.
+     */
+    reportError(error: unknown, context: string): void;
+    /**
+     * Fires when the host tears the transport down and the current connection
+     * is no longer usable — a language-server restart being the case that
+     * forces this to exist, since a restarted server binds new ephemeral ports
+     * and nothing re-discovers them.
+     *
+     * `DataSession` drops its connection generation on this event and
+     * builds a fresh one on the next request.
+     *
+     * A local `Event`, deliberately: nothing here crosses a structured-clone
+     * boundary, so the `Disposable` an `Event` hands back is safe even though a
+     * `Disposable` on the *wire* would not be.
+     */
+    readonly onDispose: Event<void>;
+}
+//# sourceMappingURL=data-port.d.ts.map