@abloatai/ablo 0.63.0 → 0.64.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 0.64.0
+
+React reads the same core objects as ordinary Ablo code. Read connection state with `ablo.status` outside React and `useAblo(ablo => ablo.status)` inside React; its type is `Ablo.Status`. Presence reads through `useAblo(ablo => ablo.presence.others)` or `ablo.presence.forModel(model, id)` now react to activity changes. The unregistered-schema selector also preserves core properties and methods.
+
+This is a breaking API cleanup for 0.64, with no compatibility aliases:
+
+- Replace `useSyncStatus()` with `useAblo(ablo => ablo.status)`, and `SyncStatusSnapshot` with `Ablo.Status`. Replace the client's raw `syncStatus` with `status`; raw transport details remain internal to the store.
+- Replace `useSync()` with `useAblo()`. The client is available during startup; await `client.ready()` before operations that require initialization.
+- Replace `usePeers()` with `useAblo(ablo => ablo.presence.others)`. Replace scoped peer reads with `useAblo(ablo => ablo.presence.forModel(model, id))`; this returns sessions, including the current session when it has activity on that record. Filter by session ID when you specifically need other sessions.
+- Replace `useMutationFailureListener(listener)` with `useEffect(() => ablo?.onMutationFailure(listener), [ablo, listener])`; the payload type is `Ablo.MutationFailure`.
+- Handle provider startup errors with `<AbloProvider onError={...}>` instead of `useErrorListener()`.
+- Read application identity from your authentication client or application context instead of `useCurrentUserId()`. The informational `AbloProvider.userId` prop is removed; authenticated Ablo authority still comes from the client's session.
+- `GroupScope` leaves the React entry point with `usePeers`; presence filtering uses model and record arguments.
+- `useSyncStore`, `SyncStoreContract`, and `useReactive` are no longer React entry-point exports. Use the core client; framework integration internals remain under the humans runtime boundary.
+- `ClientSideSuspense` and `DefaultFallback` are no longer public components. Supply your own UI through the provider's `fallback` prop or render from `ablo.status`.
+
+The React entry point explicitly exports its supported bindings instead of forwarding all implementation exports through a wildcard. Existing model operations, claims, and reading-activity lifetimes remain on their core owners.
+
+React type annotations now follow their owners. The entry point has eight runtime exports (`Ablo`, `humans`, `AbloProvider`, `createAbloReact`, `useAblo`, `usePresence`, `useMutators`, `useUndoScope`) and no standalone type exports:
+
+| Removed React type export                                 | Replacement                                                                                         |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `AbloOptions`                                             | `Ablo.Options`                                                                                      |
+| `AbloReads`                                               | `Ablo.Reads`                                                                                        |
+| `HumansSurface`                                           | Infer the plugin result; low-level plugin authors can still import the type from `@abloatai/humans` |
+| `AbloProviderProps`                                       | `AbloProvider.Props`                                                                                |
+| `AbloReactBinding`                                        | Infer the binding, or `ReturnType<typeof createAbloReact<Models>>`                                  |
+| `PresenceModelSelector`                                   | Infer an inline selector against the bound schema                                                   |
+| `UseAbloModelOptions`                                     | `useAblo.Options<Row>`                                                                              |
+| `UseAbloModelResult`                                      | `useAblo.Result<Row>`                                                                               |
+| `UseAbloHydratedModelResult`                              | `useAblo.Result<Row>`; handle optional data after local removal, even with `initial`                |
+| `InvokerFor`                                              | `typeof mutations.model.operation`                                                                  |
+| `MutatorInvokers`                                         | `useMutators.Result<typeof definitions>`                                                            |
+| `UseMutatorsOptions`                                      | `useMutators.Options<typeof schema>`                                                                |
+| `UseUndoScopeResult`                                      | `useUndoScope.Result<typeof schema>`                                                                |
+| `ResolveSchema`                                           | Existing core `Ablo.ResolveSchema`, when using module registration                                  |
+| `ResolveModelKey`                                         | `keyof typeof schema.models`                                                                        |
+| `DefaultSyncShape`, `ResolveUserMeta`, `ResolveClaimMeta` | Internal registration details; use schema inference and the core presence/claim types               |
+| `MutateActions`                                           | `Ablo.Mutator.Transaction<typeof schema>['mutate'][ModelKey]`                                       |
+| `ReaderActions`                                           | `Ablo.Mutator.Transaction<typeof schema>['read'][ModelKey]`                                         |
+| `ReaderFindOptions`                                       | Infer read options; advanced callers can import the existing type from `@abloatai/ablo/client`      |
+
+`ModelScope` is no longer re-exported by React; its existing advanced owner is `@abloatai/ablo/client`. Ordinary model reads use their `state` option.
+
+`createAbloReact(schema)` now specializes only types and returns the existing module-level provider and hooks. It creates no React context or component identity. Hooks always read the nearest AbloProvider, including when bindings for different schemas are nested; do not call a binding's hooks below a provider for another schema. Recreating a binding no longer remounts its children. Keep the application binding at module scope for clear ownership.
+
+Selectors now preserve equal snapshot identity, detach nested row data, and subscribe to claim events. Subscriptions survive suspended renders and catch changes between render and subscription. Initial rows match server rendering during hydration, then yield to local data; a later removal no longer restores the seed. Local cache absence remains distinct from server absence.
+
+## 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.

