@voltro/plugin-presence 0.87.0 → 0.88.0

package/dist/errors.js

@@ -1,5 +1,4 @@
 import { Schema as e } from "effect";
-//#region src/errors.ts
+// src/errors.ts
 var t = class extends e.TaggedError()("PresenceKeyMissing", { channel: e.String }) {}, n = class extends e.TaggedError()("PresenceStoreUnavailable", {}) {};
-//#endregion
 export { t as PresenceKeyMissing, n as PresenceStoreUnavailable };

package/dist/index.d.ts

@@ -35,6 +35,9 @@ export declare interface AttachPresenceBusOptions {
      */
     readonly onRosterChanged?: (() => void) | undefined;
     readonly now?: () => number;
+    /** Called when binding settles: acquired, local-only, or failed. Pending
+     * acquisition and a closed handle never report a usable transport. */
+    readonly onTransportSettled?: (connected: boolean, cause?: unknown) => void;
 }
 
 /**
@@ -51,7 +54,7 @@ export declare const PRESENCE_BROADCAST_CHANNEL = "voltro:presence";
 export declare interface PresenceBusHandle {
     readonly tracker: PresenceTracker;
     /**
-     * Whether a cross-instance transport is attached.
+     * Whether the transport's subscription has been acquired and is still owned.
      *
      * Exposed so the plugin can WARN at boot. Without one every replica keeps a
      * correct roster of its own clients and nothing errors — which is why the

package/dist/index.js

@@ -4,63 +4,74 @@ import { PresenceKeyMissing as r, PresenceStoreUnavailable as i } from "./errors
 import { BASE_NAME as a, heartbeatDescriptor as o, leaveDescriptor as s, listDescriptor as c, presenceRoster as l, presenceRpcClientImports as u } from "./rpc.js";
 import { Effect as d } from "effect";
 import { definePlugin as f, pluginInstanceName as p, publishReactivity as m } from "@voltro/protocol";
-//#region src/index.ts
+// src/index.ts
 var h = a, g = (e = {}) => {
 	if (e.timeoutMs !== void 0 && e.timeoutMs < 1e3) throw Error(`presencePlugin: \`timeoutMs\` is ${e.timeoutMs}, which expires every member before it can heartbeat again.
   A member is online for \`timeoutMs\` after its last heartbeat, and \`usePresence\` beats every 15s by default — so this must be LARGER than your client's
   \`heartbeatMs\`, comfortably. The default pair is 30s server / 15s client.
   There is no "never expire" spelling: omit \`timeoutMs\` for the default.`);
-	let t, a = e.timeoutMs ?? 3e4, g = Math.max(1e3, Math.floor(e.sweepIntervalMs ?? a / 3)), _ = p({
+	let t = e.timeoutMs ?? 3e4, a = Math.max(1e3, Math.floor(e.sweepIntervalMs ?? t / 3)), g = p({
 		base: h,
 		alias: e.alias,
 		instance: e.name
-	}), v, y, b = !1, x = (e) => {
+	}), _, v, y = () => {
+		let e = v ?? _;
+		_ = void 0, e !== void 0 && (v = e, e.detach(), v = void 0);
+	}, b, x = !1, S, C = 0, w = !1, T = !1, E, D, O, k = () => {
+		let e = D;
+		if (x) {
+			if (e === void 0) {
+				let e = _ === void 0 ? "awaiting-binding" : T ? "connecting" : void 0;
+				e !== void 0 && E !== `${C}:${e}` && (E = `${C}:${e}`, S?.info("presence transport", { state: e }));
+			} else e.generation === C && e !== O && (O = e, S?.info("presence transport", { crossInstance: e.connected }), !e.connected && (e.hasProvider ? S?.warn("presence: could not subscribe — this instance will only see its own members", { cause: e.cause }) : S?.warn("presence: no broadcast provider — each replica sees only the clients CONNECTED TO IT. Correct for a single instance; on more than one, every screen shows a fraction of the room and nothing reports it. Add @voltro/plugin-broadcast (redis:// or nats://) to share the roster.")));
+		}
+	}, A = (e) => {
 		let t = e === void 0 || e.includes("presence");
-		if (y !== void 0 && y !== t) throw Error("Presence bind and activation workloads must agree");
-		return y = t, t;
-	}, S, C, w, T = () => {
-		w === void 0 && v !== void 0 && (w = setInterval(() => {
-			let e = v;
+		if (b !== void 0 && b !== t) throw Error("Presence bind and activation workloads must agree");
+		return b = t, t;
+	}, j, M, N, P = () => {
+		N === void 0 && _ !== void 0 && (N = setInterval(() => {
+			let e = _;
 			if (e === void 0) return;
-			let t = e.tracker.sweep(a);
-			if (t.length !== 0) {
-				for (let n of t) e.announce(n);
-				O();
+			let n = e.tracker.sweep(t);
+			if (n.length !== 0) {
+				for (let t of n) e.announce(t);
+				L();
 			}
-		}, g), w.unref?.());
-	}, E = (e, t) => typeof t == "string" && t.length > 0 ? t : e.request.subject?.id ?? null, D = (e) => e.request.subject?.tenantId ?? null, O = () => {
-		m(S, l);
-	}, k = [
+		}, a), N.unref?.());
+	}, F = (e, t) => typeof t == "string" && t.length > 0 ? t : e.request.subject?.id ?? null, I = (e) => e.request.subject?.tenantId ?? null, L = () => {
+		m(j, l);
+	}, R = [
 		{
 			...o,
 			description: "Register/refresh the caller's presence in a channel.",
 			execute: (t, n) => d.gen(function* () {
 				let a = t;
-				if (!v) return yield* d.fail(new i({}));
-				let o = E(n, a.key);
+				if (!_) return yield* d.fail(new i({}));
+				let o = F(n, a.key);
 				if (o === null) return yield* d.fail(new r({ channel: a.channel }));
-				let s = e.resolveMember !== void 0 && C !== void 0 ? yield* d.promise(async () => e.resolveMember({
+				let s = e.resolveMember !== void 0 && M !== void 0 ? yield* d.promise(async () => e.resolveMember({
 					subject: n.request.subject,
 					channel: a.channel,
 					key: o,
-					store: C
+					store: M
 				})) : void 0, c = e.resolveMember !== void 0 && e.identityFields !== void 0 ? Object.fromEntries(Object.entries(a.meta ?? {}).filter(([t]) => !e.identityFields.includes(t))) : a.meta, l = s === void 0 ? c : {
 					...c ?? {},
 					...s
-				}, u = v.tracker.track({
+				}, u = _.tracker.track({
 					channel: a.channel,
-					tenantId: D(n),
+					tenantId: I(n),
 					key: o,
 					...l === void 0 ? {} : { meta: l }
 				});
-				return v.announce(u.delta), u.changed && O(), { ok: !0 };
+				return _.announce(u.delta), u.changed && L(), { ok: !0 };
 			})
 		},
 		{
 			...c,
 			description: "The online roster of a channel (heartbeat-fresh members). Push-driven — updates live.",
 			execute: (e, t) => d.gen(function* () {
-				return v ? v.tracker.roster(e.channel, D(t)).map((e) => ({
+				return _ ? _.tracker.roster(e.channel, I(t)).map((e) => ({
 					key: e.key,
 					meta: e.meta
 				})) : yield* d.fail(new i({}));
@@ -71,53 +82,56 @@ var h = a, g = (e = {}) => {
 			description: "Remove the caller's presence from a channel.",
 			execute: (e, t) => d.gen(function* () {
 				let n = e;
-				if (!v) return yield* d.fail(new i({}));
-				let a = E(t, n.key);
+				if (!_) return yield* d.fail(new i({}));
+				let a = F(t, n.key);
 				if (a === null) return yield* d.fail(new r({ channel: n.channel }));
-				let o = v.tracker.untrack({
+				let o = _.tracker.untrack({
 					channel: n.channel,
-					tenantId: D(t),
+					tenantId: I(t),
 					key: a
 				});
-				return v.announce(o.delta), o.changed && O(), { ok: !0 };
+				return _.announce(o.delta), o.changed && L(), { ok: !0 };
 			})
 		}
 	];
 	return f({
-		name: _,
+		name: g,
 		baseName: h,
 		workloads: ["rpc", "presence"],
 		description: "Ephemeral realtime presence — heartbeat roster per channel.",
-		routes: k,
+		routes: R,
 		rpcClientDescriptors: u,
 		bindDataStore: (e, t) => {
-			if (!x(t?.workloads)) return;
-			S = e, C = e;
-			let r = t;
-			v = n({
-				instanceId: r?.instanceId ?? `presence-${process.pid}`,
-				membership: r?.membership ?? { onChange: () => () => {} },
-				...r?.broadcast === void 0 ? {} : { provider: r.broadcast },
-				...r?.broadcastChannels?.presence === void 0 ? {} : { channel: r.broadcastChannels.presence },
-				onRosterChanged: O
-			}), b && T();
+			if (w || !A(t?.workloads)) return;
+			let r = ++C;
+			D = void 0, O = void 0, E = void 0, y(), j = e, M = e;
+			let i = t;
+			T = i?.broadcast !== void 0, _ = n({
+				instanceId: i?.instanceId ?? `presence-${process.pid}`,
+				membership: i?.membership ?? { onChange: () => () => {} },
+				...i?.broadcast === void 0 ? {} : { provider: i.broadcast },
+				...i?.broadcastChannels?.presence === void 0 ? {} : { channel: i.broadcastChannels.presence },
+				onRosterChanged: L,
+				logger: { warn: (e, t) => S?.warn(e, t) },
+				onTransportSettled: (e, t) => {
+					r === C && (T = !1, D = {
+						generation: r,
+						connected: e,
+						hasProvider: i?.broadcast !== void 0,
+						cause: t
+					}, k());
+				}
+			}), x && (P(), k());
 		},
 		onActivate: (e) => d.sync(() => {
-			if (!x(e.workloads)) return;
-			b = !0, T(), e.logger.info("presence active", {
-				timeoutMs: a,
-				sweepEveryMs: g
-			});
-			let n = Number(process.env.VOLTRO_PRESENCE_BROKER_GRACE_MS ?? 5e3), r = setTimeout(() => {
-				let t = v?.hasTransport === !0;
-				e.logger.info("presence transport", { crossInstance: t }), !t && e.logger.warn("presence: no broadcast provider — each replica sees only the clients CONNECTED TO IT. Correct for a single instance; on more than one, every screen shows a fraction of the room and nothing reports it. Add @voltro/plugin-broadcast (redis:// or nats://) to share the roster.");
-			}, n);
-			r.unref?.(), t = r;
+			A(e.workloads) && (x || (w = !1, S = e.logger, x = !0, P(), e.logger.info("presence active", {
+				timeoutMs: t,
+				sweepEveryMs: a
+			}), k()));
 		}),
 		onDeactivate: () => d.sync(() => {
-			b = !1, t !== void 0 && (clearTimeout(t), t = void 0), w !== void 0 && (clearInterval(w), w = void 0), v?.detach(), v = void 0, S = void 0, C = void 0;
+			x = !1, w = !0, C += 1, T = !1, E = void 0, D = void 0, O = void 0, N !== void 0 && (clearInterval(N), N = void 0), j = void 0, M = void 0, y();
 		})
 	});
 };
-//#endregion
 export { t as PRESENCE_BROADCAST_CHANNEL, r as PresenceKeyMissing, i as PresenceStoreUnavailable, e as PresenceTracker, n as attachPresenceBus, g as presencePlugin, l as presenceRoster };

package/dist/rpc.js

@@ -1,7 +1,7 @@
 import { PresenceKeyMissing as e, PresenceStoreUnavailable as t } from "./errors.js";
 import { Schema as n } from "effect";
 import { defineMutation as r, defineQuery as i, reactivityChannel as a } from "@voltro/protocol";
-//#region src/rpc.ts
+// src/rpc.ts
 var o = "@voltro/plugin-presence", s = a("presence"), c = n.Struct({
 	key: n.String,
 	meta: n.NullOr(n.Record(n.String, n.Unknown))
@@ -57,5 +57,4 @@ var o = "@voltro/plugin-presence", s = a("presence"), c = n.Struct({
 		}
 	}
 ];
-//#endregion
 export { o as BASE_NAME, l as heartbeatDescriptor, d as leaveDescriptor, u as listDescriptor, s as presenceRoster, f as presenceRpcClientImports };

package/dist/tracker.js

@@ -1,4 +1,4 @@
-//#region src/tracker.ts
+// src/tracker.ts
 var e = (e, t) => `${e ?? "~"}::${t}`, t = (e) => e === void 0 ? "undefined" : typeof e != "object" || !e ? JSON.stringify(e) ?? "undefined" : Array.isArray(e) ? `[${e.map(t).join(",")}]` : `{${Object.entries(e).sort(([e], [t]) => e < t ? -1 : +(e > t)).map(([e, n]) => `${JSON.stringify(e)}:${t(n)}`).join(",")}}`, n = (e, n) => e === n || e !== null && n !== null && t(e) === t(n), r = class {
 	partitions = /* @__PURE__ */ new Map();
 	selfId;
@@ -130,5 +130,4 @@ var e = (e, t) => `${e ?? "~"}::${t}`, t = (e) => e === void 0 ? "undefined" : t
 		return this.owners().reduce((e, t) => e + t.members, 0);
 	}
 };
-//#endregion
 export { r as PresenceTracker };

package/dist/trackerBus.js

@@ -1,17 +1,24 @@
 import { PresenceTracker as e } from "./tracker.js";
 import { Effect as t } from "effect";
-//#region src/trackerBus.ts
+// src/trackerBus.ts
 var n = "voltro:presence", r = (e) => typeof e == "object" && !!e && typeof e.owner == "string" && typeof e.delta == "object" && e.delta !== null, i = (e) => typeof e == "object" && !!e && typeof e.owner == "string" && Array.isArray(e.sync), a = (n) => {
 	let a = new e({
 		instanceId: n.instanceId,
 		...n.now === void 0 ? {} : { now: n.now }
-	}), o = n.logger, s = () => {
+	}), o = n.logger, s = !1, c = !1, l = (e, t) => {
+		if (!s) try {
+			n.onTransportSettled?.(e, t);
+		} catch (e) {
+			o?.warn("presence: transport observer failed", { cause: e });
+		}
+	}, u = () => {
 		try {
 			n.onRosterChanged?.();
 		} catch {}
-	}, c = n.membership.onChange((e) => {
+	}, d = n.membership.onChange((e) => {
+		if (s) return;
 		if (e.kind === "joined") {
-			f();
+			h();
 			return;
 		}
 		let t = a.dropOwner(e.instanceId);
@@ -19,17 +26,18 @@ var n = "voltro:presence", r = (e) => typeof e == "object" && !!e && typeof e.ow
 			instanceId: e.instanceId,
 			members: t,
 			reason: e.kind
-		}), s()), e.kind === "restarted" && f();
-	}), l = n.provider, u = n.channel ?? "voltro:presence", d = (e) => {
-		l !== void 0 && t.runPromise(l.publish(u, JSON.stringify(e))).catch(() => {});
-	}, f = () => {
+		}), u()), e.kind === "restarted" && h();
+	}), f = n.provider, p = n.channel ?? "voltro:presence", m = (e) => {
+		s || f === void 0 || t.runPromise(f.publish(p, JSON.stringify(e))).catch(() => {});
+	}, h = () => {
 		let e = a.ownSnapshot();
-		e.length !== 0 && d({
+		e.length !== 0 && m({
 			owner: n.instanceId,
 			sync: e
 		});
-	}, p;
-	return l !== void 0 && t.runPromise(l.subscribe(u, (e) => {
+	}, g;
+	return f === void 0 ? queueMicrotask(() => l(!1)) : t.runPromise(f.subscribe(p, (e) => {
+		if (s) return;
 		let t;
 		try {
 			t = JSON.parse(e);
@@ -39,25 +47,43 @@ var n = "voltro:presence", r = (e) => typeof e == "object" && !!e && typeof e.ow
 		if (i(t)) {
 			let e = !1;
 			for (let n of t.sync) e = a.apply(t.owner, n) || e;
-			e && s();
-		} else r(t) && a.apply(t.owner, t.delta) && s();
+			e && u();
+		} else r(t) && a.apply(t.owner, t.delta) && u();
 	})).then((e) => {
-		p = e;
+		if (g = e, s) try {
+			e(), g = void 0;
+		} catch (e) {
+			o?.warn("presence: could not release a closed subscription", { cause: e });
+		}
+		else c = !0, l(!0);
 	}, (e) => {
-		o?.warn("presence: could not subscribe — this instance will only see its own members", { cause: e });
+		s || (n.onTransportSettled === void 0 && o?.warn("presence: could not subscribe — this instance will only see its own members", { cause: e }), l(!1, e));
 	}), {
 		tracker: a,
-		hasTransport: l !== void 0,
+		get hasTransport() {
+			return c && !s;
+		},
 		announce: (e) => {
-			d({
+			m({
 				owner: n.instanceId,
 				delta: e
 			});
 		},
 		detach: () => {
-			c(), p?.();
+			s = !0, c = !1;
+			let e = [];
+			try {
+				d?.(), d = void 0;
+			} catch (t) {
+				e.push(t);
+			}
+			try {
+				g?.(), g = void 0;
+			} catch (t) {
+				e.push(t);
+			}
+			if (e.length > 0) throw AggregateError(e, "presence: could not detach transport");
 		}
 	};
 };
-//#endregion
 export { n as PRESENCE_BROADCAST_CHANNEL, a as attachPresenceBus };

package/dist/web.js

@@ -2,7 +2,7 @@ import { BASE_NAME as e } from "./rpc.js";
 import { pluginTag as t } from "@voltro/protocol";
 import { useCallback as n, useEffect as r, useMemo as i, useRef as a, useState as o } from "react";
 import { useMutation as s, useSubscription as c } from "@voltro/client";
-//#region src/web.ts
+// src/web.ts
 var l = (n) => t(e, n), u = (e, t = {}) => {
 	let { meta: o, key: u, heartbeatMs: d = 15e3, apiName: f = "app" } = t, p = s(f, l("heartbeat")), m = s(f, l("leave")), h = a(p), g = a(m);
 	h.current = p, g.current = m;
@@ -111,5 +111,4 @@ var l = (n) => t(e, n), u = (e, t = {}) => {
 		}
 	}), [e, n]);
 };
-//#endregion
 export { d as activeTypers, u as usePresence, p as usePresenceChannel, f as useTyping };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-presence",
-  "version": "0.87.0",
+  "version": "0.88.0",
   "description": "Ephemeral realtime presence — who is online in a channel, with heartbeat + live roster + per-member metadata (cursor, status — client-supplied and relayed verbatim; identity fields belong in the server-side resolveMember hook). Held in memory, owner-partitioned; cross-instance with @voltro/plugin-broadcast.",
   "keywords": [
     "voltro",
@@ -48,12 +48,12 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/client": "0.87.0",
-    "@voltro/protocol": "0.87.0"
+    "@voltro/client": "0.88.0",
+    "@voltro/protocol": "0.88.0"
   },
   "peerDependencies": {
-    "@voltro/database": "0.87.0",
-    "effect": "4.0.1",
+    "@voltro/database": "0.88.0",
+    "effect": "4.1.0",
     "react": "^19.0.0"
   },
   "peerDependenciesMeta": {