eraspace 0.0.0-stage → 0.1.0

package/sdk/src/client/pagination.ts

@@ -0,0 +1,101 @@
+import { signal, computed, effect, type Signal, type ReadonlySignal } from "@preact/signals";
+import type { PaginationResult } from "../server/index.ts";
+import type { PaginatedQueryResult } from "./types.ts";
+import type { ClientImpl } from "./connection.ts";
+import type { Subscription } from "./subscription.ts";
+
+export class Pager {
+  readonly pages: Signal<Subscription[]> = signal([]);
+  private stops: (() => void)[] = [];
+  private sizes: number[] = [];
+  readonly result: ReadonlySignal<{ results: any[]; status: PaginatedQueryResult<any>["status"] }>;
+  private client: ClientImpl;
+  private fn: string;
+  private prefix: unknown[];
+  private initial: number;
+
+  constructor(client: ClientImpl, fn: string, prefix: unknown[], initial: number) {
+    this.client = client;
+    this.fn = fn;
+    this.prefix = prefix;
+    this.initial = initial;
+    this.result = computed(() => {
+      const pages = this.pages.value;
+      const results: any[] = [];
+      let loading = false;
+      let done = false;
+      for (const p of pages) {
+        const err = p.error.value;
+        if (err) throw err;
+        const v = p.value.value as PaginationResult<any> | undefined;
+        if (v === undefined) {
+          loading = true;
+          break;
+        }
+        results.push(...v.page);
+        done = v.isDone;
+      }
+      const status = loading
+        ? pages.length <= 1
+          ? "LoadingFirstPage"
+          : "LoadingMore"
+        : done
+          ? "Exhausted"
+          : "CanLoadMore";
+      return { results, status } as const;
+    });
+  }
+
+  start(): void {
+    if (this.pages.peek().length === 0) this.addPage(null, this.initial);
+  }
+
+  stop(): void {
+    for (const s of this.stops) s();
+    this.stops = [];
+    this.sizes = [];
+    for (const p of this.pages.peek()) this.client.release(p);
+    this.pages.value = [];
+  }
+
+  reset(): void {
+    this.stop();
+    this.start();
+  }
+
+  loadMore(n?: number): void {
+    const pages = this.pages.peek();
+    const last = pages[pages.length - 1];
+    const v = last?.value.peek() as PaginationResult<any> | undefined;
+    if (!v || v.isDone) return;
+    this.addPage(v.continueCursor, n ?? this.initial);
+  }
+
+  private addPage(cursor: string | null, numItems: number): void {
+    const sub = this.client.acquire(this.fn, [...this.prefix, { cursor, numItems }]);
+    this.client.retain(sub);
+    const index = this.pages.peek().length;
+    this.sizes.push(numItems);
+    this.pages.value = [...this.pages.peek(), sub];
+    // If this page's end cursor moves (rows inserted/deleted), re-chain the pages after it.
+    let lastCursor: string | undefined;
+    const stop = effect(() => {
+      const v = sub.value.value as PaginationResult<any> | undefined;
+      if (!v) return;
+      if (lastCursor !== undefined && v.continueCursor !== lastCursor) this.truncateAfter(index, v);
+      lastCursor = v.continueCursor;
+    });
+    this.stops.push(stop);
+  }
+
+  private truncateAfter(index: number, v: PaginationResult<any>): void {
+    const pages = this.pages.peek();
+    if (pages.length <= index + 1) return;
+    const sizes = this.sizes.slice(index + 1);
+    for (const p of pages.slice(index + 1)) this.client.release(p);
+    for (const s of this.stops.splice(index + 1)) s();
+    this.sizes = this.sizes.slice(0, index + 1);
+    this.pages.value = pages.slice(0, index + 1);
+    if (!v.isDone) this.addPage(v.continueCursor, sizes.reduce((a, b) => a + b, 0));
+  }
+}

package/sdk/src/client/result-diff.ts

