@abloatai/ablo 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.63.0
+
+Reactive model clients now expose live awareness beneath the model namespace.
+`usePresence((ablo) => ablo.chats, chatId)` owns the mounted view's read
+activity, refresh, reconnect announcement, and cleanup, and returns the human
+and agent sessions active on that record. Multiple tabs remain distinct
+authenticated sessions.
+
+Transient collaboration now uses `ablo.<model>.events`. Applications can send
+and subscribe to cursor, selection, and similar signals by record id without
+putting routing or caller-authored identity in the payload. Ablo derives the
+record sync group, routes only to other connections in that group, and supplies
+the authenticated participant, presence session, and server timestamp to the
+receiver.
+
+Model events are deliberately lossy: disconnected sends are dropped and
+events are not replayed after reconnect. Persist state that must recover as
+ordinary model data, and throttle high-frequency pointer updates in the
+application. The legacy store-level collaboration-event API remains available
+and now receives optional authenticated context from updated servers.
+
 ## 0.62.0
 
 Every live client now exposes one session-owned `ablo.presence` projection.

package/docs/api.md

@@ -66,6 +66,9 @@ Each schema model becomes a typed model on the client:
 - `ablo.weatherReports.update({ id, data, ...options })` updates a row.
 - `ablo.weatherReports.delete({ id, ...options })` deletes a row.
 - `ablo.weatherReports.claim({ id, description })` acquires a durable write lease; the HTTP form is awaited.
+- `ablo.weatherReports.presence(id)` reads the live session projection for one row on a reactive client.
+- `ablo.weatherReports.events.send(id, name, payload)` sends a transient row-scoped event on a reactive client.
+- `ablo.weatherReports.events.subscribe(id, name, handler)` subscribes to that transient event and returns a disposer.
 
 `local.` narrows a query to what has already synced. `get({ id })`, `read({ id })`, and
 `list({ where })` answer from the local graph and fall back to IndexedDB and
@@ -91,11 +94,48 @@ fallback removed — nothing to await, so they return a value.
 | `claim.queue({ id })` | `Promise<ClaimQueueView>` on HTTP | You need the durable wait line. |
 | `claim.release({ id })` | `Promise<void>` on HTTP | You need to release a claim early. |
 | `claim.reorder({ id, order })` | `Promise<void>` on HTTP | A privileged coordinator needs to reorder the wait line. |
+| `presence(id?)` | `readonly PresenceSession[]` on reactive clients | You need the sessions currently active on a model or row. |
+| `events.send(id, name, payload)` | `void` on reactive clients | You need to send a cursor, selection, or other transient signal. |
+| `events.subscribe(id, name, handler)` | `() => void` on reactive clients | You need transient signals for one row until cleanup. |
 
 `get`, `read`, `list`, `create`, `update`, `delete`, and `claim` go
 through the server. The `local` reads work off the rows a session has already
 synced, so a cheap re-read needs no round-trip.
 
+### Live presence and model events
+
+Presence and events belong to the reactive WebSocket client. They are not on
+the stateless HTTP client used by server-side agents and workers.
+
+Use presence for who is active on a row. In React, `usePresence` also owns the
+mounted component's read activity and cleanup:
+
+```tsx
+const viewers = usePresence((ablo) => ablo.chats, chatId);
+```
+
+Use model events for short-lived UI detail that should not become a database
+field:
+
+```ts
+const stop = ablo.files.events.subscribe(fileId, 'cursor', (cursor, context) => {
+  renderCursor(context.sender.presenceSessionId, cursor);
+});
+
+ablo.files.events.send(fileId, 'cursor', { line: 12, column: 4 });
+stop();
+```
+
+The model and row determine the sync group. Ablo excludes the sending
+connection, validates the wire envelope, and supplies authenticated
+`context.sender` and `context.sentAt`; identity does not belong in the payload.
+Event names are strings and payloads are objects. Payloads are not inferred
+from the schema today.
+
+Delivery is lossy: sending while disconnected is dropped, and events are not
+replayed after reconnect. Cursor and live selection fit this contract. Persist
+anything that must be recovered as ordinary model data.
+
 ## Atomic commits
 
 Use one `ablo.commits.create` when several Ablo model writes must all land or

package/docs/integration-guide.md

@@ -523,6 +523,8 @@ that guarantee as eventual completion with repair—not atomicity.
 | `persistence: 'indexeddb'`                | Durable browser cache that survives reloads, for apps that need it. |
 | `durableWrites: { store, namespace? }`     | Recover unacknowledged worker writes after a process restart.      |
 | `claim` / `claim.state` / `claim.queue`          | Show active work and coordinate before a write.                   |
