@abloatai/humans 0.63.0 → 0.64.0

package/src/react/createAbloReact.ts

@@ -1,55 +1,31 @@
 '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.
+ * 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 { createContext, createElement, useContext, type ReactElement } from 'react';
+import type { ReactElement } from 'react';
+import { AbloProvider } from './AbloProvider.js';
 import {
-  AbloProvider,
-  type AbloProviderProps,
-} from './AbloProvider.js';
-import {
-  useAbloImpl,
-  useAbloClientImpl,
+  useAblo,
   type AbloSelector,
   type ModelClientSelector,
-  type UseAbloHydratedModelResult,
-  type UseAbloModelOptions,
-  type UseAbloModelResult,
 } 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 {
-  usePresenceImpl,
-  type PresenceModelSelector,
-} from './usePresence.js';
+import { usePresence, type PresenceModelSelector } from './usePresence.js';
 import type { PresenceSession } from '@abloatai/transaction/presence';
 
 /** What a binding returns: the provider and the hook, with `S` fixed. */
 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: {
@@ -58,13 +34,8 @@ export interface AbloReactBinding<S extends SchemaRecord> {
     <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>;
+      options?: useAblo.Options<T>,
+    ): useAblo.Result<T>;
   };
   /** Declare and reactively read record presence with the same model clients. */
   usePresence: <T, C>(
@@ -73,68 +44,16 @@ export interface AbloReactBinding<S extends SchemaRecord> {
   ) => 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 function createAbloReact<S extends SchemaRecord>(
   schema: Schema<S>,
 ): AbloReactBinding<S> {
   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<Ablo<S> | null>(null);
-
-  function BoundAbloProvider(props: AbloProviderProps<S>): ReactElement {
-    return createElement(
-      BoundClientContext.Provider,
-      { value: props.client },
-      createElement(AbloProvider<S>, props),
-    );
-  }
-
-  function useBoundAblo(): Ablo<S> | null;
-  function useBoundAblo<T>(select: AbloSelector<S, T>): T | undefined;
-  function useBoundAblo<T, C>(
-    modelClientOrSelect: ModelOperations<T, C> | ModelClientSelector<S, T, C>,
-    id: string,
-    options: UseAbloModelOptions<T> & { readonly initial: T },
-  ): UseAbloHydratedModelResult<T>;
-  function useBoundAblo<T, C>(
-    modelClientOrSelect: ModelOperations<T, C> | ModelClientSelector<S, T, C>,
-    id: string,
-    options?: UseAbloModelOptions<T>,
-  ): UseAbloModelResult<T>;
-  function useBoundAblo<T, C>(
-    modelOrSelect?:
-      | ModelOperations<T, C>
-      | ModelClientSelector<S, T, C>
-      | AbloSelector<S, T>,
-    id?: string,
-    options?: UseAbloModelOptions<T>,
-  ): Ablo<S> | null | UseAbloModelResult<T> | T | undefined {
-    const bound = useContext(BoundClientContext);
-    return useAbloImpl<S, T, C>(bound, modelOrSelect, id, options);
-  }
-
-  function useBoundPresence<T, C>(
-    modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<S, T, C>,
-    recordId: string,
-  ): readonly PresenceSession[] {
-    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 } as AbloReactBinding<S>;
 }

package/src/react/internalContext.ts

@@ -4,32 +4,15 @@ import { createContext } from 'react';
 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/src/react/snapshot.ts

@@ -0,0 +1,67 @@
+import { isObservableObject } from 'mobx';
+import { Model } from '../local/Model.js';
+import { getModelClientMeta } from '../local/client/createModelOperations.js';
+
+function isRecord(value: object): boolean {
+  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<T>(value: T): T {
+  const seen = new WeakMap<object, unknown>();
+  function visit(input: unknown): unknown {
+    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: unknown[] = new Array(input.length);
+      seen.set(input, array);
+      input.forEach((item, index) => { array[index] = visit(item); });
+      return Object.freeze(array);
+    }
+    const source: object = input instanceof Model ? input.toReactiveSnapshot<Record<string, unknown>>() : input;
+    if (!isRecord(source)) return input;
+    const result: Record<PropertyKey, unknown> = Object.getPrototypeOf(source) === null ? Object.create(null) as Record<PropertyKey, unknown> : {};
+    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) as T;
+}
+
+/** Compare data snapshots, including non-enumerable schema-derived fields. */
+export function equalSnapshots(a: unknown, b: unknown): boolean {
+  const seen = new WeakMap<object, object>();
+  function equal(left: unknown, right: unknown): boolean {
+    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/src/react/useAblo.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useContext, useEffect, useState } from 'react';
+import { useCallback, useContext, useEffect, useMemo } from 'react';
 import { AbloInternalContext } from './internalContext.js';
 import type { AbloClient as Ablo, AbloReads } from '../client.js';
 import type { ModelClaim } from '@abloatai/transaction/coordination';
@@ -8,10 +8,9 @@ import {
   getModelClientMeta,
   type ModelOperations,
 } from '../local/client/createModelOperations.js';
-import { Model } from '../local/Model.js';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
 import type { ResolveSchema } from '@abloatai/transaction/types/global';
-import { useReactive } from '../useReactive.js';
+import { useReactive } from './useReactive.js';
 
 /**
  * The app's resolved schema-record type. It reads your `Register` module
@@ -56,37 +55,17 @@ 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 };
-
 function readModelResult<R extends SchemaRecord, T, C>(
   engine: Ablo<R> | null,
   modelClient: ModelOperations<T, C> | undefined,
   id: string | undefined,
   initial: T | undefined,
-): UseAbloModelResult<T> {
+): useAblo.Result<T> {
   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 })
@@ -95,27 +74,6 @@ function readModelResult<R extends SchemaRecord, T, C>(
   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<T>(value: T): T {
-  if (value instanceof Model) {
-    return value.toReactiveSnapshot<T>();
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => snapshotValue(item)) as T;
-  }
-  return value;
-}
-
 /**
  * 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
@@ -144,15 +102,16 @@ function snapshotValue<T>(value: T): T {
  * // 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 active = useAblo((ablo) => ablo.records.claim.state({ id }));
+ * 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.
+ * 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;
 export function useAblo<
@@ -164,22 +123,8 @@ export function useAblo<
 export function useAblo<T, C>(
   modelClient: ModelOperations<T, C>,
   id: string,
-  options: UseAbloModelOptions<T> & { readonly initial: T },
-): UseAbloHydratedModelResult<T>;
-export 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 function useAblo<T, C>(
-  modelClient: ModelOperations<T, C>,
-  id: string,
-  options?: UseAbloModelOptions<T>,
-): UseAbloModelResult<T>;
+  options?: useAblo.Options<T>,
+): useAblo.Result<T>;
 export function useAblo<
   R extends SchemaRecord = DefaultModels,
   T = Record<string, unknown>,
@@ -187,8 +132,8 @@ export function useAblo<
 >(
   select: ModelClientSelector<R, T, C>,
   id: string,
-  options?: UseAbloModelOptions<T>,
-): UseAbloModelResult<T>;
+  options?: useAblo.Options<T>,
+): useAblo.Result<T>;
 export function useAblo<
   R extends SchemaRecord = DefaultModels,
   T = Record<string, unknown>,
@@ -196,34 +141,9 @@ export function useAblo<
 >(
   modelOrSelect?: ModelOperations<T, C> | ModelClientSelector<R, T, C> | AbloSelector<R, T>,
   id?: string,
-  options?: UseAbloModelOptions<T>,
-): Ablo<R> | null | UseAbloModelResult<T> | T | undefined {
-  return useAbloImpl<R, T, C>(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<
-  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 {
-  const engine = useAbloClientImpl(boundClient);
+  options?: useAblo.Options<T>,
+): Ablo<R> | null | useAblo.Result<T> | T | undefined {
+  const engine = useAbloClient<R>();
   const initial = options?.initial;
   const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
   const modelClient: ModelOperations<T, C> | undefined =
@@ -235,54 +155,65 @@ export function useAbloImpl<
         ? 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. Only the model-row form (`id !== undefined`) reads
-  // claims, so we subscribe only when `id` is set. The selector-only form never
-  // reads claims, and subscribing it to the workspace-wide claim stream would
-  // re-render and recompute it on every claim or presence change anywhere — a
-  // real storm during AI editing or live collaboration — for a value that cannot
-  // change.
-  const [claimVersion, setClaimVersion] = useState(0);
+  // 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 reading = modelOrSelect !== undefined;
+  const subscribe = useCallback((notify: () => void) => {
+    if (!engine || !reading) return () => undefined;
+    return engine.claims.onChange(notify);
+  }, [engine, reading]);
+  const value = useReactive<T | useAblo.Result<T> | undefined>(() => {
+    if (isSelectorOnly && typeof modelOrSelect === 'function') {
+      return engine ? modelOrSelect(reactiveReads<R>(engine)) as T : undefined;
+    }
+    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 }),
+    } : {}),
+  });
   useEffect(() => {
-    if (!engine || id === undefined) return;
-    return engine.claims.onChange(() => { setClaimVersion((version) => version + 1); });
-  }, [engine, id]);
-
-  const selected = useReactive<T | undefined>(
-    () => {
-      if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {
-        return 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<R>(engine)) as T);
-    },
-  );
+    if (id !== undefined && modelClient?.local.get(id) !== undefined) seed.received = true;
+  }, [seed, modelClient, id, value]);
 
-  const modelResult = useReactive<UseAbloModelResult<T>>(
-    () => {
-      void claimVersion;
-      return readModelResult(engine, modelClient, id, initial);
-    },
-  );
-
-  if (isSelectorOnly) return selected;
-  if (modelOrSelect) return modelResult;
+  if (isSelectorOnly || modelOrSelect) return value;
   return engine;
 }
 
-/** @internal Resolve the bound or legacy provider client through one rebind seam. */
-export function useAbloClientImpl<R extends SchemaRecord>(
-  boundClient: Ablo<R> | null,
-): Ablo<R> | null {
+/** @internal Resolve the nearest provider's client through one schema rebind. */
+export function useAbloClient<R extends SchemaRecord>(): Ablo<R> | null {
   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: Ablo<R> | null =
-    boundClient ?? (ctx?.engine ? rebindEngine<R>(ctx.engine) : null);
-  return engine;
+  return ctx?.engine ? rebindEngine<R>(ctx.engine) : null;
+}
+
+/** Type annotations belong to the operation; most callers rely on inference. */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace useAblo {
+  export 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;
+  }
+
+  export 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/src/react/useMutators.ts

@@ -26,7 +26,7 @@ import { getContext } from '../local/context.js';
  * If a mutator throws, the error propagates to the caller and any writes it
  * already dispatched stay in place — there is no automatic rollback. Wrap the
  * call in your own try/catch and issue compensating writes when you need to
- * undo a partial change, or pass an `undoScope` (see {@link UseMutatorsOptions})
+ * undo a partial change, or pass an `undoScope` (see {@link useMutators.Options})
  * to record inverses for undo and redo.
  */
 
@@ -50,28 +50,12 @@ export type InvokerFor<F> = F extends (options: infer O) => Promise<infer R>
  * The hook's return shape: same tree as the input `MutatorDefs`, every leaf
  * rewritten to its invoker form.
  */
-export type MutatorInvokers<M> = {
-  [K in keyof M]: {
-    [N in keyof M[K]]: InvokerFor<M[K][N]>;
-  };
-};
-
-/**
- * Options passed to `useMutators`. When `undoScope` is set, every mutator
- * invocation is wrapped in a `RecordingMutation` and its inverses are
- * pushed to the scope as one undo entry.
- */
-export interface UseMutatorsOptions<S extends Schema> {
-  /** Target undo scope for recording inverses. Omit to disable recording. */
-  undoScope?: UndoScope<S>;
-}
-
 /** Mutator invokers (explicit schema arg). */
 export function useMutators<S extends Schema, M extends MutatorDefs<S>>(
   schema: S,
   mutators: M,
-  options?: UseMutatorsOptions<S>,
-): MutatorInvokers<M>;
+  options?: useMutators.Options<S>,
+): useMutators.Result<M>;
 
 /** Mutator invokers via the `Register` module augmentation. Schema comes
  * from the `SyncProvider`'s context; the mutator tree is typed against
@@ -80,14 +64,14 @@ export function useMutators<
   M extends ResolveSchema extends Schema ? MutatorDefs<ResolveSchema> : MutatorDefs<Schema>,
 >(
   mutators: M,
-  options?: UseMutatorsOptions<ResolveSchema extends Schema ? ResolveSchema : Schema>,
-): MutatorInvokers<M>;
+  options?: useMutators.Options<ResolveSchema extends Schema ? ResolveSchema : Schema>,
+): useMutators.Result<M>;
 
 export function useMutators(
   schemaOrMutators: Schema | MutatorDefs<Schema>,
-  mutatorsOrOptions?: MutatorDefs<Schema> | UseMutatorsOptions<Schema>,
-  maybeOptions?: UseMutatorsOptions<Schema>,
-): MutatorInvokers<MutatorDefs<Schema>> {
+  mutatorsOrOptions?: MutatorDefs<Schema> | useMutators.Options<Schema>,
+  maybeOptions?: useMutators.Options<Schema>,
+): useMutators.Result<MutatorDefs<Schema>> {
   const { store, organizationId, schema: ctxSchema } = useSyncContext();
 
   // Disambiguate: explicit-schema path has the schema object in first slot;
@@ -101,7 +85,7 @@ export function useMutators(
   const schema = isExplicit ? (schemaOrMutators as Schema) : ctxSchema;
   const mutators = (isExplicit ? mutatorsOrOptions : schemaOrMutators) as MutatorDefs<Schema>;
   const options = (isExplicit ? maybeOptions : mutatorsOrOptions) as
-    | UseMutatorsOptions<Schema>
+    | useMutators.Options<Schema>
     | undefined;
 
   if (!schema) {
@@ -115,7 +99,7 @@ export function useMutators(
 
   const { undoScope } = options ?? {};
 
-  return useMemo<MutatorInvokers<MutatorDefs<Schema>>>(() => {
+  return useMemo<useMutators.Result<MutatorDefs<Schema>>>(() => {
     const out: Record<string, Record<string, (args: unknown) => Promise<unknown>>> = {};
 
     for (const modelKey of Object.keys(mutators)) {
@@ -182,3 +166,23 @@ export function useMutators(
     return out;
   }, [schema, mutators, store, organizationId, undoScope]);
 }
+
+/** Optional annotations for custom mutation bindings. */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace useMutators {
+  export type Result<M> = {
+    [K in keyof M]: {
+      [N in keyof M[K]]: InvokerFor<M[K][N]>;
+    };
+  };
+
+  /**
+   * Options passed to `useMutators`. When `undoScope` is set, every mutator
+   * invocation is wrapped in a `RecordingMutation` and its inverses are
+   * pushed to the scope as one undo entry.
+   */
+  export interface Options<S extends Schema> {
+    /** Target undo scope for recording inverses. Omit to disable recording. */
+    undoScope?: UndoScope<S>;
+  }
+}