@hydranium/protocol 1.0.0-next.10

package/lib/client/message-relay.js

@@ -0,0 +1,139 @@
+"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.relayToPostMessageChannel = relayToPostMessageChannel;
+const vscode_jsonrpc_1 = require("vscode-jsonrpc");
+/**
+ * Pump JSON-RPC messages between a framed transport and a structured-clone
+ * {@link PostMessageChannel}, decoding neither.
+ *
+ * This is the extension-host half of the hop whose webview half is
+ * `createPostMessageTransport`. A webview has no `net`, so the data-server
+ * socket can only be held by the extension host; the host therefore has to move
+ * whole messages between a Content-Length-framed socket and a pipe that carries
+ * objects. Both sides speak the same JSON-RPC, so this moves messages and adds
+ * no semantics — there is no re-proxy in between, and `createRpcProxy` on the far
+ * side is unaware the relay exists.
+ *
+ * **No `MessageConnection` is built here, and that is what keeps the module
+ * browser-neutral.** A relay is not a JSON-RPC endpoint: it has no requests of
+ * its own, so it needs no message queue, hence no vscode-jsonrpc runtime
+ * abstraction layer. `reader.listen` / `writer.write` are enough. The caller
+ * imports the entrypoint that frames its own transport (`vscode-jsonrpc/node`
+ * for a socket) and the RAL that comes with it; this tier stays neutral and is
+ * gated so by `npm run check:neutral`. Contrast
+ * `@hydranium/data-client-theia`'s `SocketChannelForwarder`, which does build a
+ * connection only to borrow its `onClose`, and pays a Theia dependency for the
+ * byte coding this shape does not need.
+ *
+ * **The race this exists to close.** `openTransport` is asynchronous — a real
+ * host discovers a port first, then connects — while the clone pipe is usable
+ * immediately. `PostMessageChannel.onMessage` is a plain emitter with no replay,
+ * so a message sent during the connect window is dropped outright.
+ *
+ * It is not enough that a disciplined client awaits its own connection before
+ * sending: a host builds the far-side connection and hands it back *without*
+ * waiting for the relay, so `DataSession`'s very first call — the readiness
+ * handshake — is already in flight while the socket is still opening. Dropping
+ * that first request presents as a client hanging forever on connect against a
+ * perfectly healthy server.
+ *
+ * So the subscription is taken **synchronously, before the first await**, and
+ * buffers; the hand-off then swaps listeners and replays within one turn of the
+ * event loop, which is what makes it impossible for a message to be both
+ * buffered and forwarded, or to arrive between the two. Replay is FIFO because
+ * order is load-bearing — a `getModelDocument` that overtook its own
+ * `openModelDocument` would answer against an unopened document.
+ * `@hydranium/client-theia`'s `AbstractSocketForwardingConnectionHandler` carries the
+ * same fix for the Theia channel transport.
+ */
+function relayToPostMessageChannel(channel, openTransport, options = {}) {
+    const closeEmitter = new vscode_jsonrpc_1.Emitter();
+    const subscriptions = [];
+    let transport;
+    let disposed = false;
+    // Taken before the first await, so nothing the far side sends during the
+    // connect window is lost. See the race note above.
+    const buffered = [];
+    let bufferSubscription = channel.onMessage(message => buffered.push(message));
+    const closeFramedSide = () => {
+        if (disposed) {
+            return;
+        }
+        closeEmitter.fire();
+    };
+    const wired = (async () => {
+        let opened;
+        try {
+            opened = await openTransport();
+        }
+        catch (error) {
+            bufferSubscription?.dispose();
+            bufferSubscription = undefined;
+            buffered.length = 0;
+            options.reportError?.(error, 'opening the transport to relay');
+            closeFramedSide();
+            return false;
+        }
+        if (disposed) {
+            // Disposed while connecting: the transport is ours now, so it is ours
+            // to release, or the socket outlives the relay that owns it.
+            opened.dispose?.();
+            return false;
+        }
+        transport = opened;
+        // Synchronous hand-off: drop the buffering listener, wire both
+        // directions, then replay. No await in between, so the event loop cannot
+        // interleave a message into the gap.
+        bufferSubscription?.dispose();
+        bufferSubscription = undefined;
+        subscriptions.push(opened.reader.listen(message => channel.post(message)), opened.reader.onClose(() => closeFramedSide()), opened.reader.onError(error => {
+            options.reportError?.(error, 'reading from the relayed transport');
+            closeFramedSide();
+        }), channel.onMessage(message => {
+            void opened.writer.write(message).catch((error) => {
+                options.reportError?.(error, 'writing to the relayed transport');
+            });
+        }));
+        const onChannelClose = channel.onClose?.(() => dispose());
+        if (onChannelClose) {
+            subscriptions.push(onChannelClose);
+        }
+        for (const message of buffered) {
+            void opened.writer.write(message).catch((error) => {
+                options.reportError?.(error, 'replaying a buffered message to the relayed transport');
+            });
+        }
+        buffered.length = 0;
+        return true;
+    })();
+    function dispose() {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        bufferSubscription?.dispose();
+        bufferSubscription = undefined;
+        buffered.length = 0;
+        for (const subscription of subscriptions) {
+            subscription.dispose();
+        }
+        subscriptions.length = 0;
+        transport?.dispose?.();
+        transport = undefined;
+        closeEmitter.dispose();
+    }
+    return {
+        wired,
+        onClose: closeEmitter.event,
+        dispose
+    };
+}
+//# sourceMappingURL=message-relay.js.map

package/lib/client/message-relay.js.map

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

package/lib/client/post-message-transport.d.ts

@@ -0,0 +1,77 @@
+/********************************************************************************
+ * 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 Disposable, type Message, type MessageReader, type MessageWriter } from 'vscode-jsonrpc';
+/**
+ * A `postMessage`-shaped pipe: fire-and-forget, structured-clone-only, no
+ * framing and no bytes.
+ *
+ * This is the shape every extension↔webview hop reduces to, and the reason the
+ * data head needs a port at all. A webview has no `net`, no reach into the
+ * extension host's connection, and nothing but structured clone — so a
+ * transport built on it can carry plain data and nothing else.
+ *
+ * Deliberately minimal, and deliberately not typed against any host's messaging
+ * library — a host adapter satisfies it in a few lines over whatever messenger
+ * it already has, so a diagram and a form can share one hop, one lifecycle and
+ * one dispose rather than opening a second channel for the form.
+ */
+export interface PostMessageChannel {
+    /**
+     * Hand one JSON-RPC message to the other side. Fire-and-forget: delivery
+     * failures surface through {@link onClose}, never as a rejection, because
+     * `postMessage` has no completion to report.
+     */
+    post(message: Message): void;
+    /** Register for messages arriving from the other side. */
+    onMessage(listener: (message: Message) => void): Disposable;
+    /**
+     * Register for the pipe going away — the webview being disposed, the
+     * extension deactivating. Optional: a channel with no observable end simply
+     * never fires close, and the reader/writer then rely on their owner's
+     * dispose instead.
+     */
+    onClose?(listener: () => void): Disposable;
+}
+/**
+ * A reader/writer pair over a {@link PostMessageChannel}, ready to be handed to
+ * `createMessageConnection`.
+ *
+ * The connection is NOT built here, and that omission is the point:
+ * `createMessageConnection`'s message queue needs a vscode-jsonrpc runtime
+ * abstraction layer, and only the `/node` and `/browser` entrypoints install
+ * one. vscode-jsonrpc 9's package ROOT resolves to the RAL-less common API and
+ * throws `No runtime abstraction layer installed` on the first message. Only
+ * the host knows which side it is on, so the host imports the matching entry
+ * (`/browser` in a webview, `/node` in an extension host) and builds the
+ * connection there.
+ *
+ * Keeping the factory out of this module is also what lets the module stay
+ * browser-neutral: it touches only `AbstractMessageReader` /
+ * `AbstractMessageWriter` / `Emitter`, none of which need a RAL.
+ */
+export interface PostMessageTransport {
+    readonly reader: MessageReader;
+    readonly writer: MessageWriter;
+    /** Release the channel subscriptions. */
+    dispose(): void;
+}
+/**
+ * Build the reader/writer pair for `channel`.
+ *
+ * What this buys, and why `DataPort` is shaped the way it is:
+ * `createRpcProxy` runs **unchanged** over the result. The typed surface, the
+ * `DATA_*_PROTOCOL_METHODS` allowlists and the whole open → watch → update →
+ * close sequence are identical in a webview and in a Node extension host,
+ * because only the `MessageConnection` the port hands back differs. Terminating
+ * JSON-RPC in the extension host and declaring one request type per data-head
+ * method is the wrong trade: it hand-maintains a per-method mapping and
+ * discards the `as const satisfies keyof` allowlists, which cannot drift.
+ */
+export declare function createPostMessageTransport(channel: PostMessageChannel): PostMessageTransport;
+//# sourceMappingURL=post-message-transport.d.ts.map

