@abloatai/humans 0.63.1 → 0.64.1

package/dist/react/useMutators.d.ts

@@ -1,7 +1,7 @@
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import type { MutatorDefs } from '../local/mutators/defineMutators.js';
 import type { UndoScope } from '../local/mutators/UndoManager.js';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
+import type { ResolveSchema, RequireRegisteredSchema } from '@abloatai/transaction/types/global';
 /**
  * Turns a mutator tree built with `defineMutators` into callable invokers. The
  * returned object mirrors that tree one-to-one, but each leaf becomes an
@@ -14,7 +14,7 @@ import type { ResolveSchema } from '@abloatai/transaction/types/global';
  * If a mutator throws, the error propagates to the caller and any writes it
  * already dispatched stay in place — there is no automatic rollback. Wrap the
  * call in your own try/catch and issue compensating writes when you need to
- * undo a partial change, or pass an `undoScope` (see {@link UseMutatorsOptions})
+ * undo a partial change, or pass an `undoScope` (see {@link useMutators.Options})
  * to record inverses for undo and redo.
  */
 /**
@@ -34,23 +34,26 @@ export type InvokerFor<F> = F extends (options: infer O) => Promise<infer R> ? O
  * The hook's return shape: same tree as the input `MutatorDefs`, every leaf
  * rewritten to its invoker form.
  */
-export type MutatorInvokers<M> = {
-    [K in keyof M]: {
-        [N in keyof M[K]]: InvokerFor<M[K][N]>;
-    };
-};
-/**
- * Options passed to `useMutators`. When `undoScope` is set, every mutator
- * invocation is wrapped in a `RecordingMutation` and its inverses are
- * pushed to the scope as one undo entry.
- */
-export interface UseMutatorsOptions<S extends Schema> {
-    /** Target undo scope for recording inverses. Omit to disable recording. */
-    undoScope?: UndoScope<S>;
-}
 /** Mutator invokers (explicit schema arg). */
-export declare function useMutators<S extends Schema, M extends MutatorDefs<S>>(schema: S, mutators: M, options?: UseMutatorsOptions<S>): MutatorInvokers<M>;
+export declare function useMutators<S extends Schema, M extends MutatorDefs<S>>(schema: S, mutators: M, options?: useMutators.Options<S>): useMutators.Result<M>;
 /** Mutator invokers via the `Register` module augmentation. Schema comes
- * from the `SyncProvider`'s context; the mutator tree is typed against
+ * from the `AbloProvider` store context; the mutator tree is typed against
  * `ResolveSchema` at the call site. */
-export declare function useMutators<M extends ResolveSchema extends Schema ? MutatorDefs<ResolveSchema> : MutatorDefs<Schema>>(mutators: M, options?: UseMutatorsOptions<ResolveSchema extends Schema ? ResolveSchema : Schema>): MutatorInvokers<M>;
+export declare function useMutators<M extends ResolveSchema extends Schema ? MutatorDefs<ResolveSchema> : MutatorDefs<Schema>>(mutators: RequireRegisteredSchema<M>, options?: useMutators.Options<ResolveSchema extends Schema ? ResolveSchema : Schema>): useMutators.Result<M>;
+/** Optional annotations for custom mutation bindings. */
+export declare namespace useMutators {
+    type Result<M> = {
+        [K in keyof M]: {
+            [N in keyof M[K]]: InvokerFor<M[K][N]>;
+        };
+    };
+    /**
+     * Options passed to `useMutators`. When `undoScope` is set, every mutator
+     * invocation is wrapped in a `RecordingMutation` and its inverses are
+     * pushed to the scope as one undo entry.
+     */
+    interface Options<S extends Schema> {
+        /** Target undo scope for recording inverses. Omit to disable recording. */
+        undoScope?: UndoScope<S>;
+    }
+}

package/dist/react/useMutators.js

@@ -2,11 +2,11 @@
 import { useMemo } from 'react';
 import { createTransaction } from '../local/mutators/Transaction.js';
 import { createRecordingMutation } from '../local/mutators/RecordingMutation.js';
-import { useSyncContext } from './context.js';
+import { useAbloStoreContext } from './context.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { getContext } from '../local/context.js';
 export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
-    const { store, organizationId, schema: ctxSchema } = useSyncContext();
+    const { store, organizationId, schema: ctxSchema } = useAbloStoreContext();
     // Disambiguate: explicit-schema path has the schema object in first slot;
     // the global-resolved path has the mutator tree there. A schema object
     // has a `.models` property; a mutator tree doesn't.
