@abloatai/ablo 0.63.1 → 0.64.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.64.1
+
+The React read and write boundaries are now explicit: `useAbloClient()` returns the writable client and `useAblo(selector)` returns render snapshots. The zero-argument `useAblo()` overload is removed. `ablo upgrade` reports migration hints; see [Upgrade Guide](./docs/migration.md).
+
+Public schema registration reaches Transaction and Humans across emitted package declarations. Ambient mutators without a registered schema now report a schema diagnostic; prefer explicit-schema overloads. Internal package dependencies are exact, and CLI/SDK compatibility is checked as one release family.
+
+`usePresence(..., { excludeSelf: true })` and `presence.forModel(model, id, { excludeSelf: true })` omit the current session. `useMutationFailure` owns React subscription cleanup. Custom framework adapters use `getAbloStore(client)` from `/client`. Generic collaboration subscriptions preserve their declared event tuples; attributed handlers use `collaboration.subscribe` (or transport `subscribeCollaboration`).
+
+`AbloProvider` is now the sole provider vocabulary. Advanced framework adapters use `useAbloStoreContext` and `AbloStoreContextValue`; the missing-provider error code is `ablo_context_missing_provider`.
+
+## 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.

package/dist/index.d.ts

@@ -8,4 +8,12 @@ export { Ablo as default } from '@abloatai/transaction';
  */
 export { noopLogger } from '@abloatai/transaction/logger';
 export type { Logger } from '@abloatai/transaction/logger';
+/** Application registration, owned here so augmentation survives re-exports. */
+export interface Register {
+}
+type PublicRegister = Register;
+declare module '@abloatai/transaction/types/global' {
+    interface Register extends PublicRegister {
+    }
+}
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,YAAY,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,YAAY,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAE3D,gFAAgF;AAEhF,MAAM,WAAW,QAAQ;CAAG;AAC5B,KAAK,cAAc,GAAG,QAAQ,CAAC;AAI/B,OAAO,QAAQ,oCAAoC,CAAC;IAClD,UAAU,QAAS,SAAQ,cAAc;KAAG;CAC7C"}

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, useAbloClient, useMutationFailure, 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,aAAa,EACb,kBAAkB,EAClB,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, useAbloClient, useMutationFailure, 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,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,wBAAwB,CAAC"}

package/docs/examples/account-multiplayer.md

@@ -118,8 +118,8 @@ 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
+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

package/docs/examples/scoped-agent.md

@@ -115,11 +115,11 @@ the agent can never reach a workspace its triggering user couldn't.
 
 ## 3. Write: it fans out to everyone on that workspace
 
-Inside any component under the provider, grab the scoped client with `useAblo()`
+Inside any component under the provider, grab the scoped client with `useAbloClient()`
 and write. The connection is already narrowed to `workspace:<workspaceId>` from Step 2.
 
 ```ts
-const ablo = useAblo();
+const ablo = useAbloClient();
 
 // Other participants subscribed to workspace:<workspaceId> — a reviewer agent, a
 // person watching in the UI — receive this delta in realtime. Participants on

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

@@ -585,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/integration-guide.md

@@ -287,7 +287,7 @@ In React, selector `useAblo` is the public read API:
 ```tsx
 'use client';
 
-import { useAblo } from '@abloatai/ablo/react';
+import { useAblo, useAbloClient } from '@abloatai/ablo/react';
 
 export function ReportRow({
   report: serverReport,
@@ -301,10 +301,10 @@ export function ReportRow({
 }
 ```
 
-Use zero-argument `useAblo()` only in callbacks and effects:
+Call `useAbloClient()` during render, then use its client in callbacks and effects:
 
 ```tsx
-const ablo = useAblo();
+const ablo = useAbloClient();
 ```
 
 ## 4. Write State

package/docs/migration.md

@@ -3,7 +3,100 @@
 > A safe workflow for upgrading the pre-1.0 SDK.
 
 Ablo is pre-1.0, so a minor release may contain a breaking API change. Patch
-releases remain compatible within the same minor line.
+releases normally remain compatible within the same minor line. The 0.64.1
+release includes the explicit React and collaboration migrations below.
+
+## React and package boundaries after 0.64
+
+Run `npx ablo upgrade` for migration hints before editing. It previews changes;
+`--write` applies only mechanical rewrites. React changes requiring application
+judgment are reported with their replacements.
+
+| Previous API | Current API |
+| --- | --- |
+| `useSync()` or zero-argument `useAblo()` | `useAbloClient()` for actions; await `client.ready()` when initialization is required |
+| `useSyncStatus()` | `useAblo(client => client.status)` |
+| `usePeers()` | `useAblo(client => client.presence.others)` |
+| Scoped peers | `usePresence(client => client.records, id, { excludeSelf: true })` |
+| `useMutationFailureListener(listener)` | `useMutationFailure(listener)` |
+| `useErrorListener()` | `AbloProvider`'s `onError` prop for startup errors |
+| `useCurrentUserId()` | Your application's authentication context |
+| `useSDKSyncStore()` / `useSyncStore()` | Public client operations; `getAbloStore(client)` from `/client` for custom local-store adapters |
+| `ClientSideSuspense` / `DefaultFallback` | Application UI through the provider's `fallback` prop |
+| `GroupScope` for presence | Model and record arguments |
+
+`useAblo(selector)` returns detached snapshots for rendering. They have no model
+methods or relation accessors. `useAbloClient()` returns the writable client and
+does not subscribe to row changes. Do not perform writes inside a selector.
+
+### Presence, activities and claims
+
+`Activity` is replaced by `Ablo.PresenceActivity`, including for agents. A session
+is `Ablo.PresenceSession`: identify the execution with `presenceSessionId` and its
+actor with `participant.id` and `participant.kind`. A participant can have several
+sessions, so exclude self by session rather than user ID.
+
+`presence.active` contains this session's activities; `presence.others` contains
+other sessions, each with an `activities` array. `forModel(model, id)` includes
+self by default; pass `{ excludeSelf: true }` as its third argument to omit self.
+The same option on `usePresence` still announces the component's reading activity
+and cleans it up on unmount.
+
+An activity has `operation`, `target`, `source`, and ISO timestamp fields.
+Read the model and row from `activity.target.model` and `.id`; field-specific
+activity uses `.field` or `.fields` (never both, and always with a row ID).
+Activities describe visible work; they do not grant write authority.
+
+Claims are acquired through `await using claim = await client.records.claim({ id })`.
+The protected row is `claim.data`; pass `claim` to the write. Claim lookup uses
+`client.records.claim.state({ id })` and `.queue({ id })`. Claim metadata is on
+`claim.target.meta`, and a multi-field claim uses `fields` in the claim target.
+Do not reconstruct a claim handle from a presence activity. See [Claims](./claims.md).
+
+### Imports and schema ownership
+
+The root factory creates a headless client; `/client` creates the reactive client.
+Import the `Ablo` type namespace beside the factory you use. Both expose the
+shared schema, presence-activity and claim types. Reactive-only types such as
+`Ablo.Status`, `Ablo.Reads`, `Ablo.Store`, and `Ablo.Mutator` belong to `/client`
+(or `/react` for its re-exported reactive factory).
+
+Prefer explicit schema inference:
+
+```ts
+import { defineMutators } from '@abloatai/ablo/client';
+import { useMutators, useUndoScope } from '@abloatai/ablo/react';
+import { schema } from './schema';
+
+const definitions = defineMutators(schema, {
+  records: {
+    rename: async ({ tx, args }: {
+      tx: import('@abloatai/ablo/client').Ablo.Mutator.Transaction<typeof schema>;
+      args: { id: string; title: string };
+    }) => tx.mutations.records.update({ id: args.id, title: args.title }),
+  },
+});
+
+function useRecordActions() {
+  const { scope } = useUndoScope(schema, 'record-editor');
+  return useMutators(schema, definitions, { undoScope: scope });
+}
+```
+
+Ambient registration remains available for a single application. Its module must
+be included in that TypeScript program and import `@abloatai/ablo` before
+augmenting `Register`. The public registration now reaches the downstream
+Transaction and Humans resolvers through the emitted declarations. A package
+compiled independently cannot inherit a consuming app's ambient declaration.
+
+### Structural collaboration adapters
+
+Generic `subscribe(event, handler)` preserves exactly the argument tuples in your
+event map. Receive optional server attribution through the session's
+`collaboration.subscribe(event, (payload, context) => ...)`; low-level transport
+adapters use `subscribeCollaboration`. Model-scoped `client.records.events.on`
+continues to supply authenticated context as its second callback argument.
+Legacy servers may omit context on application events; handle `undefined` there.
 
 ## Upgrade safely
 
@@ -14,7 +107,7 @@ releases remain compatible within the same minor line.
 5. Run the three-state deployment plan, then push the exact reviewed plan.
 
 ```bash
-npm install @abloatai/ablo@0.48
+npm install --save-exact @abloatai/ablo@<version> @abloatai/cli@<version>
 npx ablo docs
 npx ablo docs api
 npx ablo plan

package/docs/react.md

@@ -13,9 +13,58 @@ agents, start with [Integration Guide](/docs/integration-guide).
 The React bindings ship with the main package — no extra install.
 
 ```ts
-import { useAblo } from '@abloatai/ablo/react';
+import { useAblo, useAbloClient } 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, let the hook own the subscription:
+
+```tsx
+import { useMutationFailure } from '@abloatai/ablo/react';
+
+useMutationFailure(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,
@@ -37,12 +86,12 @@ 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,
+// born-typed hooks from this file — `useAbloClient()` takes no type arguments,
 // and a selector's `ablo` parameter knows your models.
-export const { AbloProvider, useAblo, usePresence } = createAbloReact(schema);
+export const { AbloProvider, useAblo, useAbloClient, usePresence, useMutationFailure } = createAbloReact(schema);
 ```
 
-Import `AbloProvider`, `useAblo`, and `usePresence` from `lib/ablo` rather than from the
+Import `AbloProvider`, `useAbloClient`, `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.
@@ -135,19 +184,19 @@ for the complete ownership boundary and runnable component.
 
 ## Render immediately with connection status
 
-`useSyncStatus()` works during provider startup, in passthrough children and in
+`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 { useSyncStatus } from '@abloatai/ablo/react';
+import { useAblo } from '@abloatai/ablo/react';
 
 function ConnectionIndicator() {
-  const status = useSyncStatus();
+  const status = useAblo(ablo => ablo.status);
   return <span role="status">{
-    status.name === 'initial' || status.name === 'connecting'
-      ? 'Connecting…' : status.name
+    status?.name === 'initial' || status?.name === 'connecting'
+      ? 'Connecting…' : status?.name
   }</span>;
 }
 
@@ -171,6 +220,7 @@ export function ReportView({ report: serverReport }: { report: { id: string; loc
     { initial: serverReport },
   );
 
+  if (!report) return <p>This report is not in the local cache.</p>;
   return <article>{report.location}{claimed && <span>Claimed</span>}</article>;
 }
 ```
@@ -180,14 +230,30 @@ The row form subscribes to both data and claim events. It returns `data`,
 
 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.
+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.
+
+`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:
 
 ```tsx
-const abloClient = useAblo();
+const abloClient = useAbloClient();
 ```
 
 Prefer selector reads like `useAblo((ablo) => ablo.<model>.local.get(id))`. Older hooks
@@ -237,7 +303,7 @@ For client event handlers, get the application-owned client and call the same
 model client:
 
 ```tsx
-const ablo = useAblo();
+const ablo = useAbloClient();
 
 async function markReady() {
   if (!ablo) return;
@@ -311,7 +377,7 @@ 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();
+const ablo = useAbloClient();
 
 useEffect(() => {
   if (!ablo) return;
@@ -339,32 +405,73 @@ 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
 
 The Next.js [App Router landing](./examples/nextjs.md) walks through Server Components
 + Server Actions + `useAblo` together.
+
+## Separate packages and monorepos
+
+Put the schema in an application-owned package, with a public export for its
+value and type. Put the React binding in a client module which imports that
+schema, and export its inferred declarations. Components import their hooks from
+that binding package. Build the schema package before its dependents and test the
+emitted declarations without workspace source aliases.
+
+```ts
+'use client';
+import { createAbloReact } from '@abloatai/ablo/react';
+import { schema } from '@app/schema';
+
+export const { AbloProvider, useAbloClient, useAblo, usePresence, useMutationFailure } =
+  createAbloReact(schema);
+```
+
+Use one binding per schema, and mount its hooks under a provider for that schema.
+The binding specializes types; it does not create an isolated runtime context or
+validate that a different binding's provider has the same schema. Keep React and
+the Ablo package family deduplicated across packages. Reusable libraries should
+accept a schema or typed binding rather than declare an application-global schema.
+An app's ambient registration cannot retroactively change a separately compiled
+library. Use `defineMutators(schema, definitions)`, `useMutators(schema, definitions)`
+and `useUndoScope(schema, name)` across those boundaries.
+
+## Mutation failures and scoped collaborators
+
+```tsx
+const peers = usePresence(client => client.records, id, { excludeSelf: true });
+useMutationFailure(({ error }) => showToast(error.message));
+```
+
+`useMutationFailure` uses the latest committed callback, moves its subscription
+when the provider client changes, and unsubscribes on unmount. For non-React
+callers, `client.onMutationFailure` returns the cleanup function.
+
+For a custom framework adapter, `getAbloStore(client)` from
+`@abloatai/ablo/client` returns the supported `Ablo.Store` contract: local pool
+access, mutation observation, and scope management. Ordinary writes, confirmation,
+reconnection and model events already have public client methods; they do not
+require a store adapter.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.63.1",
+  "version": "0.64.1",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -132,7 +132,8 @@
     "build:docs": "node scripts/build-blume-docs.mjs",
     "lint:docs-site": "node scripts/build-blume-docs.mjs --check",
     "lint:docs": "node scripts/check-doc-drift.mjs",
-    "lint:pkg": "publint"
+    "lint:pkg": "publint",
+    "verify:package-contract": "node scripts/package-contract/index.mjs"
   },
   "publishConfig": {
     "access": "public",
@@ -145,8 +146,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.63.1",
-    "@abloatai/transaction": "^0.63.1",
+    "@abloatai/humans": "0.64.1",
+    "@abloatai/transaction": "0.64.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {