@abloatai/ablo 0.64.0 → 0.64.1

package/CHANGELOG.md

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

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 { AbloProvider, createAbloReact, useAblo, usePresence, useMutators, useUndoScope, } 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,+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"}
+{"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,4 +1,4 @@
 /** Core client and the explicitly supported React bindings. */
 export { Ablo, humans } from '@abloatai/humans';
-export { AbloProvider, createAbloReact, useAblo, usePresence, useMutators, useUndoScope, } 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,+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"}
+{"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/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/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,7 +13,7 @@ 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`
@@ -21,11 +21,12 @@ 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:
+For mutation failures, let the hook own the subscription:
 
 ```tsx
-const ablo = useAblo();
-useEffect(() => ablo?.onMutationFailure(reportFailure), [ablo, reportFailure]);
+import { useMutationFailure } from '@abloatai/ablo/react';
+
+useMutationFailure(reportFailure);
 ```
 
 `reportFailure` receives `Ablo.MutationFailure`. Read application identity from
@@ -85,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.
@@ -252,7 +253,7 @@ 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
@@ -302,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;
@@ -376,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;
@@ -431,3 +432,46 @@ its returned cleanup function.
 
 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.64.0",
+  "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.64.0",
-    "@abloatai/transaction": "^0.64.0",
+    "@abloatai/humans": "0.64.1",
+    "@abloatai/transaction": "0.64.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {