@abloatai/humans 0.37.0

package/dist/react/createAbloReact.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The typed react binding — the schema generic is captured ONCE, at a factory
+ * call in app code, and every hook the factory returns is born typed. This is
+ * a schema-bound shape with no module augmentation or generic parameters at call sites,
+ * and — once the legacy generic erasure retires — no casts anywhere on the
+ * path from context to component.
+ *
+ * The app's one binding file, by convention:
+ *
+ * ```ts
+ * // lib/ablo.ts
+ * import { createAbloReact } from '@abloatai/ablo/react';
+ * import { schema } from './schema';
+ *
+ * export const { AbloProvider, useAblo } = createAbloReact(schema);
+ * ```
+ *
+ * Components then import `useAblo` from `lib/ablo` and never spell a type
+ * argument; `useAblo()` is `Ablo<S> | null`, and a selector's `ablo`
+ * parameter is the reactive-read view of the same `S`.
+ */
+import { type ReactElement } from 'react';
+import { type AbloProviderProps } from './AbloProvider.js';
+import { type AbloSelector, type ModelClientSelector, type UseAbloHydratedModelResult, type UseAbloModelOptions, type UseAbloModelResult } from './useAblo.js';
+import type { AbloClient as Ablo } from '../client.js';
+import type { ModelOperations } from '../local/client/createModelProxy.js';
+import type { Schema, SchemaRecord } from '@abloatai/transaction/schema/schema';
+/** 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;
+    /** `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>;
+    };
+}
+/**
+ * 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).
+ */
+export declare function createAbloReact<S extends SchemaRecord>(schema: Schema<S>): AbloReactBinding<S>;

package/dist/react/createAbloReact.js

@@ -0,0 +1,48 @@
+'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, } from './useAblo.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).
+ */
+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);
+    }
+    return { AbloProvider: BoundAbloProvider, useAblo: useBoundAblo };
+}

package/dist/react/internalContext.d.ts

@@ -0,0 +1,33 @@
+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.
+ */
+export interface AbloInternalContextValue {
+    /**
+     * The application user id, when your app passed one to `<AbloProvider>`. Sync
+     * identity is derived on the server from the API key, so this is `null`
+     * unless you set it, and it is not required for sync to work.
+     */
+    currentUserId: string | null;
+    /** Subscribe to provider-level errors: engine errors, bootstrap failures, and session issues. */
+    subscribeError: (listener: (error: Error) => void) => () => void;
+    /** Emit an error to every subscribed listener. The provider calls this for you. */
+    emitError: (error: Error) => void;
+    /**
+     * The typed `Ablo` client for this provider, or `null` until the first sync
+     * bootstrap resolves. It is held here so `useSync()` can return it without
+     * reaching into the store; the client and the store are sibling objects, and
+     * neither is derived from the other.
+     *
+     * It is typed loosely as `Ablo<SchemaRecord>` because generics do not flow
+     * through React context. `useSync<R>()` restores the precise type through its
+     * own generic; the runtime value is the fully typed client.
+     */
+    engine: Ablo<SchemaRecord> | null;
+}
+export declare const AbloInternalContext: import("react").Context<AbloInternalContextValue | null>;

package/dist/react/internalContext.js

@@ -0,0 +1,3 @@
+'use client';
+import { createContext } from 'react';
+export const AbloInternalContext = createContext(null);

package/dist/react/useAblo.d.ts

@@ -0,0 +1,96 @@
+import type { AbloClient as Ablo, AbloReads } from '../client.js';
+import type { ModelClaim } from '@abloatai/transaction/coordination';
+import { type ModelOperations } from '../local/client/createModelProxy.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { ResolveSchema } from '@abloatai/transaction/types/global';
+/**
+ * The app's resolved schema-record type. It reads your `Register` module
+ * augmentation when you declare one and falls back to the loose
+ * {@link SchemaRecord} otherwise, so `useAblo()` returns a fully typed client
+ * without you passing `<(typeof schema)['models']>` at every call site.
+ */
+type DefaultModels = ResolveSchema extends {
+    models: infer M;
+} ? M extends SchemaRecord ? M : SchemaRecord : SchemaRecord;
+export type ModelClientSelector<R extends SchemaRecord, T, C> = (ablo: AbloReads<R>) => ModelOperations<T, C>;
+export type AbloSelector<R extends SchemaRecord, T> = (ablo: AbloReads<R>) => T;
+export interface UseAbloModelOptions<T> {
+    /**
+     * An initial row, usually from a server component or a route loader. The hook
+     * returns it until sync delivers a newer row for the same id.
+     */
+    readonly initial?: T;
+}
+export interface UseAbloModelResult<T> {
+    /** The current row for the id, or `initial` until the row has synced. */
+    readonly data: T | undefined;
+    /** The work claims currently held on this row by any participant. */
+    readonly claims: readonly ModelClaim[];
+    /** True while another participant holds a claim — handy for disabling UI. */
+    readonly claimed: boolean;
+}
+export type UseAbloHydratedModelResult<T> = Omit<UseAbloModelResult<T>, 'data'> & {
+    readonly data: T;
+};
+/**
+ * Reads Ablo from inside an `<AbloProvider>` subtree. Called with no arguments
+ * it returns the typed client for use in callbacks and effects; called with a
+ * selector it subscribes the component to a reactive read — such as one
+ * `ablo.<model>` row — and re-renders when that read changes.
+ *
+ * You can call it with no type arguments once you declare the `Register` module
+ * augmentation (`declare module '@abloatai/ablo' { interface Register {
+ * Schema: typeof schema } }`); the default type then resolves through your
+ * schema's models, so call sites stay clean:
+ *
+ * **Prefer the binding.** `createAbloReact(schema)` captures the schema once
+ * in your app's binding file and returns a `useAblo` that needs none of the
+ * typing arrangements below — no type argument, no `Register` declaration
+ * (see `react.md`). Passing an explicit schema type argument to THIS hook is
+ * deprecated in favor of that binding; it keeps working for shared packages
+ * that cannot bind a concrete schema.
+ *
+ * ```ts
+ * // With the Register augmentation (recommended):
+ * const ablo = useAblo();
+ * if (!ablo) return <Loading />;
+ * const doc = await ablo.documents.get({ id }); // 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.documents.local.get(id)) ?? serverDoc;
+ * const active = useAblo((ablo) => ablo.documents.claim.state({ id }));
+ *
+ * // Without the augmentation, pass the schema as a type argument:
+ * const ablo = useAblo<(typeof schema)['models']>();
+ * ```
+ *
+ * The no-argument form returns `null` while the engine is still bootstrapping.
+ * Branch on `null` and render a loading state — or gate on `useSyncStatus()`
+ * reaching `'connected'` — before calling model methods.
+ */
+export declare function useAblo<R extends SchemaRecord = DefaultModels>(): Ablo<R> | null;
+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;
+export {};

package/dist/react/useAblo.js

@@ -0,0 +1,120 @@
+'use client';
+import { useContext, useEffect, useState } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+import { getModelClientMeta, } from '../local/client/createModelProxy.js';
+import { Model } from '../local/Model.js';
+import { useReactive } from '../useReactive.js';
+const EMPTY_CLAIMS = Object.freeze([]);
+/**
+ * Restore the caller's schema generics on the context-held engine. React
+ * context erases generics (see `AbloInternalContextValue.engine`), so this is
+ * the one deliberate rebind point: the runtime value is the fully typed
+ * client, and `R` is the compile-time view the calling hook declared.
+ */
+function rebindEngine(engine) {
+    return engine;
+}
+/**
+ * The reactive-read view of a client — the identical runtime object, with
+ * model reads typed as snapshot rows, because everything a selector returns
+ * is converted through `snapshotValue` before the hook hands it back. Same
+ * generic in and out, so this compiles with no schema rebinding.
+ */
+function reactiveReads(engine) {
+    return engine;
+}
+function readModelResult(engine, modelClient, id, initial) {
+    if (!modelClient || id === undefined) {
+        return { data: initial, claims: EMPTY_CLAIMS, claimed: false };
+    }
+    const data = snapshotValue(modelClient.local.get(id) ?? initial);
+    const meta = getModelClientMeta(modelClient);
+    const claims = meta && engine
+        ? engine.claims.list({ model: meta.key, id })
+        : EMPTY_CLAIMS;
+    return { data, claims, claimed: claims.length > 0 };
+}
+/**
+ * Projects a reactive read into the value that `useReactive` caches and
+ * returns.
+ *
+ * For a `Model`, this reads the row's fields through `toReactiveSnapshot`
+ * rather than returning the instance itself. Property access is what subscribes
+ * the reaction to those fields, so the read has to happen inside this tracked
+ * function; returning the live instance without reading its fields would leave
+ * the component blind to later edits. The fresh object it produces also lets
+ * `useReactive`'s equality check detect an in-place update.
+ */
+function snapshotValue(value) {
+    if (value instanceof Model) {
+        return value.toReactiveSnapshot();
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => snapshotValue(item));
+    }
+    return value;
+}
+export function useAblo(modelOrSelect, id, options) {
+    return useAbloImpl(null, modelOrSelect, id, options);
+}
+/**
+ * @internal The one implementation behind `useAblo` and the bound hooks a
+ * `createAbloReact` binding returns — written once so the reactive read path
+ * cannot fork between the global hook and a factory's.
+ *
+ * `boundClient` is a binding's own context value — typed `Ablo<S>` at the
+ * factory, so that path never rebinds and never casts. `null` means "no
+ * binding provider in this tree": the global hook always passes it, and a
+ * binding hook mounted under a legacy provider falls through to the erased
+ * internal context, which is what keeps both mounts working while the last
+ * legacy mount migrates.
+ */
+export function useAbloImpl(boundClient, modelOrSelect, id, options) {
+    const ctx = useContext(AbloInternalContext);
+    // The bound client wins — it is already `Ablo<R>`, no rebinding. The
+    // fallback is the ONE remaining schema rebind in the SDK; it retires with
+    // the last legacy provider mount (docs/plans/typed-react-binding.md).
+    const engine = boundClient ?? (ctx?.engine ? rebindEngine(ctx.engine) : null);
+    const initial = options?.initial;
+    const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
+    const modelClient = typeof modelOrSelect === 'function' && id !== undefined
+        ? engine
+            ? modelOrSelect(reactiveReads(engine))
+            : undefined
+        : typeof modelOrSelect === 'function'
+            ? undefined
+            : modelOrSelect;
+    // Claims arrive through an event emitter (engine.claims), not through MobX, so
+    // the useReactive reactions below cannot track them; we bridge changes with a
+    // setState bump instead. 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);
+    useEffect(() => {
+        if (!engine || id === undefined)
+            return;
+        return engine.claims.onChange(() => { setClaimVersion((version) => version + 1); });
+    }, [engine, id]);
+    const selected = useReactive(() => {
+        if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {
+            return undefined;
+        }
+        // The selector runs against the real engine — reads inside it return the
+        // pool's model instances. `snapshotValue` then converts the RESULT to
+        // plain snapshot rows, which is what the selector's `AbloReads`
+        // parameter type already promised.
+        return snapshotValue(modelOrSelect(reactiveReads(engine)));
+    });
+    const modelResult = useReactive(() => {
+        void claimVersion;
+        return readModelResult(engine, modelClient, id, initial);
+    });
+    if (isSelectorOnly)
+        return selected;
+    if (modelOrSelect)
+        return modelResult;
+    return engine;
+}

package/dist/react/useCurrentUserId.d.ts

@@ -0,0 +1,2 @@
+/** Returns the application user id supplied to the nearest AbloProvider. */
+export declare function useCurrentUserId(): string | null;

package/dist/react/useCurrentUserId.js

@@ -0,0 +1,12 @@
+'use client';
+import { useContext } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+/** Returns the application user id supplied to the nearest AbloProvider. */
+export function useCurrentUserId() {
+    const context = useContext(AbloInternalContext);
+    if (!context) {
+        throw new AbloValidationError('useCurrentUserId: no <AbloProvider> mounted above this component.', { code: 'no_ablo_provider' });
+    }
+    return context.currentUserId;
+}

package/dist/react/useErrorListener.d.ts

@@ -0,0 +1,2 @@
+/** Subscribe to provider-level errors without causing component re-renders. */
+export declare function useErrorListener(listener: (error: Error) => void): void;

package/dist/react/useErrorListener.js

@@ -0,0 +1,14 @@
+'use client';
+import { useContext, useEffect, useRef } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+/** Subscribe to provider-level errors without causing component re-renders. */
+export function useErrorListener(listener) {
+    const context = useContext(AbloInternalContext);
+    if (!context) {
+        throw new AbloValidationError('useErrorListener: no <AbloProvider> mounted above this component.', { code: 'no_ablo_provider' });
+    }
+    const listenerRef = useRef(listener);
+    listenerRef.current = listener;
+    useEffect(() => context.subscribeError((error) => listenerRef.current(error)), [context]);
+}

package/dist/react/useMutationFailureListener.d.ts

@@ -0,0 +1,8 @@
+import { type QueuedMutation } from '../reactRuntime.js';
+export interface MutationFailurePayload {
+    transaction: QueuedMutation;
+    error: Error;
+    permanent?: boolean;
+}
+/** Subscribe to optimistic mutation rollbacks and permanent write failures. */
+export declare function useMutationFailureListener(listener: (payload: MutationFailurePayload) => void): void;

package/dist/react/useMutationFailureListener.js

@@ -0,0 +1,19 @@
+'use client';
+import { useContext, useEffect, useRef } from 'react';
+import { AbloInternalContext, } from '../reactRuntime.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+/** Subscribe to optimistic mutation rollbacks and permanent write failures. */
+export function useMutationFailureListener(listener) {
+    const context = useContext(AbloInternalContext);
+    if (!context) {
+        throw new AbloValidationError('useMutationFailureListener: no <AbloProvider> mounted above this component.', { code: 'no_ablo_provider' });
+    }
+    const listenerRef = useRef(listener);
+    listenerRef.current = listener;
+    useEffect(() => {
+        const engine = context.engine;
+        if (!engine)
+            return;
+        return engine.onMutationFailure((payload) => listenerRef.current(payload));
+    }, [context, context.engine]);
+}

package/dist/react/useMutators.d.ts

@@ -0,0 +1,56 @@
+import type { Schema } from '@abloatai/transaction/schema/schema';
+import type { MutatorDefs } from '../local/mutators/defineMutators.js';
+import type { UndoScope } from '../local/mutators/UndoManager.js';
+import type { ResolveSchema } from '@abloatai/transaction/types/global';
+/**
+ * Turns a mutator tree built with `defineMutators` into callable invokers. The
+ * returned object mirrors that tree one-to-one, but each leaf becomes an
+ * `(args) => Promise<TResult>` function.
+ *
+ * Each invocation builds a fresh `Transaction` bound to the current store and
+ * organization, calls your mutator with `{ tx, args }`, and returns whatever
+ * the mutator resolves to.
+ *
+ * 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})
+ * to record inverses for undo and redo.
+ */
+/**
+ * Map a `MutatorFn` onto its invoker form — strip `tx`, keep `args`/return.
+ *
+ * Uses nested `infer O` so the `args`/`result` types are extracted from the
+ * function signature without binding the `tx` parameter to a specific
+ * `Transaction<S>` variance. Function parameters are contravariant, so a
+ * match against `MutatorFn<Schema>` would reject mutators declared against
+ * a narrower schema (e.g. `Transaction<typeof appSchema>`). The two-step
+ * inference sidesteps that without resorting to `any`/`unknown` placeholders.
+ */
+export type InvokerFor<F> = F extends (options: infer O) => Promise<infer R> ? O extends {
+    args: infer A;
+} ? (args: A) => Promise<R> : never : never;
+/**
+ * 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 declare function useMutators<S extends Schema, M extends MutatorDefs<S>>(schema: S, mutators: M, options?: UseMutatorsOptions<S>): MutatorInvokers<M>;
+/** Mutator invokers via the `Register` module augmentation. Schema comes
+ * from the `SyncProvider`'s context; the mutator tree is typed against
+ * `ResolveSchema` at the call site. */
+export declare function useMutators<M extends ResolveSchema extends Schema ? MutatorDefs<ResolveSchema> : MutatorDefs<Schema>>(mutators: M, options?: UseMutatorsOptions<ResolveSchema extends Schema ? ResolveSchema : Schema>): MutatorInvokers<M>;

package/dist/react/useMutators.js

@@ -0,0 +1,84 @@
+'use client';
+import { useMemo } from 'react';
+import { createTransaction } from '../local/mutators/Transaction.js';
+import { createRecordingMutation } from '../local/mutators/RecordingMutation.js';
+import { useSyncContext } from './context.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+import { getContext } from '../local/context.js';
+export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
+    const { store, organizationId, schema: ctxSchema } = useSyncContext();
+    // Disambiguate: explicit-schema path has the schema object in first slot;
+    // the global-resolved path has the mutator tree there. A schema object
+    // has a `.models` property; a mutator tree doesn't.
+    const isExplicit = typeof schemaOrMutators === 'object' &&
+        schemaOrMutators !== null &&
+        'models' in schemaOrMutators;
+    const schema = isExplicit ? schemaOrMutators : ctxSchema;
+    const mutators = (isExplicit ? mutatorsOrOptions : schemaOrMutators);
+    const options = (isExplicit ? maybeOptions : mutatorsOrOptions);
+    if (!schema) {
+        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.', { code: 'mutators_schema_missing' });
+    }
+    const { undoScope } = options ?? {};
+    return useMemo(() => {
+        const out = {};
+        for (const modelKey of Object.keys(mutators)) {
+            const group = mutators[modelKey];
+            if (!group)
+                continue;
+            const invokers = {};
+            for (const mutatorName of Object.keys(group)) {
+                const maybeFn = group[mutatorName];
+                if (!maybeFn)
+                    continue;
+                // Bind the narrowed value: `noUncheckedIndexedAccess` types the indexed
+                // read as `Fn | undefined`, and that narrowing doesn't survive into the
+                // deferred invoker closures below — a non-optional local does.
+                const fn = maybeFn;
+                const label = `${String(modelKey)}.${mutatorName}`;
+                invokers[mutatorName] = async (args) => {
+                    // Recording path: wrap the transaction so each write snapshots its
+                    // inverse. On success, push the captured entry to the scope.
+                    //
+                    // The whole snapshot → write → record sequence runs on the scope's
+                    // serialization chain so concurrent invocations (a caller may fire
+                    // writes without awaiting them) record in invocation order and never
+                    // interleave their shared-model snapshots. See UndoScope.runRecorded.
+                    if (undoScope) {
+                        return undoScope.runRecorded(async () => {
+                            const recording = createRecordingMutation(schema, store, organizationId);
+                            try {
+                                const result = await fn({ tx: recording.tx, args });
+                                const entry = recording.getEntry(label);
+                                if (entry)
+                                    undoScope.record(entry);
+                                return result;
+                            }
+                            catch (err) {
+                                // The error is re-thrown to the caller's await (the real
+                                // consumer surface), so this is a forensic follow-on → debug.
+                                getContext().logger.debug(`[useMutators] mutator "${label}" threw`, { error: err });
+                                throw err;
+                            }
+                        });
+                    }
+                    // Non-recording path — plain transaction, no inverse capture.
+                    const tx = createTransaction(schema, store, organizationId);
+                    try {
+                        return await fn({ tx, args });
+                    }
+                    catch (err) {
+                        // Re-thrown to the caller's await (the real consumer surface) →
+                        // this duplicate is forensic, debug only.
+                        getContext().logger.debug(`[useMutators] mutator "${label}" threw`, { error: err });
+                        throw err;
+                    }
+                };
+            }
+            out[modelKey] = invokers;
+        }
+        return out;
+    }, [schema, mutators, store, organizationId, undoScope]);
+}

package/dist/react/useSyncStatus.d.ts

@@ -0,0 +1,19 @@
+export type SyncStatusSnapshot = {
+    readonly name: 'initial';
+} | {
+    readonly name: 'connecting';
+    readonly progress: number;
+} | {
+    readonly name: 'connected';
+    readonly hasUnsyncedChanges: boolean;
+} | {
+    readonly name: 'reconnecting';
+    readonly reason?: string;
+} | {
+    readonly name: 'disconnected';
+    readonly reason?: string;
+} | {
+    readonly name: 'needs-auth';
+};
+/** Reactively exposes the local store's connection and settlement status. */
+export declare function useSyncStatus(): SyncStatusSnapshot;

package/dist/react/useSyncStatus.js

@@ -0,0 +1,37 @@
+'use client';
+import { useCallback } from 'react';
+import { useSyncContext, } from './context.js';
+import { useReactive } from '../useReactive.js';
+/** Reactively exposes the local store's connection and settlement status. */
+export function useSyncStatus() {
+    const { store } = useSyncContext();
+    const compute = useCallback(() => deriveStatus(store), [store]);
+    return useReactive(compute, sameSnapshot);
+}
+function deriveStatus(store) {
+    const { state, progress, pendingChanges, isSessionError, error } = store.syncStatus;
+    if (isSessionError)
+        return { name: 'needs-auth' };
+    if (state === 'reconnecting')
+        return { name: 'reconnecting', reason: error?.message };
+    if (state === 'offline')
+        return { name: 'disconnected', reason: 'offline' };
+    if (state === 'error')
+        return { name: 'disconnected', reason: error?.message };
+    if (store.isReady)
+        return { name: 'connected', hasUnsyncedChanges: pendingChanges > 0 };
+    if (state === 'idle' || state === 'syncing')
+        return { name: 'connecting', progress };
+    return { name: 'initial' };
+}
+function sameSnapshot(a, b) {
+    if (a.name !== b.name)
+        return false;
+    if (a.name === 'initial' || a.name === 'needs-auth')
+        return true;
+    if (a.name === 'connecting')
+        return b.name === 'connecting' && a.progress === b.progress;
+    if (a.name === 'connected')
+        return b.name === 'connected' && a.hasUnsyncedChanges === b.hasUnsyncedChanges;
+    return (b.name === 'reconnecting' || b.name === 'disconnected') && a.reason === b.reason;
+}