eraspace 0.0.0-stage → 0.2.0

package/sdk/src/client/errors.ts

@@ -0,0 +1,37 @@
+/**
+ * An error raised by a server handler (or the transport). `name` is the server error name, for example `Error`,
+ * `TypeError`, or `OutcomeUnknownError` when a mutation or action could have applied.
+ */
+export class EraspaceError extends Error {
+  readonly data?: unknown;
+  constructor(name: string, message: string, data?: unknown) {
+    super(message);
+    this.name = name;
+    if (data !== undefined) this.data = data;
+  }
+
+  static from(payload: unknown, fallback = "Request failed"): EraspaceError {
+    if (payload && typeof payload === "object") {
+      const p = payload as { name?: unknown; message?: unknown; data?: unknown };
+      return new EraspaceError(
+        typeof p.name === "string" ? p.name : "Error",
+        typeof p.message === "string" ? p.message : fallback,
+        p.data,
+      );
+    }
+    return new EraspaceError("Error", typeof payload === "string" ? payload : fallback);
+  }
+}
+
+export function isEraspaceError(e: unknown): e is EraspaceError {
+  return e instanceof EraspaceError;
+}
+
+/** The mutation may have committed. Recover with `client.retryMutation(name, args, error.requestKey)`. */
+export class OutcomeUnknownError extends EraspaceError {
+  readonly requestKey: string;
+  constructor(requestKey: string, message = "The request's outcome is unknown") {
+    super("OutcomeUnknownError", message);
+    this.requestKey = requestKey;
+  }
+}

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

@@ -0,0 +1,36 @@
+// eraspace/client: typed hooks over native WebSockets, routing, and mount().
+export {
+  createClient,
+  readConfig,
+  subKey,
+  type ClientOptions,
+  type MutationOptions,
+  type OptimisticStore,
+  type PaginatedQueryName,
+  type PaginatedQueryResult,
+  type PresenceEntry,
+  type Room,
+  type EraspaceClient,
+  type EraspaceConfig,
+} from "./client.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,
+  Router,
+  Routes,
+  Route,
+  Link,
+  useLocation,
+  useNavigate,
+  useParams,
+  useRoute,
+  stripBase,
+  withBase,
+  type LocationValue,
+  type RouteProps,
+} from "./router.ts";
+export { signal, computed, effect, batch, useSignal, useComputed, useSignalEffect, type Signal, type ReadonlySignal } from "@preact/signals";
+export type { Id, Doc, PaginationOptions, PaginationResult } from "../server/index.ts";

package/sdk/src/client/mount.ts

@@ -0,0 +1,45 @@
+import { Component, h, render, type ComponentChildren, type ComponentType } from "preact";
+import { LocationProvider } from "./router.ts";
+
+export interface ErrorBoundaryProps {
+  children?: ComponentChildren;
+  /** Render a fallback for `error`. `retry` re-renders the subtree. */
+  fallback?: (error: Error, retry: () => void) => ComponentChildren;
+}
+
+/** Catches render errors (including query errors thrown by `useQuery`) in its subtree. */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, { error: Error | null }> {
+  state = { error: null as Error | null };
+  static getDerivedStateFromError(error: unknown) {
+    return { error: error instanceof Error ? error : new Error(String(error)) };
+  }
+  componentDidCatch(error: unknown) {
+    console.error(error);
+  }
+  retry = () => this.setState({ error: null });
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+    if (this.props.fallback) return this.props.fallback(error, this.retry);
+    return h(
+      "div",
+      { role: "alert", style: "font-family:system-ui,sans-serif;padding:1.5rem;max-width:40rem;margin:2rem auto" },
+      h("p", { style: "font-weight:600;margin:0 0 .5rem" }, "Something went wrong"),
+      h("pre", { style: "white-space:pre-wrap;color:#b91c1c;margin:0 0 1rem" }, `${error.name}: ${error.message}`),
+      h("button", { type: "button", onClick: this.retry, style: "padding:.375rem .75rem;border:1px solid #ccc;border-radius:.375rem" }, "Retry"),
+    );
+  }
+}
+
+export interface MountOptions {
+  /** Provide the app-relative location for `useLocation`, `<Link>` and `<Router>` (default true). */
+  router?: boolean;
+}
+
+/** Render `App` into `#app` (or `target`) inside a LocationProvider and an ErrorBoundary. */
+export function mount(App: ComponentType<{}>, target?: Element | null, options: MountOptions = {}): void {
+  const el = target ?? document.getElementById("app");
+  if (!el) throw new Error("eraspace: mount() could not find #app");
+  const app = h(ErrorBoundary, null, h(App, null));
+  render(options.router === false ? app : h(LocationProvider, null, app), el);
+}

package/sdk/src/client/pagination.ts

@@ -0,0 +1,104 @@
+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[] = [];
+      // Before start() subscribes the first page, nothing has loaded yet.
+      let loading = pages.length === 0;
+      let done = false;
+      for (const [index, p] of pages.entries()) {
+        const err = p.error.value;
+        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;
+        }
+        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/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/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/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);
+}