@@ -0,0 +1,41 @@
+export type Patch =
+  | { path: (string | number)[]; value: unknown }
+  | { path: (string | number)[]; remove: true }
+  | { path: (string | number)[]; index: number; deleteCount: number; items: unknown[] };
+
+/** Apply only to the server value. Optimistic layers are replayed afterwards. */
+export function applyPatch(value: unknown, patches: Patch[]): unknown {
+  return patches.reduce((current, patch) => edit(current, patch.path, patch), value);
+}
+
+function edit(value: unknown, path: (string | number)[], patch: Patch): unknown {
+  if (path.length === 0) {
+    if ("index" in patch) {
+      if (!Array.isArray(value) || patch.index < 0 || patch.index + patch.deleteCount > value.length) {
+        throw new Error("Invalid array patch");
+      }
+      const next: unknown[] = [...value];
+      next.splice(patch.index, patch.deleteCount, ...patch.items);
+      return next;
+    }
+    if ("value" in patch) return patch.value;
+    throw new Error("Cannot remove the root value");
+  }
+  const [key, ...rest] = path;
+  if (Array.isArray(value) && typeof key === "number" && key >= 0 && key < value.length) {
+    const next: unknown[] = [...value];
+    if (rest.length === 0 && "remove" in patch) next.splice(key, 1);
+    else next[key] = edit(value[key], rest, patch);
+    return next;
+  }
+  if (value !== null && typeof value === "object" && !Array.isArray(value) && typeof key === "string") {
+    const next: Record<string, unknown> = { ...value };
+    if (rest.length === 0 && "remove" in patch) delete next[key];
+    else {
+      const previous = Object.hasOwn(next, key) ? next[key] : undefined;
+      Object.defineProperty(next, key, { value: edit(previous, rest, patch), enumerable: true, writable: true, configurable: true });
+    }
+    return next;
+  }
+  throw new Error("Invalid patch path");
+}

package/sdk/src/client/room.ts

@@ -0,0 +1,58 @@
+import { Presence, type Socket, type Channel } from "phoenix";
+import { signal, type Signal } from "@preact/signals";
+import type { PresenceEntry } from "./types.ts";
+import { stableStringify } from "./sub-key.ts";
+
+export class RoomConn {
+  channel: Channel;
+  presence: Presence;
+  readonly members: Signal<PresenceEntry<any>[]> = signal([]);
+  readonly state: Signal<Record<string, unknown>> = signal({});
+  readonly self: Signal<string>;
+  refs = 0;
+  meta: Record<string, unknown> = {};
+  listeners = new Map<string, Set<(payload: any, from: string | undefined) => void>>();
+  timer: ReturnType<typeof setTimeout> | undefined;
+  readonly topic: string;
+
+  constructor(socket: Socket, topic: string, clientSelf: Signal<string>) {
+    this.topic = topic;
+    // The join reply carries the server-derived id; until then this is the id from the app channel, if known.
+    this.self = signal(clientSelf.value);
+    this.channel = socket.channel(topic, () => ({ meta: this.meta }));
+    this.presence = new Presence(this.channel);
+    this.presence.onSync(() => {
+      this.members.value = this.presence.list((id: string, entry: any) => {
+        const metas = (entry.metas ?? []).map(stripPhxRef);
+        return { id, meta: metas[0] ?? {}, metas };
+      });
+    });
+    this.channel.on("msg", (m: { event: string; payload: unknown; from?: string }) => {
+      const set = this.listeners.get(m.event);
+      if (set) for (const cb of [...set]) cb(m.payload, m.from);
+      const all = this.listeners.get("*");
+      if (all) for (const cb of [...all]) cb(m, m.from);
+    });
+    this.channel.on("state:full", (m: { state?: Record<string, unknown> }) => {
+      this.state.value = { ...(m.state ?? {}) };
+    });
+    this.channel.on("state", (m: { key: string; value: unknown }) => {
+      this.state.value = { ...this.state.value, [m.key]: m.value };
+    });
+    this.channel.join().receive("ok", (resp: { self?: string } | undefined) => {
+      if (resp && typeof resp.self === "string") this.self.value = clientSelf.value = resp.self;
+    });
+  }
+
+  setMeta(meta: Record<string, unknown>): void {
+    if (stableStringify(meta) === stableStringify(this.meta)) return;
+    this.meta = meta;
+    this.channel.push("meta", { meta });
+  }
+}
+
+function stripPhxRef(meta: any): any {
+  if (!meta || typeof meta !== "object") return meta;
+  const { phx_ref: _a, phx_ref_prev: _b, ...rest } = meta;
+  return rest;
+}

package/sdk/src/client/router.ts

@@ -0,0 +1,168 @@
+// Client routing. preact-iso's <Router> does the matching; our <LocationProvider> feeds it app-relative paths, so
+// `<Route path="/todos/:id">` matches `/<app>/todos/123`. Links and navigation add the base back.
+import { h, isValidElement, toChildArray, type ComponentChildren, type ComponentType, type Context, type JSX, type VNode } from "preact";
+import { useContext, useLayoutEffect, useMemo, useState } from "preact/hooks";
+import { LocationProvider as IsoLocationProvider, Router as IsoRouter, useLocation as isoUseLocation, useRoute } from "preact-iso/router";
+import { readConfig } from "./client.ts";
+
+export interface LocationValue {
+  /** App-relative URL including the query string, e.g. `/todos/1?x=2`. */
+  url: string;
+  /** App-relative path, e.g. `/todos/1`. */
+  path: string;
+  query: Record<string, string>;
+  /** Navigate to an app-relative URL. */
+  route(url: string, replace?: boolean): void;
+  back(): void;
+  forward(): void;
+}
+
+const ctx = (IsoLocationProvider as unknown as { ctx: Context<any> }).ctx;
+
+function normalizeBase(base: string | undefined): string {
+  let b = base ?? readConfig().base ?? "/";
+  if (!b.startsWith("/")) b = "/" + b;
+  if (!b.endsWith("/")) b += "/";
+  return b;
+}
+
+/** Strip the app base from an absolute path: `/chat/rooms/1` → `/rooms/1`. */
+export function stripBase(base: string, url: string): string {
+  if (url.startsWith(base)) return "/" + url.slice(base.length);
+  const bare = base.slice(0, -1);
+  if (url === bare || url.startsWith(bare + "?") || url.startsWith(bare + "#")) return "/" + url.slice(bare.length);
+  return url;
+}
+
+/** Turn an app-relative URL into an absolute one: `/rooms/1` → `/chat/rooms/1`. */
+export function withBase(base: string, to: string): string {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(to) || to.startsWith("//")) return to;
+  if (to.startsWith(base)) return to;
+  return base + (to.startsWith("/") ? to.slice(1) : to);
+}
+
+function currentUrl(base: string): string {
+  if (typeof location === "undefined") return "/";
+  return stripBase(base, location.pathname + location.search);
+}
+
+let globalBase = "/";
+
+/** Provides the app-relative location. `mount()` adds one around your App unless `router: false`. */
+export function LocationProvider(props: { base?: string; url?: string; children?: ComponentChildren }) {
+  const base = normalizeBase(props.base);
+  globalBase = base;
+  const [state, setState] = useState(() => ({ url: props.url ?? currentUrl(base), wasPush: false }));
+
+  const value = useMemo(() => {
+    const u = new URL(state.url, "http://x");
+    const path = u.pathname.replace(/\/+$/g, "") || "/";
+    const route = (to: string, replace?: boolean) => {
+      const abs = withBase(base, to);
+      if (typeof history !== "undefined") {
+        if (replace) history.replaceState(null, "", abs);
+        else history.pushState(null, "", abs);
+      }
+      setState({ url: stripBase(base, abs), wasPush: !replace });
+    };
+    return {
+      url: state.url,
+      path,
+      query: Object.fromEntries(u.searchParams),
+      route,
+      back: () => history.back(),
+      forward: () => history.forward(),
+      wasPush: state.wasPush,
+    };
+  }, [state, base]);
+
+  useLayoutEffect(() => {
+    const onPop = () => setState({ url: currentUrl(base), wasPush: false });
+    const onClick = (e: MouseEvent) => {
+      if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+      const a = (e.composedPath() as Element[]).find((el) => el.nodeName === "A") as HTMLAnchorElement | undefined;
+      if (!a || !a.href || a.origin !== location.origin || a.download) return;
+      if (a.target && !/^_?self$/i.test(a.target)) return;
+      const href = a.getAttribute("href") ?? "";
+      if (href.startsWith("#")) return;
+      const abs = a.pathname + a.search;
+      if (!(abs + "/").startsWith(base) && !abs.startsWith(base)) return;
+      e.preventDefault();
+      value.route(stripBase(base, abs + a.hash));
+    };
+    addEventListener("popstate", onPop);
+    addEventListener("click", onClick);
+    return () => {
+      removeEventListener("popstate", onPop);
+      removeEventListener("click", onClick);
+    };
+  }, [base, value]);
+
+  return h(ctx.Provider, { value }, props.children);
+}
+
+function isRouteChild(v: unknown): boolean {
+  const p = (v as VNode<any> | null)?.props;
+  return !!p && (p.path !== undefined || p.default);
+}
+
+/**
+ * Renders the first child `<Route>` whose `path` matches. Without route children it only provides the location,
+ * so both `<Router><Route .../></Router>` and Lakebed's `<Router><Routes>...</Routes></Router>` work.
+ */
+export function Router(props: {
+  children?: ComponentChildren;
+  onRouteChange?: (url: string) => void;
+  onLoadStart?: (url: string) => void;
+  onLoadEnd?: (url: string) => void;
+}) {
+  const hasProvider = !!useContext(ctx)?.url;
+  const routes = toChildArray(props.children).some(isRouteChild);
+  // preact-iso serializes route props; rendered VNodes contain circular parent links.
+  const children = useMemo(() => toChildArray(props.children).filter(isValidElement).map((child) => {
+    if (child.type !== Route) return child;
+    const { element, ...rest } = (child as VNode<RouteProps>).props;
+    if (element === undefined) return child;
+    return h(Route, { ...rest, key: child.key, component: () => element });
+  }), [props.children]);
+  const content = routes ? h(IsoRouter as ComponentType<typeof props>, { ...props, children }) : props.children;
+  return hasProvider ? (content as any) : h(LocationProvider, null, content);
+}
+
+/** Alias of `<Router>` (react-router style naming). */
+export const Routes = Router;
+
+export type RouteProps<P = {}> = {
+  path?: string;
+  default?: boolean;
+} & ({ component: ComponentType<any>; element?: undefined } | { element: JSX.Element | null; component?: undefined }) &
+  P;
+
+/** A route. Use `component={Page}` (gets `params` as props) or `element={<Page />}` (read `useParams()`). */
+export function Route(props: RouteProps<Record<string, unknown>>) {
+  const { component, element, ...rest } = props as any;
+  return element !== undefined ? element : h(component, rest);
+}
+
+/** `<a>` with an app-relative `to`. */
+export function Link(props: JSX.IntrinsicElements["a"] & { to?: string; href?: string }) {
+  const { to, href, ...rest } = props as any;
+  return h("a", { ...rest, href: withBase(globalBase, to ?? href ?? "/") });
+}
+
+export function useLocation(): LocationValue {
+  return isoUseLocation() as unknown as LocationValue;
+}
+
+/** Returns `navigate(to, { replace })` for app-relative paths. */
+export function useNavigate(): (to: string, options?: { replace?: boolean }) => void {
+  const loc = useLocation();
+  return (to, options) => loc.route(to, options?.replace);
+}
+
+/** Route params of the matched `<Route path="/x/:id">`. */
+export function useParams<P extends Record<string, string> = Record<string, string>>(): P {
+  return ((useRoute() as any)?.params ?? {}) as P;
+}
+
+export { useRoute };

