@fitzzero/quickdraw-core 5.0.0-rc.3 → 5.0.0-rc.4

package/README.md

@@ -25,7 +25,7 @@ single hand-written event.
 - **Testing**: a real test server, access matrices, performance budgets that
   count statements and bytes, strict development warnings.
 
-Design record: [`docs/rfcs/0003-v5.md`](../../docs/rfcs/0003-v5.md).
+Design record: [`docs/rfcs/0003-v5.md`](https://github.com/fitzzero/quickdraw/blob/dev/docs/rfcs/0003-v5.md).
 
 ## Install
 
@@ -710,10 +710,12 @@ export const taskService = qd.defineService(task, {
   (`adminBypass: false` turns that off). A grant below `Admin` counts only
   where the form names `service`: a `Read` grant does not read every row.
 - Grants come from `principal.serviceAccess`, as `authenticate` returns it or
-  `createServer({ auth: { loadServiceAccess } })` loads it. With
+  `createServer({ auth: { loadServiceAccess } })` loads it for a principal
+  that carries none: at a socket's handshake, for each HTTP call, and for
+  an in-process caller (`qd.caller`) at its first call. With
   `auth.serviceAccessSource: { model: "user", column: "serviceAccess" }`, a
   tracked write to that column refreshes the user's open sockets
-  (`qd:access`).
+  (`qd:access`), and in-process callers load the grants again.
 - Policies: `owner(field)`, `jsonAcl(field, { owner? })`,
   `members({ model, entry, user, level, levels? })`, `inherit({ from, via })`,
   `anyOf(...)`, `resolver({ levelsFor, where? })` and `everyone(level)`
@@ -774,6 +776,10 @@ tracked client as `db`; the server finds the rest on it.
   not wait for (a push sent after a message, pruning what it reports dead)
   runs in `qd.run(fn, { detached: true })`, a unit of its own that flushes
   when `fn` settles (catch what the promise rejects with: nothing awaits it).
+  Before any server exists (a seed at boot, before `createServer`),
+  `qd.run(fn)` still runs `fn` in a unit of its own, and its writes reach no
+  one: no socket can be subscribed yet (behind a cluster, write after
+  `createServer` when other nodes' subscribers must hear of it).
 
 <!-- example: apps/api/src/jobs/overdue.ts#run -->
 
@@ -908,7 +914,7 @@ export const taskService = qd.defineService(task, {
   Valkey's clock in microseconds, so revisions from all nodes are one order;
   its key needs persistence or replication. A node whose Valkey connection
   comes back has its clients reconnect to catch up.
-  [docs/deploying.md](../../docs/deploying.md) has the wiring, what holds across
+  [docs/deploying.md](https://github.com/fitzzero/quickdraw/blob/dev/docs/deploying.md) has the wiring, what holds across
   nodes, what it costs, and what happens when a node or Valkey stops
   answering.
 
@@ -1001,7 +1007,9 @@ export const taskService = qd.defineService(task, {
   scope after a change tracked writes cannot describe.
 - `qd:watch { s, topic }` joins a change topic: `{collection}:{scope}`,
   authorized like a subscribe to that scope, or `service`, which changes
-  whenever any row of the service does. The service topic is closed
+  whenever any row of the service does, or a row of a model it lists in
+  `writes` (a game's high scores, which no service owns). A query declares
+  `watch: "service"` to be invalidated by it. The service topic is closed
   (`FORBIDDEN`) unless the service declares `watchAccess` (`"public"`,
   `"authenticated"` or `{ service: level }`). A watcher that loses access
   leaves the topic after one last `qd:changed`.
@@ -1018,7 +1026,9 @@ over three transports (design: sections 3, 8 and 10):
 
 - **Socket.IO** (protocol 5): a client connects with
   `auth: { token, qd: { protocol: 5, client } }`, receives `qd:hello` with the
-  server's limits and who it acts for, and calls through `qd:call` and
+  server's limits, who it acts for and the server's id (`serverId`, new
+  each time a server starts: a reconnect that brings another one reached a
+  restarted server, or another node), and calls through `qd:call` and
   `qd:cancel`. Every socket gets the same few listeners however many methods
   the services have. The JSON-only parser is the default; `binary: true`
   restores the stock one. The socket rate limiter is on by default (600
@@ -1040,7 +1050,13 @@ over three transports (design: sections 3, 8 and 10):
   `./server/express`), which refuses with the `RATE_LIMITED` reply.
 - **In process**: `server.dispatcher.caller(principal)` or
   `qd.caller(principal)`: `await qd.caller(user).taskService.rename(input)`,
-  typed by the `contracts` of `initQuickdraw`'s types.
+  typed by the `contracts` of `initQuickdraw`'s types. A principal that
+  carries no `serviceAccess` gets the grants `auth.loadServiceAccess`
+  loads, as a socket's handshake and an HTTP call do: at the caller's first
+  call, and again at its next call after the server applied new grants to
+  a user (`server.access.refresh`, a tracked write to
+  `auth.serviceAccessSource`). One that carries grants (even `{}`) keeps
+  exactly those. A load that fails rejects the call with `INTERNAL`.
 
 `authenticate` takes one request (`{ transport, auth, headers, socket | req }`)
 for both transports and returns a principal, a user id, or nothing for an
@@ -1154,15 +1170,16 @@ the method's kind does not have, is a compile error.
 `QueryClient` (5-minute stale time by default), and works without DOM
 globals (React Native).
 
-| Member                                                                    | Gives                                                                                          |
-| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `qd.task.get.useQuery(input, options)`                                    | TanStack's `useQuery`; errors are `QuickdrawError` with a `code`                               |
-| `qd.task.rename.useMutation(options)`                                     | TanStack's `useMutation`; `mutate` returns nothing, `mutateAsync` the output                   |
-| `qd.task.useEntity(id)`, `useEntities(ids)`                               | live rows at the user's level: `{ data, isLoading, isRemoved, error }`                         |
-| `qd.task.board.useCollection(scope, { view, load, limit })`               | a live scope: `{ items, index, byId, totalCount, hasMore, isLoading, loadMore, refresh, ... }` |
-| `qd.task.get.call(input)`, `.key(input)`, `.prefetch(queryClient, input)` | a call over the mounted provider's connection, the cache key, a prefetch                       |
-| `qd.invalidate(qd.task.get, input?)`                                      | invalidates through the coordinator: a read in flight is never cancelled                       |
-| `useQuickdraw()`                                                          | `{ connection, status, isConnected, userId, serviceAccess, hello, refusal, isRateLimited }`    |
+| Member                                                                    | Gives                                                                                           |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `qd.task.get.useQuery(input, options)`                                    | TanStack's `useQuery`; errors are `QuickdrawError` with a `code`                                |
+| `qd.task.rename.useMutation(options)`                                     | TanStack's `useMutation`; `mutate` returns nothing, `mutateAsync` the output                    |
+| `qd.task.useEntity(id)`, `useEntities(ids)`                               | live rows at the user's level: `{ data, isLoading, isRemoved, error }`                          |
+| `qd.task.board.useCollection(scope, { view, load, limit })`               | a live scope: `{ items, index, byId, pending, totalCount, hasMore, isLoading, loadMore, ... }`  |
+| `qd.task.get.call(input)`, `.key(input)`, `.prefetch(queryClient, input)` | a call over the mounted provider's connection, the cache key, a prefetch                        |
+| `qd.invalidate(qd.task.get, input?)`                                      | invalidates through the coordinator: a read in flight is never cancelled                        |
+| `qd.task.get.setData(input, updater)`                                     | writes a cached result an event carries, at once; a read in flight is followed by one more      |
+| `useQuickdraw()`                                                          | `{ connection, status, isConnected, isKnown, reconnecting, userId, serviceAccess, hello, ... }` |
 
 <!-- example: apps/web/src/components/TaskDetail.tsx#detail -->
 
@@ -1203,12 +1220,18 @@ export function TaskDetail({ id }: { readonly id: string }) {
   collection items from the moment it is sent, are dropped if it fails, and
   give way to the server's frame. `optimistic: false` turns that off;
   `optimistic: (input, cache) => ...` writes its own layers with
-  `patchEntity`, `removeEntity` and `patchItem`.
+  `patchEntity`, `removeEntity` and `patchItem`, and adds rows with
+  `addItem` and `addEntity` (below).
 - Live rows and collections need no refetching: frames keep them current,
   and after a reconnect they resume by revision. A query whose result
   follows writes declares `watch` in its contract; the coordinator fetches
   it again once per change, with at most one read in flight per key. Do not
   call `refetch` or `invalidateQueries` on quickdraw keys after a mutation.
+- An event that carries a query's new result (a room's roster, a score)
+  writes it with `qd.<service>.<query>.setData(input, updater)` rather than
+  refetching: the hooks show it at once, under the overlays of optimistic
+  mutations, and a read of that key already in flight (which may predate
+  the event) is followed by one more, never cancelled.
 - After a reconnect, the queries that are watched (they missed the changes
   meanwhile) or stale are refetched, each after a random delay of up to
   `reconnectJitterMs` (2,000 ms by default), so clients that reconnect
@@ -1227,6 +1250,87 @@ export function TaskDetail({ id }: { readonly id: string }) {
 - A protocol mismatch reloads the page once per session by default
   (`onProtocolMismatch`); `RATE_LIMITED` answers back off with jitter per
   kind of work.
+- Server rendering: a server never connects, so `useQuickdraw()`,
+  `usePresence`, streams and overlays render the state a new connection has
+  (nobody known, no rooms, nothing loaded), and the browser hydrates that
+  same state even where the provider connected first (a Suspense boundary
+  that hydrates late), then renders the live one.
+
+A create shows its row before the server answers with `cache.addItem(collection,
+scope, item)`: the item appears in the scope at once, in its place by the
+collection's `order` (give it the order's fields; without them it goes
+last), and `useCollection`'s `pending` names it while the call is in flight.
+A refused call removes it. The reply's `id` (the created row's) and values
+replace the item's own, and once the scope's own copy arrives (its `added`
+delta, or a load) that copy shows in its place: never both, never a gap.
+`cache.addEntity(row)` adds a row to every collection of entity rows whose
+scope column (and `where`) it matches; a collection of a projection takes
+`addItem`. The item may give its own `id`, one the client made and the
+server keeps:
+
+<!-- example: apps/web/src/components/AddTask.tsx#add -->
+
+```tsx
+export function TaskList({ projectId }: { readonly projectId: string }) {
+  const { items, pending } = qd.task.board.useCollection(projectId);
+  const create = qd.task.create.useMutation({
+    // the new card shows at once, last on the board (its ordinal), until the server's arrives
+    optimistic: (input, cache) =>
+      cache.addItem("board", input.projectId, {
+        projectId: input.projectId,
+        title: input.title,
+        status: "open",
+        ordinal: Number.MAX_SAFE_INTEGER,
+        assigneeId: null,
+      }),
+  });
+  return (
+    <>
+      <ul>
+        {items.map((task) => (
+          // pending: the create is on its way; the card is the server's once it answers
+          <li key={task.id} style={{ opacity: pending.has(task.id) ? 0.5 : 1 }}>
+            {task.title}
+          </li>
+        ))}
+      </ul>
+      <button type="button" onClick={() => create.mutate({ projectId, title: "New task" })}>
+        Add
+      </button>
+      {create.error === null ? null : <p>{`Not added: ${create.error.code}`}</p>}
+    </>
+  );
+}
+```
+
+`useQuickdraw()` says who the connection acts for. `userId` is `null` both
+for an anonymous socket and before the server's hello, so a gate waits for
+`isKnown` (the hello on the current credentials arrived; false again from
+new credentials until theirs). `isConnected` turns true before the hello and
+false while the connection reconnects; `reconnecting` says the user and the
+page stay meanwhile:
+
+<!-- example: apps/web/src/components/AuthGate.tsx#gate -->
+
+```tsx
+export function AuthGate({ children }: { readonly children: ReactNode }) {
+  // isKnown: the server's hello named the user, so userId is final (null: signed out)
+  const { isKnown, userId, reconnecting } = useQuickdraw();
+  if (!isKnown) {
+    return <p>Connecting…</p>;
+  }
+  if (userId === null) {
+    return <SignIn />;
+  }
+  // a reconnect keeps the user and the page: say so, unmount nothing
+  return (
+    <>
+      {reconnecting ? <p role="status">Reconnecting…</p> : null}
+      {children}
+    </>
+  );
+}
+```
 
 ### Server components and other runtimes
 
@@ -1282,9 +1386,9 @@ such code, and `createInvalidationCoordinator(queryClient)` invalidates as
 the hooks do.
 
 A client in another language (a Godot game, a native app) speaks the wire
-itself: [`docs/protocol-v5.md`](../../docs/protocol-v5.md) is its specification,
-generated from the protocol's source, and [`examples/godot`](../../examples/godot)
-holds a GDScript client written from it. [`docs/clients.md`](../../docs/clients.md)
+itself: [`docs/protocol-v5.md`](https://github.com/fitzzero/quickdraw/blob/dev/docs/protocol-v5.md) is its specification,
+generated from the protocol's source, and [`examples/godot`](https://github.com/fitzzero/quickdraw/tree/dev/examples/godot)
+holds a GDScript client written from it. [`docs/clients.md`](https://github.com/fitzzero/quickdraw/blob/dev/docs/clients.md)
 compares the three ways in.
 
 ## Kits
@@ -1759,7 +1863,10 @@ export function AdminTasks() {
   // [{ key: "task", serviceName, displayName }]
   const { services } = useAdminServices(qd);
   const { data } = qd.task.admin.adminList.useQuery({ page: 1, sort: { field: "title" } });
-  const update = qd.task.admin.adminUpdate.useMutation();
+  const update = qd.task.admin.adminUpdate.useMutation({
+    // adminList is a query, not live data: read the page again after this screen's own write
+    onSuccess: () => qd.invalidate(qd.task.admin.adminList),
+  });
   return (
     <table aria-label={services[0]?.displayName}>
       <tbody>
@@ -1807,7 +1914,7 @@ export function AdminTasks() {
   value is checked by the entity schema itself, and a value the database
   refuses is `VALIDATION`. A missing row is `NOT_FOUND`.
 - `adminMeta()` returns `{ serviceName, displayName, fields }`, one
-  `{ name, type, label, required, editable, showInTable, sortable, filterable, enumValues?, relationService? }`
+  `{ name, type, label, required, editable, showInTable, sortable, filterable, enumValues?, relationService?, kind?, showInForm? }`
   per field: `type` is
   `string`, `number`, `boolean`, `date` (an ISO string with a date format),
   `enum` or `json` from the field's JSON Schema, and `relation` by override;
@@ -1824,7 +1931,21 @@ export function AdminTasks() {
   rows without it and `FORBIDDEN` for a write, filter or sort naming it.
   The write is tracked, so with `auth.serviceAccessSource` naming the column
   the user's open sockets get the new grants at once, on every node. Such
-  an Admin can grant any service, themself included.
+  an Admin can grant any service, themself included. The field's
+  configuration says `kind: "grants"`, so a screen with a grants editor of
+  its own finds it without its name, and
+  `fieldOverrides: { serviceAccess: { showInForm: false } }` keeps it out
+  of a generic create or edit form (a form shows the fields whose
+  `showInForm` is not `false`); the kit still reads and writes it.
+- `admin.handlers(contract, { onWrite })` runs `onWrite({ method, id,
+before?, after }, ctx, db)` after each `adminCreate`, `adminUpdate` and
+  `adminDelete`, in one transaction with the write (`db` is the
+  transaction's tracked client; a throw undoes the write and fails the
+  call): what an admin edit must set off, such as a game reloading its
+  tunables, without wrapping the kit's handlers. The rows are the entity,
+  every field. Without it the kit opens no transaction. Each handler
+  `admin.handlers` returns resolves with its method's output type, so a
+  wrapper reads the row and returns it with no cast.
 - `adminSubscribers({ id })` counts the sockets subscribed to a row per
   access level (`{ id, count, levels, complete }`; behind a Redis adapter
   the counts are this server's and `complete` is `false`), and
@@ -1834,6 +1955,21 @@ export function AdminTasks() {
   `qd.admin`, since `admin` is reserved per service). `useAdminServices(qd)`
   lists the client's services whose `adminMeta` answers the user, with their
   display names, sharing the cache of `qd.<service>.admin.adminMeta.useQuery()`.
+  It asks only the services the user's grants (from the server's hello)
+  allow: `Admin` by default, what the kit's methods require;
+  `useAdminServices(qd, { requires: "Moderate" })` for an `adminMeta` given
+  another form, `requires: null` for every service. A service that refused
+  is not asked again until the user's grant on it changes, reconnects
+  included.
+- The kit's rows are not live: `adminList` and `adminGet` are queries that
+  watch nothing, so a screen reads them again after its own writes (the
+  `onSuccess` above), and sees other admins' writes when it next reads.
+- A screen that serves every service from its metadata (the route names the
+  service) takes `adminOf(qd, key)`: the same members, keyed by what the kit
+  made them for and typed by field name (`AdminScreen`: rows are
+  `AdminRow`, `adminList` takes `{ page, pageSize, filter, sort: { field, direction } }`
+  with names read from `adminMeta`), so no cast is needed over a union of
+  keys; a method the contract does not expose is absent.
 
 ### Presence, streams and channels
 
@@ -1899,6 +2035,16 @@ export const taskService = qd.defineService(task, {
       ctx.rooms.emit(`board:${payload.projectId}`, task, "cursorMoved", payload);
     },
   },
+  // once per socket that leaves app rooms, in every server this service runs in, in a unit of its own
+  onRoomLeave: ({ principal, rooms }) => {
+    for (const { room, last } of rooms) {
+      // last: no socket of the user is in the room any more (a second tab keeps it false)
+      if (principal !== null && last && room.startsWith("board:")) {
+        const projectId = room.slice("board:".length);
+        qd.rooms.emit(room, task, "leftBoard", { projectId, userId: principal.userId });
+      }
+    }
+  },
 });
 
 // in handlers, jobs and timers
@@ -1922,14 +2068,17 @@ export function TaskRoom({
   readonly projectId: string;
   readonly taskId: string;
 }) {
+  // the socket is in the board's room on every connection: a reconnect is a new socket in no room
+  const board = useJoin(qd.task.enterBoard, { projectId });
   const { items } = qd.task.logs.useStream(taskId, { max: 200 });
   const { send, isReady } = qd.task.cursor.useChannel();
   const [lastX, setLastX] = useState(0);
   qd.task.cursorMoved.useEvent((cursor) => setLastX(cursor.x));
-  // user ids, after enterBoard joined the room
+  // user ids, once enterBoard joined the room
   const here = usePresence(`board:${projectId}`);
+  const move = (x: number) => isReady && board.isJoined && send({ projectId, taskId, x });
   return (
-    <div onMouseMove={(event) => isReady && send({ projectId, taskId, x: event.clientX })}>
+    <div onMouseMove={(event) => move(event.clientX)}>
       <p>{`${String(here.length)} here; a cursor at ${String(lastX)}`}</p>
       <pre>{items.map((item) => item.line).join("\n")}</pre>
     </div>
@@ -1943,20 +2092,33 @@ export function TaskRoom({
   latest `seed` items per scope in memory on that process (at most 1,000 per
   scope and 10,000 scopes per stream; a restart empties them, and durable
   history is the app's: store the rows and expose a collection), and sends
-  `qd:stream { s, stream, scope?, item }` to the feed's subscribers,
-  volatile when the stream says so. `pushMany(scope, items)`
+  `qd:stream [service, stream, scope, item]` (`scope` null for a global
+  stream; positional, so a fast stream's frames carry no key names) to the
+  feed's subscribers, volatile when the stream says so. `pushMany(scope, items)`
   (`pushMany(items)` for a global stream) pushes several items to one feed
   at once: every item is checked before any is kept or sent, and each goes
   out as its own frame, in order; use it rather than `push` in a loop
   (`no-emit-in-loop`). `qd:stream:sub` is authorized with the
   stream's `access` through the access engine, the scope being the row an
-  `entry` or `scope` form checks; a stream without `access` is closed. The
-  answer is the seed; `useStream` then appends, keeps the latest `max`
-  (default 500), and subscribes again after a reconnect, when the seed
-  replaces what it held. A socket holds at most 500 feeds. A subscriber
-  whose access is lowered is authorized again; one refused leaves the feed
-  and gets `qd:revoked { kind: "stream", reason: "access", s, stream, scope? }`,
-  and `useStream` shows `FORBIDDEN` until the next connect.
+  `entry` or `scope` form checks; `access: { room }` (a name, `{ prefix }`,
+  or for a scoped stream a function of the scope) opens it to the sockets
+  in that app room instead, signed in or not, and a socket that leaves the
+  room, or is taken out, leaves the feed; a stream without `access` is
+  closed. The answer is the seed; `useStream` then appends, keeps the
+  latest `max` (default 500), and subscribes again after a reconnect, when
+  the seed replaces what it held. A socket holds at most 500 feeds. A
+  subscriber whose access is lowered is authorized again; one refused
+  leaves the feed and gets
+  `qd:revoked { kind: "stream", reason: "access", s, stream, scope? }`, and
+  `useStream` shows `FORBIDDEN` until the next connect.
+- A service's `streams: { <name>: { seed, validate } }` computes a stream's
+  seed per subscriber, `seed: (scope, ctx) => items` (the current state,
+  where the items that follow are deltas; on whichever node the subscriber
+  is on, under its principal, in the tick it joins the feed; a contract
+  `seed: n` and a seed function cannot both be declared), and
+  `validate: "development"` checks pushed items only while the dispatcher
+  checks outputs (`outputValidation`, off in production), for a hot stream:
+  unchecked, an item goes out as pushed, extra keys included.
 - Channels: each message is `qd:ch [service, channel, payload]`, sent
   volatile and never answered. Per socket and channel a token bucket
   (`ratePerSecond`, default 30; `burst`, default twice that) drops what is
@@ -1968,10 +2130,13 @@ export function TaskRoom({
   scope; `{ room }`: the app room, a name like `"world"` or a function of
   the payload, which a call over that same socket joined) is dropped.
   Nothing is logged per message; a handler's error is. The socket rate
-  limiter does not count channels. Every requirement is the sending
-  socket's own: a room another socket of the user joined does not count, a
-  reconnected socket must join again, and behind a cluster the check runs
-  on the node the socket is connected to, with no round trip.
+  limiter does not count channels. `{ room: { prefix: "world:" } }` takes
+  a socket in any app room whose name starts with the prefix (a game of many
+  worlds), and every room form gives the handler the room it matched as
+  `ctx.room`, so the payload need not repeat it. Every requirement is the
+  sending socket's own: a room another socket of the user joined does not
+  count, a reconnected socket must join again, and behind a cluster the
+  check runs on the node the socket is connected to, with no round trip.
 - Presence: `isOnline`, `lastSeen` (now while online, else when the user's
   last socket on this process disconnected), `count` and `users` (each user
   once, anonymous sockets left out; app rooms only) come from this process's
@@ -1986,16 +2151,24 @@ export function TaskRoom({
   `emitToUser(userId, ...)` check the payload first (`INTERNAL`, nothing
   sent, when it fails), then send the validated payload as
   `qd:event [service, event, payload]`; `useEvent` hears them.
+- Rooms belong to a socket: a reconnect (a lost network, `qd:rotate`, new
+  credentials) is a new socket in no room, which hears none of its events
+  and whose channel messages requiring it are dropped. `useJoin(member,
+input, { enabled?, onJoined? })` (from `./client`) runs the joining call
+  (`enterBoard` above) on every `qd:hello` and when its input changes by
+  value, never on a re-render, and shows `status` (`idle` with no socket to
+  join with, `joining`, `joined`, `error`), `isJoined`, `data` and `error`;
+  a refusal stands until the next hello, `RATE_LIMITED` is tried again after
+  its backoff, and it never leaves the room itself.
+  `connection.onHello(listener)` is the same hook without React.
 
 Code that is not a handler (a game loop, a timer, a job) reaches rooms
-through `qd.rooms` (also `server.rooms`), and `onRoomLeave` hears sockets
-leave:
+through `qd.rooms` (also `server.rooms`); the service's `onRoomLeave` (above)
+hears sockets leave:
 
 <!-- example: apps/api/src/services/kits/rooms.ts#rooms -->
 
 ```ts
-import type { RoomLeaveHandler } from "@fitzzero/quickdraw-core/server";
-
 const boardRoom = (projectId: string): string => `board:${projectId}`;
 
 // a timer or a game loop's tick, outside any handler: every socket in the room, on every node
@@ -2009,20 +2182,20 @@ export async function removeFromBoard(projectId: string, userId: string): Promis
   await qd.rooms.leave(boardRoom(projectId), { userId });
 }
 
-// qd.createServer({ ..., onRoomLeave }): once per socket that leaves app rooms, in a unit of its own
-export const onRoomLeave: RoomLeaveHandler<AppPrincipal> = ({ principal, rooms }) => {
-  for (const { room, last } of rooms) {
-    // last: no socket of the user is in the room any more (a second tab keeps it false)
-    if (principal !== null && last && room.startsWith("board:")) {
-      const projectId = room.slice("board:".length);
-      qd.rooms.emit(room, task, "leftBoard", { projectId, userId: principal.userId });
-    }
-  }
-};
+// a tick loop's "is anyone watching?", at its tick rate: this node's sockets in the room,
+// anonymous ones too, with no promise (presence.count asks every node for users)
+export function hasAudience(projectId: string): boolean {
+  return qd.rooms.size(boardRoom(projectId)) > 0;
+}
 ```
 
 - `qd.rooms.emit` and `emitToUser` are `ctx.rooms`' own, from anywhere,
   reaching every node behind a cluster adapter.
+- `rooms.size(room)` (on `qd.rooms`, `server.rooms` and `ctx.rooms`) counts
+  the sockets in an app room on this node, anonymous ones included, at once:
+  a game loop can ask it every tick. It is local by design; `presence.count`
+  counts users on every node. A handler's `ctx.socketId` names the socket
+  its call arrived on (`undefined` over HTTP, MCP or in process).
 - `leave(room, { userId })` (on `qd.rooms`, and on `ctx.rooms` beside the
   calling socket's own `leave(room)`) takes every socket of the user out of
   an app room, on every node: they hear nothing more of it, a channel that
@@ -2030,8 +2203,13 @@ export const onRoomLeave: RoomLeaveHandler<AppPrincipal> = ({ principal, rooms }
   `qd:presence { room, users: [] }`, and the room hears `left`. Behind a
   cluster it is broadcast and answered, so await it before sending what the
   user must not receive. Joining again is the app's to refuse.
-- `createServer({ onRoomLeave })` runs once per socket that leaves app
-  rooms, on the node that held it: its own `leave` (`reason: "leave"`), a
+- A service's `onRoomLeave` runs once per socket that leaves app rooms, in
+  every server the service runs in (`createTestApp` and a benchmark's
+  server included, with nothing to wire), beside every other service's and
+  `createServer({ onRoomLeave })`, the app's own; each runs in a unit of
+  work of its own, and one that throws stops none of the others. It hears
+  every app room a socket leaves, so check the room's name. It runs on
+  the node that held the socket: its own `leave` (`reason: "leave"`), a
   removal (`"removed"`), or a disconnect, which leaves every app room it was
   in (`"disconnect"`; `qd:rotate` reconnects with a new socket). Each room
   comes with `last`: true when no socket of that user is in the room any
@@ -2191,11 +2369,11 @@ nothing is cached:
   session's token, for clients that keep no cookies (a game engine, a page
   in a third-party iframe), at the cost of the token being readable by the
   page's scripts.
-- `requireSession({ sessions, jwtSecret })` guards the app's own REST
-  routes: the credential is read as `/me` reads it, the JWT verified once
-  and the session checked in the store, then `req.userId` and
-  `req.sessionId` are set; otherwise 401 `{ error: "UNAUTHENTICATED", message }`.
-  4.1's `createRequireAuth` stays for token-keyed sessions.
+- `requireSession({ sessions, jwtSecret }, { loadPrincipal? })` guards the
+  app's own REST routes (below): the credential is read as `/me` reads it,
+  the JWT verified once and the session checked in the store; otherwise
+  401 `{ error: "UNAUTHENTICATED", message }`. 4.1's `createRequireAuth`
+  stays for token-keyed sessions.
 - Rate limits: the sign-in routes share `createAuthLimiter({ max: 60 })` (60
   requests per 15 minutes per IP) and the session routes
   `createAuthStatusLimiter()` (120); pass `rateLimit: { signIn, session }`
@@ -2240,6 +2418,83 @@ nothing is cached:
   session for an app's own sign-in flow (login codes, an embedded activity),
   and `liveSession` reads a token back; both work with `socketAuth`.
 
+From the browser, `./client` speaks to these routes: `signInUrl(provider,
+{ apiUrl, returnTo })` is the start route's URL (to navigate to; `returnTo`
+defaults to the current page's origin), and `signOut()` and
+`signOutEverywhere()` post to `logout` and `logout-all`. Each POST sends the
+session cookie (`credentials: "include"`, so the API's CORS must allow the
+web app's origin with credentials) with `Content-Type: application/json`,
+and the token `setAuthToken` stored, if any, as a bearer token; the stored
+token is forgotten either way, and a refusal or an unreachable server
+rejects with a `QuickdrawError`. A socket keeps the user it signed in as
+until it connects again, so reconnect the provider's connection after
+signing out (with a token in `auth`, clearing it does that):
+
+<!-- example: apps/web/src/components/SignIn.tsx#browser -->
+
+```tsx
+export function SignIn() {
+  // the kit's GET /auth/google/start: back to this page's origin with the session cookie
+  return <a href={signInUrl("google", { apiUrl: API_URL })}>Sign in with Google</a>;
+}
+
+export function SignOut() {
+  const { connection } = useQuickdraw();
+  const leave = async (): Promise<void> => {
+    // POST /auth/logout with the cookie: the session is revoked, the cookie cleared
+    await signOut({ apiUrl: API_URL });
+    // the socket keeps its user until it connects again, as nobody now
+    connection.close();
+    connection.open();
+  };
+  return (
+    <button type="button" onClick={() => void leave()}>
+      Sign out
+    </button>
+  );
+}
+```
+
+An app's own REST route (a service worker's renewal, a webhook) signs the
+user in with `requireSession` and calls the services in process, so the
+method's validation, access check and tracked writes are a socket call's.
+`sessionOf(req)` gives the route `{ userId, sessionId, principal }`, typed,
+with no cast of `req` (`sessionOf<AppPrincipal>(req)` when `loadPrincipal`,
+like `socketAuth`'s, builds the app's own principal; by default it is
+`{ userId, kind: "user" }`); they are also set as `req.userId`,
+`req.sessionId` and `req.principal`. `qd.caller(principal)` then loads the
+user's grants as the user's sockets get them, so a method behind
+`{ service: L }` passes or answers `FORBIDDEN` as it would over a socket:
+
+<!-- example: apps/api/src/auth/routes.ts#rest -->
+
+```ts
+import { httpStatus, toWire } from "@fitzzero/quickdraw-core";
+import { requireSession, sessionOf } from "@fitzzero/quickdraw-core/server/auth";
+
+// 401 without a live session; the principal built as socketAuth builds a socket's
+const signedIn = requireSession(
+  { sessions, jwtSecret: env.JWT_SECRET },
+  { loadPrincipal: (userId): AppPrincipal => ({ userId, kind: "user" }) },
+);
+
+app.get("/api/projects/:projectId/task-count", signedIn, (req, res) => {
+  void (async () => {
+    const { principal } = sessionOf<AppPrincipal>(req);
+    try {
+      // the method's validation, access check (with the user's grants) and writes, as over a socket
+      const count = await qd.caller(principal).taskService.countOnBoard({
+        projectId: req.params.projectId,
+      });
+      res.json({ count });
+    } catch (error) {
+      const failure = toWire(error);
+      res.status(httpStatus(failure.code)).json(failure);
+    }
+  })();
+});
+```
+
 `createMemorySessionStore()` keeps sessions in the process, for development
 and tests. In production, store them in the database. Sessions are not live
 data, so nothing needs their writes tracked: with the tracked client, the
@@ -2320,8 +2575,14 @@ it("sends a rename to the other members' boards", async () => {
 - `app.as(principal)` calls in process and `app.connect(principal)` over a
   real socket (`{ call, socket, hello, close }`); both are keyed by service
   name. `app.frames(match?)` lists every frame the server sent, with its
-  socket and user; `frames.waitFor(match)` waits for one. `emitWithAck` and
-  `waitForEvent` send raw frames and wait for events.
+  socket and user; `frames.waitFor(match)` waits for one. A query of one
+  event takes `where`, a predicate over its frames typed by the event
+  (`{ event: "qd:presence", where: ({ data }) => data.joined === id }`), and
+  `streamFrames(contract, stream, where?, scope?)` and
+  `eventFrames(contract, event, where?)` match one stream's items or one
+  event's payloads, typed by the contract, to spread beside `socketId` or
+  `userId`. `emitWithAck` and `waitForEvent` send raw frames and wait for
+  events.
 
 ### Access matrices
 
@@ -2500,9 +2761,22 @@ async (Testing Library, an optional peer, is loaded lazily) and returns
 Testing Library's result plus `connection`, `queryClient`, `disconnect()`
 and `reconnect()`, which drop and restore the socket as a lost network does.
 
-For a component test without a server, `createMockClient(contracts)` gives
-the typed client's shape with stubs; give it to the components in place of
-the app's client (a module mock of the file that exports `qd`, say):
+The web app's test imports the API's services across apps, as above, and
+needs a database: run such tests in a jsdom project of their own, with the
+API's global setup (the template its test databases boot from, below) and a
+setup file that calls `installJsdomShims()` from `./testing/client`. That
+adds what jsdom lacks, and keeps what it has: `scrollTo`, `scrollBy` and
+`scrollIntoView` on elements (they do nothing; a list that follows its newest
+item calls them) and `Blob.prototype.arrayBuffer` (PGlite reads a database
+dump through it). This repository runs the README's example app that way:
+`packages/core/vitest.config.ts`, project `readme`, with
+`test/readme/globalSetup.ts` and `test/readme/workerSetup.ts`.
+
+For a component test or a story without a server, `createMockClient(contracts)`
+gives the typed client's shape with stubs; give it to the components in place
+of the app's client (a module mock of the file that exports `qd`, say). It
+comes from `./testing/client`, or from `@fitzzero/quickdraw-core/testing/mock`,
+which names no Testing Library, for a browser bundle (Storybook):
 
 <!-- example: apps/web/src/components/TaskBoard.test.tsx#mock -->
 
@@ -2522,14 +2796,52 @@ each test only when the test runner has a global `afterEach` (vitest with
 (`resetAfterEach: false` opts out); otherwise call `mock.$reset()` in an
 `afterEach` of your own, as above. Optimistic updates are not shown.
 
+The members' hooks need no provider. A component that reads the connection
+(`useQuickdraw()`, `usePresence(room)`) renders inside the mock's own
+provider, `mock.$Provider`, where those real hooks read the mock's session:
+who it acts for, set with `createMockClient(contracts, { session })` and
+`mock.$session({ userId, serviceAccess, isConnected, isKnown })` (each field
+left out keeps its starting value, and the reset after each test puts the
+starting session back), and the rooms `mock.$presence(room, userIds)` sets.
+Its views select members for the session's user:
+
+<!-- example: apps/web/src/components/TaskBoard.test.tsx#session -->
+
+```tsx
+it("lets a signed-in user through the gate", () => {
+  mock.$session({ userId: "ada", serviceAccess: { taskService: "Admin" } }); // useQuickdraw() shows it
+  render(<AuthGate>Board</AuthGate>, { wrapper: mock.$Provider });
+  expect(screen.getByText("Board")).toBeTruthy();
+});
+```
+
+In Storybook, a decorator renders every story inside `qd.$Provider`, and a
+story's `beforeEach` sets its session (`qd.$session(...)`) beside its data.
+
 ### Test databases
 
 `@fitzzero/quickdraw-core/testing/prisma` gives each vitest worker a database
 of its own: `createPrismaTestGlobalSetup` migrates a template once per run
 and clones a database per worker on PostgreSQL (`TEST_DATABASE_URL`), or
-boots PGlite from a cached dump without one; `workerDatabaseUrl` and
-`resetDatabase` (truncates every table) do the rest. Apply `trackPrisma` to
-the test client exactly as in production.
+builds a PGlite dump without one; `workerDatabaseUrl` and `resetDatabase`
+(truncates every table) do the rest. On PGlite each worker boots its own
+database from the dump with `openPgliteFromTemplate`, in milliseconds and
+under jsdom too (it reads the dump through Node's `Blob`); the app's db
+package gives its test client from it while tests run:
+
+<!-- example: packages/db/src/testing.ts#worker -->
+
+```ts
+// this worker's own database: the migrated template, loaded in milliseconds
+const pglite = await openPgliteFromTemplate(TEST_TEMPLATE);
+export const prisma = new PrismaClient({ adapter: new PrismaPGlite(pglite) });
+```
+
+`TEST_TEMPLATE` is `{ migrationsDir, cacheDir, templateName }`, the same the
+global setup builds with (`buildPgliteTemplate(TEST_TEMPLATE)`, or
+`createPrismaTestGlobalSetup`), and a setup file empties the database before
+each test (`beforeEach(() => resetDatabase(prisma))`). Apply `trackPrisma`
+to the test client exactly as in production.
 
 ## Observability
 
@@ -2582,17 +2894,30 @@ is also a server span named `service.method`, with an error status for
 
 ## API docs from contracts
 
-The `quickdraw-docs` command writes Markdown API docs from the contracts
-alone: one page per service (its entity and field tiers, projections,
-methods with their kind, input fields and output, collections, streams,
-channels and events, from the schemas' JSON Schema where they have one) and
-a `README.md` index. It reads contracts, never source code.
+The `quickdraw-docs` command writes Markdown API docs from the contracts:
+one page per service (its entity and field tiers, projections, methods
+with their kind, input fields and output, collections, streams, channels
+and events, from the schemas' JSON Schema where they have one) and a
+`README.md` index. It reads contracts (and, with `--services`, the
+services' definitions), never source code.
 
 ```bash
 quickdraw-docs packages/shared/src/index.ts --out docs/api           # write the pages
 quickdraw-docs packages/shared/src/index.ts --out docs/api --check   # exit 1 when they are stale
+quickdraw-docs packages/shared/src/index.ts --services apps/api/src/services/index.ts --out docs/api
 ```
 
+With `--services <module>` (a module exporting the services, each or in a
+list, as the server takes them; importing it must not start the server),
+each page also says who may call what, read from the services'
+definitions: an "Access" section with the row policy, whether a
+service-wide `Admin` grant passes every check, who may watch the change
+topic (`watchAccess`) and the field levels; each method's access form, in
+words, and its `rowless`; who may open a collection's scope; a channel's
+access; a stream's computed seed and when its items are checked. A
+contract the services module has no service for says so, and a service
+without a contract is an error. Pass the same flag to `--check`.
+
 The module may export each contract, or a map of them as given to
 `createQuickdrawClient`. A TypeScript module loads through Node's type
 stripping, or through `tsx` when the project has it installed (for
@@ -2604,7 +2929,7 @@ nothing. Run `--check` in CI next to the lint step.
 
 ## Lint rules and agent guidance
 
-[`@fitzzero/quickdraw-lint`](../../packages/lint) is the oxlint plugin and base
+[`@fitzzero/quickdraw-lint`](https://github.com/fitzzero/quickdraw/tree/dev/packages/lint) is the oxlint plugin and base
 config every 5.0 app extends: it reports untracked and foreign writes, nested
 and raw SQL writes, hand-sent frames, inline auth guards, unbounded reads,
 database calls and emits in loops, layering breaks, bypasses of the typed
@@ -2619,7 +2944,7 @@ takes an `id`, unless it says `rowless: true`); then lint; then a
 development warning as it happens (`repeated-call`, `repeated-mutation` and
 `repeated-invalidation` name a client loop before the rate limit does).
 
-[`@fitzzero/quickdraw-skills`](../../packages/skills) ships agent rules and skills
+[`@fitzzero/quickdraw-skills`](https://github.com/fitzzero/quickdraw/tree/dev/packages/skills) ships agent rules and skills
 for quickdraw apps and links them into `.claude/` with
 `quickdraw-skills link`, so every app's agents read the same, current
 guidance:
@@ -2635,11 +2960,11 @@ guidance:
 
 ## Migrating from 4.x
 
-[`@fitzzero/quickdraw-codemod`](../../packages/codemod) moves a 4.x app to 5.0:
+[`@fitzzero/quickdraw-codemod`](https://github.com/fitzzero/quickdraw/tree/dev/packages/codemod) moves a 4.x app to 5.0:
 contracts from the method maps, `defineService` from the service classes,
 the typed client for the hooks, and a report of everything left to decide.
-[`MIGRATION.md`](../../MIGRATION.md) explains each step, the access mapping and
-the defaults that changed; [`UPGRADE-PROMPT.md`](../../UPGRADE-PROMPT.md) is the
+[`MIGRATION.md`](https://github.com/fitzzero/quickdraw/blob/dev/MIGRATION.md) explains each step, the access mapping and
+the defaults that changed; [`UPGRADE-PROMPT.md`](https://github.com/fitzzero/quickdraw/blob/dev/UPGRADE-PROMPT.md) is the
 procedure for an agent. Both ship with the codemod, at
 `node_modules/@fitzzero/quickdraw-codemod/MIGRATION.md` and
 `node_modules/@fitzzero/quickdraw-codemod/UPGRADE-PROMPT.md`.
@@ -2654,7 +2979,7 @@ bunx @fitzzero/quickdraw-codemod@next v5 .
 | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `.`                | `defineContract`, `query`, `mutation`, `nullable`, `listOf`, `via`, the kits' contract halves, inference types, `QuickdrawError`, error codes, protocol types, room and topic names                                                             |
 | `./server`         | `initQuickdraw`, `createServer`, `createDispatcher`, `createHttpRouter`, policies, `custom`, the kits' handlers, `requireRow`, `nextOrdinal`, `storageOf`, dev warnings, the Redis adapter, the socket rate limiter, env and encryption helpers |
-| `./server/auth`    | `createAuthRoutes`, `socketAuth`, providers (`google`, `discord`, `mock`, `guest`), session stores, `issueSession`, `liveSession`, JWT, cookie and origin helpers                                                                               |
+| `./server/auth`    | `createAuthRoutes`, `socketAuth`, `requireSession` and `sessionOf`, providers (`google`, `discord`, `mock`, `guest`), session stores, `issueSession`, `liveSession`, JWT, cookie and origin helpers                                             |
 | `./server/express` | Express rate limits: `createAuthLimiter`, `createAuthStatusLimiter`, `createCallLimiter`, `createPublicApiLimiter`, `createWebhookLimiter`                                                                                                      |
 | `./server/mcp`     | `createMcpRegistry`, `describeTools`, `createMcpStdioServer`, `createMcpHttpRouter`, `bootstrapMcpServer`                                                                                                                                       |
 | `./server/otel`    | `otelOnCall`                                                                                                                                                                                                                                    |
@@ -2663,7 +2988,8 @@ bunx @fitzzero/quickdraw-codemod@next v5 .
 | `./utils`          | `createServerCaller`, cache keys (`methodKey`, `entityKey`, `collectionKey`), formatting, navigation, `parseJWTPayload`                                                                                                                         |
 | `./parser`         | the JSON-only Socket.IO parser                                                                                                                                                                                                                  |
 | `./testing`        | `createTestApp`, `describeAccessMatrix`, `expectBudget`, `createRecordingSink`, `DevWarningError`                                                                                                                                               |
-| `./testing/client` | `renderWithQuickdraw`, `createMockClient`                                                                                                                                                                                                       |
+| `./testing/client` | `renderWithQuickdraw`, and everything in `./testing/mock`                                                                                                                                                                                       |
+| `./testing/mock`   | `createMockClient` alone, without Testing Library: for browser bundles such as Storybook                                                                                                                                                        |
 | `./testing/prisma` | test databases on PostgreSQL or PGlite                                                                                                                                                                                                          |
 
 The package also ships the `quickdraw-docs` command.
@@ -2672,7 +2998,7 @@ The package also ships the `quickdraw-docs` command.
 
 A bun workspace with turbo: `packages/core` (this package), `packages/lint`,
 `packages/skills` and `packages/codemod`. See
-[CONTRIBUTING.md](../../CONTRIBUTING.md).
+[CONTRIBUTING.md](https://github.com/fitzzero/quickdraw/blob/dev/CONTRIBUTING.md).
 
 ```bash
 bun install