@abloatai/humans 0.63.1 → 0.64.0

package/dist/Ablo.d.ts

@@ -86,6 +86,10 @@ import type * as _Global from '@abloatai/transaction/types/global';
  *      into one of the public subpaths.
  */
 export declare namespace Ablo {
+    /** Payload delivered by the core client's onMutationFailure subscription. */
+    type MutationFailure = Parameters<Parameters<AbloClient<SchemaRecord>['onMutationFailure']>[0]>[0];
+    /** Current client lifecycle, also selected through React's useAblo. */
+    type Status = import('./local/client/status.js').ClientStatus;
     type Options<S extends SchemaRecord = SchemaRecord> = AbloOptions<S>;
     /**
      * The read view of the client that `useAblo` selectors receive: model reads

package/dist/client.d.ts

@@ -12,9 +12,9 @@
  */
 import type { Schema, SchemaRecord, Model, InferCreate, InferRow } from '@abloatai/transaction/schema/schema';
 import type { InstanceCache } from './local/InstanceCache.js';
-import type { SyncStoreContract } from './react/context.js';
+import type { SyncStoreContract } from './local/storeContract.js';
 import type { SyncWebSocket, CoreSyncEventMap } from './local/sync/SyncWebSocket.js';
-import type { SyncStatus } from './local/BaseSyncedStore.js';
+import type { ClientStatus } from './local/client/status.js';
 import type { ModelOperations } from './local/client/createModelOperations.js';
 import type { ClaimResource, CommitResource } from '@abloatai/transaction/client/resources/httpResources';
 import type { EffectiveAuthority } from '@abloatai/transaction/auth';
@@ -25,7 +25,9 @@ export type { LocalReadOptions } from './local/client/resourceTypes.js';
 /** The typed sync engine client — one property per model in the schema */
 export type AbloClient<S extends SchemaRecord> = {
     readonly [K in keyof S & string]: ModelOperations<Model<Schema<S>, K>, InferCreate<Schema<S>, K>>;
-} & {
+} & AbloCore<S>;
+/** Core members stay intact even when the model schema is not registered. */
+interface AbloCore<S extends SchemaRecord> {
     /**
      * Wait for the sync engine to finish its initial bootstrap.
      * Resolves once entity data is loaded and the WebSocket is connected.
@@ -50,7 +52,7 @@ export type AbloClient<S extends SchemaRecord> = {
      * acknowledged everything before continuing — for example, before
      * navigating away, before triggering a server-side workflow, or in tests.
      *
-     * Resolves when `syncStatus.pendingChanges` reaches 0. If the engine is
+     * Resolves when all pending local changes are confirmed. If the engine is
      * offline, this waits until reconnect + flush completes.
      *
      * ```ts
@@ -171,32 +173,10 @@ export type AbloClient<S extends SchemaRecord> = {
      */
     waitForConfirmation(modelName: string, modelId: string): Promise<void>;
     /**
-     * Reactive sync status — a MobX observable.
-     *
-     * Single source of truth for "what's the sync engine doing?" Contains:
-     * - `state`: `'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting'`
-     * - `progress`: 0-100 for bootstrap progress
-     * - `error?`: Error object when `state === 'error'`
-     * - `pendingChanges`: Number of unconfirmed mutations in the queue
-     * - `lastSyncAt?`: Timestamp of the last successful delta processing
-     * - `offlineSince?`: When the connection dropped
-     * - `isSessionError`: True when the error requires re-authentication
-     *
-     * React components using `observer()` re-render automatically when
-     * any field changes — no manual subscription or polling needed.
-     *
-     * ```tsx
-     * import { observer } from 'mobx-react-lite';
-     *
-     * const SyncIndicator = observer(() => {
-     *   if (sync.syncStatus.state === 'syncing') return <Spinner />;
-     *   if (sync.syncStatus.state === 'error') return <Error msg={sync.syncStatus.error} />;
-     *   if (sync.syncStatus.state === 'offline') return <OfflineBadge />;
-     *   return null;
-     * });
-     * ```
+     * Current connection and confirmation state. Available before ready().
+     * React reads the same value with `useAblo(ablo => ablo.status)`.
      */
-    readonly syncStatus: SyncStatus;
+    readonly status: ClientStatus;
     /**
      * Session-owned live activity projected from this client's existing
      * connection. Use `active` for every visible activity, `others` to exclude
@@ -243,7 +223,7 @@ export type AbloClient<S extends SchemaRecord> = {
      * no window in which this is absent and nothing needs to guard for one.
      */
     readonly _ws: SyncWebSocket;
-};
+}
 /**
  * The reactive-read client a `useAblo` selector receives. The same surface as
  * {@link AbloClient}, except model reads are typed as reactive rows
@@ -253,6 +233,6 @@ export type AbloClient<S extends SchemaRecord> = {
  * compile error here instead of a silent runtime `undefined`; compose
  * relations through selectors or hooks that resolve the pool's instance.
  */
