@synapse-sdk/client 0.1.0

package/dist/node-CSSIXG4k.js

@@ -0,0 +1,1501 @@
+import * as Phoenix from "phoenix";
+//#region src/errors.ts
+var ConnectionError = class extends Error {
+	constructor(message, options) {
+		super(message);
+		this.name = "ConnectionError";
+		if (options && options.cause !== void 0) this.cause = options.cause;
+	}
+};
+var TimeoutError = class extends ConnectionError {
+	constructor(message) {
+		super(message);
+		this.name = "TimeoutError";
+	}
+};
+/** A newer `connect(...)` (or `disconnect()`) replaced the target this promise was awaiting. */
+var SupersededError = class extends ConnectionError {
+	constructor() {
+		super("connection target was superseded");
+		this.name = "SupersededError";
+	}
+};
+var ChannelError = class extends Error {
+	topic;
+	response;
+	constructor(topic, message, response) {
+		super(`channel ${topic}: ${message}`);
+		this.name = "ChannelError";
+		this.topic = topic;
+		this.response = response;
+	}
+};
+/**
+* Known bus error codes — server-emitted (`unauthorized`, `service_unavailable`,
+* `provider_error`, `invalid_input`, `unknown_event`, `ros_error`) plus client-side
+* (`bad_ack`, `not_connected`, `timeout`, `cancelled`). Match on these to avoid magic
+* strings; treat the set as **non-exhaustive** (the server may add codes).
+*/
+const BusErrorCode = {
+	Unauthorized: "unauthorized",
+	ServiceUnavailable: "service_unavailable",
+	ProviderError: "provider_error",
+	InvalidInput: "invalid_input",
+	UnknownEvent: "unknown_event",
+	RosError: "ros_error",
+	BadAck: "bad_ack",
+	NotConnected: "not_connected",
+	Timeout: "timeout",
+	Cancelled: "cancelled"
+};
+/** Raised when a service call fails — at accept time or mid-flight (see the bus error model). */
+var BusError = class extends Error {
+	code;
+	detail;
+	constructor(error) {
+		const e = error ?? {};
+		super(typeof e.message === "string" ? e.message : "bus error");
+		this.name = "BusError";
+		this.code = typeof e.code === "string" ? e.code : "error";
+		this.detail = error;
+	}
+};
+//#endregion
+//#region src/channel.ts
+/**
+* One topic on the connection. Owned and reference-counted by `Connection` (one Channel
+* per topic). Membership is independent of any UI component lifecycle: listeners attach
+* and detach freely via `on`/`off` without re-joining, and the channel auto-rejoins when
+* the socket reconnects.
+*/
+var Channel = class {
+	topic;
+	state = "closed";
+	host;
+	params;
+	joinRef = null;
+	joinPromise = null;
+	joinResponse = void 0;
+	bindings = /* @__PURE__ */ new Map();
+	constructor(host, topic, params) {
+		this.host = host;
+		this.topic = topic;
+		this.params = params;
+	}
+	/** Idempotent: a join in flight or already joined returns the existing result. */
+	join(timeoutMs) {
+		if (this.state === "joined") return Promise.resolve(this.joinResponse);
+		if (this.state === "joining" && this.joinPromise) return this.joinPromise;
+		return this.doJoin(timeoutMs);
+	}
+	doJoin(timeoutMs) {
+		if (!this.host._isOpen()) {
+			this.state = "errored";
+			return Promise.reject(new ChannelError(this.topic, "socket not open"));
+		}
+		this.state = "joining";
+		const ref = this.host._makeRef();
+		this.joinRef = ref;
+		this.joinPromise = this.host._request({
+			join_ref: ref,
+			ref,
+			topic: this.topic,
+			event: "phx_join",
+			payload: this.params
+		}, timeoutMs).then((reply) => {
+			if (reply.status === "ok") {
+				this.state = "joined";
+				this.joinResponse = reply.response;
+				return reply.response;
+			}
+			this.state = "errored";
+			throw new ChannelError(this.topic, `join ${reply.status}`, reply.response);
+		}).catch((e) => {
+			this.state = "errored";
+			throw e;
+		});
+		return this.joinPromise;
+	}
+	async leave(timeoutMs) {
+		const wasActive = this.state === "joined" || this.state === "joining";
+		this.state = "leaving";
+		this.host._removeChannel(this.topic);
+		if (wasActive && this.joinRef && this.host._isOpen()) try {
+			await this.host._request({
+				join_ref: this.joinRef,
+				ref: this.host._makeRef(),
+				topic: this.topic,
+				event: "phx_leave",
+				payload: {}
+			}, timeoutMs);
+		} catch {}
+		this.state = "closed";
+		this.joinRef = null;
+		this.joinPromise = null;
+		this.bindings.clear();
+	}
+	/** Fire-and-forget; for handlers that reply with `{:noreply, ...}` (e.g. pub/sub publish). */
+	push(event, payload) {
+		this.host._send({
+			join_ref: this.joinRef,
+			ref: this.host._makeRef(),
+			topic: this.topic,
+			event,
+			payload: payload ?? {}
+		});
+	}
+	/** Send and await the reply; for handlers that reply with `{:reply, ...}`. */
+	request(event, payload, timeoutMs) {
+		return this.host._request({
+			join_ref: this.joinRef,
+			ref: this.host._makeRef(),
+			topic: this.topic,
+			event,
+			payload: payload ?? {}
+		}, timeoutMs);
+	}
+	on(event, cb) {
+		let set = this.bindings.get(event);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.bindings.set(event, set);
+		}
+		set.add(cb);
+		return cb;
+	}
+	off(event, cb) {
+		this.bindings.get(event)?.delete(cb);
+	}
+	_trigger(event, payload, ref) {
+		const set = this.bindings.get(event);
+		if (!set) return;
+		for (const cb of set) try {
+			cb(payload, ref);
+		} catch (e) {
+			this.host._log("error", `channel handler threw for ${this.topic}/${event}`, e);
+		}
+	}
+	/** Called when a (new) socket is open. Re-establishes membership if needed. */
+	_rejoin() {
+		if (this.state === "joined" || this.state === "joining" || this.state === "leaving") return;
+		this.doJoin().catch(() => {});
+	}
+	/** Called when the socket goes down: the join is no longer valid; we'll rejoin on reconnect. */
+	_onSocketDown() {
+		if (this.state === "leaving" || this.state === "closed") return;
+		this.state = "closed";
+		this.joinRef = null;
+		this.joinPromise = null;
+	}
+};
+//#endregion
+//#region src/serializer.ts
+const phx = Phoenix.Serializer;
+/**
+* The wire serializer — the **installed** Phoenix `Serializer` (v2 text + binary frames),
+* wrapped to our `Serializer` interface so wire-compat tracks the `phoenix` package. Its
+* `encode`/`decode` are callback-style but synchronous, so we capture the result inline.
+*/
+const serializer = {
+	encode(msg) {
+		let out = "";
+		phx.encode(msg, (result) => {
+			out = result;
+		});
+		return out;
+	},
+	decode(raw) {
+		let out;
+		phx.decode(raw, (msg) => {
+			out = msg;
+		});
+		return out;
+	}
+};
+//#endregion
+//#region src/connection.ts
+const WS_OPEN = 1;
+const WS_CLOSE_NORMAL = 1e3;
+const DEFAULT_VSN = "2.0.0";
+const AUTH_TOKEN_PREFIX = "base64url.bearer.phx.";
+const DEFAULT_BACKOFF = [
+	10,
+	50,
+	100,
+	250,
+	500,
+	1e3,
+	2e3
+];
+const defaultReconnectAfterMs = (tries) => DEFAULT_BACKOFF[tries - 1] ?? 5e3;
+/**
+* Single-socket connection supervisor.
+*
+* Invariant (the whole point): **at most one socket is ever acted upon.** A new socket is
+* never created until the previous one's `close` is confirmed (healthy switch) or it has
+* been fenced and abandoned (dead socket). Three mechanics enforce it:
+*
+*  1. **Serialized reconcile** — every transition runs through one queue; the latest
+*     desired target always wins (rapid `connect`/`disconnect` coalesce).
+*  2. **Generation + live-identity guards** — every socket event checks it belongs to the
+*     current desired-epoch *and* the current socket; late events from a superseded or
+*     replaced socket are inert.
+*  3. **Verified teardown** — switching/closing awaits the real `close` event (with a
+*     force-fence timeout) before any new socket opens.
+*
+* No global/`window` coupling, so discarding a socket is clean — nothing to leak or
+* resurrect on tab visibility.
+*/
+var Connection = class {
+	WS;
+	serializer;
+	heartbeatIntervalMs;
+	requestTimeoutMs;
+	closeTimeoutMs;
+	reconnectAfterMs;
+	vsn;
+	_log;
+	desired = null;
+	live = null;
+	generation = 0;
+	state = {
+		status: "idle",
+		endpoint: null,
+		error: null,
+		since: now()
+	};
+	listeners = /* @__PURE__ */ new Set();
+	channels = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new Map();
+	refCounter = 0;
+	reconciling = false;
+	dirty = false;
+	reconnectAttempt = 0;
+	reconnectTimer = null;
+	closed = false;
+	constructor(options = {}) {
+		const WS = options.WebSocket ?? globalThis.WebSocket;
+		if (!WS) throw new ConnectionError("no WebSocket available — pass options.WebSocket (e.g. the `ws` package on older Node)");
+		this.WS = WS;
+		this.serializer = options.serializer ?? serializer;
+		this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? 15e3;
+		this.requestTimeoutMs = options.requestTimeoutMs ?? 1e4;
+		this.closeTimeoutMs = options.closeTimeoutMs ?? 2e3;
+		this.reconnectAfterMs = options.reconnectAfterMs ?? defaultReconnectAfterMs;
+		this.vsn = options.vsn ?? DEFAULT_VSN;
+		this._log = options.logger ?? (() => {});
+	}
+	getState() {
+		return this.state;
+	}
+	/** Observe connection state. Returns an unsubscribe fn. `getState`/state are stable
+	*  references between changes, so this is `useSyncExternalStore`-friendly. */
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	/** Declarative + idempotent. Sets the desired target and converges to it. Resolves when
+	*  this target reaches `connected`; rejects if a different target supersedes it. */
+	connect(target) {
+		if (this.closed) return Promise.reject(new ConnectionError("connection disposed"));
+		const key = targetKey(target);
+		if (this.desired && targetKey(this.desired) === key) return this.state.status === "connected" ? Promise.resolve() : this.waitForTarget(key);
+		this.desired = target;
+		this.bumpGeneration();
+		this.cancelReconnect();
+		this.reconcile();
+		return this.waitForTarget(key);
+	}
+	/** Tear down to `idle`. Resolves once fully closed. */
+	disconnect() {
+		if (this.closed || this.desired === null && this.live === null) return Promise.resolve();
+		this.desired = null;
+		this.bumpGeneration();
+		this.cancelReconnect();
+		this.reconcile();
+		if (this.state.status === "idle") return Promise.resolve();
+		return new Promise((resolve) => {
+			const off = this.subscribe((s) => {
+				if (s.status === "idle") {
+					off();
+					resolve();
+				}
+			});
+		});
+	}
+	/** Permanent dispose — closes the socket and stops everything. */
+	close() {
+		this.closed = true;
+		this.desired = null;
+		this.bumpGeneration();
+		this.cancelReconnect();
+		if (this.live) {
+			this.fence(this.live);
+			this.live = null;
+		}
+		this.flushPending(new ConnectionError("connection disposed"));
+		this.setState({
+			status: "idle",
+			endpoint: null,
+			error: null
+		});
+	}
+	/** Get-or-create the (single) channel for a topic. Joined now if the socket is open,
+	*  otherwise it joins automatically once a socket comes up. */
+	channel(topic, params = {}) {
+		let ch = this.channels.get(topic);
+		if (ch) return ch;
+		ch = new Channel(this, topic, params);
+		this.channels.set(topic, ch);
+		if (this._isOpen()) ch._rejoin();
+		return ch;
+	}
+	_makeRef() {
+		this.refCounter += 1;
+		return String(this.refCounter);
+	}
+	_isOpen() {
+		return !!this.live && this.live.opened && this.live.ws.readyState === WS_OPEN;
+	}
+	_send(msg) {
+		const live = this.live;
+		if (!live || !this._isOpen()) {
+			this._log("warn", `dropping ${msg.event} on ${msg.topic} — socket not open`);
+			return;
+		}
+		this.sendRaw(live, msg);
+	}
+	_request(msg, timeoutMs = this.requestTimeoutMs) {
+		return new Promise((resolve, reject) => {
+			const live = this.live;
+			if (!live || !this._isOpen()) {
+				reject(new ConnectionError("not connected"));
+				return;
+			}
+			const ref = msg.ref ?? this._makeRef();
+			const timer = setTimeout(() => {
+				this.pending.delete(ref);
+				resolve({
+					status: "timeout",
+					response: void 0
+				});
+			}, timeoutMs);
+			this.pending.set(ref, {
+				resolve,
+				reject,
+				timer
+			});
+			try {
+				this.sendRaw(live, {
+					...msg,
+					ref
+				});
+			} catch (e) {
+				clearTimeout(timer);
+				this.pending.delete(ref);
+				reject(e);
+			}
+		});
+	}
+	_removeChannel(topic) {
+		this.channels.delete(topic);
+	}
+	reconcile() {
+		this.dirty = true;
+		if (this.reconciling) return;
+		this.reconciling = true;
+		this.runReconcile();
+	}
+	async runReconcile() {
+		try {
+			while (this.dirty && !this.closed) {
+				this.dirty = false;
+				await this.step();
+			}
+		} finally {
+			this.reconciling = false;
+		}
+	}
+	async step() {
+		const desired = this.desired;
+		const live = this.live;
+		if (!desired && !live) {
+			this.setState({
+				status: "idle",
+				endpoint: null,
+				error: null
+			});
+			return;
+		}
+		if (!desired && live) {
+			await this.teardown(live);
+			this.dirty = true;
+			return;
+		}
+		if (desired && !live) {
+			await this.bringUp(desired);
+			return;
+		}
+		if (desired && live) {
+			if (targetKey(live.target) === targetKey(desired)) return;
+			await this.teardown(live);
+			this.dirty = true;
+		}
+	}
+	async bringUp(target) {
+		const gen = this.generation;
+		if (this.state.status !== "reconnecting") this.setState({
+			status: "connecting",
+			endpoint: target.url,
+			error: null
+		});
+		let token;
+		let params;
+		try {
+			token = target.token ? await target.token() : void 0;
+			if (gen !== this.generation) return;
+			params = await resolveParams(target.params);
+			if (gen !== this.generation) return;
+		} catch (e) {
+			if (gen === this.generation) this.failTarget(e);
+			return;
+		}
+		const url = buildUrl(target.url, params, this.vsn);
+		let ws;
+		try {
+			ws = token ? new this.WS(url, ["phoenix", AUTH_TOKEN_PREFIX + base64NoPad(token)]) : new this.WS(url);
+		} catch (e) {
+			if (gen === this.generation) this.failTarget(e);
+			return;
+		}
+		const live = {
+			ws,
+			generation: gen,
+			target,
+			heartbeatTimer: null,
+			pendingHeartbeatRef: null,
+			opened: false
+		};
+		this.live = live;
+		ws.onopen = () => {
+			if (this.generation === gen && this.live === live) this.onOpen(live);
+		};
+		ws.onmessage = (ev) => {
+			if (this.generation === gen && this.live === live) this.onMessage(live, ev.data);
+		};
+		ws.onerror = (ev) => {
+			if (this.generation === gen && this.live === live) this._log("warn", "socket error", ev);
+		};
+		ws.onclose = () => {
+			if (this.generation === gen && this.live === live) this.onUnexpectedClose(live);
+		};
+	}
+	onOpen(live) {
+		live.opened = true;
+		this.reconnectAttempt = 0;
+		this.startHeartbeat(live);
+		for (const ch of this.channels.values()) ch._rejoin();
+		const verify = live.target.verify;
+		if (!verify) {
+			this.setConnected(live);
+			return;
+		}
+		const gen = live.generation;
+		verify(this.verifyHandle()).then(() => {
+			if (this.generation === gen && this.live === live) this.setConnected(live);
+		}).catch((e) => {
+			if (this.generation === gen && this.live === live) {
+				this._log("warn", "verify failed", e);
+				this.replaceDead(live, asError$1(e));
+			}
+		});
+	}
+	verifyHandle() {
+		return { channel: (topic, params) => this.channel(topic, params ?? {}) };
+	}
+	setConnected(live) {
+		this.setState({
+			status: "connected",
+			endpoint: live.target.url,
+			error: null
+		});
+	}
+	async teardown(live) {
+		this.setState({ status: "closing" });
+		this.clearHeartbeat(live);
+		const ws = live.ws;
+		await new Promise((resolve) => {
+			let done = false;
+			const finish = () => {
+				if (done) return;
+				done = true;
+				clearTimeout(forceTimer);
+				resolve();
+			};
+			const forceTimer = setTimeout(() => {
+				detach(ws);
+				finish();
+			}, this.closeTimeoutMs);
+			ws.onopen = null;
+			ws.onmessage = null;
+			ws.onerror = null;
+			ws.onclose = () => finish();
+			try {
+				ws.close(WS_CLOSE_NORMAL);
+			} catch {
+				finish();
+			}
+		});
+		if (this.live === live) this.live = null;
+		this.afterSocketGone(new ConnectionError("connection closed"));
+	}
+	replaceDead(live, err) {
+		this._log("warn", "socket dead — fencing", err);
+		this.fence(live);
+		if (this.live === live) this.live = null;
+		this.afterSocketGone(err);
+		if (this.desired && targetKey(this.desired) === targetKey(live.target)) this.scheduleReconnect();
+		else this.reconcile();
+	}
+	onUnexpectedClose(live) {
+		this.clearHeartbeat(live);
+		if (this.live === live) this.live = null;
+		this.afterSocketGone(new ConnectionError("connection lost"));
+		if (this.desired && targetKey(this.desired) === targetKey(live.target)) this.scheduleReconnect();
+		else this.reconcile();
+	}
+	/** Detach handlers and best-effort close, without awaiting (the socket may never close). */
+	fence(live) {
+		this.clearHeartbeat(live);
+		detach(live.ws);
+		try {
+			live.ws.close(WS_CLOSE_NORMAL);
+		} catch {}
+	}
+	afterSocketGone(err) {
+		this.flushPending(err);
+		for (const ch of this.channels.values()) ch._onSocketDown();
+	}
+	scheduleReconnect() {
+		if (this.closed || !this.desired) return;
+		this.reconnectAttempt += 1;
+		const delay = this.reconnectAfterMs(this.reconnectAttempt);
+		this.setState({ status: "reconnecting" });
+		this.cancelReconnect();
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = null;
+			this.reconcile();
+		}, delay);
+	}
+	cancelReconnect() {
+		if (this.reconnectTimer) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = null;
+		}
+	}
+	startHeartbeat(live) {
+		this.clearHeartbeat(live);
+		live.heartbeatTimer = setTimeout(() => this.sendHeartbeat(live), this.heartbeatIntervalMs);
+	}
+	sendHeartbeat(live) {
+		if (this.live !== live || !this._isOpen()) return;
+		if (live.pendingHeartbeatRef) {
+			this.replaceDead(live, new ConnectionError("heartbeat timeout"));
+			return;
+		}
+		live.pendingHeartbeatRef = this._makeRef();
+		this.sendRaw(live, {
+			join_ref: null,
+			ref: live.pendingHeartbeatRef,
+			topic: "phoenix",
+			event: "heartbeat",
+			payload: {}
+		});
+		live.heartbeatTimer = setTimeout(() => this.sendHeartbeat(live), this.heartbeatIntervalMs);
+	}
+	clearHeartbeat(live) {
+		if (live.heartbeatTimer) {
+			clearTimeout(live.heartbeatTimer);
+			live.heartbeatTimer = null;
+		}
+		live.pendingHeartbeatRef = null;
+	}
+	onMessage(live, data) {
+		let msg;
+		try {
+			msg = this.serializer.decode(data);
+		} catch (e) {
+			this._log("error", "decode failed", e);
+			return;
+		}
+		if (msg.ref && msg.ref === live.pendingHeartbeatRef && msg.topic === "phoenix") {
+			live.pendingHeartbeatRef = null;
+			return;
+		}
+		if (msg.event === "phx_reply" && msg.ref) {
+			const p = this.pending.get(msg.ref);
+			if (p) {
+				this.pending.delete(msg.ref);
+				clearTimeout(p.timer);
+				const payload = msg.payload;
+				p.resolve({
+					status: payload?.status ?? "ok",
+					response: payload?.response
+				});
+				return;
+			}
+		}
+		const ch = this.channels.get(msg.topic);
+		if (ch) ch._trigger(msg.event, msg.payload, msg.ref);
+	}
+	sendRaw(live, msg) {
+		live.ws.send(this.serializer.encode(msg));
+	}
+	flushPending(err) {
+		for (const p of this.pending.values()) {
+			clearTimeout(p.timer);
+			p.reject(err);
+		}
+		this.pending.clear();
+	}
+	setState(partial) {
+		const merged = {
+			...this.state,
+			...partial
+		};
+		if (!(merged.status !== this.state.status || merged.endpoint !== this.state.endpoint || merged.error !== this.state.error)) return;
+		this.state = {
+			...merged,
+			since: now()
+		};
+		for (const l of this.listeners) try {
+			l(this.state);
+		} catch (e) {
+			this._log("error", "state listener threw", e);
+		}
+	}
+	failTarget(e) {
+		this.setState({
+			status: "error",
+			error: asError$1(e)
+		});
+	}
+	desiredKey() {
+		return this.desired ? targetKey(this.desired) : "\0idle";
+	}
+	waitForTarget(key) {
+		return new Promise((resolve, reject) => {
+			const check = (s) => {
+				if (this.desiredKey() !== key) {
+					reject(new SupersededError());
+					return true;
+				}
+				if (s.status === "connected" && this.live && targetKey(this.live.target) === key) {
+					resolve();
+					return true;
+				}
+				if (s.status === "error" && s.error) {
+					reject(s.error);
+					return true;
+				}
+				return false;
+			};
+			if (check(this.state)) return;
+			const off = this.subscribe((s) => {
+				if (check(s)) off();
+			});
+		});
+	}
+	bumpGeneration() {
+		this.generation += 1;
+	}
+};
+function now() {
+	return Date.now();
+}
+function asError$1(e) {
+	return e instanceof Error ? e : new ConnectionError(String(e));
+}
+/** Detach all handlers so an abandoned socket can never call back into us. */
+function detach(ws) {
+	ws.onopen = null;
+	ws.onmessage = null;
+	ws.onerror = null;
+	ws.onclose = null;
+}
+/** Target identity = url + plain params only. `token`/`verify` (functions, often fresh per
+*  render) are *how* to connect, never *what* — so they don't trigger spurious reconnects. */
+function targetKey(t) {
+	const p = t.params && typeof t.params !== "function" ? stableStringify(t.params) : "";
+	return t.url + "|" + p;
+}
+function stableStringify(o) {
+	const keys = Object.keys(o).sort();
+	const out = {};
+	for (const k of keys) out[k] = o[k];
+	return JSON.stringify(out);
+}
+async function resolveParams(p) {
+	if (!p) return {};
+	return typeof p === "function" ? await p() : p;
+}
+function buildUrl(base, params, vsn) {
+	let url = base.replace(/\/$/, "");
+	if (!url.endsWith("/websocket")) url += "/websocket";
+	const q = new URLSearchParams();
+	q.set("vsn", vsn);
+	for (const [k, v] of Object.entries(params)) {
+		if (v === void 0 || v === null) continue;
+		q.set(k, typeof v === "string" ? v : JSON.stringify(v));
+	}
+	return `${url}?${q.toString()}`;
+}
+function base64NoPad(token) {
+	return (typeof btoa === "function" ? btoa(token) : globalThis.Buffer.from(token, "utf-8").toString("base64")).replace(/=/g, "");
+}
+//#endregion
+//#region src/address.ts
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* Split a `[realm:]name` address into `{ realm, name }`; default realm `synapse`.
+* Only a bare-identifier prefix counts as a realm, so a synapse name with `/` and no realm
+* passes through unchanged. Mirrors the Python client.
+*
+*   "camera/capture"          -> { realm: "synapse",   name: "camera/capture" }
+*   "rosbridge:/add_two_ints" -> { realm: "rosbridge", name: "/add_two_ints" }
+*/
+function address(addr) {
+	const i = addr.indexOf(":");
+	if (i > 0) {
+		const realm = addr.slice(0, i);
+		if (IDENTIFIER.test(realm)) return {
+			realm,
+			name: addr.slice(i + 1)
+		};
+	}
+	return {
+		realm: "synapse",
+		name: addr
+	};
+}
+//#endregion
+//#region src/node.ts
+/**
+* A Synapse bus node. Wraps the single-socket {@link Connection} and adds the bus verbs —
+* `call`, `callStream`, `subscribe`, `publish`, `service` — mirroring the Python `Node`.
+* Any node can both consume and provide (a browser can publish joystick state *and* expose
+* a service the robot calls into).
+*/
+var Synapse = class {
+	connection;
+	identity;
+	tasks = /* @__PURE__ */ new Map();
+	consumerChannels = /* @__PURE__ */ new Map();
+	pubsubChannels = /* @__PURE__ */ new Map();
+	pubsubSubs = /* @__PURE__ */ new Map();
+	stateHandles = /* @__PURE__ */ new Map();
+	catalogChannelP = null;
+	catalogWatchers = /* @__PURE__ */ new Set();
+	systemEnabled;
+	systemChannel = null;
+	role = null;
+	projectId = null;
+	systemError = null;
+	systemRequest = {};
+	systemState;
+	systemListeners = /* @__PURE__ */ new Set();
+	systemGen = 0;
+	constructor(options = {}) {
+		this.connection = new Connection(options);
+		this.identity = {
+			user_id: options.userId ?? randomId(),
+			type: options.role ?? "agent"
+		};
+		if (options.name) this.identity.user_name = options.name;
+		this.systemEnabled = options.system !== false;
+		this.systemState = this.computeSystem();
+		this.connection.subscribe((cs) => this.onTransport(cs));
+	}
+	/**
+	* Connect (and negotiate the system session). Identity params are merged in. Resolves when
+	* **ready** — transport connected *and* a server role assigned (unless `system: false`,
+	* where ready just means connected). Declarative + idempotent. To request control, pass
+	* `{ project, controller: true }`.
+	*/
+	async connect(target) {
+		const req = {
+			project: target.project,
+			controller: target.controller
+		};
+		if (this.systemChannel && (req.project !== this.systemRequest.project || req.controller !== this.systemRequest.controller)) {
+			this.systemChannel.leave();
+			this.systemChannel = null;
+		}
+		this.systemRequest = req;
+		await this.connection.connect({
+			url: target.url,
+			params: this.withIdentity(target.params),
+			token: target.token,
+			verify: target.verify
+		});
+		if (this.systemEnabled) await this.whenReady();
+	}
+	disconnect() {
+		return this.connection.disconnect();
+	}
+	close() {
+		this.connection.close();
+	}
+	getState() {
+		return this.connection.getState();
+	}
+	/** Observe connection state — `useSyncExternalStore`-friendly. */
+	subscribeState(listener) {
+		return this.connection.subscribe(listener);
+	}
+	/** The full readiness — `{ status, role, projectId, ready, error }`. */
+	getSystem() {
+		return this.systemState;
+	}
+	/** Observe readiness — `useSyncExternalStore`-friendly. The connection indicator binds
+	*  to `{ status, role }` (transport status + server role) and `ready` is the gate. */
+	subscribeSystem(listener) {
+		this.systemListeners.add(listener);
+		return () => this.systemListeners.delete(listener);
+	}
+	/** Resolves once **ready** (negotiated + role assigned), or rejects after `timeoutMs`. */
+	whenReady(timeoutMs = 1e4) {
+		if (this.systemState.ready) return Promise.resolve();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				off();
+				reject(new BusError({
+					code: BusErrorCode.NotConnected,
+					message: "timed out waiting for ready"
+				}));
+			}, timeoutMs);
+			const off = this.subscribeSystem((s) => {
+				if (s.ready) {
+					clearTimeout(timer);
+					off();
+					resolve();
+				}
+			});
+		});
+	}
+	/** Activate a project (request control of it). Role updates arrive live via the session. */
+	async activateProject(projectId) {
+		const reply = await this.requireSystem().request("activate_project", { project_id: projectId });
+		if (reply.status !== "ok") throw new BusError(reply.response);
+	}
+	/** Step back to viewer for the active project. */
+	async deactivateProject() {
+		const reply = await this.requireSystem().request("deactivate_project", {});
+		if (reply.status !== "ok") throw new BusError(reply.response);
+	}
+	/** Resolves once the transport is connected — used internally before channel ops (channels
+	*  need the socket, not a role). */
+	awaitConnected(timeoutMs = 1e4) {
+		if (this.connection.getState().status === "connected") return Promise.resolve();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				off();
+				reject(new BusError({
+					code: BusErrorCode.NotConnected,
+					message: "timed out waiting for connection"
+				}));
+			}, timeoutMs);
+			const off = this.connection.subscribe((s) => {
+				if (s.status === "connected") {
+					clearTimeout(timer);
+					off();
+					resolve();
+				}
+			});
+		});
+	}
+	onTransport(cs) {
+		if (cs.status === "connected") {
+			if (this.systemEnabled) this.enterSystem();
+		} else {
+			this.role = null;
+			this.projectId = null;
+			if (cs.status !== "error") this.systemError = null;
+			this.systemGen++;
+		}
+		this.emitSystem();
+	}
+	async enterSystem() {
+		const gen = ++this.systemGen;
+		let ch = this.systemChannel;
+		if (!ch) {
+			ch = this.connection.channel("synapse:system", this.systemPayload());
+			ch.on("session_state", (p) => this.onSessionState(p));
+			ch.on("promoted", () => this.setRole("controller"));
+			ch.on("demoted", () => this.setRole("viewer"));
+			this.systemChannel = ch;
+		}
+		try {
+			const reply = await ch.join();
+			if (gen !== this.systemGen) return;
+			this.role = normalizeRole(reply?.role) ?? this.role;
+			if (typeof reply?.project_id === "string") this.projectId = reply.project_id;
+			this.systemError = null;
+			this.emitSystem();
+		} catch (e) {
+			if (gen !== this.systemGen) return;
+			this.role = null;
+			this.systemError = asError(e);
+			this.emitSystem();
+		}
+	}
+	onSessionState(p) {
+		const r = normalizeRole(p.role);
+		if (r) this.role = r;
+		if (typeof p.project_id === "string") this.projectId = p.project_id;
+		this.emitSystem();
+	}
+	setRole(role) {
+		this.role = role;
+		this.emitSystem();
+	}
+	requireSystem() {
+		if (!this.systemChannel) throw new BusError({
+			code: BusErrorCode.NotConnected,
+			message: "system channel not joined"
+		});
+		return this.systemChannel;
+	}
+	systemPayload() {
+		const p = {};
+		if (this.systemRequest.project) p.project_id = this.systemRequest.project;
+		if (this.systemRequest.controller) p.role = "controller";
+		return p;
+	}
+	computeSystem() {
+		const cs = this.connection.getState();
+		const ready = cs.status === "connected" && (!this.systemEnabled || this.role !== null);
+		return {
+			status: cs.status,
+			role: this.role,
+			projectId: this.projectId,
+			ready,
+			error: this.systemError ?? cs.error
+		};
+	}
+	emitSystem() {
+		const next = this.computeSystem();
+		const prev = this.systemState;
+		if (next.status === prev.status && next.role === prev.role && next.projectId === prev.projectId && next.ready === prev.ready && next.error === prev.error) return;
+		this.systemState = next;
+		for (const l of this.systemListeners) try {
+			l(next);
+		} catch (e) {
+			this.connection._log("error", "system listener threw", e);
+		}
+	}
+	async call(service, input = {}, opts = {}) {
+		const { realm, name } = address(service);
+		const ch = await this.consumerChannel(realm, name);
+		const ack = await ch.request("call", input, opts.timeout);
+		if (ack.status !== "ok") throw new BusError(ack.response);
+		const taskId = ack.response?.task_id;
+		if (!taskId) throw new BusError({
+			code: BusErrorCode.BadAck,
+			message: "service did not return a task_id"
+		});
+		return await new Promise((resolve, reject) => {
+			let idle;
+			const settle = () => {
+				this.tasks.delete(taskId);
+				if (idle) clearTimeout(idle);
+			};
+			const armIdle = () => {
+				if (!opts.idleTimeout) return;
+				if (idle) clearTimeout(idle);
+				idle = setTimeout(() => {
+					settle();
+					ch.push("cancel", { task_id: taskId });
+					reject(new BusError({
+						code: BusErrorCode.Timeout,
+						message: `no progress for ${opts.idleTimeout}ms`
+					}));
+				}, opts.idleTimeout);
+			};
+			this.tasks.set(taskId, {
+				onUpdate: (f) => {
+					armIdle();
+					opts.onUpdate?.(f);
+				},
+				onResult: (f) => {
+					settle();
+					resolve(f.result ?? f);
+				},
+				onError: (f) => {
+					settle();
+					reject(new BusError(f.error ?? f));
+				}
+			});
+			armIdle();
+			const signal = opts.signal;
+			if (signal) {
+				const onAbort = () => {
+					settle();
+					ch.push("cancel", { task_id: taskId });
+					reject(abortError(signal));
+				};
+				if (signal.aborted) onAbort();
+				else signal.addEventListener("abort", onAbort, { once: true });
+			}
+		});
+	}
+	/** Call as a loop: yields each `update` then the terminal `result`. Breaking cancels. */
+	async *callStream(service, input = {}, opts = {}) {
+		const { realm, name } = address(service);
+		const ch = await this.consumerChannel(realm, name);
+		const ack = await ch.request("call", input, opts.timeout);
+		if (ack.status !== "ok") throw new BusError(ack.response);
+		const taskId = ack.response?.task_id;
+		if (!taskId) throw new BusError({
+			code: BusErrorCode.BadAck,
+			message: "service did not return a task_id"
+		});
+		const queue = [];
+		let wake = null;
+		let done = false;
+		let err = null;
+		let idle;
+		const bump = () => {
+			wake?.();
+			wake = null;
+		};
+		const clearIdle = () => {
+			if (idle) clearTimeout(idle);
+		};
+		const armIdle = () => {
+			if (!opts.idleTimeout) return;
+			clearIdle();
+			idle = setTimeout(() => {
+				err = new BusError({
+					code: BusErrorCode.Timeout,
+					message: `no progress for ${opts.idleTimeout}ms`
+				});
+				done = true;
+				bump();
+			}, opts.idleTimeout);
+		};
+		this.tasks.set(taskId, {
+			onUpdate: (f) => {
+				armIdle();
+				queue.push({
+					type: "update",
+					data: f
+				});
+				bump();
+			},
+			onResult: (f) => {
+				clearIdle();
+				queue.push({
+					type: "result",
+					data: f
+				});
+				done = true;
+				bump();
+			},
+			onError: (f) => {
+				clearIdle();
+				err = new BusError(f.error ?? f);
+				done = true;
+				bump();
+			}
+		});
+		armIdle();
+		try {
+			while (true) {
+				if (queue.length === 0 && !done && !err) await new Promise((r) => wake = r);
+				while (queue.length) {
+					const ev = queue.shift();
+					yield ev;
+					if (ev.type === "result") return;
+				}
+				if (err) throw err;
+				if (done) return;
+			}
+		} finally {
+			clearIdle();
+			this.tasks.delete(taskId);
+			ch.push("cancel", { task_id: taskId });
+		}
+	}
+	async publish(resource, data = {}, opts = {}) {
+		const { realm, name } = address(resource);
+		(await this.ensurePubsub(realm, name, opts.opts)).push("publish", data);
+	}
+	subscribe(resource, cbOrOpts, maybeOpts) {
+		if (typeof cbOrOpts === "function") return this.subscribePush(resource, cbOrOpts, maybeOpts);
+		return this.subscribePull(resource, cbOrOpts);
+	}
+	/** A render-loop-friendly latest-value holder for high-rate topics (three.js / `useFrame`). */
+	latest(resource, opts = {}) {
+		return new LatestValue((cb) => this.subscribePush(resource, cb, opts));
+	}
+	/**
+	* Open a live, always-current local mirror of a `synapse:state:<name>` resource — a
+	* shared key→value map that converges across nodes. `handle.value` is kept up to date
+	* from the initial sync and each diff; write with `handle.put`/`handle.delete`. Cached
+	* per resource (repeated calls share one mirror).
+	*/
+	openState(resource) {
+		const { realm, name } = address(resource);
+		const topic = `${realm}:state:${name}`;
+		let p = this.stateHandles.get(topic);
+		if (!p) {
+			p = this.doOpenState(resource, topic);
+			this.stateHandles.set(topic, p);
+		}
+		return p;
+	}
+	async doOpenState(resource, topic) {
+		await this.awaitConnected();
+		const ch = this.connection.channel(topic, {});
+		const handle = new StateHandle(resource, ch);
+		ch.on("state_diff", (d) => handle._onDiff(d));
+		const sync = await ch.join();
+		handle._applySync(sync);
+		return handle;
+	}
+	/** Capability cards of every registered service. */
+	async listServices() {
+		const reply = await (await this.catalog()).request("list", {});
+		if (reply.status !== "ok") throw new BusError(reply.response);
+		return reply.response.services ?? [];
+	}
+	/** One service's capability card (throws `BusError` if unknown). */
+	async describe(service) {
+		const reply = await (await this.catalog()).request("info", { service });
+		if (reply.status !== "ok") throw new BusError(reply.response);
+		return reply.response;
+	}
+	/** State resources currently registered on the bus. */
+	async listResources() {
+		const reply = await (await this.catalog()).request("list", {});
+		if (reply.status !== "ok") throw new BusError(reply.response);
+		return reply.response.resources ?? [];
+	}
+	watchCatalog(callback) {
+		if (callback) {
+			this.catalogWatchers.add(callback);
+			this.catalog().catch((e) => this.connection._log("warn", "catalog join failed", e));
+			return { unsubscribe: () => void this.catalogWatchers.delete(callback) };
+		}
+		return this.watchCatalogIterator();
+	}
+	watchCatalogIterator() {
+		const self = this;
+		return { async *[Symbol.asyncIterator]() {
+			const queue = [];
+			let wake = null;
+			const cb = (c) => {
+				queue.push(c);
+				wake?.();
+				wake = null;
+			};
+			self.catalogWatchers.add(cb);
+			try {
+				await self.catalog();
+				while (true) {
+					if (queue.length === 0) await new Promise((r) => wake = r);
+					while (queue.length) yield queue.shift();
+				}
+			} finally {
+				self.catalogWatchers.delete(cb);
+			}
+		} };
+	}
+	catalog() {
+		if (!this.catalogChannelP) this.catalogChannelP = this.openCatalog();
+		return this.catalogChannelP;
+	}
+	async openCatalog() {
+		await this.awaitConnected();
+		const ch = this.connection.channel("synapse:catalog", {});
+		ch.on("change", (c) => {
+			for (const w of this.catalogWatchers) w(c);
+		});
+		await ch.join();
+		return ch;
+	}
+	service(name, handler, card = {}) {
+		const { realm, name: svc } = address(name);
+		const topic = `${realm}:service:${svc}`;
+		const ch = this.connection.channel(topic, {
+			role: "provider",
+			card
+		});
+		const cancels = /* @__PURE__ */ new Map();
+		ch.on("call", (frame) => void this.runProvider(ch, handler, frame, cancels));
+		ch.on("cancel", (frame) => {
+			const id = frame.task_id;
+			if (id) cancels.get(id)?.abort();
+		});
+		this.awaitConnected().then(() => ch.join()).catch((e) => this.connection._log("warn", `provider join failed for ${topic}`, e));
+		return { unregister: () => void ch.leave() };
+	}
+	async runProvider(ch, handler, frame, cancels) {
+		const taskId = frame.task_id;
+		const ac = new AbortController();
+		cancels.set(taskId, ac);
+		const ctx = {
+			update: (data) => ch.push("update", {
+				task_id: taskId,
+				...data
+			}),
+			signal: ac.signal,
+			taskId
+		};
+		try {
+			const result = await handler(frame.input ?? {}, ctx);
+			ch.push("result", {
+				task_id: taskId,
+				result
+			});
+		} catch (e) {
+			ch.push("error", {
+				task_id: taskId,
+				error: {
+					code: BusErrorCode.ProviderError,
+					message: errMessage(e)
+				}
+			});
+		} finally {
+			cancels.delete(taskId);
+		}
+	}
+	withIdentity(p) {
+		const id = this.identity;
+		if (typeof p === "function") {
+			const fn = p;
+			return async () => ({
+				...id,
+				...await fn()
+			});
+		}
+		return {
+			...id,
+			...p ?? {}
+		};
+	}
+	async consumerChannel(realm, name) {
+		const topic = `${realm}:service:${name}`;
+		let ch = this.consumerChannels.get(topic);
+		if (!ch) {
+			ch = this.connection.channel(topic, { role: "consumer" });
+			ch.on("result", (f) => this.routeTask("result", f));
+			ch.on("update", (f) => this.routeTask("update", f));
+			ch.on("error", (f) => this.routeTask("error", f));
+			this.consumerChannels.set(topic, ch);
+		}
+		await this.awaitConnected();
+		await ch.join();
+		return ch;
+	}
+	routeTask(kind, frame) {
+		const taskId = frame.task_id;
+		if (!taskId) return;
+		const w = this.tasks.get(taskId);
+		if (!w) return;
+		if (kind === "update") w.onUpdate?.(frame);
+		else if (kind === "result") w.onResult(frame);
+		else w.onError(frame);
+	}
+	subsFor(topic) {
+		let s = this.pubsubSubs.get(topic);
+		if (!s) {
+			s = /* @__PURE__ */ new Set();
+			this.pubsubSubs.set(topic, s);
+		}
+		return s;
+	}
+	async ensurePubsub(realm, name, joinOpts) {
+		const topic = `${realm}:pubsub:${name}`;
+		let ch = this.pubsubChannels.get(topic);
+		if (!ch) {
+			ch = this.connection.channel(topic, joinOpts ?? {});
+			const subs = this.subsFor(topic);
+			ch.on("message", (m) => {
+				for (const f of subs) f(m);
+			});
+			this.pubsubChannels.set(topic, ch);
+		}
+		await this.awaitConnected();
+		await ch.join();
+		return ch;
+	}
+	subscribePush(resource, cb, opts) {
+		const { realm, name } = address(resource);
+		const topic = `${realm}:pubsub:${name}`;
+		const subs = this.subsFor(topic);
+		subs.add(cb);
+		this.ensurePubsub(realm, name, opts?.opts).catch((e) => this.connection._log("warn", `subscribe failed for ${topic}`, e));
+		return { unsubscribe: () => void subs.delete(cb) };
+	}
+	subscribePull(resource, opts) {
+		const self = this;
+		const { realm, name } = address(resource);
+		const topic = `${realm}:pubsub:${name}`;
+		return { async *[Symbol.asyncIterator]() {
+			const queue = [];
+			let wake = null;
+			const cb = (m) => {
+				queue.push(m);
+				wake?.();
+				wake = null;
+			};
+			const subs = self.subsFor(topic);
+			subs.add(cb);
+			try {
+				await self.ensurePubsub(realm, name, opts?.opts);
+				while (true) {
+					if (queue.length === 0) await new Promise((r) => wake = r);
+					while (queue.length) yield queue.shift();
+				}
+			} finally {
+				subs.delete(cb);
+			}
+		} };
+	}
+};
+/**
+* Latest-value holder for high-frequency topics. Read `.get()` inside a three.js / r3f
+* `useFrame` loop (non-reactive) and mutate the scene directly — React never re-renders.
+*/
+var LatestValue = class {
+	value = void 0;
+	listeners = /* @__PURE__ */ new Set();
+	sub;
+	constructor(subscribe) {
+		this.sub = subscribe((m) => {
+			this.value = m;
+			for (const l of this.listeners) l(m);
+		});
+	}
+	get() {
+		return this.value;
+	}
+	onChange(cb) {
+		this.listeners.add(cb);
+		return () => void this.listeners.delete(cb);
+	}
+	close() {
+		this.sub.unsubscribe();
+		this.listeners.clear();
+	}
+};
+/**
+* A live local mirror of a `synapse:state:<name>` resource. `value` is kept current from the
+* initial `state_sync` and each `state_diff` (absolute, version-ordered); a version gap
+* triggers an automatic `resync`. Writes (`put`/`delete`) are server-confirmed and come back
+* as a diff (self-included). `value` is replaced (new reference) on each change, so it binds
+* cleanly to `useSyncExternalStore` / reads cleanly in a `useFrame` loop.
+*/
+var StateHandle = class {
+	resource;
+	ch;
+	_value = {};
+	_version = 0;
+	listeners = /* @__PURE__ */ new Set();
+	resyncing = false;
+	constructor(resource, ch) {
+		this.resource = resource;
+		this.ch = ch;
+	}
+	/** The current converged map (new reference on every change). */
+	get value() {
+		return this._value;
+	}
+	/** The version of the last applied op. */
+	get version() {
+		return this._version;
+	}
+	async put(key, value) {
+		const reply = await this.ch.request("put", {
+			key,
+			value
+		});
+		if (reply.status !== "ok") throw new BusError(reply.response);
+	}
+	async delete(key) {
+		const reply = await this.ch.request("delete", { key });
+		if (reply.status !== "ok") throw new BusError(reply.response);
+	}
+	/** Observe each applied change: `(value, diff) => …`. Returns unsubscribe. */
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => void this.listeners.delete(listener);
+	}
+	/** Force a full re-sync from the server. */
+	async resync() {
+		if (this.resyncing) return;
+		this.resyncing = true;
+		try {
+			const reply = await this.ch.request("resync", {});
+			if (reply.status === "ok") this._applySync(reply.response);
+		} finally {
+			this.resyncing = false;
+		}
+	}
+	close() {
+		this.listeners.clear();
+		this.ch.leave();
+	}
+	_applySync(sync) {
+		this._value = { ...sync.state ?? {} };
+		this._version = sync.version ?? 0;
+		this.emit({
+			changed: this._value,
+			removed: [],
+			version: this._version
+		});
+	}
+	_onDiff(diff) {
+		const v = diff.version;
+		if (typeof v === "number" && v !== this._version + 1) {
+			this.resync();
+			return;
+		}
+		const next = { ...this._value };
+		for (const [k, val] of Object.entries(diff.changed ?? {})) next[k] = val;
+		for (const k of diff.removed ?? []) delete next[k];
+		this._value = next;
+		if (typeof v === "number") this._version = v;
+		this.emit(diff);
+	}
+	emit(diff) {
+		for (const l of this.listeners) try {
+			l(this._value, diff);
+		} catch {}
+	}
+};
+function randomId() {
+	const c = globalThis.crypto;
+	return c?.randomUUID ? c.randomUUID() : `node-${Math.random().toString(36).slice(2, 10)}`;
+}
+function errMessage(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+function abortError(signal) {
+	const reason = signal.reason;
+	return reason instanceof Error ? reason : new BusError({
+		code: BusErrorCode.Cancelled,
+		message: "call aborted"
+	});
+}
+function asError(e) {
+	return e instanceof Error ? e : new BusError({ message: String(e) });
+}
+/** Accept any non-empty string role (roles are open-ended), else null. */
+function normalizeRole(r) {
+	return typeof r === "string" && r.length > 0 ? r : null;
+}
+//#endregion
+export { Connection as a, BusError as c, ConnectionError as d, SupersededError as f, address as i, BusErrorCode as l, StateHandle as n, serializer as o, TimeoutError as p, Synapse as r, Channel as s, LatestValue as t, ChannelError as u };