@abloatai/ablo 0.62.0 → 0.63.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.63.1
+
+React workspaces can render immediately while collaboration connects.
+`useSyncStatus()` now works during provider startup, passthrough children retain
+their state when the provider becomes ready, and replacing a client moves account
+scope and reactive subscriptions to the new client.
+
+The runnable account multiplayer reference combines authenticated people and
+agents, account isolation, presence and claims. Its walkthrough covers client
+disposal, permissions, ownership loss and cleanup, with browser tests for
+competing agents, account switching and data catch-up after reconnect.
+
+The accompanying sync-server update registers HTTP agent presence, preserves
+manually held claims across writes, and reports repeated releases accurately.
+It also adds organization isolation to claim activity evidence. Deploy the
+server update and its database migration to receive these server-side fixes.
+
+## 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/coordination.md

@@ -34,6 +34,30 @@ result rather than reasoning against state that has since moved.
 The important boundary is explicit: a plain update does not claim a row and
 does not carry a stale premise. It is intentionally last-write-wins.
 
+## Claim permissions
+
+Claims coordinate authority already granted by a session; they do not grant it.
+The `can` API has no separate `claim` operation.
+
+| Operation | Required model permission | Authority received |
+|---|---|---|
+| Read / list | `read` | Read authorized rows |
+| Acquire a row or field claim | `update` or `delete` | Coordinate the target, with the corresponding mutation authority |
+| Update through a claim | `update` | Update authorized rows; the claim guards its selected target |
+| Delete through a claim | `delete` | Delete authorized rows |
+
+For example, `can: { conversations: ['read', 'update'] }` permits updates to
+**all fields on authorized conversation rows**, not just `executionOwner`.
+Selecting `fields: fields => fields.executionOwner` narrows coordination,
+not the session's write permission. Omit `delete` and `create` when unnecessary.
+Use a subject rule and server-verified membership to restrict rows. If a worker
+must only change execution state, put that state in a separately authorized
+model or keep mutations behind an application endpoint that validates the patch.
+
+For a process that outlives its starting function, see the runnable
+[account multiplayer ownership lifecycle](./examples/account-multiplayer.md).
+It handles contention, failed initialization, ownership loss and shared cleanup.
+
 ## Explicit read dependencies
 
 Pass the exact rows that produced a decision on the write:

package/docs/customer-organizations.md

@@ -5,18 +5,19 @@
 Serving many customers from one backend has two shapes, and the first question
 is whether isolating them is a security boundary or a routing convenience.
 
-**One Ablo organization per customer** is the hard boundary. Every row carries
-the organization, and the engine compares it on every read and every write,
-below your code. Choose it when one customer reading another's rows would be an
-incident.
+**Use a model `subject` rule for account isolation inside one project.** Bind
+`accountId` to the `account` group, mint sessions only after verifying membership,
+and use those scoped sessions for server operations too. The complete
+[account multiplayer walkthrough](./examples/account-multiplayer.md) shows this
+composition and its verification path.
 
-**One organization, customers as rows told apart by sync groups** is delivery
-and read routing. It is declarative, it depends on every model being covered,
-and it is not enforced on every path. Choose it when cross-customer reads are
-tolerable or intentional, not when they are a breach.
+A separate Ablo organization per customer is another tenant boundary. It is not
+required merely because your application has accounts.
 