package/sdk/src/client/storage.ts

@@ -0,0 +1,46 @@
+import { EraspaceError } from "./errors.ts";
+
+export interface UploadedObject {
+  key: string;
+  url: string;
+  size: number;
+  contentType: string;
+  name: string | null;
+}
+
+export interface StorageClient {
+  /** Store a file in this app's Postgres schema. v1 apps and their files are public. */
+  upload(body: Blob, options?: { name?: string; signal?: AbortSignal }): Promise<UploadedObject>;
+  url(key: string): string;
+  delete(key: string, options?: { signal?: AbortSignal }): Promise<void>;
+}
+
+export function createStorageClient(base: () => string): StorageClient {
+  function url(key?: string): string {
+    const path = `${base().replace(/\/+$/, "")}/_sb/storage`;
+    return key === undefined ? path : `${path}/${encodeURIComponent(key)}`;
+  }
+  async function check(response: Response): Promise<Record<string, unknown>> {
+    const payload = await response.json() as unknown;
+    if (!payload || typeof payload !== "object") throw new EraspaceError("StorageError", `HTTP ${response.status}`);
+    const result = payload as Record<string, unknown>;
+    if (!response.ok || result.ok !== true) throw EraspaceError.from(result.error, `Storage request failed: HTTP ${response.status}`);
+    return result;
+  }
+  return {
+    url,
+    async upload(body, options = {}) {
+      const headers = new Headers({ "content-type": body.type || "application/octet-stream" });
+      const name = options.name ?? (typeof File !== "undefined" && body instanceof File ? body.name : undefined);
+      if (name) headers.set("x-filename", encodeURIComponent(name));
+      const result = await check(await fetch(url(), { method: "POST", headers, body, signal: options.signal }));
+      if (typeof result.key !== "string" || typeof result.url !== "string" || typeof result.size !== "number" || typeof result.contentType !== "string" || (result.name !== null && typeof result.name !== "string")) {
+        throw new EraspaceError("StorageError", "Invalid upload response");
+      }
+      return { key: result.key, url: result.url, size: result.size, contentType: result.contentType, name: result.name };
+    },
+    async delete(key, options = {}) {
+      await check(await fetch(url(key), { method: "DELETE", signal: options.signal }));
+    },
+  };
+}

