@abloatai/humans 0.63.1 → 0.64.1

package/dist/react/createAbloReact.d.ts

@@ -1,54 +1,19 @@
-/**
- * The typed react binding — the schema generic is captured ONCE, at a factory
- * call in app code, and every hook the factory returns is born typed. This is
- * a schema-bound shape with no module augmentation or generic parameters at call sites,
- * and — once the legacy generic erasure retires — no casts anywhere on the
- * path from context to component.
- *
- * The app's one binding file, by convention:
- *
- * ```ts
- * // lib/ablo.ts
- * import { createAbloReact } from '@abloatai/ablo/react';
- * import { schema } from './schema';
- *
- * export const { AbloProvider, useAblo } = createAbloReact(schema);
- * ```
- *
- * Components then import `useAblo` from `lib/ablo` and never spell a type
- * argument; `useAblo()` is `Ablo<S> | null`, and a selector's `ablo`
- * parameter is the reactive-read view of the same `S`.
- */
-import { type ReactElement } from 'react';
-import { type AbloProviderProps } from './AbloProvider.js';
-import { type AbloSelector, type ModelClientSelector, type UseAbloHydratedModelResult, type UseAbloModelOptions, type UseAbloModelResult } from './useAblo.js';
+import type { ReactElement } from 'react';
+import { useMutationFailure } from './useMutationFailure.js';
+import { AbloProvider } from './AbloProvider.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: AbloProviderProps<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: UseAbloModelOptions<T> & {
-            readonly initial: T;
-        }): UseAbloHydratedModelResult<T>;
-        <T, C>(modelClientOrSelect: ModelOperations<T, C> | ModelClientSelector<S, T, C>, id: string, options?: UseAbloModelOptions<T>): UseAbloModelResult<T>;
-    };
+    AbloProvider: (props: AbloProvider.Props<S>) => ReactElement;
+    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 react surface to one schema. The schema value is taken for
- * inference — write `createAbloReact(schema)`, never a hand-spelled type
- * argument — and it is the seam where the binding's own typed context arrives
- * when the legacy erasure retires (docs/plans/typed-react-binding.md, step 3).
- */
+/** 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,58 +1,12 @@
 'use client';
-/**
- * The typed react binding — the schema generic is captured ONCE, at a factory
- * call in app code, and every hook the factory returns is born typed. This is
- * a schema-bound shape with no module augmentation or generic parameters at call sites,
- * and — once the legacy generic erasure retires — no casts anywhere on the
- * path from context to component.
- *
- * The app's one binding file, by convention:
- *
- * ```ts
- * // lib/ablo.ts
- * import { createAbloReact } from '@abloatai/ablo/react';
- * import { schema } from './schema';
- *
- * export const { AbloProvider, useAblo } = createAbloReact(schema);
- * ```
- *
- * Components then import `useAblo` from `lib/ablo` and never spell a type
- * argument; `useAblo()` is `Ablo<S> | null`, and a selector's `ablo`
- * parameter is the reactive-read view of the same `S`.
- */
-import { createContext, createElement, useContext } from 'react';
-import { AbloProvider, } from './AbloProvider.js';
-import { useAbloImpl, useAbloClientImpl, } from './useAblo.js';
-import { usePresenceImpl, } from './usePresence.js';
-/**
- * Bind the react surface to one schema. The schema value is taken for
- * inference — write `createAbloReact(schema)`, never a hand-spelled type
- * argument — and it is the seam where the binding's own typed context arrives
- * when the legacy erasure retires (docs/plans/typed-react-binding.md, step 3).
- */
+import { useAbloClient } from './useAbloClient.js';
+import { useMutationFailure } from './useMutationFailure.js';
+import { AbloProvider } from './AbloProvider.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;
-    // The binding's own context — created here, AFTER the schema generic is
-    // known, so it is typed `Ablo<S>` from birth. A hook that reads it never rebinds and
-    // never casts; a binding hook mounted under a legacy provider (no bound
-    // provider in the tree) reads `null` here and falls through to the shared
-    // implementation's internal-context fallback.
-    const BoundClientContext = createContext(null);
-    function BoundAbloProvider(props) {
-        return createElement(BoundClientContext.Provider, { value: props.client }, createElement((AbloProvider), props));
-    }
-    function useBoundAblo(modelOrSelect, id, options) {
-        const bound = useContext(BoundClientContext);
-        return useAbloImpl(bound, modelOrSelect, id, options);
-    }
-    function useBoundPresence(modelOrSelect, recordId) {
-        const bound = useContext(BoundClientContext);
-        const engine = useAbloClientImpl(bound);
-        return usePresenceImpl(engine, modelOrSelect, recordId);
-    }
-    return {
-        AbloProvider: BoundAbloProvider,
-        useAblo: useBoundAblo,
-        usePresence: useBoundPresence,
-    };
+    // Specialize the shared functions without creating new contexts or identities.
+    return { AbloProvider, useAblo, useAbloClient, useMutationFailure, usePresence };
 }