@@ -19,7 +19,7 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
     if (!schema) {
         throw new AbloValidationError('useMutators: no schema available. Pass the schema as the first arg, ' +
             'or build the <AbloProvider> above with `Ablo({ schema })` so the ' +
-            'zero-arg overload can read it from context.', { code: 'mutators_schema_missing' });
+            'schema-free overload can read it from context.', { code: 'mutators_schema_missing' });
     }
     const { undoScope } = options ?? {};
     return useMemo(() => {

package/dist/react/usePresence.d.ts

@@ -2,18 +2,18 @@ import type { PresenceSession } from '@abloatai/transaction/presence';
 import { type ModelOperations } from '../local/client/createModelOperations.js';
 import type { AbloClient as Ablo } from '../client.js';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
-type DefaultModels = ResolveSchema extends {
-    models: infer M;
-} ? M extends SchemaRecord ? M : SchemaRecord : SchemaRecord;
+import type { ResolveModels as DefaultModels } from '@abloatai/transaction/types/global';
 export type PresenceModelSelector<R extends SchemaRecord, T, C> = (ablo: Ablo<R>) => ModelOperations<T, C>;
 /**
  * Declare that this component is reading one row and return every live session
  * reading or otherwise acting on that row. Ablo owns the lease, refresh,
  * reconnect, and cleanup mechanics for the component's lifetime.
  */
-export declare function usePresence<T, C>(modelClient: ModelOperations<T, C>, recordId: string): readonly PresenceSession[];
-export declare function usePresence<R extends SchemaRecord = DefaultModels, T = Record<string, unknown>, C = unknown>(select: PresenceModelSelector<R, T, C>, recordId: string): readonly PresenceSession[];
-/** @internal Shared by the global hook and schema-bound React factory. */
-export declare function usePresenceImpl<R extends SchemaRecord, T, C>(engine: Ablo<R> | null, modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<R, T, C>, recordId: string): readonly PresenceSession[];
-export {};
+export declare function usePresence<T, C>(modelClient: ModelOperations<T, C>, recordId: string, options?: usePresence.Options): readonly PresenceSession[];
+export declare function usePresence<R extends SchemaRecord = DefaultModels, T = Record<string, unknown>, C = unknown>(select: PresenceModelSelector<R, T, C>, recordId: string, options?: usePresence.Options): readonly PresenceSession[];
+export declare namespace usePresence {
+    interface Bound<S extends SchemaRecord> {
+        <T, C>(model: ModelOperations<T, C> | PresenceModelSelector<S, T, C>, recordId: string, options?: Options): readonly PresenceSession[];
+    }
+    type Options = import('@abloatai/transaction/presence').PresenceQueryOptions;
+}

package/dist/react/usePresence.js

@@ -1,14 +1,11 @@
 'use client';
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect } from 'react';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { getModelClientMeta, } from '../local/client/createModelOperations.js';
-import { useAbloClientImpl } from './useAblo.js';
-export function usePresence(modelOrSelect, recordId) {
-    const engine = useAbloClientImpl(null);
-    return usePresenceImpl(engine, modelOrSelect, recordId);
-}
-/** @internal Shared by the global hook and schema-bound React factory. */
-export function usePresenceImpl(engine, modelOrSelect, recordId) {
+import { useAbloClient } from './useAbloClient.js';
+import { useReactive } from './useReactive.js';
+export function usePresence(modelOrSelect, recordId, options) {
+    const engine = useAbloClient();
     if (recordId.length === 0) {
         throw new AbloValidationError('usePresence requires a non-empty record id.', { code: 'invalid_request', param: 'recordId' });
     }
@@ -21,8 +18,8 @@ export function usePresenceImpl(engine, modelOrSelect, recordId) {
     if (modelClient !== null && presence === undefined) {
         throw new AbloValidationError('usePresence requires a model from the reactive Ablo client.', { code: 'invalid_request', param: 'modelClient' });
     }
-    const [, render] = useState(0);
-    useEffect(() => presence?.subscribe(() => { render((version) => version + 1); }), [presence]);
+    const subscribe = useCallback((notify) => presence?.subscribe(notify) ?? (() => undefined), [presence]);
+    const sessions = useReactive(() => presence?.get(recordId, options) ?? [], { subscribe });
     useEffect(() => presence?.read(recordId), [presence, recordId]);
-    return presence?.get(recordId) ?? [];
+    return sessions;
 }

package/dist/react/useReactive.d.ts

@@ -0,0 +1,12 @@
+interface ObservationOptions<T> {
+    equals?: (a: T, b: T) => boolean;
+    subscribe?: (listener: () => void) => () => void;
+    serverSnapshot?: () => T;
+}
+/**
+ * Each render's computation has its own observation. A suspended render cannot
+ * replace the computation used by the committed tree's subscription. Reactions
+ * start only on subscription, so abandoned renders retain no store observers.
+ */
+export declare function useReactive<T>(compute: () => T, options?: ObservationOptions<T>): T;
+export {};

package/dist/react/useReactive.js

@@ -0,0 +1,57 @@
+'use client';
+import { useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { reaction } from 'mobx';
+import { equalSnapshots, snapshotValue } from './snapshot.js';
+/**
+ * Each render's computation has its own observation. A suspended render cannot
+ * replace the computation used by the committed tree's subscription. Reactions
+ * start only on subscription, so abandoned renders retain no store observers.
+ */
+export function useReactive(compute, options = {}) {
+    const { equals = equalSnapshots, subscribe, serverSnapshot = compute } = options;
+    const committed = useRef(null);
+    const observation = useMemo(() => {
+        let cached = committed.current;
+        let server = null;
+        const failed = Symbol('selector error');
+        const read = () => {
+            const next = snapshotValue(compute());
+            if (cached === null || !equals(cached.value, next))
+                cached = { value: next };
+            return cached.value;
+        };
+        return {
+            read,
+            readServer: () => {
+                server ??= { value: snapshotValue(serverSnapshot()) };
+                return server.value;
+            },
+            subscribe: (notify) => {
+                const stop = reaction(() => {
+                    // Notify React of selector failures; React re-reads and delivers the
+                    // exception to its error boundary instead of MobX swallowing it.
+                    try {
+                        return read();
+                    }
+                    catch {
+                        return failed;
+                    }
+                }, () => { notify(); });
+                let stopExternal;
+                try {
+                    stopExternal = subscribe?.(notify);
+                }
+                catch (error) {
+                    stop();
+                    throw error;
+                }
+                return () => { stop(); stopExternal?.(); };
+            },
+        };
+    }, [compute, equals, subscribe, serverSnapshot]);
+    // read() recomputes from the actual store, including React's consistency
+    // checks between render and commit, while equal snapshots retain identity.
+    const value = useSyncExternalStore(observation.subscribe, observation.read, observation.readServer);
+    useEffect(() => { committed.current = { value }; }, [value]);
+    return value;
+}

package/dist/react/useUndoScope.d.ts

@@ -1,34 +1,20 @@
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import { type UndoScope, type UndoScopeOptions } from '../local/mutators/UndoManager.js';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
-/**
- * Provides per-surface undo and redo for mutator invocations. Each named scope
- * owns an independent undo/redo stack, so different parts of your app — a main
- * editor, a sidebar form — can undo separately without stepping on each other.
- *
- * Wire the returned `scope` into `useMutators(schema, mutators, { undoScope:
- * scope })` and those invocations become recorded. `undo()` and `redo()` replay
- * the captured inverses and forwards as new transactions that do not record
- * themselves; the manager moves the entry between the two stacks explicitly.
- *
- * @example
- * const { undo, redo, canUndo, canRedo, scope } = useUndoScope('report-editor');
- * const mutate = useMutators(schema, reportMutators, { undoScope: scope });
- *
- * // Cmd+Z handler
- * useHotkey('mod+z', () => { if (canUndo) void undo(); });
- */
-export interface UseUndoScopeResult<S extends Schema> {
-    /** Pass to `useMutators(..., { undoScope })` to enable recording. */
-    scope: UndoScope<S>;
-    undo: () => Promise<void>;
-    redo: () => Promise<void>;
-    canUndo: boolean;
-    canRedo: boolean;
-    /** Drop history. Use after sync errors / auth context changes. */
-    clear: () => void;
-}
+import type { ResolveSchema, RequireRegisteredSchema } from '@abloatai/transaction/types/global';
 /** Per-surface undo/redo (explicit schema arg). */
-export declare function useUndoScope<S extends Schema>(schema: S, name: string, options?: UndoScopeOptions): UseUndoScopeResult<S>;
+export declare function useUndoScope<S extends Schema>(schema: S, name: string, options?: UndoScopeOptions): useUndoScope.Result<S>;
 /** Per-surface undo/redo via the `Register` module augmentation. */
-export declare function useUndoScope(name: string, options?: UndoScopeOptions): UseUndoScopeResult<ResolveSchema extends Schema ? ResolveSchema : Schema>;
+export declare function useUndoScope(name: RequireRegisteredSchema<string>, options?: UndoScopeOptions): useUndoScope.Result<ResolveSchema extends Schema ? ResolveSchema : Schema>;
+/** The state returned by an undo scope; inferred for ordinary hook calls. */
+export declare namespace useUndoScope {
+    interface Result<S extends Schema> {
+        /** Pass to `useMutators(..., { undoScope })` to enable recording. */
+        scope: UndoScope<S>;
+        undo: () => Promise<void>;
+        redo: () => Promise<void>;
+        canUndo: boolean;
+        canRedo: boolean;
+        /** Drop history. Use after sync errors / auth context changes. */
+        clear: () => void;
+    }
+}

package/dist/react/useUndoScope.js

@@ -1,10 +1,27 @@
 'use client';
 import { useEffect, useMemo, useState } from 'react';
 import { UndoManager, } from '../local/mutators/UndoManager.js';
-import { useSyncContext } from './context.js';
+import { useAbloStoreContext } from './context.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
+/**
+ * Provides per-surface undo and redo for mutator invocations. Each named scope
+ * owns an independent undo/redo stack, so different parts of your app — a main
+ * editor, a sidebar form — can undo separately without stepping on each other.
+ *
+ * Wire the returned `scope` into `useMutators(schema, mutators, { undoScope:
+ * scope })` and those invocations become recorded. `undo()` and `redo()` replay
+ * the captured inverses and forwards as new transactions that do not record
+ * themselves; the manager moves the entry between the two stacks explicitly.
+ *
+ * @example
+ * const { undo, redo, canUndo, canRedo, scope } = useUndoScope('report-editor');
+ * const mutate = useMutators(schema, reportMutators, { undoScope: scope });
+ *
+ * // Cmd+Z handler
+ * useHotkey('mod+z', () => { if (canUndo) void undo(); });
+ */
 // Module-level weak registry: `SyncStoreContract` → `UndoManager`.
-// A single app wiring through one SyncProvider shares one manager across
+// A single AbloProvider shares one manager across
 // every useUndoScope call, so scopes with the same name are identity-equal.
 // The hook implementation already operates on the runtime-wide `Schema` type;
 // its overloads restore the caller's precise schema type at the public boundary,
@@ -20,7 +37,7 @@ function getManager(key, factory) {
     return m;
 }
 export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
-    const { store, organizationId, schema: ctxSchema } = useSyncContext();
+    const { store, organizationId, schema: ctxSchema } = useAbloStoreContext();
     const isExplicit = typeof schemaOrName !== 'string';
     const schema = isExplicit ? (schemaOrName) : ctxSchema;
     const name = isExplicit ? nameOrOptions : schemaOrName;
@@ -31,7 +48,7 @@ export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
             'zero-arg overload can read it from context.', { code: 'undo_scope_schema_missing' });
     }
     const scope = useMemo(() => {
-        // Store is the identity for the manager — one per SyncProvider.
+        // Store is the identity for the manager — one per AbloProvider.
         const manager = getManager(store, () => new UndoManager(schema, store, organizationId));
         return manager.getScope(name, options);
         // eslint-disable-next-line react-hooks/exhaustive-deps

package/dist/react.d.ts

@@ -1,19 +1,9 @@
-/** React bindings for the optional human-facing local-state package. */
-export { useReactive } from './useReactive.js';
-export { useCurrentUserId } from './react/useCurrentUserId.js';
-export { useErrorListener } from './react/useErrorListener.js';
-export { useSyncStatus, type SyncStatusSnapshot } from './react/useSyncStatus.js';
-export { usePresence, type PresenceModelSelector, } from './react/usePresence.js';
-export { useMutationFailureListener, type MutationFailurePayload, } from './react/useMutationFailureListener.js';
-export { AbloProvider, usePeers, useSync, useSyncStore, type AbloProviderProps, type GroupScope, } from './react/AbloProvider.js';
-export { ClientSideSuspense, type ClientSideSuspenseProps, } from './react/ClientSideSuspense.js';
-export { DefaultFallback } from './react/DefaultFallback.js';
-export { createAbloReact, type AbloReactBinding, } from './react/createAbloReact.js';
-export { useAblo, type UseAbloHydratedModelResult, type UseAbloModelOptions, type UseAbloModelResult, } from './react/useAblo.js';
-export { useMutators, type InvokerFor, type MutatorInvokers, type UseMutatorsOptions, } from './react/useMutators.js';
-export { useUndoScope, type UseUndoScopeResult, } from './react/useUndoScope.js';
-export type { DefaultSyncShape, ResolveSchema, ResolveUserMeta, ResolveClaimMeta, ResolveModelKey, } from '@abloatai/transaction/types/global';
-export { ModelScope } from '@abloatai/transaction/types';
-export type { SyncStoreContract } from './react/context.js';
-export type { MutateActions } from './local/mutators/mutateActions.js';
-export type { ReaderActions, ReaderFindOptions, } from './local/mutators/readerActions.js';
+/** React owns context, subscriptions and component lifetimes over core Ablo. */
+export { AbloProvider } from './react/AbloProvider.js';
+export { createAbloReact } from './react/createAbloReact.js';
+export { useAblo } from './react/useAblo.js';
+export { useAbloClient } from './react/useAbloClient.js';
+export { useMutationFailure } from './react/useMutationFailure.js';
+export { usePresence } from './react/usePresence.js';
+export { useMutators } from './react/useMutators.js';
+export { useUndoScope } from './react/useUndoScope.js';

package/dist/react.js

@@ -1,15 +1,9 @@
-/** React bindings for the optional human-facing local-state package. */
-export { useReactive } from './useReactive.js';
-export { useCurrentUserId } from './react/useCurrentUserId.js';
-export { useErrorListener } from './react/useErrorListener.js';
-export { useSyncStatus } from './react/useSyncStatus.js';
-export { usePresence, } from './react/usePresence.js';
-export { useMutationFailureListener, } from './react/useMutationFailureListener.js';
-export { AbloProvider, usePeers, useSync, useSyncStore, } from './react/AbloProvider.js';
-export { ClientSideSuspense, } from './react/ClientSideSuspense.js';
-export { DefaultFallback } from './react/DefaultFallback.js';
-export { createAbloReact, } from './react/createAbloReact.js';
-export { useAblo, } from './react/useAblo.js';
-export { useMutators, } from './react/useMutators.js';
-export { useUndoScope, } from './react/useUndoScope.js';
-export { ModelScope } from '@abloatai/transaction/types';
+/** React owns context, subscriptions and component lifetimes over core Ablo. */
+export { AbloProvider } from './react/AbloProvider.js';
+export { createAbloReact } from './react/createAbloReact.js';
+export { useAblo } from './react/useAblo.js';
+export { useAbloClient } from './react/useAbloClient.js';
+export { useMutationFailure } from './react/useMutationFailure.js';
+export { usePresence } from './react/usePresence.js';
+export { useMutators } from './react/useMutators.js';
+export { useUndoScope } from './react/useUndoScope.js';

package/dist/reactRuntime.d.ts

@@ -1,4 +1,4 @@
 export { AbloInternalContext, type AbloInternalContextValue, } from './react/internalContext.js';
-export { useSyncContext, type SyncReactContext, } from './react/context.js';
+export { useAbloStoreContext, type AbloStoreContextValue, } from './react/context.js';
 export type { SyncStoreContract } from './local/storeContract.js';
 export type { QueuedMutation } from './local/transactions/mutations/MutationQueue.js';

package/dist/reactRuntime.js

@@ -1,2 +1,2 @@
 export { AbloInternalContext, } from './react/internalContext.js';
-export { useSyncContext, } from './react/context.js';
+export { useAbloStoreContext, } from './react/context.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.63.1",
+  "version": "0.64.1",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -71,7 +71,8 @@
     "lint:eslint": "eslint . --cache --suppressions-location eslint-suppressions.json",
     "check:boundary": "node scripts/check-boundary.mjs",
     "test:integration": "npm run build && node scripts/check-package-integration.mjs",
-    "lint:pkg": "publint"
+    "lint:pkg": "publint",
+    "typecheck:react": "tsc -p typetests/binding/tsconfig.json"
   },
   "publishConfig": {
     "access": "public",
@@ -84,7 +85,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.63.1",
+    "@abloatai/transaction": "0.64.1",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/Ablo.ts

@@ -264,6 +264,12 @@ import type * as _Global from '@abloatai/transaction/types/global';
  */
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace Ablo {
+  /** Payload delivered by the core client's onMutationFailure subscription. */
+  export type MutationFailure = Parameters<Parameters<AbloClient<SchemaRecord>['onMutationFailure']>[0]>[0];
+  /** Current client lifecycle, also selected through React's useAblo. */
+  export type Store = import('./local/storeContract.js').SyncStoreContract;
+  export type Status = import('./local/client/status.js').ClientStatus;
+
   // ── Factory options ────────────────────────────────────────────────
   export type Options<S extends SchemaRecord = SchemaRecord> = AbloOptions<S>;
   /**
@@ -315,6 +321,7 @@ export namespace Ablo {
    * different schemas.
    */
   export type ResolveSchema = _Global.ResolveSchema;
+  export type ResolveClaimMeta = _Global.ResolveClaimMeta;
   /**
    * `ResolveSchema` guaranteed to satisfy the `Schema` bound. `ResolveSchema`
    * falls back to a loose `{ models }` shape when nothing is registered, which

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
@@ -275,7 +256,7 @@ export type AbloClient<S extends SchemaRecord> = {
 
   /**
    * The internal store. It implements {@link SyncStoreContract} — pass it to
-   * `SyncContext.Provider` so the SDK's `useModel` / `useModels` / `useMutations`
+   * `AbloStoreContext.Provider` so the SDK's React data hooks
    * hooks can reach it.
    */
   readonly _store: SyncStoreContract;
@@ -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/index.ts

@@ -39,3 +39,5 @@ export {
 export type {
   CommitLatencySample,
 } from './local/transactions/mutations/commitLatency.js';
+
+export { getAbloStore } from './local/storeAccess.js';

package/src/local/client/createModelOperations.ts

@@ -143,7 +143,7 @@ import type {
   HttpModelClient,
 } from '@abloatai/transaction/transport/http';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
-import type { PresenceSession } from '@abloatai/transaction/presence';
+import type { PresenceSession, PresenceQueryOptions } from '@abloatai/transaction/presence';
 import type {
   CollaborationEventContext,
   ModelEventEnvelope,
@@ -165,7 +165,7 @@ export interface ModelClientMeta {
   readonly key: string;
   readonly typename: string;
   readonly presence?: {
-    get(recordId: string): readonly PresenceSession[];
+    get(recordId: string, options?: PresenceQueryOptions): readonly PresenceSession[];
     subscribe(listener: () => void): () => void;
     read(recordId: string): () => void;
   };
@@ -192,7 +192,7 @@ type EntityHalf = Pick<ModelTarget, 'model' | 'id'>;
 // while reading as though they differed.
 export interface ModelCollaboration {
   /** Session projections already held by this client's one presence store. */
-  presence(model: string, recordId?: string): readonly PresenceSession[];
+  presence(model: string, recordId?: string, options?: PresenceQueryOptions): readonly PresenceSession[];
   /** Subscribe once to the connection-owned presence projection. */
   onPresenceChange(listener: () => void): () => void;
   /** Start one session-owned read activity and return its cleanup. */
@@ -1784,7 +1784,7 @@ export function createModelOperations<T, C>(
     ...(collaboration
       ? {
           presence: {
-            get: (recordId: string) => collaboration.presence(registeredModelName, recordId),
+            get: (recordId, options) => collaboration.presence(registeredModelName, recordId, options),
             subscribe: (listener: () => void) => collaboration.onPresenceChange(listener),
             read: (recordId: string) => {
               const scope = { [schemaKey]: recordId };

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';
@@ -575,7 +576,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
       modelRegistry,
       hydration,
       {
-        presence: (model, recordId) => presenceStream.forModel(model, recordId),
+        presence: (model, recordId, options) => presenceStream.forModel(model, recordId, options),
         onPresenceChange: (listener) => presenceStream.onChange(listener),
         startReadPresence: (target) => presenceStream.startRead(target),
         modelEventTarget: (recordId) => {
@@ -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.
@@ -858,11 +857,11 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 
     // ── Internal accessors for framework integration ─────────────────
     // These expose internal components for consumers that need direct
-    // access (e.g., SyncEngineProvider wiring SyncContext, collaboration
+    // access (e.g., AbloProvider wiring its store context, collaboration
     // events accessing the WebSocket handle, demand loaders accessing
     // the pool). Prefixed with _ to signal "internal but stable."
 
-    /** The BaseSyncedStore — implements SyncStoreContract for SyncContext.Provider. */
+    /** The BaseSyncedStore — implements SyncStoreContract for AbloStoreContext.Provider. */
     get _store() { return store; },
 
     /** The InstanceCache — for demand loaders that need pool.createFromData(). */