package/sdk/src/client/sub-key.ts

@@ -0,0 +1,12 @@
+/** Stable key for `(fn, args)`. Object keys are sorted so `{a,b}` and `{b,a}` dedupe. */
+export function subKey(fn: string, args: unknown[]): string {
+  return fn + ":" + stableStringify(args);
+}
+export function stableStringify(v: unknown): string {
+  if (v === undefined) return "null";
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return "[" + v.map(stableStringify).join(",") + "]";
+  const o = v as Record<string, unknown>;
+  const keys = Object.keys(o).filter((k) => o[k] !== undefined).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(o[k])).join(",") + "}";
+}

package/sdk/src/client/subscription.ts

@@ -0,0 +1,51 @@
+import { signal, type Signal } from "@preact/signals";
+import { EraspaceError } from "./errors.ts";
+import type { Patch } from "./result-diff.ts";
+
+export interface FullResult {
+  value: unknown;
+  commitSeq: number;
+  revision: number;
+}
+export type DataMessage = { id: string } & (FullResult | {
+  patch: Patch[];
+  base: number;
+  revision: number;
+  commitSeq: number;
+});
+
+interface Layer {
+  mid: number;
+  apply: (prev: any) => any;
+  commitSeq?: number;
+}
+
+export class Subscription {
+  readonly value: Signal<any> = signal(undefined);
+  readonly error: Signal<EraspaceError | undefined> = signal(undefined);
+  server: any = undefined;
+  hasServer = false;
+  commitSeq = -1;
+  revision: number | undefined;
+  request = 0;
+  refs = 0;
+  layers: Layer[] = [];
+  timer: ReturnType<typeof setTimeout> | undefined;
+  // Resubscriptions take a new id so messages for the previous one are ignored.
+  id: string;
+  readonly fn: string;
+  readonly args: unknown[];
+  readonly key: string;
+  constructor(id: string, fn: string, args: unknown[], key: string) {
+    this.id = id;
+    this.fn = fn;
+    this.args = args;
+    this.key = key;
+  }
+
+  recompute(): void {
+    let v = this.server;
+    if (this.hasServer) for (const l of this.layers) v = l.apply(v);
+    this.value.value = v;
+  }
+}

package/sdk/src/client/types.ts