-The rest of this page is the second shape. Read *Where the boundary is enforced*
-before you rely on it.
+**Sync-group routing alone is not subject authorization.** The older routing-only
+example below illustrates delivery configuration; add subject rules before using
+that pattern as a customer security boundary. The limitations below describe
+models without subject rules, not subject-protected models.
 
 ```ts
 // 1. src/ablo/schema.ts — your customer table is a scope root.
@@ -91,8 +92,7 @@ organization, project, and branch, and all three are compared on every read and
 every write, from the credential rather than the request. A client cannot reach
 past them by asking. This is the boundary that holds unconditionally.
 
-**Sync groups are a cut inside your account, and they are not applied
-everywhere.** They decide which changes are delivered and which rows a
+**Without a subject rule, sync groups are a routing cut inside your account.** They decide which changes are delivered and which rows a
 log-served read returns. That is routing. It is not a universal authorization
 boundary, and the gaps are specific:
 

package/docs/examples/account-multiplayer.md

@@ -0,0 +1,164 @@
+# Account multiplayer
+
+> Assemble account isolation, two humans, one agent, presence and reconnect in one runnable app.
+
+The maintained reference lives in
+[`examples/account-multiplayer`](https://github.com/Abloatai/ablo/tree/main/examples/account-multiplayer).
+Start at `src/index.ts`, then follow its owned `accounts`, `agent` and `workspace`
+boundaries. Its README contains the install, isolated-branch setup and test commands.
+
+## One account, one authorization rule
+
+“People in this account can see its chats” requires both a row rule and a
+server-verified session grant:
+
+```ts
+const schema = defineSchema({
+  conversations: model({
+    accountId: z.string().min(1),
+    title: z.string(),
+    executionOwner: z.string().nullable(),
+    executionState: z.enum(['idle', 'generating']),
+  }, { subject: { field: 'accountId', group: 'account' } }),
+});
+```
+
+The subject rule maps the row's `accountId` to the required `account:<id>`
+membership. This is authorization, distinct from optional group routing. Push
+the schema to your isolated branch before using it. When connecting your own
+database, apply the subject policies through the supported connection setup too.
+
+```ts
+const POST = sessions.handler({
+  authenticate: request => authenticateApplicationCookie(request),
+  async grant({ principal, request }) {
+    const member = await verifyRequestedAccountMembership(principal, request);
+    if (!member) return null;
+    return {
+      user: { id: member.user.id },
+      groups: [syncGroup('account', member.accountId)],
+      can: { conversations: ['read'] },
+    };
+  },
+});
+```
+
+Your application authenticates the person and verifies membership on every
+mint. The subject rule authorizes rows; `groups` proves membership; `can`
+authorizes operations. Synchronization delivers the authorized data. A list
+filter helps select a view but does not establish any of these permissions.
+The provider's `userId` prop is informational, not an authentication mechanism.
+
+## Browser reads and server writes share the scope
+
+The browser creates an application-owned React client with the account-specific
+session endpoint. It receives only read authority. The server uses its secret key
+only to mint credentials, then creates a scoped client for the actual operation:
+
+```ts
+const session = await sessions.create({
+  user: { id: member.user.id },
+  groups: [syncGroup('account', member.accountId)],
+  can: { conversations: ['read', 'create', 'update'] },
+});
+const client = Ablo({ schema, session, transport: 'http' });
+try {
+  await client.conversations.create({ data: {
+    accountId: member.accountId,
+    title: 'New chat', executionOwner: null, executionState: 'idle',
+  } });
+} finally {
+  await client.dispose();
+}
+```
+
+Resolve `member` on the server for this request. Do not accept a submitted account
+ID as proof of membership. Do not reuse a privileged singleton for account writes.
+
+On account switching, unmount the old account tree, dispose its client, and create
+a new client pointed at the newly authorized account endpoint. The example keys
+the component by account and creates each client in an effect, so Strict Mode
+cleanup cannot dispose an instance that a later setup reuses. See [React](../react.md)
+for both singleton and component-owned patterns and startup status.
+
+## Long-running ownership
+
+The example's `agent/index.ts` owns account-scoped run receipts;
+`agent/execution.ts` owns the typed claim and writes. Its
+`agent/lifetime.ts` owns a process handle with `done` and `stop()`; the handle can
+outlive the function that started it. Server shutdown and normal stream completion
+join the same completion promise.
+
+The agent session carries account membership and `read`/`update` authority. See
+[claim permissions](../coordination.md#claim-permissions): selecting claim fields
+does not limit which fields that session can update.
+
+The lifecycle follows these rules:
+
+1. Acquire with `contention: { mode: 'skip' }`; a null grant means another agent
+   owns the task. Dispose the unused client.
+2. Install heartbeat loss handling during acquisition. Loss aborts application
+   execution; every later model write also passes the held claim so the server
+   rejects stale ownership.
+3. Put initialization and the first write inside the cleanup boundary.
+4. Make execution cooperate with its abort signal. Shutdown aborts execution and
+   waits for it to settle before releasing ownership. Cancellation cannot undo
+   an external side effect already performed.
+5. Release in `finally`, and dispose in the release's own `finally`. A failed
+   release must never prevent client disposal. Failed release falls back to TTL
+   expiry; report the failure rather than presenting immediate release as certain.
+
+The long-running agent takes an id-only lease with `claim(id, options)`, then
+reads the row before each mutation and passes `reads: [current]` alongside the
+claim. The lease supplies exclusion and fencing; each read supplies fresh
+conflict evidence. The object-form `claim({ id, ... })` also captures a snapshot,
+whose write guard remains fixed at acquisition even after your own writes.
+
+The example claims both `executionOwner` and `executionState`, writes with the
+claim, simulates generating, then stays idle while still holding ownership.
+The `executionOwner` row value is historical metadata after release; the UI uses
+`useAblo(client => client.conversations, id).claimed` for reactive ownership.
+The row form subscribes to claim events; a selector-only call to `claim.state`
+is only a snapshot and can miss ownership changes. Applications decide how to recover
+an interrupted execution-state field; a lease is not proof of ongoing generation.
+
+Text buffering, tool execution and queued-message scheduling belong to the
+application. They are deliberately outside this reference's coordination owner.
+
+## Presence semantics
+
+`usePresence(client => client.conversations, id)` declares a read lease while the
+chat is mounted and returns sessions, including the current connection. Two tabs
+can represent one person. Count people by participant identity; use
+`presenceSessionId` when displaying sessions. Human and agent identities have a
+`participant.kind` as well as an ID.
+
+A read lease means “viewing”; a claim means “owns this chat”; application execution
+state means “generating.” None substitutes for the others. Navigation releases
+the previous read lease. Reconnect reannounces active reads. A disconnected
+participant can remain visible until lease expiry.
+
+## What proves the composition
+
+The reference's tests cover membership, contention, initialization failure, first
+write failure, ownership loss, duplicate cleanup, release failure and shutdown
+during acquisition. Its Playwright scenario signs in two humans and an outsider,
+checks forbidden account session/write requests and observes multiple tabs. Two
+distinct agent identities contend on the exact conversation created by the test:
+one executes and one skips, then another acquires after release. Bob renames the
+chat while Alice is offline; reconnect must deliver that title to Alice. Selectors
+use the conversation ID, so existing rows cannot change which chat is tested.
+
+CI runs the browser scenario twice against the same isolated credential, alongside
+the three subject-authorization journey suites. The existing journey harness
+mints the key in temporary Postgres, starts real Redis and the sync server, pushes
+the reference schema, and passes the credential only to the app's server process.
+Missing infrastructure fails the lane. Run it from the monorepo root with
+`npm run test:multiplayer --workspace=@ablo/sync-server`. This verifies the
+checked-out server, not a deployed fleet; the browser suite can separately target
+a deployed isolated branch.
+
+The sync server's `subject-authorization` journeys test authorization beneath the
+UI across hosted SQL/RLS, log-fold and endpoint paths, including direct-ID access,
+lists, writes and claims. Run those alongside the browser test for the deployment
+plane you use. A filtered UI hiding another account's row is not an isolation test.

package/docs/identity.md

@@ -6,6 +6,9 @@ This is the doc the Quickstart skips: **who is connecting, and which slice
 of shared state do they get?** If you've wired `<AbloProvider client={ablo}>`
 and wondered where org / team / user actually come from — start here.
 
+For account-scoped humans and agents together, start with the maintained
+[account multiplayer walkthrough](./examples/account-multiplayer.md).
+
 ## Ablo does not do auth
 
 Ablo is not an identity provider. It has no login, no password store, no

package/docs/index.md

@@ -77,3 +77,6 @@ Ablo is designed to be implemented by agents as well as people. Use
 index, or connect an assistant to the [documentation MCP server](./mcp.md). The
 coordination MCP package also ships its agent-facing skill as
 `@abloatai/mcp/skill.md`.
+
+For a complete human-and-agent application, follow the
+[account multiplayer reference](./examples/account-multiplayer.md).

package/docs/integration-guide.md

@@ -24,6 +24,9 @@ Three things hold no matter which actor is writing:
   credential scoped to just what that run can touch, verified per request and
   revocable instantly. (See the Agents section below for the actual calls.)
 
+For account-scoped humans and agents together, start with the maintained
+[account multiplayer walkthrough](./examples/account-multiplayer.md).
+
 ## The integration in one diagram
 
 The normal integration is one client:
@@ -523,6 +526,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 +551,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,18 +39,19 @@ 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.
 
 ## AbloProvider
 
-Mount it once near the root of your tree. It owns the connection, the local
-pool, and the engine lifecycle; everything below it reads with `useAblo`.
+Mount it once near the root of your tree. **The application owns the client
+and must dispose it.** The provider starts readiness and binds React to the
+client; unmounting the provider does not dispose a shared client.
 
 ```tsx
 'use client';
