eraspace 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "eraspace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "eraspace: build, deploy and manage eraspace capsules",
+  "type": "module",
+  "keywords": [
+    "eraspace",
+    "cli",
+    "realtime",
+    "preact",
+    "v8"
+  ],
+  "license": "MIT",
+  "bin": {
+    "eraspace": "bin.js"
+  },
+  "eraspace": {
+    "command": "npx eraspace"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@preact/signals": "2.11.3",
+    "@tailwindcss/node": "4.3.3",
+    "@tailwindcss/oxide": "4.3.3",
+    "esbuild": "0.28.2",
+    "oxc-parser": "0.154.0",
+    "preact": "11.0.1",
+    "preact-iso": "2.12.2",
+    "tailwindcss": "4.3.3",
+    "typescript": "7.0.2"
+  }
+}

package/sdk/src/client/client.ts

@@ -0,0 +1,171 @@
+import { computed, type ReadonlySignal } from "@preact/signals";
+import { useEffect, useMemo, useRef, useState } from "preact/hooks";
+import { createStorageClient } from "./storage.ts";
+import { useUpload, type UseUploadOptions } from "./files.ts";
+import type { ClientOptions } from "./config.ts";
+import { subKey, stableStringify } from "./sub-key.ts";
+import type { Subscription } from "./subscription.ts";
+import type { RoomConn } from "./room.ts";
+import type { EraspaceClient, Room } from "./types.ts";
+import { EraspaceError } from "./errors.ts";
+import { ClientImpl } from "./connection.ts";
+import { Pager } from "./pagination.ts";
+
+export { readConfig, type EraspaceConfig, type ClientOptions } from "./config.ts";
+export { subKey } from "./sub-key.ts";
+export type { EraspaceClient, Room, PresenceEntry, MutationOptions, OptimisticStore, PaginatedQueryName, PaginatedQueryResult } from "./types.ts";
+
+type Fn = (...args: any[]) => any;
+
+/**
+ * Create the typed client. Import the server definition with `import type app from "../server/index"`, then
+ * `const client = createClient<typeof app>()`. Options default to `window.__ERASPACE__`.
+ */
+export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C> {
+  let impl: ClientImpl | undefined;
+  // Lazy so a module-level createClient() costs nothing until first use.
+  const get = () => (impl ??= new ClientImpl(options));
+
+  function useSubscription(name: string, args: unknown[]): Subscription {
+    const c = get();
+    const sub = c.acquire(name, args);
+    useEffect(() => {
+      c.retain(sub);
+      return () => c.release(sub);
+    }, [sub]);
+    return sub;
+  }
+
+  function useQuerySignal(name: string, ...args: unknown[]): ReadonlySignal<unknown> {
+    const sub = useSubscription(name, args);
+    return useMemo(() => computed(() => {
+      const err = sub.error.value;
+      const value: unknown = sub.value.value;
+      // Retried failures keep showing the last value; a gone app cannot recover.
+      if (err && (value === undefined || err.name === "AppGone")) throw err;
+      return value;
+    }), [sub]);
+  }
+
+  function useQuerySelector(name: string, args: unknown[], select: (value: unknown) => unknown): unknown {
+    const result = useQuerySignal(name, ...args);
+    const selected = useMemo(() => computed(() => select(result.value)), [result, select]);
+    return selected.value;
+  }
+
+  function useQuery(name: string, ...args: unknown[]): unknown {
+    return useQuerySignal(name, ...args).value;
+  }
+
+  function useMutation(name: string, opts?: { optimistic?: Fn }) {
+    const ref = useRef(opts);
+    ref.current = opts;
+    return useMemo(() => (...args: unknown[]) => get().mutate(name, args, ref.current?.optimistic), [name]);
+  }
+
+  function useAction(name: string) {
+    return useMemo(() => (...args: unknown[]) => get().call(name, args, "action"), [name]);
+  }
+
+  function usePaginatedQuery(name: string, args: unknown[], opts?: { initialNumItems?: number }) {
+    const c = get();
+    const n = opts?.initialNumItems ?? 20;
+    const key = subKey(name, args) + ":" + n;
+    const pager = useMemo(() => new Pager(c, name, args, n), [key]);
+    useEffect(() => {
+      pager.start();
+      return () => pager.stop();
+    }, [pager]);
+    const { results, status } = pager.result.value;
+    return {
+      results,
+      status,
+      isLoading: status === "LoadingFirstPage" || status === "LoadingMore",
+      loadMore: (k?: number) => pager.loadMore(k),
+      reset: () => pager.reset(),
+    };
+  }
+
+  function useRoomConn(room: string, meta: Record<string, unknown> | undefined): RoomConn {
+    const c = get();
+    const [generation, renew] = useState(0);
+    // Acquiring during render holds nothing: only a committed effect retains the room.
+    const r = useMemo(() => c.acquireRoom(room), [room, generation]);
+    useEffect(() => {
+      if (!c.retainRoom(r)) {
+        // Dropped between render and commit.
+        renew((n) => n + 1);
+        return;
+      }
+      return () => c.releaseRoom(r);
+    }, [r]);
+    const metaKey = meta === undefined ? undefined : stableStringify(meta);
+    useEffect(() => {
+      if (meta !== undefined) r.setMeta(meta);
+    }, [r, metaKey]);
+    return r;
+  }
+
+  function usePresence(room: string, meta?: Record<string, unknown>) {
+    return useRoomConn(room, meta).members.value;
+  }
+
+  function useRoom(room: string, meta?: Record<string, unknown>): Room<any, any> {
+    const r = useRoomConn(room, meta);
+    return {
+      presence: r.members.value,
+      self: r.self.value,
+      state: r.state.value,
+      error: r.error.value,
+      broadcast: (event: string, payload?: unknown) => {
+        void r.channel.push("broadcast", { event, payload: payload ?? null }).catch(error => { r.error.value = EraspaceError.from(error); });
+      },
+      on: (event: string, cb: (payload: any, from: string | undefined) => void) => {
+        let set = r.listeners.get(event);
+        if (!set) r.listeners.set(event, (set = new Set()));
+        set.add(cb);
+        return () => set!.delete(cb);
+      },
+      setState: (key: string, value: unknown) => {
+        r.setState(key, value);
+      },
+    };
+  }
+
+  const storage = createStorageClient(() => get().base);
+  const client = {
+    storage,
+    useUpload: (opts?: UseUploadOptions) => useUpload(storage, opts),
+    useQuery,
+    useQuerySignal,
+    useQuerySelector,
+    useMutation,
+    useAction,
+    usePaginatedQuery,
+    usePresence,
+    useRoom,
+    query: (name: string, ...args: unknown[]) => get().call(name, args),
+    mutation: (name: string, ...args: unknown[]) => get().mutate(name, args),
+    retryMutation: (name: string, args: unknown[], requestKey: string) => get().retryMutation(name, args, requestKey),
+    action: (name: string, ...args: unknown[]) => get().call(name, args, "action"),
+    subscribe: (name: string, args: unknown[], onValue: Fn, onError?: Fn) => get().subscribe(name, args, onValue, onError),
+    get app() {
+      return get().app;
+    },
+    get base() {
+      return get().base;
+    },
+    get guestId() {
+      return get().self.value;
+    },
+    get status() {
+      return get().status;
+    },
+    get version() {
+      return get().version;
+    },
+    onDeployed: (cb: (v: number) => void) => get().onDeployedCb(cb),
+    close: () => impl?.close(),
+  };
+  return client as unknown as EraspaceClient<C>;
+}

package/sdk/src/client/config.ts

@@ -0,0 +1,39 @@
+import type { SocketOptions, WebSocketConstructor } from "./transport.ts";
+
+/** `window.__ERASPACE__`, injected by the platform's HTML shell (SPEC §6). */
+export interface EraspaceConfig {
+  app: string;
+  base: string;
+  version: number;
+  socket: string;
+}
+
+export interface ClientOptions {
+  app?: string;
+  /** Socket endpoint, e.g. `/socket` or `ws://localhost:4000/socket`. */
+  socket?: string;
+  base?: string;
+  version?: number;
+  /** Reload the page when the app is redeployed. Default `false`. */
+  reloadOnDeploy?: boolean;
+  /** Push timeout in ms. Default 15000. */
+  timeout?: number;
+  /** Delay before an unused subscription is dropped. Default 50 ms. */
+  unsubscribeDelayMs?: number;
+  /** Delay before refreshing a subscription still waiting for a mutation commit. Default 2000 ms. */
+  optimisticTimeoutMs?: number;
+  /** WebSocket constructor (tests, non-browser runtimes). */
+  transport?: WebSocketConstructor;
+  /** Reconnect and rejoin delay overrides. */
+  socketOptions?: Pick<SocketOptions, "reconnectAfterMs" | "rejoinAfterMs">;
+}
+
+declare global {
+  interface Window {
+    __ERASPACE__?: EraspaceConfig;
+  }
+}
+
+export function readConfig(): Partial<EraspaceConfig> {
+  return (typeof window !== "undefined" && window.__ERASPACE__) || {};
+}

package/sdk/src/client/connection.ts

@@ -0,0 +1,450 @@
+import { Socket, type Channel } from "./transport.ts";
+import { signal, effect, batch, type Signal } from "@preact/signals";
+import { applyPatch } from "./result-diff.ts";
+import { EraspaceError, OutcomeUnknownError } from "./errors.ts";
+import { readConfig, type ClientOptions } from "./config.ts";
+import { requestKey } from "./request-key.ts";
+import { subKey } from "./sub-key.ts";
+import { Subscription, type FullResult, type DataMessage } from "./subscription.ts";
+import { RoomConn } from "./room.ts";
+import { retryDelay } from "./retry.ts";
+import type { Status } from "./types.ts";
+
+type Fn = (...args: any[]) => any;
+
+export class ClientImpl {
+  readonly app: string;
+  readonly base: string;
+  readonly self = signal("");
+  readonly status = signal<Status>("connecting");
+  readonly version: Signal<number>;
+  private opts: ClientOptions;
+  private socketUrl: string;
+  private socket: Socket | undefined;
+  private channel: Channel | undefined;
+  private joinedOnce = false;
+  /** Counts app channel joins. Server subscription ids live only as long as the join that created them. */
+  private joins = 0;
+  /** Server time minus local time, from the latest join reply. */
+  private clockOffset = 0;
+  private gone: EraspaceError | undefined;
+  private nextSub = 1;
+  private nextMutation = 1;
+  private subs = new Map<string, Subscription>();
+  private subsById = new Map<string, Subscription>();
+  private rooms = new Map<string, RoomConn>();
+  private deployedCbs = new Set<(v: number) => void>();
+
+  constructor(opts: ClientOptions) {
+    const cfg = readConfig();
+    this.opts = opts;
+    this.app = opts.app ?? cfg.app ?? "";
+    if (!this.app) throw new Error("eraspace: createClient() needs an app (window.__ERASPACE__ is missing)");
+    this.base = opts.base ?? cfg.base ?? `/${this.app}/`;
+    this.socketUrl = opts.socket ?? cfg.socket ?? "/socket";
+    this.version = signal(opts.version ?? cfg.version ?? 0);
+  }
+
+  // -- connection -----------------------------------------------------------------------------------------------
+
+  private ensureSocket(): Socket {
+    if (this.socket) return this.socket;
+    const socket = new Socket(this.socketUrl, {
+      timeout: this.opts.timeout,
+      ...this.opts.socketOptions,
+      transport: this.opts.transport,
+    });
+    socket.onOpen(() => { this.status.value = "open"; });
+    socket.onClose(() => { this.status.value = "closed"; });
+    socket.connect();
+    this.socket = socket;
+    return socket;
+  }
+
+  private ensureChannel(): Channel {
+    if (this.channel) return this.channel;
+    const socket = this.ensureSocket();
+    const channel = socket.channel(`app:${this.app}`, {});
+    channel.on("data", (m: DataMessage) => this.onData(m));
+    channel.on("error", (m: { id?: string; name?: string; message?: string }) => {
+      const sub = m.id !== undefined ? this.subsById.get(String(m.id)) : undefined;
+      if (sub) {
+        sub.error.value = EraspaceError.from(m);
+        this.retrySub(sub);
+      }
+    });
+    channel.on("gone", () => this.onGone());
+    // Transport loss changes status; reconnect rejoins and resubscribes while cached values stay valid.
+    // A join the server rejects is reported to every subscription.
+    const failed = (payload: unknown, rejected: boolean) => {
+      if (this.gone) return;
+      if (payload instanceof EraspaceError && payload.name === "AppGone") { this.onGone(); return; }
+      this.status.value = "closed";
+      if (rejected) for (const sub of this.subs.values()) sub.error.value = EraspaceError.from(payload, "App channel join failed");
+    };
+    channel.onError((reason, rejected) => failed(reason, rejected));
+    channel.onClose(() => failed(undefined, false));
+    channel.on("deployed", (m: { version?: number }) => this.onDeployed(m?.version));
+    channel.onJoin((resp) => {
+      this.joins++;
+      if (this.gone) return;
+      this.status.value = "open";
+      if (resp && typeof resp.self === "string") this.self.value = resp.self;
+      if (resp && typeof resp.now === "number") this.clockOffset = resp.now - Date.now();
+      // The channel process is new after a reconnect, so every live subscription is sent again.
+      if (this.joinedOnce) this.resubscribeAll();
+      this.joinedOnce = true;
+    });
+    channel.join();
+    this.channel = channel;
+    return channel;
+  }
+
+  private push<T>(event: string, payload: object | (() => object | null)): Promise<T> {
+    if (this.gone) return Promise.reject(this.gone);
+    const channel = this.ensureChannel();
+    return channel.push<T>(event, payload, this.opts.timeout ?? 15000);
+  }
+
+  async call(fn: string, args: unknown[], kind: "query" | "action" = "query"): Promise<unknown> {
+    const key = this.requestKey();
+    try {
+      const resp = await this.push<{ value?: unknown }>("call", { fn, args, kind, key });
+      return resp?.value;
+    } catch (error) {
+      if (kind === "action" && error instanceof EraspaceError && ["TimeoutError", "OutcomeUnknownError"].includes(error.name)) {
+        throw new OutcomeUnknownError(key, "The action may have performed effects; it cannot be replayed safely");
+      }
+      throw error;
+    }
+  }
+
+  /** Request keys carry server time, so a skewed client clock cannot place them outside the retry window. */
+  private requestKey(): string {
+    return requestKey(Date.now() + this.clockOffset);
+  }
+
+  private async mutationRequest(fn: string, args: unknown[], key = this.requestKey(), retry = false): Promise<{ value: unknown; commitSeq?: number }> {
+    let rekeyed = false;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await this.push("call", { fn, args, kind: "mutation", key, retry });
+      } catch (error) {
+        // The server refused the key before running anything. The join reply has corrected the clock by now.
+        if (error instanceof EraspaceError && error.name === "RequestKeyError" && !retry && !rekeyed) {
+          rekeyed = true;
+          attempt--;
+          key = this.requestKey();
+          continue;
+        }
+        const uncertain = error instanceof EraspaceError && ["TimeoutError", "OutcomeUnknownError", "RetryExpiredError"].includes(error.name);
+        // A rejected recovery attempt cannot resolve the original request's unknown outcome.
+        if (!uncertain && !retry) throw error;
+        if (uncertain && attempt === 0 && error.name !== "RetryExpiredError") {
+          retry = true;
+          continue;
+        }
+        const message = error instanceof Error ? error.message : "Recovery failed";
+        throw new OutcomeUnknownError(key, `${message}. Recover this mutation only with the same request key.`);
+      }
+    }
+  }
+
+  async retryMutation(fn: string, args: unknown[], key: string): Promise<unknown> {
+    return (await this.mutationRequest(fn, args, key, true)).value;
+  }
+
+  close(): void {
+    for (const sub of this.subs.values()) {
+      clearTimeout(sub.timer);
+      clearTimeout(sub.retryTimer);
+      sub.request++;
+    }
+    for (const r of this.rooms.values()) r.close();
+    this.rooms.clear();
+    this.channel?.leave();
+    this.socket?.disconnect();
+    this.channel = undefined;
+    this.socket = undefined;
+    this.subs.clear();
+    this.subsById.clear();
+    this.joinedOnce = false;
+    this.status.value = "closed";
+  }
+
+  private onGone(): void {
+    this.gone = new EraspaceError("AppGone", "This app is no longer serving");
+    for (const sub of this.subs.values()) {
+      clearTimeout(sub.retryTimer);
+      sub.retryTimer = undefined;
+      sub.request++;
+      sub.error.value = this.gone;
+    }
+    for (const r of this.rooms.values()) r.close();
+    this.channel?.leave();
+    this.socket?.disconnect();
+    this.status.value = "closed";
+  }
+
+  private retrySub(sub: Subscription): void {
+    if (this.gone || sub.retryTimer || this.subs.get(sub.key) !== sub) return;
+    sub.retryTimer = setTimeout(() => {
+      sub.retryTimer = undefined;
+      if (this.subs.get(sub.key) === sub) this.sendSub(sub);
+    }, retryDelay(++sub.retries));
+  }
+
+  // -- subscriptions --------------------------------------------------------------------------------------------
+
+  private sendSub(sub: Subscription): void {
+    if (this.gone) { sub.error.value = this.gone; return; }
+    clearTimeout(sub.retryTimer);
+    sub.retryTimer = undefined;
+    const oldId = sub.id;
+    const request = ++sub.request;
+    if (request > 1) {
+      this.subsById.delete(oldId);
+      sub.id = String(this.nextSub++);
+      this.subsById.set(sub.id, sub);
+      sub.revision = undefined;
+      this.unsubscribe(sub, oldId);
+    }
+    const id = sub.id;
+    this.push<FullResult>("sub", () => {
+      // A newer request or a drop replaced this one before it was sent: withdraw it.
+      if (sub.request !== request) return null;
+      sub.sent = { id, join: this.joins };
+      return { id, fn: sub.fn, args: sub.args, minCommitSeq: Math.max(0, ...sub.layers.map(layer => layer.commitSeq ?? 0)) };
+    }).then(
+      (resp) => {
+        if (this.subsById.get(sub.id) !== sub || sub.request !== request) return;
+        this.setServer(sub, resp.value, resp.commitSeq, resp.revision);
+      },
+      (err: EraspaceError) => {
+        if (this.subsById.get(sub.id) === sub && sub.request === request) {
+          sub.error.value = err;
+          this.retrySub(sub);
+        }
+      },
+    );
+  }
+
+  /** Tells the server to drop `id`, unless the server cannot have it: never sent, or sent before a reconnect. */
+  private unsubscribe(sub: Subscription, id: string): void {
+    if (sub.sent?.id !== id || sub.sent.join !== this.joins) return;
+    sub.sent = undefined;
+    this.push("unsub", { id }).catch(() => {});
+  }
+
+  // Messages for one subscription id arrive in order, so only commit watermarks are compared. Revisions
+  // belong to a server cache entry and may restart lower when an identity-dependent query splits.
+  private setServer(sub: Subscription, value: unknown, commitSeq: number, revision: number): void {
+    if (commitSeq < sub.commitSeq) return;
+    clearTimeout(sub.retryTimer);
+    sub.retryTimer = undefined;
+    sub.retries = 0;
+    batch(() => {
+      sub.server = value;
+      sub.hasServer = true;
+      sub.commitSeq = commitSeq;
+      sub.revision = revision;
+      sub.layers = sub.layers.filter((l) => l.commitSeq === undefined || l.commitSeq > commitSeq);
+      sub.error.value = undefined;
+      sub.recompute();
+    });
+  }
+
+  private onData(message: DataMessage): void {
+    if (this.gone) return;
+    const sub = this.subsById.get(String(message.id));
+    if (!sub || message.commitSeq < sub.commitSeq) return;
+    if ("patch" in message) {
+      if (!sub.hasServer || sub.revision !== message.base) {
+        this.sendSub(sub);
+        return;
+      }
+      try {
+        this.setServer(sub, applyPatch(sub.server, message.patch), message.commitSeq, message.revision);
+      } catch {
+        this.sendSub(sub);
+      }
+    } else {
+      this.setServer(sub, message.value, message.commitSeq, message.revision);
+    }
+  }
+
+  private resubscribeAll(): void {
+    for (const sub of this.subs.values()) this.sendSub(sub);
+  }
+
+  // Subscriptions survive a deploy: the server re-runs them with the new code and pushes changed values.
+  private onDeployed(version: number | undefined): void {
+    if (typeof version === "number") this.version.value = version;
+    for (const cb of [...this.deployedCbs]) cb(this.version.value);
+    if (this.opts.reloadOnDeploy && typeof location !== "undefined") location.reload();
+  }
+
+  onDeployedCb(cb: (v: number) => void): () => void {
+    this.deployedCbs.add(cb);
+    return () => this.deployedCbs.delete(cb);
+  }
+
+  /** Get or create the subscription for `(fn, args)`. A new sub with no retainers is dropped after a grace period. */
+  acquire(fn: string, args: unknown[]): Subscription {
+    const key = subKey(fn, args);
+    let sub = this.subs.get(key);
+    if (!sub) {
+      sub = new Subscription(String(this.nextSub++), fn, args, key);
+      this.subs.set(key, sub);
+      this.subsById.set(sub.id, sub);
+      this.sendSub(sub);
+    }
+    if (sub.refs === 0) this.scheduleDrop(sub, 1000);
+    return sub;
+  }
+
+  retain(sub: Subscription): void {
+    if (this.subs.get(sub.key) !== sub) {
+      // Dropped in the meantime: bring it back.
+      const existing = this.subs.get(sub.key);
+      if (existing) sub = existing;
+      else {
+        this.subs.set(sub.key, sub);
+        this.subsById.set(sub.id, sub);
+        this.sendSub(sub);
+      }
+    }
+    sub.refs++;
+    if (sub.timer) clearTimeout(sub.timer);
+    sub.timer = undefined;
+  }
+
+  release(sub: Subscription): void {
+    const live = this.subs.get(sub.key);
+    if (!live) return;
+    live.refs = Math.max(0, live.refs - 1);
+    if (live.refs === 0) this.scheduleDrop(live, this.opts.unsubscribeDelayMs ?? 50);
+  }
+
+  private scheduleDrop(sub: Subscription, ms: number): void {
+    if (sub.timer) clearTimeout(sub.timer);
+    sub.timer = setTimeout(() => {
+      sub.timer = undefined;
+      if (sub.refs > 0 || this.subs.get(sub.key) !== sub) return;
+      clearTimeout(sub.retryTimer);
+      sub.retryTimer = undefined;
+      sub.request++;
+      this.subs.delete(sub.key);
+      this.subsById.delete(sub.id);
+      this.unsubscribe(sub, sub.id);
+    }, ms);
+  }
+
+  subscribe(fn: string, args: unknown[], onValue: Fn, onError?: Fn): () => void {
+    const sub = this.acquire(fn, args);
+    this.retain(sub);
+    const stop = effect(() => {
+      const err = sub.error.value;
+      const v = sub.value.value;
+      if (err) onError?.(err);
+      else if (sub.hasServer) onValue(v);
+    });
+    return () => {
+      stop();
+      this.release(sub);
+    };
+  }
+
+  // -- mutations ------------------------------------------------------------------------------------------------
+
+  async mutate(fn: string, args: unknown[], optimistic?: Fn): Promise<any> {
+    if (!optimistic) return (await this.mutationRequest(fn, args)).value;
+    const mid = this.nextMutation++;
+    const touched = new Set<Subscription>();
+    const store = {
+      get: (name: string, qargs: unknown[]) => this.subs.get(subKey(name, qargs))?.value.peek(),
+      set: (name: string, qargs: unknown[], value: unknown) => this.addLayer(mid, name, qargs, () => value, touched),
+      update: (name: string, qargs: unknown[], updater: Fn) =>
+        this.addLayer(mid, name, qargs, (prev) => (prev === undefined ? prev : updater(prev)), touched),
+    };
+    try {
+      batch(() => optimistic(store, ...args));
+      const { value, commitSeq } = await this.mutationRequest(fn, args);
+      const timeout = this.opts.optimisticTimeoutMs ?? 2000;
+      for (const sub of touched) {
+        // Only mutations report a commit. Without one, no watermark can cover the layer.
+        if (typeof commitSeq !== "number") {
+          setTimeout(() => this.dropLayers(sub, mid), timeout);
+          continue;
+        }
+        for (const l of sub.layers) {
+          if (l.mid !== mid) continue;
+          l.commitSeq = commitSeq;
+        }
+        if (sub.commitSeq >= commitSeq) this.dropLayers(sub, mid);
+        else setTimeout(() => {
+          if (sub.layers.some((l) => l.mid === mid) && this.subs.get(sub.key) === sub) this.sendSub(sub);
+        }, timeout);
+      }
+      return value;
+    } catch (e) {
+      for (const sub of touched) this.dropLayers(sub, mid);
+      throw e;
+    }
+  }
+
+  private addLayer(mid: number, name: string, args: unknown[], apply: Fn, touched: Set<Subscription>): void {
+    const sub = this.subs.get(subKey(name, args));
+    if (!sub) return;
+    sub.layers.push({ mid, apply });
+    touched.add(sub);
+    sub.recompute();
+  }
+
+  private dropLayers(sub: Subscription, mid: number): void {
+    const before = sub.layers.length;
+    sub.layers = sub.layers.filter((l) => l.mid !== mid);
+    if (sub.layers.length !== before) sub.recompute();
+  }
+
+  // -- rooms ----------------------------------------------------------------------------------------------------
+
+  /**
+   * Get or create the room for `room`. Like a subscription, it is only held once retained: a render that never
+   * commits leaves an unretained room, which is dropped after a grace period.
+   */
+  acquireRoom(room: string): RoomConn {
+    const topic = `room:${this.app}:${room}`;
+    let r = this.rooms.get(topic);
+    if (!r) {
+      r = new RoomConn(this.ensureSocket(), topic, this.self);
+      this.rooms.set(topic, r);
+    }
+    if (r.refs === 0) this.scheduleRoomDrop(r, 1000);
+    return r;
+  }
+
+  /** False when the room was dropped after it was acquired; acquire it again. */
+  retainRoom(r: RoomConn): boolean {
+    if (this.rooms.get(r.topic) !== r) return false;
+    clearTimeout(r.timer);
+    r.timer = undefined;
+    r.refs++;
+    return true;
+  }
+
+  releaseRoom(r: RoomConn): void {
+    r.refs = Math.max(0, r.refs - 1);
+    if (r.refs === 0) this.scheduleRoomDrop(r, this.opts.unsubscribeDelayMs ?? 50);
+  }
+
+  private scheduleRoomDrop(r: RoomConn, ms: number): void {
+    clearTimeout(r.timer);
+    r.timer = setTimeout(() => {
+      r.timer = undefined;
+      if (r.refs > 0 || this.rooms.get(r.topic) !== r) return;
+      this.rooms.delete(r.topic);
+      r.close();
+    }, ms);
+  }
+}