@vantage-ui/client 0.0.0-stage → 0.4.3

package/skills/vantage-client/SKILL.md

@@ -0,0 +1,390 @@
+---
+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"
+---
+
+# @vantage-ui/client
+
+`@vantage-ui/client` turns a Vantage API (`api/<name>.yaml`, served by
+vantage-server) into a typed, live object graph. Reads are lazy and stay
+current: the server pushes changes, and a component re-renders on exactly
+the fields it read. Writes are optimistic and roll back when the server
+refuses them.
+
+References in this skill:
+- `references/react.md`: the provider, `observer`, and the hooks;
+- `references/testing.md`: `createTestVantage` and `MockServer`;
+- `references/protocol.md`: the wire frames, for scripts and debugging.
+
+## Generate the types
+
+The models come from the API's schema at `/v1/schema`. In a Vantage
+project, the web dev container installs, generates and builds the frontend
+for you; no Node is needed on the machine (the `vantage-web` skill covers
+it). Outside one, with Node 22 or later, generate straight from the
+running server:
+
+```sh
+npx vantage-client generate --from http://127.0.0.1:<port>/v1/schema --out src/vantage.gen.ts
+```
+
+As an alternative, `--from` takes a saved copy of the schema, for when the
+generator can't reach the server:
+
+```sh
+curl -fsS http://127.0.0.1:<port>/v1/schema -o schema.json
+npx vantage-client generate --from schema.json --out src/vantage.gen.ts
+```
+
+The output follows the schema's order, so regenerating an unchanged schema
+gives an identical file. Never edit `vantage.gen.ts`; regenerate it after
+the API's YAML changes.
+
+Per entity, the file has `XFields` (the record as data), `XInput` (what
+`create()` takes) and the model `X`. A model has typed columns, a
+`LazyReference` per reference, a `LazyCollection` per has-many, a method
+per row action, and `$run` with a run factory per row action. Per action
+there is `<Action>Run` (`IssuesCloseIssueRun` for a row action): its `args`,
+`state`, `inputs` and `messages`. Model names come from entity names: entity
+`issues` gives the model `Issues`.
+
+Every column in `XFields` is `T | null`, `mandatory` ones included. Only
+`XInput` makes `mandatory` columns required. `mandatory` makes a form ask
+for the value, and the generated `create()` type require it, but Vantage
+doesn't enforce it on the stored data (only a database constraint such as
+`NOT NULL` does). A row written some other way, or before the column
+became mandatory, can hold null. A field also reads `null` until its record has loaded, and after the
+record is removed. Handle `null` when you read a field, even a mandatory
+one.
+
+A model's `id` is a `string` whatever type the id column has: ids travel as
+text. A SurrealDB id reads `"table:id"` (`"issues:12"`); an integer key
+arrives as its digits (`"6"`). Pass ids back as you received them.
+
+## Connect
+
+In the browser, the client connects to `/v1/ws` on the page's own origin.
+Serve the frontend from vantage-server (the API's `frontend:` folder) and
+no URL is needed:
+
+```ts
+// test: connect#same-origin
+import { createVantage } from "@vantage-ui/client";
+import { schema, type Schema } from "./vantage.gen";
+
+const db = createVantage<Schema>({ schema, token: () => sessionStorage.getItem("vantage.token") ?? undefined });
+```
+
+`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).
+Outside a browser (scripts, tests, Node), pass the URL:
+
+```ts
+// test: connect#script-url
+// continues from the previous block: createVantage, schema, Schema
+const db = createVantage<Schema>({ schema, url: "ws://127.0.0.1:8090/v1/ws", token: process.env.VANTAGE_TOKEN });
+```
+
+`db.ready` resolves with the connection (`{ status, halted, error? }`) once
+the API's `instant` entities have loaded, or once the connection is refused
+for good (see below).
+
+## Read
+
+Every entity is a property of `db`. Collections are lazy: reading one opens
+it on the server, which then keeps its membership and records current. The
+server filters, sorts and pages them; a collection has `map`, `forEach` and
+iteration, but no `filter` or `find`. The same description gives the same
+collection object, so a render can build one inline, with no `useMemo`.
+
+```ts
+// test: read#collections
+// continues from Connect: db
+const open = db.issues.where({ status: "open" }).sort("created_at", "desc");
+await open.load();
+const lines = open.map((issue) => `${issue.id}: ${issue.title}`);
+const refusal = open.error; // the server's message if it refused the query, else null
+```
+
+`where` takes `{ column: value }` (equality), `{ column: [a, b] }` (in), or
+`{ column: { gt: 3 } }` with `eq ne gt gte lt lte in not_in like`. A
+reference may be named by its relation (`{ project: "JIR" }`). The API
+decides which columns may be filtered and sorted (`params.filter`,
+`sortable`); anything else is refused, and the refusal lands on `error`.
+
+The generated `schema` carries those whitelists, and each enum column's
+values in the API's order, so menus and chips needn't hard-code them:
+
+```ts
+// test: read#whitelists
+import { schema } from "./vantage.gen";
+
+const issues = schema.tables.issues;
+const sortChoices = issues.sortable ?? Object.keys(issues.columns); // null: any column sorts
+const filterable = issues.filter; // columns `where` may name
+const statusChips = issues.columns.status.enum; // ["open", "in_progress", "done"]
+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`
+re-renders as they arrive instead.
+
+```ts
+// test: read#window
+// continues from Connect: db
+const page = await db.issues.sort("created_at", "desc").window(0, 50).whenLoaded();
+const rows = page.items; // (Issues | undefined)[]
+const fourth = page.at(3)?.title;
+const scrollHeight = page.length * 32; // the server's total, else the rows so far
+const footer = page.lengthExact ? `${page.length} issues` : `${page.length}+ issues`;
+```
+
+A window's `length` is the server's `total` when it sends one, and
+otherwise the rows that have arrived without a gap. `lengthExact` says when
+it is the real count: `totalExact` when there is a total (the server counts
+exactly once it has sent the whole collection), else once a settled window
+came back short. Size a scrollbar from `length` either way, but only show
+it as a count when `lengthExact` is true. `settled` is true once the
+window's rows have arrived or it failed, which is what `whenLoaded()` waits
+for. A collection has `total` and `totalExact` the same way.
+
+A window refused by the server, or waiting when the connection halts,
+settles with `page.error` set.
+
+One record, by id. `ref()` gives a `LazyReference`: `.value` is the model
+once loaded (reading it starts the load, and is `undefined` until then);
+`await` or `.load()` waits. A model's references are lazy the same way:
+
+```ts
+// test: read#records
+// continues from Connect: db
+const issue = await db.issues.ref("JIR-12").load(); // undefined when missing or refused
+if (issue) {
+  const project = await issue.project; // awaiting a reference loads its record
+  const projectName = project?.name;
+}
+const ghost = db.issues.ref("JIR-404");
+await ghost.load();
+const status = ghost.status; // "missing"
+```
+
+Has-many references are collections through the parent (`via`), and narrow
+like any other:
+
+```ts
+// test: read#via
+// continues from Connect: db
+const project = await db.projects.ref("JIR").load();
+if (project) {
+  const openInProject = await project.issues.where({ status: "open" }).load();
+}
+```
+
+## Write
+
+Writes are optimistic: the model shows the new value at once, and rolls
+back (with `$errors` per field) if the server refuses.
+
+```ts
+// test: write#patch
+// continues from Read: issue, loaded
+const result = await issue.patch({ status: "done" });
+if (!result.ok) console.warn(result.error.message, issue.$errors);
+```
+
+A draft collects several changes and sends them together. Everything a
+draft adds is `$`-prefixed (`$flash()`, `$isDirty`, `$status`, `$errors`,
+`$dirty(field)`, `$revert(field?)`), so any column stays editable on it:
+
+```ts
+// test: write#draft
+// continues from Read: issue, loaded
+const draft = issue.edit();
+draft.title = "Login fails on Safari";
+const saved = await draft.$flash();
+```
+
+```ts
+// test: write#create
+// continues from Connect: db
+const created = await db.issues.create({ title: "Export to CSV", project: "JIR", status: "open" });
+```
+
+Writes made in one tick travel as one `batch` (not a transaction). The API's
+`params.columns` limits which fields a write may set.
+
+## Actions
+
+Row actions are methods on the model; `$actions` lists the ones the server
+allows on that row right now (their `when:` holds). A method runs the action
+and waits for its end; the row's new values arrive like any other change.
+
+```ts
+// test: actions#row
+// continues from Read: issue, loaded
+if (issue.$actions.includes("close_issue")) {
+  const closed = await issue.close_issue({ resolution: "fixed" });
+  if (!closed.ok) console.error(closed.error.message);
+}
+```
+
+In React, `useAction` wraps one for a button; see `references/react.md`.
+Forms and confirms are your UI: ask the user, then call the action with the
+values. Actions that start OS processes or need the desktop (`command`,
+`terminal`, `stream`, `wizard`, `builtin:`) run only in the Vantage app and
+are left out of the schema.
+
+## Runs
+
+Every action runs as a *run*: it shares variables (`state`) and sends
+messages while it goes, then ends with a `result`. Project actions are on
+`db.run.<action>`, row actions on `model.$run.<action>`. `start` sends the
+action with a new run id (a UUIDv7); invoking an id again never runs the
+action twice, so a retry or a reload attaches instead.
+
+```ts
+// test: runs#start
+// continues from Connect: db
+const run = db.run.triage.start({ project: "JIR" });
+const stop = run.on("flagged", (m) => console.warn(`${m.issue} has no assignee`));
+```
+
+A run's getters are reactive (`status`, `state.<name>`, `result`, `error`,
+`messages`), so `autorun` and `observer` follow them. `status` goes
+`starting` → `running` → `done`, `failed` or `cancelled`. An `input`
+variable is the one thing you write; the write shows at once and rolls back
+if the server refuses it:
+
+```ts
+// test: runs#input
+// continues from runs#start: run
+await run.set("confirmed", true);
+const outcome = await run.done;
+if (outcome.ok) console.log(outcome.value, `${run.state.progress} of ${run.state.total}`);
+```
+
+`run.cancel()` stops it at its next wait. `attach(id)` follows a run started
+earlier, by this page before a reload or by another tab; a run that isn't
+yours, or whose result has expired, ends `failed` with `error.code`
+`forbidden` or `expired`:
+
+```ts
+// test: runs#attach
+// continues from Connect: db; runId is a run started earlier
+const again = db.run.triage.attach(runId);
+```
+
+`on` also takes the framework's messages: `"vantage.notify"` is the body's
+`notify(text)` and `"vantage.log"` its `log(text)`, both `{ text }`. A run
+you started delivers to `on` what it sent before you followed it; after an
+`attach`, earlier messages are history in `messages`, not events. Messages
+sent while the connection was down, or across a `resync`, still reach `on`
+once the run catches up, if they are among its last 100.
+`run.messages` is a list of `{ name, payload }`, oldest first: the run's
+last 100 messages, framework ones included. After a reload, build anything
+the page lists from messages out of `run.messages`, not from `on`
+(`references/react.md`, Runs, has a tested example).
+
+A run's `result` is what the action's body returns, sent as it is: the
+API's column whitelists don't filter it. The client sends an unanswered
+`start` again with the same id after a reconnect or `resync`, and attaches
+to its running runs for a fresh snapshot, so a dropped connection never
+runs an action twice. `run.forget()` goes back to `idle`. Toolbar actions
+have no `$run` yet: `db.<table>.actions.<name>(input)` runs one and waits
+for its end. In React, `useRun`, `useShared` and `useRunMessage`
+(`references/react.md`) keep a run across page reloads and re-render only
+what reads a variable.
+
+## Connection states
+
+`db.connection` is a signal of `{ status, halted, error? }`; `halted` is
+true in the two final states:
+
+| `status` | Meaning |
+|---|---|
+| `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 |
+| `protocol_mismatch` | The server speaks another protocol version. Final |
+
+After `refused` or `protocol_mismatch` the client stops reconnecting, and
+everything waiting settles: `db.ready` resolves, and pending loads return
+with `error` set to the server's message. Show it:
+
+```ts
+// test: connection#status
+// continues from Connect: db; showBanner is your UI's
+import { autorun } from "@vantage-ui/client";
+
+const stop = autorun(() => {
+  const { status, halted, error } = db.connection.get();
+  if (halted) showBanner(`${status}: ${error}`);
+});
+```
+
+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:
+
+```ts
+// test: connection#reconnect
+// continues from Connect: db, whose token function reads sessionStorage; newToken is what the user typed, showBanner is your UI's
+sessionStorage.setItem("vantage.token", newToken);
+const connection = await db.reconnect();
+if (connection.halted) showBanner(`Sign-in refused: ${connection.error}`);
+```
+
+## Refusals
+
+The server refuses what the API doesn't allow (an unknown column, a filter
+outside `params.filter`, a record outside your scope). A refusal never
+throws and is never retried on its own:
+- a collection or window has `error` (the message) and `loadState: "error"`;
+- a record has `status: "error"` and `error` on its reference;
+- a write or action returns `{ ok: false, error }`.
+
+Change the query (a new `where` is a new collection) to try again.
+
+## Resync
+
+When the API's YAML changes, vantage-server reloads and sends `resync`. The
+client reopens every collection and window on screen and reloads the
+records it holds. Rows stay visible until the fresh ones arrive, so nothing
+flashes empty. Refused collections and records get one more try under the
+reloaded API. There is nothing to handle in app code.
+
+## Reload
+
+When vantage-server serves a built frontend (`--static <dist>`) and a new
+build rewrites `<dist>/index.html` or `<dist>/assets/`, it sends `reload` to every open page. By
+default the client calls `location.reload()` (outside a browser, nothing
+happens). Pass `onReload` to do something first, or instead:
+
+```ts
+// test: connection#reload
+// continues from Connect: createVantage, schema, Schema; saveDraft is your UI's
+const db = createVantage<Schema>({
+  schema,
+  onReload: () => {
+    saveDraft();
+    location.reload();
+  },
+});
+```
+
+## Scripts and the wire `where`
+
+On the wire, `where` is a list of `[column, op, value]` tuples:
+`[["status", "eq", "open"]]`. The client builds that from `.where({...})`;
+only raw WebSocket scripts write it by hand (`references/protocol.md`).

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