@@ -89,6 +90,73 @@ identity comes from, and why the API key never reaches the browser, is the whole
 of [Identity & Sync Groups](./identity.md) — read that if it isn't obvious how
 org / team / user map to what a participant can see.
 
+## Client lifetime and account switching
+
+For an application-owned singleton, create it once as above. Your application
+session owner calls `await ablo.dispose()` on logout or before replacing that
+client. Provider remounts can reuse it. Never share a browser singleton across
+server requests. When changing accounts, remove the old account UI and create a
+fresh client whose session endpoint grants the newly verified membership.
+A query filter and the provider's `userId` prop do not change authorization.
+
+For a component-owned client, create and dispose the instance in the same effect.
+React Strict Mode can replay setup and cleanup, so each setup creates a fresh
+instance rather than reusing one that cleanup already disposed:
+
+```tsx
+const createClient = (accountId: string) => Ablo({
+  schema,
+  persistence: 'memory',
+  session: { endpoint: `/api/accounts/${encodeURIComponent(accountId)}/ablo-session` },
+});
+
+function AccountWorkspace({ accountId }: { accountId: string }) {
+  const [owned, setOwned] = useState<{
+    accountId: string;
+    client: ReturnType<typeof createClient>;
+  } | null>(null);
+
+  useEffect(() => {
+    const client = createClient(accountId);
+    setOwned({ accountId, client });
+    return () => { void client.dispose().catch(reportError); };
+  }, [accountId]);
+
+  // Never render an old account's client under the new account's heading.
+  if (!owned || owned.accountId !== accountId) return <AppSkeleton />;
+  return <AbloProvider key={accountId} client={owned.client}><Workspace /></AbloProvider>;
+}
+```
+
+Import `useEffect` and `useState` from React. The endpoint must verify membership
+for the requested account on every mint; the URL itself grants no access.
+See the [account multiplayer walkthrough](./examples/account-multiplayer.md)
+for the complete ownership boundary and runnable component.
+
+## Render immediately with connection status
+
+`useSyncStatus()` works during provider startup, in passthrough children and in
+custom fallbacks. It observes the client's status before row scope is available.
+It still requires a provider. Data hooks that require authenticated scope must
+wait for readiness.
+
+```tsx
+import { useSyncStatus } from '@abloatai/ablo/react';
+
+function ConnectionIndicator() {
+  const status = useSyncStatus();
+  return <span role="status">{
+    status.name === 'initial' || status.name === 'connecting'
+      ? 'Connecting…' : status.name
+  }</span>;
+}
+
+<AbloProvider client={ablo} fallback="passthrough">
+  <ConnectionIndicator />
+  <ExistingWorkspace />
+</AbloProvider>
+```
+
 ## useAblo: model client
 
 ```tsx
@@ -97,23 +165,23 @@ org / team / user map to what a participant can see.
 import { useAblo } from '@abloatai/ablo/react';
 
 export function ReportView({ report: serverReport }: { report: { id: string; location: string } }) {
-  const report = useAblo((ablo) => ablo.weatherReports.local.get(serverReport.id)) ?? serverReport;
-  const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
-  const claimed = Boolean(active);
+  const { data: report, claimed } = useAblo(
+    ablo => ablo.weatherReports,
+    serverReport.id,
+    { initial: serverReport },
+  );
 
-  return <article>{report.location}</article>;
+  return <article>{report.location}{claimed && <span>Claimed</span>}</article>;
 }
 ```
 