+| `usePresence` / `<model>.presence`         | Show the human and agent sessions active on a row.                 |
+| `<model>.events`                           | Send lossy row-scoped cursor, selection, and similar UI signals.   |
 | `read` + `reads`                          | Reject writes based on stale state.                               |
 | `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and read tuning.                                  |
 
@@ -546,7 +548,16 @@ them.
 | `delete({ id, ...opts })`              | Delete through the model client.                                                 |
 | `claim.state({ id })`                  | See who is currently working on a row (synchronous).                             |
 | `claim({ id, description?, ttl? })`    | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
+| `presence(id?)`                        | Read live human and agent sessions on a reactive client.                         |
+| `events.send(id, name, payload)`       | Send a transient row-scoped signal; disconnected sends are dropped.              |
+| `events.subscribe(id, name, handler)`  | Listen until its returned disposer is called; events are not replayed.            |
 
 Keep first integrations on the model methods above. Every mutation and
 server-read verb takes one options object; the synchronous `local.get(id)` stays
 positional.
+
+Presence and events require the reactive WebSocket client. Server-side agents
+using the stateless HTTP client still coordinate through reads, claims, and
+writes, but they do not open a cursor/selection event channel. Event payloads
+carry application data only; Ablo derives the model scope and supplies
+authenticated participant context to receivers.

package/docs/options.md

@@ -200,7 +200,23 @@ connection follows, but it cannot widen the authority granted by
 
 ## collaborationEvents
 
-Application-defined WebSocket event names accepted by `subscribe()`.
+Legacy store-level WebSocket event names accepted by `subscribe()`. New React
+and reactive-client code should prefer the record-scoped
+`ablo.<model>.events.send(...)` and `.subscribe(...)` surface. A
+collaboration-event handler receives the application's unchanged payload first
+and optional server-authenticated context second:
+
+```ts
+store.subscribe('document:cursor', (cursor, context) => {
+  context?.sender.presenceSessionId;
+  context?.sender.participant; // { id, kind }
+  context?.sentAt;
+});
+```
+
+The context is optional while connecting to a server version that predates
+authenticated collaboration-event attribution. Never put caller-authored user
+identity in the application payload.
 
 ## cursorStore
 

package/docs/react.md

@@ -39,10 +39,10 @@ export const ablo = Ablo({
 // The typed binding: capture the schema once, and every component imports
 // born-typed hooks from this file — `useAblo()` takes no type arguments,
 // and a selector's `ablo` parameter knows your models.
-export const { AbloProvider, useAblo } = createAbloReact(schema);
+export const { AbloProvider, useAblo, usePresence } = createAbloReact(schema);
 ```
 
-Import `AbloProvider` and `useAblo` from `lib/ablo` rather than from the
+Import `AbloProvider`, `useAblo`, and `usePresence` from `lib/ablo` rather than from the
 package, and the schema generic never appears at a call site again — the
 same one-binding-file convention as tRPC's `createTRPCReact` or
 react-redux's typed hooks.
@@ -188,6 +188,80 @@ imperative work after an event or effect.
 
 See [API reference](/docs/api) for the full options surface.
 
+## usePresence: viewers and active participants
+
+`usePresence` declares that the mounted component is reading one model record
+and returns the live sessions active on that record. Use the selector form with
+the schema-bound hook:
+
+```tsx
+import { usePresence } from '@/lib/ablo';
+
+export function ChatView({ chatId }: { chatId: string }) {
+  const viewers = usePresence((ablo) => ablo.chats, chatId);
+
+  return viewers.map((session) => (
+    <Avatar
+      key={session.presenceSessionId}
+      participantId={session.participant.id}
+      kind={session.participant.kind}
+    />
+  ));
+}
+```
+
+The component chooses the model and record. Ablo owns the authenticated
+session identity, read lease, refresh, reconnect re-announcement, and removal
+on cleanup. Multiple tabs remain separate sessions, and human and agent
+participants use the same result shape. Do not build a separate `chat:view`
+event, heartbeat, or stale-viewer timer in the app.
+
+If you already have the client, the direct model form is equivalent:
+
+```tsx
+const viewers = usePresence(ablo.chats, chatId);
+```
+
+The hook returns the complete matching session projection, including the
+current session. Use `session.participant` for identity and inspect
+`session.activities` when the UI needs to distinguish reading from claiming or
+writing.
+
+## Model events: cursors and selections
+
+Use the `events` namespace already attached to each model for transient UI
+signals. The model and record choose the authorized sync group; the payload
+does not need routing fields or caller-authored identity.
+
+```tsx
+const ablo = useAblo();
+
+useEffect(() => {
+  if (!ablo) return;
+  return ablo.slideDecks.events.subscribe(deckId, 'cursor', (cursor, context) => {
+    drawRemoteCursor(context.sender.presenceSessionId, cursor);
+  });
+}, [ablo, deckId]);
+
+function onPointerMove(x: number, y: number) {
+  ablo?.slideDecks.events.send(deckId, 'cursor', { slideId, x, y });
+}
+```
+
+The same shape works for code editors:
+
+```ts
+ablo.files.events.send(fileId, 'selection', { anchor, head });
+```
+
+Events are lossy and are not replayed after reconnect, which fits cursor and
+live-selection updates. Ablo enters and leaves the record scope with each
+subscription, routes only inside that scope, and delivers authenticated
+`sender` and `sentAt` context separately from the application payload. Use
+durable model fields when state must survive reconnects. The sending connection
+does not receive its own event. Coalesce or throttle pointer movement in the
+application; model events do not currently declare a per-event `maxHz`.
+
 ## usePeers: read-only presence
 
 `usePeers` reads the presence stream already flowing for the client's scoped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -145,8 +145,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.62.0",
-    "@abloatai/transaction": "^0.62.0",
+    "@abloatai/humans": "^0.63.0",
+    "@abloatai/transaction": "^0.63.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {