@hydranium/protocol 1.0.0-next.10

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@hydranium/protocol",
+  "version": "1.0.0-next.10",
+  "description": "Generic, language-agnostic types, constants, and pure utilities for the hydranium framework.",
+  "keywords": [
+    "hydranium",
+    "langium",
+    "language-server",
+    "lsp",
+    "rpc",
+    "transfer-model"
+  ],
+  "homepage": "https://github.com/eclipse-emfcloud/hydranium/tree/main/packages/protocol",
+  "bugs": {
+    "url": "https://github.com/eclipse-emfcloud/hydranium/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-emfcloud/hydranium.git",
+    "directory": "packages/protocol"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Hydranium Team"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/client/index.d.ts",
+      "default": "./lib/client/index.js"
+    },
+    "./lib/client": {
+      "types": "./lib/client/index.d.ts",
+      "default": "./lib/client/index.js"
+    },
+    "./data": {
+      "types": "./lib/data/index.d.ts",
+      "default": "./lib/data/index.js"
+    },
+    "./testing": {
+      "types": "./lib/testing/index.d.ts",
+      "default": "./lib/testing/index.js"
+    },
+    "./testing/node": {
+      "types": "./lib/testing/node/index.d.ts",
+      "default": "./lib/testing/node/index.js"
+    },
+    "./lib/data": {
+      "types": "./lib/data/index.d.ts",
+      "default": "./lib/data/index.js"
+    },
+    "./lib/testing": {
+      "types": "./lib/testing/index.d.ts",
+      "default": "./lib/testing/index.js"
+    },
+    "./lib/testing/node": {
+      "types": "./lib/testing/node/index.d.ts",
+      "default": "./lib/testing/node/index.js"
+    }
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "src",
+    "!lib/**/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rimraf lib tsconfig.tsbuildinfo",
+    "lint": "eslint src test --max-warnings 0",
+    "prepack": "node -e \"const m=require('./package.json'),fs=require('node:fs');const missing=[m.main,...Object.values(m.bin||{})].filter(entry=>entry&&!fs.existsSync(entry));if(missing.length){console.error('prepack '+m.name+': not built ('+missing.join(', ')+' missing). Run the build before packing: a files entry that matches nothing is skipped silently, so the tarball would ship src only.');process.exit(1);}\"",
+    "test": "npm run typecheck:test && vitest run",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "watch": "tsc -b -w --preserveWatchOutput"
+  },
+  "dependencies": {
+    "fast-json-patch": "^3.1.1"
+  },
+  "devDependencies": {
+    "fast-check": "^3.23.2",
+    "rimraf": "^5.0.0",
+    "typescript": "^5.8.0",
+    "vscode-jsonrpc": "9.0.1"
+  },
+  "peerDependencies": {
+    "vscode-jsonrpc": "^8.0.0 || ^9.0.0"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error."
+}

package/src/abstract-logger.ts

@@ -0,0 +1,120 @@
+/********************************************************************************
+ * 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, SystemClock } from './clock';
+import { Format, LEVEL_LABELS, type LogLevel, Logger, type LogThreshold } from './logger';
+
+/** Default time source for every {@link AbstractLogger}; overridable per subclass via {@link AbstractLogger.clock}. */
+const systemClock = new 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.
+ */
+export abstract class AbstractLogger implements Logger {
+   constructor(protected component?: string) {}
+
+   /**
+    * 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 {
+      return systemClock;
+   }
+
+   /** Render the current wall-clock instant as `HH:MM:SS.mmm`, sourced from {@link clock}. */
+   protected timestamp(): string {
+      return Format.timestamp(new Date(this.clock().now()));
+   }
+
+   error(message?: string, ...args: unknown[]): this {
+      this.send('error', message, args);
+      return this;
+   }
+   warn(message?: string, ...args: unknown[]): this {
+      this.send('warn', message, args);
+      return this;
+   }
+   info(message?: string, ...args: unknown[]): this {
+      this.send('info', message, args);
+      return this;
+   }
+   debug(message?: string, ...args: unknown[]): this {
+      this.send('debug', message, args);
+      return this;
+   }
+   /** High-volume diagnostic lines, only emitted when the log level is set to 'trace'. */
+   trace(message?: string, ...args: unknown[]): this {
+      this.send('trace', message, args);
+      return this;
+   }
+   /** Info-level threshold rendered with the `Log` label instead of `Info`. */
+   log(message?: string, ...args: unknown[]): this {
+      this.send('info', message, args, 'Log');
+      return this;
+   }
+
+   /** Emit `message` at `threshold`, or do nothing when `threshold === 'off'`. */
+   logAt(threshold: LogThreshold, message: string): this {
+      if (threshold === 'off') {
+         return this;
+      }
+      return this[threshold](message);
+   }
+
+   /** Replace the component prefix with `component`. */
+   for(component: string): this {
+      return this.derive(component);
+   }
+
+   /** Append `component` to the existing prefix as a nested `parent :: child` segment. */
+   sub(component: string): this {
+      return this.derive(this.component ? `${this.component} :: ${component}` : component);
+   }
+
+   /** Append `component` as a separate bracket: `[a] [b]` rather than `[a :: b]`. */
+   with(component: string): this {
+      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: string): this {
+      return this.with(uri);
+   }
+
+   /** Threshold-gated send. Subclasses can override the label by passing one explicitly. */
+   protected send(level: LogLevel, message?: string, args: readonly unknown[] = [], label = LEVEL_LABELS[level]): void {
+      if (!message || !Logger.isLevelEnabled(level)) {
+         return;
+      }
+      this.emit(level, label, message, args);
+   }
+
+   /** 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;
+}

package/src/browser-runtime.ts

@@ -0,0 +1,135 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/*
+ * Browser-origin renderer-capture shapes. They live in `@hydranium/protocol`
+ * (neutral — no DOM, no `node:` deps) so the client-theia live capture
+ * (`captureBrowserRuntime`) and the Playwright CDP bridge produce the SAME
+ * `browser-runtime.json` artefact type. One report with `source`-graded
+ * fidelity, so a reader has one shape and one file to interpret.
+ */
+
+/**
+ * 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[];
+}

package/src/client/data-events.ts

@@ -0,0 +1,71 @@
+/********************************************************************************
+ * 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 class DataEvents<
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TProject extends Project = Project
+> implements DataClientProtocol<TTransfer, TDiagnostic, TProject> {
+   protected readonly documentUpdatedEmitter = new Emitter<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>();
+   protected readonly documentSavedEmitter = new Emitter<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>();
+   protected readonly projectsChangedEmitter = new Emitter<ProjectsChangedEvent<TProject>>();
+
+   /** A build-phase event for a watched document. Carries the originating `sourceClientId`. */
+   readonly onDidUpdateDocument: Event<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>> = this.documentUpdatedEmitter.event;
+   /** A watched document was persisted to disk. */
+   readonly onDidSaveDocument: Event<TransferDocumentSavedEvent<TTransfer, TDiagnostic>> = this.documentSavedEmitter.event;
+   /** The project set changed. */
+   readonly onDidChangeProjects: Event<ProjectsChangedEvent<TProject>> = this.projectsChangedEmitter.event;
+
+   // --- DataClientProtocol (wire names) ---
+
+   onDocumentUpdated(event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>): void {
+      this.documentUpdatedEmitter.fire(event);
+   }
+
+   onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void {
+      this.documentSavedEmitter.fire(event);
+   }
+
+   onProjectsChanged(event: ProjectsChangedEvent<TProject>): void {
+      this.projectsChangedEmitter.fire(event);
+   }
+
+   dispose(): void {
+      this.documentUpdatedEmitter.dispose();
+      this.documentSavedEmitter.dispose();
+      this.projectsChangedEmitter.dispose();
+   }
+}

package/src/client/data-port.ts

@@ -0,0 +1,99 @@
+/********************************************************************************
+ * 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>;
+}