package/dist/react/internalContext.d.ts

@@ -1,33 +1,7 @@
 import type { AbloClient as Ablo } from '../client.js';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
-/**
- * The context that `<AbloProvider>` populates for its own hooks. It is kept
- * separate from the data-hook context, which carries the store and schema,
- * because these fields belong to the provider rather than to the store. Read
- * them through the typed hooks such as `useCurrentUserId` and
- * `useErrorListener` rather than reaching into this context directly.
- */
+/** The provider owns only the reference to the application-owned client. */
 export interface AbloInternalContextValue {
-    /**
-     * The application user id, when your app passed one to `<AbloProvider>`. Sync
-     * identity is derived on the server from the API key, so this is `null`
-     * unless you set it, and it is not required for sync to work.
-     */
-    currentUserId: string | null;
-    /** Subscribe to provider-level errors: engine errors, bootstrap failures, and session issues. */
-    subscribeError: (listener: (error: Error) => void) => () => void;
-    /** Emit an error to every subscribed listener. The provider calls this for you. */
-    emitError: (error: Error) => void;
-    /**
-     * The typed `Ablo` client for this provider, or `null` until the first sync
-     * bootstrap resolves. It is held here so `useSync()` 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. `useSync<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/snapshot.d.ts

@@ -0,0 +1,4 @@
+/** Read and detach selected data while the enclosing reaction tracks its fields. */
+export declare function snapshotValue<T>(value: T): T;
+/** Compare data snapshots, including non-enumerable schema-derived fields. */
+export declare function equalSnapshots(a: unknown, b: unknown): boolean;

package/dist/react/snapshot.js

@@ -0,0 +1,75 @@
+import { isObservableObject } from 'mobx';
+import { Model } from '../local/Model.js';
+import { getModelClientMeta } from '../local/client/createModelOperations.js';
+function isRecord(value) {
+    return Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null;
+}
+/** Read and detach selected data while the enclosing reaction tracks its fields. */
+export function snapshotValue(value) {
+    const seen = new WeakMap();
+    function visit(input) {
+        if (input === null || typeof input !== 'object')
+            return input;
+        if (seen.has(input))
+            return seen.get(input);
+        // A selected model namespace is an API handle, not row data. Preserve its
+        // identity so it can still be passed to presence and other core operations.
+        if (getModelClientMeta(input))
+            return input;
+        if (input instanceof Date) {
+            const date = new Date(input.getTime());
+            seen.set(input, date);
+            return Object.freeze(date);
+        }
+        if (Array.isArray(input)) {
+            const array = new Array(input.length);
+            seen.set(input, array);
+            input.forEach((item, index) => { array[index] = visit(item); });
+            return Object.freeze(array);
+        }
+        const source = input instanceof Model ? input.toReactiveSnapshot() : input;
+        if (!isRecord(source))
+            return input;
+        const result = Object.getPrototypeOf(source) === null ? Object.create(null) : {};
+        seen.set(input, result);
+        // MobX's own symbols describe its administration, not selected application data.
+        const keys = isObservableObject(source) ? Object.keys(source) : Reflect.ownKeys(source);
+        for (const key of keys) {
+            Object.defineProperty(result, key, {
+                value: visit(Reflect.get(source, key)),
+                enumerable: Object.prototype.propertyIsEnumerable.call(source, key),
+            });
+        }
+        return Object.freeze(result);
+    }
+    return visit(value);
+}
+/** Compare data snapshots, including non-enumerable schema-derived fields. */
+export function equalSnapshots(a, b) {
+    const seen = new WeakMap();
+    function equal(left, right) {
+        if (Object.is(left, right))
+            return true;
+        if (left === null || right === null || typeof left !== 'object' || typeof right !== 'object')
+            return false;
+        if (left instanceof Date || right instanceof Date) {
+            return left instanceof Date && right instanceof Date && Object.is(left.getTime(), right.getTime());
+        }
+        if (Array.isArray(left) !== Array.isArray(right))
+            return false;
+        if (!Array.isArray(left) && (!isRecord(left) || !isRecord(right)))
+            return false;
+        if (Object.getPrototypeOf(left) !== Object.getPrototypeOf(right))
+            return false;
+        if (seen.has(left))
+            return seen.get(left) === right;
+        seen.set(left, right);
+        const keys = Reflect.ownKeys(left);
+        if (keys.length !== Reflect.ownKeys(right).length)
+            return false;
+        return keys.every(key => Object.prototype.hasOwnProperty.call(right, key)
+            && Object.prototype.propertyIsEnumerable.call(left, key) === Object.prototype.propertyIsEnumerable.call(right, key)
+            && equal(Reflect.get(left, key), Reflect.get(right, key)));
+    }
+    return equal(a, b);
+}

package/dist/react/useAblo.d.ts

@@ -1,98 +1,34 @@
-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;
-export interface UseAbloModelOptions<T> {
-    /**
-     * An initial row, usually from a server component or a route loader. The hook
-     * returns it until sync delivers a newer row for the same id.
-     */
-    readonly initial?: T;
-}
-export interface UseAbloModelResult<T> {
-    /** The current row for the id, or `initial` until the row has synced. */
-    readonly data: T | undefined;
-    /** The work claims currently held on this row by any participant. */
-    readonly claims: readonly ModelClaim[];
-    /** True while another participant holds a claim — handy for disabling UI. */
-    readonly claimed: boolean;
-}
-export type UseAbloHydratedModelResult<T> = Omit<UseAbloModelResult<T>, 'data'> & {
-    readonly data: 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 no-argument form returns `null` while the engine is still bootstrapping.
- * Branch on `null` and render a loading state — or gate on `useSyncStatus()`
- * reaching `'connected'` — before calling model methods.
- */
-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: UseAbloModelOptions<T> & {
-    readonly initial: T;
-}): UseAbloHydratedModelResult<T>;
-export declare function useAblo<R extends SchemaRecord = DefaultModels, T = Record<string, unknown>, C = unknown>(select: ModelClientSelector<R, T, C>, id: string, options: UseAbloModelOptions<T> & {
-    readonly initial: T;
-}): UseAbloHydratedModelResult<T>;
-export declare function useAblo<T, C>(modelClient: ModelOperations<T, C>, id: string, options?: UseAbloModelOptions<T>): UseAbloModelResult<T>;
-export declare function useAblo<R extends SchemaRecord = DefaultModels, T = Record<string, unknown>, C = unknown>(select: ModelClientSelector<R, T, C>, id: string, options?: UseAbloModelOptions<T>): UseAbloModelResult<T>;
-/**
- * @internal The one implementation behind `useAblo` and the bound hooks a
- * `createAbloReact` binding returns — written once so the reactive read path
- * cannot fork between the global hook and a factory's.
- *
- * `boundClient` is a binding's own context value — typed `Ablo<S>` at the
- * factory, so that path never rebinds and never casts. `null` means "no
- * binding provider in this tree": the global hook always passes it, and a
- * binding hook mounted under a legacy provider falls through to the erased
- * internal context, which is what keeps both mounts working while the last
- * legacy mount migrates.
- */
-export declare function useAbloImpl<R extends SchemaRecord, T = Record<string, unknown>, C = unknown>(boundClient: Ablo<R> | null, modelOrSelect?: ModelOperations<T, C> | ModelClientSelector<R, T, C> | AbloSelector<R, T>, id?: string, options?: UseAbloModelOptions<T>): Ablo<R> | null | UseAbloModelResult<T> | T | undefined;
-/** @internal Resolve the bound or legacy provider client through one rebind seam. */
-export declare function useAbloClientImpl<R extends SchemaRecord>(boundClient: Ablo<R> | null): Ablo<R> | null;
-export {};
+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>;
+/** 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
+         * uses it for hydration and until a local row has been observed. A later
+         * local removal returns undefined instead of restoring this seed.
+         */
+        readonly initial?: T;
+    }
+    interface Result<T> {
+        /** The local row or its initial seed. Undefined is a local cache miss, not proof of server absence. */
+        readonly data: T | undefined;
+        /** The work claims currently held on this row by any participant. */
+        readonly claims: readonly ModelClaim[];
+        /** True while another participant holds a claim — handy for disabling UI. */
+        readonly claimed: boolean;
+    }
+}

package/dist/react/useAblo.js

@@ -1,25 +1,10 @@
 'use client';
-import { useContext, useEffect, useState } 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 { Model } from '../local/Model.js';
-import { useReactive } from '../useReactive.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;
 }
@@ -27,50 +12,15 @@ function readModelResult(engine, modelClient, id, initial) {
     if (!modelClient || id === undefined) {
         return { data: initial, claims: EMPTY_CLAIMS, claimed: false };
     }
-    const data = snapshotValue(modelClient.local.get(id) ?? initial);
+    const data = modelClient.local.get(id) ?? initial;
     const meta = getModelClientMeta(modelClient);
     const claims = meta && engine
         ? engine.claims.list({ model: meta.key, id })
         : EMPTY_CLAIMS;
     return { data, claims, claimed: claims.length > 0 };
 }
-/**
- * Projects a reactive read into the value that `useReactive` caches and
- * returns.
- *
- * For a `Model`, this reads the row's fields through `toReactiveSnapshot`
- * rather than returning the instance itself. Property access is what subscribes
- * the reaction to those fields, so the read has to happen inside this tracked
- * function; returning the live instance without reading its fields would leave
- * the component blind to later edits. The fresh object it produces also lets
- * `useReactive`'s equality check detect an in-place update.
- */
-function snapshotValue(value) {
-    if (value instanceof Model) {
-        return value.toReactiveSnapshot();
-    }
-    if (Array.isArray(value)) {
-        return value.map((item) => snapshotValue(item));
-    }
-    return value;
-}
 export function useAblo(modelOrSelect, id, options) {
-    return useAbloImpl(null, modelOrSelect, id, options);
-}
-/**
- * @internal The one implementation behind `useAblo` and the bound hooks a
- * `createAbloReact` binding returns — written once so the reactive read path
- * cannot fork between the global hook and a factory's.
- *
- * `boundClient` is a binding's own context value — typed `Ablo<S>` at the
- * factory, so that path never rebinds and never casts. `null` means "no
- * binding provider in this tree": the global hook always passes it, and a
- * binding hook mounted under a legacy provider falls through to the erased
- * internal context, which is what keeps both mounts working while the last
- * legacy mount migrates.
- */
-export function useAbloImpl(boundClient, modelOrSelect, id, options) {
-    const engine = useAbloClientImpl(boundClient);
+    const engine = useAbloClient();
     const initial = options?.initial;
     const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
     const modelClient = typeof modelOrSelect === 'function' && id !== undefined
@@ -80,43 +30,36 @@ export function useAbloImpl(boundClient, modelOrSelect, id, options) {
         : typeof modelOrSelect === 'function'
             ? undefined
             : modelOrSelect;
-    // Claims arrive through an event emitter (engine.claims), not through MobX, so
-    // the useReactive reactions below cannot track them; we bridge changes with a
-    // setState bump instead. Subscribe the model-row form (`id !== undefined`)
-    // to claims. Selector-only reads track MobX model data; callers displaying
-    // ownership use the row form's `claims` / `claimed` result.
-    const [claimVersion, setClaimVersion] = useState(0);
-    useEffect(() => {
-        if (!engine || id === undefined)
-            return;
-        return engine.claims.onChange(() => { setClaimVersion((version) => version + 1); });
-    }, [engine, id]);
-    const selected = useReactive(() => {
-        if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {
-            return undefined;
+    // The initial row is a seed for this client/model/id, not a permanent
+    // fallback: once local data has been committed to the UI, its removal must
+    // not resurrect the seed. Only committed effects change this marker.
+    // 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 subscribe = useCallback((notify) => {
+        if (!engine)
+            return () => undefined;
+        return engine.claims.onChange(notify);
+    }, [engine]);
+    const value = useReactive(() => {
+        if (isSelectorOnly && typeof modelOrSelect === 'function') {
+            return engine ? modelOrSelect(reactiveReads(engine)) : undefined;
         }
-        // The selector runs against the real engine — reads inside it return the
-        // pool's model instances. `snapshotValue` then converts the RESULT to
-        // plain snapshot rows, which is what the selector's `AbloReads`
-        // parameter type already promised.
-        return snapshotValue(modelOrSelect(reactiveReads(engine)));
-    });
-    const modelResult = useReactive(() => {
-        void claimVersion;
-        return readModelResult(engine, modelClient, id, initial);
+        if (modelOrSelect) {
+            return readModelResult(engine, modelClient, id, seed.received ? undefined : initial);
+        }
+        return undefined;
+    }, {
+        subscribe,
+        // The same seed produces the server HTML and the first hydration render,
+        // even if the browser already has a newer row or claim in its local cache.
+        ...(id !== undefined && initial !== undefined ? {
+            serverSnapshot: () => ({ data: initial, claims: EMPTY_CLAIMS, claimed: false }),
+        } : {}),
     });
-    if (isSelectorOnly)
-        return selected;
-    if (modelOrSelect)
-        return modelResult;
-    return engine;
-}
-/** @internal Resolve the bound or legacy provider client through one rebind seam. */
-export function useAbloClientImpl(boundClient) {
-    const ctx = useContext(AbloInternalContext);
-    // The bound client wins — it is already `Ablo<R>`, no rebinding. The
-    // fallback is the ONE remaining schema rebind in the SDK; it retires with
-    // the last legacy provider mount (docs/plans/typed-react-binding.md).
-    const engine = boundClient ?? (ctx?.engine ? rebindEngine(ctx.engine) : null);
-    return engine;
+    useEffect(() => {
+        if (id !== undefined && modelClient?.local.get(id) !== undefined)
+            seed.received = true;
+    }, [seed, modelClient, id, value]);
+    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]);
+}