From 614df513a411e13206289ee1c0a5d8c7e8df78c0 Mon Sep 17 00:00:00 2001 From: Seenu K Date: Wed, 12 Aug 2026 20:12:15 +0530 Subject: [PATCH] Describe pagination cursors as opaque The one hand-written sentence about cursors said the cursor is the previous page's last sort value, which is what it used to be. It is now an opaque token the server returns as `nextCursor`, null exactly when the list is exhausted. The generated `docs/reference/*` pages carry the parameter and response shapes and are synced from the engine by CI, so this is the only edit needed here. Co-Authored-By: Claude Opus 5 --- docs/how-it-works/transport.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/how-it-works/transport.md b/docs/how-it-works/transport.md index 0c6370b..edea886 100644 --- a/docs/how-it-works/transport.md +++ b/docs/how-it-works/transport.md @@ -45,9 +45,13 @@ None of it is game code; a game never opens a socket or resolves an identity. older app does not know to `unknownDefaultOpenApi`, so decoding succeeds and the app can request an update. The fallback is read-side only and is never sent back. -- **Lists page by keyset cursor**, not offset: the cursor is the previous page's - last sort value. These lists change while they are being read, and an offset - would show the same row twice after a single insert. +- **Lists page by keyset cursor**, not offset. These lists change while they are + being read, and an offset would show the same row twice after a single insert. + The cursor is opaque: a paged response carries a `nextCursor`, and a client + passes it back untouched rather than deriving it from the last row it holds. + It is null exactly when the list is exhausted, so "is there another page" is + an answer rather than something inferred from a short page. Composing a cursor + is not supported; a malformed one is refused with `invalidCursor`. - **Avatar URLs may be relative.** With the default worker-served setup the server returns `/avatars/{uid}?v=`; with a public bucket domain it returns an absolute URL. `resolveAvatarUrl` resolves either against the API origin, and