@vantage-ui/client 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.5.0 — 2026-10-18
+
+- `db.reconnect()` works from any state: it closes an open socket and connects again with `token` called afresh, so a sign-in over an open anonymous connection switches to the new token. Breaking: before, it did nothing unless the connection was `refused`.
+- Sign-in over auth `session`: connect with no token (the `welcome` names `anonymous`), run the sign-in action, store the token from its result, `reconnect()`. The skill and the protocol reference say how.
+- A 1008 close with `signed out` (the session ended, expired or was revoked) reads as `refused` with that error.
+- `hello` sends `features: ["runs:1", "session:1"]`.
+- Edits queued offline under one principal are never sent under another: when a `welcome` names someone else (a sign-out and sign-in on one page), each settles with an error and the outbox is emptied. People are told apart by `welcome.principal_id` (stable and unique), not the display name, so two people with one name never share edits; an older server without the id falls back to the name. `reconnect()` also cancels a pending backoff reconnect, so it opens one socket, not two.
+- The saved outbox records which principal id made each edit. On the first `welcome` after a reload, saved edits from anyone else (or saved by an older client, unattributed) are dropped with a console warning and never sent. `Persisted.outbox` and `PersistChange.outbox` are now `OutboxEntry[]` (`{ item, principal }`); a custom `Storage` saves and returns them as given.
+- An `invalidated` change (live or replayed) also re-reads the table's records held outside any open collection, not only its collections, so a change the server can't name per row still reaches them.
+- A window's `items` stops at the last row once `lengthExact` is true. A 100-row window over a 22-row table now holds 22 items, not 22 and 78 `undefined` slots that never load (a list rendered `items` as an endless tail of placeholders).
+- A sign-in page works with `instant` tables: while the `welcome` is `anonymous`, the client sends no table read (no `open_table`, no `open_records`); collections and records wait, loading, instead of failing with "sign in first", and load at the signed-in `welcome`.
+- A write or run an access rule refused says what refused: the server's `code: "forbidden"` frames carry `table`, `rule` and `reason`, and the client puts them on `error.forbidden` (an `ActionError`, with `kind: "forbidden"`) and `run.error.forbidden`. The protocol types gain `AccessRefusal` and `RejectedFrame`; `AccessRefusal` is exported.
+- The skill and protocol reference cover an API profile's own `sign_in:` list for anonymous sockets.
+- MockServer fixtures take `principals` (token → the name `welcome` gives), `principalIds` (token → its `principal_id`) and `signIn` (a tokenless `hello` is anonymous, and its table reads and writes are refused).
+
 ## 0.4.4 — 2026-10-13
 
 - A README for the npm page, plus `keywords` and `homepage`.

package/dist/client-connection.d.ts

