eraspace 0.1.0 → 0.2.0

package/sdk/src/client/files.ts

@@ -0,0 +1,364 @@
+// 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 { EraspaceError } from "./errors.ts";
+import { isStorageKey, type StorageClient, type UploadedObject } from "./storage.ts";
+
+/**
+ * What to save in a row to show a file later. Declare it in the schema as
+ * `object({ key: string(), name: string(), contentType: string(), size: number() })`.
+ */
+export interface FileRef {
+  key: string;
+  name: string;
+  contentType: string;
+  size: number;
+}
+
+export interface UseUploadOptions {
+  /** Accepted types, as for `<input accept>`: `"image/*"`, `".pdf,.txt"`, `"image/png,application/pdf"`. */
+  accept?: string;
+  /** Refuse larger files before uploading. The server also enforces its own limit (5 MiB by default). */
+  maxBytes?: number;
+  /**
+   * Called after each file is stored, typically to save it with a mutation. If it throws, the stored file is
+   * deleted again and the error is reported.
+   */
+  onUpload?: (file: FileRef) => unknown;
+}
+
+export interface Upload {
+  /**
+   * Upload files one after another, after any batch already running. Resolves with the stored files; failures are
+   * reported in `error`. Type and size checks run only in the browser: the server stores any type up to its limit.
+   */
+  upload(files: Blob | Iterable<Blob> | ArrayLike<Blob> | null | undefined): Promise<FileRef[]>;
+  uploading: boolean;
+  /** Fraction of the current batch's bytes uploaded, from 0 to 1. */
+  progress: number;
+  /** The latest failure, cleared when the next batch starts. */
+  error: EraspaceError | null;
+  reset(): void;
+}
+
+type StorageHolder = { readonly storage: StorageClient };
+
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 1024) return `${Math.max(0, Math.round(bytes || 0))} B`;
+  const units = ["KB", "MB", "GB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}
+
+function nameOf(blob: Blob): string {
+  return typeof File !== "undefined" && blob instanceof File && blob.name ? blob.name : "file";
+}
+
+/** Whether `blob` matches an `<input accept>` list. */
+export function acceptsFile(accept: string | undefined, blob: Blob): boolean {
+  const tokens = (accept ?? "").split(",").map((t) => t.trim().toLowerCase()).filter(Boolean);
+  if (!tokens.length) return true;
+  const type = blob.type.toLowerCase();
+  const name = nameOf(blob).toLowerCase();
+  return tokens.some((t) => t === "*/*" || (t.startsWith(".") ? name.endsWith(t) : t.endsWith("/*") ? type.startsWith(t.slice(0, -1)) : type === t));
+}
+
+function toList(files: Blob | Iterable<Blob> | ArrayLike<Blob> | null | undefined): Blob[] {
+  if (!files) return [];
+  if (files instanceof Blob) return [files];
+  return Array.from(files as ArrayLike<Blob>);
+}
+
+function asError(e: unknown): EraspaceError {
+  if (e instanceof EraspaceError) return e;
+  if (e instanceof Error) return new EraspaceError(e.name, e.message);
+  return EraspaceError.from(e, "Upload failed");
+}
+
+/**
+ * Upload state for a component. Calls made while a batch is uploading wait their turn. `reset()` and unmounting
+ * 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 opts = useRef(options);
+  opts.current = options;
+  // Replaced by reset(), so batches queued before it never start.
+  const controller = useRef<AbortController | null>(null);
+  const queue = useRef<Promise<unknown>>(Promise.resolve());
+  useEffect(() => () => controller.current?.abort(), []);
+
+  async function run(files: Blob[], abort: AbortController): Promise<FileRef[]> {
+    if (abort.signal.aborted) return [];
+    // Progress is weighted by size; a batch of empty files counts each file once.
+    const bytes = files.reduce((n, f) => n + f.size, 0);
+    const total = bytes || files.length;
+    let done = 0;
+    let error: EraspaceError | null = null;
+    const stored: FileRef[] = [];
+    setState({ uploading: true, progress: 0, error: null });
+    for (const file of files) {
+      const weight = bytes ? file.size : 1;
+      try {
+        const object: UploadedObject = await storage.upload(file, {
+          signal: abort.signal,
+          onProgress: (fraction) => {
+            if (!abort.signal.aborted) setState((s) => ({ ...s, progress: Math.min(1, (done + fraction * weight) / total) }));
+          },
+        });
+        const ref: FileRef = { key: object.key, name: object.name ?? nameOf(file), contentType: object.contentType, size: object.size };
+        try {
+          await opts.current.onUpload?.(ref);
+        } catch (e) {
+          await storage.delete(ref.key).catch(() => {});
+          throw e;
+        }
+        stored.push(ref);
+      } catch (e) {
+        if (abort.signal.aborted) return stored;
+        error = asError(e);
+      }
+      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 }));
+    return stored;
+  }
+
+  function upload(input: Parameters<Upload["upload"]>[0]): Promise<FileRef[]> {
+    const { accept, maxBytes } = opts.current;
+    const files = toList(input);
+    if (!files.length) return Promise.resolve([]);
+    const rejected = files.find((f) => !acceptsFile(accept, f)) ?? files.find((f) => maxBytes !== undefined && f.size > maxBytes);
+    if (rejected) {
+      const message = acceptsFile(accept, rejected)
+        ? `${nameOf(rejected)} is larger than ${formatBytes(maxBytes!)}.`
+        : `${nameOf(rejected)} is not an accepted file type.`;
+      setState((s) => ({ ...s, error: new EraspaceError("StorageError", message) }));
+      return Promise.resolve([]);
+    }
+    const abort = (controller.current ??= new AbortController());
+    const batch = queue.current.then(() => run(files, abort));
+    queue.current = batch.catch(() => {});
+    return batch;
+  }
+
+  return {
+    upload,
+    uploading: state.uploading,
+    progress: state.progress,
+    error: state.error,
+    reset() {
+      controller.current?.abort();
+      controller.current = null;
+      setState({ uploading: false, progress: 0, error: null });
+    },
+  };
+}
+
+export interface FileUploadProps extends UseUploadOptions {
+  /** The app client, from `createClient()`. */
+  client: StorageHolder;
+  multiple?: boolean;
+  disabled?: boolean;
+  /** Classes for the drop zone. Without them it has a small default style. It has `data-dragging` during a drag. */
+  class?: string;
+  /** The drop zone's label. Defaults to "Drop a file here or click to upload". */
+  children?: ComponentChildren;
+}
+
+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";
+
+/** 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;
+  const state = useUpload(client.storage, props);
+  const [dragging, setDragging] = useState(false);
+  const off = disabled || state.uploading;
+  const style = props.class
+    ? undefined
+    : `position:relative;display:flex;flex-direction:column;align-items:center;gap:.5rem;padding:1.25rem;border:2px dashed ${dragging ? "#64748b" : "#cbd5e1"};border-radius:.75rem;background:${dragging ? "#f1f5f9" : "transparent"};color:#475569;text-align:center;cursor:${off ? "default" : "pointer"};opacity:${disabled ? ".6" : "1"}`;
+  const drop = (e: TargetedDragEvent<HTMLLabelElement>) => {
+    e.preventDefault();
+    setDragging(false);
+    if (off) return;
+    const files: Blob[] = Array.from(e.dataTransfer?.files ?? []);
+    void state.upload(multiple ? files : files.slice(0, 1));
+  };
+  return h(
+    Fragment,
+    null,
+    h(
+      "label",
+      {
+        class: props.class,
+        style,
+        "data-dragging": dragging ? "" : undefined,
+        "aria-busy": state.uploading,
+        onDragOver: (e: TargetedDragEvent<HTMLLabelElement>) => {
+          e.preventDefault();
+          if (!off) setDragging(true);
+        },
+        onDragLeave: () => setDragging(false),
+        onDrop: drop,
+      },
+      h("input", {
+        type: "file",
+        accept: props.accept,
+        multiple,
+        disabled: off,
+        style: VISUALLY_HIDDEN,
+        onChange: (e: TargetedEvent<HTMLInputElement>) => {
+          const input = e.currentTarget;
+          const files: Blob[] = Array.from(input.files ?? []);
+          input.value = "";
+          void state.upload(files);
+        },
+      }),
+      state.uploading
+        ? h(
+            Fragment,
+            null,
+            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" }),
+          )
+        : (children ?? h("span", null, multiple ? "Drop files here or click to upload" : "Drop a file here or click to upload")),
+    ),
+    state.error && h("p", { role: "alert", style: props.class ? undefined : "color:#b91c1c;margin:.5rem 0 0" }, state.error.message),
+  );
+}
+
+// Metadata lookups for previews given only a key, shared across components. Only found files stay cached, so a
+// missing file or a failed request is asked again on the next attempt.
+const infoCache = new Map<string, Promise<UploadedObject | null>>();
+
+function lookup(storage: StorageClient, key: string): Promise<UploadedObject | null> {
+  const id = storage.url(key);
+  let pending = infoCache.get(id);
+  if (!pending) {
+    if (infoCache.size >= 500) infoCache.delete(infoCache.keys().next().value!);
+    pending = storage.info(key);
+    infoCache.set(id, pending);
+    pending.then((info) => info || infoCache.delete(id), () => infoCache.delete(id));
+  }
+  return pending;
+}
+
+export interface FilePreviewProps {
+  /** The app client, from `createClient()`. */
+  client: StorageHolder;
+  /** A storage key, or a saved file. Without `contentType`, the preview looks the file up first. */
+  file: string | { key: string; name?: string | null; contentType?: string | null; size?: number | null };
+  class?: string;
+  /** Image alt text. Defaults to the file name. */
+  alt?: string;
+  /** Show the name, size and a download link under images, video and audio (default true). */
+  caption?: boolean;
+}
+
+type Kind = "image" | "video" | "audio" | "text" | "file";
+
+function kindOf(contentType: string): Kind {
+  const type = contentType.split(";")[0]!.trim().toLowerCase();
+  if (type.startsWith("image/")) return "image";
+  if (type.startsWith("video/")) return "video";
+  if (type.startsWith("audio/")) return "audio";
+  if (type === "text/plain") return "text";
+  return "file";
+}
+
+const MEDIA = "display:block;max-width:100%;border-radius:.5rem";
+
+/**
+ * Shows a stored file by type: images, video and audio inline, plain text in a sandboxed frame, and anything else
+ * as a download card. The URL always comes from the key, never from saved data.
+ */
+export function FilePreview(props: FilePreviewProps) {
+  const { client, file } = props;
+  const given = typeof file === "string" ? { key: file } : (file ?? { key: "" });
+  const key = isStorageKey(given.key) ? given.key : null;
+  const known = typeof given.contentType === "string" && given.contentType ? given : null;
+  // `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);
+  const [attempt, setAttempt] = useState(0);
+  useEffect(() => {
+    if (!key || known) return;
+    let live = true;
+    lookup(client.storage, key).then(
+      (info) => live && setFetched({ key, info }),
+      () => live && setFetched({ key, info: "failed" }),
+    );
+    return () => {
+      live = false;
+    };
+  }, [client.storage, key, !!known, attempt]);
+
+  const plain = !props.class;
+  const box = (body: ComponentChildren, extra?: Record<string, unknown>) =>
+    h("figure", { class: props.class, style: plain ? "margin:0;max-width:100%" : undefined, ...extra }, body);
+  const card = (label: ComponentChildren, href?: string, name?: string) =>
+    box(
+      h(
+        href ? "a" : "div",
+        {
+          href,
+          download: href ? name : undefined,
+          style: "display:inline-flex;align-items:center;gap:.5rem;padding:.625rem .875rem;border:1px solid #e2e8f0;border-radius:.5rem;color:inherit;text-decoration:none;max-width:100%",
+        },
+        label,
+      ),
+    );
+
+  if (!key) return card(h("span", { style: "color:#64748b" }, "File unavailable"));
+  const meta = known ?? (fetched?.key === key ? fetched.info : undefined);
+  if (meta === undefined && broken !== key) return box(h("div", { style: "height:3rem;border-radius:.5rem;background:#f1f5f9" }), { "aria-busy": true });
+  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 = () => {
+      setBroken(null);
+      setFetched(undefined);
+      setAttempt((n) => n + 1);
+    };
+    return card([
+      h("span", { style: "color:#64748b" }, meta === null ? "File unavailable" : "Could not load the file"),
+      h("button", { type: "button", onClick: retry, style: plain ? "font:inherit;padding:.125rem .5rem;border:1px solid #cbd5e1;border-radius:.375rem;background:transparent;color:inherit;cursor:pointer" : undefined }, "Retry"),
+    ]);
+  }
+
+  const url = client.storage.url(key);
+  const name = meta.name || "file";
+  const size = typeof meta.size === "number" ? formatBytes(meta.size) : "";
+  const fail = () => setBroken(key);
+  const caption = props.caption === false
+    ? null
+    : h(
+        "figcaption",
+        { style: plain ? "display:flex;gap:.5rem;align-items:baseline;margin-top:.375rem;font-size:.875rem;color:#64748b" : undefined },
+        h("a", { href: url, download: name, style: plain ? "color:inherit;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" : undefined }, name),
+        size && h("span", null, size),
+      );
+  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 })),
+        caption,
+      ]);
+    case "video":
+      return box([h("video", { src: url, 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]);
+    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 }),
+        caption,
+      ]);
+    default:
+      return card([h("span", { "aria-hidden": true }, "📄"), h("span", { style: "overflow:hidden;text-overflow:ellipsis;white-space:nowrap" }, name), size && h("span", { style: "color:#64748b;font-size:.875rem" }, size)], url, name);
+  }
+}

package/sdk/src/client/index.ts

@@ -1,4 +1,4 @@
-// eraspace/client: typed hooks over Phoenix Channels, routing, and mount().
+// eraspace/client: typed hooks over native WebSockets, routing, and mount().
 export {
   createClient,
   readConfig,
@@ -13,8 +13,9 @@ export {
   type EraspaceClient,
   type EraspaceConfig,
 } from "./client.ts";
-export { EraspaceError, isEraspaceError } from "./errors.ts";
-export type { StorageClient, UploadedObject } from "./storage.ts";
+export { EraspaceError, OutcomeUnknownError, isEraspaceError } from "./errors.ts";
+export { isStorageKey, type StorageClient, type StorageUploadOptions, type UploadedObject } from "./storage.ts";
+export { FileUpload, FilePreview, formatBytes, type FileRef, type FilePreviewProps, type FileUploadProps, type Upload, type UseUploadOptions } from "./files.ts";
 export { mount, ErrorBoundary, type ErrorBoundaryProps, type MountOptions } from "./mount.ts";
 export {
   LocationProvider,

package/sdk/src/client/pagination.ts

@@ -22,12 +22,15 @@ export class Pager {
     this.result = computed(() => {
       const pages = this.pages.value;
       const results: any[] = [];
-      let loading = false;
+      // Before start() subscribes the first page, nothing has loaded yet.
+      let loading = pages.length === 0;
       let done = false;
-      for (const p of pages) {
+      for (const [index, p] of pages.entries()) {
         const err = p.error.value;
-        if (err) throw err;
         const v = p.value.value as PaginationResult<any> | undefined;
+        // As with useQuery, a failing page keeps its last result while it retries. A first page with no result
+        // reports the error; a later one counts as still loading. A gone app cannot recover.
+        if (err && (err.name === "AppGone" || (v === undefined && index === 0))) throw err;
         if (v === undefined) {
           loading = true;
           break;

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

@@ -0,0 +1,13 @@
+/** A random UUIDv7 whose timestamp lets the server reject retries after result retention expires. */
+export function requestKey(now = Date.now()): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  let timestamp = Math.max(0, Math.floor(now));
+  for (let i = 5; i >= 0; i--) {
+    bytes[i] = timestamp % 256;
+    timestamp = Math.floor(timestamp / 256);
+  }
+  bytes[6] = (bytes[6]! & 0x0f) | 0x70;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/sdk/src/client/retry.ts

@@ -0,0 +1,5 @@
+/** Bounded exponential backoff with equal jitter keeps reconnects spread across clients. */
+export function retryDelay(attempt: number): number {
+  const ceiling = Math.min(30_000, 1_000 * 2 ** Math.min(Math.max(0, attempt - 1), 5));
+  return ceiling * (0.5 + Math.random() * 0.5);
+}

package/sdk/src/client/room.ts

@@ -1,14 +1,20 @@
-import { Presence, type Socket, type Channel } from "phoenix";
+import type { Socket, Channel } from "./transport.ts";
 import { signal, type Signal } from "@preact/signals";
 import type { PresenceEntry } from "./types.ts";
+import { EraspaceError } from "./errors.ts";
 import { stableStringify } from "./sub-key.ts";
 
 export class RoomConn {
   channel: Channel;
-  presence: Presence;
-  readonly members: Signal<PresenceEntry<any>[]> = signal([]);
+  readonly members: Signal<PresenceEntry<Record<string, unknown>>[]> = signal([]);
   readonly state: Signal<Record<string, unknown>> = signal({});
   readonly self: Signal<string>;
+  readonly error = signal<EraspaceError | undefined>(undefined);
+  private serverState: Record<string, unknown> = {};
+  private pending = new Map<number, { key: string; value: unknown }>();
+  private revisions = new Map<string, number>();
+  private nextChange = 0;
+  private closed = false;
   refs = 0;
   meta: Record<string, unknown> = {};
   listeners = new Map<string, Set<(payload: any, from: string | undefined) => void>>();
@@ -20,12 +26,8 @@ export class RoomConn {
     // 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<Record<string, Record<string, unknown>[]>>("presence", (members) => {
+      this.members.value = Object.entries(members).map(([id, metas]) => ({ id, meta: metas[0] ?? {}, metas }));
     });
     this.channel.on("msg", (m: { event: string; payload: unknown; from?: string }) => {
       const set = this.listeners.get(m.event);
@@ -34,25 +36,75 @@ export class RoomConn {
       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.serverState = { ...(m.state ?? {}) };
+      this.revisions.clear();
+      // Writes buffered while joining still need their replies to settle or report an error.
+      this.recompute();
     });
     this.channel.on("state", (m: { key: string; value: unknown }) => {
-      this.state.value = { ...this.state.value, [m.key]: m.value };
+      this.serverState = { ...this.serverState, [m.key]: m.value };
+      this.revisions.set(m.key, (this.revisions.get(m.key) ?? 0) + 1);
+      this.recompute();
     });
-    this.channel.join().receive("ok", (resp: { self?: string } | undefined) => {
+    const failed = (payload: unknown) => {
+      this.pending.clear();
+      this.recompute();
+      this.error.value = EraspaceError.from(payload, "Room channel disconnected");
+      if (payload && typeof payload === "object" && "name" in payload && payload.name === "AppGone") this.close();
+    };
+    this.channel.on("gone", () => failed({ name: "AppGone", message: "This app is no longer serving", reason: "gone" }));
+    this.channel.onError(failed);
+    this.channel.onClose(() => { if (!this.closed) failed({ name: "UnavailableError", message: "Room channel closed" }); });
+    this.channel.onJoin((resp) => {
+      this.error.value = undefined;
       if (resp && typeof resp.self === "string") this.self.value = clientSelf.value = resp.self;
     });
+    this.channel.join();
   }
 
   setMeta(meta: Record<string, unknown>): void {
     if (stableStringify(meta) === stableStringify(this.meta)) return;
+    const previous = this.meta;
     this.meta = meta;
-    this.channel.push("meta", { meta });
+    const failed = (payload: unknown) => {
+      if (this.meta === meta) this.meta = previous;
+      this.error.value = EraspaceError.from(payload, "Room metadata update failed");
+    };
+    void this.channel.push("meta", { meta }).catch(failed);
+  }
+
+  private recompute(): void {
+    const state = { ...this.serverState };
+    for (const { key, value } of this.pending.values()) state[key] = value;
+    this.state.value = state;
+  }
+
+  setState(key: string, value: unknown): void {
+    if (this.closed) return;
+    const id = ++this.nextChange;
+    const revision = this.revisions.get(key) ?? 0;
+    this.pending.set(id, { key, value: value ?? null });
+    this.recompute();
+    const failed = (payload: unknown) => {
+      if (!this.pending.delete(id)) return;
+      this.recompute();
+      this.error.value = EraspaceError.from(payload, "Room state update failed");
+    };
+    void this.channel.push("state:set", { key, value: value ?? null })
+      .then(() => {
+        if (!this.pending.delete(id)) return;
+        if ((this.revisions.get(key) ?? 0) === revision) this.serverState = { ...this.serverState, [key]: value ?? null };
+        this.error.value = undefined;
+        this.recompute();
+      }, failed);
+  }
+
+  close(): void {
+    this.closed = true;
+    clearTimeout(this.timer);
+    this.pending.clear();
+    this.recompute();
+    this.channel.leave();
   }
-}
 
-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

@@ -118,17 +118,26 @@ export function Router(props: {
 }) {
   const hasProvider = !!useContext(ctx)?.url;
   const routes = toChildArray(props.children).some(isRouteChild);
-  // preact-iso serializes route props; rendered VNodes contain circular parent links.
+  // preact-iso serializes route props, and rendered VNodes contain circular parent links, so elements travel in
+  // a function. It re-renders a matched route only when the URL or those serialized props change, and functions
+  // do not serialize: the revision marks every new element as a change. ElementRoute stays the same component,
+  // so the route updates in place instead of remounting.
   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 });
+    return h(Route, { ...rest, key: child.key, component: ElementRoute, render: () => element, revision: ++elementRevision });
   }), [props.children]);
   const content = routes ? h(IsoRouter as ComponentType<typeof props>, { ...props, children }) : props.children;
   return hasProvider ? (content as any) : h(LocationProvider, null, content);
 }
 
+let elementRevision = 0;
+
+function ElementRoute(props: { render: () => JSX.Element | null }) {
+  return props.render();
+}
+
 /** Alias of `<Router>` (react-router style naming). */
 export const Routes = Router;