@abloatai/humans 0.64.0 → 0.64.1

package/src/react/internalContext.ts

@@ -6,15 +6,6 @@ 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;
 }
 

package/src/react/useAblo.ts

@@ -1,7 +1,7 @@
 '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 type { AbloClient as Ablo, AbloReads } from '../client.js';
 import type { ModelClaim } from '@abloatai/transaction/coordination';
 import {
@@ -9,48 +9,16 @@ import {
   type ModelOperations,
 } from '../local/client/createModelOperations.js';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
+import type { ResolveModels as DefaultModels } from '@abloatai/transaction/types/global';
 import { useReactive } from './useReactive.js';
 
-/**
- * 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;
-
 const EMPTY_CLAIMS: readonly ModelClaim[] = 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<R extends SchemaRecord>(engine: Ablo<SchemaRecord>): Ablo<R> {
-  return engine as Ablo<R>;
-}
-
-/**
- * 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<R extends SchemaRecord>(engine: Ablo<R>): AbloReads<R> {
   return engine as AbloReads<R>;
 }
 
-// Selectors receive the reactive-read client: model reads are typed as
-// snapshot rows (data fields + computeds, no relation accessors), which is the
-// shape the hook actually returns after `toReactiveSnapshot()`. This makes the
-// selector's inferred result type honest — `row.layers` fails to compile here
-// instead of reading `undefined` at runtime.
 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;
@@ -74,46 +42,7 @@ function readModelResult<R extends SchemaRecord, T, C>(
   return { data, claims, claimed: claims.length > 0 };
 }
 
-/**
- * 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 function useAblo<R extends SchemaRecord = DefaultModels>(): Ablo<R> | null;
+/** Select a reactive snapshot or read a row with its current claims. */
 export function useAblo<
   R extends SchemaRecord = DefaultModels,
   T = unknown,
@@ -139,10 +68,10 @@ export function useAblo<
   T = Record<string, unknown>,
   C = unknown,
 >(
-  modelOrSelect?: ModelOperations<T, C> | ModelClientSelector<R, T, C> | AbloSelector<R, T>,
+  modelOrSelect: ModelOperations<T, C> | ModelClientSelector<R, T, C> | AbloSelector<R, T>,
   id?: string,
   options?: useAblo.Options<T>,
-): Ablo<R> | null | useAblo.Result<T> | T | undefined {
+): useAblo.Result<T> | T | undefined {
   const engine = useAbloClient<R>();
   const initial = options?.initial;
   const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
@@ -161,11 +90,10 @@ export function useAblo<
   // 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: () => void) => {
-    if (!engine || !reading) return () => undefined;
+    if (!engine) return () => undefined;
     return engine.claims.onChange(notify);
-  }, [engine, reading]);
+  }, [engine]);
   const value = useReactive<T | useAblo.Result<T> | undefined>(() => {
     if (isSelectorOnly && typeof modelOrSelect === 'function') {
       return engine ? modelOrSelect(reactiveReads<R>(engine)) as T : undefined;
@@ -186,19 +114,21 @@ export function useAblo<
     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<R extends SchemaRecord>(): Ablo<R> | null {
-  const ctx = useContext(AbloInternalContext);
-  return ctx?.engine ? rebindEngine<R>(ctx.engine) : null;
+  return value;
 }
 
 /** Type annotations belong to the operation; most callers rely on inference. */
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace useAblo {
+  export 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>;
+  }
+
   export interface Options<T> {
     /**
      * An initial row, usually from a server component or a route loader. The hook

package/src/react/useAbloClient.ts

@@ -0,0 +1,14 @@
+'use client';
+
+import { useContext } from 'react';
+import type { AbloClient } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { ResolveModels } from '@abloatai/transaction/types/global';
+import { AbloInternalContext } from './internalContext.js';
+
+/** Writable client for event handlers. Available before ready(); null without a provider. */
+export function useAbloClient<S extends SchemaRecord = ResolveModels>(): AbloClient<S> | null {
+  const client = useContext(AbloInternalContext)?.engine;
+  // React context erases the schema; the application binding restores it.
+  return client ? client as AbloClient<S> : null;
+}

package/src/react/useMutationFailure.ts

@@ -0,0 +1,17 @@
+'use client';
+
+import { useEffect, useEffectEvent } from 'react';
+import type { AbloClient } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+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: Parameters<AbloClient<SchemaRecord>['onMutationFailure']>[0],
+): void {
+  const client = useAbloClient();
+  const onFailure = useEffectEvent(listener);
+  useEffect(() => client?.onMutationFailure(onFailure), [client]);
+}

package/src/react/useMutators.ts

@@ -9,8 +9,8 @@ import type {
 import { createTransaction } from '../local/mutators/Transaction.js';
 import { createRecordingMutation } from '../local/mutators/RecordingMutation.js';
 import type { UndoScope } from '../local/mutators/UndoManager.js';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
-import { useSyncContext } from './context.js';
+import type { ResolveSchema, RequireRegisteredSchema } from '@abloatai/transaction/types/global';
+import { useAbloStoreContext } from './context.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { getContext } from '../local/context.js';
 
@@ -58,12 +58,12 @@ export function useMutators<S extends Schema, M extends MutatorDefs<S>>(
 ): useMutators.Result<M>;
 
 /** Mutator invokers via the `Register` module augmentation. Schema comes
- * from the `SyncProvider`'s context; the mutator tree is typed against
+ * from the `AbloProvider` store context; the mutator tree is typed against
  * `ResolveSchema` at the call site. */
 export function useMutators<
   M extends ResolveSchema extends Schema ? MutatorDefs<ResolveSchema> : MutatorDefs<Schema>,
 >(
-  mutators: M,
+  mutators: RequireRegisteredSchema<M>,
   options?: useMutators.Options<ResolveSchema extends Schema ? ResolveSchema : Schema>,
 ): useMutators.Result<M>;
 
@@ -72,7 +72,7 @@ export function useMutators(
   mutatorsOrOptions?: MutatorDefs<Schema> | useMutators.Options<Schema>,
   maybeOptions?: useMutators.Options<Schema>,
 ): useMutators.Result<MutatorDefs<Schema>> {
-  const { store, organizationId, schema: ctxSchema } = useSyncContext();
+  const { store, organizationId, schema: ctxSchema } = useAbloStoreContext();
 
   // Disambiguate: explicit-schema path has the schema object in first slot;
   // the global-resolved path has the mutator tree there. A schema object
@@ -92,7 +92,7 @@ export function useMutators(
     throw new AbloValidationError(
       'useMutators: no schema available. Pass the schema as the first arg, ' +
         'or build the <AbloProvider> above with `Ablo({ schema })` so the ' +
-        'zero-arg overload can read it from context.',
+        'schema-free overload can read it from context.',
       { code: 'mutators_schema_missing' },
     );
   }

package/src/react/usePresence.ts

@@ -9,16 +9,10 @@ import {
 } from '../local/client/createModelOperations.js';
 import type { AbloClient as Ablo } from '../client.js';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
-import { useAbloClient } from './useAblo.js';
+import type { ResolveModels as DefaultModels } from '@abloatai/transaction/types/global';
+import { useAbloClient } from './useAbloClient.js';
 import { useReactive } from './useReactive.js';
 
-type DefaultModels = ResolveSchema extends { models: infer M }
-  ? M extends SchemaRecord
-    ? M
-    : SchemaRecord
-  : SchemaRecord;
-
 export type PresenceModelSelector<R extends SchemaRecord, T, C> =
   (ablo: Ablo<R>) => ModelOperations<T, C>;
 
@@ -30,6 +24,7 @@ export type PresenceModelSelector<R extends SchemaRecord, T, C> =
 export function usePresence<T, C>(
   modelClient: ModelOperations<T, C>,
   recordId: string,
+  options?: usePresence.Options,
 ): readonly PresenceSession[];
 export function usePresence<
   R extends SchemaRecord = DefaultModels,
@@ -38,6 +33,7 @@ export function usePresence<
 >(
   select: PresenceModelSelector<R, T, C>,
   recordId: string,
+  options?: usePresence.Options,
 ): readonly PresenceSession[];
 export function usePresence<
   R extends SchemaRecord = DefaultModels,
@@ -46,17 +42,9 @@ export function usePresence<
 >(
   modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<R, T, C>,
   recordId: string,
+  options?: usePresence.Options,
 ): readonly PresenceSession[] {
   const engine = useAbloClient<R>();
-  return usePresenceImpl(engine, modelOrSelect, recordId);
-}
-
-/** @internal Shared by the global hook and schema-bound React factory. */
-export function usePresenceImpl<R extends SchemaRecord, T, C>(
-  engine: Ablo<R> | null,
-  modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<R, T, C>,
-  recordId: string,
-): readonly PresenceSession[] {
   if (recordId.length === 0) {
     throw new AbloValidationError(
       'usePresence requires a non-empty record id.',
@@ -77,7 +65,19 @@ export function usePresenceImpl<R extends SchemaRecord, T, C>(
   }
 
   const subscribe = useCallback((notify: () => void) => presence?.subscribe(notify) ?? (() => undefined), [presence]);
-  const sessions = useReactive(() => presence?.get(recordId) ?? [], { subscribe });
+  const sessions = useReactive(() => presence?.get(recordId, options) ?? [], { subscribe });
   useEffect(() => presence?.read(recordId), [presence, recordId]);
   return sessions;
 }
+
+export namespace usePresence {
+  export interface Bound<S extends SchemaRecord> {
+    <T, C>(
+      model: ModelOperations<T, C> | PresenceModelSelector<S, T, C>,
+      recordId: string,
+      options?: Options,
+    ): readonly PresenceSession[];
+  }
+
+  export type Options = import('@abloatai/transaction/presence').PresenceQueryOptions;
+}

package/src/react/useUndoScope.ts

@@ -7,8 +7,8 @@ import {
   type UndoScope,
   type UndoScopeOptions,
 } from '../local/mutators/UndoManager.js';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
-import { useSyncContext } from './context.js';
+import type { ResolveSchema, RequireRegisteredSchema } from '@abloatai/transaction/types/global';
+import { useAbloStoreContext } from './context.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 
 /**
@@ -30,7 +30,7 @@ import { AbloValidationError } from '@abloatai/transaction/errors';
  */
 
 // Module-level weak registry: `SyncStoreContract` → `UndoManager`.
-// A single app wiring through one SyncProvider shares one manager across
+// A single AbloProvider shares one manager across
 // every useUndoScope call, so scopes with the same name are identity-equal.
 // The hook implementation already operates on the runtime-wide `Schema` type;
 // its overloads restore the caller's precise schema type at the public boundary,
@@ -59,7 +59,7 @@ export function useUndoScope<S extends Schema>(
 
 /** Per-surface undo/redo via the `Register` module augmentation. */
 export function useUndoScope(
-  name: string,
+  name: RequireRegisteredSchema<string>,
   options?: UndoScopeOptions,
 ): useUndoScope.Result<ResolveSchema extends Schema ? ResolveSchema : Schema>;
 
@@ -68,7 +68,7 @@ export function useUndoScope(
   nameOrOptions?: string | UndoScopeOptions,
   maybeOptions?: UndoScopeOptions,
 ): useUndoScope.Result<Schema> {
-  const { store, organizationId, schema: ctxSchema } = useSyncContext();
+  const { store, organizationId, schema: ctxSchema } = useAbloStoreContext();
 
   const isExplicit = typeof schemaOrName !== 'string';
   const schema = isExplicit ? (schemaOrName) : ctxSchema;
@@ -85,7 +85,7 @@ export function useUndoScope(
   }
 
   const scope = useMemo(() => {
-    // Store is the identity for the manager — one per SyncProvider.
+    // Store is the identity for the manager — one per AbloProvider.
     const manager = getManager(store, () => new UndoManager(schema, store, organizationId));
     return manager.getScope(name, options);
     // eslint-disable-next-line react-hooks/exhaustive-deps

package/src/react.ts

@@ -2,6 +2,8 @@
 export { AbloProvider } from './react/AbloProvider.js';
 export { createAbloReact } from './react/createAbloReact.js';
 export { useAblo } from './react/useAblo.js';
+export { useAbloClient } from './react/useAbloClient.js';
+export { useMutationFailure } from './react/useMutationFailure.js';
 export { usePresence } from './react/usePresence.js';
 export { useMutators } from './react/useMutators.js';
 export { useUndoScope } from './react/useUndoScope.js';

package/src/reactRuntime.ts

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