reflectdb 0.1.0 → 0.1.2

package/README.md

@@ -23,6 +23,7 @@ You bring your own types and your own database. reflectdb handles the protocol,
 
 ## Table of Contents
 
+- [Demos](#demos)
 - [Why reflectdb](#why-reflectdb)
 - [Features](#features)
 - [Use Cases](#use-cases)
@@ -36,12 +37,16 @@ You bring your own types and your own database. reflectdb handles the protocol,
   - [Custom conflict resolvers](#custom-conflict-resolvers)
   - [Validating client payloads](#validating-client-payloads)
   - [Ephemeral messages (cursors, presence, typing)](#ephemeral-messages-cursors-presence-typing)
+  - [Typed presence](#typed-presence)
   - [Per-user query results](#per-user-query-results)
+  - [Read-only views](#read-only-views)
   - [Server-driven game loops](#server-driven-game-loops)
+  - [Transactional writes with `server.tx`](#transactional-writes-with-servertx)
   - [Windowed sync and pagination](#windowed-sync-and-pagination)
   - [Auto-generated REST API](#auto-generated-rest-api)
   - [High availability with Postgres](#high-availability-with-postgres)
 - [Whiteboard + Pictionary example](#whiteboard--pictionary-example)
+- [Infinite Tetris example](#infinite-tetris-example)
 - [Architecture](#architecture)
 - [Core Concepts](#core-concepts)
   - [Hybrid Logical Clocks](#hybrid-logical-clocks)
@@ -59,6 +64,8 @@ You bring your own types and your own database. reflectdb handles the protocol,
   - [`reflectdb/transport/*`](#reflectdbtransport)
 - [Configuration Reference](#configuration-reference)
   - [Query definition](#query-definition)
+  - [View definition](#view-definition)
+  - [Presence definition](#presence-definition)
   - [Server configuration](#server-configuration)
   - [`implement()` options](#implement-options)
   - [Rate limiting](#rate-limiting)
@@ -69,6 +76,17 @@ You bring your own types and your own database. reflectdb handles the protocol,
 - [Development](#development)
 - [License](#license)
 
+## Demos
+
+| Demo | Try it | What it demonstrates |
+|------|--------|----------------------|
+| **Infinite multiplayer Tetris** | [Play live](https://reflectdb-tetris.fly.dev/) · [source](./examples/tetris/) | Optimistic input prediction, server reconciliation and gravity, a live leaderboard, per-player progression, and Bun SQLite persistence in one perpetual game. Open two tabs to add another player. |
+| **Collaborative whiteboard** | [Draw live](https://reflectdb-whiteboard.fly.dev/) · [source](./examples/whiteboard/) | Freeform drawing by default, optional Pictionary rounds, guest-authenticated rooms, ephemeral cursors, chat, presence, and per-user query results. Rooms and everything in them are deleted 30 minutes after they are created. Open two tabs to draw with yourself. |
+
+Both demos run on one auto-stopping Fly Machine with no volume, so the first load
+after an idle period may take a moment. Their data is intentionally ephemeral
+across deployments and Machine replacement.
+
 ## Why reflectdb
 
 Most real-time sync libraries force you to choose: CRDTs (powerful but opaque), or simple pub/sub (fast but brittle). reflectdb sits in the middle — **per-row operations** with **hybrid logical clocks** for causal ordering, validated through a server-side pipeline so your database stays authoritative.
@@ -108,8 +126,11 @@ Optional bits (use what you want):
 - **Op log compaction** — configurable retention for old accepted ops
 - **High availability** — shared Postgres + optional cross-instance polling
 - **Framework bindings** — React hooks, Svelte stores, and a vanilla-JS helper; the core client works anywhere
-- **Ephemeral channels** — presence, cursors, typing indicators that never touch the op log
+- **Ephemeral channels** — presence, cursors, typing indicators that never touch the op log, with a room snapshot on join and a pluggable adapter (Redis included) so presence spans a fleet
+- **Typed presence** — `presence()` in the schema, `usePresence()` in the component, key derived for you
+- **Read-only views** — `view()` entries that recompute on their dependencies and reject writes at both levels
 - **Windowed sync** — paginate large tables with `loadMore` + `useTotalCount`
+- **Server-side toolkit** — `tx` (transaction + auto-notify), `lock` / `tryLock`, and self-disposing `interval` / `timeout`
 
 ## Use Cases
 
@@ -268,7 +289,7 @@ Open two tabs — edits in one appear in the other within a round-trip. Close th
 
 ## Recipes
 
-The repo ships one end-to-end example — [`examples/whiteboard/`](./examples/whiteboard/) — a collaborative drawing app with two modes (freeform and **Pictionary**). It exercises the patterns below in one place. The snippets here are minimal, copy-paste-friendly references; see the example for how they fit together.
+The repo ships two end-to-end examples: [`examples/whiteboard/`](./examples/whiteboard/), a collaborative drawing app with two modes (freeform and **Pictionary**), and [`examples/tetris/`](./examples/tetris/), one perpetual Tetris game with no player cap. Between them they exercise the patterns below in one place. The snippets here are minimal, copy-paste-friendly references; see the examples for how they fit together.
 
 ### WebSocket sync with SQLite + Drizzle
 
@@ -364,12 +385,17 @@ For multi-tenant apps, use `room()` to pin a client to a subset of data:
 ```ts
 server.room("org/:orgId", async ({ params, auth }) => {
   if (!auth.memberships.includes(params.orgId)) {
-    throw new Error("not a member of this org");
+    return { ok: false, reason: "not a member of this org" };
   }
-  return { scope: { orgId: params.orgId } };
+  // return nothing (or `{ ok: true }`) to allow the subscription
 });
 ```
 
+Room keys are resolved from the subscription's params and fail closed: params that
+address a pattern only partially, or that produce a key the pattern can't match, are
+rejected rather than falling back to an unscoped, cross-room subscription. Set
+`room` in `implement()` to require a specific pattern for a query.
+
 The whiteboard example wires this up with [better-auth](https://better-auth.com) — see [`examples/whiteboard/auth.ts`](./examples/whiteboard/auth.ts).
 
 ### Per-column merge for collaborative editing
@@ -483,8 +509,84 @@ broadcast({ x: e.clientX, y: e.clientY });
 Object.values(events).map((c) => <Cursor x={c.x} y={c.y} />);
 ```
 
+Fan-out follows the sender's **query subscriptions**: recipients are the clients
+subscribed to the same queries, narrowed to the sender's room when one is resolved. A
+client that has called no `sync()` yet has no audience, so its ephemeral messages reach
+nobody. The `userId` on the wire is always the authenticated one — the client-supplied
+value is ignored — and a client-supplied `ttlMs` is clamped server-side.
+
+Subscribing to a room also delivers a **snapshot** of that room's live ephemeral
+state, so a client that joins mid-session sees the peers already there instead of
+waiting for each one to move again. Snapshots arrive as ordinary `ephemeral` events
+and exclude the joiner's own entries.
+
+By default this state lives in the server process, which is correct on one node
+and invisible across a fleet — two clients on different instances never see each
+other. Point `ephemeral.adapter` at shared infrastructure to fix both halves; see
+[Ephemeral (presence)](#ephemeral-presence).
+
 The whiteboard renders peer cursors this way — see [`examples/whiteboard/app.tsx`](./examples/whiteboard/app.tsx).
 
+### Typed presence
+
+`presence()` is `useEphemeral` with the shape declared in the schema instead of at the
+call site. The channel key is derived from the entry name plus its serialized params, so
+two components watching the same presence entry always agree on the key.
+
+```ts
+// schema.ts
+import { defineSyncQueries, presence, t } from "reflectdb/core";
+
+export const queries = defineSyncQueries({
+  cursor: presence({
+    state: t<{ x: number; y: number; name: string }>(),
+    params: t<{ gameId: string }>(),   // part of the derived key
+    ttlMs: 10_000,
+  }),
+});
+```
+
+```tsx
+// app.tsx — usePresence comes from the typed factory, not the bare import
+import { createSyncReact } from "reflectdb/react";
+import { queries } from "./schema";
+
+export const { SyncProvider, useSync, usePresence } = createSyncReact(queries);
+
+function Cursors({ gameId }: { gameId: string }) {
+  const { peers, set } = usePresence("cursor", { gameId });
+  //      ^? { userId: string; state: { x, y, name } }[]
+
+  useEffect(() => {
+    const onMove = (e: PointerEvent) =>
+      set({ x: e.clientX, y: e.clientY, name: myName });
+    window.addEventListener("pointermove", onMove);
+    return () => window.removeEventListener("pointermove", onMove);
+  }, [set]);
+
+  return peers.map((p) => <Cursor key={p.userId} {...p.state} />);
+}
+```
+
+Details worth knowing:
+
+- **No server registration.** Presence entries are not queries — there is no
+  `server.implement`/`server.view` for them. They ride the same ephemeral channel and
+  are room-scoped by the sender's active subscriptions.
+- **`peers` excludes you.** Ephemeral events are only delivered to *other* clients, so
+  render your own cursor from local state.
+- **Peers are keyed by connection, not by account.** Presence entries are keyed by
+  `clientId` end to end — on the wire, in the server's store, and in `peers` — so two
+  tabs from one login are two peers with two cursors. Put the display identity in
+  `state` (as `name` above) if you need it; the authenticated `userId` rides along on
+  every event for authorization and display.
+- **Params are required when declared**, exactly like `useSync` — `usePresence("cursor")`
+  fails to compile if the entry declares params.
+- **React only.** `createSyncSvelte` / `createSyncVanilla` have no presence helper; use
+  `sync.sendEphemeral` / `sync.onEphemeral` (or the store's `ephemeral()`) with your own
+  key there. `derivePresenceKey(name, params)` is exported from `reflectdb/react` if you
+  want to interoperate with the same channel by hand.
+
 ### Per-user query results
 
 A `query` callback is just a function — it can return different rows depending on the caller's `auth`. reflectdb re-runs it whenever the listed `tables` change, so each subscriber gets a personalized view that stays live.
@@ -516,24 +618,152 @@ server.implement("roundWord", {
 
 The `game_secrets` table isn't registered in `defineSyncQueries`, so it's never broadcast directly. Calling `server.notifyChange("game_secrets")` from the engine fans out the recomputed `roundWord` result to whichever client is now the drawer.
 
+### Read-only views
+
+The recipe above is a query that happens to reject writes. `view()` makes that the
+declaration: the entry has no `mutate`, `useSync(...)` returns only `{ rows, loading }`,
+and a write that reaches the server anyway is rejected with `readonly_query`.
+
+```ts
+// schema.ts
+import { defineSyncQueries, view, t } from "reflectdb/core";
+
+export const queries = defineSyncQueries({
+  leaderboard: view({
+    row: t<{ id: string; name: string; points: number }>(),
+    params: t<{ gameId: string }>(),
+    deps: ["games", "scores"],   // re-run when either table changes
+  }),
+});
+```
+
+```ts
+// server.ts — server.view, not server.implement
+server.view("leaderboard", (ctx, db) =>
+  db.select().from(scores)
+    .where(eq(scores.gameId, ctx.params.gameId))
+    .orderBy(desc(scores.points))
+    .limit(10));
+```
+
+```tsx
+// app.tsx
+const { rows } = useSync("leaderboard", { params: { gameId } });
+// rows: { id, name, points }[] — there is no .insert / .update / .remove here
+```
+
+Notes:
+
+- **`deps` drives change detection**, falling back to `tables` and then to the entry
+  name. A view over tables it doesn't share a name with must declare them, or it never
+  re-broadcasts.
+- **`implement()` and `view()` are not interchangeable.** Calling `server.implement` on a
+  name declared as a view throws, and so does `server.view` on a name that isn't one.
+- **`server.view(name, fn)` takes no options** — only the callback and the schema's
+  dependency list. There is no `authorize`, `room`, `groupBy`, `count`/`countHints` or
+  `pk` on a view. Do access control inside the callback (it gets `ctx.auth` and
+  `ctx.params`), and fall back to a regular `implement()` with a throwing `mutate` when
+  you need those knobs.
+- **Rows need an `id`.** The primary key isn't configurable for views, so give each row a
+  stable `id` — that's what delta diffing keys on. Computed rows can synthesize one.
+- **The type-level block is React-only.** `createSyncSvelte` / `createSyncVanilla` don't
+  narrow view entries, so a write there compiles and is refused at runtime instead.
+
 ### Server-driven game loops
 
-Some apps need state that advances on a clock, not on user input — round timers, expiring claims, scheduled rotations. Pair a `setInterval` with `notifyChange` and the server stays the single source of truth.
+Some apps need state that advances on a clock, not on user input — round timers, expiring claims, scheduled rotations. Pair `server.interval` with `notifyChange` and the server stays the single source of truth.
 
 ```ts
-setInterval(async () => {
-  const now = Date.now();
-  const active = await db.select().from(games).where(eq(games.mode, "pictionary"));
-  for (const g of active) {
-    if (g.state === "drawing" && now >= g.roundEndsAt) {
-      await endRound(g.id);                  // raw SQL writes
-      await server.notifyChange("games");    // fan-out to subscribers
+server.interval(500, () =>
+  server.lock("tick", async () => {          // a tick must never outrun itself
+    const now = Date.now();
+    const active = await db.select().from(games).where(eq(games.mode, "pictionary"));
+    for (const g of active) {
+      if (g.state === "drawing" && now >= g.roundEndsAt) {
+        await endRound(g.id);                // raw SQL writes
+        await server.notifyChange("games");  // fan-out to subscribers
+      }
     }
-  }
-}, 500);
+  }),
+);
+```
+
+`server.interval(ms, fn)` and `server.timeout(ms, fn)` wrap the globals with three
+differences worth having: a throw or a rejected promise inside `fn` is caught and logged
+instead of taking the process down, the handle is cleared by `server.close()`, and it is
+disposed on `bun --hot` reload — so an edit-save loop doesn't leave a fleet of orphaned
+timers ticking against the same rows. Both return `{ clear() }`.
+
+`server.lock(key, fn)` serializes async work per key: calls queue and run one at a time,
+and a failure in one doesn't poison the queue behind it. `server.tryLock(key, fn)` is the
+skip-if-busy variant — it returns `null` immediately when the key is held, which is
+usually what you want for a tick that would otherwise pile up.
+
+```ts
+const result = await server.tryLock(`game:${gameId}`, () => scoreRound(gameId));
+if (result === null) return;   // another call is already scoring this game
 ```
 
-Pair with a per-row mutex if a tick can outrun its interval. The whiteboard example does both — see [`examples/whiteboard/server.tsx`](./examples/whiteboard/server.tsx).
+Both are in-process only. Across instances, keep the guard in the database (a
+conditional `UPDATE … WHERE state = 'drawing'` that returns rows-affected) — the lock
+protects a single Node/Bun process, not a cluster. The whiteboard example uses both —
+see [`examples/whiteboard/server.tsx`](./examples/whiteboard/server.tsx).
+
+### Transactional writes with `server.tx`
+
+`notifyChange` per table gets tedious the moment one logical action touches three of
+them. `server.tx` runs the work, tracks which tables it wrote, and fires one
+`notifyChange` per touched table — only if the whole function succeeded.
+
+```ts
+await server.tx(async (tx) => {
+  await tx.update(games).set({ state: "scoring" }).where(eq(games.id, gameId));
+  await tx.insert(scores).values(rows);
+  await tx.delete(guesses).where(eq(guesses.gameId, gameId));
+});
+// → games, scores and guesses each broadcast once, after COMMIT
+```
+
+- **Atomic by default.** `atomic: true` is the default: the body runs inside
+  `BEGIN`/`COMMIT` and rolls back on throw. It resolves an adapter from
+  `ServerConfig.txAtomic`, falling back to a bundled Drizzle adapter (lazy-loaded, so
+  there's no top-level `drizzle-orm` dependency). With neither available it throws —
+  pass `atomic: false` for a non-transactional group, or supply your own adapter with
+  `server.tx({ atomic: myAdapter }, fn)`.
+- **Table tracking is automatic for Drizzle only.** The proxy watches
+  `insert` / `update` / `delete` (`select` is not a write, so it doesn't count). On
+  Kysely, Prisma or raw SQL, call `tx.touch("games")` after each write.
+- **Notifies never fire on a throw**, transactional or not.
+- **Pooled connections need care.** `BEGIN`/`COMMIT` and the writes must share one
+  connection, so pass a single-connection handle when atomicity is load-bearing rather
+  than a pool.
+
+For a single row there is `server.emit(table, payload)`. It generates a rowId, stamps an
+HLC, writes reflectdb's mirror plus the op-log entry, and broadcasts:
+
+```ts
+const { rowId, hlc } = await server.emit("todos", { title: "filed by a cron", done: false });
+await server.emit("todos", { done: true }, { rowId, type: "update" });
+```
+
+It does **not** call your `implement`'s `mutate`, so it does not write your database.
+That makes it the right tool when reflectdb's own store is what your `query` reads, and
+the wrong one when your database is — a broadcast re-runs the query, so a row your
+database never received simply won't appear. When your write has to happen under the
+same stamp, use the primitive `emit` and `server.rest()` are both built on:
+
+```ts
+await server.applyServerOp(
+  { type: "insert", table: "todos", rowId, payload },
+  async (stamped) => {                       // runs before the mirror write
+    await db.insert(todos).values({ id: stamped.rowId, ...stamped.payload });
+  },
+  { roomKey: `org/${orgId}` },               // keep the fanout inside the tenant
+);
+```
+
+A throw inside `execute` aborts before anything touches the mirror or the op log. Omit
+`roomKey` and the broadcast reaches every subscriber of the affected query, across rooms.
 
 ### Windowed sync and pagination
 
@@ -632,7 +862,9 @@ Each poll tick first probes the shared op log's head HLC; an idle tick costs one
 
 ## Whiteboard + Pictionary example
 
-A complete React + Bun + Drizzle app that exercises most of reflectdb in one place: [`examples/whiteboard/`](./examples/whiteboard/).
+A complete React + Bun + Drizzle app that exercises most of reflectdb in one
+place: [`examples/whiteboard/`](./examples/whiteboard/). It is deployed at
+[reflectdb-whiteboard.fly.dev](https://reflectdb-whiteboard.fly.dev/).
 
 ```bash
 cd examples/whiteboard
@@ -646,13 +878,17 @@ Two modes:
 - **Freeform draw** — every player can draw on a shared canvas. Strokes are LWW per row.
 - **Pictionary** — players take turns drawing while the others guess in chat. The server picks a word, runs a per-round timer, awards points based on remaining time, advances the drawer, and ends the game after N full rotations.
 
+Rooms are ephemeral: 30 minutes after a room is created, a server-side sweep
+deletes it together with every stroke, chat line, player row and round secret
+belonging to it. Both tabs bounce back to the lobby when it happens.
+
 What it demonstrates:
 
 | Pattern | Where |
 |---------|-------|
 | Drizzle-typed schema, SQLite op log | [`schema.ts`](./examples/whiteboard/schema.ts) |
 | WebSocket transport on Bun | [`server.tsx`](./examples/whiteboard/server.tsx) |
-| Authentication via better-auth (email/password + anonymous) | [`auth.ts`](./examples/whiteboard/auth.ts) |
+| Guest-only authentication via better-auth's anonymous plugin | [`auth.ts`](./examples/whiteboard/auth.ts) |
 | `params`-scoped queries (`strokes`, `messages` per game) | [`server.tsx`](./examples/whiteboard/server.tsx) |
 | Per-user query results — only the drawer receives the secret word | `roundWord` in [`server.tsx`](./examples/whiteboard/server.tsx) |
 | Server-side game loop with a mutex + `notifyChange` | `tick`, `withLock` in [`server.tsx`](./examples/whiteboard/server.tsx) |
@@ -660,6 +896,40 @@ What it demonstrates:
 | `readonly` field enforcement to keep the engine state out of client hands | [`schema.ts`](./examples/whiteboard/schema.ts) |
 | Ephemeral cursors per game, scoped via `key: \`cursor:${gameId}\`` | [`app.tsx`](./examples/whiteboard/app.tsx) |
 | Per-table rate limiting (loose for strokes, tight for chat) | `server.rateLimit` in [`server.tsx`](./examples/whiteboard/server.tsx) |
+| TTL sweep deleting whole rooms and their content out of band, with `notifyChange` turning it into client deletes | `sweepExpiredRooms` in [`schema.ts`](./examples/whiteboard/schema.ts) |
+| One-Machine Fly.io deployment, prebuilt bundle and env-driven config | [`Dockerfile`](./examples/whiteboard/Dockerfile) / [`fly.toml`](./examples/whiteboard/fly.toml) / [`config.ts`](./examples/whiteboard/config.ts) |
+
+The included Fly.io config runs on one auto-stopping 512 MB Machine; deploying
+your own copy takes two commands, both covered in
+[`examples/whiteboard/README.md`](./examples/whiteboard/README.md).
+
+## Infinite Tetris example
+
+One ongoing Tetris game with no player cap: [`examples/tetris/`](./examples/tetris/).
+Every visitor gets a live 10×20 well and a random server-assigned name. Players join
+and leave without rounds or rooms; top out and that player's score resets to zero
+before a fresh run begins immediately.
+
+```bash
+cd examples/tetris
+bun install
+bun dev
+# open http://localhost:3004 in two tabs — each tab is a player
+```
+
+Bun SQLite stores the authoritative wells and reflectdb sync log in one WAL
+database. The included Fly.io config runs on one auto-stopping 256 MB Machine.
+
+| Pattern | Where |
+|---------|-------|
+| Server-authoritative gravity — `server.interval` + `server.tryLock` | [`server.tsx`](./examples/tetris/server.tsx) |
+| `groupBy` — one query execution for the global game instead of one per player | `players` in [`server.tsx`](./examples/tetris/server.tsx) |
+| `serverSet` refreshing the player heartbeat | `players` in [`server.tsx`](./examples/tetris/server.tsx) |
+| Read-only board, piece, random name, and score fields | [`schema.ts`](./examples/tetris/schema.ts) |
+| Row ownership enforced with `MutationError` | `players.mutate` in [`server.tsx`](./examples/tetris/server.tsx) |
+| `view()` leaderboard, recomputed from `players` | `standings` in [`server.tsx`](./examples/tetris/server.tsx) |
+| Headless game rules and top-out reset tests | [`game.ts`](./examples/tetris/game.ts) / [`game.test.ts`](./examples/tetris/game.test.ts) |
+| Bun SQLite persistence and restart tests | [`database.ts`](./examples/tetris/database.ts) / [`database.test.ts`](./examples/tetris/database.test.ts) |
 
 ## Architecture
 
@@ -684,21 +954,22 @@ What it demonstrates:
 │                                   │  │                                      │
 │  createSyncServer<TQueries>()     │  │  createSyncClient<TQueries>()        │
 │   ├─ .implement(name, opts)       │  │   ├─ .sync(name, params?)            │
-│   ├─ .auth(token → AuthContext)   │  │   ├─ .insert/.update/.delete         │
-│   ├─ .room(pattern, cb)           │  │   ├─ .subscribe / .subscribeTable    │
-│   ├─ .rateLimit({...})            │  │   ├─ .getRows / .getRow / .getState  │
-│   ├─ .compaction({...})           │  │   ├─ .loadMore / .getTotalCount      │
+│   ├─ .view(name, fn)              │  │   ├─ .insert/.update/.delete         │
+│   ├─ .auth(token → AuthContext)   │  │   ├─ .subscribe / .subscribeTable    │
+│   ├─ .room(pattern, cb)           │  │   ├─ .getRows / .getRow / .getState  │
+│   ├─ .rateLimit / .compaction     │  │   ├─ .loadMore / .getTotalCount      │
 │   ├─ .rest({ prefix })            │  │   └─ .sendEphemeral / .subscribeEph. │
-│   ├─ .notifyChange(table)         │  │                                      │
-│   └─ .close()                     │  │  Internal:                           │
+│   ├─ .notifyChange / .emit / .tx  │  │                                      │
+│   ├─ .lock / .interval / .timeout │  │  Internal:                           │
+│   └─ .close()                     │  │                                      │
 │                                   │  │   • SyncClient (state machine)       │
 │  Pipeline (per op):               │  │   • ClientStore (row cache + queue)  │
 │   1. clock drift check            │  │   • OpCreator (HLC stamping)         │
 │   2. rate limit (fail-open)       │  │                                      │
 │   3. batch-size check             │  │  State machine:                      │
-│   4. readonly enforcement         │  │   hydrating → disconnected → …       │
-│   5. serverSet injection          │  │   connecting → bootstrapping → synced│
-│   6. conflict resolution*         │  │                                      │
+│   4. readonly enforcement         │  │   hydrating → disconnected →         │
+│   5. serverSet injection          │  │   connecting → connected →           │
+│   6. conflict resolution*         │  │   bootstrapping → synced             │
 │                                   │  │  Storage adapters:                   │
 │   (* skipped by eager modes)      │  │   • memory (ephemeral)               │
 │                                   │  │   • indexeddb (persistent)           │
@@ -789,7 +1060,9 @@ Both eager broadcast modes skip conflict resolution entirely — writes land las
 3.  client ──▶ ops (optimistic)   server runs pipeline
 4.                                server ──▶ ack / reject
 5.                                server ──▶ delta (broadcast to subscribers)
-6.  client reconnects ──▶ resume (watermark HLC)   server ──▶ missed deltas
+6.  client reconnects ──▶ resume (watermark HLC)
+7.                                server ──▶ snapshot per changed query,
+                                              then resume_complete
 ```
 
 All messages are JSON; the transport is just a pipe. WebSocket gives bi-directional real-time; SSE gives server-push with POST for upstream; polling is stateless HTTP for constrained environments.
@@ -812,9 +1085,20 @@ A write therefore lands in two places: your `mutate` callback commits to your da
 
 ### The Op Log and Resume
 
-Every accepted mutation is appended to the server's op log with its HLC. On reconnect, the client sends its last seen HLC as a watermark, and the server replays only what the client missed. This makes cross-server failover automatic when the log is shared (Postgres).
+Every accepted mutation is appended to the server's op log with its HLC. On reconnect, the client sends its last seen HLC as a watermark.
+
+The server does **not** replay those ops to the client. It asks the log a single question — *which tables changed since this HLC* — and then re-executes the subscribed queries that depend on those tables, sending each result as a fresh `snapshot`, followed by `resume_complete`.
+
+Re-running the query is what keeps resume honest: the client's own `auth`, params and room scoping are applied to what comes back, exactly as they were at bootstrap. A raw op replay would hand back rows the query itself would have filtered out.
 
-Old ops are compacted on a schedule based on client inactivity and minimum op age. Reconnecting clients whose watermark has been compacted receive a fresh bootstrap.
+Two details worth knowing:
+
+- When at least one table has moved, queries depending on none of them are skipped. With no op log configured — or if the log lookup fails — every subscribed query re-runs instead.
+- Adapters that implement `getChangedTablesSince` answer with just the distinct table names. Without it, the handler falls back to `getOpsSince` and reads the op rows only to collect those names, which is unbounded work for a client that has been away a long time.
+
+Because the watermark is only an HLC and the log is the only shared state, cross-server failover is automatic when that log is shared (Postgres) — any instance can answer the question.
+
+Old ops are compacted on a schedule based on client inactivity and minimum op age. A client whose watermark is older than the compaction cutoff gets `resume_rejected` with `reason: "compacted"` and falls back to a fresh bootstrap.
 
 ## API Reference
 
@@ -822,7 +1106,7 @@ Old ops are compacted on a schedule based on client inactivity and minimum op ag
 
 ```ts
 import {
-  defineSyncQueries, t,
+  defineSyncQueries, t, view, presence,
   createHlc, sendHlc, receiveHlc, packHlc, unpackHlc, compareHlc,
   MutationError, TransportSendError, isErrorReason, reasonFromError,
   PROTOCOL_VERSION, MAX_CLOCK_DRIFT_MS, MAX_BATCH_SIZE,
@@ -834,13 +1118,15 @@ import {
 |--------|-------------|
 | `defineSyncQueries(map)` | Identity function that pins your schema's literal types. Feed its result to both server and client. |
 | `t<T>()` | Phantom helper to declare a row or params type. Returns `undefined as T`. |
+| `view({ row?, params?, deps?, tables? })` | Declare a read-only computed query. Registered with `server.view()`; writes are blocked at the type level and rejected at runtime. See [Read-only views](#read-only-views). |
+| `presence({ state?, params?, ttlMs? })` | Declare a typed ephemeral channel. Read with `usePresence()` from `createSyncReact`. See [Typed presence](#typed-presence). |
 | `createHlc(nodeId)` / `sendHlc` / `receiveHlc` | HLC constructors and transitions. |
 | `packHlc` / `unpackHlc` / `compareHlc` | Serialize, deserialize, compare HLC values. |
 | `MutationError(reason, message?)` | Throw from `mutate`/`authorize` to reject a write with a specific `ErrorReason`. |
 | `TransportSendError(clientId, message)` | Throw from a custom `ServerTransport.send` when a frame did not reach the peer. |
 | `isErrorReason(v)` / `reasonFromError(e)` | Validate / extract an `ErrorReason`. |
 
-Types: `HLC`, `SyncOp`, `OpType`, `OpStatus`, `ClientMessage`, `ServerMessage`, `ErrorReason`, `ConflictPolicy`, `ConflictResolver`, `SyncQueryDef`, `InferRow`, `InferParams`, `InferWritableRow`, `RequiresParams`, `RateLimitConfig`, `CompactionConfig`, `ShapeConfig`, `AuthContext`, `DrizzleTableLike`.
+Types: `HLC`, `SyncOp`, `OpType`, `OpStatus`, `ClientMessage`, `ServerMessage`, `ErrorReason`, `ConflictPolicy`, `ConflictResolver`, `SyncQueryDef`, `SyncViewDef`, `SyncPresenceDef`, `SyncQueryEntry`, `SyncQueryMap`, `InferRow`, `InferState`, `InferParams`, `InferWritableRow`, `RequiresParams`, `RateLimitConfig`, `CompactionConfig`, `ShapeConfig`, `AuthContext`, `DrizzleTableLike`.
 
 ### `reflectdb/server`
 
@@ -858,16 +1144,27 @@ import {
 
 | Method | Purpose |
 |--------|---------|
-| `.implement(name, options)` | Register a query handler (required for every query in the schema). |
+| `.implement(name, options)` | Register a query handler (required for every regular query in the schema). |
+| `.view(name, fn)` | Register a read-only query declared with `view()`. No `mutate`; writes reject with `readonly_query`. |
 | `.auth(callback)` | Validate the connection request and return an `AuthContext`. |
-| `.room(pattern, callback)` | Scope clients to a subset of data, matched against URL-style patterns (`org/:orgId`). |
+| `.room(pattern, callback)` | Scope clients to a subset of data, matched against URL-style patterns (`org/:orgId`). Return `{ ok: false, reason }` to deny. |
 | `.rateLimit(config)` | Set per-user/per-table limits. Fail-open on limiter errors. |
 | `.compaction(config)` | Configure op-log compaction. |
 | `.rest({ prefix })` | Generate a CRUD fetch handler. |
 | `.minSchemaVersion(n)` | Reject clients on older schema versions. |
-| `.notifyChange(table)` | Manually trigger a broadcast (for external writes). |
+| `.notifyChange(table, roomKey?)` | Manually trigger a broadcast (for external writes). |
+| `.emit(table, payload, opts?)` | Server-origin row write: stamps an HLC, writes the mirror + op log, broadcasts. Does not call your `mutate`. Returns `{ hlc, rowId }`. |
+| `.applyServerOp(op, execute?, opts?)` | The primitive behind `emit` and `rest`. Hands the stamped HLC to `execute` before the mirror write; a throw aborts both. |
+| `.tx(fn)` / `.tx(opts, fn)` | Run a write group in a transaction (`atomic: true` by default), tracking touched tables and firing one `notifyChange` each on success. |
+| `.lock(key, fn)` | Serialize async work per key. `.tryLock(key, fn)` returns `null` instead of queueing when the key is held. |
+| `.interval(ms, fn)` / `.timeout(ms, fn)` | Timers that log instead of crashing on a throw, and auto-dispose on `close()` and `bun --hot` reload. Return `{ clear() }`. |
+| `.reserveOpId(id)` | Idempotency gate — `true` when the id is fresh. Used to dedupe REST retries. |
 | `.runCompaction()` | Manually run one compaction pass. |
-| `.close()` | Shut down, disconnect clients, close storage. |
+| `.close()` | Shut down, disconnect clients, clear timers, close storage. |
+
+See [Server-driven game loops](#server-driven-game-loops) for `interval` / `lock`, and
+[Transactional writes with `server.tx`](#transactional-writes-with-servertx) for `tx`,
+`emit` and `applyServerOp`.
 
 `createServer()` is the lower-level untyped variant — use it only if you need to register queries dynamically or don't have a `defineSyncQueries` map.
 
@@ -897,7 +1194,7 @@ import { createIndexedDBStorage } from "reflectdb/client/storage/indexeddb";
 | Windowing | `loadMore(name, count)`, `getTotalCount(name)` |
 | Ephemeral | `sendEphemeral({ key, userId, data, ttlMs? })`, `subscribeEphemeral(key, listener)` |
 
-State machine: `hydrating → disconnected → connecting → bootstrapping → synced`. Reconnects with exponential backoff (capped by `maxReconnectDelayMs`, default 30s).
+State machine: `hydrating → disconnected → connecting → connected → bootstrapping → synced`. Reconnects with exponential backoff (capped by `maxReconnectDelayMs`, default 30s).
 
 ### `reflectdb/react`
 
@@ -907,7 +1204,7 @@ import {
   useSync, useSyncStatus, useRow,
   usePendingCount, useEphemeral,
   useTotalCount, useLoadMore,
-  createSyncReact,
+  createSyncReact, derivePresenceKey,
 } from "reflectdb/react";
 ```
 
@@ -928,14 +1225,23 @@ import {
 | Hook | Returns |
 |------|---------|
 | `useSync(table, options?)` | `{ rows, insert, update, remove, loading }` — options: `{ params?, includeDeleted?, window? }` |
-| `useSyncStatus()` | `"hydrating" \| "disconnected" \| "connecting" \| "bootstrapping" \| "synced"` |
+| `useSyncStatus()` | `"hydrating" \| "disconnected" \| "connecting" \| "connected" \| "bootstrapping" \| "synced"` |
 | `useRow(table, id)` | Single row or `null` |
 | `usePendingCount()` | Total unsynced op count |
 | `useEphemeral({ key, userId, ttlMs? })` | `{ events, broadcast }` |
 | `useTotalCount(table)` | Server-side count (requires `countHints: true`) |
 | `useLoadMore(table)` | Function to expand the sync window |
 
-**`createSyncReact<TQueries>()`** returns the same hook set with row and param types inferred from your schema.
+**`createSyncReact<TQueries>(queries)`** returns the same hook set with row and param
+types inferred from your schema, plus two things the bare hooks can't provide:
+
+| Hook | Returns |
+|------|---------|
+| `usePresence(name, params?)` | `{ peers, set }` for a `presence()` entry — `peers` is `{ userId, state }[]`, typed by the schema, and excludes you. Params are required when the entry declares them. |
+| `useSync(viewName)` | `{ rows, loading }` for a `view()` entry — the mutators are absent from the type *and* stripped at runtime. |
+
+`derivePresenceKey(name, params)` produces the same channel key `usePresence` uses, for
+interoperating with `useEphemeral` or a non-React binding by hand.
 
 ### `reflectdb/svelte`
 
@@ -1021,6 +1327,50 @@ Every entry in `defineSyncQueries({ ... })`:
 
 `conflict` resolves the incoming op against **reflectdb's mirror** (its own JSONB row store and per-column clocks), not against your database. The two agree as long as every write goes through reflectdb and `mutate` persists the resolved payload verbatim — see [Two stores, one sync](#two-stores-one-sync).
 
+A schema entry can also be a **view** or a **presence** channel instead of a regular
+query. All three live in the same `defineSyncQueries({ ... })` map:
+
+```ts
+import { defineSyncQueries, t, view, presence } from "reflectdb/core";
+
+export const queries = defineSyncQueries({
+  todos:       { row: t<Todo>(), conflict: "lww" },  // regular  → server.implement()
+  leaderboard: view({ row: t<Score>(), deps: ["scores"] }),   // → server.view()
+  cursor:      presence({ state: t<{ x: number; y: number }>() }),  // → no server call
+});
+```
+
+### View definition
+
+```ts
+view({
+  row: t<MyRow>(),               // row type (or omit for Record<string, unknown>)
+  params: t<{ gameId: string }>(),// typed params, same rules as a query
+  deps: ["games", "scores"],     // change-detection tables
+  tables: ["scores"],            // fallback when `deps` is absent
+})
+```
+
+`deps` → `tables` → the entry name, in that order, decides what re-runs the view. Views
+have no `conflict`, `readonly`, `serverSet` or `pk` — they never accept a write.
+Register with [`server.view(name, fn)`](#read-only-views); `server.implement` on a view
+name throws.
+
+### Presence definition
+
+```ts
+presence({
+  state: t<{ x: number; y: number; name: string }>(),  // payload shape
+  params: t<{ gameId: string }>(),                     // folded into the channel key
+  ttlMs: 10_000,                                       // entry expiry; omit for none
+})
+```
+
+Presence entries are ephemeral channels, not queries: there is nothing to register
+server-side, nothing lands in the op log, and the fan-out is scoped by the sender's
+active room. Read them with `usePresence` from `createSyncReact(queries)` — see
+[Typed presence](#typed-presence).
+
 ### Server configuration
 
 ```ts
@@ -1062,6 +1412,13 @@ server.implement("todos", {
 });
 ```
 
+`query` may return whatever your data layer hands back, including live objects
+your own code mutates later — an in-memory store, a game loop, an ORM's tracked
+entities. Change detection snapshots each row when it caches it, so mutating the
+same object in place is still seen as a change. The snapshot is shallow: mutating
+a *nested* object inside a row is not, so treat nested values as immutable
+(replace them rather than editing in place).
+
 `broadcast` modes:
 
 - **`consistent`** (default): run the conflict pipeline, persist, then broadcast by diffing each subscriber's re-executed query result.
@@ -1157,6 +1514,64 @@ At boot the client restores its persisted subscriptions first and hydrates only
 | `createMemoryStorage()` | `reflectdb/client` | Testing, SSR, short sessions |
 | `createIndexedDBStorage({ dbName, version?, migrate? })` | `reflectdb/client/storage/indexeddb` | Production browser apps |
 
+#### Ephemeral (presence)
+
+Presence, cursors and typing indicators are stored separately from the op log —
+they never durably persist, and they have their own adapter.
+
+| Adapter | Import | Best for |
+|---------|--------|----------|
+| _(none)_ | omit `ephemeral` | In-process store; single node |
+| `createRedisEphemeral({ client, subscriber?, prefix? })` | `reflectdb/server/ephemeral/redis` | Multiple instances behind a load balancer |
+
+```ts
+import { createRedisEphemeral } from "reflectdb/server/ephemeral/redis";
+import Redis from "ioredis";
+
+const commands = new Redis(process.env.REDIS_URL!);
+// Subscribe mode blocks ordinary commands, so the bus needs its own connection.
+const bus = new Redis(process.env.REDIS_URL!);
+
+const server = createSyncServer({
+  queries,
+  db,
+  transport,
+  ephemeral: {
+    adapter: createRedisEphemeral({
+      client: commands,
+      subscriber: {
+        subscribe: (channel, onMessage) => {
+          bus.on("message", (c, m) => { if (c === channel) onMessage(m); });
+          return bus.subscribe(channel);
+        },
+      },
+    }),
+  },
+});
+```
+
+`client` needs one method — `call(command, ...args)`, which `ioredis` has natively.
+For node-redis or Bun, wrap it:
+
+```ts
+// node-redis
+{ call: (cmd, ...args) => client.sendCommand([cmd, ...args.map(String)]) }
+// Bun
+{ call: (cmd, ...args) => client.send(cmd, args.map(String)) }
+```
+
+Options: `prefix` (default `reflectdb:eph`), `maxEntries` (default `100_000`,
+fleet-wide), `hashTtlSeconds` (default 24h — a safety net so a crashed instance
+can't strand entries forever). Omit `subscriber` to share state without a live
+bus: peers then appear on join and after a sweep, but not as they move.
+
+`ephemeral.maxEntries` on its own tunes the in-process store's ceiling
+(default `10_000`) without swapping the adapter.
+
+Implement `EphemeralAdapter` (from `reflectdb/server/ephemeral`) to back
+presence with something else. `publish`/`subscribe` are optional — an adapter
+without them is a shared store with no live bus.
+
 ### Transport configuration
 
 #### WebSocket
@@ -1228,6 +1643,51 @@ bun install
 | `bun run verify:exports` | Check the `exports` map against `dist/`, and type-check the emitted declarations without ambient Bun/React globals (run after `build`) |
 | `bun run verify:node` | Install the packed tarball into a throwaway Node project and check every subpath imports, requires, and type-checks there under both export conditions (run after `build`; needs `node` + `npm`) |
 
+### Landing page and social cards
+
+The site at [reflectdb.dev](https://reflectdb.dev) lives in `landing/`:
+
+```bash
+cd landing
+bun install
+bun run dev       # vite dev server
+bun run og        # regenerate the social cards in landing/public
+```
+
+`bun run og` renders every card in `landing/og/` with your local Chrome (set
+`CHROME_PATH` if it lives somewhere unusual) and writes the PNGs the pages
+reference:
+
+| Card | Output | Size | Used by |
+|------|--------|------|---------|
+| `og/index.html` | `public/og.png` | 1200x630 at 2x | reflectdb.dev |
+| `og/tetris.html` | `public/og-tetris.png` | 1200x630 at 2x | the Tetris demo — served from reflectdb.dev, since the Fly Machine sleeps |
+| `og/whiteboard.html` | `public/og-whiteboard.png` | 1200x630 at 2x | the whiteboard demo, served from reflectdb.dev for the same reason |
+| `og/github.html` | `public/og-github.png` | 1280x640 at 2x | this repository's social preview, uploaded by hand under Settings → Social preview |
+
+Edit the HTML, not the PNGs. 1200x630 is the one ratio X, Facebook, LinkedIn,
+Slack, Discord, Telegram, Mastodon and iMessage all unfurl without cropping, and
+each card has to stay under 300 kB or WhatsApp silently downgrades it to a small
+thumbnail — the script renders at the largest scale factor that fits, and fails
+if a card is oversized or the wrong shape.
+
+#### Analytics
+
+The site reports page views to a self-hosted [Umami](https://umami.is) instance,
+and does so only when it is configured to. `landing/vite.config.ts` injects the
+tag into `index.html` at build time from these variables — with the website id
+unset, nothing is injected and the page makes no third-party request, so a local
+dev server or a fork builds and runs untouched:
+
+| Variable | Required | Default | Purpose |
+|----------|----------|---------|---------|
+| `VITE_UMAMI_WEBSITE_ID` | yes, to enable | — | The site's id in Umami. Unset disables analytics entirely. |
+| `VITE_UMAMI_SCRIPT_URL` | no | `https://linesofcode-umami.vercel.app/script.js` | The tracker script, if you host Umami elsewhere. |
+| `VITE_UMAMI_DOMAINS` | no | — | Comma-separated hostnames to count. Set it to `reflectdb.dev` to keep preview deployments and localhost out of the numbers. |
+
+They are read at build time, so changing one in the Vercel project takes effect
+on the next deployment rather than the next request.
+
 ### Project Structure
 
 ```
@@ -1253,7 +1713,7 @@ src/
 - Test: `bun:test`
 - Lint: oxlint
 - Format: oxfmt
-- CI: GitHub Actions (Ubuntu + macOS + Windows)
+- CI: GitHub Actions (Ubuntu + macOS)
 
 ## License