@voltro/plugin-rooms 0.0.0-stage → 0.88.0

package/dist/snapshotSegmentBlobs.js

@@ -0,0 +1,57 @@
+import { ProtocolError as e } from "./errors.js";
+import { ROOM_SNAPSHOT_SEGMENTS_TABLE as t } from "./identities.js";
+import { captureRoomSnapshotBlobReference as n } from "./snapshotBlob.js";
+import { and as r, eq as i } from "@voltro/database";
+// src/snapshotSegmentBlobs.ts
+function a(t) {
+	throw new e({ detail: t });
+}
+var o = (e, t) => r(i("roomId", e), i("tenantId", t)), s = (e, t, r, i) => e.blob == null ? null : e.roomId !== t || e.tenantId !== r || !(e.bytes instanceof Uint8Array) || e.bytes.byteLength !== 0 ? a("Snapshot segment blob has mixed or foreign SQL payload identity") : n(e.blob, {
+	roomId: t,
+	tenantId: r,
+	epoch: e.epoch,
+	revision: e.revision
+}, i), c = async (e, n, r, i, c) => {
+	if (c !== void 0 && (!Number.isSafeInteger(c) || c < 2)) return a("Invalid snapshot segment withdrawal boundary");
+	let l = await e.query({
+		table: t,
+		predicate: o(n, r),
+		order: [],
+		take: 146,
+		skip: void 0,
+		projection: [
+			"id",
+			"roomId",
+			"tenantId",
+			"epoch",
+			"revision",
+			"bytes",
+			"blob"
+		]
+	});
+	if (l.length > 145) return a("Snapshot segment claim inventory exceeds its bound");
+	let u = [];
+	for (let e of l) {
+		if (c !== void 0 && (e.roomId !== n || e.tenantId !== r || !Number.isSafeInteger(e.epoch) || Number(e.epoch) < 1 || Number(e.epoch) >= c || !Number.isSafeInteger(e.revision) || Number(e.revision) < 1)) return a("Snapshot segment still has an unfenced writer");
+		let t = s(e, n, r, i);
+		t && u.push(t);
+	}
+	return u;
+}, l = async (e, n, c, l, u) => {
+	let d = await e.query({
+		table: t,
+		predicate: u ? r(o(n, c), u) : o(n, c),
+		order: [],
+		take: 146,
+		skip: void 0,
+		projection: void 0
+	});
+	if (d.length > 145) return a("Snapshot segment retirement exceeds its bound");
+	let f = [];
+	for (let a of d) {
+		let u = s(a, n, c, l);
+		u && f.push(u), await e.deleteMany(t, { where: r(o(n, c), i("id", a.id)) });
+	}
+	return f;
+};
+export { s as captureRoomSnapshotSegmentBlob, c as readRoomSnapshotSegmentBlobs, l as retireRoomSnapshotSegments };

package/dist/snapshotUploads.js

@@ -0,0 +1,165 @@
+import { ProtocolError as e } from "./errors.js";
+import { ROOMS_TABLE as t, ROOM_CHECKPOINTS_TABLE as n } from "./identities.js";
+import { canonicalRoomJson as r } from "./checkpointJson.js";
+import { captureRoomSnapshotBlobReference as i } from "./snapshotBlob.js";
+import { captureRoomSnapshotBlobs as a, captureRoomSnapshotEffectRunner as o } from "./snapshotBlobIndex.js";
+import { readRoomSnapshotSegmentBlobs as s } from "./snapshotSegmentBlobs.js";
+import { readRoomSnapshotBlobJournal as c } from "./snapshotBlobCleanup.js";
+import { and as l, eq as u } from "@voltro/database";
+import { Effect as d } from "effect";
+import { createHash as f } from "node:crypto";
+// src/snapshotUploads.ts
+function p(t) {
+	throw new e({ detail: t });
+}
+var m = (e) => f("sha256").update(e).digest("hex"), h = (e, t) => l(u("id", e), u("tenantId", t)), g = (e) => `rooms:snapshot:${m(e.claimId)}`, _ = (e, t) => r({
+	...e,
+	reference: null
+}) === r({
+	...t,
+	reference: null
+}), v = async (e, n, r) => (await e.query({
+	table: t,
+	predicate: h(n, r),
+	order: [],
+	take: 1,
+	skip: void 0,
+	projection: void 0,
+	lock: "update"
+}))[0] || p("Snapshot upload journal lost its SQL room authority"), y = (e, t, n, r) => {
+	if (!e || typeof e != "object" || Array.isArray(e) || Object.keys(e).some((e) => ![
+		"roomId",
+		"tenantId",
+		"hostId",
+		"epoch",
+		"revision",
+		"requestId",
+		"fingerprint",
+		"claimId",
+		"size",
+		"checksum",
+		"reference"
+	].includes(e)) || e.roomId !== t || e.tenantId !== n || ![
+		t,
+		n,
+		e.hostId
+	].every((e) => typeof e == "string" && e.trim() && e.length <= 191) || ![
+		e.epoch,
+		e.revision,
+		e.size
+	].every((e) => Number.isSafeInteger(e) && e > 0) || e.size > r || e.requestId !== `${t}:${e.epoch}:checkpoint:${e.revision}` || e.requestId.length > 191 || typeof e.claimId != "string" || e.claimId.length > 191 || ![e.fingerprint, e.checksum].every((e) => typeof e == "string" && /^[a-f0-9]{64}$/.test(e)) || e.claimId !== e.requestId && e.claimId !== `${e.requestId}:segment` || e.reference === void 0) return p("Malformed scoped snapshot upload intent");
+	let a = e.reference === null ? null : i(e.reference, e, r);
+	return a && (a.claim !== g(e) || a.size !== e.size || a.checksum !== e.checksum) ? p("Snapshot upload receipt does not match its durable intent") : Object.freeze({
+		roomId: t,
+		tenantId: n,
+		hostId: e.hostId,
+		epoch: e.epoch,
+		revision: e.revision,
+		requestId: e.requestId,
+		fingerprint: e.fingerprint,
+		claimId: e.claimId,
+		size: e.size,
+		checksum: e.checksum,
+		reference: a
+	});
+}, b = (e, t, n, r) => {
+	if (e.id !== t || e.tenantId !== n || !Number.isSafeInteger(e.epoch) || Number(e.epoch) < 1) return p("Snapshot upload journal has foreign SQL room identity");
+	let i = e.snapshotUploads;
+	if (i == null) return [];
+	if (!Array.isArray(i) || i.length > 16) return p("Snapshot upload journal exceeds its bounded inventory");
+	let a = /* @__PURE__ */ new Set(), o = [];
+	for (let s = 0; s < i.length; s++) {
+		if (!Object.hasOwn(i, s)) return p("Snapshot upload journal cannot be sparse");
+		let c = y(i[s], t, n, r);
+		if (c.epoch > Number(e.epoch) || a.has(c.requestId)) return p("Snapshot upload journal contains a future or duplicate owner request");
+		a.add(c.requestId), o.push(c);
+	}
+	return Object.freeze(o);
+}, x = async (e, n, r, i) => {
+	let a = y(r, r.roomId, r.tenantId, i), o = b(n, a.roomId, a.tenantId, i), s = o.find((e) => e.requestId === a.requestId);
+	s ? _(s, a) || p("Snapshot upload request identity was reused") : (o.length >= 16 && p("Snapshot upload journal must drain before another preupload"), await e.updateMany(t, { snapshotUploads: [...o, a] }, { where: h(a.roomId, a.tenantId) }));
+}, S = async (e, n, i, a) => e.transactional(async (e) => {
+	let o = y({
+		...n,
+		reference: i
+	}, n.roomId, n.tenantId, a), s = b(await v(e, n.roomId, n.tenantId), n.roomId, n.tenantId, a), c = s.find((e) => e.requestId === n.requestId);
+	if (!c || !_(c, o) || c.reference && r(c.reference) !== r(i)) return p("Snapshot upload receipt no longer owns its durable journal entry");
+	await e.updateMany(t, { snapshotUploads: s.map((e) => e.requestId === n.requestId ? o : e) }, { where: h(n.roomId, n.tenantId) });
+}), C = async (e, n, r, i, a, o) => {
+	let s = b(await v(e, n, r), n, r, o), c = s.find((e) => e.requestId === i);
+	if (c) {
+		if (c.fingerprint !== a) return p("Snapshot upload journal completion has unrelated checkpoint identity");
+		await e.updateMany(t, { snapshotUploads: s.filter((e) => e.requestId !== i) }, { where: h(n, r) });
+	}
+}, w = (r, f, m, _, x = 1048576) => {
+	let w = a(f);
+	return !w || ![m, _].every((e) => typeof e == "string" && e.trim() && e.length <= 191) || !Number.isSafeInteger(x) || x < 1 || x > 67108864 ? d.fail(new e({ detail: "Invalid scoped snapshot upload recovery budget" })) : d.flatMap(d.context(), (a) => d.uninterruptible(d.tryPromise({
+		try: async () => {
+			let e = o(a), d = await r.transactional(async (e) => {
+				let r = await v(e, m, _), a = b(r, m, _, x);
+				if (!a.length) return {
+					indexed: 0,
+					candidates: [],
+					pending: 0
+				};
+				let o = (await e.query({
+					table: n,
+					predicate: l(u("roomId", m), u("tenantId", _)),
+					order: [],
+					take: 1,
+					skip: void 0,
+					projection: void 0,
+					lock: "update"
+				}))[0], d = c(o, m, _, x), f = [
+					...d.blobHistory,
+					...d.retiredBlobs,
+					...await s(e, m, _, x)
+				];
+				o?.blob && f.push(i(o.blob, o.checkpoint, x));
+				let p = /* @__PURE__ */ new Set();
+				for (let e of a) {
+					let t = f.find((t) => t.claim === g(e) && t.epoch === e.epoch && t.revision === e.revision);
+					t && (y({
+						...e,
+						reference: t
+					}, m, _, x), p.add(e.requestId));
+				}
+				p.size && await e.updateMany(t, { snapshotUploads: a.filter((e) => !p.has(e.requestId)) }, { where: h(m, _) });
+				let S = a.filter((e) => !p.has(e.requestId)), C = S.filter((e) => Number(r.epoch) > e.epoch);
+				return {
+					indexed: p.size,
+					candidates: C,
+					pending: S.length - C.length
+				};
+			}), f = 0, T = d.pending;
+			for (let t of d.candidates) {
+				let n = t.reference;
+				if (!n) {
+					let i = await e(w.recover(t));
+					if (!i || typeof i != "object" || ![
+						"pending",
+						"ready",
+						"released"
+					].includes(i.state)) return p("Snapshot recovery port returned an invalid durable observation");
+					if (i.state === "pending") {
+						T++;
+						continue;
+					}
+					if (n = y({
+						...t,
+						reference: i.reference
+					}, m, _, x).reference, !n) return p("Snapshot recovered upload has no exact claim");
+					await S(r, t, n, x);
+				}
+				await e(w.release(n, n)), await r.transactional((e) => C(e, m, _, t.requestId, t.fingerprint, x)), f++;
+			}
+			return {
+				indexed: d.indexed,
+				released: f,
+				pending: T
+			};
+		},
+		catch: (t) => t instanceof e ? t : new e({ detail: "Snapshot upload recovery remains unconfirmed" })
+	})));
+};
+export { x as appendRoomSnapshotUploadIntent, y as captureRoomSnapshotUploadIntent, w as cleanupRoomSnapshotUploads, C as finishRoomSnapshotUploadIntent, b as readRoomSnapshotUploadJournal, S as recordRoomSnapshotUploadReference };

package/dist/socketTransport.js

@@ -0,0 +1,252 @@
+import { BudgetExceeded as e, ProtocolError as t, RoomAuthoringError as n } from "./errors.js";
+import { captureRoomTransportClock as r, captureRoomTransportDataMethod as i } from "./transportAuthoring.js";
+import { RoomTransportCleanupFailure as a } from "./transportCleanup.js";
+// src/socketTransport.ts
+var o = (e) => {
+	let n = Reflect.get(globalThis, "WebSocket");
+	if (typeof n != "function") throw new t({ detail: "This platform requires a Room WebSocket factory" });
+	return Reflect.construct(n, [e]);
+}, s = (e) => Number.isSafeInteger(e) ? e === 1e3 || e >= 3e3 && e <= 4999 ? e : e >= 1001 && e <= 1014 ? 4e3 + e - 1e3 : 4e3 : 4e3, ee = (e) => {
+	let t = "", n = 0, r = new TextEncoder();
+	for (let i of e) {
+		let e = r.encode(i).byteLength;
+		if (n + e > 123) break;
+		n += e, t += i;
+	}
+	return t;
+}, c = (c, l, u = {}) => {
+	if (l.aborted) return Promise.reject(new t({ detail: "Room socket connection was cancelled" }));
+	let d = [
+		"factory",
+		"clock",
+		"connectTimeoutMs",
+		"drainPollMs",
+		"maxFrameBytes",
+		"maxPendingBytes",
+		"maxPendingFrames",
+		"highWaterBytes",
+		"maxListeners"
+	];
+	if (!u || Object.getPrototypeOf(u) !== Object.prototype || Reflect.ownKeys(u).some((e) => {
+		let t = Object.getOwnPropertyDescriptor(u, e);
+		return typeof e != "string" || !d.includes(e) || !t?.enumerable || !("value" in t);
+	}) || u.factory !== void 0 && typeof u.factory != "function") return Promise.reject(new n({
+		room: "socket",
+		detail: "Room socket options require exact own providers and budgets"
+	}));
+	let f = Object.freeze({
+		connectTimeoutMs: 5e3,
+		drainPollMs: 10,
+		maxFrameBytes: 65536,
+		maxPendingBytes: 1048576,
+		maxPendingFrames: 128,
+		highWaterBytes: 32768,
+		maxListeners: 128,
+		...u
+	});
+	for (let e of [
+		f.connectTimeoutMs,
+		f.drainPollMs,
+		f.maxFrameBytes,
+		f.maxPendingBytes,
+		f.maxPendingFrames,
+		f.highWaterBytes,
+		f.maxListeners
+	]) if (!Number.isSafeInteger(e) || e < 1) return Promise.reject(new n({
+		room: "socket",
+		detail: "Socket budgets must be positive safe integers"
+	}));
+	if (f.maxFrameBytes > f.maxPendingBytes || f.connectTimeoutMs > 2147483647 || f.drainPollMs > 2147483647) return Promise.reject(new n({
+		room: "socket",
+		detail: "Socket frame or timer budget exceeds its parent budget"
+	}));
+	let p, m;
+	try {
+		p = r(f.clock ?? { now: () => performance.now() });
+		let e = new URL(c);
+		if (!["ws:", "wss:"].includes(e.protocol) || e.username || e.password || e.search || e.hash) throw new t({ detail: "Rooms socket address must contain no credentials, query or fragment" });
+		m = (f.factory ?? o)(e.toString());
+	} catch (e) {
+		return Promise.reject(e instanceof t || e instanceof n ? e : new t({ detail: "Room socket native acquisition failed" }));
+	}
+	let h, g, _, v;
+	try {
+		h = i(m, "addEventListener", "Room socket needs an actual event observer"), g = i(m, "removeEventListener", "Room socket needs actual event withdrawal"), _ = i(m, "close", "Room socket needs an actual native close"), v = i(m, "send", "Room socket needs an actual binary writer");
+	} catch {
+		let e = !1, n = new a(async () => {
+			if (e ||= (i(m, "close", "Room socket parent release remains unavailable")(1e3, "Room socket provider admission failed"), !0), m.readyState !== 3) throw new t({ detail: "Room socket provider terminal evidence remains unavailable" });
+		});
+		return n.cleanupAsync().then(() => {
+			throw new t({ detail: "Room socket provider admission failed" });
+		}, () => {
+			throw n;
+		});
+	}
+	let y = new AbortController(), b = /* @__PURE__ */ new Set(), x = [], S = /* @__PURE__ */ new Set(), C = 0, w = !1, T = !1, E = !1, D = !1, O = !1, k = !1, A = -1, j, M = !1, N, P, F, I, L = new Promise((e) => {
+		I = e;
+	}), R, z, B = new Promise((e, t) => {
+		R = e, z = t;
+	}), V = () => {
+		let e = p.now();
+		if (!Number.isFinite(e) || e < 0 || e < A) throw new t({ detail: "Socket receive clock must be monotonic" });
+		return A = e, e;
+	}, H = () => {
+		let e = m.bufferedAmount;
+		if (!Number.isSafeInteger(e) || e < 0) throw new t({ detail: "Platform socket returned an invalid buffer size" });
+		return e;
+	}, U = () => x.reduce((e, t) => e + (t.sent ? 0 : t.frame.byteLength), H()), W = (e) => {
+		if (!w) {
+			w = !0, N !== void 0 && clearTimeout(N), P !== void 0 && clearTimeout(P), N = void 0, P = void 0;
+			for (let t of x.splice(0)) t.reject(e);
+			C = 0, b.clear(), y.abort();
+		}
+	}, G = () => {
+		D || O || (_(F.code, F.reason), O = !0);
+	}, K = new a(async () => {
+		if (j !== void 0) throw j = void 0, new t({ detail: "Room socket native close remains incomplete" });
+		!D && m.readyState === 3 && (D = !0, I()), !D && !k && (S.add("close"), h("close", Z), k = !0), G(), await L;
+		let e = !1;
+		for (let [t, n] of $) if (S.has(t)) try {
+			g(t, n), S.delete(t), t === "close" && (k = !1);
+		} catch {
+			e = !0;
+		}
+		if (M) try {
+			l.removeEventListener("abort", Q), M = !1;
+		} catch {
+			e = !0;
+		}
+		if (e) throw new t({ detail: "Room socket listener cleanup remains incomplete" });
+	}), q = (e, n, r) => {
+		if (F ??= Object.freeze({
+			code: s(e),
+			reason: ee(n)
+		}), W(r), j === void 0) try {
+			G();
+		} catch {
+			j = new t({ detail: "Room socket native close failed" });
+		}
+		let i = K.cleanupAsync();
+		return i.then(() => {
+			z(r);
+		}, () => {
+			z(K);
+		}), i;
+	}, J = (e, t, n) => {
+		q(e, t, n).catch(() => {});
+	}, Y = () => {
+		if (N = void 0, !w && T) try {
+			if (m.readyState !== 1) {
+				J(1e3, "Room socket is no longer open", new t({ detail: "Room socket is no longer open" }));
+				return;
+			}
+			if (H() > f.maxPendingBytes) throw new e({
+				budget: "socketPendingBytes",
+				limit: f.maxPendingBytes
+			});
+			for (; x.length;) {
+				let e = x[0];
+				if (e.sent) {
+					if (H() !== 0) break;
+					x.shift(), C -= e.frame.byteLength, e.resolve();
+					continue;
+				}
+				let t = H();
+				if (t > 0 && t + e.frame.byteLength > f.highWaterBytes) break;
+				v(e.frame), e.sent = !0;
+			}
+			x.length && (N = setTimeout(Y, f.drainPollMs));
+		} catch (t) {
+			J(t instanceof e ? 1009 : 1002, "Room socket write failed", t);
+		}
+	}, te = Object.freeze({
+		name: "ws",
+		signal: y.signal,
+		reliable: Object.freeze({
+			send: (n) => {
+				if (w || !T) return Promise.reject(new t({ detail: "Room socket is not open" }));
+				if (!(n instanceof Uint8Array)) return Promise.reject(new t({ detail: "Room socket requires binary bytes" }));
+				if (n.byteLength > f.maxFrameBytes) return Promise.reject(new e({
+					budget: "socketFrameBytes",
+					limit: f.maxFrameBytes
+				}));
+				if (x.length >= f.maxPendingFrames || C + n.byteLength > f.maxPendingBytes) {
+					let t = x.length >= f.maxPendingFrames ? new e({
+						budget: "socketPendingFrames",
+						limit: f.maxPendingFrames
+					}) : new e({
+						budget: "socketPendingBytes",
+						limit: f.maxPendingBytes
+					});
+					return J(1009, "Room socket queue exceeded its budget", t), Promise.reject(t);
+				}
+				let r = new Promise((e, t) => {
+					let r = Uint8Array.from(n);
+					x.push({
+						frame: r,
+						resolve: e,
+						reject: t,
+						sent: !1
+					}), C += r.byteLength;
+				});
+				return N === void 0 && Y(), r;
+			},
+			onFrame: (n) => {
+				if (w || typeof n != "function") throw new t({ detail: "Room socket cannot attach this listener after close" });
+				if (!b.has(n) && b.size >= f.maxListeners) throw new e({
+					budget: "roomTransportListeners",
+					limit: f.maxListeners
+				});
+				return b.add(n), () => {
+					b.delete(n);
+				};
+			}
+		}),
+		stats: () => ({
+			rttMs: null,
+			queuedBytes: w ? 0 : U(),
+			droppedDatagrams: 0
+		}),
+		close: (e, n) => J(e, n, new t({ detail: "Room socket was closed" })),
+		closeAsync: (e, n) => q(e, n, new t({ detail: "Room socket was closed" }))
+	}), X = () => {
+		w || T || !E || (T = !0, P !== void 0 && clearTimeout(P), P = void 0, R(te));
+	}, ne = (n) => {
+		if (!w && T) try {
+			let r = n.data, i = r instanceof ArrayBuffer ? new Uint8Array(r) : ArrayBuffer.isView(r) ? new Uint8Array(r.buffer, r.byteOffset, r.byteLength) : null;
+			if (!i) throw new t({ detail: "Rooms sockets require binary frames" });
+			if (i.byteLength > f.maxFrameBytes) throw new e({
+				budget: "socketFrameBytes",
+				limit: f.maxFrameBytes
+			});
+			let a = V();
+			for (let e of b) {
+				if (w) break;
+				e(Uint8Array.from(i), a);
+			}
+		} catch (t) {
+			J(t instanceof e ? 1009 : 1002, "Room socket frame refused", t);
+		}
+	}, Z = () => {
+		D = !0, I(), J(1e3, "Room socket disconnected", new t({ detail: "Room socket disconnected" }));
+	}, re = () => {
+		w || J(1002, "Room socket failed", new t({ detail: "Room socket failed" }));
+	}, Q = () => {
+		w || J(1e3, "Room socket cancelled", new t({ detail: "Room socket connection was cancelled" }));
+	}, $ = [
+		["open", X],
+		["message", ne],
+		["close", Z],
+		["error", re]
+	];
+	try {
+		if (S.add("close"), h("close", Z), k = !0, w) throw new t({ detail: "Room socket closed during observer admission" });
+		m.binaryType = "arraybuffer";
+		for (let [e, t] of $) e !== "close" && (S.add(e), h(e, t));
+		M = !0, l.addEventListener("abort", Q, { once: !0 }), E = !0, w || (P = setTimeout(() => J(1e3, "Room socket connection timed out", new t({ detail: "Room socket connection timed out" })), f.connectTimeoutMs)), l.aborted ? Q() : m.readyState === 1 ? X() : m.readyState === 3 ? Z() : m.readyState !== 0 && J(1e3, "Room socket admission failed", new t({ detail: "Room socket is already closing" }));
+	} catch {
+		J(1e3, "Room socket initialization failed", new t({ detail: "Room socket initialization failed" }));
+	}
+	return B;
+};
+export { o as defaultRoomWebSocketFactory, c as openRoomSocketTransport };

package/dist/spatial.js

@@ -0,0 +1,103 @@
+import { BudgetExceeded as e, RoomAuthoringError as t } from "./errors.js";
+// src/spatial.ts
+function n(e) {
+	throw new t({
+		room: "spatial",
+		detail: e
+	});
+}
+var r = (e) => {
+	Number.isFinite(e.x) && Number.isFinite(e.y) || n("Spatial positions must be finite");
+}, i = (e) => Number.isSafeInteger(e) && e > 0 ? e : n("Spatial budgets must be positive safe integers"), a = class {
+	entities = /* @__PURE__ */ new Map();
+	cells = /* @__PURE__ */ new Map();
+	options;
+	constructor(e) {
+		(!Number.isFinite(e.cell) || e.cell <= 0) && n("Spatial cell size must be positive and finite"), i(e.maxEntities), i(e.maxQueryCells), this.options = Object.freeze({ ...e });
+	}
+	coordinate(e) {
+		let t = Math.floor(e / this.options.cell);
+		return Number.isSafeInteger(t) ? t : n("Spatial cell coordinate exceeds its integer range");
+	}
+	key(e) {
+		return r(e), `${this.coordinate(e.x)}:${this.coordinate(e.y)}`;
+	}
+	set(t, i, a) {
+		t.trim() || n("Spatial entity id is required"), r(i);
+		let o = this.entities.get(t);
+		if (!o && this.entities.size >= this.options.maxEntities) throw new e({
+			budget: "spatialEntities",
+			limit: this.options.maxEntities
+		});
+		let s = this.key(i), c = structuredClone(a);
+		o && o.cell !== s && this.removeFromCell(t, o.cell);
+		let l = this.cells.get(s) ?? /* @__PURE__ */ new Set();
+		l.add(t), this.cells.set(s, l), this.entities.set(t, {
+			cell: s,
+			position: Object.freeze({ ...i }),
+			value: c
+		});
+	}
+	removeFromCell(e, t) {
+		let n = this.cells.get(t);
+		n?.delete(e), n?.size === 0 && this.cells.delete(t);
+	}
+	delete(e) {
+		let t = this.entities.get(e);
+		return t ? (this.removeFromCell(e, t.cell), this.entities.delete(e)) : !1;
+	}
+	get(e) {
+		let t = this.entities.get(e);
+		return t === void 0 ? void 0 : structuredClone(t.value);
+	}
+	nearby(t, a, o = this.options.maxEntities) {
+		r(t), i(o), (!Number.isFinite(a) || a < 0) && n("Spatial radius must be finite and nonnegative");
+		let s = this.coordinate(t.x - a), c = this.coordinate(t.x + a), l = this.coordinate(t.y - a), u = this.coordinate(t.y + a), d = (c - s + 1) * (u - l + 1);
+		if (!Number.isSafeInteger(d) || d > this.options.maxQueryCells) throw new e({
+			budget: "spatialQueryCells",
+			limit: this.options.maxQueryCells
+		});
+		let f = [];
+		for (let e = s; e <= c; e++) for (let n = l; n <= u; n++) for (let r of this.cells.get(`${e}:${n}`) ?? []) {
+			let e = this.entities.get(r);
+			if (!e) continue;
+			let n = Math.hypot(e.position.x - t.x, e.position.y - t.y);
+			n <= a && f.push({
+				id: r,
+				value: e.value,
+				distance: n
+			});
+		}
+		return f.sort((e, t) => e.distance - t.distance || (e.id < t.id ? -1 : +(e.id > t.id))), f.slice(0, Math.min(o, this.options.maxEntities)).map((e) => ({
+			...e,
+			value: structuredClone(e.value)
+		}));
+	}
+	size() {
+		return this.entities.size;
+	}
+	cellCount() {
+		return this.cells.size;
+	}
+	clear() {
+		this.entities.clear(), this.cells.clear();
+	}
+}, o = (e) => new a(e), s = class {
+	grid;
+	radius;
+	hysteresis;
+	maxEntities;
+	visible = /* @__PURE__ */ new Set();
+	constructor(e, t, r, a) {
+		this.grid = e, this.radius = t, this.hysteresis = r, this.maxEntities = a, (!Number.isFinite(t) || t < 0 || !Number.isFinite(r) || r < 0) && n("Interest bounds must be finite and nonnegative"), i(a);
+	}
+	update(e) {
+		let t = this.grid.nearby(e, this.radius + this.hysteresis).filter((e) => e.distance <= this.radius || this.visible.has(e.id)).slice(0, this.maxEntities), n = new Set(t.map((e) => e.id)), r = [...n].filter((e) => !this.visible.has(e)), i = [...this.visible].filter((e) => !n.has(e)).sort();
+		return this.visible = n, {
+			entities: t,
+			entered: r,
+			left: i
+		};
+	}
+};
+export { a as SpatialGrid2D, s as SpatialInterest2D, o as spatialGrid };

package/dist/spectatorPolicy.js

@@ -0,0 +1,25 @@
+import { ProtocolError as e } from "./errors.js";
+// src/spectatorPolicy.ts
+var t = Object.freeze({
+	delayMs: 0,
+	retentionMs: 18e4,
+	maxFrames: 4096,
+	maxBytes: 16777216,
+	maxFrameBytes: 1048576,
+	checkpointEveryMs: 5e3,
+	maxDeliveryFrames: 256
+});
+function n() {
+	throw new e({ detail: "Invalid spectator history policy or allocation budget" });
+}
+var r = (e = {}) => {
+	e && typeof e == "object" && [Object.prototype, null].includes(Object.getPrototypeOf(e)) || n();
+	let r = { ...t };
+	for (let i of Reflect.ownKeys(e)) {
+		let a = Object.getOwnPropertyDescriptor(e, i);
+		typeof i == "string" && Object.hasOwn(t, i) && a && Object.hasOwn(a, "value") && a.enumerable && typeof a.value == "number" || n(), r[i] = a.value;
+	}
+	for (let [e, t] of Object.entries(r)) (!Number.isSafeInteger(t) || t < (e === "delayMs" ? 0 : 1)) && n();
+	return (r.retentionMs < r.delayMs || r.maxFrames > 1e6 || r.maxBytes > 536870912 || r.maxFrameBytes > r.maxBytes || r.maxDeliveryFrames > r.maxFrames) && n(), Object.freeze(r);
+};
+export { r as defaultRoomSpectatorPolicy };