package/lib/client/post-message-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-message-transport.d.ts","sourceRoot":"","sources":["../../src/client/post-message-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAKJ,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,aAAa,EACpB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB;IAChC;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAE7B,0DAA0D;IAC1D,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,UAAU,CAAC;IAE5D;;;;;OAKG;IACH,OAAO,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,UAAU,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB;IAClC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,yCAAyC;IACzC,OAAO,IAAI,IAAI,CAAC;CAClB;AAmED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,kBAAkB,GAAG,oBAAoB,CAW5F"}

package/lib/client/post-message-transport.js

@@ -0,0 +1,95 @@
+"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.createPostMessageTransport = createPostMessageTransport;
+const vscode_jsonrpc_1 = require("vscode-jsonrpc");
+/**
+ * A `MessageReader` over a {@link PostMessageChannel}.
+ *
+ * Structured clone moves objects, so there is nothing to frame and nothing to
+ * decode — the message arrives as the message.
+ */
+class PostMessageReader extends vscode_jsonrpc_1.AbstractMessageReader {
+    messageEmitter = new vscode_jsonrpc_1.Emitter();
+    subscriptions = [];
+    constructor(channel) {
+        super();
+        this.subscriptions.push(channel.onMessage(message => this.messageEmitter.fire(message)));
+        const onClose = channel.onClose?.(() => this.fireClose());
+        if (onClose) {
+            this.subscriptions.push(onClose);
+        }
+    }
+    listen(callback) {
+        return this.messageEmitter.event(callback);
+    }
+    dispose() {
+        super.dispose();
+        for (const subscription of this.subscriptions) {
+            subscription.dispose();
+        }
+        this.subscriptions.length = 0;
+        this.messageEmitter.dispose();
+    }
+}
+/** The dual of {@link PostMessageReader} — one `post` per JSON-RPC message. */
+class PostMessageWriter extends vscode_jsonrpc_1.AbstractMessageWriter {
+    channel;
+    subscriptions = [];
+    constructor(channel) {
+        super();
+        this.channel = channel;
+        const onClose = channel.onClose?.(() => this.fireClose());
+        if (onClose) {
+            this.subscriptions.push(onClose);
+        }
+    }
+    write(message) {
+        this.channel.post(message);
+        // `postMessage` reports no completion, so the resolved promise means
+        // "handed over", not "delivered". vscode-jsonrpc only needs the former.
+        return Promise.resolve();
+    }
+    end() {
+        this.dispose();
+    }
+    dispose() {
+        super.dispose();
+        for (const subscription of this.subscriptions) {
+            subscription.dispose();
+        }
+        this.subscriptions.length = 0;
+    }
+}
+/**
+ * Build the reader/writer pair for `channel`.
+ *
+ * What this buys, and why `DataPort` is shaped the way it is:
+ * `createRpcProxy` runs **unchanged** over the result. The typed surface, the
+ * `DATA_*_PROTOCOL_METHODS` allowlists and the whole open → watch → update →
+ * close sequence are identical in a webview and in a Node extension host,
+ * because only the `MessageConnection` the port hands back differs. Terminating
+ * JSON-RPC in the extension host and declaring one request type per data-head
+ * method is the wrong trade: it hand-maintains a per-method mapping and
+ * discards the `as const satisfies keyof` allowlists, which cannot drift.
+ */
+function createPostMessageTransport(channel) {
+    const reader = new PostMessageReader(channel);
+    const writer = new PostMessageWriter(channel);
+    return {
+        reader,
+        writer,
+        dispose() {
+            reader.dispose();
+            writer.dispose();
+        }
+    };
+}
+//# sourceMappingURL=post-message-transport.js.map

package/lib/client/post-message-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-message-transport.js","sourceRoot":"","sources":["../../src/client/post-message-transport.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;AAoJlF,gEAWC;AA7JD,mDASwB;AA4DxB;;;;;GAKG;AACH,MAAM,iBAAkB,SAAQ,sCAAqB;IAC/B,cAAc,GAAG,IAAI,wBAAO,EAAW,CAAC;IACxC,aAAa,GAAiB,EAAE,CAAC;IAEpD,YAAY,OAA2B;QACpC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACzF,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QAC1D,IAAI,OAAO,EAAE,CAAC;YACX,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,QAAsB;QAC1B,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAEQ,OAAO;QACb,KAAK,CAAC,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM,YAAY,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YAC7C,YAAY,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;IACjC,CAAC;CACH;AAED,+EAA+E;AAC/E,MAAM,iBAAkB,SAAQ,sCAAqB;IAGnB;IAFZ,aAAa,GAAiB,EAAE,CAAC;IAEpD,YAA+B,OAA2B;QACvD,KAAK,EAAE,CAAC;QADoB,YAAO,GAAP,OAAO,CAAoB;QAEvD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QAC1D,IAAI,OAAO,EAAE,CAAC;YACX,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAgB;QACnB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3B,qEAAqE;QACrE,wEAAwE;QACxE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IAED,GAAG;QACA,IAAI,CAAC,OAAO,EAAE,CAAC;IAClB,CAAC;IAEQ,OAAO;QACb,KAAK,CAAC,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM,YAAY,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YAC7C,YAAY,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;IACjC,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,0BAA0B,CAAC,OAA2B;IACnE,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC9C,OAAO;QACJ,MAAM;QACN,MAAM;QACN,OAAO;YACJ,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,CAAC;KACH,CAAC;AACL,CAAC"}

package/lib/clock.d.ts

@@ -0,0 +1,111 @@
+/********************************************************************************
+ * 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 { Disposable } from './util';
+/**
+ * Measures how long something takes. Born running at {@link Clock.stopwatch};
+ * there is no `start` — you create it at the moment timing begins.
+ *
+ * Backed by a monotonic source (`performance.now`), so it is sub-millisecond
+ * precise and immune to wall-clock jumps (NTP/DST adjustments can make a
+ * `Date.now` delta go backwards; a stopwatch cannot). Use this for durations
+ * and {@link Clock.now} for "what time is it" (timestamps, TTLs).
+ *
+ * It holds no scheduled resource and is therefore NOT a {@link Disposable} —
+ * the disposable thing is a {@link Clock.setTimer}. Reads are lazy, so a fake
+ * clock just answers the current virtual time.
+ */
+export interface Stopwatch {
+    /** Total elapsed since creation; live while running, frozen after {@link stop}. */
+    readonly elapsedMs: number;
+    /**
+     * Split: the elapsed since the previous `lap` (or since creation for the
+     * first call), starting a new split. Non-destructive — the running total
+     * ({@link elapsedMs}) is unaffected, so `lap` is not a restart.
+     */
+    lap(): number;
+    /**
+     * Freeze and return the grand total (the sum of every lap plus the tail
+     * since the last lap). Idempotent: further calls return the same value and
+     * {@link elapsedMs} stops advancing.
+     */
+    stop(): number;
+}
+/**
+ * Injectable time, so logic gated on time (debounce windows, slow-update
+ * warnings, request timeouts, the self-save TTL) is deterministically
+ * testable instead of waiting on real wall-clock. The {@link SystemClock}
+ * default delegates to the platform; tests bind `makeFakeClock`.
+ *
+ * Two distinct readings on purpose: {@link now} is wall-clock (for timestamps
+ * and TTLs that compare against a file's mtime), while {@link stopwatch}
+ * measures durations off a monotonic source. They are different clocks; do not
+ * subtract two {@link now} readings to measure a duration.
+ *
+ * A cross-head contract, so it carries no platform or DI-framework coupling.
+ *
+ * Note: the runtime health monitors (event-loop, memory) intentionally keep
+ * the real wall-clock rather than taking a `Clock` — faking the time they
+ * measure would invert their meaning.
+ */
+export interface Clock {
+    /** Current wall-clock time in milliseconds (the `Date.now` reading). */
+    now(): number;
+    /**
+     * Run `callback` after `ms` have elapsed; the returned {@link Disposable}
+     * cancels it if disposed before it fires. This is the testable
+     * `setTimeout` — debounce, deferred slow-warn, request timeouts.
+     */
+    setTimer(callback: () => void, ms: number): Disposable;
+    /** Start measuring a duration. See {@link Stopwatch}. */
+    stopwatch(): Stopwatch;
+    /**
+     * Run `callback` and return its result together with how long it took.
+     * Sugar over {@link stopwatch} — pure measurement, no logging and no
+     * threshold gating (unlike `Tracer.time`). Use in
+     * measurement pipelines that consume `elapsedMs` directly. Async callbacks
+     * return a Promise of the same shape, timed across the full settle.
+     */
+    measure<T>(callback: () => Promise<T>): Promise<Timed<T>>;
+    measure<T>(callback: () => T): Timed<T>;
+}
+/**
+ * The result of {@link Clock.measure}: a callback's return value paired with
+ * its elapsed wall-time in milliseconds. A plain value object — no methods, no
+ * logging — deliberately distinct from `@theia/core`'s `Measurement` (a
+ * stateful self-logging handle), which would collide in a Theia process.
+ */
+export interface Timed<T> {
+    /**
+     * The callback's return value, unchanged. For an async callback this is the
+     * settled value rather than the promise — and a callback that REJECTS
+     * produces no `Timed` at all, because the rejection propagates, so a failed
+     * run cannot be timed through this shape.
+     */
+    result: T;
+    /**
+     * Milliseconds off the monotonic source, so it is comparable with
+     * {@link Stopwatch.elapsedMs} and NOT with a difference of two
+     * {@link Clock.now} readings. For an async callback it spans the full settle,
+     * not just the synchronous prefix.
+     */
+    elapsedMs: number;
+}
+/**
+ * Default {@link Clock}: delegates to the platform's `Date.now`,
+ * `performance.now`, and `setTimeout`/`clearTimeout`. Bound everywhere in
+ * production; swapped for `makeFakeClock` in tests.
+ */
+export declare class SystemClock implements Clock {
+    now(): number;
+    setTimer(callback: () => void, ms: number): Disposable;
+    stopwatch(): Stopwatch;
+    measure<T>(callback: () => Promise<T>): Promise<Timed<T>>;
+    measure<T>(callback: () => T): Timed<T>;
+}
+//# sourceMappingURL=clock.d.ts.map

package/lib/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACvB,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,GAAG,IAAI,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,IAAI,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,KAAK;IACnB,wEAAwE;IACxE,GAAG,IAAI,MAAM,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC;IACvD,yDAAyD;IACzD,SAAS,IAAI,SAAS,CAAC;IACvB;;;;;;OAMG;IACH,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC;IACrB;;;;;OAKG;IACH,MAAM,EAAE,CAAC,CAAC;IACV;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;CACpB;AAyCD;;;;GAIG;AACH,qBAAa,WAAY,YAAW,KAAK;IACtC,GAAG,IAAI,MAAM;IAIb,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU;IAMtD,SAAS,IAAI,SAAS;IAItB,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACzD,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;CASzC"}

