@abloatai/humans 0.63.1 → 0.64.0

package/dist/react/AbloProvider.js

@@ -1,38 +1,42 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
-import { useCallback, useContext, useEffect, useMemo, useRef, useState, createContext, } from 'react';
-import { resolveScopeGroups } from '../local/sync/scopeGroups.js';
+import { useCallback, useEffect, useMemo, useRef, useState, createContext, } from 'react';
 import { SyncContext } from './context.js';
 import { AbloInternalContext } from './internalContext.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
-import { useSyncStatus } from './useSyncStatus.js';
+import { useAblo } from './useAblo.js';
 import { DefaultFallback } from './DefaultFallback.js';
-import { presenceOfClient } from '../presence/index.js';
-// ── Implementation ───────────────────────────────────────────────────
+/** Reactive binding over an application-owned client. Starts readiness,
+ * forwards errors and gates bootstrap; the application owns client disposal.
+ */
+// ── Props ────────────────────────────────────────────────────────────
 /**
- * Lightweight event emitter for provider-level errors. Lives on the
- * provider instance (ref-based) so `useErrorListener` subscriptions
- * survive re-renders without thrashing.
+ * Props for `<AbloProvider>`.
+ *
+ * The one required prop is a prebuilt {@link Ablo} client — the client
+ * owns auth and the credential lifecycle; this provider is the reactive
+ * binding over it:
+ *
+ * ```tsx
+ * // Build once at module scope — a new instance per render tears down the socket.
+ * // The endpoint string points at your session-mint route (`ablo init`
+ * // scaffolds it); the SDK fetches it and keeps the token fresh.
+ * const ablo = Ablo({ schema, session: { endpoint: '/api/ablo-session' } });
+ *
+ * <AbloProvider client={ablo}>
+ *   <App />
+ * </AbloProvider>
+ * ```
+ *
+ * That's it for most apps. The `fallback`,
+ * `preventUnsavedChanges`, and `on*` props are opt-in app glue; and the
+ * block tagged "Optional DI (advanced)" below is escape-hatch wiring for
+ * tests and platform builders — if you don't recognize a prop there, you
+ * don't need it.
  */
-function createErrorEmitter() {
-    const listeners = new Set();
-    return {
-        subscribe(fn) {
-            listeners.add(fn);
-            return () => { listeners.delete(fn); };
-        },
-        emit(err) {
-            for (const fn of listeners) {
-                try {
-                    fn(err);
-                }
-                catch { }
-            }
-        },
-    };
-}
+// ── Implementation ───────────────────────────────────────────────────
 export function AbloProvider(props) {
-    const { client, userId, preventUnsavedChanges, onSessionExpired, onError, fallback = _jsx(DefaultFallback, {}), children, } = props;
+    const { client, preventUnsavedChanges, onSessionExpired, onError, fallback = _jsx(DefaultFallback, {}), children, } = props;
     // The client IS the engine — synchronous, never null. This provider is a
     // REACTIVE binding over it (context + bootstrap gate + error/session
     // forwarding); it does NOT construct, configure, or own the connection. The
@@ -45,19 +49,16 @@ export function AbloProvider(props) {
     // Account scope isn't a prop — read it from `_store.orgId` once `ready()`
     // resolves the identity from the client's auth.
     const [resolvedScope, setResolvedScope] = useState(null);
-    // ── Error emitter (provider-instance scoped) ─────────────────────
-    const errorEmitterRef = useRef(null);
-    if (!errorEmitterRef.current) {
-        errorEmitterRef.current = createErrorEmitter();
-    }
-    const errorEmitter = errorEmitterRef.current;
     // Stash callbacks in refs so a new identity each render doesn't re-run the
     // start effect (the `useEventCallback` idiom).
     const onErrorRef = useRef(onError);
     onErrorRef.current = onError;
-    useEffect(() => {
-        return errorEmitter.subscribe((err) => onErrorRef.current?.(err));
-    }, [errorEmitter]);
+    const reportError = useCallback((error) => {
+        try {
+            onErrorRef.current?.(error);
+        }
+        catch { /* Error reporting must not interrupt session cleanup. */ }
+    }, []);
     const onSessionExpiredRef = useRef(onSessionExpired);
     onSessionExpiredRef.current = onSessionExpired;
     // Re-key the bootstrap gate when the client INSTANCE changes — a genuinely new
@@ -79,16 +80,16 @@ export function AbloProvider(props) {
     useEffect(() => {
         let stale = false;
         const unsubscribeSession = engine.onSessionError((err) => {
-            errorEmitter.emit(err);
+            reportError(err);
             void (async () => {
                 try {
                     await onSessionExpiredRef.current?.();
                 }
                 catch (hookErr) {
-                    errorEmitter.emit(hookErr);
+                    reportError(hookErr);
                 }
             })().catch(() => {
-                // Only a throwing errorEmitter subscriber can land here — it was
+                // This was
                 // already the error-reporting path, so swallow rather than surface
                 // an unhandled rejection loop.
             });
@@ -106,13 +107,13 @@ export function AbloProvider(props) {
             .catch((err) => {
             if (stale)
                 return;
-            errorEmitter.emit(err);
+            reportError(err);
         });
         return () => {
             stale = true;
             unsubscribeSession();
         };
-    }, [engine, errorEmitter]);
+    }, [engine, reportError]);
     // ── beforeunload + preventUnsavedChanges ─────────────────────────
     useEffect(() => {
         if (typeof window === 'undefined')
@@ -146,13 +147,10 @@ export function AbloProvider(props) {
             schema,
         };
     }, [engine, resolvedScope, schema]);
-    // ── Internal context (currentUserId + error subscription) ────────
+    // The React tree holds the same client used by core code.
     const internalValue = useMemo(() => ({
-        currentUserId: userId ?? null,
-        subscribeError: errorEmitter.subscribe,
-        emitError: errorEmitter.emit,
         engine: engine,
-    }), [userId, errorEmitter, engine]);
+    }), [engine]);
     // ── Render ───────────────────────────────────────────────────────
     //
     // Keep the context tree stable during startup so passthrough children retain
@@ -172,118 +170,15 @@ export function AbloProvider(props) {
  * a new "first bootstrap" cycle.
  */
 function BootstrapGate({ fallback, children, }) {
-    const status = useSyncStatus();
+    const status = useAblo(ablo => ablo.status);
     const [everConnected, setEverConnected] = useState(false);
     useEffect(() => {
-        if (status.name === 'connected' ||
-            status.name === 'reconnecting' ||
-            status.name === 'disconnected') {
+        if (status?.name === 'connected' ||
+            status?.name === 'reconnecting' ||
+            status?.name === 'disconnected') {
             setEverConnected(true);
         }
-    }, [status.name]);
-    const showFallback = !everConnected && status.name === 'connecting';
+    }, [status?.name]);
+    const showFallback = !everConnected && status?.name === 'connecting';
     return _jsx(_Fragment, { children: showFallback ? fallback : children });
 }
-const EMPTY_PRESENCE = Object.freeze([]);
-/**
- * Read-only presence: the other sessions currently visible to this
- * connection, bridged to React. This is a pure reader of the engine's
- * already-flowing presence stream; it does not mutate connection groups.
- *
- * Pass `scope` to narrow to the peers on that scope's sync group(s); omit
- * it to get everyone on the engine's groups. Membership is driven entirely
- * by the presence channel (set server-side on connect, independent of any
- * cursor/collaboration traffic), so reading it never affects what the
- * connection is subscribed to and can't deadlock against a gated channel.
- *
- * Use this to answer "is anyone else here?", for example to suppress
- * live-cursor broadcasts while alone.
- *
- * ```ts
- * const peers = usePeers({ reports: reportId });
- * const alone = !peers.some((p) => p.participantKind === 'user');
- * ```
- */
-export function usePeers(scope) {
-    const ctx = useContext(AbloInternalContext);
-    const engine = ctx?.engine ?? null;
-    // Resolve scope → groups through the schema.
-    // The stringified, sorted key is the stable effect dependency.
-    const scopeKey = JSON.stringify(resolveScopeGroups(scope, engine?.schema).sort());
-    const groups = useMemo(() => JSON.parse(scopeKey), [scopeKey]);
-    const [peers, setPeers] = useState(EMPTY_PRESENCE);
-    useEffect(() => {
-        if (!engine) {
-            setPeers(EMPTY_PRESENCE);
-            return;
-        }
-        const presence = presenceOfClient(engine);
-        const compute = () => groups.length === 0
-            ? presence.others
-            : presence.others.filter((session) => session.activities.some(({ target }) => target.id !== undefined && groups.includes(`${target.model.toLowerCase()}:${target.id}`)));
-        // Plain useState + onChange — presence changes on connect/disconnect/activity
-        // only (never on cursor traffic, a separate channel), so this fires
-        // rarely; a frame of stale presence is harmless.
-        setPeers(compute());
-        return presence.onChange(() => { setPeers(compute()); });
-    }, [engine, groups, scopeKey]);
-    return peers;
-}
-// ── Escape-hatches: raw engine/store access ──────────────────────────
-/**
- * Returns the raw `SyncEngine` proxy. Typically you want the typed
- * hooks (`useQuery`, `useOne`, `useMutate`) — this is for rare cases
- * where you need direct access (e.g., `sync.items.onChange(cb)`).
- *
- * The generic parameter narrows the return type to your schema's
- * model record so call sites get typed `sync.items.findMany()` /
- * `sync.sections.create(...)` without a cast at the call site:
- *
- * ```ts
- * const sync = useSync<(typeof schema)['models']>();
- * ```
- *
- * The runtime value is the exact engine the provider constructed;
- * the generic just widens the compile-time type.
- */
-export function useSync() {
-    const ctx = useContext(AbloInternalContext);
-    if (!ctx) {
-        throw new AbloValidationError('useSync: no <AbloProvider> mounted above this component.', { code: 'no_ablo_provider' });
-    }
-    if (!ctx.engine) {
-        throw new AbloValidationError('useSync: the sync engine has not yet initialized. Wrap your ' +
-            'consumer in <ClientSideSuspense> or guard on useSyncStatus().', { code: 'sync_not_ready' });
-    }
-    return rebindProviderEngine(ctx.engine);
-}
-function rebindProviderEngine(engine) {
-    return engine;
-}
-/**
- * Returns the underlying `SyncStoreContract` (the BaseSyncedStore).
- * Most consumers should prefer the typed hooks (`useQuery` etc.); this
- * is for advanced cases like direct InstanceCache access or custom
- * reactive bridges. Throws if the provider hasn't mounted the store
- * yet — wrap consumers in `<ClientSideSuspense>` to gate correctly.
- *
- * The generic parameter lets consumers widen the return type to a
- * concrete `BaseSyncedStore<...>` subclass if they track one:
- *
- * ```ts
- * type AppStore = BaseSyncedStore<AppEvents, typeof schema>;
- * const store = useSyncStore<AppStore>();  // no cast needed at call site
- * ```
- *
- * The runtime value is always the concrete store the SDK constructed,
- * so widening the type is safe. The bounded generic (`T extends
- * SyncStoreContract`) keeps the widening honest.
- */
-export function useSyncStore() {
-    const sync = useContext(SyncContext);
-    if (!sync?.store) {
-        throw new AbloValidationError('useSyncStore: the sync engine has not yet initialized. Wrap ' +
-            'consumers in <ClientSideSuspense> or guard on useSyncStatus().', { code: 'sync_not_ready' });
-    }
-    return sync.store;
-}

package/dist/react/createAbloReact.d.ts

@@ -1,27 +1,13 @@
 /**
- * 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.
+ * Capture schema inference once while reusing module-level React functions.
+ * This helper creates no components, hooks, contexts or client instances.
  *
- * 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`.
+ * Define the app binding at module scope:
+ * `export const { AbloProvider, useAblo, usePresence } = createAbloReact(schema)`.
  */
-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 { AbloProvider } from './AbloProvider.js';
+import { useAblo, type AbloSelector, type ModelClientSelector } 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';
@@ -31,24 +17,16 @@ import type { PresenceSession } from '@abloatai/transaction/presence';
 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;
+    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: UseAbloModelOptions<T> & {
-            readonly initial: T;
-        }): UseAbloHydratedModelResult<T>;
-        <T, C>(modelClientOrSelect: ModelOperations<T, C> | ModelClientSelector<S, T, C>, id: string, options?: UseAbloModelOptions<T>): UseAbloModelResult<T>;
+        <T, C>(modelClientOrSelect: ModelOperations<T, C> | ModelClientSelector<S, T, C>, id: string, options?: useAblo.Options<T>): useAblo.Result<T>;
     };
     /** 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[];
 }
-/**
- * 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,14 @@
 '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 { 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,
-    };
+    // 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 };
 }

package/dist/react/internalContext.d.ts

@@ -1,31 +1,14 @@
 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
+     * 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. `useSync<R>()` restores the precise type through its
+     * 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;

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

@@ -14,24 +14,6 @@ type DefaultModels = ResolveSchema extends {
 } ? M extends SchemaRecord ? M : SchemaRecord : SchemaRecord;
 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
@@ -66,33 +48,34 @@ export type UseAbloHydratedModelResult<T> = Omit<UseAbloModelResult<T>, 'data'>
  * 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.
+ * 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;
 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 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 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;
+    }
+}
 export {};