@abloatai/humans 0.64.0 → 0.64.1

package/dist/Ablo.d.ts

@@ -89,6 +89,7 @@ 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 Store = import('./local/storeContract.js').SyncStoreContract;
     type Status = import('./local/client/status.js').ClientStatus;
     type Options<S extends SchemaRecord = SchemaRecord> = AbloOptions<S>;
     /**
@@ -123,6 +124,7 @@ export declare namespace Ablo {
      * different schemas.
      */
     type ResolveSchema = _Global.ResolveSchema;
+    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/dist/client.d.ts

@@ -210,7 +210,7 @@ interface AbloCore<S extends SchemaRecord> {
     subscribe<K extends keyof CoreSyncEventMap>(event: K, handler: (...args: CoreSyncEventMap[K]) => void): () => void;
     /**
      * 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;

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export { createTransaction, type Transaction, type ReaderFindOptions, } from './
 export { ClaimLog, formatClaim, formatConflict, type ClaimLogEntry, } from './local/coordination/ClaimLog.js';
 export { isStorageOpenTimeout, } from './local/stores/openIDBWithTimeout.js';
 export type { CommitLatencySample, } from './local/transactions/mutations/commitLatency.js';
+export { getAbloStore } from './local/storeAccess.js';

package/dist/index.js

@@ -4,3 +4,4 @@ export { defineMutators, } from './local/mutators/defineMutators.js';
 export { createTransaction, } from './local/mutators/Transaction.js';
 export { ClaimLog, formatClaim, formatConflict, } from './local/coordination/ClaimLog.js';
 export { isStorageOpenTimeout, } from './local/stores/openIDBWithTimeout.js';
+export { getAbloStore } from './local/storeAccess.js';

package/dist/local/client/createModelOperations.d.ts

@@ -22,14 +22,14 @@ export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease
 import type { ClaimApi, ClaimAttemptEvent, LocalCountOptions, LocalReadOptions } from '@abloatai/transaction/client/resources/modelOperations';
 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, ModelEventInput, ModelEventTarget } from '@abloatai/transaction/collaboration';
 import { type ReadSetContext } from '@abloatai/transaction/internal/read-set';
 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;
     };
@@ -42,7 +42,7 @@ export declare function getModelClientMeta(modelClient: unknown): ModelClientMet
 type EntityHalf = Pick<ModelTarget, 'model' | 'id'>;
 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. */

package/dist/local/client/createModelOperations.js

@@ -1091,7 +1091,7 @@ hydration, collaboration, readSetContext) {
         ...(collaboration
             ? {
                 presence: {
-                    get: (recordId) => collaboration.presence(registeredModelName, recordId),
+                    get: (recordId, options) => collaboration.presence(registeredModelName, recordId, options),
                     subscribe: (listener) => collaboration.onPresenceChange(listener),
                     read: (recordId) => {
                         const scope = { [schemaKey]: recordId };

package/dist/local/client/reactiveEngine.js

@@ -395,7 +395,7 @@ export function buildReactiveEngine(inputs) {
     for (const [schemaKey, modelDef] of Object.entries(schema.models)) {
         const registeredModelName = modelDef.typename ?? schemaKey;
         modelProxies[schemaKey] = createModelOperations(schemaKey, registeredModelName, objectPool, syncClient, 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) => {
@@ -617,10 +617,10 @@ export function buildReactiveEngine(inputs) {
         schema,
         // ── 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(). */
         get _pool() { return objectPool; },

package/dist/local/mutators/defineMutators.d.ts

@@ -1,60 +1,15 @@
-/**
- * Declares a tree of named custom mutators grouped by model key. Each mutator is
- * a plain async function that receives `{ tx, args }` and composes any number of
- * `tx.mutations.*` and `tx.read.*` calls to carry out a named operation, such as
- * `sections.createWithBlocks`.
- *
- * The function is purely a place for types to anchor and returns its input
- * unchanged; the runtime that dispatches a mutator lives elsewhere — the
- * transaction object it receives and the React hook that invokes it. Because
- * `defineMutators(schema, { ... })` returns the exact object you wrote,
- * `typeof mutators` carries every mutator's precise `args` and result types
- * through to wherever they are invoked.
- */
+/** Define typed named operations. Pass the schema explicitly across package boundaries. */
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import type { Transaction } from './Transaction.js';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
-/**
- * `ResolveSchema` narrowed to satisfy the `Schema` bound — mirrors
- * {@link Ablo.RegisteredSchema}. When nothing is registered, `ResolveSchema`
- * is a loose `{ models }` shape that doesn't extend `Schema`, so we fall back
- * to `Schema` to keep the mutator tree typed rather than collapsing.
- */
+import type { ResolveSchema, RequireRegisteredSchema } from '@abloatai/transaction/types/global';
 type RegisteredSchema = ResolveSchema extends Schema ? ResolveSchema : Schema;
-/**
- * The signature of a single custom mutator. The engine supplies `tx`; you control
- * `args`, in whatever shape you like, and the resolved return value. `TArgs` and
- * `TResult` are bounded by `unknown` rather than `any`, so a mixed tree of
- * mutators can be typed together without falling back to `any`.
- */
 export type MutatorFn<S extends Schema, TArgs, TResult = void> = (options: {
     tx: Transaction<S>;
     args: TArgs;
 }) => Promise<TResult>;
-/**
- * The shape {@link defineMutators} accepts: an optional record per model key
- * whose values are named mutator functions. The `unknown` bounds keep the public
- * boundary type-safe without `any`; when you write your mutators inline,
- * TypeScript still infers the concrete `args` and result of each function, so the
- * `unknown` here is only a ceiling, not what you end up working with.
- */
 export type MutatorDefs<S extends Schema> = {
     [K in keyof S['models']]?: Record<string, MutatorFn<S, never, unknown>>;
 };
-/**
- * Returns the mutators object unchanged while constraining its shape against the
- * schema. The `S` generic pins the model keys, and the `M` generic is inferred as
- * a `const`, so each mutator's literal signature survives. There is no runtime
- * work here; the function exists purely as a place for type inference to anchor.
- */
 export declare function defineMutators<S extends Schema, const M extends MutatorDefs<S>>(_schema: S, mutators: M): M;
-/**
- * Register-anchored overload: omit the schema value and the tree is typed
- * against `ResolveSchema` (this app's registered schema). Shared product code
- * used across apps that bind different schemas should use this form — it moves
- * with each app's `Register` instead of pinning one concrete schema, so the
- * mutator tree stays assignable at every consumer (which reads the same
- * `Register`). See docs/plans/per-product-schema-projections.md.
- */
-export declare function defineMutators<const M extends MutatorDefs<RegisteredSchema>>(mutators: M): M;
+export declare function defineMutators<const M extends MutatorDefs<RegisteredSchema>>(mutators: RequireRegisteredSchema<M>): M;
 export {};

package/dist/local/mutators/defineMutators.js

@@ -1,18 +1,3 @@
-/**
- * Declares a tree of named custom mutators grouped by model key. Each mutator is
- * a plain async function that receives `{ tx, args }` and composes any number of
- * `tx.mutations.*` and `tx.read.*` calls to carry out a named operation, such as
- * `sections.createWithBlocks`.
- *
- * The function is purely a place for types to anchor and returns its input
- * unchanged; the runtime that dispatches a mutator lives elsewhere — the
- * transaction object it receives and the React hook that invokes it. Because
- * `defineMutators(schema, { ... })` returns the exact object you wrote,
- * `typeof mutators` carries every mutator's precise `args` and result types
- * through to wherever they are invoked.
- */
 export function defineMutators(schemaOrMutators, maybeMutators) {
-    // The schema argument is a type anchor only — never read at runtime. With one
-    // argument the mutator tree is in the first slot; with two it's in the second.
     return (maybeMutators ?? schemaOrMutators);
 }

package/dist/local/storeAccess.d.ts

@@ -0,0 +1,7 @@
+import type { AbloClient } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { SyncStoreContract } from './storeContract.js';
+/** Access the supported local store contract for custom framework adapters,
+ * demand loading, scope management and custom undo infrastructure.
+ */
+export declare function getAbloStore<S extends SchemaRecord>(client: AbloClient<S>): SyncStoreContract;

package/dist/local/storeAccess.js

@@ -0,0 +1,6 @@
+/** Access the supported local store contract for custom framework adapters,
+ * demand loading, scope management and custom undo infrastructure.
+ */
+export function getAbloStore(client) {
+    return client._store;
+}

package/dist/presence/index.d.ts

@@ -1,10 +1,10 @@
-import { type PresenceProjection, type PresenceProjectionEvents, type PresenceView } from '@abloatai/transaction/presence';
+import { type PresenceProjection, type PresenceProjectionEvents, type PresenceView, type PresenceQueryOptions } from '@abloatai/transaction/presence';
 import type { PresenceTarget } from '@abloatai/transaction/presence';
 import { type ReadActivityTransport } from './readActivity.js';
 type PresenceTransport = PresenceProjectionEvents & ReadActivityTransport;
 /** Reactive-client presence backed by the client's existing live connection. */
 export interface ReactivePresence extends PresenceView {
-    forModel(model: string, recordId?: string): ReturnType<PresenceProjection['forModel']>;
+    forModel(model: string, recordId?: string, options?: PresenceQueryOptions): ReturnType<PresenceProjection['forModel']>;
     onChange(listener: () => void): () => void;
 }
 /** Lifecycle hooks kept inside the humans composition boundary. */

package/dist/presence/index.js

@@ -52,9 +52,9 @@ export function createPresence(transport = null) {
                 lifetime.stop();
             };
         },
-        forModel(model, recordId) {
+        forModel(model, recordId, options) {
             version.get();
-            return projection?.forModel(model, recordId) ?? [];
+            return projection?.forModel(model, recordId, options) ?? [];
         },
         dispose() {
             for (const read of reads)

package/dist/react/AbloProvider.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState, createContext, } from 'react';
-import { SyncContext } from './context.js';
+import { AbloStoreContext } from './context.js';
 import { AbloInternalContext } from './internalContext.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { useAblo } from './useAblo.js';
@@ -75,7 +75,7 @@ export function AbloProvider(props) {
     //      onSessionExpired. Credential cleanup lives in the CLIENT, so direct
     //      consumers and React consumers have the same security boundary.
     //   2. Drive `ready()` (idempotent) so bootstrap starts on mount, then read the
-    //      resolved org scope for SyncContext.
+    //      resolved org scope for the Ablo store context.
     // It does NOT dispose the client (consumer-owned) and does NOT touch auth.
     useEffect(() => {
         let stale = false;
@@ -131,12 +131,12 @@ export function AbloProvider(props) {
         window.addEventListener('beforeunload', handler);
         return () => { window.removeEventListener('beforeunload', handler); };
     }, [engine, preventUnsavedChanges]);
-    // ── SyncContext value (for useQuery/useOne/useMutate hooks) ──────
+    // ── Store context value (for Ablo data hooks) ────────────────────
     //
     // The engine is always present (it's the `client` prop), but its org scope is
-    // unknown until `ready()` resolves identity — so `syncValue` is null until
+    // unknown until `ready()` resolves identity — so the store context is null until
     // then, which drives the initial fallback below.
-    const syncValue = useMemo(() => {
+    const storeContextValue = useMemo(() => {
         const currentAccountScope = (resolvedScope?.engine === engine ? resolvedScope.account : null) ??
             engine._store.orgId;
         if (!currentAccountScope)
@@ -156,7 +156,7 @@ export function AbloProvider(props) {
     // Keep the context tree stable during startup so passthrough children retain
     // their component state when authenticated row scope becomes available.
     const passthrough = fallback === 'passthrough';
-    return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: _jsx(SyncContext.Provider, { value: syncValue, children: passthrough ? (children) : syncValue ? (_jsx(BootstrapGate, { fallback: fallback, children: children }, engineKey)) : fallback }) }));
+    return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: _jsx(AbloStoreContext.Provider, { value: storeContextValue, children: passthrough ? (children) : storeContextValue ? (_jsx(BootstrapGate, { fallback: fallback, children: children }, engineKey)) : fallback }) }));
 }
 /**
  * Internal gate that renders `fallback` only during the very first

package/dist/react/context.d.ts

@@ -1,55 +1,16 @@
-import { type ReactNode } from 'react';
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import type { SyncStoreContract } from '../local/storeContract.js';
 export type { SyncStoreContract, LocalMutation, } from '../local/storeContract.js';
-export interface SyncReactContext {
+export interface AbloStoreContextValue {
     store: SyncStoreContract;
     /** The organization id used as the default scope for reads and writes. */
     organizationId: string;
-    /**
-     * An optional schema. When provided, hooks that take a model by name (such as
-     * `useQuery('items')`) read that model's metadata from this schema, so
-     * callers don't pass a schema at every call site. When omitted, those hooks
-     * require the schema as an argument instead.
-     *
-     * The field is loosely typed here because a single runtime context value is
-     * shared by every hook. Precise per-model types come from your `Register`
-     * module augmentation
-     * (`declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`),
-     * not from this reference.
-     */
+    /** Runtime schema used by ambient mutator overloads. */
     schema?: Schema;
 }
-export declare const SyncContext: import("react").Context<SyncReactContext | null>;
+export declare const AbloStoreContext: import("react").Context<AbloStoreContextValue | null>;
 /**
- * Reads the sync store context from inside a provider subtree, throwing a clear
- * error when no provider is mounted above. `<AbloProvider>` supplies this
- * context by rendering the internal {@link SyncProvider}; you wire
- * `<AbloProvider client={ablo}>` rather than touching this directly.
+ * Reads the store scope owned by `<AbloProvider>`, throwing a clear error when
+ * no provider is mounted above it.
  */
-export declare function useSyncContext(): SyncReactContext;
-/**
- * Props for SyncProvider.
- */
-export interface SyncProviderProps {
-    /** The sync store, which must implement {@link SyncStoreContract}. */
-    store: SyncStoreContract;
-    /** The organization id used as the default scope for reads and writes. */
-    organizationId: string;
-    /**
-     * An optional schema. Provide it to enable hooks that take a model by name
-     * (such as `useQuery('items')`); the model types also narrow through your
-     * `Register` augmentation. Omit it to pass the schema to those hooks directly
-     * instead.
-     */
-    schema?: Schema;
-    children?: ReactNode;
-}
-/**
- * A low-level provider that places a built sync store on React context so the
- * data hooks can reach it. This is an internal building block: it is not part
- * of the package's public entry point. Reach for `<AbloProvider>` instead,
- * which builds the store from your `Ablo({ schema, apiKey })` client and
- * renders this provider underneath.
- */
-export declare function SyncProvider({ store, organizationId, schema, children, }: SyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SyncReactContext | null>>;
+export declare function useAbloStoreContext(): AbloStoreContextValue;

package/dist/react/context.js

@@ -1,29 +1,17 @@
 'use client';
-import { createContext, createElement, useContext } from 'react';
+import { createContext, useContext } from 'react';
 import { AbloValidationError } from '@abloatai/transaction/errors';
-export const SyncContext = createContext(null);
+export const AbloStoreContext = createContext(null);
 /**
- * Reads the sync store context from inside a provider subtree, throwing a clear
- * error when no provider is mounted above. `<AbloProvider>` supplies this
- * context by rendering the internal {@link SyncProvider}; you wire
- * `<AbloProvider client={ablo}>` rather than touching this directly.
+ * Reads the store scope owned by `<AbloProvider>`, throwing a clear error when
+ * no provider is mounted above it.
  */
-export function useSyncContext() {
-    const ctx = useContext(SyncContext);
+export function useAbloStoreContext() {
+    const ctx = useContext(AbloStoreContext);
     if (!ctx) {
-        throw new AbloValidationError('Sync hooks must be used within an <AbloProvider>.', {
-            code: 'sync_context_missing_provider',
+        throw new AbloValidationError('Ablo hooks must be used within an <AbloProvider>.', {
+            code: 'ablo_context_missing_provider',
         });
     }
     return ctx;
 }
-/**
- * A low-level provider that places a built sync store on React context so the
- * data hooks can reach it. This is an internal building block: it is not part
- * of the package's public entry point. Reach for `<AbloProvider>` instead,
- * which builds the store from your `Ablo({ schema, apiKey })` client and
- * renders this provider underneath.
- */
-export function SyncProvider({ store, organizationId, schema, children, }) {
-    return createElement(SyncContext.Provider, { value: { store, organizationId, schema } }, children);
-}

package/dist/react/createAbloReact.d.ts

@@ -1,32 +1,19 @@
-/**
- * Capture schema inference once while reusing module-level React functions.
- * This helper creates no components, hooks, contexts or client instances.
- *
- * Define the app binding at module scope:
- * `export const { AbloProvider, useAblo, usePresence } = createAbloReact(schema)`.
- */
 import type { ReactElement } from 'react';
+import { useMutationFailure } from './useMutationFailure.js';
 import { AbloProvider } from './AbloProvider.js';
-import { useAblo, type AbloSelector, type ModelClientSelector } from './useAblo.js';
+import { useAblo } from './useAblo.js';
 import type { AbloClient as Ablo } from '../client.js';
-import type { ModelOperations } from '../local/client/createModelOperations.js';
 import type { Schema, SchemaRecord } from '@abloatai/transaction/schema/schema';
-import { type PresenceModelSelector } from './usePresence.js';
-import type { PresenceSession } from '@abloatai/transaction/presence';
-/** What a binding returns: the provider and the hook, with `S` fixed. */
+import { usePresence } from './usePresence.js';
+/** Shared provider and hooks specialized to one schema. */
 export interface AbloReactBinding<S extends SchemaRecord> {
-    /** `AbloProvider` with its `client` prop typed `Ablo<S>` — same component,
-     *  no per-app generics. */
     AbloProvider: (props: AbloProvider.Props<S>) => ReactElement;
-    /** `useAblo` with the schema bound — the same overloads as the global
-     *  hook, minus the type arguments. */
-    useAblo: {
-        (): Ablo<S> | null;
-        <T>(select: AbloSelector<S, T>): T | undefined;
-        <T, C>(modelClientOrSelect: ModelOperations<T, C> | ModelClientSelector<S, T, C>, id: string, options?: useAblo.Options<T>): useAblo.Result<T>;
-    };
+    useAblo: useAblo.Bound<S>;
+    /** Writable client for actions; useAblo(selector) supplies render snapshots. */
+    useAbloClient: () => Ablo<S> | null;
+    useMutationFailure: typeof useMutationFailure;
     /** Declare and reactively read record presence with the same model clients. */
-    usePresence: <T, C>(modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<S, T, C>, recordId: string) => readonly PresenceSession[];
+    usePresence: usePresence.Bound<S>;
 }
 /** Bind the existing React functions to one schema's types. */
 export declare function createAbloReact<S extends SchemaRecord>(schema: Schema<S>): AbloReactBinding<S>;

package/dist/react/createAbloReact.js

@@ -1,14 +1,12 @@
 'use client';
+import { useAbloClient } from './useAbloClient.js';
+import { useMutationFailure } from './useMutationFailure.js';
 import { AbloProvider } from './AbloProvider.js';
-import { useAblo, } from './useAblo.js';
+import { useAblo } from './useAblo.js';
 import { usePresence } from './usePresence.js';
 /** Bind the existing React functions to one schema's types. */
 export function createAbloReact(schema) {
     void schema;
-    // TypeScript cannot partially specialize the generic overloads, so this
-    // assertion binds their schema parameter. Positive and negative consumer
-    // type tests verify the specialization; no runtime value changes.
-    // Specialize types only. Every binding uses the same module-level functions,
-    // so calling this helper again cannot change component identity or reset state.
-    return { AbloProvider, useAblo, usePresence };
+    // Specialize the shared functions without creating new contexts or identities.
+    return { AbloProvider, useAblo, useAbloClient, useMutationFailure, usePresence };
 }

package/dist/react/internalContext.d.ts

@@ -2,15 +2,6 @@ import type { AbloClient as Ablo } from '../client.js';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
 /** The provider owns only the reference to the application-owned client. */
 export interface AbloInternalContextValue {
-    /**
-     * The typed `Ablo` client for this provider, available before bootstrap resolves. It is held here so `useAblo()` can return it without
-     * reaching into the store; the client and the store are sibling objects, and
-     * neither is derived from the other.
-     *
-     * It is typed loosely as `Ablo<SchemaRecord>` because generics do not flow
-     * through React context. `useAblo<R>()` restores the precise type through its
-     * own generic; the runtime value is the fully typed client.
-     */
     engine: Ablo<SchemaRecord> | null;
 }
 export declare const AbloInternalContext: import("react").Context<AbloInternalContextValue | null>;

package/dist/react/useAblo.d.ts

@@ -1,66 +1,20 @@
-import type { AbloClient as Ablo, AbloReads } from '../client.js';
+import type { AbloReads } from '../client.js';
 import type { ModelClaim } from '@abloatai/transaction/coordination';
 import { type ModelOperations } from '../local/client/createModelOperations.js';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
-/**
- * The app's resolved schema-record type. It reads your `Register` module
- * augmentation when you declare one and falls back to the loose
- * {@link SchemaRecord} otherwise, so `useAblo()` returns a fully typed client
- * without you passing `<(typeof schema)['models']>` at every call site.
- */
-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 ModelClientSelector<R extends SchemaRecord, T, C> = (ablo: AbloReads<R>) => ModelOperations<T, C>;
 export type AbloSelector<R extends SchemaRecord, T> = (ablo: AbloReads<R>) => T;
-/**
- * Reads Ablo from inside an `<AbloProvider>` subtree. Called with no arguments
- * it returns the typed client for use in callbacks and effects; called with a
- * selector it subscribes the component to a reactive read — such as one
- * `ablo.<model>` row — and re-renders when that read changes.
- *
- * You can call it with no type arguments once you declare the `Register` module
- * augmentation (`declare module '@abloatai/ablo' { interface Register {
- * Schema: typeof schema } }`); the default type then resolves through your
- * schema's models, so call sites stay clean:
- *
- * **Prefer the binding.** `createAbloReact(schema)` captures the schema once
- * in your app's binding file and returns a `useAblo` that needs none of the
- * typing arrangements below — no type argument, no `Register` declaration
- * (see `react.md`). Passing an explicit schema type argument to THIS hook is
- * deprecated in favor of that binding; it keeps working for shared packages
- * that cannot bind a concrete schema.
- *
- * ```ts
- * // With the Register augmentation (recommended):
- * const ablo = useAblo();
- * if (!ablo) return <Loading />;
- * const doc = await ablo.records.get({ id }); // observational async server read
- *
- * // Reactive selector (a synchronous local snapshot). The selector's reads
- * // are typed as snapshot rows — data fields + computeds, no relation
- * // accessors — matching what the hook actually returns:
- * const doc = useAblo((ablo) => ablo.records.local.get(id)) ?? serverDoc;
- * const { claimed } = useAblo((ablo) => ablo.records, id);
- *
- * // Without the augmentation, pass the schema as a type argument:
- * const ablo = useAblo<(typeof schema)['models']>();
- * ```
- *
- * The client and its status are available during provider startup. Select
- * `ablo.status` to display connection state; await `ablo.ready()` before
- * operations that require an initialized client. Without a provider, the
- * no-argument form returns `null` and selectors return `undefined`.
- */
-export declare function useAblo<R extends SchemaRecord = DefaultModels>(): Ablo<R> | null;
+/** Select a reactive snapshot or read a row with its current claims. */
 export declare function useAblo<R extends SchemaRecord = DefaultModels, T = unknown>(select: AbloSelector<R, T>): T | undefined;
 export declare function useAblo<T, C>(modelClient: ModelOperations<T, C>, id: string, options?: useAblo.Options<T>): useAblo.Result<T>;
 export declare function useAblo<R extends SchemaRecord = DefaultModels, T = Record<string, unknown>, C = unknown>(select: ModelClientSelector<R, T, C>, id: string, options?: useAblo.Options<T>): useAblo.Result<T>;
-/** @internal Resolve the nearest provider's client through one schema rebind. */
-export declare function useAbloClient<R extends SchemaRecord>(): Ablo<R> | null;
 /** Type annotations belong to the operation; most callers rely on inference. */
 export declare namespace useAblo {
+    interface Bound<S extends SchemaRecord> {
+        <T>(select: AbloSelector<S, T>): T | undefined;
+        <T, C>(model: ModelOperations<T, C> | ModelClientSelector<S, T, C>, id: string, options?: Options<T>): Result<T>;
+    }
     interface Options<T> {
         /**
          * An initial row, usually from a server component or a route loader. The hook
@@ -78,4 +32,3 @@ export declare namespace useAblo {
         readonly claimed: boolean;
     }
 }
-export {};

package/dist/react/useAblo.js

@@ -1,24 +1,10 @@
 'use client';
-import { useCallback, useContext, useEffect, useMemo } from 'react';
-import { AbloInternalContext } from './internalContext.js';
+import { useCallback, useEffect, useMemo } from 'react';
+import { useAbloClient } from './useAbloClient.js';
 import { getModelClientMeta, } from '../local/client/createModelOperations.js';
 import { useReactive } from './useReactive.js';
 const EMPTY_CLAIMS = Object.freeze([]);
-/**
- * Restore the caller's schema generics on the context-held engine. React
- * context erases generics (see `AbloInternalContextValue.engine`), so this is
- * the one deliberate rebind point: the runtime value is the fully typed
- * client, and `R` is the compile-time view the calling hook declared.
- */
-function rebindEngine(engine) {
-    return engine;
-}
-/**
- * The reactive-read view of a client — the identical runtime object, with
- * model reads typed as snapshot rows, because everything a selector returns
- * is converted through `snapshotValue` before the hook hands it back. Same
- * generic in and out, so this compiles with no schema rebinding.
- */
+// Selector results are detached snapshots with no model methods or relations.
 function reactiveReads(engine) {
     return engine;
 }
@@ -50,12 +36,11 @@ export function useAblo(modelOrSelect, id, options) {
     // These dependencies define when the seed belongs to a different row.
     // eslint-disable-next-line react-hooks/exhaustive-deps
     const seed = useMemo(() => ({ received: false }), [engine, modelClient, id]);
-    const reading = modelOrSelect !== undefined;
     const subscribe = useCallback((notify) => {
-        if (!engine || !reading)
+        if (!engine)
             return () => undefined;
         return engine.claims.onChange(notify);
-    }, [engine, reading]);
+    }, [engine]);
     const value = useReactive(() => {
         if (isSelectorOnly && typeof modelOrSelect === 'function') {
             return engine ? modelOrSelect(reactiveReads(engine)) : undefined;
@@ -76,12 +61,5 @@ export function useAblo(modelOrSelect, id, options) {
         if (id !== undefined && modelClient?.local.get(id) !== undefined)
             seed.received = true;
     }, [seed, modelClient, id, value]);
-    if (isSelectorOnly || modelOrSelect)
-        return value;
-    return engine;
-}
-/** @internal Resolve the nearest provider's client through one schema rebind. */
-export function useAbloClient() {
-    const ctx = useContext(AbloInternalContext);
-    return ctx?.engine ? rebindEngine(ctx.engine) : null;
+    return value;
 }

package/dist/react/useAbloClient.d.ts

@@ -0,0 +1,5 @@
+import type { AbloClient } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { ResolveModels } from '@abloatai/transaction/types/global';
+/** Writable client for event handlers. Available before ready(); null without a provider. */
+export declare function useAbloClient<S extends SchemaRecord = ResolveModels>(): AbloClient<S> | null;

package/dist/react/useAbloClient.js

@@ -0,0 +1,9 @@
+'use client';
+import { useContext } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+/** Writable client for event handlers. Available before ready(); null without a provider. */
+export function useAbloClient() {
+    const client = useContext(AbloInternalContext)?.engine;
+    // React context erases the schema; the application binding restores it.
+    return client ? client : null;
+}

package/dist/react/useMutationFailure.d.ts

@@ -0,0 +1,6 @@
+import type { AbloClient } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+/** Subscribe for this component's lifetime using the latest committed listener.
+ * Replacing the provider client moves the subscription; unmount removes it.
+ */
+export declare function useMutationFailure(listener: Parameters<AbloClient<SchemaRecord>['onMutationFailure']>[0]): void;

package/dist/react/useMutationFailure.js

@@ -0,0 +1,11 @@
+'use client';
+import { useEffect, useEffectEvent } from 'react';
+import { useAbloClient } from './useAbloClient.js';
+/** Subscribe for this component's lifetime using the latest committed listener.
+ * Replacing the provider client moves the subscription; unmount removes it.
+ */
+export function useMutationFailure(listener) {
+    const client = useAbloClient();
+    const onFailure = useEffectEvent(listener);
+    useEffect(() => client?.onMutationFailure(onFailure), [client]);
+}