@abloatai/humans 0.64.0 → 0.64.2

package/src/local/sync/groupChange.ts

@@ -1,10 +1,13 @@
 /**
  * Handles the delta types that change which sync groups a session can see. A
- * sync group is a fan-out scope the server uses to decide which entities a
- * client receives. When a session's membership changes, these handlers update
+ * sync group connects shared state to authorized participant subscriptions.
+ * This module owns the client side of membership changes and local-state
+ * rebuilding; it neither grants server authority nor configures per-group loading.
+ * When a session's membership changes, these handlers update
  * the client's subscription list; when access is revoked, they clear cached
- * data and trigger a full re-bootstrap so revoked rows cannot linger on the
- * device.
+ * managed data and request re-bootstrap. Clients without automatic bootstrap
+ * rely on covering deltas or explicit reads instead. This cannot retract copies
+ * retained outside the managed cache.
  *
  * Every handler takes a {@link GroupChangeContext}, the narrow facade through
  * which it reaches the client's local storage and connection lifecycle hooks.

package/src/local/sync/scopeGroups.ts

@@ -2,7 +2,10 @@ import type { ClaimTarget } from '@abloatai/transaction/types/streams';
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import { scopeKindOf, type ModelDef } from '@abloatai/transaction/schema/model';
 
-/** A schema-shaped selector used to narrow connection groups and presence reads. */
+/**
+ * Selects group interest using model records or explicit group names. Resolving
+ * a selector names a requested scope; the server still checks authority.
+ */
 export type GroupScope =
   | ClaimTarget
   | readonly ClaimTarget[]

package/src/presence/index.ts

@@ -4,6 +4,7 @@ import {
   type PresenceProjection,
   type PresenceProjectionEvents,
   type PresenceView,
+  type PresenceQueryOptions,
 } from '@abloatai/transaction/presence';
 import type { PresenceTarget } from '@abloatai/transaction/presence';
 import {
@@ -16,7 +17,7 @@ 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;
 }
 
@@ -87,9 +88,9 @@ export function createPresence(
         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) read.dispose();

package/src/react/AbloProvider.tsx

@@ -11,7 +11,7 @@ import {
 } from 'react';
 import type { Schema, SchemaRecord } from '@abloatai/transaction/schema/schema';
 import type { AbloClient as Ablo } from '../client.js';
-import { SyncContext, type SyncStoreContract } from './context.js';
+import { AbloStoreContext, type SyncStoreContract } from './context.js';
 import { AbloInternalContext, type AbloInternalContextValue } from './internalContext.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { useAblo } from './useAblo.js';
@@ -100,7 +100,7 @@ export function AbloProvider<R extends SchemaRecord = SchemaRecord>(
   //      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;
@@ -158,12 +158,12 @@ export function AbloProvider<R extends SchemaRecord = SchemaRecord>(
     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 as SyncStoreContract & { orgId?: string }).orgId;
@@ -189,15 +189,15 @@ export function AbloProvider<R extends SchemaRecord = SchemaRecord>(
 
   return (
     <AbloInternalContext.Provider value={internalValue}>
-      <SyncContext.Provider value={syncValue}>
+      <AbloStoreContext.Provider value={storeContextValue}>
         {passthrough ? (
           children
-        ) : syncValue ? (
+        ) : storeContextValue ? (
           <BootstrapGate key={engineKey} fallback={fallback}>
             {children}
           </BootstrapGate>
         ) : fallback}
-      </SyncContext.Provider>
+      </AbloStoreContext.Provider>
     </AbloInternalContext.Provider>
   );
 }

package/src/react/context.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { createContext, createElement, useContext, type ReactNode } from 'react';
+import { createContext, useContext } from 'react';
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import type { SyncStoreContract } from '../local/storeContract.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
@@ -13,77 +13,26 @@ export type {
   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 const SyncContext = createContext<SyncReactContext | null>(null);
+export const AbloStoreContext = createContext<AbloStoreContextValue | null>(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(): SyncReactContext {
-  const ctx = useContext(SyncContext);
+export function useAbloStoreContext(): AbloStoreContextValue {
+  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;
 }
-
-/**
- * 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 function SyncProvider({
-  store,
-  organizationId,
-  schema,
-  children,
-}: SyncProviderProps) {
-  return createElement(
-    SyncContext.Provider,
-    { value: { store, organizationId, schema } },
-    children
-  );
-}

package/src/react/createAbloReact.ts

@@ -1,47 +1,23 @@
 'use client';
 
-/**
- * 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 { useAbloClient } from './useAbloClient.js';
+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 { usePresence, type PresenceModelSelector } from './usePresence.js';
-import type { PresenceSession } from '@abloatai/transaction/presence';
+import { usePresence } from './usePresence.js';
 
-/** What a binding returns: the provider and the hook, with `S` fixed. */
+/** 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. */
@@ -50,10 +26,6 @@ export function createAbloReact<S extends SchemaRecord>(
 ): AbloReactBinding<S> {
   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 } as AbloReactBinding<S>;
+  // Specialize the shared functions without creating new contexts or identities.
+  return { AbloProvider, useAblo, useAbloClient, useMutationFailure, usePresence } as AbloReactBinding<S>;
 }

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