package/dist/react.d.ts

@@ -1,4 +1,4 @@
+/** Core client and the explicitly supported React bindings. */
 export { Ablo, humans } from '@abloatai/humans';
-export type { AbloOptions, AbloReads, HumansSurface } from '@abloatai/humans';
-export * from '@abloatai/humans/react';
+export { AbloProvider, createAbloReact, useAblo, usePresence, useMutators, useUndoScope, } from '@abloatai/humans/react';
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC9E,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,YAAY,EACZ,eAAe,EACf,OAAO,EACP,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,wBAAwB,CAAC"}

package/dist/react.js

@@ -1,3 +1,4 @@
+/** Core client and the explicitly supported React bindings. */
 export { Ablo, humans } from '@abloatai/humans';
-export * from '@abloatai/humans/react';
+export { AbloProvider, createAbloReact, useAblo, usePresence, useMutators, useUndoScope, } from '@abloatai/humans/react';
 //# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEhD,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,YAAY,EACZ,eAAe,EACf,OAAO,EACP,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,wBAAwB,CAAC"}

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.
+Both the row form and `useAblo(client => client.conversations.claim.state({ id }))`
+subscribe to claim events. 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/groups.md

@@ -46,7 +46,7 @@ question you have.
 ablo.records.onChange((docs) => render(docs));
 
 // In React: who else is visible on this client's scoped groups?
-const peers = usePeers({ records: documentId });
+const peers = useAblo(ablo => ablo.presence.forModel('records', documentId)) ?? [];
 
 // Stop this write if the thing I read moved while I composed it.
 const record = await ablo.records.read({ id: 's-1' });
@@ -57,10 +57,10 @@ await ablo.blocks.update({ id, data, reads: [record] });
 | Question | Channel | Arrives |
 | --- | --- | --- |
 | What do the rows say right now? | `onChange` | As deltas land, on the socket |
-| Who else is working here? | `usePeers` over the session/client groups | As participants connect, disconnect, or change activity |
+| Who else is working here? | `useAblo(ablo => ablo.presence.others)` over the session/client groups | As participants connect, disconnect, or change activity |
 | Did the premise for **this** write move? | `reads` on the write | On that write's receipt, before it applies |
 
-`onChange` and `usePeers` use the reactive client's socket. `reads` rides the
+`onChange` and `useAblo(ablo => ablo.presence.others)` use the reactive client's socket. `reads` rides the
 commit, so it reaches a socketless actor over HTTP too. The row returned by
 `read` privately carries its model, id, and
 watermark; passing that row in `reads` is enough to protect a later write. Ablo
@@ -183,6 +183,6 @@ them coarse everywhere else.
   [`concurrency-convention.md`](./concurrency-convention.md) (§4 and §5).
 - **The mechanics**, the three coordination blocks underneath, are
   [`coordination.md`](./coordination.md).
-- **Presence** is read with `usePeers`; active exclusions remain on the
+- **Presence** is read with `useAblo(ablo => ablo.presence.others)`; active exclusions remain on the
   `claim` namespace. See [`react.md`](./react.md) and
   [`coordination.md`](./coordination.md).

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
@@ -582,7 +585,7 @@ an agent pointed at the entities it's working on. You **never hand-write**
    So an agent's reachable set **accretes** as it works — no extra subscribe call.
 
 3. **Presence follows those same groups.** A reactive client announces one
-   participant on its connection; `usePeers(scope)` filters the roster already
+   participant on its connection; `ablo.presence.forModel(model, id)` filters the roster already
    visible through the session and connection groups. There is no second
    membership lease or participant handle. Use `claim` separately when work needs
    exclusion. See [React](./react.md#usepeers-read-only-presence).

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:

package/docs/react.md

@@ -16,6 +16,54 @@ The React bindings ship with the main package — no extra install.
 import { useAblo } from '@abloatai/ablo/react';
 ```
 
+React uses the same objects and operations as core Ablo. Read `ablo.status`
+with `useAblo(ablo => ablo.status)`, select `ablo.presence.others` for other
+sessions, and call ordinary model methods from event handlers. React owns the
+subscription or component lifetime; the client owns the behavior.
+
+For mutation failures, subscribe to the core event in an effect:
+
+```tsx
+const ablo = useAblo();
+useEffect(() => ablo?.onMutationFailure(reportFailure), [ablo, reportFailure]);
+```
+
+`reportFailure` receives `Ablo.MutationFailure`. Read application identity from
+your auth provider; Ablo's authenticated authority comes from its session.
+
+## Types follow their owners
+
+Most calls infer their types from your schema. For wrapper components or explicit
+annotations, use the name you already imported:
+
+```tsx
+import { Ablo, AbloProvider, useAblo } from '@abloatai/ablo/react';
+import { schema } from './schema';
+
+type Models = (typeof schema)['models'];
+type Chat = Ablo.Schema.InferRow<typeof schema, 'chats'>;
+
+function Provider(props: AbloProvider.Props<Models>) {
+  return <AbloProvider {...props} />;
+}
+
+function ChatView({ result }: { result: useAblo.Result<Chat> }) {
+  return <p>{result.data?.title}</p>;
+}
+```
+
+The React annotation types are `AbloProvider.Props`, `useAblo.Options`,
+`useAblo.Result`, `useMutators.Options`, `useMutators.Result` and
+`useUndoScope.Result`. Core types remain under `Ablo`, including `Ablo.Options`,
+`Ablo.Reads`, `Ablo.Status` and `Ablo.PresenceSession`. Import annotation owners
+from the SDK entry point; functions destructured from an app binding infer their
+call types but do not create new TypeScript namespaces in the app module.
+
+`createAbloReact(schema)` specializes types and returns the existing provider and
+hooks. Define your binding at module scope. It creates no client, React context
+or component identity. Hooks always read the nearest provider: use the binding
+that matches that provider's client schema.
+
 ## Building the client
 
 You build the Ablo client once — that's where the schema, the session endpoint,
@@ -49,8 +97,9 @@ 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 +138,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
+
+`useAblo(ablo => ablo.status)` 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 { useAblo } from '@abloatai/ablo/react';
+
+function ConnectionIndicator() {
+  const status = useAblo(ablo => ablo.status);
+  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 +213,40 @@ 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>;
+  if (!report) return <p>This report is not in the local cache.</p>;
+  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.
+
+For data-only reads, selectors such as
+`useAblo(ablo => ablo.weatherReports.local.get(id))` track model fields.
+Claim selectors subscribe too: `useAblo(ablo => ablo.weatherReports.claim.state({ id }))`
+updates when ownership changes. Use the row form when you want data and claims together.
+
+Selectors must be pure synchronous reads. Ablo copies selected rows, arrays and plain
+records into frozen snapshots, including nested data and computed fields. Unchanged
+data retains its snapshot identity across renders. Treat copied dates as read-only;
+model API handles and other class instances retain their original identity. Read
+data inside the selector to subscribe to it. Selector errors reach React error boundaries.
 
-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 })`.
+`initial` supplies the server HTML and first hydration render; React then reads the
+current local row. Once a local row has appeared, removing it returns `undefined`
+instead of restoring the seed, so `data` remains optional even with `initial`.
+
+A local cache miss (`undefined` or an empty list) does not prove that the server has
+no matching data. Local reads do not fetch rows, and connection status does not
+indicate query completeness. Use your route loader and an awaited server read, such
+as `await ablo.weatherReports.get({ id })`, to establish server results and handle
+request errors before passing an initial row to React.
 
 Use the zero-argument form only when you need the full client for callbacks,
 effects, or writes:
@@ -165,7 +298,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
@@ -227,6 +360,15 @@ 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
@@ -262,30 +404,28 @@ 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
+## Presence: the same core read
 
-`usePeers` reads the presence stream already flowing for the client's scoped
-groups. It does not create a second membership or lease and does not change the
-connection's subscriptions.
+Select `ablo.presence.others` for the other sessions visible to this client, or
+filter by a model and record. These reads subscribe to changes without starting
+an activity or claiming ownership.
 
 ```tsx
-'use client';
-
-import { usePeers } from '@abloatai/ablo/react';
+import { useAblo } from '@abloatai/ablo/react';
 
-export function CursorBroadcaster({ workspaceId }: { workspaceId: string }) {
-  const peers = usePeers({ entryCollections: workspaceId });
-  const alone = !peers.some((p) => p.participantKind === 'user');
-  // suppress live-cursor broadcasts while alone
+function Readers({ conversationId }: { conversationId: string }) {
+  const sessions = useAblo(ablo => ablo.presence.forModel('conversations', conversationId)) ?? [];
+  const people = new Set(sessions.filter(session => session.participant.kind === 'user')
+    .map(session => session.participant.id));
+  return <span>{people.size} people, {sessions.length} sessions</span>;
 }
 ```
 
-Pass a schema-shaped group scope to filter the visible peers, or omit it for
-everyone on the client's groups. Returns `ReadonlyArray<Peer>`, where each `Peer` carries
-`participantKind` (`'user' | 'agent' | 'system'`), `participantId`, optional
-`label`, `syncGroups`, `activity`, `lastActive`, and optional `activeClaims`.
-Use `ablo.<model>.claim` when the caller needs exclusion; reading presence does
-not claim anything.
+`usePresence(ablo => ablo.conversations, conversationId)` additionally owns a
+reading activity for the component's lifetime. Use it when mounting the component
+should announce that this session is reading the record. Core code owns the same
+lifecycle explicitly with `ablo.conversations.presence.read(conversationId)` and
+its returned cleanup function.
 
 ## Next.js
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.63.0",
+  "version": "0.64.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.63.0",
-    "@abloatai/transaction": "^0.63.0",
+    "@abloatai/humans": "^0.64.0",
+    "@abloatai/transaction": "^0.64.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {