@vantage-ui/client 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.6.0 — 2026-10-28
+
+- Anonymous sessions (vantage-server 1.9.0, `session: { anonymous: true }`): `db.sessionToken` holds `welcome.session_token`, and `hello` resends it whenever `token` gives none, so a reconnect resumes the session and its grants. `createVantage({ session: "localStorage" })` keeps it across reloads and tabs (default `"memory"`). A 1008 `signed out` for an anonymous session drops its token and connects again for a new one, instead of halting.
+- An invoke past its action's `rate_limit` (vantage-server 1.9.0) is an `error` frame with `kind: "rate_limited"`, `code: "rate_limited"` and `retry_after` (whole seconds); the types carry both.
+- A `hello` refused as `rate_limited` (too many new sessions or failed tokens from one address) is not final: the client closes, stays `closed` with the message, and connects again after `retry_after` seconds. `MockServer.limitHellos(times, retryAfter)` answers hellos so.
+- MockServer fixture `anonymousSessions`: tokenless or unknown `hello`s get a new session (`anon-1`, …); issued tokens resume.
+
+## 0.5.2 — 2026-10-25
+
+- `vantage-client generate` leaves `--out` untouched when the content would be the same, and logs `unchanged <out> (schema <hash>)`.
+
 ## 0.5.1 — 2026-10-25
 
 - MockServer traverses `via` over a numeric foreign key (it compared the number with the wire's string id and found nothing).

package/dist/client-connection.d.ts

@@ -35,6 +35,12 @@ export declare class ClientConnection extends ClientRuns {
     private settleReconnect;
     protected start(): Promise<void>;
     private connect;
+    /** Where `session: "localStorage"` keeps the anonymous session's token. */
+    private get sessionKey();
+    /** The anonymous session to resume: this client's, else the one localStorage kept. */
+    private savedSession;
+    /** Hold `token` as the anonymous session's (`null`: there is none), in localStorage too when asked. */
+    private keepSession;
     private hello;
     /**
      * Reopen every collection that is pinned or shown, and send the record
@@ -52,6 +58,12 @@ export declare class ClientConnection extends ClientRuns {
      * with `error`, writes queued offline included.
      */
     private halt;
+    /**
+     * The server refused a `hello` for now (`rate_limited`: too many new
+     * sessions or failed tokens from this address): not final. Close, stay
+     * `closed` with its message, and connect again once `seconds` have passed.
+     */
+    private retryAfter;
     private lost;
     private receive;
     private applyChange;

package/dist/client-connection.js

@@ -114,6 +114,39 @@ export class ClientConnection extends ClientRuns {
             close: (code, reason) => current() && this.lost(code, reason),
         });
     }
+    /** Where `session: "localStorage"` keeps the anonymous session's token. */
+    get sessionKey() {
+        return `vantage.session:${this.opts.url ?? "page"}`;
+    }
+    /** The anonymous session to resume: this client's, else the one localStorage kept. */
+    savedSession() {
+        const held = this.sessionToken.peek();
+        if (held !== null)
+            return held;
+        if (this.opts.session !== "localStorage")
+            return undefined;
+        try {
+            return globalThis.localStorage?.getItem(this.sessionKey) ?? undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Hold `token` as the anonymous session's (`null`: there is none), in localStorage too when asked. */
+    keepSession(token) {
+        this.sessionToken.set(token);
+        if (this.opts.session !== "localStorage")
+            return;
+        try {
+            if (token === null)
+                globalThis.localStorage?.removeItem(this.sessionKey);
+            else
+                globalThis.localStorage?.setItem(this.sessionKey, token);
+        }
+        catch {
+            // Storage refused (private mode, quota): the session lasts as long as the page.
+        }
+    }
     async hello() {
         let token;
         try {
@@ -122,11 +155,16 @@ export class ClientConnection extends ClientRuns {
         catch (e) {
             return this.halt("refused", e instanceof Error ? e.message : String(e));
         }
+        // No token of the app's own: resume the anonymous session, if there is one.
+        const saved = token === undefined ? this.savedSession() : undefined;
+        token ??= saved;
         const welcome = await this.request({ t: "hello", protocol: PROTOCOL, token, cursor: this.cursor, schema_hash: this.schema.hash, features: FEATURES }, true);
         if (welcome.t === "error" && welcome.kind === "offline")
             return; // lost mid-hello: the reconnect says hello again
         if (welcome.t === "error" && welcome.code === "protocol")
             return this.halt("protocol_mismatch", welcome.message);
+        if (welcome.t === "error" && welcome.code === "rate_limited")
+            return this.retryAfter(welcome.retry_after ?? 1, welcome.message);
         if (welcome.t !== "welcome")
             return this.halt("refused", welcome.t === "error" ? welcome.message : `unexpected reply \`${welcome.t}\``);
         if (welcome.protocol !== undefined && welcome.protocol !== PROTOCOL) {
@@ -145,6 +183,13 @@ export class ClientConnection extends ClientRuns {
             this.dropRestoredEditsOfOthers(id);
         this.principalId = id;
         this.principal.set(welcome.principal);
+        // The session sent may have ended: the server then made a new one.
+        if (welcome.session_token !== undefined)
+            this.keepSession(welcome.session_token);
+        else if (saved !== undefined)
+            this.keepSession(null);
+        else
+            this.sessionToken.set(null);
         // Anonymous (a sign-in page before sign-in): the server reads no table
         // for it, so nothing opens, `instant` tables included; they load at the
         // signed-in `welcome` that `reconnect()` brings.
@@ -241,13 +286,32 @@ export class ClientConnection extends ClientRuns {
         this.markReady();
         this.settleReconnect();
     }
+    /**
+     * The server refused a `hello` for now (`rate_limited`: too many new
+     * sessions or failed tokens from this address): not final. Close, stay
+     * `closed` with its message, and connect again once `seconds` have passed.
+     */
+    retryAfter(seconds, error) {
+        // The close of this socket is not a loss to back off from.
+        this.attempt++;
+        this.transport.close();
+        this.forgetSocket();
+        this.setStatus("closed", error);
+        if (this.closed)
+            return;
+        clearTimeout(this.backoff);
+        this.backoff = setTimeout(() => this.connect(), Math.max(1, seconds) * 1000);
+    }
     lost(code, reason) {
         this.forgetSocket();
         const halted = this.haltedWith !== undefined;
         // 1008 (policy violation): the reloaded API refuses this client's token,
         // or its session ended (`signed out`). Either way the token is spent;
-        // `reconnect()` with another one.
-        if (code === 1008 && !halted)
+        // `reconnect()` with another one. An anonymous session that ended needs
+        // no sign-in: the next `hello`, without it, gets a new one.
+        if (code === 1008 && !halted && this.sessionToken.peek() !== null)
+            this.keepSession(null);
+        else if (code === 1008 && !halted)
             return this.halt("refused", reason || "the server refused this client");
         if (halted)
             return;

package/dist/client-core.d.ts

@@ -13,6 +13,12 @@ type Pending = (frame: ServerFrame) => void;
 export declare class ClientCore {
     readonly connection: State<Connection>;
     readonly principal: State<string | null>;
+    /**
+     * The token of this client's anonymous session (`welcome.session_token`,
+     * under `session: { anonymous: true }`), `null` without one. The client
+     * resends it in `hello` when `token` gives none (see `session`).
+     */
+    readonly sessionToken: State<string | null>;
     readonly seq: State<number>;
     /**
      * Resolves with the connection once `instant` tables have loaded for the

package/dist/client-core.js

@@ -9,6 +9,12 @@ export class ClientCore {
     /** @internal */ store = new Store();
     connection = new State({ status: "connecting", halted: false });
     principal = new State(null);
+    /**
+     * The token of this client's anonymous session (`welcome.session_token`,
+     * under `session: { anonymous: true }`), `null` without one. The client
+     * resends it in `hello` when `token` gives none (see `session`).
+     */
+    sessionToken = new State(null);
     /**
      * @internal Who the last `welcome` said this client is, stably
      * (`welcome.principal_id`, else its name from an older server): what the

package/dist/client.d.ts

@@ -10,6 +10,13 @@ export interface VantageOptions {
     url?: string;
     /** Sent in `hello`: a token, or a function returning one, called on every connect. */
     token?: string | (() => string | undefined | Promise<string | undefined>);
+    /**
+     * Where the token of an anonymous session (`welcome.session_token`) is
+     * kept, to resend in `hello` whenever `token` gives none. Default:
+     * `"memory"`, so a reconnect resumes the session. `"localStorage"` also
+     * keeps it across reloads and tabs of the page.
+     */
+    session?: "memory" | "localStorage";
     /** Offline mirror of `persist: true` tables (see ./persist). */
     storage?: Storage;
     /** Swap the WebSocket (tests use the MockServer). */

package/dist/codegen/cli.js

@@ -1,5 +1,5 @@
 // `vantage-client generate --from <url-or-file> --out <file>`.
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { emit } from "./emit.js";
 import { loadSchema } from "./fetch.js";
@@ -20,8 +20,8 @@ export async function main(args, log = console.log, fail = console.error) {
             return 1;
         }
         const schema = await loadSchema(from);
-        await write(out, emit(schema, from));
-        log(`wrote ${out} (schema ${schema.hash})`);
+        const wrote = await write(out, emit(schema, from));
+        log(`${wrote ? "wrote" : "unchanged"} ${out} (schema ${schema.hash})`);
         return 0;
     }
     catch (e) {
@@ -41,11 +41,23 @@ function option(args, name) {
         throw new GenerateError(`${name} needs a value`);
     return value;
 }
-/** Write `text` to `path`, creating its directory when missing. */
+/**
+ * Write `text` to `path`, creating its directory when missing; false when the
+ * file already holds `text`. Leaving it alone keeps its mtime, so a watcher
+ * downstream (Vite) doesn't rebuild for the same output.
+ */
 async function write(path, text) {
+    try {
+        if ((await readFile(path, "utf8")) === text)
+            return false;
+    }
+    catch {
+        // Missing or unreadable: write it.
+    }
     try {
         await mkdir(dirname(path), { recursive: true });
         await writeFile(path, text);
+        return true;
     }
     catch (e) {
         const code = e.code ?? (e instanceof Error ? e.message : String(e));

package/dist/mock-store.d.ts

@@ -46,6 +46,13 @@ export interface Fixtures {
      * with "sign in first".
      */
     signIn?: boolean;
+    /**
+     * Like vantage-server under `session: { anonymous: true }`: a `hello`
+     * without a token, or with one this server never issued, gets a new
+     * session (`welcome.session_token`, `anon-1`, `anon-2`, …); a `hello`
+     * with an issued one resumes it.
+     */
+    anonymousSessions?: boolean;
 }
 export declare class MockStore {
     readonly schema: SchemaMeta;

package/dist/protocol.d.ts

@@ -45,7 +45,7 @@ export type ChangeEvent = {
     k: "invalidated";
     table: string;
 };
-export type ErrorKind = "invalid" | "not_found" | "forbidden" | "unavailable" | "conflict" | "failed" | "offline";
+export type ErrorKind = "invalid" | "not_found" | "forbidden" | "unavailable" | "conflict" | "failed" | "rate_limited" | "offline";
 /**
  * Which access rule refused a request, sent with `code: "forbidden"` on a
  * `rejected`, an `error` and a failed run's `error`: the table's catalog
@@ -61,7 +61,9 @@ export type ServerFrame =
 /**
  * `principal` is the display name; `principal_id` tells people apart (an
  * older server sends none); `anonymous` is a socket not signed in yet,
- * which reads no table.
+ * which reads no table. `session_token`, under `session: { anonymous:
+ * true }`: the token of the client's anonymous session, which a `hello`
+ * resumes it with.
  */
 {
     t: "welcome";
@@ -69,6 +71,7 @@ export type ServerFrame =
     principal: string;
     principal_id?: string;
     anonymous?: boolean;
+    session_token?: string;
     epoch: string;
     seq: number;
     schema_hash: string;
@@ -145,7 +148,9 @@ export type ServerFrame =
 }
 /**
  * `code` names errors a client acts on: `protocol`, `unknown_frame`,
- * `forbidden` (with the {@link AccessRefusal}) and a run's {@link RunCode}.
+ * `forbidden` (with the {@link AccessRefusal}), `rate_limited` (an invoke
+ * past its action's `rate_limit`, with `retry_after`, whole seconds) and a
+ * run's {@link RunCode}.
  */
  | ({
     t: "error";
@@ -153,6 +158,7 @@ export type ServerFrame =
     kind: ErrorKind;
     message: string;
     code?: string;
+    retry_after?: number;
 } & Partial<AccessRefusal>) | {
     t: "pong";
     id: number;

package/dist/testing.d.ts

@@ -22,8 +22,13 @@ export declare class MockServer extends MockStore {
     private held;
     private refusals;
     private writeRefusal?;
+    /** `hello`s still to answer `rate_limited` (`limitHellos`). */
+    private limitedHellos;
+    private helloRetryAfter;
     /** Sockets whose `hello` had no token, under fixture `signIn`. */
     private anonymous;
+    /** Anonymous sessions issued, by token (fixture `anonymousSessions`). */
+    private sessions;
     /** A server with one table, its schema made from the rows' keys. */
     static withTable(table: string, rows: Row[], fixtures?: Omit<Fixtures, "tables">): MockServer;
     transport(): MockTransport;
@@ -33,6 +38,12 @@ export declare class MockServer extends MockStore {
     reload(): void;
     /** Answer every `op` request with an error carrying `message`. */
     refuse(op: ClientFrame["t"], message: string): void;
+    /**
+     * Answer the next `times` `hello`s with `rate_limited` and `retry_after`
+     * (whole seconds), as vantage-server does once an address has made too
+     * many sessions.
+     */
+    limitHellos(times: number, retryAfter?: number): void;
     /** Stop refusing `op`. */
     allow(op: ClientFrame["t"]): void;
     /** Refuse every write with `message`, however the client sends it (`flash`, `batch` or `delete`). */

package/dist/testing.js

@@ -44,8 +44,13 @@ export class MockServer extends MockStore {
     held = new Map();
     refusals = new Map();
     writeRefusal;
+    /** `hello`s still to answer `rate_limited` (`limitHellos`). */
+    limitedHellos = 0;
+    helloRetryAfter = 1;
     /** Sockets whose `hello` had no token, under fixture `signIn`. */
     anonymous = new Set();
+    /** Anonymous sessions issued, by token (fixture `anonymousSessions`). */
+    sessions = new Set();
     /** A server with one table, its schema made from the rows' keys. */
     static withTable(table, rows, fixtures = {}) {
         return new MockServer(tableSchema(table, rows), { ...fixtures, tables: { [table]: rows } });
@@ -70,6 +75,15 @@ export class MockServer extends MockStore {
     refuse(op, message) {
         this.refusals.set(op, message);
     }
+    /**
+     * Answer the next `times` `hello`s with `rate_limited` and `retry_after`
+     * (whole seconds), as vantage-server does once an address has made too
+     * many sessions.
+     */
+    limitHellos(times, retryAfter = 1) {
+        this.limitedHellos = times;
+        this.helloRetryAfter = retryAfter;
+    }
     /** Stop refusing `op`. */
     allow(op) {
         this.refusals.delete(op);
@@ -128,8 +142,33 @@ export class MockServer extends MockStore {
                     // The close follows the error, as vantage-server's writer sends it.
                     return void setTimeout(() => client.drop(1002, "unsupported protocol"), 0);
                 }
+                if (this.limitedHellos > 0) {
+                    this.limitedHellos--;
+                    const wait = this.helloRetryAfter;
+                    const message = `too many new sessions from this address; try again in ${wait} s`;
+                    return reply({ t: "error", id, kind: "rate_limited", code: "rate_limited", retry_after: wait, message });
+                }
                 if (this.fixtures.refuseHello)
                     return reply({ t: "error", id, kind: "forbidden", message: this.fixtures.refuseHello });
+                if (this.fixtures.anonymousSessions) {
+                    const resumed = frame.token !== undefined && this.sessions.has(frame.token);
+                    const token = resumed ? frame.token : `anon-${this.sessions.size + 1}`;
+                    this.sessions.add(token);
+                    return reply({
+                        t: "welcome",
+                        id,
+                        principal: `anonymous-${token}`,
+                        principal_id: `session:${token}`,
+                        anonymous: false,
+                        session_token: token,
+                        epoch: `mock-${this.epoch}`,
+                        seq: this.seq,
+                        schema_hash: this.schema.hash,
+                        resync: true,
+                        protocol: this.fixtures.protocol ?? PROTOCOL,
+                        features: (this.fixtures.features ?? FEATURES).filter((f) => !frame.features || frame.features.includes(f)),
+                    });
+                }
                 {
                     const anonymous = this.fixtures.signIn === true && !frame.token;
                     if (anonymous)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantage-ui/client",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "A vantage-ui project as a typed, live object graph: lazy references and collections, optimistic edits, server-side actions, React bindings.",
   "keywords": ["vantage", "vantage-ui", "websocket", "realtime", "react", "codegen"],
   "homepage": "https://vantage-ui.com",

package/skills/vantage-client/SKILL.md

@@ -360,6 +360,17 @@ sign-out action, an expired session, or one deleted on the server closes
 the socket with 1008 `signed out`, which reads as `refused` with that
 error: clear the stored token and `reconnect()` to continue anonymously.
 
+When the project gives every visitor a session (`application.yaml`
+`session: { anonymous: true }`), there is no sign-in: the `welcome` carries
+`session_token`, which `db.sessionToken` holds, and the client resends it
+in `hello` whenever `token` gives none, so a lost socket comes back to the
+same session and whatever its actions granted (an unlocked plan, say).
+`createVantage({ schema, session: "localStorage" })` keeps it across
+reloads and tabs too; the default, `"memory"`, only for this client. A
+session that ended (idle on the server) closes with 1008 `signed out`
+without halting: the client drops the token and the next `hello` gets a
+new session, without the old one's grants.
+
 This sign-in form is the only one such a project needs. Its desktop app never
 signs in (vantage-ui's
 `vantage-application-settings/references/sessions-and-audit.md`).

package/skills/vantage-client/references/protocol.md

@@ -9,10 +9,11 @@ scripts and debugging. HTTP: `/v1/schema` (the schema `generate` reads),
 
 | Client → server | Server → client |
 |---|---|
-| `hello {protocol: 1, token?, cursor?, schema_hash?, features?}` | `welcome {protocol, principal, principal_id, anonymous, epoch, seq, schema_hash, resync, features}`: `principal` is the name to show, `principal_id` the stable id that tells people apart (`identity:<id>`, `anonymous:<socket>`, `token:<name>`), `anonymous` true for a socket not signed in (the client then opens no table, `instant` ones included, until a signed-in `welcome`); the features both sides have (`runs:1`, `session:1`). Under auth `session` a `hello` without a token is welcomed as `anonymous`, which may only `invoke` the actions the project lists in `session.signed_out` (sign in), `run_set`, `run_cancel` and `ping`; anything else gets `error {kind: "forbidden", message: "sign in first"}` |
+| `hello {protocol: 1, token?, cursor?, schema_hash?, features?}` | `welcome {protocol, principal, principal_id, anonymous, session_token?, epoch, seq, schema_hash, resync, features}`: `session_token`, under `session: { anonymous: true }`, is the token of the client's anonymous session (a `hello` with it resumes the session; one that ended gets a new session and token); `principal` is the name to show, `principal_id` the stable id that tells people apart (`identity:<id>`, `anonymous:<socket>`, `token:<name>`), `anonymous` true for a socket not signed in (the client then opens no table, `instant` ones included, until a signed-in `welcome`); the features both sides have (`runs:1`, `session:1`). Under auth `session` a `hello` without a token is welcomed as `anonymous`, which may only `invoke` the actions the project lists in `session.signed_out` (sign in), `run_set`, `run_cancel` and `ping`; anything else gets `error {kind: "forbidden", message: "sign in first"}` |
 | a frame with a `t` the server doesn't know | `error {code: "unknown_frame"}`; a client ignores frames and fields it doesn't know |
 | | `error {kind, message, code: "protocol"}`, then close 1002: another protocol version |
 | | `error {kind: "forbidden", message}`: the token is refused; the socket stays open for another `hello` |
+| | `error {kind: "rate_limited", code: "rate_limited", retry_after, message}`: too many new sessions or failed tokens from this address; say `hello` again after `retry_after` seconds (`@vantage-ui/client` closes, stays `closed` with the message, and reconnects then) |
 | | `resync {epoch, seq, schema_hash}`: the API was reloaded; reopen what you show, and re-attach the runs you follow (`invoke {run}`): an `invoke` answered around the reload may not stream its run |
 | | `reload`: the served frontend was rebuilt; reload the page (sent before `welcome` too) |
 | | close 1008: after a reload, the API refuses the token; or `signed out`: the session ended (signed out, expired, deleted, its person deactivated) |