-The hook:
+The row form subscribes to both data and claim events. It returns `data`,
+`claims`, and `claimed`, and accepts an initial server-rendered row.
 
-1. Uses the same `ablo.<model>.local.get(id)` / `.local.list()` methods you'd call anywhere
-   else in the SDK — the hook just makes them reactive.
-2. Tracks the model fields read by the selector and re-renders when confirmed
-   deltas arrive.
-3. Lets Server Component data stay outside the hook: use `?? serverReport` when a
-   parent already loaded the row.
-4. Works for coordination state too, such as `ablo.weatherReports.claim.state({ id })`.
+For data-only reads, selectors such as
+`useAblo(ablo => ablo.weatherReports.local.get(id))` track model fields.
+A selector-only `claim.state({ id })` read does not subscribe to the claim event
+stream. Use the row form above when the UI displays ownership.
 
 Use the zero-argument form only when you need the full client for callbacks,
 effects, or writes:
@@ -165,7 +233,7 @@ await ablo.weatherReports.update({
 });
 ```
 
-For client event handlers, get the provider-owned client and call the same
+For client event handlers, get the application-owned client and call the same
 model client:
 
 ```tsx
@@ -188,6 +256,89 @@ 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.
+
+A presence session is a connection, not a unique person. Two tabs can share
+`participant.id` while having different `presenceSessionId` values. For a people
+count, deduplicate by both `participant.kind` and `participant.id`; retain the
+sessions when displaying connection details. Reading declares attention; claiming
+declares ownership. Neither proves that an agent is generating text. Label a held
+claim “Agent owns this chat.” Drive “Generating” from application execution state.
+On navigation, the hook releases its old read lease. After a lost connection,
+remote presence may remain until its lease expires; disappearance is not immediate.
+
+## 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.1",
   "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.1",
+    "@abloatai/transaction": "^0.63.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {