svelte-realtime 0.6.0-next.21 → 0.6.0-next.23

package/README.md

@@ -2933,6 +2933,39 @@ How it behaves:
 
 `tolerance` (per call: `ctx.compensate(t, fn, { tolerance: 20 })`) skips the rewind when the stamp is within that many milliseconds of now - the low-latency common case.
 
+### Room enumeration (lobby browser)
+
+A lobby browser needs to list the *active* rooms of a type - the open games, and how many players are in each. Opt in with a `meta` function (or `enumerable: true` for a count-only list) and the export gains a `rooms()` view:
+
+```js
+export const game = live.room({
+  topic: (ctx, id) => 'game:' + id,
+  topicArgs: 1,
+  init: async (ctx, id) => loadGame(id),
+  meta: (id) => ({ name: nameFor(id), map: mapFor(id), cap: 32 })   // opt-in; resolved once when a room opens
+});
+```
+```svelte
+<script>
+  import { game } from '$live/game';
+  const lobby = game.rooms();   // a snapshot, then live
+  $effect(() => () => lobby.destroy());
+</script>
+
+{#each [...lobby.rooms] as [id, r] (id)}
+  <a href={'/game/' + id}>{r.meta.name} - {r.count}/{r.meta.cap}</a>
+{/each}
+```
+
+How it behaves:
+
+- **A room is "active" while it has a subscriber.** The first client to subscribe to a topic (`game:7`) opens that room in the enumeration; the last to leave closes it. `count` is the live subscriber count and moves as players join and leave. The view is a snapshot on subscribe, then live deltas - no polling.
+- **`lobby.rooms` is a reactive `Map` keyed by the room args** - the single arg (a `gameId`) when the room takes one, else the joined args. Each value is `{ args, count, meta }`. `lobby.list()` returns a one-shot snapshot array without opening a live subscription (for a `+page.server` load or a one-off fetch).
+- **`meta(args)` is resolved once, when the room opens** (its first subscriber), and frozen - it is the room's display card (name, map, cap). A throwing `meta` never blocks the room; the room appears with an empty meta. Mutable per-room state belongs in the room's own data stream, not in `meta`.
+- **Off by default.** A room without `meta` or `enumerable` installs no registry and no enumeration stream, so it is byte-identical to a plain room - you pay only when you browse.
+
+Single-instance today: `rooms()` lists the rooms active on the instance the client is connected to. Cluster-wide aggregation (a Redis roster unioning every instance's active rooms) is a separate, additive step; until it lands, host a lobby browser on a single instance or one all its viewers share.
+
 ---
 
 ## Multiplayer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.6.0-next.21",
+  "version": "0.6.0-next.23",
   "publishConfig": {
     "tag": "next"
   },
@@ -44,6 +44,10 @@
       "types": "./src/client-doc.d.ts",
       "default": "./src/client-doc.svelte.js"
     },