@@ -0,0 +1,125 @@
+import type { ReadonlySignal } from "@preact/signals";
+import type { EraspaceError } from "./errors.ts";
+import type { StorageClient } from "./storage.ts";
+
+import type {
+  ActionArgs,
+  ActionName,
+  ActionResult,
+  MutationArgs,
+  MutationName,
+  MutationResult,
+  PaginationOptions,
+  PaginationResult,
+  QueryArgs,
+  QueryName,
+  QueryResult,
+} from "../server/index.ts";
+
+export type Status = "connecting" | "open" | "closed";
+
+export interface PresenceEntry<M = Record<string, unknown>> {
+  id: string;
+  meta: M;
+  /** All metas for this id (one per open connection). */
+  metas: M[];
+}
+
+/** Query names whose last argument is `PaginationOptions` and whose result is a `PaginationResult`. */
+export type PaginatedQueryName<C> = {
+  [N in QueryName<C>]: QueryArgs<C, N> extends [...any[], PaginationOptions]
+    ? QueryResult<C, N> extends PaginationResult<any>
+      ? N
+      : never
+    : never;
+}[QueryName<C>];
+type PaginatedArgs<C, N extends QueryName<C>> = QueryArgs<C, N> extends [...infer P, PaginationOptions] ? P : never;
+type PaginatedItem<C, N extends QueryName<C>> = QueryResult<C, N> extends PaginationResult<infer T> ? T : never;
+
+export interface PaginatedQueryResult<T> {
+  /** Every loaded row, in page order. */
+  results: T[];
+  status: "LoadingFirstPage" | "CanLoadMore" | "LoadingMore" | "Exhausted";
+  isLoading: boolean;
+  loadMore(numItems?: number): void;
+  reset(): void;
+}
+
+/** The local cache handed to optimistic updaters. */
+export interface OptimisticStore<C> {
+  get<N extends QueryName<C>>(name: N, args: QueryArgs<C, N>): QueryResult<C, N> | undefined;
+  set<N extends QueryName<C>>(name: N, args: QueryArgs<C, N>, value: QueryResult<C, N>): void;
+  /** Apply `updater` to the cached result of `name(...args)` if it is loaded. */
+  update<N extends QueryName<C>>(
+    name: N,
+    args: QueryArgs<C, N>,
+    updater: (prev: QueryResult<C, N>) => QueryResult<C, N>,
+  ): void;
+}
+
+export interface MutationOptions<C, A extends any[]> {
+  optimistic?: (store: OptimisticStore<C>, ...args: A) => void;
+}
+
+export interface Room<M = Record<string, unknown>, S extends Record<string, unknown> = Record<string, unknown>> {
+  /** Members currently in the room. */
+  presence: PresenceEntry<M>[];
+  /** This connection's public guest id. Changes on reconnect. Empty until the room join completes. */
+  self: string;
+  /** Send `event` to every other member. */
+  broadcast(event: string, payload?: unknown): void;
+  /** Listen for `event` broadcasts. Returns an unsubscribe function. Call it in an effect. */
+  on(event: string, cb: (payload: any, from: string | undefined) => void): () => void;
+  /** Ephemeral shared state (kept by the room process, never stored). */
+  state: Partial<S>;
+  setState<K extends keyof S & string>(key: K, value: S[K]): void;
+}
+
+export interface EraspaceClient<C> {
+  readonly storage: StorageClient;
+  /** Subscribe to a query. Returns `undefined` until the first result arrives, then live values. */
+  useQuery<N extends QueryName<C>>(name: N, ...args: QueryArgs<C, N>): QueryResult<C, N> | undefined;
+  /** Pass computed signals directly to JSX text nodes for updates without a component render. */
+  useQuerySignal<N extends QueryName<C>>(name: N, ...args: QueryArgs<C, N>): ReadonlySignal<QueryResult<C, N> | undefined>;
+  /** Re-render only when the selected result changes. */
+  useQuerySelector<N extends QueryName<C>, T>(name: N, args: QueryArgs<C, N>, select: (value: QueryResult<C, N> | undefined) => T): T;
+  useMutation<N extends MutationName<C>>(
+    name: N,
+    options?: MutationOptions<C, MutationArgs<C, N>>,
+  ): (...args: MutationArgs<C, N>) => Promise<MutationResult<C, N>>;
+  useAction<N extends ActionName<C>>(name: N): (...args: ActionArgs<C, N>) => Promise<ActionResult<C, N>>;
+  usePaginatedQuery<N extends PaginatedQueryName<C>>(
+    name: N,
+    args: PaginatedArgs<C, N>,
+    options?: { initialNumItems?: number },
+  ): PaginatedQueryResult<PaginatedItem<C, N>>;
+  /** Join `room` and return its members. `meta` is this tab's presence metadata (cursor, typing, name...). */
+  usePresence<M extends Record<string, unknown> = Record<string, unknown>>(room: string, meta?: M): PresenceEntry<M>[];
+  useRoom<M extends Record<string, unknown> = Record<string, unknown>, S extends Record<string, unknown> = Record<string, unknown>>(
+    room: string,
+    meta?: M,
+  ): Room<M, S>;
+
+  query<N extends QueryName<C>>(name: N, ...args: QueryArgs<C, N>): Promise<QueryResult<C, N>>;
+  mutation<N extends MutationName<C>>(name: N, ...args: MutationArgs<C, N>): Promise<MutationResult<C, N>>;
+  action<N extends ActionName<C>>(name: N, ...args: ActionArgs<C, N>): Promise<ActionResult<C, N>>;
+  /** Imperative live subscription. Returns an unsubscribe function. */
+  subscribe<N extends QueryName<C>>(
+    name: N,
+    args: QueryArgs<C, N>,
+    onValue: (value: QueryResult<C, N>) => void,
+    onError?: (error: EraspaceError) => void,
+  ): () => void;
+
+  readonly app: string;
+  readonly base: string;
+  /** This connection's public guest id. Changes on reconnect. Empty until the socket has joined. */
+  readonly guestId: string;
+  /** Socket status: `connecting`, `open` or `closed`. */
+  readonly status: ReadonlySignal<Status>;
+  /** Latest deployed version seen by this client. */
+  readonly version: ReadonlySignal<number>;
+  /** Called after each redeploy (after subscriptions are re-sent). */
+  onDeployed(cb: (version: number) => void): () => void;
+  close(): void;
+}