@@ -5,15 +5,32 @@ export declare class ClientConnection extends ClientRuns {
     private attempt;
     /** `reconnect()` calls waiting for the attempt to open or be refused. */
     private reconnecting;
+    /** The backoff reconnect a lost socket scheduled; `reconnect()` replaces it. */
+    private backoff?;
     /**
-     * Connect again after the server refused this client, calling `token`
-     * afresh: what a sign-in form does once the user has entered a new token.
-     * Collections and records the refusal failed get another try. Resolves
+     * Connect again with `token` called afresh, from any state: what a
+     * sign-in does once it has a token (a signed-in session's, after an
+     * anonymous `hello`), or a sign-out once it has dropped one. A live socket
+     * is closed first; requests it still owed settle as `offline`.
+     * Collections and records a refusal failed get another try. Resolves
      * like `ready` does, once the new connection has loaded the `instant`
-     * tables or has been refused again. Only `refused` reconnects; in any
-     * other state this resolves with the connection as it is.
+     * tables or has been refused.
      */
     reconnect(): Promise<Connection>;
+    /**
+     * Edits queued while `before` was signed in never go out as `now` (a
+     * sign-out and sign-in on one page): each settles with an error, and the
+     * offline mirror's outbox is emptied.
+     */
+    private dropEditsOf;
+    /**
+     * The first `welcome` after a reload: edits the saved outbox holds from
+     * anyone but `now` (or from an older client, which didn't say whose) are
+     * dropped, with a warning, and never sent.
+     */
+    private dropRestoredEditsOfOthers;
+    /** The socket is gone: what it owed settles `offline`, its subs mean nothing. */
+    private forgetSocket;
     /** Answer the `reconnect()` calls waiting on this attempt. */
     private settleReconnect;
     protected start(): Promise<void>;

package/dist/client-connection.js

@@ -10,18 +10,25 @@ export class ClientConnection extends ClientRuns {
     attempt = 0;
     /** `reconnect()` calls waiting for the attempt to open or be refused. */
     reconnecting = [];
+    /** The backoff reconnect a lost socket scheduled; `reconnect()` replaces it. */
+    backoff;
     /**
-     * Connect again after the server refused this client, calling `token`
-     * afresh: what a sign-in form does once the user has entered a new token.
-     * Collections and records the refusal failed get another try. Resolves
+     * Connect again with `token` called afresh, from any state: what a
+     * sign-in does once it has a token (a signed-in session's, after an
+     * anonymous `hello`), or a sign-out once it has dropped one. A live socket
+     * is closed first; requests it still owed settle as `offline`.
+     * Collections and records a refusal failed get another try. Resolves
      * like `ready` does, once the new connection has loaded the `instant`
-     * tables or has been refused again. Only `refused` reconnects; in any
-     * other state this resolves with the connection as it is.
+     * tables or has been refused.
      */
     reconnect() {
-        if (this.connection.peek().status !== "refused")
-            return Promise.resolve(this.connection.peek());
         const settled = new Promise((resolve) => this.reconnecting.push(resolve));
+        // Events from the socket being replaced are ignored from here on, and a
+        // backoff reconnect still pending would open a second socket.
+        this.attempt++;
+        clearTimeout(this.backoff);
+        this.transport.close();
+        this.forgetSocket();
         this.closed = false;
         this.retry = 0;
         for (const cell of this.collections.values())
@@ -29,10 +36,49 @@ export class ClientConnection extends ClientRuns {
         for (const cell of this.store.allCells())
             if (cell.presence.peek() === "error")
                 cell.presence.set("none");
+        clearInterval(this.sweeper);
         this.sweeper = setInterval(() => this.sweep(), 5_000);
         this.connect();
         return settled;
     }
+    /**
+     * Edits queued while `before` was signed in never go out as `now` (a
+     * sign-out and sign-in on one page): each settles with an error, and the
+     * offline mirror's outbox is emptied.
+     */
+    dropEditsOf(before, now) {
+        const message = `made as ${before}; not sent as ${now}`;
+        for (const { resolve } of this.flashQueue.splice(0))
+            resolve({ t: "error", id: 0, kind: "forbidden", message });
+        if (this.outbox.length) {
+            this.outbox = [];
+            void this.storage?.save({ outbox: [] });
+        }
+    }
+    /**
+     * The first `welcome` after a reload: edits the saved outbox holds from
+     * anyone but `now` (or from an older client, which didn't say whose) are
+     * dropped, with a warning, and never sent.
+     */
+    dropRestoredEditsOfOthers(now) {
+        this.outboxRestored = false;
+        const kept = this.outbox.filter((entry) => entry.principal === now);
+        const dropped = this.outbox.length - kept.length;
+        if (dropped === 0)
+            return;
+        console.warn(`vantage: dropped ${dropped} edit(s) saved offline by someone other than ${now}; they were not sent`);
+        this.outbox = kept;
+        void this.storage?.save({ outbox: kept });
+    }
+    /** The socket is gone: what it owed settles `offline`, its subs mean nothing. */
+    forgetSocket() {
+        for (const resolve of this.requests.values())
+            resolve({ t: "error", id: 0, kind: "offline", message: "connection lost" });
+        this.requests.clear();
+        for (const cell of this.collections.values())
+            cell.sub = null;
+        this.bySub.clear();
+    }
     /** Answer the `reconnect()` calls waiting on this attempt. */
     settleReconnect() {
         const connection = this.connection.peek();
@@ -51,6 +97,7 @@ export class ClientConnection extends ClientRuns {
                 });
                 this.cursor = saved.cursor ?? undefined;
                 this.outbox = saved.outbox ?? [];
+                this.outboxRestored = this.outbox.length > 0;
             }
         }
         this.connect();
@@ -88,11 +135,24 @@ export class ClientConnection extends ClientRuns {
         this.checkSchema(welcome.schema_hash);
         this.retry = 0;
         this.cursor = { epoch: welcome.epoch, seq: welcome.seq };
+        // People are told apart by their stable id, not their display name: two
+        // "John Smith"s never share edits.
+        const id = welcome.principal_id ?? welcome.principal;
+        const before = this.principalId;
+        if (before !== null && before !== id)
+            this.dropEditsOf(before, id);
+        if (this.outboxRestored)
+            this.dropRestoredEditsOfOthers(id);
+        this.principalId = id;
         this.principal.set(welcome.principal);
+        // 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.
+        this.anonymous = welcome.anonymous === true;
         this.features = new Set(welcome.features ?? []);
         this.setStatus("open");
         this.resumeRuns();
-        // Bootstrap: instant tables load whole and stay open.
+        // Bootstrap: instant tables load whole and stay open (once signed in).
         const instant = Object.entries(this.schema.tables)
             .filter(([, meta]) => meta.load === "instant")
             .map(([name]) => this.collectionCell({ table: name }));
@@ -182,14 +242,11 @@ export class ClientConnection extends ClientRuns {
         this.settleReconnect();
     }
     lost(code, reason) {
-        for (const resolve of this.requests.values())
-            resolve({ t: "error", id: 0, kind: "offline", message: "connection lost" });
-        this.requests.clear();
-        for (const cell of this.collections.values())
-            cell.sub = null;
-        this.bySub.clear();
+        this.forgetSocket();
         const halted = this.haltedWith !== undefined;
-        // 1008 (policy violation): the reloaded API refuses this client's token.
+        // 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)
             return this.halt("refused", reason || "the server refused this client");
         if (halted)
@@ -198,7 +255,7 @@ export class ClientConnection extends ClientRuns {
         if (this.closed)
             return;
         const delay = Math.min(10_000, 200 * 2 ** this.retry++);
-        setTimeout(() => this.connect(), delay);
+        this.backoff = setTimeout(() => this.connect(), delay);
     }
     receive(frame) {
         if ("id" in frame && frame.id && this.requests.has(frame.id)) {
@@ -251,10 +308,25 @@ export class ClientConnection extends ClientRuns {
                     c.drop(event.id);
         }
         else {
+            // `invalidated`: the table changed in ways no row names (live, or
+            // replayed after a reconnect). Re-read it: the open collections, and
+            // the records held outside them, which no collection reload reaches.
+            const inCollections = new Set();
             for (const c of this.collections.values()) {
-                if (c.spec.table === event.table && c.sub !== null)
+                if (c.spec.table !== event.table)
+                    continue;
+                for (const id of c.ids.peek())
+                    inCollections.add(id);
+                if (c.sub !== null)
                     void this.openCollection(c);
             }
+            const held = [];
+            for (const cell of this.store.allCells()) {
+                if (cell.table === event.table && cell.presence.peek() === "loaded" && !inCollections.has(cell.id))
+                    held.push(cell.id);
+            }
+            if (held.length)
+                void this.reloadRecords(event.table, held);
         }
     }
 }

package/dist/client-core.d.ts

@@ -3,7 +3,7 @@ import type { CollectionCell } from "./collection-cell.js";
 import type { Collection } from "./collection.js";
 import { type AnyModel } from "./model.js";
 import type { ClientFrame, Cursor, FlashItem, ServerFrame } from "./protocol.js";
-import type { Storage } from "./persist.js";
+import type { OutboxEntry, Storage } from "./persist.js";
 import { State } from "./signal.js";
 import { type RecordCell } from "./store.js";
 import type { TableHandle } from "./table.js";
@@ -39,7 +39,9 @@ export declare class ClientCore {
         item: FlashItem;
         resolve: (frame: ServerFrame) => void;
     }[];
-    protected outbox: FlashItem[];
+    protected outbox: OutboxEntry[];
+    /** The outbox came from storage (a reload): the first `welcome` checks whose it is. */
+    protected outboxRestored: boolean;
     protected undoStack: {
         table: string;
         id: string;
@@ -61,6 +63,14 @@ export declare class ClientCore {
     protected get db(): Vantage<any>;
     close(): void;
     protected get online(): boolean;
+    /**
+     * The last `welcome` was anonymous (auth `session`, not signed in yet):
+     * the server answers no table read, so none is sent. Collections and
+     * records wait, loading, until a signed-in `welcome`.
+     */
+    protected anonymous: boolean;
+    /** Whether reads go out now: open, and signed in (or no sign-in needed). */
+    protected get readsOpen(): boolean;
     protected setStatus(status: ConnectionStatus, error?: string): void;
     protected send(frame: ClientFrame): void;
     protected persistLater(cell: RecordCell): void;

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);
+    /**
+     * @internal Who the last `welcome` said this client is, stably
+     * (`welcome.principal_id`, else its name from an older server): what the
+     * outbox is stamped with, since display names may repeat.
+     */
+    principalId = null;
     seq = new State(0);
     /**
      * Resolves with the connection once `instant` tables have loaded for the
@@ -33,6 +39,8 @@ export class ClientCore {
     loadWaiters = new Map();
     flashQueue = [];
     outbox = [];
+    /** The outbox came from storage (a reload): the first `welcome` checks whose it is. */
+    outboxRestored = false;
     undoStack = [];
     retry = 0;
     /** Bumps on every `resync`: replies to frames sent before it are stale. */
@@ -68,6 +76,16 @@ export class ClientCore {
     get online() {
         return this.connection.peek().status === "open";
     }
+    /**
+     * The last `welcome` was anonymous (auth `session`, not signed in yet):
+     * the server answers no table read, so none is sent. Collections and
+     * records wait, loading, until a signed-in `welcome`.
+     */
+    anonymous = false;
+    /** Whether reads go out now: open, and signed in (or no sign-in needed). */
+    get readsOpen() {
+        return this.online && !this.anonymous;
+    }
     /** @internal The server's final refusal (`refused`, `protocol_mismatch`), once there is one. */
     get haltedWith() {
         const { status, error, halted } = this.connection.peek();

package/dist/client-loading.js

@@ -37,8 +37,8 @@ export class ClientLoading extends ClientCore {
         return Promise.all(waits).then(() => undefined);
     }
     async flushLoads() {
-        if (!this.online)
-            return; // retried on reconnect
+        if (!this.readsOpen)
+            return; // retried at the next (signed-in) welcome
         const queued = [...this.loadQueue];
         this.loadQueue.clear();
         await Promise.all(queued.map(async ([table, ids]) => {
@@ -79,7 +79,9 @@ export class ClientLoading extends ClientCore {
      * replaces them. When the reload fails, the next read of each tries again.
      */
     async reloadRecords(table, ids) {
-        const reply = await this.request({ t: "open_records", table, ids });
+        const reply = this.readsOpen
+            ? await this.request({ t: "open_records", table, ids })
+            : { t: "error", id: 0, kind: "offline", message: "not signed in" };
         if (reply.t !== "records") {
             for (const id of ids) {
                 const cell = this.store.peek(table, id);
@@ -115,8 +117,8 @@ export class ClientLoading extends ClientCore {
      * closed; so is the sub this open replaces.
      */
     async openCollection(cell) {
-        if (!this.online)
-            return;
+        if (!this.readsOpen)
+            return; // opened at the next (signed-in) welcome
         const { $window: _, ...spec } = cell.spec;
         const generation = this.generation;
         const reply = await this.request({ t: "open_table", ...spec });

package/dist/client-writes.js

@@ -1,7 +1,7 @@
 // Writing: optimistic edits batched per microtask, deletes, undo, and edits
 // queued while offline.
 import { ClientLoading } from "./client-loading.js";
-import { fail, failFrom, pick, sameValue, uuidv7 } from "./util.js";
+import { errorOf, fail, failFrom, pick, sameValue, uuidv7 } from "./util.js";
 export class ClientWrites extends ClientLoading {
     /** Choices for a form field whose options come from a script. */
     async options(action, field, form = {}) {
@@ -46,12 +46,12 @@ export class ClientWrites extends ClientLoading {
                 this.undoStack.shift();
             return { ok: true, value: this.model(table, target.id) };
         }
-        const fieldErrors = frame.t === "rejected" ? (frame.field_errors ?? {}) : {};
-        const message = frame.t === "rejected" || frame.t === "error" ? frame.message : "write failed";
+        const error = frame.t === "rejected" || frame.t === "error" ? errorOf(frame) : { kind: "invalid", message: "write failed", fieldErrors: {} };
+        const { fieldErrors, message } = error;
         cell.settle(keys, "failed", Object.keys(fieldErrors).length ? fieldErrors : { $: message });
         if (!before)
             cell.markRemoved();
-        return { ok: false, error: { kind: frame.t === "error" ? frame.kind : "invalid", message, fieldErrors } };
+        return { ok: false, error };
     }
     /** @internal */ async remove(table, id) {
         const cell = this.store.cell(table, id);
@@ -87,7 +87,7 @@ export class ClientWrites extends ClientLoading {
                 if (!this.storage)
                     return resolve({ t: "error", id: 0, kind: "offline", message: "not connected" });
                 // Offline with a mirror: keep it and send on reconnect.
-                this.outbox.push(item);
+                this.outbox.push({ item, principal: this.principalId });
                 void this.storage.save({ outbox: this.outbox });
                 this.flashQueue.push({ item, resolve });
                 return;

package/dist/collection.js

@@ -91,16 +91,21 @@ export class Collection {
         const loadState = cell.loadState.get();
         const total = cell.total.get();
         const error = cell.error.get();
-        const items = Array.from({ length: count }, (_, i) => {
+        const slots = Array.from({ length: count }, (_, i) => {
             const at = start + i - cell.start;
             const id = at >= 0 && at < ids.length ? ids[at] : undefined;
             return id ? this.db.model(this.spec.table, id) : undefined;
         });
-        const gap = items.indexOf(undefined);
+        const gap = slots.indexOf(undefined);
         const end = start + (gap === -1 ? count : gap); // rows arrived from `start` without a gap
         const settled = cell.windowSettled(start, count);
         // The last `rows`/`members` frame said `complete`: the server sent every row.
         const totalExact = loadState === "complete" && total !== null;
+        const length = total ?? end;
+        const lengthExact = total !== null ? totalExact : settled && error === null && (loadState === "complete" || end < start + count);
+        // Once the real count is known, the window stops at the last row: slots past it would
+        // stay `undefined` for good, and a list rendering them shows rows that never load.
+        const items = lengthExact ? slots.slice(0, Math.max(0, length - start)) : slots;
         return {
             start,
             count,
@@ -110,8 +115,8 @@ export class Collection {
             total,
             totalExact,
             settled,
-            length: total ?? end,
-            lengthExact: total !== null ? totalExact : settled && error === null && (loadState === "complete" || end < start + count),
+            length,
+            lengthExact,
             whenLoaded: () => cell.whenWindow(start, count).then(() => this.window(start, count)),
         };
     }

package/dist/index.d.ts

@@ -4,5 +4,5 @@ export { State, batch, autorun } from "./signal.js";
 export type { Transport } from "./transport.js";
 export { MemoryStorage, IndexedDBStorage, type Storage } from "./persist.js";
 export type { ActionError, ActionResult, CollectionWindow, Connection, ConnectionStatus, FieldMeta, Hydrated, LazyCollection, LazyReference, LoadState, Model, Presence, RelationKeys, RowStatus, SchemaMeta, SchemaTypes, Servo, TableMeta, WritableFields, } from "./types.js";
-export type { CollectionSpec, Where, Sort, WireRecord, Json, RunCode } from "./protocol.js";
+export type { AccessRefusal, CollectionSpec, Where, Sort, WireRecord, Json, RunCode } from "./protocol.js";
 export type { Run, RunError, RunFactory, RunMessageOf, RunStatus, RunTypes, StartOptions } from "./run/types.js";

package/dist/mock-store.d.ts

@@ -36,6 +36,16 @@ export interface Fixtures {
     eager?: boolean;
     /** The features `welcome` offers (default: all this client knows); `[]` is a server without runs. */
     features?: string[];
+    /** The principal `welcome` names for each `hello` token (default, and for any other token: `test`). */
+    principals?: Record<string, string>;
+    /** The stable `principal_id` `welcome` gives for each token (default: the principal's name). */
+    principalIds?: Record<string, string>;
+    /**
+     * Like vantage-server under auth `session`: a `hello` without a token is
+     * welcomed as `anonymous`, and its table reads and writes are refused
+     * with "sign in first".
+     */
+    signIn?: boolean;
 }
 export declare class MockStore {
     readonly schema: SchemaMeta;

package/dist/persist.d.ts

@@ -1,11 +1,17 @@
 import type { Cursor, FlashItem, WireRecord } from "./protocol.js";
+/** One edit waiting to go out, and who was signed in when it was made. */
+export interface OutboxEntry {
+    item: FlashItem;
+    /** The `welcome` principal at the time; `null` before any `welcome`. */
+    principal: string | null;
+}
 export interface Persisted {
     records: {
         table: string;
         record: WireRecord;
     }[];
     cursor: Cursor | null;
-    outbox: FlashItem[];
+    outbox: OutboxEntry[];
 }
 export interface PersistChange {
     /** `record: null` removes it. */
@@ -15,7 +21,7 @@ export interface PersistChange {
         record: WireRecord | null;
     }[];
     cursor?: Cursor;
-    outbox?: FlashItem[];
+    outbox?: OutboxEntry[];
 }
 export interface Storage {
     load(): Promise<Persisted>;

package/dist/persist.js

@@ -4,8 +4,23 @@
 // next start the app paints from the mirror (records marked `stale`)
 // before the socket connects. Edits made while offline wait in memory and
 // go out in order on reconnect, within the same page. They are also saved
-// to the outbox, but nothing sends a saved outbox after a reload: edits
-// still waiting when the page reloads are lost.
+// to the outbox, each with the principal that made it, but nothing sends a
+// saved outbox after a reload: edits still waiting when the page reloads
+// are lost. On the first `welcome` after a reload, saved edits another
+// principal made are dropped from it (with a warning), so a later sign-in
+// can never send them.
+/**
+ * A saved outbox entry, or an edit an older client saved bare: whose it was
+ * is unknown, so it reads as nobody's (`null`) and is dropped at the next
+ * `welcome`.
+ */
+function asEntry(saved) {
+    const entry = saved;
+    if (entry && typeof entry === "object" && "item" in entry && entry.item) {
+        return { item: entry.item, principal: entry.principal ?? null };
+    }
+    return { item: saved, principal: null };
+}
 /** Keeps everything in memory (tests; SSR). */
 export class MemoryStorage {
     records = new Map();
@@ -66,7 +81,7 @@ export class IndexedDBStorage {
             req(tx.objectStore("meta").get("cursor")),
             req(tx.objectStore("meta").get("outbox")),
         ]);
-        return { records, cursor: cursor ?? null, outbox: outbox ?? [] };
+        return { records, cursor: cursor ?? null, outbox: (outbox ?? []).map(asEntry) };
     }
     async save(change) {
         const db = await this.open();

package/dist/protocol.d.ts

@@ -1,6 +1,10 @@
 /** The wire protocol this client speaks; sent in `hello`. */
 export declare const PROTOCOL = 1;
-/** What this client understands beyond the protocol; sent in `hello`. */
+/**
+ * What this client understands beyond the protocol; sent in `hello`.
+ * `runs:1`: actions run as runs. `session:1`: an anonymous `hello` under
+ * auth `session`, and a 1008 `signed out` close when the session ends.
+ */
 export declare const FEATURES: string[];
 export type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
@@ -42,10 +46,29 @@ export type ChangeEvent = {
     table: string;
 };
 export type ErrorKind = "invalid" | "not_found" | "forbidden" | "unavailable" | "conflict" | "failed" | "offline";
-export type ServerFrame = {
+/**
+ * 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
+ * key, the rule (`<datasource>.invariants.<column>`, `.script` for a rule
+ * script's) and the rule's own words.
+ */
+export type AccessRefusal = {
+    table: string;
+    rule: string;
+    reason: string;
+};
+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.
+ */
+{
     t: "welcome";
     id: number;
     principal: string;
+    principal_id?: string;
+    anonymous?: boolean;
     epoch: string;
     seq: number;
     schema_hash: string;
@@ -95,12 +118,7 @@ export type ServerFrame = {
     rid: string;
     seq: number;
     record: WireRecord | null;
-} | {
-    t: "rejected";
-    id: number;
-    message: string;
-    field_errors?: Record<string, string>;
-} | {
+} | RejectedFrame | {
     t: "batch_result";
     id: number;
     results: ({
@@ -109,12 +127,7 @@ export type ServerFrame = {
         rid: string;
         seq: number;
         record: WireRecord | null;
-    } | {
-        t: "rejected";
-        id: number;
-        message: string;
-        field_errors?: Record<string, string>;
-    })[];
+    } | RejectedFrame)[];
 }
 /** The answer to `invoke`; the run's frames follow. */
  | {
@@ -130,14 +143,17 @@ export type ServerFrame = {
         label: string;
     }[];
 }
-/** `code` names errors a client acts on: `protocol`, `unknown_frame`, and a run's {@link RunCode}. */
- | {
+/**
+ * `code` names errors a client acts on: `protocol`, `unknown_frame`,
+ * `forbidden` (with the {@link AccessRefusal}) and a run's {@link RunCode}.
+ */
+ | ({
     t: "error";
     id: number;
     kind: ErrorKind;
     message: string;
     code?: string;
-} | {
+} & Partial<AccessRefusal>) | {
     t: "pong";
     id: number;
 }
@@ -167,11 +183,24 @@ export interface RunFrame {
         seq?: number;
     }[];
     result?: Json;
+    /** A body an access rule stopped fails with code `forbidden` and the {@link AccessRefusal}. */
     error?: {
         code: RunCode;
         message: string;
-    };
+    } & Partial<AccessRefusal>;
 }
+/** A write that didn't happen; `code: "forbidden"` when an access rule refused it. */
+export type RejectedFrame = {
+    t: "rejected";
+    id: number;
+    message: string;
+    field_errors?: Record<string, string>;
+    code?: "forbidden";
+} & Partial<AccessRefusal>;
+/** The access rule's refusal a frame carries, if any. */
+export declare function refusalOf(frame: {
+    code?: string;
+} & Partial<AccessRefusal>): AccessRefusal | undefined;
 export type FlashItem = {
     table: string;
     rid?: string;

package/dist/protocol.js

@@ -1,5 +1,15 @@
 // Wire frames (mirror of vantage-server `src/protocol.rs`).
 /** The wire protocol this client speaks; sent in `hello`. */
 export const PROTOCOL = 1;
-/** What this client understands beyond the protocol; sent in `hello`. */
-export const FEATURES = ["runs:1"];
+/**
+ * What this client understands beyond the protocol; sent in `hello`.
+ * `runs:1`: actions run as runs. `session:1`: an anonymous `hello` under
+ * auth `session`, and a 1008 `signed out` close when the session ends.
+ */
+export const FEATURES = ["runs:1", "session:1"];
+/** The access rule's refusal a frame carries, if any. */
+export function refusalOf(frame) {
+    if (frame.code !== "forbidden" || frame.table === undefined || frame.rule === undefined || frame.reason === undefined)
+        return undefined;
+    return { table: frame.table, rule: frame.rule, reason: frame.reason };
+}

package/dist/run/run.d.ts

@@ -1,4 +1,4 @@
-import type { Json, ServerFrame } from "../protocol.js";
+import { type Json, type ServerFrame } from "../protocol.js";
 import type { RunMeta } from "../schema-meta.js";
 import type { ActionResult } from "../types.js";
 import type { Run, RunError, RunFactory, RunStatus, RunTypes, StartOptions } from "./types.js";

package/dist/run/run.js

@@ -5,6 +5,7 @@
 // answer is sent again with the same id and args after the welcome (the
 // server attaches instead of running twice), and a running run attaches
 // again for a fresh snapshot.
+import { refusalOf } from "../protocol.js";
 import { State, batch } from "../signal.js";
 import { fail, uuidv7 } from "../util.js";
 import { classify, isFinal } from "./frames.js";
@@ -201,10 +202,10 @@ export class RunImpl {
             return;
         this.reattaching = false;
         const code = reply.code ?? "failed";
-        this.finishWith("failed", undefined, { code, message: reply.message });
+        this.finishWith("failed", undefined, runError(code, reply.message, refusalOf(reply)));
     }
     finish(frame) {
-        const error = frame.error ? { code: frame.error.code, message: frame.error.message } : null;
+        const error = frame.error ? runError(frame.error.code, frame.error.message, refusalOf(frame.error)) : null;
         this.finishWith(frame.status, frame.result, error);
     }
     finishWith(status, result, error) {
@@ -234,6 +235,9 @@ export class RunImpl {
         return this.lastSeq >= 0 && message.seq !== undefined && message.seq > this.lastSeq;
     }
 }
+function runError(code, message, forbidden) {
+    return forbidden ? { code, message, forbidden } : { code, message };
+}
 /** The factory for `action`: `start`, `attach`, `idle`. */
 export function runFactory(host, action, rid, meta) {
     const make = () => new RunImpl(host, action, rid, meta);

package/dist/run/types.d.ts

@@ -1,4 +1,4 @@
-import type { Json, RunCode } from "../protocol.js";
+import type { AccessRefusal, Json, RunCode } from "../protocol.js";
 import type { ActionResult } from "../types.js";
 /**
  * One action's run types, as `generate` emits them: what it takes (`args`),
@@ -16,10 +16,15 @@ export interface RunTypes {
  * server's `running`, `done`, `failed` or `cancelled`.
  */
 export type RunStatus = "idle" | "starting" | "running" | "done" | "failed" | "cancelled";
-/** Why a run was refused or failed. `offline`: the client wasn't connected. */
+/**
+ * Why a run was refused or failed. `offline`: the client wasn't connected.
+ * `forbidden` is set when an access rule refused it: the table, the rule
+ * and its reason.
+ */
 export interface RunError {
     readonly code: RunCode | "offline";
     readonly message: string;
+    readonly forbidden?: AccessRefusal;
 }
 /** The messages the framework sends for any action: a body's `notify(text)` and `log(text)`. */
 export interface FrameworkMessages {

package/dist/testing.d.ts

@@ -22,6 +22,8 @@ export declare class MockServer extends MockStore {
     private held;
     private refusals;
     private writeRefusal?;
+    /** Sockets whose `hello` had no token, under fixture `signIn`. */
+    private anonymous;
     /** 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;

package/dist/testing.js

@@ -32,6 +32,8 @@ import { FEATURES, PROTOCOL } from "./protocol.js";
 export { MockTransport };
 /** The frames a write travels in: one edit, several batched in a tick, a delete. */
 const WRITES = new Set(["flash", "batch", "delete"]);
+/** What an anonymous socket may not send (fixture `signIn`). */
+const READS_AND_WRITES = new Set(["open_table", "open_records", "viewport", "options", ...WRITES]);
 export class MockServer extends MockStore {
     /** Every `hello` received, in order. */
     hellos = [];
@@ -42,6 +44,8 @@ export class MockServer extends MockStore {
     held = new Map();
     refusals = new Map();
     writeRefusal;
+    /** Sockets whose `hello` had no token, under fixture `signIn`. */
+    anonymous = 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 } });
@@ -102,6 +106,11 @@ export class MockServer extends MockStore {
         const refusal = this.refusals.get(frame.t) ?? (WRITES.has(frame.t) ? this.writeRefusal : undefined);
         if (refusal !== undefined)
             return client.deliver({ t: "error", id: frame.id ?? 0, kind: "invalid", message: refusal });
+        // Like vantage-server under auth `session`: an anonymous socket reads
+        // and writes no table.
+        if (this.anonymous.has(client) && READS_AND_WRITES.has(frame.t)) {
+            return client.deliver({ t: "error", id: frame.id ?? 0, kind: "forbidden", message: "sign in first" });
+        }
         const held = this.held.get(frame.t);
         if (held)
             return void held.push([client, frame]);
@@ -121,10 +130,35 @@ export class MockServer extends MockStore {
                 }
                 if (this.fixtures.refuseHello)
                     return reply({ t: "error", id, kind: "forbidden", message: this.fixtures.refuseHello });
+                {
+                    const anonymous = this.fixtures.signIn === true && !frame.token;
+                    if (anonymous)
+                        this.anonymous.add(client);
+                    else
+                        this.anonymous.delete(client);
+                    if (anonymous) {
+                        return reply({
+                            t: "welcome",
+                            id,
+                            principal: "anonymous",
+                            principal_id: "anonymous:mock",
+                            anonymous: true,
+                            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)),
+                        });
+                    }
+                }
                 return reply({
                     t: "welcome",
                     id,
-                    principal: "test",
+                    principal: (frame.token !== undefined && this.fixtures.principals?.[frame.token]) || "test",
+                    principal_id: (frame.token !== undefined && this.fixtures.principalIds?.[frame.token]) ||
+                        (frame.token !== undefined && this.fixtures.principals?.[frame.token]) ||
+                        "test",
                     epoch: `mock-${this.epoch}`,
                     seq: this.seq,
                     schema_hash: this.schema.hash,

package/dist/types.d.ts

@@ -1,11 +1,16 @@
-import type { ErrorKind, Sort, Where } from "./protocol.js";
+import type { AccessRefusal, ErrorKind, Sort, Where } from "./protocol.js";
 import type { Presence, RowStatus } from "./store.js";
 export type { RowStatus, Presence };
 export type { ActionMeta, FieldMeta, RunMeta, SchemaMeta, SchemaTypes, TableMeta } from "./schema-meta.js";
+/**
+ * Why a write or run failed. `forbidden` is set when an access rule refused
+ * it (`kind` is then `forbidden`): the table, the rule and its reason.
+ */
 export type ActionError = {
     kind: ErrorKind;
     message: string;
     fieldErrors: Record<string, string>;
+    forbidden?: AccessRefusal;
 };
 export type ActionResult<R> = {
     ok: true;

package/dist/util.d.ts

@@ -1,4 +1,4 @@
-import type { ErrorKind, ServerFrame } from "./protocol.js";
+import { type ErrorKind, type ServerFrame } from "./protocol.js";
 import type { ActionError, TableMeta } from "./types.js";
 /** Relation names → their columns (`bakery` → `bakery_id`). */
 export declare function toColumns(meta: TableMeta, fields: Record<string, unknown>): Record<string, unknown>;
@@ -10,6 +10,10 @@ export declare function failFrom(frame: ServerFrame): {
     ok: false;
     error: ActionError;
 };
+/** A `rejected` or `error` as an {@link ActionError}, with the access rule's refusal when one caused it. */
+export declare function errorOf(frame: ServerFrame & {
+    t: "error" | "rejected";
+}): ActionError;
 export declare function pick(record: Record<string, unknown>, keys: string[]): Record<string, unknown>;
 export declare function sameValue(a: unknown, b: unknown): boolean;
 /** A type name from a table name: `order_line` → `OrderLine`. Separators are dropped. */

package/dist/util.js

@@ -1,4 +1,5 @@
 // Small helpers shared by the client's parts.
+import { refusalOf } from "./protocol.js";
 /** Relation names → their columns (`bakery` → `bakery_id`). */
 export function toColumns(meta, fields) {
     const out = {};
@@ -10,12 +11,17 @@ export function fail(kind, message) {
     return { ok: false, error: { kind, message, fieldErrors: {} } };
 }
 export function failFrom(frame) {
-    if (frame.t === "error")
-        return fail(frame.kind, frame.message);
-    if (frame.t === "rejected")
-        return { ok: false, error: { kind: "invalid", message: frame.message, fieldErrors: frame.field_errors ?? {} } };
+    if (frame.t === "error" || frame.t === "rejected")
+        return { ok: false, error: errorOf(frame) };
     return fail("failed", `unexpected reply \`${frame.t}\``);
 }
+/** A `rejected` or `error` as an {@link ActionError}, with the access rule's refusal when one caused it. */
+export function errorOf(frame) {
+    const forbidden = refusalOf(frame);
+    const kind = forbidden ? "forbidden" : frame.t === "error" ? frame.kind : "invalid";
+    const fieldErrors = frame.t === "rejected" ? (frame.field_errors ?? {}) : {};
+    return forbidden ? { kind, message: frame.message, fieldErrors, forbidden } : { kind, message: frame.message, fieldErrors };
+}
 export function pick(record, keys) {
     return Object.fromEntries(keys.filter((k) => k in record).map((k) => [k, record[k]]));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantage-ui/client",
-  "version": "0.4.4",
+  "version": "0.5.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

@@ -2,7 +2,7 @@
 name: vantage-client
 description: Use when writing a web frontend (React or plain TypeScript) against a Vantage API served by vantage-server — connecting with @vantage-ui/client, generating typed models, reading collections, windows and records, writing, running actions as runs with shared state and messages, handling refusals and resync, and testing against MockServer.
 metadata:
-  version: "2.2.3"
+  version: "2.3.0"
 ---
 
 # @vantage-ui/client
@@ -78,8 +78,8 @@ const db = createVantage<Schema>({ schema, token: () => sessionStorage.getItem("
 ```
 
 `token` is sent in `hello` on every connect; a function is called each
-time, so a new sign-in is picked up on the next connect. After the server
-refuses a token, `db.reconnect()` connects again (see Connection states).
+time, so a new sign-in is picked up on the next connect, and
+`db.reconnect()` connects again at once (see Connection states).
 Outside a browser (scripts, tests, Node), pass the URL:
 
 ```ts
@@ -131,7 +131,8 @@ const initialSort = issues.defaultSort; // { column, direction }, or null
 
 For long lists, read one window at a time. Rows outside the window are not
 sent. `window()` returns what has arrived so far (a row is `undefined` until
-it loads); `whenLoaded()` waits for the window's rows. In React, `useWindow`
+it loads, and once `lengthExact` is true `items` stops at the last row, so a
+100-row window over 22 rows holds 22); `whenLoaded()` waits for the window's rows. In React, `useWindow`
 re-renders as they arrive instead.
 
 ```ts
@@ -310,7 +311,7 @@ true in the two final states:
 | `connecting` | Before the first `welcome` |
 | `open` | Connected; reads and writes go out |
 | `closed` | Lost; the client reconnects with backoff and resumes |
-| `refused` | The server refused the token (at `hello`, or after an API reload). Final |
+| `refused` | The server refused the token (at `hello`, after an API reload, or `signed out` when the session ended). Final |
 | `protocol_mismatch` | The server speaks another protocol version. Final |
 
 After `refused` or `protocol_mismatch` the client stops reconnecting, and
@@ -331,11 +332,12 @@ const stop = autorun(() => {
 In React, `useConnection()` gives the same; `references/react.md` shows a
 provider fallback built on it.
 
-`refused` stays final until you call `db.reconnect()`. It connects again,
-calls `token` afresh, and gives the collections and records the refusal
-failed another try. It resolves like `db.ready`: with the connection once
-it is open, or refused again. A sign-in form stores the new token where the
-`token` function reads it and calls `reconnect()`, with no page reload:
+`refused` stays final until you call `db.reconnect()`. It works from any
+state: it closes an open socket, connects again, calls `token` afresh, and
+gives the collections and records a refusal failed another try. It
+resolves like `db.ready`: with the connection once it is open, or refused.
+A sign-in form stores the new token where the `token` function reads it
+and calls `reconnect()`, with no page reload:
 
 ```ts
 // test: connection#reconnect
@@ -345,6 +347,23 @@ const connection = await db.reconnect();
 if (connection.halted) showBanner(`Sign-in refused: ${connection.error}`);
 ```
 
+When the API signs people in itself (auth `session`), the page connects
+with no token first: the `welcome` names `anonymous`, and the only thing it
+may do is run actions. Which ones is the API's choice: the profile's own
+`auth: { <profile>: { session: { sign_in: [..] } } }` list, else
+`application.yaml` `session.signed_out`; anything else answers `forbidden`
+"sign in first". Signing in is one: run the project's sign-in action
+(`db.run.sign_in.start({ email, password })`), wait for `run.done`, store
+the token its result carries where `token` reads it, and call
+`db.reconnect()`. From then on every socket of that session shares it. A
+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.
+
+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`).
+
 ## Refusals
 
 The server refuses what the API doesn't allow (an unknown column, a filter
@@ -356,6 +375,15 @@ throws and is never retried on its own:
 
 Change the query (a new `where` is a new collection) to try again.
 
+A refusal by the project's access rules (a datasource `invariants:` rule or
+its `script:` hook, say "editors change only their environments") comes
+with what refused: the write's `error.kind` is `forbidden` and
+`error.forbidden` is `{ table, rule, reason }`, and so is a failed run's
+`run.error.forbidden` (its `code` is `forbidden`). `reason` is the rule's
+own words, fit to show; `rule` names it (`flags.invariants.environment.script`).
+Other refusals have no `forbidden`. The API runs as its own app (the
+`api/<key>.yaml` key), which no client can change.
+
 ## Resync
 
 When the API's YAML changes, vantage-server reloads and sends `resync`. The

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

@@ -9,13 +9,14 @@ 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, epoch, seq, schema_hash, resync, features}`: the features both sides have (`runs:1`) |
+| `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"}` |
 | 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` |
 | | `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 |
+| | close 1008: after a reload, the API refuses the token; or `signed out`: the session ended (signed out, expired, deleted, its person deactivated) |
+| | `resync` also follows a change to the session's own fields (impersonation): the same `hello` holds, collections and interest are gone |
 | | close 1012 `reconnect`: the server is shutting down |
 
 Nothing but `hello` is accepted before a `welcome`.
@@ -38,7 +39,7 @@ has-many). A refused request gets `error {id, kind, message}`.
 
 | Client → server | Server → client |
 |---|---|
-| `flash {table, rid?, patch}` · `batch {items}` · `delete {table, rid}` | `flashed {rid, seq, record}` · `rejected {message, field_errors}` · `batch_result {results}` |
+| `flash {table, rid?, patch}` · `batch {items}` · `delete {table, rid}` | `flashed {rid, seq, record}` · `rejected {message, field_errors, code?, table?, rule?, reason?}` · `batch_result {results}` |
 | `invoke {run, action?, rid?, args}` (no `action`: attach) | `result {run, status: started \| attached \| done}`, then `run {run, seq, status?, state?, messages?, result?, error?}`, the first a snapshot |
 | `run_set {run, name, value}` · `run_cancel {run}` | `ack` · `error {kind, message, code}` |
 | `options {action, field, form?}` | `options_result {items}` |
@@ -51,6 +52,15 @@ missed. A refused `invoke` carries `code`:
 `conflict` (the id was used with other args), `expired`, `forbidden` (no
 such run for you, or an action the API can't run), `invalid` or `limit`.
 
+A request an access rule refused carries `code: "forbidden"` and the
+refusal beside `message`: `table` (the table's catalog key), `rule`
+(`<datasource>.invariants.<column>`, `.script` for a rule script's,
+`session.table`, `session.identity`) and `reason`, the rule's own words.
+This holds for `rejected`, for `error` (an `open_table`, `open_records`,
+`options` or `invoke` the rule refused) and for a run's `error` when a rule
+stopped its body. Signed out, an `invoke` runs only the actions in the
+API profile's `sign_in:` list, or without one `session.signed_out`.
+
 ## A raw script
 
 ```ts

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

@@ -70,7 +70,10 @@ For virtualised lists, `useWindow(collection, start, count)` gives the rows
 `start..start+count`. Moving `start` moves the server's window; rows stay
 on screen until the new ones arrive. Size the virtualiser from
 `page.length`, show it as a count only when `page.lengthExact`, and use
-`page.settled` to tell "still loading" from "no rows here".
+`page.settled` to tell "still loading" from "no rows here". Once the count is
+exact, `page.items` ends at the last row, so rendering `items` never shows
+placeholders for rows that don't exist. A list that grows its window as the
+user scrolls asks for more only while `!page.lengthExact`.
 
 ```tsx
 // test: react#window