+    "./rooms": {
+      "types": "./src/client-rooms.d.ts",
+      "default": "./src/client-rooms.svelte.js"
+    },
     "./vite": {
       "types": "./src/vite.d.ts",
       "default": "./src/vite.js"

package/src/client-rooms.d.ts

@@ -0,0 +1,32 @@
+/** One active room in a lobby view. */
+export interface RoomEntry<Meta = any> {
+	/** The room-identifying args (e.g. `[gameId]`), as the topic function received them. */
+	args: any[];
+	/** Live subscriber count (connections subscribed to the room on this instance). */
+	count: number;
+	/** The value the export's `meta(args)` returned when the room opened, or `undefined`. */
+	meta: Meta;
+}
+
+/**
+ * Live view of a `live.room` export's ACTIVE rooms - the backing for a lobby
+ * browser. Subscribe through the generated `game.rooms()`; reads through Svelte 5
+ * runes (the view is a rune class, so it requires Svelte 5). The server keeps it
+ * current as rooms open (first subscriber), fill/empty (count), and close (last
+ * subscriber leaves).
+ */
+export class RoomsList<Meta = any> {
+	constructor(deps: {
+		stream: { subscribe: (fn: (v: any) => void) => () => void };
+		status?: { subscribe: (fn: (v: string) => void) => () => void };
+		list?: (...args: any[]) => Promise<any>;
+	});
+	/** Reactive map of active rooms, keyed by room args (the single arg when there is one, else joined). */
+	readonly rooms: Map<string, RoomEntry<Meta>>;
+	/** The connection-status passthrough. */
+	readonly status: string;
+	/** One-shot snapshot of the active rooms without opening a live subscription. */
+	list(): Promise<Array<RoomEntry<Meta>>>;
+	/** Stop the live subscription. Call from the component's cleanup. */
+	destroy(): void;
+}

package/src/client-rooms.svelte.js

@@ -0,0 +1,103 @@
+// @ts-check
+
+/**
+ * A stable per-room key for the lobby Map: the single room arg (a gameId) when
+ * the room takes exactly one, the joined args when it takes several, else the
+ * wire topic. Each rendered value keeps the raw `args` so an app addresses a
+ * room however it declared it.
+ * @param {{ topic?: string, args?: any[] }} e
+ * @returns {string}
+ */
+function _roomKey(e) {
+	const args = Array.isArray(e.args) ? e.args : [];
+	if (args.length === 1) return String(args[0]);
+	if (args.length > 1) return args.map(String).join(':');
+	return /** @type {string} */ (e.topic);
+}
+
+/**
+ * Normalize a wire entry to the public `{ args, count, meta }` shape.
+ * @param {{ args?: any[], count?: number, meta?: any }} e
+ */
+function _roomEntry(e) {
+	return {
+		args: Array.isArray(e.args) ? e.args : [],
+		count: typeof e.count === 'number' ? e.count : 0,
+		meta: e.meta
+	};
+}
+
+/**
+ * Project the enumeration stream's flat entry list into a Map keyed by room
+ * args. The server keys the stream by wire topic (unique), so a malformed entry
+ * with neither a topic nor args is dropped rather than collapsing onto a shared
+ * key.
+ * @param {Array<{ topic?: string, args?: any[], count?: number, meta?: any }>} entries
+ */
+function _roomsMap(entries) {
+	const m = new Map();
+	for (const e of entries) {
+		if (e && (e.topic !== undefined || Array.isArray(e.args))) m.set(_roomKey(e), _roomEntry(e));
+	}
+	return m;
+}
+
+/**
+ * Live view of a `live.room` export's ACTIVE rooms - the backing for a lobby
+ * browser. Subscribes to the export's enumeration stream and projects its
+ * entries into a reactive Map keyed by the room's identifying args, each value
+ * `{ args, count, meta }`. The server feeds the stream as topics gain their
+ * first subscriber (a room opens), gain/lose subscribers (the live count moves),
+ * and lose their last (the room closes), so the view always reflects the open
+ * rooms and their current player counts.
+ *
+ * Mirrors `MultiplayerRoom`: subscribe in the constructor into `$state`, expose
+ * a `$derived` view, collect unsubscribes for `destroy()`. Requires Svelte 5
+ * (the view is a rune class).
+ */
+export class RoomsList {
+	#entries = $state([]);
+	#status = $state('idle');
+	#list;
+	#unsubs = [];
+
+	/**
+	 * @param {{
+	 *   stream: { subscribe: (fn: (v: any) => void) => () => void },
+	 *   status?: { subscribe: (fn: (v: string) => void) => () => void },
+	 *   list?: (...args: any[]) => Promise<any>
+	 * }} deps - `stream` is the export's enumeration stream (a crud store keyed by
+	 *   topic), `status` the optional connection-status passthrough, `list` the
+	 *   one-shot snapshot RPC.
+	 */
+	constructor(deps) {
+		this.#list = typeof deps.list === 'function' ? deps.list : null;
+		this.#unsubs.push(deps.stream.subscribe((v) => { this.#entries = Array.isArray(v) ? v : []; }));
+		if (deps.status) this.#unsubs.push(deps.status.subscribe((v) => { this.#status = v; }));
+	}
+
+	/** Reactive `Map<roomKey, { args, count, meta }>` of the active rooms. */
+	#roomsDerived = $derived(_roomsMap(this.#entries));
+	get rooms() { return this.#roomsDerived; }
+
+	/** The connection-status passthrough. */
+	get status() { return this.#status; }
+
+	/**
+	 * One-shot snapshot of the active rooms WITHOUT opening a live subscription -
+	 * the same `{ args, count, meta }` entries `rooms` holds. Resolves to an
+	 * array (empty when enumeration is unavailable).
+	 * @returns {Promise<Array<{ args: any[], count: number, meta: any }>>}
+	 */
+	async list() {
+		if (this.#list === null) return [];
+		const snap = await this.#list();
+		return Array.isArray(snap) ? snap.map(_roomEntry) : [];
+	}
+
+	/** Stop the live subscription. Call from the component's cleanup. */
+	destroy() {
+		for (const off of this.#unsubs) off();
+		this.#unsubs = [];
+	}
+}

package/src/server/dispatch.js

@@ -465,7 +465,10 @@ async function _executeStreamRpc(ws, platform, fn, ctx, args, msg, subscribedRef
 	subscribedRef.topic = topic;
 
 	if (/** @type {any} */ (fn).__onSubscribe) {
-		try { await /** @type {any} */ (fn).__onSubscribe(ctx, topic); } catch {}
+		// `streamArgs` (3rd arg) lets a room enumeration registry capture the
+		// room-identifying args of the topic that just gained a subscriber; the
+		// presence hook ignores it.
+		try { await /** @type {any} */ (fn).__onSubscribe(ctx, topic, streamArgs); } catch {}
 	}
 
 	if (/** @type {any} */ (fn).__isDerived && !state.activateDerivedCalled && !state.warnedActivateDerived) {

package/src/server/room.js

@@ -26,6 +26,12 @@ export function installRoom(seams) {
  * @returns {any}
  */
 
+// Per-export enumeration topic counter. A process-local id is enough for the
+// single-instance enumeration stream (the client reaches it through the
+// generated path, never the raw string); a future cluster-wide variant will
+// derive a stable topic from the module path so two instances of one export agree.
+let _roomsEnumSeq = 0;
+
 export const _roomRegister = function room(config) {
 	const {
 		topic: topicFn,
@@ -37,11 +43,23 @@ export const _roomRegister = function room(config) {
 		onJoin,
 		onLeave,
 		merge: mergeMode = 'crud',
-		key: keyField = 'id'
+		key: keyField = 'id',
+		meta: metaFn,
+		enumerable: enumerableFlag
 	} = config;
 
 	/** @type {any} */ (topicFn).__topicUsesCtx = true;
 
+	// Room enumeration (opt-in: a `meta` function or `enumerable: true`). When on,
+	// a per-export registry tracks which of this room's topics currently have
+	// subscribers (and how many), so `game.rooms()` can render a live lobby
+	// browser. Off by default - a room without it installs no registry hooks and
+	// no enumeration stream, so it is byte-identical to before.
+	if (metaFn !== undefined && typeof metaFn !== 'function') {
+		throw new Error('[svelte-realtime] live.room() meta must be a function (args) => ({ ... })\n  See: https://svti.me/rooms');
+	}
+	const isEnumerable = enumerableFlag === true || typeof metaFn === 'function';
+
 	// Number of room-identifying args the topic function expects (excluding ctx).
 	// Used by room actions to separate room args from action-specific payload.
 	let _roomArgCount = Math.max(0, topicFn.length - 1);
@@ -133,6 +151,55 @@ export const _roomRegister = function room(config) {
 
 	const roomExport = {};
 
+	// Enumeration registry (single-instance): which of this room's topics
+	// currently have subscribers, with a per-connection count and the `meta`
+	// captured at the moment the topic gained its first subscriber. Keyed by the
+	// data topic; the lobby-browser snapshot is `Array.from(roomsIndex.values())`.
+	const roomsIndex = new Map();
+	const enumTopic = 'rooms:' + ++_roomsEnumSeq;
+
+	// Resolve meta once, when a room opens. A throwing meta never blocks the room
+	// (the entry still appears, with empty meta); a frozen copy keeps a later
+	// reader from mutating the registry through the snapshot.
+	const _roomMeta = (args) => {
+		if (typeof metaFn !== 'function') return undefined;
+		try {
+			const m = metaFn(...args);
+			return m && typeof m === 'object' ? Object.freeze({ ...m }) : m;
+		} catch {
+			return {};
+		}
+	};
+	// First subscriber opens the room (created); later subscribers bump the count
+	// (updated). `args` is the room-identifying args of the topic, forwarded by
+	// the stream subscribe path as the hook's 3rd argument.
+	const _enumOnSub = (ctx, topic, args) => {
+		let entry = roomsIndex.get(topic);
+		if (entry === undefined) {
+			entry = { topic, args: Array.isArray(args) ? args.slice() : [], count: 1, meta: _roomMeta(args || []) };
+			roomsIndex.set(topic, entry);
+			// Publish a snapshot copy, not the live entry - the registry mutates
+			// `count` in place, so a delta must capture its value at this moment.
+			ctx.publish(enumTopic, 'created', { ...entry });
+		} else {
+			entry.count++;
+			ctx.publish(enumTopic, 'updated', { ...entry });
+		}
+	};
+	// The last subscriber to leave closes the room (deleted); otherwise the count
+	// drops to the authoritative remaining count the unsubscribe path supplies.
+	const _enumOnUnsub = (ctx, topic, remainingSubscribers) => {
+		const entry = roomsIndex.get(topic);
+		if (entry === undefined) return;
+		if (remainingSubscribers <= 0) {
+			roomsIndex.delete(topic);
+			ctx.publish(enumTopic, 'deleted', { topic });
+		} else {
+			entry.count = remainingSubscribers;
+			ctx.publish(enumTopic, 'updated', { ...entry });
+		}
+	};
+
 	const dataStream = live.stream(topicFn, async function roomInit(ctx, ...args) {
 		if (guardFn) await guardFn(ctx, ...args);
 		const result = await initFn(ctx, ...args);
@@ -144,7 +211,9 @@ export const _roomRegister = function room(config) {
 	}, {
 		merge: mergeMode,
 		key: keyField,
-		onSubscribe: presenceFn ? async (ctx, topic) => {
+		onSubscribe: (presenceFn || isEnumerable) ? async (ctx, topic, args) => {
+			if (isEnumerable) _enumOnSub(ctx, topic, args);
+			if (!presenceFn) return;
 			const userId = _getIdentityKey(ctx);
 			const refKey = topic + '\0' + userId;
 
@@ -207,7 +276,9 @@ export const _roomRegister = function room(config) {
 				}
 			}
 		} : undefined,
-		onUnsubscribe: presenceFn ? (ctx, topic) => {
+		onUnsubscribe: (presenceFn || isEnumerable) ? (ctx, topic, remainingSubscribers) => {
+			if (isEnumerable) _enumOnUnsub(ctx, topic, remainingSubscribers);
+			if (!presenceFn) return;
 			const userId = _getIdentityKey(ctx);
 			const refKey = topic + '\0' + userId;
 
@@ -254,6 +325,21 @@ export const _roomRegister = function room(config) {
 	/** @type {any} */ (roomExport).__hasPresence = !!presenceFn;
 	/** @type {any} */ (roomExport).__hasCursors = !!cursorConfig;
 	/** @type {any} */ (roomExport).__cursorThrottle = typeof cursorConfig === 'object' ? cursorConfig.throttle || 50 : 50;
+	/** @type {any} */ (roomExport).__hasRooms = isEnumerable;
+
+	// Enumeration stream (opt-in): one per-export stream whose snapshot is the
+	// active-rooms registry and whose live deltas (created/updated/deleted, fed by
+	// the data-stream subscribe hooks above) merge into the client's lobby view,
+	// keyed by topic. `__roomsSync` backs the one-shot `.list()` (snapshot, no
+	// subscription).
+	if (isEnumerable) {
+		/** @type {any} */ (roomExport).__roomsStream = live.stream(
+			enumTopic,
+			async () => Array.from(roomsIndex.values(), (e) => ({ ...e })),
+			{ merge: 'crud', key: 'topic' }
+		);
+		/** @type {any} */ (roomExport).__roomsSync = live(async () => Array.from(roomsIndex.values(), (e) => ({ ...e })));
+	}
 
 	// Presence stream (if enabled)
 	if (presenceFn) {

package/src/server/smooth.js

@@ -269,6 +269,12 @@ function _smoothRecord(name, cfg, platform, rt) {
 			lastSeenOwner: null,
 			lastRenew: 0,
 			owned: false,
+			// Owner wall-clock basis captured at a non-owner from inbound acks (which
+			// carry the owner's `t`): a forwarding edge reconstructs the owner's clock
+			// from this to measure a shot's latency on the owner's axis. Null until the
+			// first ack with a `t` lands; read only on the forwarded-shoot path.
+			lastOwnerT: null,
+			lastOwnerWall: 0,
 			// Warm-handoff snapshot state (opt-in; null/0 on the default path).
 			// `lastSnap` throttles the owner's debounced write; `pendingSnapshot`
 			// holds states recovered on acquire until each entity's real client
@@ -886,6 +892,13 @@ function _ensureSmoothCluster(smooth) {
 		onAck: (wireTopic, identity, payload) => {
 			const rec = _smoothRecByWire(wireTopic);
 			if (!rec) return;
+			// Capture the owner's wall stamp (carried on every ack) so a non-owner can
+			// reconstruct the owner's clock for an edge-measured forwarded shot. Gated
+			// on hitTest so a non-lag-comp topic pays nothing.
+			if (rec.cfg.hitTest !== undefined && payload && typeof payload.t === 'number' && Number.isFinite(payload.t)) {
+				rec.lastOwnerT = payload.t;
+				rec.lastOwnerWall = wallEpoch();
+			}
 			const ws = rec.registry.get(identity);
 			if (ws !== undefined) _smoothSendTo(rec, ws, 'ack', payload);
 		},
@@ -902,6 +915,41 @@ function _ensureSmoothCluster(smooth) {
 				_smoothRelayRemove(rec, removed[i]);
 			}
 			if (rec.authority.size === 0) _smoothForget(rec);
+		},
+		// Owner: a non-owner forwarded a client's shot. Resolve it against the ring
+		// using the EDGE-measured durations (reach width + rewind age) applied to the
+		// owner's OWN present - never re-measuring across the inter-instance hop, which
+		// would fold that hop into the window. The authoritative hit rides the owner's
+		// existing event broadcast back to the shooter's instance, so a forwarded shot
+		// needs no correlated reply.
+		onShoot: (wireTopic, identity, originInstance, payload) => {
+			const rec = _smoothRecByWire(wireTopic);
+			if (!rec || !rec.owned || rec.lagComp === null) return;
+			if (!payload || typeof payload !== 'object') return;
+			const shooterEntity = rec.authority.get(identity);
+			if (shooterEntity === undefined) return; // no entity here: this shooter cannot aim
+			const ht = rec.cfg.hitTest;
+			const reach = typeof payload.reach === 'number' && Number.isFinite(payload.reach)
+				? Math.min(payload.reach, ht.maxRewindMs)
+				: ht.maxRewindMs;
+			const rewindAge =
+				typeof payload.rewindAge === 'number' && Number.isFinite(payload.rewindAge) && payload.rewindAge >= 0
+					? payload.rewindAge
+					: null;
+			// The detection signal fires from the edge-measured picture the owner cannot
+			// recompute; a throwing hook never affects the shot.
+			if (ht.detectionHook !== undefined && payload.detect && typeof payload.detect === 'object') {
+				try {
+					// Spread the forwarded picture first, then the trusted identity, so a
+					// forged payload.detect.identity can never override the authoritative shooter.
+					ht.detectionHook({ ...payload.detect, identity });
+				} catch {
+					/* observability only */
+				}
+			}
+			const nowMono = rec.monoClock.mono(wallEpoch());
+			const rewindAt = _smoothRewindAt(nowMono, reach, rewindAge);
+			_smoothResolveShot(rec, rec.name, identity, shooterEntity, rec.platform, payload.cmd, rewindAt).catch(() => {});
 		}
 	});
 }
@@ -1082,6 +1130,240 @@ function _shotUnitDir(d) {
 	return null;
 }
 
+/**
+ * Reconstruct the topic owner's wall clock at a non-owner (the forwarding edge).
+ * The owner stamps an absolute `t` on every ack; the edge captures it with its
+ * own wall time (`onAck`), so the owner's clock "now" is that stamp plus the
+ * wall time elapsed since. Returns null until an ack with a `t` has been seen
+ * (cold start) - the edge then forwards no rewind age and the owner resolves the
+ * shot at the present (favor the defender). Wall-elapsed (not the monotonic
+ * seam) keeps it deterministic under a seeded/faked clock.
+ * @param {any} rec
+ * @returns {number | null}
+ */
+function _edgeOwnerNow(rec) {
+	if (rec.lastOwnerT === null) return null;
+	return rec.lastOwnerT + (wallEpoch() - rec.lastOwnerWall);
+}
+
+/**
+ * Convert a reach window width + a rewind age (both DURATIONS, milliseconds)
+ * into a rewindAt on a ring's own monotonic axis. A null age resolves at the
+ * present (favor the defender); otherwise the aimed instant `now - age` is
+ * floored by the reach window and capped at the present. This is the age-form of
+ * the single-instance clamp `max(now - reach, min(rtMono, now))` and is
+ * bit-identical to it for a local shot (where `age = now - rt`).
+ * @param {number} nowMono @param {number} reach @param {number | null} rewindAge
+ * @returns {number}
+ */
+function _smoothRewindAt(nowMono, reach, rewindAge) {
+	if (rewindAge === null || rewindAge === undefined) return nowMono;
+	return Math.min(nowMono, Math.max(nowMono - reach, nowMono - rewindAge));
+}
+
+/**
+ * Edge measurement for a shot: from the shot payload compute the favor-shooter
+ * reach WIDTH and the rewind AGE (both durations, axis-free), run the per-
+ * connection replay defense + latch, and - when a `detectionHook` is configured
+ * - the latency detection picture. `now` is the wall time on the OWNER's axis:
+ * `wallEpoch()` on the owner / single instance, the reconstructed owner clock on
+ * a forwarding edge (null on edge cold start -> resolve at present). Both the
+ * uplink sample and the replay latch live on this connection's `ws` (the edge
+ * always holds the real shooter socket, so the WeakMap already keys on the
+ * origin client, never the inter-instance hop). Returns the forwarded payload
+ * shape `{ cmd, reach, rewindAge, detect, nowMono }`, or null when the shot is a
+ * replayed / older render-time the latch rejects.
+ * @param {any} rec @param {any} ctx @param {any} payload @param {string} shooterKey @param {number | null} now
+ * @returns {{ cmd: any, reach: number, rewindAge: number | null, detect: any, nowMono: number | null } | null}
+ */
+function _smoothEdgeMeasure(rec, ctx, payload, shooterKey, now) {
+	const ht = rec.cfg.hitTest;
+	const cmd = payload.cmd;
+	// No owner-clock basis yet (edge cold start): forward at the present.
+	if (now === null) return { cmd, reach: ht.maxRewindMs, rewindAge: null, detect: null, nowMono: null };
+	const nowMono = rec.monoClock.mono(now);
+	const monoCorr = nowMono - now;
+	const rtStamp = payload.rt;
+	let reach = ht.maxRewindMs;
+	let rewindAge = null;
+	let detect = null;
+	if (typeof rtStamp === 'number' && Number.isFinite(rtStamp)) {
+		let st = ctx.ws ? _lcRtt.get(ctx.ws) : undefined;
+		if (ctx.ws && st === undefined) {
+			st = { tracker: createRttTracker(), lastRt: -Infinity };
+			_lcRtt.set(ctx.ws, st);
+		}
+		// Map the wall-axis render-time onto the monotonic axis so the replay
+		// defense, the latch, and the age all live on one axis (a wall backstep
+		// then stays continuous). monoCorr is zero in normal operation.
+		const rtMono = rtStamp + monoCorr;
+		// Replay defense: a real rendered instant only advances, so a render-time
+		// strictly OLDER than the last accepted one (a captured shot resent to
+		// re-resolve an old lineup) is dropped before it can resolve or forward.
+		if (st && rtMono < st.lastRt) return null;
+		const ackT = payload.ackT;
+		if (st && typeof ackT === 'number' && Number.isFinite(ackT) && ackT <= now && now - ackT <= ht.maxRewindMs) {
+			st.tracker.sample((now - ackT) / 2, nowMono);
+		}
+		// Favor-the-shooter reach width = measured uplink (max-of-recent) + the
+		// client's interpolation delay; both server-measured, clamped to the cap.
+		const maxUp = st ? st.tracker.maxUplink() : null;
+		const serverInterp = rec.interest.interpDelayMs(shooterKey, rec.tickMs, now);
+		reach = maxUp === null ? ht.maxRewindMs : Math.min(ht.maxRewindMs, maxUp + serverInterp);
+		// The rewind age is a pure duration the owner applies to its own present.
+		rewindAge = Math.max(0, now - rtStamp);
+		if (st) st.lastRt = Math.max(st.lastRt, Math.min(rtMono, nowMono));
+		if (ht.detectionHook !== undefined && st) {
+			const minUp = st.tracker.minUplink();
+			detect = {
+				minUplink: minUp,
+				maxUplink: maxUp,
+				reach,
+				interpDelay: serverInterp,
+				divergence: minUp !== null && maxUp !== null ? maxUp - minUp : 0
+			};
+		}
+	}
+	return { cmd, reach, rewindAge, detect, nowMono };
+}
+
+/**
+ * Resolve a shot against the rewound world: gate candidates at `rewindAt`, run
+ * the shot geometry from the shooter's CURRENT state, the broadphase + per-
+ * candidate narrowphase, the nearest-first `onHit` consequence, and the hit-
+ * event broadcast (plus cluster relay). Shared by the local / owner-direct shot
+ * path and the forwarded-shot owner handler; the caller computes `rewindAt`
+ * (directly from a local measurement, or from forwarded durations on the owner)
+ * and supplies the platform whose `smooth` coordinator relays the hit events.
+ * @param {any} rec @param {string} name @param {string} shooterKey
+ * @param {any} shooterEntity @param {any} ctxPlatform @param {any} cmd @param {number} rewindAt
+ */
+async function _smoothResolveShot(rec, name, shooterKey, shooterEntity, ctxPlatform, cmd, rewindAt) {
+	const ht = rec.cfg.hitTest;
+	const cluster = ctxPlatform && ctxPlatform.smooth;
+	// Candidate set, gated at the REWIND instant rather than at receipt: a target
+	// the shooter had on screen when it fired is a valid hit even if it drifted
+	// out of range in flight, and one that drifted in only after firing is not.
+	const candKeys = new Set();
+	const liveCand = rec.interest.getCandidates(shooterKey);
+	if (liveCand !== undefined) for (const k of liveCand) if (k !== shooterKey) candKeys.add(k);
+	// The geometric gate compares ring positions against the interest radius, so
+	// it is only sound when the ring records the SAME position the interest set
+	// uses (the default, where hitTest.position falls back to interest.position).
+	// A custom hitTest.position in another space, or a null rewound center, skips
+	// the gate and falls back to the receipt-time membership.
+	const gateInRingSpace = rec.cfg.hitTest.position === rec.cfg.interest.position;
+	const shooterAt = gateInRingSpace ? rec.lagComp.sample(shooterKey, rewindAt) : null;
+	let world;
+	if (shooterAt === null) {
+		if (candKeys.size === 0) return;
+		world = rec.lagComp.rewind(candKeys, rewindAt);
+	} else {
+		const radius = rec.interest.radius;
+		// Also broadphase the departed shell - entities near the shooter's rewound
+		// position the receipt-time set no longer lists (they left in flight). The
+		// exact gate below trims it back, so over-pulling is safe.
+		const near = rec.interest.candidatesAt(shooterAt.x, shooterAt.y, radius * 2);
+		for (let i = 0; i < near.length; i++) if (near[i] !== shooterKey) candKeys.add(near[i]);
+		if (candKeys.size === 0) return;
+		world = rec.lagComp.rewindWithin(candKeys, rewindAt, shooterAt.x, shooterAt.y, radius * radius);
+	}
+	if (world.size === 0) return;
+	// Shot geometry from the shooter's CURRENT state: only the targets rewind. A
+	// throw on malformed state drops the shot (favor-defender miss).
+	let origin, dir;
+	try {
+		origin = ht.shot.origin(cmd, shooterEntity.state);
+		dir = _shotUnitDir(ht.shot.dir(cmd, shooterEntity.state));
+	} catch {
+		return;
+	}
+	if (origin === null || typeof origin !== 'object' || !Number.isFinite(origin.x) || !Number.isFinite(origin.y)) return;
+	if (dir === null) return;
+	const maxDist = ht.shot.maxDist;
+	const useResolve = typeof ht.resolve === 'function';
+	// Broadphase distance cull, defaulting to maxDist plus the hitbox's own reach
+	// so a target centred just past maxDist can still be struck on its near edge.
+	const hitboxReach = useResolve
+		? Infinity
+		: ht.hitbox.shape === 'circle'
+			? ht.hitbox.radius
+			: 0.5 * Math.sqrt(ht.hitbox.w * ht.hitbox.w + ht.hitbox.h * ht.hitbox.h);
+	const bpMaxDist = ht.broadphase && ht.broadphase.maxDist ? ht.broadphase.maxDist : maxDist + hitboxReach;
+	const bpMaxSq = bpMaxDist * bpMaxDist;
+	const cone = ht.broadphase ? ht.broadphase.cone : undefined;
+	const shot = { origin, dir, maxDist };
+	// The shoot ctx is per-shot (not per-target): applyTo (authoritative cross-
+	// entity mutation) and emitEvent (the hit signal) are plain locals.
+	let armed = false;
+	const pendingEvents = [];
+	const shootCtx = {
+		identity: shooterKey,
+		platform: ctxPlatform,
+		applyTo(victimKey, victimCmd) {
+			if (typeof victimKey !== 'string') return false;
+			if (rec.authority.inject(victimKey, victimCmd)) {
+				armed = true;
+				return true;
+			}
+			return false;
+		},
+		emitEvent(type, data, opts) {
+			if (typeof type !== 'string') return;
+			pendingEvents.push({ type, data, opts });
+		}
+	};
+	// Broadphase cull + narrowphase per candidate, nearest-first. Penetration is
+	// ON by default: every aligned candidate is hit unless onHit returns { stop: true }.
+	const hits = [];
+	for (const [key, s] of world) {
+		const vx = s.x - origin.x;
+		const vy = s.y - origin.y;
+		const distSq = vx * vx + vy * vy;
+		if (distSq > bpMaxSq) continue;
+		if (cone !== undefined && cone !== null && distSq > 0) {
+			if ((vx * dir.x + vy * dir.y) / Math.sqrt(distSq) < cone) continue;
+		}
+		let hit;
+		if (useResolve) {
+			hit = ht.resolve(shot, { key, pos: { x: s.x, y: s.y }, state: s.state }, shootCtx);
+		} else if (ht.hitbox.shape === 'circle') {
+			hit = rayCircleHit(origin.x, origin.y, dir.x, dir.y, maxDist, s.x, s.y, ht.hitbox.radius);
+		} else {
+			hit = rayAabbHit(origin.x, origin.y, dir.x, dir.y, maxDist, s.x, s.y, ht.hitbox.w, ht.hitbox.h);
+		}
+		if (hit !== null && hit !== undefined && Number.isFinite(hit.dist)) {
+			hits.push({ key, pos: { x: s.x, y: s.y }, state: s.state, dist: hit.dist, point: hit.point, fallback: s.fallback });
+		}
+	}
+	if (hits.length === 0) return;
+	hits.sort((a, b) => a.dist - b.dist);
+	for (let i = 0; i < hits.length; i++) {
+		const h = hits[i];
+		const target = { key: h.key, pos: h.pos, state: h.state };
+		const info = { dist: h.dist, point: h.point, fraction: maxDist > 0 ? h.dist / maxDist : 0, rewindAt, fallback: h.fallback };
+		const verdict = await ht.onHit(shootCtx, target, info);
+		if (verdict && verdict.stop) break;
+	}
+	// onHit may have awaited; if the topic was forgotten or this instance lost
+	// ownership meanwhile, do not publish the events or arm a dead/demoted record.
+	if (_smoothTopics.get(name) !== rec || (cluster && !rec.owned)) return;
+	for (let i = 0; i < pendingEvents.length; i++) {
+		const pe = pendingEvents[i];
+		const wire = {
+			type: pe.type,
+			key: pe.opts && typeof pe.opts.key === 'string' ? pe.opts.key : shooterKey,
+			data: pe.data,
+			id: ++rec.shootEventSeq
+		};
+		_smoothPublish(rec, 'event', wire, undefined);
+		if (cluster && typeof cluster.relayBroadcast === 'function') {
+			cluster.relayBroadcast(rec.wireTopic, 'event', wire, undefined, rec.eventSeq++);
+		}
+	}
+	if (armed) _armSmoothTick(rec);
+}
+
 /**
  * Declare a topic of smoothed (predicted / reconciled) entities.
  *
@@ -1404,263 +1686,46 @@ export const _smoothRegister = function smooth(config) {
 		// No live record, or hit testing off: nothing to resolve. (Defense in depth -
 		// the RPC is only registered when hitTest is configured.)
 		if (rec === undefined || rec.lagComp === null) return;
-		// The ring and the authoritative catalog live only on the ticking owner. A
-		// non-owner shooter's shot is forwarded to the owner in a later step; until
-		// then it is inert on a non-owning instance (never resolved against an empty
-		// local ring, which would be a silent miss).
-		const cluster = ctx.platform && ctx.platform.smooth;
-		if (cluster && !rec.owned) return;
 		const shooterKey = _getIdentityKey(ctx);
+		const cluster = ctx.platform && ctx.platform.smooth;
+		if (cluster && !rec.owned) {
+			// EDGE: this instance does not own the ring (the authoritative catalog and
+			// the history ring live on the owner). Measure latency against the
+			// reconstructed owner clock, run the replay defense, and forward the
+			// bounded DURATIONS (reach width + rewind age) to the owner, which resolves
+			// the shot on its own ring axis - never re-measuring across the hop, which
+			// would fold the inter-instance latency into the reach. Inert when the
+			// coordinator predates relayShoot (an older extensions build): the shot
+			// stays a no-op, exactly as it did before forwarded shots existed.
+			if (typeof cluster.relayShoot !== 'function') return;
+			const fwd = _smoothEdgeMeasure(rec, ctx, payload, shooterKey, _edgeOwnerNow(rec));
+			if (fwd === null) return; // a replayed / older render-time, dropped at the edge
+			cluster.relayShoot(rec.wireTopic, shooterKey, cluster.instanceId, {
+				cmd: fwd.cmd,
+				reach: fwd.reach,
+				rewindAge: fwd.rewindAge,
+				...(fwd.detect && { detect: fwd.detect })
+			});
+			return;
+		}
+		// OWNER / single instance: this instance holds the ring. Measure against the
+		// local wall clock and resolve the shot here.
 		const shooterEntity = rec.authority.get(shooterKey);
 		if (shooterEntity === undefined) return; // a shooter with no entity cannot aim
 		const ht = rec.cfg.hitTest;
-		const cmd = payload.cmd;
-		const now = wallEpoch();
-		// The ring is keyed on a monotonic axis, so the rewind works on that axis too:
-		// `nowMono` is the present on it and `monoCorr` (the wall->monotonic offset, zero
-		// in normal operation) maps the client's wall-axis render-time onto it.
-		const nowMono = rec.monoClock.mono(now);
-		const monoCorr = nowMono - now;
-		// Rewind DIRECTLY to the client's absolute synced-clock renderTime (idTech3-
-		// faithful) - reconstructing `now - rtt` at receipt would re-add the uplink leg
-		// and under-compensate. The client proposes WHERE in time; the server bounds HOW
-		// WIDE the window may be from latency it measures itself. A missing / non-finite
-		// stamp resolves at the present (favor defender).
-		const rtStamp = payload.rt;
-		let rewindAt = nowMono;
-		if (typeof rtStamp === 'number' && Number.isFinite(rtStamp)) {
-			// Per-connection server-anchored latency: the client echoed the latest
-			// server stamp it saw (ackT); roundTrip = now - ackT, BOTH ends server wall
-			// times, so the client cannot fake a lower latency (only inflate it, which
-			// costs real responsiveness and is bounded below by the policy cap). Feed
-			// this shot's own sample first so even a first shot self-seeds its reach.
-			let st = ctx.ws ? _lcRtt.get(ctx.ws) : undefined;
-			if (ctx.ws && st === undefined) {
-				st = { tracker: createRttTracker(), lastRt: -Infinity };
-				_lcRtt.set(ctx.ws, st);
-			}
-			// Map the wall-axis render-time onto the ring's monotonic axis up front, so the
-			// replay defense, the latch, AND the rewind all live on that one axis. A server
-			// wall backstep steps the client's synced render-time DOWN by the same offset, so
-			// the raw stamp would look like it moved backward; on the monotonic axis it stays
-			// continuous (rtMono = the stepped-down stamp + the absorbed offset). monoCorr is
-			// zero in normal operation, so rtMono == rtStamp and nothing below changes.
-			const rtMono = rtStamp + monoCorr;
-			// Replay defense: a real rendered instant only advances, so a renderTime OLDER
-			// than the last accepted one (a captured shot resent to re-resolve an old enemy
-			// lineup) is dropped. Strict `<` admits an EQUAL stamp: a shotgun's pellets / a
-			// burst fired in one frame share the same render-time and must all resolve. A
-			// replay of a stale lineup is strictly older once the shooter has fired since, so
-			// it is still rejected. One number per connection, on the monotonic axis - so a
-			// wall backstep (which steps the raw stamp down) is not mistaken for a replay.
-			if (st && rtMono < st.lastRt) return;
-			const ackT = payload.ackT;
-			if (st && typeof ackT === 'number' && Number.isFinite(ackT) && ackT <= now && now - ackT <= ht.maxRewindMs) {
-				// Uplink is a wall-axis duration (ackT is a server wall stamp); rotate the
-				// bucket window on the monotonic axis so a wall backstep cannot disturb it.
-				st.tracker.sample((now - ackT) / 2, nowMono);
-			}
-			// Favor-the-shooter reach width = measured uplink (max-of-recent, so a latency
-			// spike never clamps an honest shot) + the client's interpolation delay. BOTH
-			// legs are now server-measured: the uplink from the ackT round trips, and the
-			// interp delay from how often the server sends THIS shooter frames (the same
-			// cadence the client measures to set its render delay). So a sparsely-served
-			// shooter, which legitimately renders further in the past, gets the wider reach
-			// it needs instead of clamping short - while a densely-served low-latency shooter
-			// stays tight (cadence == tick rate) and cannot borrow a laggy player's budget.
-			// All clamped to the policy cap.
-			const maxUp = st ? st.tracker.maxUplink() : null;
-			const serverInterp = rec.interest.interpDelayMs(shooterKey, rec.tickMs, now);
-			const reach = maxUp === null ? ht.maxRewindMs : Math.min(ht.maxRewindMs, maxUp + serverInterp);
-			// Clamp the mapped render-time into the rewind window. `min(rtMono, nowMono)`
-			// caps an over-mapped stamp (the brief post-backstep window before the client
-			// re-syncs to the stepped clock) to the present - favor defender, never a read
-			// outside the ring.
-			rewindAt = Math.max(nowMono - reach, Math.min(rtMono, nowMono));
-			// Latch the clamped monotonic value: a one-off future/overshooting renderTime is
-			// bounded by `min(rtMono, nowMono)` so it cannot strand subsequent honest shots
-			// behind an inflated floor, and because the floor lives on the monotonic axis a
-			// wall backstep (which steps the raw stamp down) does not read as a replay.
-			if (st) st.lastRt = Math.max(st.lastRt, Math.min(rtMono, nowMono));
-			// Detection signal (opt-in, off by default): surface the per-shot latency picture
-			// to an app/anti-cheat callback. The discriminating lag-switch tell is the
-			// divergence between the un-inflatable floor (minUplink) and the reach-driving max
-			// (maxUplink), plus an abrupt floor jump the app derives from the minUplink series -
-			// NOT the raw clamp rate (honest jittery/mobile players clamp routinely). This
-			// subsystem only emits; detection action lives in the app's module. A throwing hook
-			// never affects the shot (observability only).
-			if (ht.detectionHook !== undefined && st) {
-				const minUp = st.tracker.minUplink();
-				try {
-					ht.detectionHook({
-						identity: shooterKey,
-						minUplink: minUp,
-						maxUplink: maxUp,
-						reach,
-						interpDelay: serverInterp,
-						divergence: minUp !== null && maxUp !== null ? maxUp - minUp : 0
-					});
-				} catch {
-					/* observability only */
-				}
-			}
-		}
-		// Candidate set, gated at the REWIND instant rather than at receipt. The shooter
-		// aimed at the world it saw when it fired (rewindAt), so membership belongs there:
-		// a target that drifted out of the shooter's area of interest while the shot was in
-		// flight is still a valid hit (it was replicated when fired - the honest miss the
-		// receipt-time gate dropped), and one that drifted IN only after the shot was fired
-		// is not (it was never replicated at that instant). Both reduce to one geometric
-		// test on historical positions: in-gate iff dist(shooter, target) <= interest
-		// radius, both sampled at rewindAt. The transmit-bit guarantee is unchanged - you
-		// still cannot hit what the shooter never had - it is just evaluated at the right
-		// time. The set is server-computed; the client supplies no candidate list.
-		const candKeys = new Set();
-		const liveCand = rec.interest.getCandidates(shooterKey);
-		if (liveCand !== undefined) for (const k of liveCand) if (k !== shooterKey) candKeys.add(k);
-		// The geometric gate compares ring positions against the interest radius, so it is
-		// only sound when the ring records the SAME position the interest membership uses.
-		// That holds on the default path (hitTest.position falls back to interest.position,
-		// same reference); a custom hitTest.position in a different coordinate space would
-		// make the gate mix spaces, so there we skip it and fall back to the receipt-time
-		// membership (interest-space correct, just not rewindAt-precise). A null sample
-		// (shooter just spawned, pre-history, or a ring discontinuity at rewindAt) also
-		// has no usable rewound center, so it takes the same fallback.
-		const gateInRingSpace = rec.cfg.hitTest.position === rec.cfg.interest.position;
-		const shooterAt = gateInRingSpace ? rec.lagComp.sample(shooterKey, rewindAt) : null;
-		let world;
-		if (shooterAt === null) {
-			// No usable rewound gate: fall back to the receipt-time membership ungated -
-			// never worse than the pre-gate behavior.
-			if (candKeys.size === 0) return;
-			world = rec.lagComp.rewind(candKeys, rewindAt);
-		} else {
-			const radius = rec.interest.radius;
-			// Also broadphase the departed shell: entities near the shooter's rewound
-			// position that the receipt-time set no longer lists (they left during the
-			// flight window). A target must cross a full interest radius within the rewind
-			// window (<= maxRewindMs) to escape the doubled query - implausible for a radius
-			// sized to the arena - and the exact gate below trims the broadphase back to the
-			// true membership, so over-pulling is safe; under-pulling is the only real risk.
-			const near = rec.interest.candidatesAt(shooterAt.x, shooterAt.y, radius * 2);
-			for (let i = 0; i < near.length; i++) if (near[i] !== shooterKey) candKeys.add(near[i]);
-			if (candKeys.size === 0) return;
-			world = rec.lagComp.rewindWithin(candKeys, rewindAt, shooterAt.x, shooterAt.y, radius * radius);
-		}
-		if (world.size === 0) return;
-		// Shot geometry from the shooter's CURRENT state: only the targets rewind, the
-		// shooter fires from where the server says it is. The app's origin/dir are
-		// guarded like the ring's position() (lagcomp.record): a throw on malformed
-		// state drops the shot (favor-defender miss) rather than rejecting the handler.
-		let origin, dir;
-		try {
-			origin = ht.shot.origin(cmd, shooterEntity.state);
-			dir = _shotUnitDir(ht.shot.dir(cmd, shooterEntity.state));
-		} catch {
-			return;
-		}
-		if (origin === null || typeof origin !== 'object' || !Number.isFinite(origin.x) || !Number.isFinite(origin.y)) return;
-		if (dir === null) return;
-		const maxDist = ht.shot.maxDist;
-		const useResolve = typeof ht.resolve === 'function';
-		// Broadphase distance cull. The narrowphase accepts a hit whose ray ENTRY is
-		// within maxDist, but a hitbox reaches one radius (or half-diagonal) past its
-		// centre - so a target centred just beyond maxDist can still be struck on its
-		// near edge. Default the cull to maxDist + that reach so it never drops a valid
-		// hit; for a custom resolve (unknown reach) skip the distance cull entirely
-		// unless the app set an explicit broadphase.maxDist.
-		const hitboxReach = useResolve
-			? Infinity
-			: ht.hitbox.shape === 'circle'
-				? ht.hitbox.radius
-				: 0.5 * Math.sqrt(ht.hitbox.w * ht.hitbox.w + ht.hitbox.h * ht.hitbox.h);
-		const bpMaxDist = ht.broadphase && ht.broadphase.maxDist ? ht.broadphase.maxDist : maxDist + hitboxReach;
-		const bpMaxSq = bpMaxDist * bpMaxDist;
-		const cone = ht.broadphase ? ht.broadphase.cone : undefined;
-		const shot = { origin, dir, maxDist };
-		// Build the shoot ctx once (it is per-shot, not per-target): the seam where
-		// `applyTo` (authoritative cross-entity mutation) and `emitEvent` (the hit
-		// signal) are plain locals, never threaded through the authority's time-pure
-		// synchronous apply ctx.
-		let armed = false;
-		const pendingEvents = [];
-		const shootCtx = {
-			identity: shooterKey,
-			platform: ctx.platform,
-			// Apply a server-initiated command to any entity: a non-commanded update
-			// (broadcast to all incl. the victim, no ack), via the adapter authority's
-			// inject primitive. The victim's predictor is undisturbed (its ack
-			// watermark never moves); it sees the change through the normal broadcast.
-			applyTo(victimKey, victimCmd) {
-				if (typeof victimKey !== 'string') return false;
-				if (rec.authority.inject(victimKey, victimCmd)) {
-					armed = true;
-					return true;
-				}
-				return false;
-			},
-			// Queue a discrete one-shot event (a hit) for broadcast after resolution.
-			emitEvent(type, data, opts) {
-				if (typeof type !== 'string') return;
-				pendingEvents.push({ type, data, opts });
-			}
-		};
-		// Broadphase cull + narrowphase per candidate, collecting hits to order
-		// nearest-first. Penetration is ON by default: every aligned candidate is hit
-		// unless the app stops after the nearest by returning `{ stop: true }`.
-		const hits = [];
-		for (const [key, s] of world) {
-			const vx = s.x - origin.x;
-			const vy = s.y - origin.y;
-			const distSq = vx * vx + vy * vy;
-			if (distSq > bpMaxSq) continue;
-			if (cone !== undefined && cone !== null && distSq > 0) {
-				if ((vx * dir.x + vy * dir.y) / Math.sqrt(distSq) < cone) continue;
-			}
-			let hit;
-			if (useResolve) {
-				hit = ht.resolve(shot, { key, pos: { x: s.x, y: s.y }, state: s.state }, shootCtx);
-			} else if (ht.hitbox.shape === 'circle') {
-				hit = rayCircleHit(origin.x, origin.y, dir.x, dir.y, maxDist, s.x, s.y, ht.hitbox.radius);
-			} else {
-				hit = rayAabbHit(origin.x, origin.y, dir.x, dir.y, maxDist, s.x, s.y, ht.hitbox.w, ht.hitbox.h);
-			}
-			if (hit !== null && hit !== undefined && Number.isFinite(hit.dist)) {
-				hits.push({ key, pos: { x: s.x, y: s.y }, state: s.state, dist: hit.dist, point: hit.point, fallback: s.fallback });
-			}
-		}
-		if (hits.length === 0) return;
-		hits.sort((a, b) => a.dist - b.dist);
-		for (let i = 0; i < hits.length; i++) {
-			const h = hits[i];
-			const target = { key: h.key, pos: h.pos, state: h.state };
-			const info = { dist: h.dist, point: h.point, fraction: maxDist > 0 ? h.dist / maxDist : 0, rewindAt, fallback: h.fallback };
-			const verdict = await ht.onHit(shootCtx, target, info);
-			if (verdict && verdict.stop) break;
-		}
-		// The app's onHit may have awaited. If the topic was forgotten (its last
-		// entity left) or this instance lost ownership in that window, do not publish
-		// the events or arm a tick on a dead or demoted record.
-		if (_smoothTopics.get(name) !== rec || (cluster && !rec.owned)) return;
-		// Broadcast the hit events. A shot bypasses the prediction ring, so there is
-		// no optimistic client copy to suppress: the event reaches everyone, the
-		// shooter (its hit marker) and the victim alike. The wire frame carries only
-		// {type,key,data,id}, exactly as the tick's event broadcast does.
-		for (let i = 0; i < pendingEvents.length; i++) {
-			const pe = pendingEvents[i];
-			const wire = {
-				type: pe.type,
-				key: pe.opts && typeof pe.opts.key === 'string' ? pe.opts.key : shooterKey,
-				data: pe.data,
-				id: ++rec.shootEventSeq
-			};
-			_smoothPublish(rec, 'event', wire, undefined);
-			if (cluster && typeof cluster.relayBroadcast === 'function') {
-				cluster.relayBroadcast(rec.wireTopic, 'event', wire, undefined, rec.eventSeq++);
+		const m = _smoothEdgeMeasure(rec, ctx, payload, shooterKey, wallEpoch());
+		if (m === null) return;
+		// Detection signal (opt-in): fire from this shot's locally-measured picture.
+		// A throwing hook never affects the shot.
+		if (ht.detectionHook !== undefined && m.detect) {
+			try {
+				ht.detectionHook({ ...m.detect, identity: shooterKey });
+			} catch {
+				/* observability only */
 			}
 		}
-		// Arm the tick so the injected damage drains and broadcasts this frame.
-		if (armed) _armSmoothTick(rec);
+		const rewindAt = _smoothRewindAt(m.nowMono, m.reach, m.rewindAge);
+		await _smoothResolveShot(rec, name, shooterKey, shooterEntity, ctx.platform, m.cmd, rewindAt);
 	});
 
 	return smoothExport;

package/src/server.d.ts

@@ -2395,6 +2395,19 @@ export interface RoomConfig {
 	 * actions. Requires `actions`.
 	 */
 	history?: RoomHistoryConfig;
+	/**
+	 * Per-room metadata for a lobby browser, resolved once when a room opens
+	 * (its first subscriber arrives). Providing it opts the room into
+	 * enumeration, so the generated `<export>.rooms()` lists the active rooms,
+	 * each `{ args, count, meta }`. Receives the room-identifying args. A throwing
+	 * `meta` never blocks the room (the room still appears, with empty meta).
+	 */
+	meta?: (...args: any[]) => any;
+	/**
+	 * Opt into room enumeration without per-room metadata (a count-only lobby).
+	 * Implied by `meta`. @default false
+	 */
+	enumerable?: boolean;
 }
 
 /**
@@ -2406,8 +2419,13 @@ export interface RoomExport {
 	__topicFn: Function;
 	__hasPresence: boolean;
 	__hasCursors: boolean;
+	__hasRooms: boolean;
 	__presenceStream?: any;
 	__cursorStream?: any;
+	/** The enumeration stream (active rooms) when the room opts into enumeration. */
+	__roomsStream?: any;
+	/** The one-shot enumeration snapshot RPC backing `rooms().list()`. */
+	__roomsSync?: any;
 	__actions?: Record<string, any>;
 }
 

package/src/testing.js

@@ -323,6 +323,8 @@ export function createTestEnv(options) {
 				if (fn.__dataStream) __register(path + '/__data', fn.__dataStream);
 				if (fn.__presenceStream) __register(path + '/__presence', fn.__presenceStream);
 				if (fn.__cursorStream) __register(path + '/__cursors', fn.__cursorStream);
+				if (fn.__roomsStream) __register(path + '/__rooms', fn.__roomsStream);
+				if (fn.__roomsSync) __register(path + '/__roomsSync', fn.__roomsSync);
 				if (fn.__actions) {
 					for (const [k, v] of Object.entries(fn.__actions)) {
 						__register(path + '/__action/' + k, v);

package/src/vite/codegen-client.js

@@ -345,6 +345,8 @@ export function _generateClientStubs(filePath, modulePath, dir) {
 	}
 
 	// Detect live.room() exports - generates data stream + presence stream + cursor stream + actions
+	// (and the lobby-browser `rooms()` view when the room opts into enumeration).
+	let roomsRuntimeImported = false;
 	ROOM_EXPORT_RE.lastIndex = 0;
 	while ((match = ROOM_EXPORT_RE.exec(source)) !== null) {
 		const name = match[1];
@@ -356,6 +358,10 @@ export function _generateClientStubs(filePath, modulePath, dir) {
 			// Room generates a namespace object with data, presence, cursors, and actions
 			// Extract room config to determine which sub-streams exist
 			const roomInfo = _extractRoomInfo(source, name);
+			if (roomInfo.isEnumerable && !roomsRuntimeImported) {
+				lines.push(`import { RoomsList } from 'svelte-realtime/rooms';`);
+				roomsRuntimeImported = true;
+			}
 			const roomLines = [];
 			roomLines.push(`export const ${name} = {`);
 			roomLines.push(`  data: __stream(${JSON.stringify(modulePath + '/' + name + '/__data')}, ${JSON.stringify(roomInfo.dataOpts)}, true),`);
@@ -365,6 +371,12 @@ export function _generateClientStubs(filePath, modulePath, dir) {
 			if (roomInfo.hasCursors) {
 				roomLines.push(`  cursors: __stream(${JSON.stringify(modulePath + '/' + name + '/__cursors')}, ${JSON.stringify({ merge: 'cursor' })}, true),`);
 			}
+			// Lobby-browser view (opt-in): a per-export enumeration stream of the
+			// active rooms, wrapped in the RoomsList rune. `game.rooms()` takes no
+			// args (it lists the whole export); `.list()` is the one-shot snapshot.
+			if (roomInfo.isEnumerable) {
+				roomLines.push(`  rooms: () => new RoomsList({ stream: __stream(${JSON.stringify(modulePath + '/' + name + '/__rooms')}, ${JSON.stringify({ merge: 'crud', key: 'topic' })}, true)(), list: __rpc(${JSON.stringify(modulePath + '/' + name + '/__roomsSync')}) }),`);
+			}
 			// Actions are RPCs
 			for (const action of roomInfo.actions) {
 				roomLines.push(`  ${action}: __rpc(${JSON.stringify(modulePath + '/' + name + '/__action/' + action)}),`);

package/src/vite/codegen-registry.js

@@ -414,6 +414,10 @@ export function _generateRegistry(liveDir, dir, topicsRegistry) {
 				lines.push(`__register(${JSON.stringify(rel + '/' + name + '/__presence')}, __L(() => import(${importPath}).then(m => m.${name}.__presenceStream)), ${JSON.stringify(rel)});`);
 				// Register cursor stream if present
 				lines.push(`__register(${JSON.stringify(rel + '/' + name + '/__cursors')}, __L(() => import(${importPath}).then(m => m.${name}.__cursorStream)), ${JSON.stringify(rel)});`);
+				// Register the enumeration stream + one-shot snapshot if the room opted
+				// in (resolves to undefined and is never subscribed for a plain room).
+				lines.push(`__register(${JSON.stringify(rel + '/' + name + '/__rooms')}, __L(() => import(${importPath}).then(m => m.${name}.__roomsStream)), ${JSON.stringify(rel)});`);
+				lines.push(`__register(${JSON.stringify(rel + '/' + name + '/__roomsSync')}, __L(() => import(${importPath}).then(m => m.${name}.__roomsSync)), ${JSON.stringify(rel)});`);
 				// Register actions (deferred - resolved on first RPC or cron tick)
 				lines.push(`__registerRoomActions(${JSON.stringify(rel + '/' + name)}, ${_lazy(name)});`);
 			}

package/src/vite/codegen-ssr.js

@@ -177,6 +177,11 @@ export function _generateSsrStubs(filePath, modulePath) {
 			lines.push(`const _${name}_cursors = (...args) => readable(undefined);`);
 			subFactories.push(`cursors: _${name}_cursors`);
 		}
+		// The lobby-browser view renders empty during SSR (no live subscription);
+		// the client RoomsList takes over on hydration.
+		if (info.isEnumerable) {
+			subFactories.push(`rooms: () => ({ rooms: new Map(), status: 'idle', list: () => Promise.resolve([]), destroy: () => {} })`);
+		}
 		for (const action of info.actions) {
 			subFactories.push(`${action}: () => Promise.resolve(undefined)`);
 		}

package/src/vite/extract-options.js

@@ -459,7 +459,7 @@ export function _extractChannelOptions(source, name) {
  * Extract room configuration info from source code for client stub generation.
  * @param {string} source
  * @param {string} name
- * @returns {{ dataOpts: any, hasPresence: boolean, hasCursors: boolean, actions: string[] }}
+ * @returns {{ dataOpts: any, hasPresence: boolean, hasCursors: boolean, actions: string[], isEnumerable: boolean }}
  */
 /**
  * Detect a windowed `live.aggregate(...)` export and return the window
@@ -495,8 +495,8 @@ export function _extractAggregateWindows(source, name) {
 }
 
 export function _extractRoomInfo(source, name) {
-	/** @type {{ dataOpts: any, hasPresence: boolean, hasCursors: boolean, actions: string[] }} */
-	const info = { dataOpts: { merge: 'crud' }, hasPresence: false, hasCursors: false, actions: [] };
+	/** @type {{ dataOpts: any, hasPresence: boolean, hasCursors: boolean, actions: string[], isEnumerable: boolean }} */
+	const info = { dataOpts: { merge: 'crud' }, hasPresence: false, hasCursors: false, actions: [], isEnumerable: false };
 
 	// Find the start of live.room({ ... }) call
 	const startPattern = new RegExp(
@@ -512,6 +512,8 @@ export function _extractRoomInfo(source, name) {
 	const configKeys = new Set(_extractTopLevelKeys(body));
 	info.hasPresence = configKeys.has('presence');
 	info.hasCursors = configKeys.has('cursors');
+	// Room enumeration is opt-in via `enumerable: true` or a `meta` function.
+	info.isEnumerable = configKeys.has('enumerable') || configKeys.has('meta');
 
 	const mergeVal = _extractTopLevelStringProp(body, 'merge');
 	if (mergeVal) info.dataOpts.merge = mergeVal;

package/src/vite/hmr.js

@@ -104,6 +104,8 @@ export async function _loadRegistryDirect(server, liveDir, dir) {
 					if (fn.__dataStream) __register(rel + '/' + name + '/__data', fn.__dataStream, rel);
 					if (fn.__presenceStream) __register(rel + '/' + name + '/__presence', fn.__presenceStream, rel);
 					if (fn.__cursorStream) __register(rel + '/' + name + '/__cursors', fn.__cursorStream, rel);
+					if (fn.__roomsStream) __register(rel + '/' + name + '/__rooms', fn.__roomsStream, rel);
+					if (fn.__roomsSync) __register(rel + '/' + name + '/__roomsSync', fn.__roomsSync, rel);
 					if (fn.__actions) {
 						for (const [k, v] of Object.entries(fn.__actions)) {
 							__register(rel + '/' + name + '/__action/' + k, v, rel);