eraspace 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eraspace",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "eraspace: build, deploy and manage eraspace capsules",
   "type": "module",
   "keywords": [

package/sdk/src/client/client.ts

@@ -2,7 +2,7 @@ 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 { readConfig, type ClientOptions } from "./config.ts";
 import { subKey, stableStringify } from "./sub-key.ts";
 import type { Subscription } from "./subscription.ts";
 import type { RoomConn } from "./room.ts";
@@ -23,8 +23,10 @@ type Fn = (...args: any[]) => any;
  */
 export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C> {
   let impl: ClientImpl | undefined;
-  // Lazy so a module-level createClient() costs nothing until first use.
+  // Lazy so a module-level createClient() costs nothing until first use, except in a browser page that reloads on
+  // deploy (the platform shell's default), where the client connects at once to hear deploys.
   const get = () => (impl ??= new ClientImpl(options));
+  if (typeof location !== "undefined" && (options.reloadOnDeploy ?? readConfig().app)) get().watchDeploys();
 
   function useSubscription(name: string, args: unknown[]): Subscription {
     const c = get();

package/sdk/src/client/config.ts

@@ -1,11 +1,23 @@
 import type { SocketOptions, WebSocketConstructor } from "./transport.ts";
 
+/** A query result the shell embedded, as a `sub` reply would carry it. */
+export interface InitialResult {
+  fn: string;
+  args: unknown[];
+  value: unknown;
+  commitSeq: number;
+  revision: number;
+  entry: string;
+}
+
 /** `window.__ERASPACE__`, injected by the platform's HTML shell (SPEC §6). */
 export interface EraspaceConfig {
   app: string;
   base: string;
   version: number;
   socket: string;
+  /** Current results of the queries the app's pages usually open first. */
+  initial?: InitialResult[];
 }
 
 export interface ClientOptions {
@@ -14,7 +26,11 @@ export interface ClientOptions {
   socket?: string;
   base?: string;
   version?: number;
-  /** Reload the page when the app is redeployed. Default `false`. */
+  /**
+   * Reload the page when the app is redeployed, so a deploy reaches open tabs without a manual refresh. Default
+   * `true` for the shell's own app on pages served by the platform shell (`window.__ERASPACE__` is set), otherwise
+   * `false`. When enabled in a browser, the client connects at creation rather than on first use.
+   */
   reloadOnDeploy?: boolean;
   /** Push timeout in ms. Default 15000. */
   timeout?: number;

package/sdk/src/client/connection.ts

@@ -2,10 +2,10 @@ 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 { readConfig, type ClientOptions, type InitialResult } 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 { canonicalArgs, subKey } from "./sub-key.ts";
+import { Subscription, type FullResult, type UnchangedResult, type DataMessage } from "./subscription.ts";
 import { RoomConn } from "./room.ts";
 import { retryDelay } from "./retry.ts";
 import type { Status } from "./types.ts";
@@ -18,6 +18,7 @@ export class ClientImpl {
   readonly self = signal("");
   readonly status = signal<Status>("connecting");
   readonly version: Signal<number>;
+  readonly reloadOnDeploy: boolean;
   private opts: ClientOptions;
   private socketUrl: string;
   private socket: Socket | undefined;
@@ -34,6 +35,8 @@ export class ClientImpl {
   private subsById = new Map<string, Subscription>();
   private rooms = new Map<string, RoomConn>();
   private deployedCbs = new Set<(v: number) => void>();
+  /** Results the shell embedded, by subscription key, each used by the first subscription to it. */
+  private initial = new Map<string, InitialResult>();
 
   constructor(opts: ClientOptions) {
     const cfg = readConfig();
@@ -42,7 +45,18 @@ export class ClientImpl {
     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);
+    // The shell's version and reload default describe the page's own app, not another app it talks to.
+    const ownApp = !opts.app || opts.app === cfg.app;
+    this.version = signal(opts.version ?? (ownApp ? cfg.version : undefined) ?? 0);
+    this.reloadOnDeploy = opts.reloadOnDeploy ?? (ownApp && Boolean(cfg.app));
+    if (ownApp && Array.isArray(cfg.initial)) {
+      for (const r of cfg.initial) if (typeof r?.fn === "string" && Array.isArray(r.args)) this.initial.set(subKey(r.fn, r.args), r);
+    }
+  }
+
+  /** Join the app topic now when deploys reload the page, so a page that has not queried yet still hears them. */
+  watchDeploys(): void {
+    if (this.reloadOnDeploy && !this.gone) this.ensureChannel();
   }
 
   // -- connection -----------------------------------------------------------------------------------------------
@@ -91,6 +105,7 @@ export class ClientImpl {
       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();
+      if (resp && typeof resp.version === "number") this.onJoinVersion(resp.version);
       // The channel process is new after a reconnect, so every live subscription is sent again.
       if (this.joinedOnce) this.resubscribeAll();
       this.joinedOnce = true;
@@ -109,7 +124,8 @@ export class ClientImpl {
   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 });
+      // Sorted object keys let equal query arguments share the server's cached result.
+      const resp = await this.push<{ value?: unknown }>("call", { fn, args: kind === "query" ? canonicalArgs(args) : args, kind, key });
       return resp?.value;
     } catch (error) {
       if (kind === "action" && error instanceof EraspaceError && ["TimeoutError", "OutcomeUnknownError"].includes(error.name)) {
@@ -202,6 +218,8 @@ export class ClientImpl {
     sub.retryTimer = undefined;
     const oldId = sub.id;
     const request = ++sub.request;
+    // The server replies without the value when its cache entry still holds the revision we have.
+    const known = sub.hasServer && sub.entry !== undefined && sub.revision !== undefined ? { entry: sub.entry, revision: sub.revision } : undefined;
     if (request > 1) {
       this.subsById.delete(oldId);
       sub.id = String(this.nextSub++);
@@ -210,15 +228,24 @@ export class ClientImpl {
       this.unsubscribe(sub, oldId);
     }
     const id = sub.id;
-    this.push<FullResult>("sub", () => {
+    this.push<FullResult | UnchangedResult>("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)) };
+      const minCommitSeq = Math.max(0, ...sub.layers.map(layer => layer.commitSeq ?? 0));
+      return known ? { id, fn: sub.fn, args: sub.args, minCommitSeq, known } : { id, fn: sub.fn, args: sub.args, minCommitSeq };
     }).then(
       (resp) => {
         if (this.subsById.get(sub.id) !== sub || sub.request !== request) return;
-        this.setServer(sub, resp.value, resp.commitSeq, resp.revision);
+        if ("unchanged" in resp && resp.unchanged === true) {
+          // Only a known revision is answered this way, and the value cannot have changed since it was sent.
+          if (known && sub.hasServer) this.setServer(sub, sub.server, resp.commitSeq, resp.revision);
+          else this.sendSub(sub);
+          return;
+        }
+        const full = resp as FullResult;
+        sub.entry = full.entry;
+        this.setServer(sub, full.value, full.commitSeq, full.revision);
       },
       (err: EraspaceError) => {
         if (this.subsById.get(sub.id) === sub && sub.request === request) {
@@ -269,6 +296,8 @@ export class ClientImpl {
         this.sendSub(sub);
       }
     } else {
+      // Recovered subscriptions arrive as full pushes that name their new cache entry.
+      if (typeof message.entry === "string") sub.entry = message.entry;
       this.setServer(sub, message.value, message.commitSeq, message.revision);
     }
   }
@@ -281,7 +310,14 @@ export class ClientImpl {
   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();
+    if (this.reloadOnDeploy && typeof location !== "undefined") location.reload();
+  }
+
+  // A deploy announced while the socket was down, or before the first join, shows up as a newer join version.
+  // Without a known page version there is nothing to compare, so the first one seen becomes the baseline.
+  private onJoinVersion(version: number): void {
+    if (this.version.value === 0) this.version.value = version;
+    else if (version > this.version.value) this.onDeployed(version);
   }
 
   onDeployedCb(cb: (v: number) => void): () => void {
@@ -297,6 +333,14 @@ export class ClientImpl {
       sub = new Subscription(String(this.nextSub++), fn, args, key);
       this.subs.set(key, sub);
       this.subsById.set(sub.id, sub);
+      // A result embedded in the page shows at once; the server confirms it with `unchanged` when the first
+      // `sub` sends it as `known`, or replies with the current value.
+      const seed = this.initial.get(key);
+      if (seed) {
+        this.initial.delete(key);
+        sub.entry = seed.entry;
+        this.setServer(sub, seed.value, seed.commitSeq, seed.revision);
+      }
       this.sendSub(sub);
     }
     if (sub.refs === 0) this.scheduleDrop(sub, 1000);
@@ -382,9 +426,13 @@ export class ClientImpl {
           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);
+        else {
+          // The server sends unchanged values' newer watermarks only on request.
+          this.watch(sub, commitSeq);
+          setTimeout(() => {
+            if (sub.layers.some((l) => l.mid === mid) && this.subs.get(sub.key) === sub) this.sendSub(sub);
+          }, timeout);
+        }
       }
       return value;
     } catch (e) {
@@ -393,6 +441,13 @@ export class ClientImpl {
     }
   }
 
+  /** Asks for a watermark covering `commitSeq` on the subscription's current server id. */
+  private watch(sub: Subscription, commitSeq: number): void {
+    const id = sub.id;
+    if (sub.sent?.id !== id || sub.sent.join !== this.joins) return;
+    this.push("watch", { id, commitSeq }).catch(() => {});
+  }
+
   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;

package/sdk/src/client/files.ts

@@ -1,6 +1,6 @@
 // File upload and preview for app UIs, over the storage client.
 import { Fragment, h, type ComponentChildren, type TargetedDragEvent, type TargetedEvent } from "preact";
-import { useEffect, useRef, useState } from "preact/hooks";
+import { useEffect, useLayoutEffect, useRef, useState } from "preact/hooks";
 import { EraspaceError } from "./errors.ts";
 import { isStorageKey, type StorageClient, type UploadedObject } from "./storage.ts";
 
@@ -36,6 +36,8 @@ export interface Upload {
   uploading: boolean;
   /** Fraction of the current batch's bytes uploaded, from 0 to 1. */
   progress: number;
+  /** The file being uploaded now, for an immediate local preview. */
+  file: Blob | null;
   /** The latest failure, cleared when the next batch starts. */
   error: EraspaceError | null;
   reset(): void;
@@ -85,7 +87,7 @@ function asError(e: unknown): EraspaceError {
  * cancel what has not finished; a file whose bytes already reached the server may still be stored.
  */
 export function useUpload(storage: StorageClient, options: UseUploadOptions = {}): Upload {
-  const [state, setState] = useState({ uploading: false, progress: 0, error: null as EraspaceError | null });
+  const [state, setState] = useState({ uploading: false, progress: 0, error: null as EraspaceError | null, file: null as Blob | null });
   const opts = useRef(options);
   opts.current = options;
   // Replaced by reset(), so batches queued before it never start.
@@ -101,9 +103,10 @@ export function useUpload(storage: StorageClient, options: UseUploadOptions = {}
     let done = 0;
     let error: EraspaceError | null = null;
     const stored: FileRef[] = [];
-    setState({ uploading: true, progress: 0, error: null });
+    setState({ uploading: true, progress: 0, error: null, file: null });
     for (const file of files) {
       const weight = bytes ? file.size : 1;
+      if (!abort.signal.aborted) setState((s) => ({ ...s, file }));
       try {
         const object: UploadedObject = await storage.upload(file, {
           signal: abort.signal,
@@ -126,7 +129,7 @@ export function useUpload(storage: StorageClient, options: UseUploadOptions = {}
       done += weight;
     }
     // Keep a validation error reported while this batch was running.
-    if (!abort.signal.aborted) setState((s) => ({ uploading: false, progress: 1, error: error ?? s.error }));
+    if (!abort.signal.aborted) setState((s) => ({ uploading: false, progress: 1, error: error ?? s.error, file: null }));
     return stored;
   }
 
@@ -153,10 +156,11 @@ export function useUpload(storage: StorageClient, options: UseUploadOptions = {}
     uploading: state.uploading,
     progress: state.progress,
     error: state.error,
+    file: state.file,
     reset() {
       controller.current?.abort();
       controller.current = null;
-      setState({ uploading: false, progress: 0, error: null });
+      setState({ uploading: false, progress: 0, error: null, file: null });
     },
   };
 }
@@ -174,6 +178,21 @@ export interface FileUploadProps extends UseUploadOptions {
 
 const VISUALLY_HIDDEN = "position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap";
 
+/** The image being uploaded, read from the browser's copy so it shows before any bytes reach the server. */
+function UploadingImage({ file }: { file: Blob | null }) {
+  const [shown, setShown] = useState<{ file: Blob; url: string } | null>(null);
+  // Created inside the effect that revokes it, so a fast upload or unmount cannot skip the revocation.
+  useLayoutEffect(() => {
+    if (!file || !/^image\//i.test(file.type) || typeof URL.createObjectURL !== "function") return;
+    const url = URL.createObjectURL(file);
+    setShown({ file, url });
+    return () => URL.revokeObjectURL(url);
+  }, [file]);
+  return shown && shown.file === file
+    ? h("img", { src: shown.url, alt: "", style: "display:block;max-width:100%;max-height:6rem;border-radius:.375rem;opacity:.7" })
+    : null;
+}
+
 /** A drop zone and file picker that uploads to app storage and reports each stored file through `onUpload`. */
 export function FileUpload(props: FileUploadProps) {
   const { client, multiple, disabled, children } = props;
@@ -224,6 +243,7 @@ export function FileUpload(props: FileUploadProps) {
         ? h(
             Fragment,
             null,
+            h(UploadingImage, { file: state.file }),
             h("span", null, `Uploading… ${Math.round(state.progress * 100)}%`),
             h("progress", { value: state.progress, max: 1, style: props.class ? undefined : "width:100%;max-width:16rem" }),
           )
@@ -286,6 +306,8 @@ export function FilePreview(props: FilePreviewProps) {
   // `failed`: the lookup request failed (offline, rate limited); null means the server has no such file.
   const [fetched, setFetched] = useState<{ key: string; info: UploadedObject | null | "failed" } | undefined>(undefined);
   const [broken, setBroken] = useState<string | null>(null);
+  // The key whose page-local copy failed to load, for example after it was evicted; it loads from the server.
+  const [remote, setRemote] = useState<string | null>(null);
   const [attempt, setAttempt] = useState(0);
   useEffect(() => {
     if (!key || known) return;
@@ -332,9 +354,12 @@ export function FilePreview(props: FilePreviewProps) {
   }
 
   const url = client.storage.url(key);
+  // A file uploaded from this page shows from the browser's copy instead of being downloaded again.
+  const local = remote === key ? undefined : client.storage.localUrl?.(key);
+  const src = local ?? url;
   const name = meta.name || "file";
   const size = typeof meta.size === "number" ? formatBytes(meta.size) : "";
-  const fail = () => setBroken(key);
+  const fail = () => (local ? setRemote(key) : setBroken(key));
   const caption = props.caption === false
     ? null
     : h(
@@ -346,13 +371,13 @@ export function FilePreview(props: FilePreviewProps) {
   switch (kindOf(meta.contentType!)) {
     case "image":
       return box([
-        h("a", { href: url, target: "_blank", rel: "noopener" }, h("img", { src: url, alt: props.alt ?? name, loading: "lazy", onError: fail, style: plain ? `${MEDIA};max-height:20rem` : undefined })),
+        h("a", { href: url, target: "_blank", rel: "noopener" }, h("img", { src, alt: props.alt ?? name, loading: local ? undefined : "lazy", decoding: "async", onError: fail, style: plain ? `${MEDIA};max-height:20rem` : undefined })),
         caption,
       ]);
     case "video":
-      return box([h("video", { src: url, controls: true, preload: "metadata", onError: fail, style: plain ? `${MEDIA};max-height:20rem` : undefined }), caption]);
+      return box([h("video", { src, controls: true, preload: "metadata", onError: fail, style: plain ? `${MEDIA};max-height:20rem` : undefined }), caption]);
     case "audio":
-      return box([h("audio", { src: url, controls: true, preload: "metadata", onError: fail, style: plain ? "display:block;width:100%" : undefined }), caption]);
+      return box([h("audio", { src, controls: true, preload: "metadata", onError: fail, style: plain ? "display:block;width:100%" : undefined }), caption]);
     case "text":
       return box([
         h("iframe", { src: url, title: name, sandbox: "", loading: "lazy", style: plain ? "display:block;width:100%;height:12rem;border:1px solid #e2e8f0;border-radius:.5rem;background:#fff" : undefined }),

package/sdk/src/client/router.ts

@@ -81,7 +81,7 @@ export function LocationProvider(props: { base?: string; url?: string; children?
     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 || !a.href || a.origin !== location.origin || a.hasAttribute("download")) return;
       if (a.target && !/^_?self$/i.test(a.target)) return;
       const href = a.getAttribute("href") ?? "";
       if (href.startsWith("#")) return;

package/sdk/src/client/storage.ts

@@ -24,6 +24,19 @@ export interface StorageClient {
   /** A stored file's metadata, or null when there is no such file. */
   info(key: string, options?: { signal?: AbortSignal }): Promise<UploadedObject | null>;
   delete(key: string, options?: { signal?: AbortSignal; deleteToken?: string }): Promise<void>;
+  /**
+   * A page-local URL for an image, video or audio file this client uploaded, so previews show it without
+   * downloading it again. Undefined for any other file, or after the file is deleted or evicted. Optional, so other
+   * implementations keep working; previews then use the server URL.
+   */
+  localUrl?(key: string): string | undefined;
+}
+
+/** Uploaded media kept as object URLs. Each keeps its Blob alive, so only the most recent are retained. */
+const LOCAL_FILES = 50;
+
+function isMedia(contentType: string): boolean {
+  return /^(image|video|audio)\//i.test(contentType.trim());
 }
 
 /** Storage keys are UUIDs. */
@@ -75,6 +88,19 @@ function sendWithProgress(target: string, headers: Headers, body: Blob, signal:
 
 export function createStorageClient(base: () => string): StorageClient {
   const deleteTokens = new Map<string, string>();
+  const localFiles = new Map<string, string>();
+  function forgetLocal(key: string) {
+    const local = localFiles.get(key);
+    if (local === undefined) return;
+    localFiles.delete(key);
+    URL.revokeObjectURL(local);
+  }
+  function keepLocal(key: string, body: Blob, contentType: string) {
+    if (!isMedia(contentType) || typeof URL.createObjectURL !== "function") return;
+    forgetLocal(key);
+    localFiles.set(key, URL.createObjectURL(body));
+    while (localFiles.size > LOCAL_FILES) forgetLocal(localFiles.keys().next().value!);
+  }
   function url(key?: string): string {
     const path = `${base().replace(/\/+$/, "")}/_sb/storage`;
     return key === undefined ? path : `${path}/${encodeURIComponent(key)}`;
@@ -105,6 +131,7 @@ export function createStorageClient(base: () => string): StorageClient {
       }
       const deleteToken = typeof result.deleteToken === "string" ? result.deleteToken : undefined;
       if (deleteToken) deleteTokens.set(result.key, deleteToken);
+      keepLocal(result.key, body, result.contentType);
       return { key: result.key, url: result.url, size: result.size, contentType: result.contentType, name: result.name, ...(deleteToken ? { deleteToken } : {}) };
     },
     async info(key, options = {}) {
@@ -127,6 +154,10 @@ export function createStorageClient(base: () => string): StorageClient {
       const response = await fetch(url(key), { method: "DELETE", headers, signal: options.signal });
       check(response.status, await response.text());
       deleteTokens.delete(key);
+      forgetLocal(key);
+    },
+    localUrl(key) {
+      return localFiles.get(key);
     },
   };
 }

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

@@ -2,6 +2,22 @@
 export function subKey(fn: string, args: unknown[]): string {
   return fn + ":" + stableStringify(args);
 }
+/**
+ * Arguments as sent to the server: object keys in sorted order, so equal arguments written in any order share
+ * one server cache entry. Serialization is unchanged otherwise.
+ */
+export function canonicalArgs(args: unknown[]): unknown[] {
+  return args.map(canonical);
+}
+function canonical(v: unknown): unknown {
+  if (v === null || typeof v !== "object") return v;
+  const json = (v as { toJSON?: unknown }).toJSON;
+  if (typeof json === "function") return canonical(json.call(v));
+  if (Array.isArray(v)) return v.map(canonical);
+  const o = v as Record<string, unknown>;
+  // Own data properties, so a `__proto__` key stays a key rather than setting the prototype.
+  return Object.fromEntries(Object.keys(o).sort().map((k) => [k, canonical(o[k])]));
+}
 export function stableStringify(v: unknown): string {
   if (v === undefined) return "null";
   if (v === null || typeof v !== "object") return JSON.stringify(v);

package/sdk/src/client/subscription.ts

@@ -1,11 +1,20 @@
 import { signal, type Signal } from "@preact/signals";
 import { EraspaceError } from "./errors.ts";
 import type { Patch } from "./result-diff.ts";
+import { canonicalArgs } from "./sub-key.ts";
 
 export interface FullResult {
   value: unknown;
   commitSeq: number;
   revision: number;
+  /** The server cache entry holding the value, echoed as `known` on a resubscription. */
+  entry?: string;
+}
+/** A resubscription whose `known` entry and revision still hold: the client keeps its value. */
+export interface UnchangedResult {
+  unchanged: true;
+  commitSeq: number;
+  revision: number;
 }
 export type DataMessage = { id: string } & (FullResult | {
   patch: Patch[];
@@ -27,6 +36,8 @@ export class Subscription {
   hasServer = false;
   commitSeq = -1;
   revision: number | undefined;
+  /** The server cache entry of `revision`. */
+  entry: string | undefined;
   request = 0;
   retries = 0;
   retryTimer: ReturnType<typeof setTimeout> | undefined;
@@ -43,7 +54,7 @@ export class Subscription {
   constructor(id: string, fn: string, args: unknown[], key: string) {
     this.id = id;
     this.fn = fn;
-    this.args = args;
+    this.args = canonicalArgs(args);
     this.key = key;
   }
 

package/sdk/src/client/transport.ts

@@ -22,6 +22,8 @@ export interface SocketOptions {
   rejoinAfterMs?: (attempt: number) => number;
   /** How long a socket must stay open before reconnect backoff starts again from the first attempt. */
   stableAfterMs?: number;
+  /** Accept large payloads as deflated binary frames. Defaults to on where `DecompressionStream` inflates raw deflate. */
+  compression?: boolean;
 }
 
 interface Frame {
@@ -42,6 +44,58 @@ interface Pending {
 }
 export interface JoinReply { self?: string; now?: number; version?: number }
 
+function asFrame(value: unknown): Frame | undefined {
+  if (!value || typeof value !== "object" || !("topic" in value) || typeof value.topic !== "string"
+    || !("event" in value) || typeof value.event !== "string" || !("session" in value)
+    || !(value.session === null || typeof value.session === "string") || !("ref" in value)
+    || !(value.ref === null || typeof value.ref === "string") || !("payload" in value)) return undefined;
+  return value as Frame;
+}
+
+/**
+ * Reports an exception thrown by app code that consumes frames, as an uncaught event handler exception would be.
+ * It must not look like a transport failure, which would fail every in-flight request with an unknown outcome.
+ */
+function report(error: unknown): void {
+  if (typeof reportError === "function") reportError(error);
+  else setTimeout(() => { throw error; });
+}
+
+function inflates(): boolean {
+  try { return typeof DecompressionStream === "function" && Boolean(new DecompressionStream("deflate-raw")); }
+  catch { return false; }
+}
+
+async function bytesOf(data: unknown): Promise<Uint8Array<ArrayBuffer> | undefined> {
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer);
+  if (typeof Blob !== "undefined" && data instanceof Blob) return new Uint8Array(await data.arrayBuffer());
+  return undefined;
+}
+
+/**
+ * A binary frame is a four-byte big-endian header length, the frame's JSON header and a raw-deflated JSON
+ * object. The header's `z` places the object: `"response"` is the reply's response, `"members"` adds its
+ * members to the header payload.
+ */
+async function inflateFrame(data: unknown): Promise<Frame | undefined> {
+  const bytes = await bytesOf(data);
+  if (!bytes || bytes.length < 4) return undefined;
+  const length = new DataView(bytes.buffer, bytes.byteOffset).getUint32(0);
+  if (4 + length > bytes.length) return undefined;
+  const header: unknown = JSON.parse(new TextDecoder().decode(bytes.subarray(4, 4 + length)));
+  const frame = asFrame(header);
+  const z = header && typeof header === "object" && "z" in header ? header.z : undefined;
+  if (!frame || !frame.payload || typeof frame.payload !== "object") return undefined;
+  const inflated = new Blob([bytes.subarray(4 + length)]).stream().pipeThrough(new DecompressionStream("deflate-raw"));
+  const body: unknown = JSON.parse(await new Response(inflated).text());
+  const payload = frame.payload as Record<string, unknown>;
+  if (z === "response") payload.response = body;
+  else if (z === "members" && body && typeof body === "object") frame.payload = { ...body, ...payload };
+  else return undefined;
+  return { session: frame.session, ref: frame.ref, topic: frame.topic, event: frame.event, payload: frame.payload };
+}
+
 /** Multiplexes topics over one native WebSocket. Sent requests are never replayed on reconnect. */
 export class Socket {
   private ws: WebSocketTransport | undefined;
@@ -65,6 +119,7 @@ export class Socket {
     const url = new URL(endpoint, typeof location === "undefined" ? undefined : location.href);
     url.protocol = url.protocol === "https:" || url.protocol === "wss:" ? "wss:" : "ws:";
     url.searchParams.set("v", "1");
+    if (options.compression ?? inflates()) url.searchParams.set("z", "1");
     this.url = url.href;
     this.options = options;
   }
@@ -88,6 +143,7 @@ export class Socket {
     try { ws = new Transport(this.url); }
     catch { this.scheduleReconnect(); return; }
     this.ws = ws;
+    (ws as { binaryType?: string }).binaryType = "arraybuffer";
     this.opening = setTimeout(() => this.lost(ws), this.options.timeout ?? 15000);
     ws.onopen = () => {
       if (this.ws !== ws) return;
@@ -103,25 +159,33 @@ export class Socket {
       this.heartbeat = setInterval(() => this.sendHeartbeat(ws), 25000);
     };
     ws.onmessage = (event) => {
-      if (this.ws !== ws || typeof event.data !== "string") return;
-      let frame: Frame;
-      try {
-        const value: unknown = JSON.parse(event.data);
-        if (!value || typeof value !== "object" || !("topic" in value) || typeof value.topic !== "string"
-          || !("event" in value) || typeof value.event !== "string" || !("session" in value)
-          || !(value.session === null || typeof value.session === "string") || !("ref" in value)
-          || !(value.ref === null || typeof value.ref === "string") || !("payload" in value)) return;
-        frame = value as Frame;
-      } catch { return; }
+      if (this.ws !== ws) return;
+      if (typeof event.data !== "string") {
+        // Deflated frames inflate asynchronously, in arrival order with every other frame.
+        const data = event.data;
+        // A frame that does not inflate is a transport failure; an exception while delivering one is not.
+        this.incoming = this.incoming.then(() => inflateFrame(data)).then(
+          frame => { if (frame) this.deliver(ws, frame); },
+          () => this.lost(ws),
+        );
+        return;
+      }
+      let frame: Frame | undefined;
+      try { frame = asFrame(JSON.parse(event.data)); } catch { return; }
+      if (!frame) return;
+      const received = frame;
       // ws can deliver several frames in one task. Let reply consumers settle before the next push.
-      this.incoming = this.incoming.then(() => {
-        if (this.ws === ws) this.receive(frame);
-      }).catch(() => this.lost(ws));
+      this.incoming = this.incoming.then(() => this.deliver(ws, received));
     };
     ws.onclose = () => this.lost(ws);
     ws.onerror = () => this.lost(ws);
   }
 
+  private deliver(ws: WebSocketTransport, frame: Frame): void {
+    if (this.ws !== ws) return;
+    try { this.receive(frame); } catch (error) { report(error); }
+  }
+
   private receive(frame: Frame): void {
     if (frame.event === "reply" && frame.ref) {
       const body = frame.payload;
@@ -333,8 +397,11 @@ export class Channel {
   receive(frame: Frame): void {
     if (this.closed || frame.session !== this.session) return;
     if (frame.event === "closed") { this.leave(); return; }
-    this.onMessage?.(frame.event, frame.payload);
-    for (const cb of this.events.get(frame.event) ?? []) cb(frame.payload);
+    // One throwing handler must not keep the frame from the others.
+    try { this.onMessage?.(frame.event, frame.payload); } catch (error) { report(error); }
+    for (const cb of this.events.get(frame.event) ?? []) {
+      try { cb(frame.payload); } catch (error) { report(error); }
+    }
   }
 
   disconnected(): void {