eraspace 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eraspace",
-  "version": "0.2.0",
+  "version": "0.4.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";
@@ -13,7 +13,7 @@ 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";
+export type { EraspaceClient, Room, PresenceEntry, MutationOptions, OptimisticStore, PaginatedQueryName, PaginatedQueryResult, Status } from "./types.ts";
 
 type Fn = (...args: any[]) => any;
 
@@ -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();
@@ -112,11 +114,8 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
 
   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,
+    // Stable per room, so effects and memoized children that depend on them do not rerun every render.
+    const methods = useMemo(() => ({
       broadcast: (event: string, payload?: unknown) => {
         void r.channel.push("broadcast", { event, payload: payload ?? null }).catch(error => { r.error.value = EraspaceError.from(error); });
       },
@@ -129,6 +128,13 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
       setState: (key: string, value: unknown) => {
         r.setState(key, value);
       },
+    }), [r]);
+    return {
+      presence: r.members.value,
+      self: r.self.value,
+      state: r.state.value,
+      error: r.error.value,
+      ...methods,
     };
   }
 

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;
@@ -321,6 +343,8 @@ export function FilePreview(props: FilePreviewProps) {
   if (meta === undefined || meta === null || meta === "failed" || broken === key) {
     // A media error cannot tell a missing file from a failed request, so every failure offers a retry.
     const retry = () => {
+      // Found metadata stays cached, so a file deleted since would show as found again and fail the same way.
+      infoCache.delete(client.storage.url(key));
       setBroken(null);
       setFetched(undefined);
       setAttempt((n) => n + 1);
@@ -332,9 +356,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 +373,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/index.ts

@@ -10,6 +10,7 @@ export {
   type PaginatedQueryResult,
   type PresenceEntry,
   type Room,
+  type Status,
   type EraspaceClient,
   type EraspaceConfig,
 } from "./client.ts";

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,9 +2,28 @@
 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])]));
+}
+/** Sorted-key JSON. Like `JSON.stringify` and `canonicalArgs`, it serializes what `toJSON` returns, so two Dates differ. */
 export function stableStringify(v: unknown): string {
   if (v === undefined) return "null";
   if (v === null || typeof v !== "object") return JSON.stringify(v);
+  const json = (v as { toJSON?: unknown }).toJSON;
+  if (typeof json === "function") return stableStringify(json.call(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();

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;
   }