@abloatai/humans 0.63.0 → 0.64.0

package/src/client.ts

@@ -19,9 +19,9 @@ import type {
   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,
@@ -39,7 +39,10 @@ export type AbloClient<S extends SchemaRecord> = {
     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.
@@ -65,7 +68,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
@@ -205,32 +208,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
@@ -290,7 +271,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
@@ -301,7 +282,7 @@ 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/src/local/client/reactiveEngine.ts

@@ -29,6 +29,7 @@ import {
 	streamTarget,
 	subTarget,
 } from '@abloatai/transaction/coordination';
+import { readStatus } from './status.js';
 import { validateAbloOptions } from './validateAbloOptions.js';
 import type { StoreCluster } from './storeCluster.js';
 import { startStoreLifecycle } from './storeLifecycle.js';
@@ -842,11 +843,9 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
       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.

package/src/local/client/status.ts

@@ -0,0 +1,20 @@
+import type { SyncStoreContract } from '../storeContract.js';
+
+/** The client lifecycle, shared by every framework binding. */
+export type ClientStatus =
+  | { readonly name: 'initial' }
+  | { readonly name: 'connecting'; readonly progress: number }
+  | { readonly name: 'connected'; readonly hasUnsyncedChanges: boolean }
+  | { readonly name: 'reconnecting'; readonly reason?: string }
+  | { readonly name: 'disconnected'; readonly reason?: string }
+  | { readonly name: 'needs-auth' };
+
+export function readStatus(store: SyncStoreContract): ClientStatus {
+  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/src/local/client/storeLifecycle.ts

@@ -301,7 +301,7 @@ export function startStoreLifecycle<S extends SchemaRecord>(
         //
         // 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'.
@@ -386,7 +386,7 @@ export function startStoreLifecycle<S extends SchemaRecord>(
   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.
     });
   }
 

package/src/local/storeContract.ts

@@ -19,8 +19,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';
@@ -115,7 +114,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;
@@ -137,7 +136,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/src/presence/index.ts

@@ -1,3 +1,4 @@
+import { observable, runInAction } from 'mobx';
 import {
   createPresenceProjection,
   type PresenceProjection,
@@ -44,11 +45,13 @@ export function createPresence(
 ): AttachablePresence {
   let projection: PresenceProjection | null = null;
   let attachedTransport: PresenceTransport | null = null;
+  const version = observable.box(0);
   const listeners = new Set<() => void>();
   const reads = new Set<ReadActivityLifetime>();
   let unsubscribe: (() => void) | null = null;
 
   const notify = (): void => {
+    runInAction(() => { version.set(version.get() + 1); });
     for (const listener of listeners) listener();
   };
 
@@ -63,8 +66,8 @@ export function createPresence(
   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); };
@@ -85,6 +88,7 @@ export function createPresence(
       };
     },
     forModel(model, recordId) {
+      version.get();
       return projection?.forModel(model, recordId) ?? [];
     },
     dispose() {