@frockbot/applet-sdk 0.7.20 → 0.7.22

package/README.md

@@ -51,20 +51,33 @@ The Cloudflare programming model is not hidden: an Applet is a Durable Object
 with SQLite and hibernating sockets. What the SDK does hide is every binding
 name — an author sees `tables`, `tools`, and `this.db`.
 
-## Wire protocol v1
+## Wire protocol
 
 JSON frames, at most 64 KB each, decoded by `src/protocol/` at both ends;
-an unknown type, field, or table fails closed.
-
-| Direction       | Frame      | Carries                                                     |
-| --------------- | ---------- | ----------------------------------------------------------- |
-| server → client | `hello`    | contract, generationId, viewer, tables, revision, cursor    |
-| client → server | `hello`    | contract, optional `since` cursor for catch-up              |
-| server → client | `snapshot` | every row of every table, plus the cursor                   |
-| server → client | `changes`  | ordered row changes, optionally tagged with a client txn id |
-| client → server | `mutate`   | one client transaction: insert/update/delete                |
-| server → client | `ack`      | the resulting rows for that txn                             |
-| server → client | `reject`   | why the txn was refused (the client rolls back)             |
+an unknown type, field, or table fails closed. Two versions are spoken on the
+same server, told apart by the socket URL: a page built against v2 opens with
+`v=2`, and a page built before it opens with nothing and is spoken to in v1.
+
+| Direction       | Frame      | Carries                                                                                     |
+| --------------- | ---------- | ------------------------------------------------------------------------------------------- |
+| server → client | `hello`    | contract, generationId, viewer, tables, revision, cursor — and in v2, the `snapshot` itself |
+| client → server | `hello`    | contract, optional `since` cursor for catch-up; in v2 only on a resume or when asked        |
+| server → client | `snapshot` | every row of every table, plus the cursor                                                   |
+| server → client | `changes`  | ordered row changes, optionally tagged with a client txn id                                 |
+| client → server | `mutate`   | one client transaction: insert/update/delete                                                |
+| server → client | `ack`      | the resulting rows for that txn                                                             |
+| server → client | `reject`   | why the txn was refused (the client rolls back)                                             |
+
+The host hands the page its credential in an `init` postMessage, and a fresh
+credential later in a `refresh` of the same shape; the page reconnects in
+place rather than being reloaded, and with its cursor on the URL that is the
+`changes` path.
+
+A v2 page's first render waits on one frame: the server's `hello` carries the
+snapshot when the URL named no `since` cursor, and the page marks its
+collections ready on it. A reconnect puts `since` on the URL, gets a plain
+`hello`, and asks for `changes` as v1 does. A snapshot that would not fit the
+frame is left out of the hello and the v1 exchange follows.
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/applet-sdk",
-  "version": "0.7.20",
+  "version": "0.7.22",
   "private": false,
   "type": "module",
   "description": "Authoring SDK for FrockBot Applets: schema-first Durable Object server, TanStack DB client, component kit, linter, and the build pipeline.",

package/src/client/index.ts

@@ -87,8 +87,13 @@ export interface CreateAppletOptions extends AppletTransportOptions {
   autoConnect?: boolean;
 }
 
-/** The host's `init`, with the fields an Applet page needs. */
+/**
+ * The host's `init`, with the fields an Applet page needs — or its `refresh`,
+ * the same shape carrying a fresh viewer credential for a page that is
+ * already running, so the document need not be rebuilt to hold it.
+ */
 export interface AppletHostInitV1 {
+  type: "init" | "refresh";
   themeTokens: Record<string, string>;
   applet: AppletInitV1;
 }
@@ -96,7 +101,8 @@ export interface AppletHostInitV1 {
 function decodeHostInit(data: unknown): AppletHostInitV1 | undefined {
   if (!data || typeof data !== "object") return undefined;
   const message = data as Record<string, unknown>;
-  if (message.schemaVersion !== 1 || message.type !== "init") return undefined;
+  if (message.schemaVersion !== 1) return undefined;
+  if (message.type !== "init" && message.type !== "refresh") return undefined;
   const applet = message.applet;
   const tokens = message.themeTokens;
   if (!applet || typeof applet !== "object") return undefined;
@@ -118,6 +124,7 @@ function decodeHostInit(data: unknown): AppletHostInitV1 | undefined {
     }
   }
   return {
+    type: message.type,
     themeTokens,
     applet: {
       socketUrl: value.socketUrl,
@@ -126,10 +133,24 @@ function decodeHostInit(data: unknown): AppletHostInitV1 | undefined {
       ...(value.tokenTransport === "subprotocol-v1"
         ? { tokenTransport: "subprotocol-v1" as const }
         : {}),
+      ...(value.timing === true ? { timing: true } : {}),
     },
   };
 }
 
+/**
+ * One hop of the open path, posted to the host when its `init` asked for
+ * timing. The host keeps the log; the page only says when each hop landed,
+ * in its own clock, so the host can line them up with its own hops.
+ */
+function postTiming(hop: string): void {
+  if (typeof window === "undefined") return;
+  window.parent.postMessage(
+    { schemaVersion: 1, type: "applet/timing", hop, at: performance.now() },
+    "*",
+  );
+}
+
 /** Paint the host's semantic tokens onto the page as `--frockbot-*`. */
 export function applyThemeTokens(tokens: Record<string, string>): void {
   if (typeof document === "undefined") return;
@@ -138,7 +159,7 @@ export function applyThemeTokens(tokens: Record<string, string>): void {
   }
 }
 
-/** Subscribe to the host's `init` message. Returns an unsubscribe function. */
+/** Subscribe to the host's `init` and `refresh` messages. Returns an unsubscribe function. */
 export function listenForAppletInit(
   handler: (init: AppletHostInitV1) => void,
 ): () => void {
@@ -156,7 +177,19 @@ export function createApplet<TServer extends { tables: TablesShape }>(
   options: CreateAppletOptions = {},
 ): AppletClient<TServer["tables"]> {
   const { autoConnect, ...transportOptions } = options;
-  const transport = new AppletTransport(transportOptions);
+  const transport = new AppletTransport({
+    onTiming: (hop) => {
+      postTiming(hop);
+      // `ready` is the collections marked ready; the first paint of what
+      // they hold is the frame after React commits it.
+      if (hop === "ready" && typeof requestAnimationFrame === "function") {
+        requestAnimationFrame(() =>
+          requestAnimationFrame(() => postTiming("first-render")),
+        );
+      }
+    },
+    ...transportOptions,
+  });
   const collections = new Map<string, Collection<AppletRow, string>>();
 
   const tables = new Proxy({} as Record<string, unknown>, {
@@ -179,7 +212,8 @@ export function createApplet<TServer extends { tables: TablesShape }>(
     listenForAppletInit((init) => {
       applyThemeTokens(init.themeTokens);
       lastInit = init.applet;
-      transport.connect(init.applet);
+      if (init.type === "refresh") transport.refresh(init.applet);
+      else transport.connect(init.applet);
     });
     window.parent.postMessage(
       {

package/src/client/transport.ts

@@ -9,10 +9,12 @@
 
 import {
   APPLET_CONTRACT_VERSION,
+  APPLET_PROTOCOL_VERSION,
   decodeServerFrame,
   encodeFrame,
   type AppletChangeV1,
   type AppletMutationV1,
+  type AppletSnapshotTablesV1,
   type AppletViewerV1,
 } from "../protocol/index.js";
 
@@ -23,8 +25,16 @@ export interface AppletInitV1 {
   token: string;
   generationId: string;
   tokenTransport?: "subprotocol-v1";
+  /**
+   * Report each hop of the open path — socket open, hello, ready — to the
+   * host, for the timing log it keeps behind its own flag. Off by default.
+   */
+  timing?: boolean;
 }
 
+/** The hops a page reports when the host asked for timing. */
+export type AppletTimingHop = "socket-open" | "hello" | "ready";
+
 export type AppletStatus =
   "idle" | "connecting" | "ready" | "reconnecting" | "closed";
 
@@ -69,6 +79,8 @@ export interface AppletTransportOptions {
   maximumBackoffMs?: number;
   /** Scheduler seam so tests do not wait in real time. */
   schedule?: (closure: () => void, delayMs: number) => unknown;
+  /** Where a timing hop goes when `init.timing` is set; the page posts to its host. */
+  onTiming?: (hop: AppletTimingHop) => void;
 }
 
 class RejectedMutation extends Error {}
@@ -78,8 +90,11 @@ function defaultSocketFactory(url: string, protocols?: string[]): AppletSocket {
 }
 
 export class AppletTransport {
-  #options: Required<Omit<AppletTransportOptions, "socketFactory">> & {
+  #options: Required<
+    Omit<AppletTransportOptions, "socketFactory" | "onTiming">
+  > & {
     socketFactory: AppletSocketFactory;
+    onTiming: ((hop: AppletTimingHop) => void) | undefined;
   };
   #socket?: AppletSocket;
   #init?: AppletInitV1;
@@ -117,6 +132,13 @@ export class AppletTransport {
    */
   #retrySeq = 0;
   #pendingRetryId = 0;
+  /**
+   * Whether this socket has sent its own `hello`. A v2 socket that opened with
+   * no cursor sends none: the server's `hello` carries the snapshot, and only
+   * a hello that arrives without one — a server that could not fit it, or one
+   * that speaks v1 — is answered.
+   */
+  #helloSent = false;
 
   constructor(options: AppletTransportOptions = {}) {
     this.#options = {
@@ -125,6 +147,7 @@ export class AppletTransport {
       maximumBackoffMs: options.maximumBackoffMs ?? 8_000,
       schedule:
         options.schedule ?? ((closure, delay) => setTimeout(closure, delay)),
+      onTiming: options.onTiming,
     };
   }
 
@@ -151,6 +174,30 @@ export class AppletTransport {
     this.#open();
   }
 
+  /**
+   * A fresh viewer credential for the page that is already running: the
+   * host's `refresh` message. The document stays; the transport reconnects
+   * in place with the new token, and since it carries its cursor the server
+   * answers with `changes` rather than a snapshot. The same credential
+   * offered twice — a host re-sending what the page already holds — is not
+   * a reason to drop a live socket.
+   */
+  refresh(init: AppletInitV1): void {
+    const held = this.#init;
+    if (
+      held &&
+      this.#socket &&
+      !this.#closed &&
+      held.token === init.token &&
+      held.socketUrl === init.socketUrl &&
+      held.generationId === init.generationId
+    ) {
+      this.#init = init;
+      return;
+    }
+    this.connect(init);
+  }
+
   close(): void {
     this.#closed = true;
     this.#reset(1000, "closed");
@@ -189,6 +236,12 @@ export class AppletTransport {
       status: this.#attempt === 0 ? "connecting" : "reconnecting",
     });
     const url = new URL(this.#init.socketUrl);
+    // The version this page speaks and, on a reconnect, the cursor it will
+    // resume from, both settled before the first frame so the server's hello
+    // can carry the snapshot exactly when one is needed.
+    url.searchParams.set("v", String(APPLET_PROTOCOL_VERSION));
+    const since = this.#lastChangeId === 0 ? undefined : this.#lastChangeId;
+    if (since !== undefined) url.searchParams.set("since", String(since));
     const protocols =
       this.#init.tokenTransport === "subprotocol-v1"
         ? ["frockbot.applet.v1", `frockbot.viewer.${this.#init.token}`]
@@ -196,8 +249,14 @@ export class AppletTransport {
     if (!protocols) url.searchParams.set("token", this.#init.token);
     const socket = this.#options.socketFactory(url.toString(), protocols);
     this.#socket = socket;
+    this.#helloSent = false;
     socket.onopen = () => {
-      if (this.#currentSocketId === id) this.#handshake();
+      if (this.#currentSocketId !== id) return;
+      this.#timing("socket-open");
+      // A resume asks for its catch-up at once, crossing the server's hello
+      // on the wire as it always has. A first connection waits: the hello on
+      // its way carries the snapshot.
+      if (since !== undefined) this.#handshake();
     };
     socket.onmessage = (event) => {
       if (this.#currentSocketId === id) this.#receive(event.data);
@@ -208,14 +267,19 @@ export class AppletTransport {
 
   #handshake(): void {
     const since = this.#lastChangeId === 0 ? undefined : this.#lastChangeId;
+    this.#helloSent = true;
     this.#write({
-      v: 1,
+      v: APPLET_PROTOCOL_VERSION,
       type: "hello",
       contract: APPLET_CONTRACT_VERSION,
       ...(since === undefined ? {} : { since }),
     });
   }
 
+  #timing(hop: AppletTimingHop): void {
+    if (this.#init?.timing) this.#options.onTiming?.(hop);
+  }
+
   /**
    * One failure reaches here twice — `error` then `close` — and a socket the
    * transport already replaced can reach here at any time. Only the socket that
@@ -256,6 +320,7 @@ export class AppletTransport {
     }
 
     if (frame.type === "hello") {
+      this.#timing("hello");
       const changedGeneration =
         this.#state.generationId !== null &&
         this.#state.generationId !== frame.generationId;
@@ -268,28 +333,30 @@ export class AppletTransport {
         this.#lastChangeId = 0;
         this.#synced = false;
         this.#buffer = [];
-        this.#write({ v: 1, type: "hello", contract: APPLET_CONTRACT_VERSION });
+      }
+      if (frame.snapshot) {
+        // The whole state came with the greeting: render on it, and send
+        // nothing back. A hello for a new generation carries that
+        // generation's rows, so the reset above is what it needs.
+        this.#snapshot(frame.lastChangeId, frame.snapshot);
+        return;
+      }
+      if (changedGeneration || !this.#helloSent) {
+        // Nothing came with the greeting: a server that could not fit the
+        // snapshot, one that speaks v1, or new code over the same storage.
+        // Ask, as v1 always did.
+        this.#helloSent = true;
+        this.#write({
+          v: APPLET_PROTOCOL_VERSION,
+          type: "hello",
+          contract: APPLET_CONTRACT_VERSION,
+        });
       }
       return;
     }
 
     if (frame.type === "snapshot") {
-      this.#lastChangeId = frame.lastChangeId;
-      for (const [name, sink] of this.#sinks) {
-        // `truncate` only has meaning inside an open sync transaction.
-        sink.begin();
-        sink.truncate();
-        for (const row of frame.tables[name] ?? [])
-          sink.write({ type: "insert", value: row });
-        sink.commit();
-        sink.markReady();
-      }
-      this.#synced = true;
-      this.#attempt = 0;
-      this.#setState({ status: "ready" });
-      const buffered = this.#buffer;
-      this.#buffer = [];
-      if (buffered.length > 0) this.#apply(buffered);
+      this.#snapshot(frame.lastChangeId, frame.tables);
       return;
     }
 
@@ -302,6 +369,7 @@ export class AppletTransport {
         this.#attempt = 0;
         this.#setState({ status: "ready" });
         for (const sink of this.#sinks.values()) sink.markReady();
+        this.#timing("ready");
       }
       this.#apply(frame.changes);
       return;
@@ -321,6 +389,27 @@ export class AppletTransport {
     this.#pending.delete(frame.txnId);
   }
 
+  /** The whole state, from a `snapshot` frame or a v2 hello: replace and mark ready. */
+  #snapshot(lastChangeId: number, tables: AppletSnapshotTablesV1): void {
+    this.#lastChangeId = lastChangeId;
+    for (const [name, sink] of this.#sinks) {
+      // `truncate` only has meaning inside an open sync transaction.
+      sink.begin();
+      sink.truncate();
+      for (const row of tables[name] ?? [])
+        sink.write({ type: "insert", value: row });
+      sink.commit();
+      sink.markReady();
+    }
+    this.#synced = true;
+    this.#attempt = 0;
+    this.#setState({ status: "ready" });
+    this.#timing("ready");
+    const buffered = this.#buffer;
+    this.#buffer = [];
+    if (buffered.length > 0) this.#apply(buffered);
+  }
+
   #apply(changes: AppletChangeV1[]): void {
     if (!this.#synced) {
       this.#buffer.push(...changes);
@@ -366,7 +455,12 @@ export class AppletTransport {
       this.#resyncQueued = false;
       if (!this.#socket) return;
       this.#synced = false;
-      this.#write({ v: 1, type: "hello", contract: APPLET_CONTRACT_VERSION });
+      this.#helloSent = true;
+      this.#write({
+        v: APPLET_PROTOCOL_VERSION,
+        type: "hello",
+        contract: APPLET_CONTRACT_VERSION,
+      });
     });
   }
 
@@ -379,7 +473,12 @@ export class AppletTransport {
     return new Promise<AppletChangeV1[]>((resolve, reject) => {
       this.#pending.set(txnId, { resolve, reject });
       try {
-        this.#write({ v: 1, type: "mutate", txnId, mutations });
+        this.#write({
+          v: APPLET_PROTOCOL_VERSION,
+          type: "mutate",
+          txnId,
+          mutations,
+        });
       } catch (error) {
         this.#pending.delete(txnId);
         reject(error instanceof Error ? error : new Error(String(error)));

package/src/protocol/index.ts

@@ -1,5 +1,5 @@
 /**
- * Applet wire protocol v1.
+ * Applet wire protocol, versions 1 and 2.
  *
  * One JSON frame per WebSocket message, at most 64 KB encoded. Both ends decode
  * with the functions here and nothing else: an unknown type, an unknown field,
@@ -7,17 +7,52 @@
  * that name a table or column it did not declare — that check needs the schema,
  * so it lives in `server/`, not here.
  *
- * Sequence:
+ * Sequence, v2 (a page that opened its socket with `v=2` in the URL):
+ *   server -> hello        on accept, carrying the `snapshot` when the URL
+ *                          named no `since` cursor; the page renders on it
+ *   client -> hello        only when it is resuming (`since`), or when the
+ *                          server's hello carried no snapshot
+ *   server -> changes      catch-up for a resumable cursor, else `snapshot`
+ *   client -> mutate       one client transaction
+ *   server -> ack|reject   to the originator; `changes` to every other socket
+ *
+ * Sequence, v1 (a page built before v2 sends no `v`):
  *   server -> hello        on accept (contract, generation, viewer, cursor)
  *   client -> hello        with `since` when it is resuming, otherwise absent
  *   server -> snapshot     full state, or `changes` when the cursor is resumable
- *   client -> mutate       one client transaction
- *   server -> ack|reject   to the originator; `changes` to every other socket
+ *   then as above
+ *
+ * The version a socket speaks is settled by its URL before the first frame,
+ * so a server never has to guess: the frames it sends carry that `v`, and a
+ * v1 page is spoken to exactly as it always was.
  */
 
 export const APPLET_CONTRACT_VERSION = 1 as const;
+/** The newest protocol this code speaks; a socket may still be spoken to in 1. */
+export const APPLET_PROTOCOL_VERSION = 2 as const;
+export type AppletProtocolVersion = 1 | 2;
 export const APPLET_FRAME_BYTE_LIMIT = 64 * 1024;
 
+/**
+ * What a socket's URL says about how to greet it: the protocol the page
+ * speaks and, on a reconnect, the cursor it will ask to resume from. Read on
+ * the server before the first frame, written by the client transport.
+ */
+export interface AppletHandshakeV1 {
+  protocol: AppletProtocolVersion;
+  since?: number;
+}
+
+export function appletHandshakeFromUrlV1(url: URL): AppletHandshakeV1 {
+  const protocol = url.searchParams.get("v") === "2" ? 2 : 1;
+  const since = url.searchParams.get("since");
+  const parsed = since === null ? Number.NaN : Number(since);
+  return {
+    protocol,
+    ...(Number.isSafeInteger(parsed) && parsed > 0 ? { since: parsed } : {}),
+  };
+}
+
 export type ChangeOperation = "insert" | "update" | "delete";
 
 export interface AppletChangeV1 {
@@ -43,9 +78,14 @@ export interface AppletViewerV1 {
   canWrite: boolean;
 }
 
+export type AppletSnapshotTablesV1 = Record<
+  string,
+  Array<Record<string, unknown>>
+>;
+
 export type AppletServerFrameV1 =
   | {
-      v: 1;
+      v: AppletProtocolVersion;
       type: "hello";
       contract: 1;
       generationId: string;
@@ -53,32 +93,54 @@ export type AppletServerFrameV1 =
       tables: string[];
       schemaRevision: number;
       lastChangeId: number;
+      /**
+       * Every row of every table as of `lastChangeId`, on a v2 socket that
+       * opened with no cursor: the page renders on this frame and sends no
+       * hello of its own. Absent when it would not fit the frame, in which
+       * case the v1 exchange follows.
+       */
+      snapshot?: AppletSnapshotTablesV1;
     }
   | {
-      v: 1;
+      v: AppletProtocolVersion;
       type: "snapshot";
       lastChangeId: number;
-      tables: Record<string, Array<Record<string, unknown>>>;
+      tables: AppletSnapshotTablesV1;
     }
   | {
-      v: 1;
+      v: AppletProtocolVersion;
       type: "changes";
       lastChangeId: number;
       txnId?: string;
       changes: AppletChangeV1[];
     }
   | {
-      v: 1;
+      v: AppletProtocolVersion;
       type: "ack";
       txnId: string;
       lastChangeId: number;
       changes: AppletChangeV1[];
     }
-  | { v: 1; type: "reject"; txnId: string; reason: string };
+  | {
+      v: AppletProtocolVersion;
+      type: "reject";
+      txnId: string;
+      reason: string;
+    };
 
 export type AppletClientFrameV1 =
-  | { v: 1; type: "hello"; contract: 1; since?: number }
-  | { v: 1; type: "mutate"; txnId: string; mutations: AppletMutationV1[] };
+  | {
+      v: AppletProtocolVersion;
+      type: "hello";
+      contract: 1;
+      since?: number;
+    }
+  | {
+      v: AppletProtocolVersion;
+      type: "mutate";
+      txnId: string;
+      mutations: AppletMutationV1[];
+    };
 
 export class AppletProtocolError extends Error {}
 
@@ -188,10 +250,30 @@ function parse(message: unknown, label: string): Record<string, unknown> {
     fail(`${label} is not valid JSON`);
   }
   const value = object(parsed, label);
-  if (value.v !== 1) fail(`${label} speaks an unsupported protocol version`);
+  if (value.v !== 1 && value.v !== 2) {
+    fail(`${label} speaks an unsupported protocol version`);
+  }
   return value;
 }
 
+function versionOf(value: Record<string, unknown>): AppletProtocolVersion {
+  return value.v === 2 ? 2 : 1;
+}
+
+function snapshotTables(value: unknown, label: string): AppletSnapshotTablesV1 {
+  const tables = object(value, label);
+  const decoded: AppletSnapshotTablesV1 = {};
+  for (const [table, rows] of Object.entries(tables)) {
+    const rowsLabel = `${label}.${table}`;
+    name(table, rowsLabel);
+    if (!Array.isArray(rows)) fail(`${rowsLabel} must be an array`);
+    decoded[table] = rows.map((entry, index) =>
+      row(entry, `${rowsLabel}[${index}]`),
+    );
+  }
+  return decoded;
+}
+
 function decodeChange(candidate: unknown, label: string): AppletChangeV1 {
   const value = object(candidate, label);
   exact(value, ["table", "op", "key"], ["row"], label);
@@ -225,7 +307,7 @@ export function decodeClientFrame(message: unknown): AppletClientFrameV1 {
         ? undefined
         : cursor(value.since, "Applet hello.since");
     return {
-      v: 1,
+      v: versionOf(value),
       type: "hello",
       contract: 1,
       ...(since === undefined ? {} : { since }),
@@ -267,7 +349,7 @@ export function decodeClientFrame(message: unknown): AppletClientFrameV1 {
       return decoded;
     });
     return {
-      v: 1,
+      v: versionOf(value),
       type: "mutate",
       txnId: bounded(value.txnId, "Applet mutate.txnId", 64),
       mutations,
@@ -292,7 +374,9 @@ export function decodeServerFrame(message: unknown): AppletServerFrameV1 {
         "schemaRevision",
         "lastChangeId",
       ],
-      [],
+      // A v1 speaker never sends a snapshot in its hello, so a v1 frame that
+      // carries one is not one this code produced.
+      versionOf(value) === 2 ? ["snapshot"] : [],
       "Applet server hello",
     );
     if (value.contract !== APPLET_CONTRACT_VERSION) {
@@ -307,7 +391,7 @@ export function decodeServerFrame(message: unknown): AppletServerFrameV1 {
       fail("Applet server hello.tables must be a bounded array");
     }
     return {
-      v: 1,
+      v: versionOf(value),
       type: "hello",
       contract: 1,
       generationId: bounded(
@@ -329,6 +413,14 @@ export function decodeServerFrame(message: unknown): AppletServerFrameV1 {
         value.lastChangeId,
         "Applet server hello.lastChangeId",
       ),
+      ...(value.snapshot === undefined
+        ? {}
+        : {
+            snapshot: snapshotTables(
+              value.snapshot,
+              "Applet server hello.snapshot",
+            ),
+          }),
     };
   }
   if (value.type === "snapshot") {
@@ -338,21 +430,11 @@ export function decodeServerFrame(message: unknown): AppletServerFrameV1 {
       [],
       "Applet snapshot",
     );
-    const tables = object(value.tables, "Applet snapshot.tables");
-    const decoded: Record<string, Array<Record<string, unknown>>> = {};
-    for (const [table, rows] of Object.entries(tables)) {
-      const label = `Applet snapshot.tables.${table}`;
-      name(table, label);
-      if (!Array.isArray(rows)) fail(`${label} must be an array`);
-      decoded[table] = rows.map((entry, index) =>
-        row(entry, `${label}[${index}]`),
-      );
-    }
     return {
-      v: 1,
+      v: versionOf(value),
       type: "snapshot",
       lastChangeId: cursor(value.lastChangeId, "Applet snapshot.lastChangeId"),
-      tables: decoded,
+      tables: snapshotTables(value.tables, "Applet snapshot.tables"),
     };
   }
   if (value.type === "changes") {
@@ -372,7 +454,7 @@ export function decodeServerFrame(message: unknown): AppletServerFrameV1 {
         ? undefined
         : bounded(value.txnId, "Applet changes.txnId", 64);
     return {
-      v: 1,
+      v: versionOf(value),
       type: "changes",
       lastChangeId: cursor(value.lastChangeId, "Applet changes.lastChangeId"),
       ...(txnId === undefined ? {} : { txnId }),
@@ -389,7 +471,7 @@ export function decodeServerFrame(message: unknown): AppletServerFrameV1 {
     if (!Array.isArray(value.changes))
       fail("Applet ack.changes must be an array");
     return {
-      v: 1,
+      v: versionOf(value),
       type: "ack",
       txnId: bounded(value.txnId, "Applet ack.txnId", 64),
       lastChangeId: cursor(value.lastChangeId, "Applet ack.lastChangeId"),
@@ -401,7 +483,7 @@ export function decodeServerFrame(message: unknown): AppletServerFrameV1 {
   if (value.type === "reject") {
     exact(value, ["v", "type", "txnId", "reason"], [], "Applet reject");
     return {
-      v: 1,
+      v: versionOf(value),
       type: "reject",
       txnId: bounded(value.txnId, "Applet reject.txnId", 64),
       reason: bounded(value.reason, "Applet reject.reason", 512),

package/src/server/applet.ts

@@ -15,8 +15,10 @@ import type {
 
 import {
   APPLET_CONTRACT_VERSION,
+  appletHandshakeFromUrlV1,
   encodeFrame,
   type AppletChangeV1,
+  type AppletProtocolVersion,
   type AppletViewerV1,
 } from "../protocol/index.js";
 import {
@@ -111,6 +113,8 @@ interface ViewerAttachment {
   viewer: AppletViewerV1;
   /** Set once the socket has been sent its snapshot or catch-up. */
   synced: boolean;
+  /** The protocol the page opened with; absent on a socket accepted before v2. */
+  protocol?: AppletProtocolVersion;
 }
 
 /**
@@ -293,6 +297,10 @@ export abstract class Applet<
           url.searchParams.get("canWrite") ??
           "true") !== "false",
     };
+    // The page's version and, on a reconnect, its cursor, both settled by the
+    // URL before the first frame. The kernel forwards the upgrade with the
+    // viewer token removed and everything else the page put there kept.
+    const handshake = appletHandshakeFromUrlV1(url);
     const pair = new WebSocketPair();
     const client = pair[0];
     const server = pair[1];
@@ -300,8 +308,9 @@ export abstract class Applet<
     server.serializeAttachment({
       viewer,
       synced: false,
+      protocol: handshake.protocol,
     } satisfies ViewerAttachment);
-    this.#protocol().greet(this.#peer(server));
+    this.#protocol().greet(this.#peer(server), handshake);
     return new Response(null, {
       status: 101,
       webSocket: client,
@@ -363,6 +372,7 @@ export abstract class Applet<
     }) as ViewerAttachment;
     return {
       viewer: attachment.viewer,
+      protocol: attachment.protocol ?? 1,
       get synced() {
         return attachment.synced;
       },

package/src/server/session.ts

@@ -11,6 +11,7 @@ import {
   AppletProtocolError,
   decodeClientFrame,
   type AppletChangeV1,
+  type AppletProtocolVersion,
   type AppletServerFrameV1,
   type AppletViewerV1,
 } from "../protocol/index.js";
@@ -20,6 +21,11 @@ export interface AppletPeer {
   send(frame: AppletServerFrameV1): void;
   close(code: number, reason: string): void;
   readonly viewer: AppletViewerV1;
+  /**
+   * The protocol this socket's page speaks, settled by its URL before the
+   * first frame. Every frame sent to it carries this `v`.
+   */
+  readonly protocol: AppletProtocolVersion;
   /** False until the peer has been sent a snapshot or a catch-up. */
   synced: boolean;
 }
@@ -39,10 +45,17 @@ export class AppletProtocolServer {
     private readonly options: AppletProtocolServerOptions,
   ) {}
 
-  /** The unprompted `hello` a peer gets the moment its socket is accepted. */
-  greet(peer: AppletPeer): void {
-    peer.send({
-      v: 1,
+  /**
+   * The unprompted `hello` a peer gets the moment its socket is accepted.
+   *
+   * A v2 page that opened with no cursor is handed the snapshot in the same
+   * frame, so its first render waits on nothing else. A page resuming from a
+   * cursor asks for its catch-up itself, as v1 always has, and a snapshot that
+   * would not fit the frame is left for the v1 exchange too.
+   */
+  greet(peer: AppletPeer, handshake: { since?: number } = {}): void {
+    const hello: AppletServerFrameV1 = {
+      v: peer.protocol,
       type: "hello",
       contract: APPLET_CONTRACT_VERSION,
       generationId: this.options.generationId,
@@ -50,7 +63,17 @@ export class AppletProtocolServer {
       tables: Object.keys(this.store.tables),
       schemaRevision: this.options.schemaRevision,
       lastChangeId: this.store.lastChangeId,
-    });
+    };
+    if (peer.protocol === 2 && handshake.since === undefined) {
+      try {
+        peer.send({ ...hello, snapshot: this.store.snapshot() });
+        peer.synced = true;
+        return;
+      } catch (error) {
+        if (!(error instanceof AppletProtocolError)) throw error;
+      }
+    }
+    peer.send(hello);
   }
 
   /** Handle one inbound frame. Never throws; a bad frame closes the socket. */
@@ -70,14 +93,14 @@ export class AppletProtocolServer {
           : this.store.changesSince(frame.since);
       if (catchUp) {
         peer.send({
-          v: 1,
+          v: peer.protocol,
           type: "changes",
           lastChangeId: this.store.lastChangeId,
           changes: catchUp,
         });
       } else {
         peer.send({
-          v: 1,
+          v: peer.protocol,
           type: "snapshot",
           lastChangeId: this.store.lastChangeId,
           tables: this.store.snapshot(),
@@ -89,7 +112,7 @@ export class AppletProtocolServer {
 
     if (!peer.viewer.canWrite) {
       peer.send({
-        v: 1,
+        v: peer.protocol,
         type: "reject",
         txnId: frame.txnId,
         reason: "This viewer may not write",
@@ -104,7 +127,7 @@ export class AppletProtocolServer {
       );
     } catch (error) {
       peer.send({
-        v: 1,
+        v: peer.protocol,
         type: "reject",
         txnId: frame.txnId,
         reason: describe(error),
@@ -113,7 +136,13 @@ export class AppletProtocolServer {
     }
 
     const lastChangeId = this.store.lastChangeId;
-    peer.send({ v: 1, type: "ack", txnId: frame.txnId, lastChangeId, changes });
+    peer.send({
+      v: peer.protocol,
+      type: "ack",
+      txnId: frame.txnId,
+      lastChangeId,
+      changes,
+    });
     this.broadcast(
       { v: 1, type: "changes", lastChangeId, txnId: frame.txnId, changes },
       peer,
@@ -131,17 +160,18 @@ export class AppletProtocolServer {
     });
   }
 
+  /** One frame to every synced peer, each in the version its socket speaks. */
   private broadcast(frame: AppletServerFrameV1, except?: AppletPeer): void {
     for (const peer of this.options.peers()) {
       if (peer === except || !peer.synced) continue;
       try {
-        peer.send(frame);
+        peer.send({ ...frame, v: peer.protocol });
       } catch (error) {
         if (!(error instanceof AppletProtocolError)) throw error;
         // A batch too large for one frame: tell the peer where the log now is
         // and let it resync from there rather than silently diverge.
         peer.send({
-          v: 1,
+          v: peer.protocol,
           type: "changes",
           lastChangeId: this.store.lastChangeId,
           changes: [],