@@ -0,0 +1,67 @@
+# The wire protocol
+
+JSON text frames over `ws(s)://<host>/v1/ws`, tagged by `t`. Requests carry
+an `id`; replies echo it. The client handles all of this; read on for raw
+scripts and debugging. HTTP: `/v1/schema` (the schema `generate` reads),
+`/v1/health`, `/v1/ready` (503 naming entities whose datasource is down).
+
+## Session
+
+| 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`) |
+| 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 1012 `reconnect`: the server is shutting down |
+
+Nothing but `hello` is accepted before a `welcome`.
+
+## Reading
+
+| Client → server | Server → client |
+|---|---|
+| `open_table {table, where?, search?, sort?, via?, limit?}` | `rows {sub, start, ids, records, total, complete, seq}` |
+| `viewport {sub, start, count}` | `members {sub, start, ids, records, total, complete}` |
+| `close {sub}` | `members` pushed when membership or order changes |
+| `open_records {table, ids}` | `records {records, missing}` |
+| `interest {remove: [[table, id]]}` | `changed {seq, events: upsert \| removed \| invalidated}` |
+
+`where` is a list of `[column, op, value]` tuples, `sort` is
+`[column, "asc" | "desc"]`, and `via` is `{table, id, ref}` (a parent's
+has-many). A refused request gets `error {id, kind, message}`.
+
+## Writing and actions
+
+| Client → server | Server → client |
+|---|---|
+| `flash {table, rid?, patch}` · `batch {items}` · `delete {table, rid}` | `flashed {rid, seq, record}` · `rejected {message, field_errors}` · `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}` |
+
+A run's `seq` counts its frames; a gap means one was missed, and an
+`invoke {run}` brings a fresh snapshot. Each message is
+`{name, payload, seq}`, `seq` being the frame it first went out in, so the
+snapshot's messages past the last `seq` you applied are the ones you
+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 raw script
+
+```ts
+// test: protocol#raw-script
+const ws = new WebSocket("ws://127.0.0.1:8090/v1/ws");
+ws.onopen = () => {
+  ws.send(JSON.stringify({ t: "hello", id: 1, protocol: 1, token: process.env.VANTAGE_TOKEN }));
+  ws.send(JSON.stringify({ t: "open_table", id: 2, table: "issues", where: [["status", "eq", "open"]], sort: ["created_at", "desc"], limit: 50 }));
+};
+ws.onmessage = (message) => console.log(JSON.parse(String(message.data)));
+```
+
+A WebSocket from a page on another origin is refused (403): `Origin` must
+name the host the request was sent to. Scripts send no `Origin`.