@abloatai/ablo 0.63.1 → 0.64.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # 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.

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/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/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/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,
@@ -135,19 +183,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 +219,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,8 +229,24 @@ 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:
@@ -339,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.1",
+  "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.1",
-    "@abloatai/transaction": "^0.63.1",
+    "@abloatai/humans": "^0.64.0",
+    "@abloatai/transaction": "^0.64.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {