@bian-womp/spark-remote 0.2.40 → 0.2.41

package/lib/cjs/index.cjs

@@ -1,16 +1,1139 @@
 'use strict';
 
-var index = require('./index-BS8Eessm.js');
-require('@bian-womp/spark-graph');
+var sparkGraph = require('@bian-womp/spark-graph');
 
+class SeqGenerator {
+    constructor() {
+        this.lastMs = 0;
+        this.seqInMs = 0;
+    }
+    next() {
+        const now = Date.now();
+        if (now === this.lastMs) {
+            this.seqInMs = (this.seqInMs + 1) % 1000;
+        }
+        else {
+            this.lastMs = now;
+            this.seqInMs = 0;
+        }
+        return now * 1000 + this.seqInMs;
+    }
+}
 
+const OPEN = 1;
+class WebSocketTransport {
+    constructor(url) {
+        this.listeners = new Set();
+        this.seq = new SeqGenerator();
+        this.baseUrl = url;
+    }
+    async connect(options) {
+        if (this.ws && this.ws.readyState === OPEN)
+            return;
+        // Build URL with connection params
+        // Handle both ws:///wss:// URLs and http:///https:// URLs (convert to ws)
+        let url;
+        if (this.baseUrl.startsWith("ws://") || this.baseUrl.startsWith("wss://")) {
+            url = new URL(this.baseUrl);
+        }
+        else {
+            // Convert http/https to ws/wss
+            const wsBaseUrl = this.baseUrl.replace(/^http/, "ws");
+            url = new URL(wsBaseUrl);
+        }
+        if (options?.params) {
+            for (const [key, value] of Object.entries(options.params)) {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        const wsUrl = url.toString();
+        this.ws = window
+            ? new window.WebSocket(wsUrl)
+            : new (await import('ws')).default(wsUrl);
+        await new Promise((resolve, reject) => {
+            if (!this.ws)
+                return reject(new Error("ws init failed"));
+            this.ws.onopen = () => resolve();
+            this.ws.onerror = (e) => reject(e);
+            this.ws.onmessage = (ev) => {
+                try {
+                    const env = JSON.parse(String(ev.data));
+                    for (const l of Array.from(this.listeners))
+                        l(env);
+                }
+                catch { }
+            };
+        });
+    }
+    async request(msg) {
+        // For now, just send and wait for the next message with matching seq (simple demo)
+        const seq = this.seq.next();
+        const env = { ...msg, seq };
+        const p = new Promise((resolve) => {
+            const off = this.subscribe((incoming) => {
+                if (incoming.seq === seq) {
+                    off();
+                    resolve(incoming);
+                }
+            });
+        });
+        this.send(env);
+        return p;
+    }
+    send(msg) {
+        if (!this.ws || this.ws.readyState !== OPEN)
+            return;
+        this.ws.send(JSON.stringify(msg));
+    }
+    subscribe(cb) {
+        this.listeners.add(cb);
+        return () => this.listeners.delete(cb);
+    }
+    async close() {
+        if (!this.ws)
+            return;
+        const ws = this.ws;
+        this.ws = undefined;
+        await new Promise((resolve) => {
+            ws.onclose = () => resolve();
+            try {
+                ws.close();
+            }
+            catch {
+                resolve();
+            }
+        });
+    }
+}
 
-exports.HttpPollingTransport = index.HttpPollingTransport;
-exports.RemoteEngine = index.RemoteEngine;
-exports.RuntimeApiClient = index.RuntimeApiClient;
-exports.RuntimeApiServer = index.RuntimeApiServer;
-exports.WebSocketTransport = index.WebSocketTransport;
-exports.createRuntimeAdapter = index.createRuntimeAdapter;
-exports.serializeError = index.serializeError;
-exports.summarize = index.summarize;
+class HttpPollingTransport {
+    constructor(baseUrl) {
+        this.listeners = new Set();
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+    }
+    async connect(options) {
+        // Store connection params for use in requests
+        this.connectParams = options?.params;
+        // Start polling loop
+        if (this.polling)
+            return;
+        const tick = async () => {
+            try {
+                const url = new URL(this.baseUrl + "/events");
+                if (this.cursor)
+                    url.searchParams.set("cursor", this.cursor);
+                // Add connection params to all requests
+                if (this.connectParams) {
+                    for (const [key, value] of Object.entries(this.connectParams)) {
+                        if (value !== undefined && value !== null) {
+                            url.searchParams.set(key, String(value));
+                        }
+                    }
+                }
+                const res = await fetch(url.toString());
+                if (!res.ok)
+                    return;
+                const batch = (await res.json());
+                for (const env of batch) {
+                    this.cursor = String(env.seq ?? Date.now());
+                    for (const l of Array.from(this.listeners))
+                        l(env);
+                }
+            }
+            catch { }
+        };
+        this.polling = setInterval(tick, 200);
+    }
+    async request(msg) {
+        const url = new URL(this.baseUrl + "/command");
+        // Add connection params to command requests
+        if (this.connectParams) {
+            for (const [key, value] of Object.entries(this.connectParams)) {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        const res = await fetch(url.toString(), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(msg),
+        });
+        const data = (await res.json());
+        return data;
+    }
+    send(msg) {
+        const url = new URL(this.baseUrl + "/command");
+        // Add connection params to send requests
+        if (this.connectParams) {
+            for (const [key, value] of Object.entries(this.connectParams)) {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        fetch(url.toString(), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(msg),
+        });
+    }
+    subscribe(cb) {
+        this.listeners.add(cb);
+        return () => this.listeners.delete(cb);
+    }
+    async close() {
+        if (this.polling)
+            clearInterval(this.polling);
+        this.polling = undefined;
+    }
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+function summarize(value, maxLen = 120) {
+    try {
+        const s = typeof value === "string" ? value : JSON.stringify(value);
+        return s.length > maxLen ? s.slice(0, maxLen) + "…" : s;
+    }
+    catch {
+        return String(value);
+    }
+}
+function serializeError(err) {
+    try {
+        if (!err)
+            return { message: String(err) };
+        const errAny = err;
+        if (err instanceof Error) {
+            const base = {
+                name: err.name,
+                message: err.message,
+                stack: err.stack,
+            };
+            for (const k of Object.keys(errAny))
+                base[k] = errAny[k];
+            return base;
+        }
+        if (typeof err === "object") {
+            const maybeMsg = errAny?.message;
+            const maybeName = errAny?.name;
+            const maybeStack = errAny?.stack;
+            const out = { ...errAny };
+            if (maybeMsg && !out.message)
+                out.message = String(maybeMsg);
+            if (maybeName && !out.name)
+                out.name = String(maybeName);
+            if (maybeStack && !out.stack)
+                out.stack = String(maybeStack);
+            return out;
+        }
+        return { message: String(err) };
+    }
+    catch {
+        return { message: String(err) };
+    }
+}
+
+async function createRuntimeAdapter(createRegistry, send, extensions) {
+    const registry = await createRegistry();
+    const builder = new sparkGraph.GraphBuilder(registry);
+    let graphRuntime;
+    let extData = {};
+    // Helper to get current context
+    const getContext = () => ({
+        registry,
+        builder,
+        graphRuntime,
+        extData,
+    });
+    // Original implementations - define as separate functions first to allow cross-references
+    const originalApi = {
+        coerce: async (from, to, value) => {
+            const resolved = registry.resolveCoercion(from, to);
+            if (!resolved)
+                return value;
+            if (resolved.kind === "sync")
+                return resolved.convert(value);
+            const ac = new AbortController();
+            return await resolved.convertAsync(value, ac.signal);
+        },
+        getEnvironment: () => {
+            return graphRuntime?.getEnvironment?.() ?? {};
+        },
+        applyRegistry: async (deltas) => {
+            // Pause runtime if exists
+            // Apply each delta to the live registry
+            for (const d of deltas || []) {
+                if (!d || typeof d !== "object")
+                    continue;
+                if (d.kind === "register-enum") {
+                    registry.registerEnum({
+                        id: d.id,
+                        displayName: d.displayName,
+                        options: d.options || [],
+                        bakeTarget: d.bakeTarget,
+                        opts: d.opts,
+                    });
+                }
+                else if (d.kind === "register-type") {
+                    registry.registerType({
+                        id: d.id,
+                        displayName: d.displayName,
+                        bakeTarget: d.bakeTarget,
+                        validate: (_v) => true,
+                    });
+                }
+                else if (d.kind === "register-node") {
+                    const desc = d.desc || {};
+                    registry.registerNode({
+                        id: String(desc.id || ""),
+                        categoryId: String(desc.categoryId || "compute"),
+                        displayName: desc.displayName,
+                        inputs: desc.inputs || {},
+                        outputs: desc.outputs || {},
+                        // impl must be empty per frontend registration contract
+                        impl: () => { },
+                    });
+                }
+            }
+            // Notify clients (include deltas in invalidate payload)
+            send({
+                message: {
+                    type: "invalidate",
+                    payload: { reason: "registry-changed", deltas },
+                },
+            });
+        },
+        build: async (def, opts) => {
+            const env = opts || {};
+            graphRuntime = builder.build(def, { environment: env });
+            graphRuntime.on("value", (p) => send({ message: { type: "value", payload: p } }));
+            graphRuntime.on("invalidate", (p) => send({ message: { type: "invalidate", payload: p } }));
+            graphRuntime.on("error", (p) => send({ message: { type: "error", payload: p } }));
+            graphRuntime.on("stats", (p) => send({ message: { type: "stats", payload: p } }));
+        },
+        setExtData: (data) => {
+            if (!data || typeof data !== "object") {
+                extData = {};
+                return;
+            }
+            // Replace to keep semantics deterministic
+            extData = { ...data };
+        },
+        getExtData: () => {
+            return extData;
+        },
+        snapshot: () => {
+            const inputs = {};
+            const outputs = {};
+            if (!graphRuntime)
+                return { inputs, outputs };
+            const nodes = graphRuntime.getNodeIds();
+            for (const nodeId of nodes) {
+                const data = graphRuntime.getNodeData(nodeId);
+                if (data?.inputs && Object.keys(data.inputs).length > 0) {
+                    inputs[nodeId] = { ...data.inputs };
+                }
+                if (data?.outputs && Object.keys(data.outputs).length > 0) {
+                    outputs[nodeId] = { ...data.outputs };
+                }
+            }
+            return { inputs, outputs };
+        },
+        snapshotFull: () => {
+            const snap = originalApi.snapshot();
+            const env = graphRuntime?.getEnvironment?.() ?? {};
+            const def = graphRuntime?.getGraphDef();
+            return {
+                def,
+                environment: env,
+                inputs: snap.inputs,
+                outputs: snap.outputs,
+            };
+        },
+        applySnapshotFull: async (payload) => {
+            const def = payload.def;
+            if (!def)
+                return;
+            await originalApi.build(def, payload.environment);
+            // Hydrate inputs/outputs exactly, then re-emit outputs without scheduling runs
+            graphRuntime?.hydrate({
+                inputs: payload.inputs,
+                outputs: payload.outputs,
+            });
+        },
+        describeRegistry: () => {
+            // types (include enum options when available)
+            const types = Array.from(registry.types.entries()).map(([id, d]) => {
+                const en = registry.enums.get(id);
+                return {
+                    id,
+                    displayName: d.displayName,
+                    bakeTarget: d.bakeTarget,
+                    ...(en ? { options: en.options } : {}),
+                };
+            });
+            // categories: not directly enumerable; derive from node descriptors
+            const nodeDescs = Array.from(registry.nodes.values());
+            const catIds = new Set(nodeDescs.map((n) => n.categoryId));
+            const categories = Array.from(catIds).map((id) => {
+                const cat = registry.categories.get?.(id);
+                return { id, displayName: cat?.displayName };
+            });
+            const nodes = nodeDescs.map((n) => ({
+                id: n.id,
+                categoryId: n.categoryId,
+                displayName: n.displayName,
+                inputs: n.inputs || {},
+                outputs: n.outputs || {},
+                inputDefaults: n.inputDefaults || {},
+            }));
+            const coercions = registry.listCoercions();
+            return { types, categories, nodes, coercions, schemaVersion: 4 };
+        },
+        update: async (def) => {
+            if (!graphRuntime)
+                return;
+            graphRuntime.update(def, registry);
+            send({
+                message: {
+                    type: "invalidate",
+                    payload: { reason: "graph-updated" },
+                },
+            });
+        },
+        setEnvironment: (env, opts) => {
+            if (!graphRuntime)
+                return;
+            if (opts?.merge) {
+                const current = graphRuntime.getEnvironment();
+                const next = { ...(current || {}), ...(env || {}) };
+                graphRuntime.setEnvironment(next);
+                return;
+            }
+            graphRuntime.setEnvironment(env);
+        },
+        setInput: (nodeId, handle, value) => {
+            graphRuntime?.setInput(nodeId, handle, value);
+        },
+        setInputs: (nodeId, inputs) => {
+            graphRuntime?.setInputs(nodeId, inputs);
+        },
+        triggerExternal: (nodeId, event) => {
+            graphRuntime?.triggerExternal(nodeId, event);
+        },
+        launch: (invalidate) => {
+            graphRuntime?.launch(invalidate);
+        },
+        whenIdle: () => {
+            return graphRuntime?.whenIdle?.() ?? Promise.resolve();
+        },
+        dispose: () => {
+            graphRuntime?.dispose?.();
+            graphRuntime = undefined;
+        },
+    };
+    // Helper to wrap a method with extension support
+    const wrapMethod = (key, original) => {
+        const extension = extensions?.[key];
+        if (!extension) {
+            return original;
+        }
+        return ((...args) => {
+            return extension(original, getContext(), ...args);
+        });
+    };
+    // Create API with extensions applied
+    const extendedApi = {
+        coerce: wrapMethod("coerce", originalApi.coerce),
+        getEnvironment: wrapMethod("getEnvironment", originalApi.getEnvironment),
+        applyRegistry: wrapMethod("applyRegistry", originalApi.applyRegistry),
+        build: wrapMethod("build", originalApi.build),
+        setExtData: wrapMethod("setExtData", originalApi.setExtData),
+        getExtData: wrapMethod("getExtData", originalApi.getExtData),
+        snapshot: wrapMethod("snapshot", originalApi.snapshot),
+        snapshotFull: wrapMethod("snapshotFull", originalApi.snapshotFull),
+        applySnapshotFull: wrapMethod("applySnapshotFull", originalApi.applySnapshotFull),
+        describeRegistry: wrapMethod("describeRegistry", originalApi.describeRegistry),
+        update: wrapMethod("update", originalApi.update),
+        setEnvironment: wrapMethod("setEnvironment", originalApi.setEnvironment),
+        setInput: wrapMethod("setInput", originalApi.setInput),
+        setInputs: wrapMethod("setInputs", originalApi.setInputs),
+        triggerExternal: wrapMethod("triggerExternal", originalApi.triggerExternal),
+        launch: wrapMethod("launch", originalApi.launch),
+        whenIdle: wrapMethod("whenIdle", originalApi.whenIdle),
+        dispose: wrapMethod("dispose", originalApi.dispose),
+    };
+    return extendedApi;
+}
+
+class RemoteEngine {
+    constructor(transport) {
+        this.transport = transport;
+        this.listeners = new Map();
+        this.cache = new Map();
+        this.transport.subscribe((env) => this.onEnvelope(env));
+    }
+    onEnvelope(env) {
+        const msg = env.message;
+        if (!msg)
+            return;
+        if (msg.type === "value") {
+            const key = `${msg.payload.nodeId}.${msg.payload.handle}`;
+            this.cache.set(key, {
+                value: msg.payload.value,
+                runtimeTypeId: msg.payload.runtimeTypeId,
+            });
+            this.emit("value", msg.payload);
+        }
+        else if (msg.type === "error") {
+            this.emit("error", msg.payload);
+        }
+        else if (msg.type === "invalidate") {
+            this.emit("invalidate", msg.payload);
+        }
+        else if (msg.type === "stats") {
+            this.emit("stats", msg.payload);
+        }
+    }
+    launch(invalidate) {
+        this.transport.send({
+            message: { type: "Launch", payload: { invalidate } },
+        });
+    }
+    setInput(nodeId, handle, value) {
+        this.transport.send({
+            message: { type: "SetInput", payload: { nodeId, handle, value } },
+        });
+    }
+    // Batch inputs for a single network round-trip
+    setInputs(nodeId, inputs) {
+        this.transport.send({
+            message: { type: "SetInputs", payload: { nodeId, inputs } },
+        });
+    }
+    triggerExternal(nodeId, event) {
+        this.transport.send({
+            message: { type: "TriggerExternal", payload: { nodeId, event } },
+        });
+    }
+    on(event, handler) {
+        if (!this.listeners.has(event))
+            this.listeners.set(event, new Set());
+        const set = this.listeners.get(event);
+        set.add(handler);
+        return () => set.delete(handler);
+    }
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (set)
+            for (const h of Array.from(set))
+                h(payload);
+    }
+    getOutput(nodeId, output) {
+        return this.cache.get(`${nodeId}.${output}`)?.value;
+    }
+    async whenIdle() {
+        await this.transport.request({ message: { type: "WhenIdle" } });
+    }
+    dispose() {
+        this.transport.send({ message: { type: "Dispose" } });
+    }
+}
+
+// Node-only transport using a UNIX domain socket.
+// Import directly from path: "@bian-womp/spark-remote/transport/UnixSocketTransport" in Node/Electron code.
+// Do not re-export from the browser index to avoid bundling in web builds.
+class UnixSocketTransport {
+    constructor(socketPath) {
+        this.socketPath = socketPath;
+        this.listeners = new Set();
+        this.buffer = "";
+        this.waiters = new Map();
+        this.seq = new SeqGenerator();
+    }
+    async connect() {
+        if (typeof process === "undefined") {
+            throw new Error("UnixSocketTransport requires a Node environment");
+        }
+        if (this.socket)
+            return;
+        const { createConnection } = await import('node:net');
+        const sock = createConnection(this.socketPath);
+        this.socket = sock;
+        await new Promise((resolve, reject) => {
+            sock.once("connect", () => resolve());
+            sock.once("error", (e) => reject(e));
+        });
+        sock.on("data", (chunk) => this.onData(chunk));
+        sock.on("error", () => {
+            /* noop, surface via request waiters if needed */
+        });
+    }
+    onData(chunk) {
+        this.buffer += chunk.toString("utf8");
+        let idx = this.buffer.indexOf("\n");
+        while (idx >= 0) {
+            const raw = this.buffer.slice(0, idx);
+            this.buffer = this.buffer.slice(idx + 1);
+            idx = this.buffer.indexOf("\n");
+            if (!raw.trim())
+                continue;
+            try {
+                const env = JSON.parse(raw);
+                if (env && typeof env.seq === "number" && this.waiters.has(env.seq)) {
+                    const fn = this.waiters.get(env.seq);
+                    this.waiters.delete(env.seq);
+                    fn(env);
+                }
+                else {
+                    for (const l of Array.from(this.listeners))
+                        l(env);
+                }
+            }
+            catch {
+                // ignore malformed frames
+            }
+        }
+    }
+    async request(msg) {
+        const seq = typeof msg.seq === "number" ? msg.seq : this.seq.next();
+        const env = { ...msg, seq };
+        const p = new Promise((resolve) => {
+            this.waiters.set(seq, (incoming) => resolve(incoming));
+        });
+        this.send(env);
+        return p;
+    }
+    send(msg) {
+        const s = this.socket;
+        if (!s)
+            return;
+        try {
+            s.write(JSON.stringify(msg) + "\n");
+        }
+        catch {
+            // ignore
+        }
+    }
+    subscribe(cb) {
+        this.listeners.add(cb);
+        return () => this.listeners.delete(cb);
+    }
+    async close() {
+        const s = this.socket;
+        this.socket = undefined;
+        if (!s)
+            return;
+        await new Promise((resolve) => {
+            try {
+                s.end(() => resolve());
+            }
+            catch {
+                resolve();
+            }
+        });
+    }
+}
+
+class RuntimeApiClient {
+    constructor(config, options) {
+        this.customEventListeners = new Set();
+        this.transportEventListeners = new Set();
+        this.disposed = false;
+        this.config = config;
+        this.onCustomEvent = options?.onCustomEvent;
+        // Engine will be created after transport is connected
+    }
+    /**
+     * Create transport instance based on config.
+     * Extracted to a separate method for better testability and clarity.
+     */
+    async createTransport() {
+        const kind = this.config.kind;
+        if (kind === "remote-http") {
+            if (!HttpPollingTransport) {
+                throw new Error("HttpPollingTransport not available");
+            }
+            return new HttpPollingTransport(this.config.baseUrl);
+        }
+        else if (kind === "remote-ws") {
+            if (!WebSocketTransport) {
+                throw new Error("WebSocketTransport not available");
+            }
+            return new WebSocketTransport(this.config.url);
+        }
+        else if (kind === "remote-unix") {
+            // Dynamic import to avoid bundling in browser builds
+            return new UnixSocketTransport(this.config.socketPath);
+        }
+        else {
+            throw new Error(`Invalid transport kind: ${kind}`);
+        }
+    }
+    /**
+     * Connect to the remote runtime API.
+     * Creates and connects the transport, then initializes the engine.
+     * Safe to call multiple times - concurrent calls will wait for the same connection.
+     */
+    async connect() {
+        if (this.disposed) {
+            throw new Error("Cannot connect: RuntimeApiClient has been disposed");
+        }
+        if (this.transport) {
+            // Already connected
+            return;
+        }
+        // If already connecting, wait for that connection to complete
+        if (this.connectingPromise) {
+            return this.connectingPromise;
+        }
+        const kind = this.config.kind;
+        this.emitTransportStatus({ state: "connecting", kind });
+        // Create connection promise to prevent concurrent connections
+        this.connectingPromise = (async () => {
+            try {
+                const transport = await this.createTransport();
+                await transport.connect(this.config.connectOptions);
+                this.transport = transport;
+                // Subscribe to all transport events
+                this.transportUnsubscribe = transport.subscribe((event) => {
+                    this.handleTransportEvent(event);
+                });
+                // Create engine with connected transport
+                this.engine = new RemoteEngine(transport);
+                this.emitTransportStatus({ state: "connected", kind });
+            }
+            catch (error) {
+                // Clear connecting promise on error so retry is possible
+                this.connectingPromise = undefined;
+                this.emitTransportStatus({ state: "disconnected", kind });
+                throw error;
+            }
+            finally {
+                // Clear connecting promise on success
+                this.connectingPromise = undefined;
+            }
+        })();
+        return this.connectingPromise;
+    }
+    /**
+     * Handle events from transport.
+     * Routes standard runtime events to engine, custom events to custom handlers.
+     */
+    handleTransportEvent(event) {
+        const msg = event.message;
+        if (!msg || typeof msg !== "object" || !("type" in msg))
+            return;
+        const type = msg.type;
+        // Standard runtime events: stats, value, error, invalidate
+        // These are handled by RemoteEngine via transport subscription
+        // Custom events are anything else (e.g., flow-opened, flow-latest)
+        if (!["stats", "value", "error", "invalidate"].includes(type)) {
+            // Emit to custom event listeners
+            for (const listener of this.customEventListeners) {
+                listener(event);
+            }
+            // Also call the constructor-provided handler if present
+            this.onCustomEvent?.(event);
+        }
+    }
+    /**
+     * Subscribe to custom events (non-standard runtime events like flow-opened, flow-latest).
+     * Returns an unsubscribe function.
+     */
+    subscribeCustomEvents(listener) {
+        this.customEventListeners.add(listener);
+        return () => {
+            this.customEventListeners.delete(listener);
+        };
+    }
+    /**
+     * Subscribe to transport status changes.
+     * Returns an unsubscribe function.
+     */
+    onTransportStatus(listener) {
+        this.transportEventListeners.add(listener);
+        // Immediately emit current status if connected
+        if (this.transport) {
+            const kind = this.config.kind;
+            listener({ state: "connected", kind });
+        }
+        return () => {
+            this.transportEventListeners.delete(listener);
+        };
+    }
+    emitTransportStatus(status) {
+        for (const listener of this.transportEventListeners) {
+            listener(status);
+        }
+    }
+    /**
+     * Ensure transport is connected. Called automatically by API methods.
+     * Returns the transport instance, throwing if connection fails or client is disposed.
+     */
+    async ensureConnected() {
+        if (this.disposed) {
+            throw new Error("Cannot ensure connection: RuntimeApiClient has been disposed");
+        }
+        if (!this.transport) {
+            await this.connect();
+        }
+        // After connect(), transport is guaranteed to be set
+        if (!this.transport) {
+            throw new Error("Failed to establish transport connection");
+        }
+        return this.transport;
+    }
+    async build(def, opts) {
+        const transport = await this.ensureConnected();
+        await transport.request({
+            message: {
+                type: "Build",
+                payload: { def, environment: opts?.environment },
+            },
+        });
+    }
+    async update(def) {
+        const transport = await this.ensureConnected();
+        await transport.request({
+            message: { type: "Update", payload: { def } },
+        });
+    }
+    async describeRegistry() {
+        const transport = await this.ensureConnected();
+        const res = await transport.request({
+            message: { type: "DescribeRegistry" },
+        });
+        const payload = res?.message || {};
+        return (payload.registry || {
+            types: [],
+            categories: [],
+            nodes: [],
+            coercions: [],
+            schemaVersion: 4,
+        });
+    }
+    async applyRegistry(deltas) {
+        const transport = await this.ensureConnected();
+        await transport.request({
+            message: { type: "RegistryApply", payload: { deltas } },
+        });
+    }
+    async snapshot() {
+        const transport = await this.ensureConnected();
+        const res = await transport.request({
+            message: { type: "Snapshot" },
+        });
+        const payload = res?.message || {};
+        return payload.snapshot || { inputs: {}, outputs: {} };
+    }
+    async snapshotFull() {
+        const transport = await this.ensureConnected();
+        const res = await transport.request({
+            message: { type: "SnapshotFull" },
+        });
+        const payload = res?.message || {};
+        return (payload.snapshot || {
+            def: undefined,
+            environment: {},
+            inputs: {},
+            outputs: {},
+        });
+    }
+    async applySnapshotFull(payload) {
+        const transport = await this.ensureConnected();
+        await transport.request({
+            message: { type: "ApplySnapshotFull", payload },
+        });
+    }
+    async setEnvironment(environment, opts) {
+        const transport = await this.ensureConnected();
+        await transport.request({
+            message: {
+                type: "SetEnvironment",
+                payload: { environment, merge: opts?.merge },
+            },
+        });
+    }
+    async getEnvironment() {
+        const transport = await this.ensureConnected();
+        const res = await transport.request({
+            message: { type: "GetEnvironment" },
+        });
+        const payload = res?.message || {};
+        return payload.environment || {};
+    }
+    async coerce(from, to, value) {
+        const transport = await this.ensureConnected();
+        const res = await transport.request({
+            message: { type: "Coerce", payload: { from, to, value } },
+        });
+        const payload = res?.message || {};
+        return payload.value;
+    }
+    getEngine() {
+        if (!this.engine) {
+            throw new Error("Engine not available: call connect() first");
+        }
+        return this.engine;
+    }
+    /**
+     * Dispose the client and close the transport connection.
+     * Idempotent: safe to call multiple times.
+     */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // Clear connecting promise if any
+        this.connectingPromise = undefined;
+        // Unsubscribe from transport events
+        if (this.transportUnsubscribe) {
+            this.transportUnsubscribe();
+            this.transportUnsubscribe = undefined;
+        }
+        // Close transport connection
+        if (this.transport) {
+            const transportToClose = this.transport;
+            this.transport = undefined;
+            this.engine = undefined; // Clear engine reference
+            await transportToClose.close().catch((err) => {
+                console.warn("[RuntimeApiClient] Error closing transport:", err);
+            });
+        }
+        // Clear listeners
+        this.customEventListeners.clear();
+        this.transportEventListeners.clear();
+        this.emitTransportStatus({ state: "disconnected", kind: this.config.kind });
+    }
+}
+
+class RuntimeApiServer {
+    constructor(runtimeApi, label, onError) {
+        this.runtimeApi = runtimeApi;
+        this.label = label;
+        this.onError = onError;
+        this.middlewares = [];
+    }
+    /**
+     * Register middleware to preprocess commands before handling.
+     * Middlewares are executed in registration order.
+     */
+    use(middleware) {
+        this.middlewares.push(middleware);
+    }
+    /**
+     * Handle command with error handling and middleware support.
+     */
+    async handleCommand(env, ack) {
+        try {
+            // Execute middlewares in sequence, then process command
+            await this.executeMiddlewares(env, async () => {
+                await this.processCommand(env, ack);
+            });
+        }
+        catch (err) {
+            this.handleError(env, err);
+        }
+    }
+    /**
+     * Execute middlewares in sequence, then call the final handler.
+     */
+    async executeMiddlewares(env, finalHandler) {
+        let index = 0;
+        const next = async () => {
+            if (index >= this.middlewares.length) {
+                await finalHandler();
+                return;
+            }
+            const middleware = this.middlewares[index++];
+            await middleware(env, next);
+        };
+        await next();
+    }
+    /**
+     * Process the command by routing to the appropriate handler.
+     */
+    async processCommand(env, ack) {
+        const msg = env.message;
+        switch (msg.type) {
+            case "Build": {
+                this.logCommand("Build", env, {
+                    nodes: msg.payload.def.nodes?.length ?? 0,
+                    edges: msg.payload.def.edges?.length ?? 0,
+                    envKeys: Object.keys(msg.payload.environment ?? {}).join(","),
+                });
+                await this.runtimeApi.build(msg.payload.def, msg.payload.environment);
+                ack();
+                break;
+            }
+            case "Update": {
+                this.logCommand("Update", env, {
+                    nodes: msg.payload.def.nodes?.length ?? 0,
+                    edges: msg.payload.def.edges?.length ?? 0,
+                });
+                await this.runtimeApi.update(msg.payload.def);
+                ack();
+                break;
+            }
+            case "SetEnvironment": {
+                this.logCommand("SetEnvironment", env);
+                this.runtimeApi.setEnvironment(msg.payload.environment, {
+                    merge: Boolean(msg.payload.merge),
+                });
+                ack();
+                break;
+            }
+            case "SetInput": {
+                this.logCommand("SetInput", env, {
+                    nodeId: msg.payload.nodeId,
+                    handle: msg.payload.handle,
+                    value: summarize(msg.payload.value),
+                });
+                this.runtimeApi.setInput(msg.payload.nodeId, msg.payload.handle, msg.payload.value);
+                ack();
+                break;
+            }
+            case "SetInputs": {
+                this.logCommand("SetInputs", env, {
+                    nodeId: msg.payload.nodeId,
+                    keys: Object.keys(msg.payload.inputs || {}).join(","),
+                });
+                const nodeId = msg.payload.nodeId;
+                const inputs = msg.payload.inputs;
+                this.runtimeApi.setInputs(nodeId, inputs);
+                ack();
+                break;
+            }
+            case "TriggerExternal": {
+                this.logCommand("TriggerExternal", env, {
+                    nodeId: msg.payload.nodeId,
+                    event: summarize(msg.payload.event),
+                });
+                this.runtimeApi.triggerExternal(msg.payload.nodeId, msg.payload.event);
+                ack();
+                break;
+            }
+            case "Launch": {
+                this.logCommand("Launch", env);
+                this.runtimeApi.launch(msg.payload.invalidate);
+                ack();
+                break;
+            }
+            case "WhenIdle": {
+                this.logCommand("WhenIdle", env);
+                await this.runtimeApi.whenIdle();
+                ack();
+                break;
+            }
+            case "Snapshot": {
+                this.logCommand("Snapshot", env);
+                const snap = this.runtimeApi.snapshot();
+                ack({ snapshot: snap });
+                break;
+            }
+            case "SnapshotFull": {
+                this.logCommand("SnapshotFull", env);
+                const snap = this.runtimeApi.snapshotFull();
+                ack({ snapshot: snap });
+                break;
+            }
+            case "GetEnvironment": {
+                this.logCommand("GetEnvironment", env);
+                const environment = this.runtimeApi.getEnvironment();
+                ack({ environment });
+                break;
+            }
+            case "ApplySnapshotFull": {
+                this.logCommand("ApplySnapshotFull", env);
+                await this.runtimeApi.applySnapshotFull(msg.payload);
+                ack();
+                break;
+            }
+            case "Coerce": {
+                this.logCommand("Coerce", env, {
+                    from: msg.payload.from,
+                    to: msg.payload.to,
+                });
+                const value = await this.runtimeApi.coerce(msg.payload?.from, msg.payload?.to, msg.payload?.value);
+                ack({ value });
+                break;
+            }
+            case "DescribeRegistry": {
+                this.logCommand("DescribeRegistry", env);
+                const desc = this.runtimeApi.describeRegistry();
+                ack({ registry: desc });
+                break;
+            }
+            case "RegistryApply": {
+                this.logCommand("RegistryApply", env);
+                await this.runtimeApi.applyRegistry(msg.payload.deltas || []);
+                ack();
+                break;
+            }
+            case "Dispose": {
+                this.logCommand("Dispose", env);
+                this.runtimeApi.dispose();
+                ack();
+                break;
+            }
+            case "Pause":
+            case "Resume": {
+                this.logCommand(`${msg.type} (not-impl)`, env);
+                ack();
+                break;
+            }
+            default: {
+                this.logCommand("Unknown type", env);
+                ack();
+            }
+        }
+    }
+    /**
+     * Helper method to log commands with consistent format.
+     */
+    logCommand(type, env, extra) {
+        const extraStr = extra
+            ? ` ${Object.entries(extra)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(" ")}`
+            : "";
+        console.debug(`[${this.label}] rx ${type} seq=${env.seq}${extraStr}`);
+    }
+    /**
+     * Handle errors and notify error handler if provided.
+     * Formats errors as SystemError since these are infrastructure/command processing errors,
+     * not node execution errors.
+     */
+    handleError(env, err) {
+        console.error(`[${this.label}] error handling command:`, err);
+        const serialized = serializeError(err);
+        const systemError = {
+            kind: "system",
+            message: serialized?.message || String(err) || "Unknown error",
+            code: serialized?.code || serialized?.statusCode || 500,
+            err: serialized,
+        };
+        const errorEnv = {
+            seq: env.seq ?? Date.now(),
+            ts: Date.now(),
+            message: { type: "error", payload: systemError },
+        };
+        if (this.onError) {
+            this.onError(errorEnv);
+        }
+    }
+}
+
+exports.HttpPollingTransport = HttpPollingTransport;
+exports.RemoteEngine = RemoteEngine;
+exports.RuntimeApiClient = RuntimeApiClient;
+exports.RuntimeApiServer = RuntimeApiServer;
+exports.WebSocketTransport = WebSocketTransport;
+exports.createRuntimeAdapter = createRuntimeAdapter;
+exports.serializeError = serializeError;
+exports.summarize = summarize;
 //# sourceMappingURL=index.cjs.map