-export type AbloReads<S extends SchemaRecord> = Omit<AbloClient<S>, keyof S & string> & {
+export type AbloReads<S extends SchemaRecord> = AbloCore<S> & {
     readonly [K in keyof S & string]: ModelOperations<InferRow<Schema<S>, K>, InferCreate<Schema<S>, K>>;
 };

package/dist/local/client/reactiveEngine.js

@@ -15,6 +15,7 @@ import { omittedModelError } from '@abloatai/transaction/schema/select';
 import { durableCommitOperationSchema, } from '@abloatai/transaction/commit';
 import { AbloConnectionError, AbloValidationError, claimedError } from '@abloatai/transaction/errors';
 import { batchFence, claimIdFor, fenceTokenFor, modelTarget, streamTarget, subTarget, } from '@abloatai/transaction/coordination';
+import { readStatus } from './status.js';
 import { validateAbloOptions } from './validateAbloOptions.js';
 import { startStoreLifecycle } from './storeLifecycle.js';
 import { createClaimStream } from '../sync/createClaimStream.js';
@@ -605,11 +606,9 @@ export function buildReactiveEngine(inputs) {
         waitForConfirmation(modelName, modelId) {
             return store.waitForConfirmation(modelName, modelId);
         },
-        // Expose the store's MobX observable directly — single source of truth.
-        // React components using observer() will re-render automatically on
-        // any state change (syncing, error, offline, pendingChanges, progress).
-        get syncStatus() {
-            return store.syncStatus;
+        // One core lifecycle projection; React selects the same observable reads.
+        get status() {
+            return readStatus(store);
         },
         // The humans capability owns the connection-backed presence projection.
         // Keep it on the base client as well as in the plugin surface so the

package/dist/{react/useSyncStatus.d.ts → local/client/status.d.ts}

@@ -1,4 +1,6 @@
-export type SyncStatusSnapshot = {
+import type { SyncStoreContract } from '../storeContract.js';
+/** The client lifecycle, shared by every framework binding. */
+export type ClientStatus = {
     readonly name: 'initial';
 } | {
     readonly name: 'connecting';
@@ -15,5 +17,4 @@ export type SyncStatusSnapshot = {
 } | {
     readonly name: 'needs-auth';
 };
-/** Reactively exposes the local store's connection and confirmation status. */
-export declare function useSyncStatus(): SyncStatusSnapshot;
+export declare function readStatus(store: SyncStoreContract): ClientStatus;

package/dist/local/client/status.js

@@ -0,0 +1,14 @@
+export function readStatus(store) {
+    const { state, progress, pendingChanges, isSessionError, error } = store.syncStatus;
+    if (isSessionError)
+        return { name: 'needs-auth' };
+    if (state === 'reconnecting')
+        return { name: 'reconnecting', reason: error?.message };
+    if (state === 'offline')
+        return { name: 'disconnected', reason: 'offline' };
+    if (state === 'error')
+        return { name: 'disconnected', reason: error?.message };
+    if (store.isReady)
+        return { name: 'connected', hasUnsyncedChanges: pendingChanges > 0 };
+    return { name: 'connecting', progress };
+}

package/dist/local/client/storeLifecycle.js

@@ -183,7 +183,7 @@ export function startStoreLifecycle(deps) {
                 //
                 // The store.initialize() generator updates store.syncStatus as it
                 // progresses (syncing → idle on success, error on failure), so the
-                // consumer's `sync.syncStatus` observable reflects real-time state.
+                // consumer's `ablo.status` projection reflects real-time state.
                 // Resolve bootstrap mode: explicit option wins; otherwise
                 // agents default to 'none' (transactional participant — see
                 // option doc) and everyone else defaults to 'full'.
@@ -260,7 +260,7 @@ export function startStoreLifecycle(deps) {
     if (!validationError && internalOptions.autoStart) {
         void ready().catch(() => {
             // Error is captured in store.syncStatus; consumers should check
-            // `sync.syncStatus.state === 'error'` to detect failures.
+            // `ablo.status.name === 'disconnected'` to detect failures.
         });
     }
     return {

package/dist/local/storeContract.d.ts

@@ -17,8 +17,7 @@ import type { GroupScope } from './sync/scopeGroups.js';
 /**
  * A snapshot of the client's synchronization state, shaped for binding to UI.
  * {@link SyncStoreContract.syncStatus} exposes a reactive instance of this, and
- * the `useSyncStatus()` hook reads its fields to render connection and progress
- * indicators.
+ * the client projects it into `ablo.status` for connection indicators.
  */
 export interface SyncStatus {
     state: 'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting';
@@ -112,7 +111,7 @@ export interface SyncStoreContract {
      * are backed by observable computeds, so reading them inside a reactive
      * context — an observer component or a reaction — re-runs that context when
      * the state changes. Code that prefers not to work with the reactivity system
-     * directly can read the same values through the `useSyncStatus()` hook.
+     * directly can read the same values through `useAblo(ablo => ablo.status)`.
      */
     readonly isReady: boolean;
     readonly isSyncing: boolean;
@@ -136,7 +135,7 @@ export interface SyncStoreContract {
     pinScope?(scope: GroupScope): Promise<void>;
     unpinScope?(scope: GroupScope): Promise<void>;
     /**
-     * The full reactive {@link SyncStatus} record. The `useSyncStatus()` hook
+     * The full reactive {@link SyncStatus} record. The client status projection
      * reads its fields — `state`, `progress`, `pendingChanges`, `isSessionError`,
      * and `error` — to present the current sync state. It is part of the contract
      * so hooks and test doubles can read or set it directly.

package/dist/presence/index.js

@@ -1,3 +1,4 @@
+import { observable, runInAction } from 'mobx';
 import { createPresenceProjection, } from '@abloatai/transaction/presence';
 import { startReadActivity, } from './readActivity.js';
 const clientPresence = new WeakMap();
@@ -14,10 +15,12 @@ export function presenceOfClient(client) {
 export function createPresence(transport = null) {
     let projection = null;
     let attachedTransport = null;
+    const version = observable.box(0);
     const listeners = new Set();
     const reads = new Set();
     let unsubscribe = null;
     const notify = () => {
+        runInAction(() => { version.set(version.get() + 1); });
         for (const listener of listeners)
             listener();
     };
@@ -32,8 +35,8 @@ export function createPresence(transport = null) {
     if (transport !== null)
         attach(transport);
     return {
-        get active() { return projection?.active ?? []; },
-        get others() { return projection?.others ?? []; },
+        get active() { version.get(); return projection?.active ?? []; },
+        get others() { version.get(); return projection?.others ?? []; },
         onChange(listener) {
             listeners.add(listener);
             return () => { listeners.delete(listener); };
@@ -50,6 +53,7 @@ export function createPresence(transport = null) {
             };
         },
         forModel(model, recordId) {
+            version.get();
             return projection?.forModel(model, recordId) ?? [];
         },
         dispose() {

package/dist/react/AbloProvider.d.ts

@@ -1,9 +1,6 @@
 import { type ReactNode } from 'react';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
 import type { AbloClient as Ablo } from '../client.js';
-import type { PresenceSession } from '@abloatai/transaction/presence';
-import type { GroupScope } from '../local/sync/scopeGroups.js';
-import { type SyncStoreContract } from './context.js';
 /** Reactive binding over an application-owned client. Starts readiness,
  * forwards errors and gates bootstrap; the application owns client disposal.
  */
@@ -25,127 +22,66 @@ import { type SyncStoreContract } from './context.js';
  * </AbloProvider>
  * ```
  *
- * That's it for most apps. `userId` is informational; the `fallback`,
+ * That's it for most apps. The `fallback`,
  * `preventUnsavedChanges`, and `on*` props are opt-in app glue; and the
  * block tagged "Optional DI (advanced)" below is escape-hatch wiring for
  * tests and platform builders — if you don't recognize a prop there, you
  * don't need it.
  */
-export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
-    /**
-     * A prebuilt {@link Ablo} client — **the only way to configure the engine.**
-     * Construct it yourself with `Ablo({ schema, apiKey, ... })` and pass the
-     * instance: the CLIENT owns auth, the credential lifecycle, transport, and
-     * connection; this provider is the thin REACTIVE binding over it (context,
-     * the bootstrap gate, error/​session forwarding).
-     *
-     * Memoize it (build it once, e.g. with `useMemo` or module scope) — a new
-     * instance each render re-keys the bootstrap gate and tears down the socket.
-     */
-    client: Ablo<R>;
-    /**
-     * The app user id, surfaced via `useCurrentUserId()` for app-owned fields.
-     * Purely informational for the React tree — sync identity is resolved by the
-     * client from its auth, not from this. Optional.
-     */
-    userId?: string;
-    /**
-     * Block tab close while there are unsynced local writes (the standard
-     * `beforeunload` prompt). Browsers ignore custom messages — don't pass one.
-     */
-    preventUnsavedChanges?: boolean;
-    /**
-     * Fired after the client has completed its terminal authentication cleanup
-     * (or surfaced a cleanup failure). Use it for app side effects such as a
-     * redirect to sign-in or clearing analytics identity.
-     */
-    onSessionExpired?: () => void | Promise<void>;
-    /**
-     * Fired on any error the provider surfaces (engine/WebSocket/bootstrap). For
-     * Sentry/Datadog. React-only consumers can use `useErrorListener()` instead.
-     */
-    onError?: (error: Error) => void;
-    /** @internal placeholder so the old WS-URL prop shape doesn't silently leak in. */
-    url?: never;
-    /**
-     * Rendered in place of `children` during the *first* bootstrap pass —
-     * while the engine is actively transitioning from `initial` →
-     * `connected` and has never successfully connected before. Once the
-     * engine reaches `connected` the gate latches open for the lifetime
-     * of this provider instance; transient `reconnecting` / `needs-auth`
-     * states do NOT re-show the fallback (the app's own UI handles those
-     * by then).
-     *
-     * Defaults to `<DefaultFallback />` — a neutral theme-adaptive
-     * spinner that uses `currentColor`, ships with zero design-system
-     * dependencies, and self-centers in a full-parent container. Pass
-     * your own `<Skeleton />` for a branded loading UX. Pass `null` to
-     * render nothing during bootstrap. Pass the string literal
-     * `"passthrough"` to opt out of the gate entirely — children render
-     * immediately and consumers are responsible for their own gating
-     * (`<ClientSideSuspense>` or manual `useSyncStatus()` checks).
-     * Useful for pages that mount debug helpers, error boundaries, or
-     * analytics that must run pre-ready.
-     */
-    fallback?: ReactNode | 'passthrough';
-    children: ReactNode;
+export declare function AbloProvider<R extends SchemaRecord = SchemaRecord>(props: AbloProvider.Props<R>): React.ReactElement;
+/** Props for wrappers around the provider, using the same schema parameter. */
+export declare namespace AbloProvider {
+    interface Props<R extends SchemaRecord = SchemaRecord> {
+        /**
+         * A prebuilt {@link Ablo} client — **the only way to configure the engine.**
+         * Construct it yourself with `Ablo({ schema, apiKey, ... })` and pass the
+         * instance: the CLIENT owns auth, the credential lifecycle, transport, and
+         * connection; this provider is the thin REACTIVE binding over it (context,
+         * the bootstrap gate, error/​session forwarding).
+         *
+         * Memoize it (build it once, e.g. with `useMemo` or module scope) — a new
+         * instance each render re-keys the bootstrap gate and tears down the socket.
+         */
+        client: Ablo<R>;
+        /**
+         * Block tab close while there are unsynced local writes (the standard
+         * `beforeunload` prompt). Browsers ignore custom messages — don't pass one.
+         */
+        preventUnsavedChanges?: boolean;
+        /**
+         * Fired after the client has completed its terminal authentication cleanup
+         * (or surfaced a cleanup failure). Use it for app side effects such as a
+         * redirect to sign-in or clearing analytics identity.
+         */
+        onSessionExpired?: () => void | Promise<void>;
+        /**
+         * Fired on any error the provider surfaces (engine/WebSocket/bootstrap). For
+         * Sentry/Datadog or application error UI.
+         */
+        onError?: (error: Error) => void;
+        /** @internal placeholder so the old WS-URL prop shape doesn't silently leak in. */
+        url?: never;
+        /**
+         * Rendered in place of `children` during the *first* bootstrap pass —
+         * while the engine is actively transitioning from `initial` →
+         * `connected` and has never successfully connected before. Once the
+         * engine reaches `connected` the gate latches open for the lifetime
+         * of this provider instance; transient `reconnecting` / `needs-auth`
+         * states do NOT re-show the fallback (the app's own UI handles those
+         * by then).
+         *
+         * Defaults to `<DefaultFallback />` — a neutral theme-adaptive
+         * spinner that uses `currentColor`, ships with zero design-system
+         * dependencies, and self-centers in a full-parent container. Pass
+         * your own `<Skeleton />` for a branded loading UX. Pass `null` to
+         * render nothing during bootstrap. Pass the string literal
+         * `"passthrough"` to opt out of the gate entirely — children render
+         * immediately and consumers are responsible for their own gating
+         * (for example, `useAblo(ablo => ablo.status)` checks).
+         * Useful for pages that mount debug helpers, error boundaries, or
+         * analytics that must run pre-ready.
+         */
+        fallback?: ReactNode | 'passthrough';
+        children: ReactNode;
+    }
 }
-export declare function AbloProvider<R extends SchemaRecord = SchemaRecord>(props: AbloProviderProps<R>): React.ReactElement;
-export type { GroupScope };
-/**
- * Read-only presence: the other sessions currently visible to this
- * connection, bridged to React. This is a pure reader of the engine's
- * already-flowing presence stream; it does not mutate connection groups.
- *
- * Pass `scope` to narrow to the peers on that scope's sync group(s); omit
- * it to get everyone on the engine's groups. Membership is driven entirely
- * by the presence channel (set server-side on connect, independent of any
- * cursor/collaboration traffic), so reading it never affects what the
- * connection is subscribed to and can't deadlock against a gated channel.
- *
- * Use this to answer "is anyone else here?", for example to suppress
- * live-cursor broadcasts while alone.
- *
- * ```ts
- * const peers = usePeers({ reports: reportId });
- * const alone = !peers.some((p) => p.participantKind === 'user');
- * ```
- */
-export declare function usePeers(scope?: GroupScope): readonly PresenceSession[];
-/**
- * Returns the raw `SyncEngine` proxy. Typically you want the typed
- * hooks (`useQuery`, `useOne`, `useMutate`) — this is for rare cases
- * where you need direct access (e.g., `sync.items.onChange(cb)`).
- *
- * The generic parameter narrows the return type to your schema's
- * model record so call sites get typed `sync.items.findMany()` /
- * `sync.sections.create(...)` without a cast at the call site:
- *
- * ```ts
- * const sync = useSync<(typeof schema)['models']>();
- * ```
- *
- * The runtime value is the exact engine the provider constructed;
- * the generic just widens the compile-time type.
- */
-export declare function useSync<R extends SchemaRecord = SchemaRecord>(): Ablo<R>;
-/**
- * Returns the underlying `SyncStoreContract` (the BaseSyncedStore).
- * Most consumers should prefer the typed hooks (`useQuery` etc.); this
- * is for advanced cases like direct InstanceCache access or custom
- * reactive bridges. Throws if the provider hasn't mounted the store
- * yet — wrap consumers in `<ClientSideSuspense>` to gate correctly.
- *
- * The generic parameter lets consumers widen the return type to a
- * concrete `BaseSyncedStore<...>` subclass if they track one:
- *
- * ```ts
- * type AppStore = BaseSyncedStore<AppEvents, typeof schema>;
- * const store = useSyncStore<AppStore>();  // no cast needed at call site
- * ```
- *
- * The runtime value is always the concrete store the SDK constructed,
- * so widening the type is safe. The bounded generic (`T extends
- * SyncStoreContract`) keeps the widening honest.
- */
-export declare function useSyncStore<T extends SyncStoreContract = SyncStoreContract>(): T;