package/lib/clock.js

@@ -0,0 +1,74 @@
+"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.SystemClock = void 0;
+const util_1 = require("./util");
+class SystemStopwatch {
+    start = performance.now();
+    lastLap = this.start;
+    stopped;
+    get elapsedMs() {
+        return (this.stopped ?? performance.now()) - this.start;
+    }
+    lap() {
+        const at = this.stopped ?? performance.now();
+        const split = at - this.lastLap;
+        this.lastLap = at;
+        return split;
+    }
+    stop() {
+        if (this.stopped === undefined) {
+            this.stopped = performance.now();
+        }
+        return this.stopped - this.start;
+    }
+}
+/**
+ * Detach a timer from the event loop so a single pending timer never keeps a
+ * Node process alive — a CLI run or test worker can exit cleanly while deferred
+ * work (debounce, slow-warn, idle CST eviction) is still scheduled; the
+ * persistent server connection keeps the loop alive in production regardless.
+ *
+ * `unref` is Node-only. {@link SystemClock} also runs in the browser, where
+ * `setTimeout` returns a bare numeric handle with no `unref` — the optional
+ * call is a no-op there, and declaring the parameter's `unref` optional accepts
+ * a Node `NodeJS.Timeout` structurally without a cast.
+ */
+function unrefTimer(handle) {
+    handle.unref?.();
+}
+/**
+ * Default {@link Clock}: delegates to the platform's `Date.now`,
+ * `performance.now`, and `setTimeout`/`clearTimeout`. Bound everywhere in
+ * production; swapped for `makeFakeClock` in tests.
+ */
+class SystemClock {
+    now() {
+        return Date.now();
+    }
+    setTimer(callback, ms) {
+        const handle = setTimeout(callback, ms);
+        unrefTimer(handle);
+        return util_1.Disposable.create(() => clearTimeout(handle));
+    }
+    stopwatch() {
+        return new SystemStopwatch();
+    }
+    measure(callback) {
+        const stopwatch = this.stopwatch();
+        const result = callback();
+        if (result instanceof Promise) {
+            return result.then(value => ({ result: value, elapsedMs: stopwatch.elapsedMs }));
+        }
+        return { result: result, elapsedMs: stopwatch.elapsedMs };
+    }
+}
+exports.SystemClock = SystemClock;
+//# sourceMappingURL=clock.js.map

package/lib/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,iCAAoC;AA8FpC,MAAM,eAAe;IACC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IACnC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC;IACrB,OAAO,CAAqB;IAEtC,IAAI,SAAS;QACV,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,WAAW,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;IAC3D,CAAC;IAED,GAAG;QACA,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,IAAI,WAAW,CAAC,GAAG,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,OAAO,KAAK,CAAC;IAChB,CAAC;IAED,IAAI;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC;IACpC,CAAC;CACH;AAED;;;;;;;;;;GAUG;AACH,SAAS,UAAU,CAAC,MAA8B;IAC/C,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAa,WAAW;IACrB,GAAG;QACA,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACrB,CAAC;IAED,QAAQ,CAAC,QAAoB,EAAE,EAAU;QACtC,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACxC,UAAU,CAAC,MAAM,CAAC,CAAC;QACnB,OAAO,iBAAU,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,SAAS;QACN,OAAO,IAAI,eAAe,EAAE,CAAC;IAChC,CAAC;IAID,OAAO,CAAI,QAA8B;QACtC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC1B,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;YAC7B,OAAQ,MAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QACpG,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,MAAW,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC;IAClE,CAAC;CACH;AAzBD,kCAyBC"}

package/lib/data/data-protocol-methods.d.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/** Request-method names on {@link DocumentServerProtocol}. */
+export declare const DOCUMENT_SERVER_PROTOCOL_METHODS: readonly ["openModelDocument", "closeModelDocument", "getModelDocument", "updateModelDocument", "saveModelDocument", "watchModelDocument", "unwatchModelDocument", "waitForReady"];
+/** Request-method names on {@link ProjectServerProtocol}. */
+export declare const PROJECT_SERVER_PROTOCOL_METHODS: readonly ["getProjects", "getProjectForUri"];
+/**
+ * Request-method names on the composed {@link DataServerProtocol} — the
+ * document fragment followed by the project fragment. The `as const satisfies`
+ * constraint makes the array typed against the interface — stale names (typos,
+ * renamed methods) fail to typecheck.
+ */
+export declare const DATA_SERVER_PROTOCOL_METHODS: readonly ["openModelDocument", "closeModelDocument", "getModelDocument", "updateModelDocument", "saveModelDocument", "watchModelDocument", "unwatchModelDocument", "waitForReady", "getProjects", "getProjectForUri"];
+/**
+ * Request-method names on {@link ReferenceServerProtocol}. NOT part of
+ * {@link DATA_SERVER_PROTOCOL_METHODS} — adopters that compose the reference
+ * fragment register these alongside (e.g. via a `DataServer` subclass's
+ * `additionalMethods`).
+ */
+export declare const REFERENCE_SERVER_PROTOCOL_METHODS: readonly ["findReferenceCandidates", "resolveReference", "findNextName"];
+/** Notification-method names on {@link DocumentClientProtocol}. */
+export declare const DOCUMENT_CLIENT_PROTOCOL_METHODS: readonly ["onDocumentUpdated", "onDocumentSaved"];
+/** Notification-method names on {@link ProjectClientProtocol}. */
+export declare const PROJECT_CLIENT_PROTOCOL_METHODS: readonly ["onProjectsChanged"];
+/**
+ * Notification-method names on the composed {@link DataClientProtocol}.
+ * Passed as the `localMethods` allowlist to `createRpcProxy` (frontend) /
+ * `bindRpcMethods` (backend) when binding inbound `on*` notifications — the
+ * data head's connection routes `<methodNamespace>onDocumentUpdated` etc. to
+ * the bound client target.
+ */
+export declare const DATA_CLIENT_PROTOCOL_METHODS: readonly ["onDocumentUpdated", "onDocumentSaved", "onProjectsChanged"];
+//# sourceMappingURL=data-protocol-methods.d.ts.map

package/lib/data/data-protocol-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-protocol-methods.d.ts","sourceRoot":"","sources":["../../src/data/data-protocol-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAalF,8DAA8D;AAC9D,eAAO,MAAM,gCAAgC,oLAS6C,CAAC;AAE3F,6DAA6D;AAC7D,eAAO,MAAM,+BAA+B,8CAE3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,uNAG6C,CAAC;AAEvF;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,0EAI6C,CAAC;AAE5F,mEAAmE;AACnE,eAAO,MAAM,gCAAgC,mDAE5C,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,+BAA+B,gCAA+F,CAAC;AAE5I;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,wEAG6C,CAAC"}

package/lib/data/data-protocol-methods.js

@@ -0,0 +1,61 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DATA_CLIENT_PROTOCOL_METHODS = exports.PROJECT_CLIENT_PROTOCOL_METHODS = exports.DOCUMENT_CLIENT_PROTOCOL_METHODS = exports.REFERENCE_SERVER_PROTOCOL_METHODS = exports.DATA_SERVER_PROTOCOL_METHODS = exports.PROJECT_SERVER_PROTOCOL_METHODS = exports.DOCUMENT_SERVER_PROTOCOL_METHODS = void 0;
+/** Request-method names on {@link DocumentServerProtocol}. */
+exports.DOCUMENT_SERVER_PROTOCOL_METHODS = [
+    'openModelDocument',
+    'closeModelDocument',
+    'getModelDocument',
+    'updateModelDocument',
+    'saveModelDocument',
+    'watchModelDocument',
+    'unwatchModelDocument',
+    'waitForReady'
+];
+/** Request-method names on {@link ProjectServerProtocol}. */
+exports.PROJECT_SERVER_PROTOCOL_METHODS = ['getProjects', 'getProjectForUri'];
+/**
+ * Request-method names on the composed {@link DataServerProtocol} — the
+ * document fragment followed by the project fragment. The `as const satisfies`
+ * constraint makes the array typed against the interface — stale names (typos,
+ * renamed methods) fail to typecheck.
+ */
+exports.DATA_SERVER_PROTOCOL_METHODS = [
+    ...exports.DOCUMENT_SERVER_PROTOCOL_METHODS,
+    ...exports.PROJECT_SERVER_PROTOCOL_METHODS
+];
+/**
+ * Request-method names on {@link ReferenceServerProtocol}. NOT part of
+ * {@link DATA_SERVER_PROTOCOL_METHODS} — adopters that compose the reference
+ * fragment register these alongside (e.g. via a `DataServer` subclass's
+ * `additionalMethods`).
+ */
+exports.REFERENCE_SERVER_PROTOCOL_METHODS = [
+    'findReferenceCandidates',
+    'resolveReference',
+    'findNextName'
+];
+/** Notification-method names on {@link DocumentClientProtocol}. */
+exports.DOCUMENT_CLIENT_PROTOCOL_METHODS = ['onDocumentUpdated', 'onDocumentSaved'];
+/** Notification-method names on {@link ProjectClientProtocol}. */
+exports.PROJECT_CLIENT_PROTOCOL_METHODS = ['onProjectsChanged'];
+/**
+ * Notification-method names on the composed {@link DataClientProtocol}.
+ * Passed as the `localMethods` allowlist to `createRpcProxy` (frontend) /
+ * `bindRpcMethods` (backend) when binding inbound `on*` notifications — the
+ * data head's connection routes `<methodNamespace>onDocumentUpdated` etc. to
+ * the bound client target.
+ */
+exports.DATA_CLIENT_PROTOCOL_METHODS = [
+    ...exports.DOCUMENT_CLIENT_PROTOCOL_METHODS,
+    ...exports.PROJECT_CLIENT_PROTOCOL_METHODS
+];
+//# sourceMappingURL=data-protocol-methods.js.map

package/lib/data/data-protocol-methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-protocol-methods.js","sourceRoot":"","sources":["../../src/data/data-protocol-methods.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAalF,8DAA8D;AACjD,QAAA,gCAAgC,GAAG;IAC7C,mBAAmB;IACnB,oBAAoB;IACpB,kBAAkB;IAClB,qBAAqB;IACrB,mBAAmB;IACnB,oBAAoB;IACpB,sBAAsB;IACtB,cAAc;CACyE,CAAC;AAE3F,6DAA6D;AAChD,QAAA,+BAA+B,GAAG,CAAC,aAAa,EAAE,kBAAkB,CAEhF,CAAC;AAEF;;;;;GAKG;AACU,QAAA,4BAA4B,GAAG;IACzC,GAAG,wCAAgC;IACnC,GAAG,uCAA+B;CACiD,CAAC;AAEvF;;;;;GAKG;AACU,QAAA,iCAAiC,GAAG;IAC9C,yBAAyB;IACzB,kBAAkB;IAClB,cAAc;CAC0E,CAAC;AAE5F,mEAAmE;AACtD,QAAA,gCAAgC,GAAG,CAAC,mBAAmB,EAAE,iBAAiB,CAEtF,CAAC;AAEF,kEAAkE;AACrD,QAAA,+BAA+B,GAAG,CAAC,mBAAmB,CAAwE,CAAC;AAE5I;;;;;;GAMG;AACU,QAAA,4BAA4B,GAAG;IACzC,GAAG,wCAAgC;IACnC,GAAG,uCAA+B;CACiD,CAAC"}