@abloatai/ablo 0.26.0 → 0.28.0

package/dist/react/index.js

@@ -1,48 +1,47 @@
 /**
- * @abloatai/ablo/react — React bindings (v0.3.0)
+ * React bindings for `@abloatai/ablo`.
  *
- * Umbrella provider:
- *   const ablo = Ablo({ schema, apiKey })   // build once — module scope or useMemo
+ * # Provider
+ *
+ * Build a client once — at module scope or with `useMemo` — and wrap your tree:
+ *
+ *   const ablo = Ablo({ schema, apiKey })
  *   <AbloProvider client={ablo} fallback={<Skeleton/>}>
- *     — `client` is the only required prop (construct it yourself; the provider
- *     is the thin reactive binding, like `<Elements stripe={...}>`). `userId`
- *     is optional + informational. Owns sync engine + multiplayer lifecycle;
- *     the `fallback` prop
- *     gates children on first bootstrap. Pass `fallback="passthrough"`
- *     to disable the gate.
- *   <ClientSideSuspense fallback={<Skeleton/>}> — NESTED gate inside an
- *     already-ready provider. Use only when you need a separate gate
- *     for a heavy subtree (e.g. a canvas) while app chrome renders
- *     immediately. The provider-level `fallback` is the default path.
  *
- * Data hooks:
- *   useAblo((ablo) => ablo.tasks.get(id))     — primary React read API (sync local snapshot)
- *   useAblo()                                  — typed client for callbacks/effects
- *                                                (sync local reads: ablo.<model>.get/getAll;
- *                                                 async server reads: ablo.<model>.retrieve/list;
- *                                                 writes: ablo.<model>.create/update/delete)
- *   useMutators(defs, opts?)                   — Zero-style custom mutators
- *   useUndoScope(name)                         — per-surface undo/redo
+ * `client` is the only required prop; you construct it, and the provider is the
+ * thin reactive binding around it. The provider owns the sync-engine and
+ * multiplayer lifecycle. Its `fallback` gates children until the first sync
+ * bootstrap completes — pass `fallback="passthrough"` to render children
+ * immediately. `userId` is optional and informational.
+ *
+ * {@link ClientSideSuspense} adds a nested gate inside an already-ready
+ * provider. Reach for it only when a heavy subtree, such as a canvas, needs its
+ * own gate while the rest of the app renders right away; the provider-level
+ * `fallback` is the usual path.
+ *
+ * # Data hooks
+ *
+ *   useAblo((ablo) => ablo.tasks.get(id))  — subscribe to a local snapshot (the main read API)
+ *   useAblo()                              — the typed client, for callbacks and effects:
+ *                                            synchronous local reads (`ablo.<model>.get`/`getAll`),
+ *                                            async server reads (`retrieve`/`list`),
+ *                                            and writes (`create`/`update`/`delete`)
+ *   useMutators(defs, opts?)               — define custom mutators
+ *   useUndoScope(name)                     — per-surface undo and redo
+ *
+ * # Status and errors
+ *
+ *   useSyncStatus()       — a discriminated-union snapshot of the sync lifecycle
+ *   useErrorListener(cb)  — an imperative error callback, for telemetry or toasts
+ *   useCurrentUserId()    — the provider's `userId` prop
  *
- * Status + errors:
- *   useSyncStatus()           — tagged-union lifecycle snapshot
- *   useErrorListener(cb)      — imperative error callback (Sentry/Datadog)
- *   useCurrentUserId()        — the provider's userId prop
+ * # Multiplayer
  *
- * Multiplayer (always available — `<AbloProvider>` always constructs a client):
- *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
- *   useWatch({ scope }) — join multiplayer for a scope, get peers/claims
+ * Multiplayer is always available, because `<AbloProvider>` always constructs a
+ * client:
  *
- * ── Breaking changes from v0.2.x ───────────────────────────────────
- * Removed: <SyncProvider>, SyncContext, useSyncContext — folded into
- *   <AbloProvider>. Access the raw engine with `useSync()`.
- * Removed: createAbloContext() factory + its returned AbloProvider —
- *   multiplayer is now always-on inside <AbloProvider>. Schema-typed
- *   participant hooks ship in a follow-up release.
- * Removed: withSync (no-op alias of observer). Import observer
- *   from mobx-react-lite directly if you still need it.
- * Changed: useSyncStatus() now returns a discriminated union. See the
- *   migration notes in CHANGELOG.md.
+ *   useAblo((ablo) => ablo.<model>.claim.state(...))  — reactive coordination reads
+ *   useWatch({ scope })                               — join a scope to get its peers and claims
  */
 // ── Umbrella provider + lifecycle hooks ────────────────────────────
 export { AbloProvider, useWatch, usePeers, useSync, useSyncStore, } from './AbloProvider.js';

package/dist/react/internalContext.d.ts

@@ -1,34 +1,32 @@
 import type { Ablo } from '../client/Ablo.js';
 import type { SchemaRecord } from '../schema/schema.js';
 /**
- * Internal context populated by `<AbloProvider>`. Separate from
- * `SyncContext` (which carries the store + schema for the data
- * hooks) because these fields are owned by the umbrella provider
- * and don't belong on the raw `SyncStoreContract`.
- *
- * Consumers should NOT use this directly — access the fields via
- * the typed hooks (`useCurrentUserId`, `useErrorListener`, etc.).
+ * 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 {
     /**
-     * Optional app user id when the application passed one. Hosted Ablo
-     * identity is server-derived, so this may be null.
+     * 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, session issues). */
+    /** Subscribe to provider-level errors: engine errors, bootstrap failures, and session issues. */
     subscribeError: (listener: (error: Error) => void) => () => void;
-    /** Fire an error to all subscribed listeners. Called internally by the provider. */
+    /** Emit an error to every subscribed listener. The provider calls this for you. */
     emitError: (error: Error) => void;
     /**
-     * The SyncEngine proxy for this provider. `null` before bootstrap
-     * resolves. Exposed through the internal context so `useSync()`
-     * can return it without having to reach into the store — the two
-     * are sibling objects constructed together by `createSyncEngine`
-     * and shouldn't be coerced through each other.
+     * 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.
      *
-     * Typed as `Ablo<SchemaRecord>` on the context because
-     * generics don't flow through React context. `useSync<R>()` widens
-     * via its own generic — runtime value is the concrete engine.
+     * 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;
 }

package/dist/react/useAblo.d.ts

@@ -1,63 +1,66 @@
-import type { Ablo, ModelClaim } from '../client/Ablo.js';
+import type { Ablo, AbloReads, ModelClaim } from '../client/Ablo.js';
 import type { ModelOperations } from '../client/createModelProxy.js';
 import type { SchemaRecord } from '../schema/schema.js';
 import type { ResolveSchema } from '../types/global.js';
 /**
- * Resolved schema-record type for the consumer's app. Reads the
- * `Register` module augmentation if declared, falls back to the
- * loose `SchemaRecord` if not. This lets `useAblo()` produce a
- * fully typed engine handle without the consumer having to pass
- * `<(typeof schema)['models']>` at every call site.
+ * 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;
-type ModelClientSelector<R extends SchemaRecord, T, C> = (ablo: Ablo<R>) => ModelOperations<T, C>;
-type AbloSelector<R extends SchemaRecord, T> = (ablo: Ablo<R>) => T;
+type ModelClientSelector<R extends SchemaRecord, T, C> = (ablo: AbloReads<R>) => ModelOperations<T, C>;
+type AbloSelector<R extends SchemaRecord, T> = (ablo: AbloReads<R>) => T;
 export interface UseAbloModelOptions<T> {
     /**
-     * Initial row, usually from a Server Component or loader. The hook returns it
-     * until the model client has a newer row in the local pool.
+     * 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> {
-    /** Current row for the id, or `initial` until the row has hydrated. */
+    /** The current row for the id, or `initial` until the row has synced. */
     readonly data: T | undefined;
-    /** Active work claims on this model row. */
+    /** The work claims currently held on this row by any participant. */
     readonly claims: readonly ModelClaim[];
-    /** Convenience flag for disabling UI while another participant is active. */
+    /** 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;
 };
 /**
- * useAblo — access the typed engine instance, or subscribe to a specific
- * `ablo.<model>` row from inside an `<AbloProvider>` subtree.
+ * 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.
  *
- * Zero-arg when the consumer declares the `Register` global
- * augmentation (`declare module '@abloatai/ablo' { interface Register { Schema:
- * typeof schema } }`). The default generic resolves through
- * `ResolveSchema['models']` so call sites stay clean:
+ * 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:
  *
  * ```ts
- * // With Register augmentation (recommended):
+ * // With the Register augmentation (recommended):
  * const ablo = useAblo();
  * if (!ablo) return <Loading />;
  * const doc = await ablo.documents.retrieve({ id }); // async server read
  *
- * // Reactive selector (sync local-graph snapshot):
+ * // 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.get(id)) ?? serverDoc;
  * const active = useAblo((ablo) => ablo.documents.claim.state({ id }));
  *
- * // Without augmentation, pass the schema generic:
+ * // Without the augmentation, pass the schema as a type argument:
  * const ablo = useAblo<(typeof schema)['models']>();
  * ```
  *
- * Returns `null` while the engine is bootstrapping. Branch on null
- * and render a loading state (or use `useSyncStatus()` to gate on
- * `'connected'`) before reaching for model methods.
+ * 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;

package/dist/react/useAblo.js

@@ -5,6 +5,24 @@ import { getModelClientMeta } from '../client/createModelProxy.js';
 import { Model } from '../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 same rebind viewed through the reactive-read surface — 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.
+ */
+function reactiveReads(engine) {
+    return rebindEngine(engine);
+}
 function readModelResult(engine, modelClient, id, initial) {
     if (!modelClient || id === undefined) {
         return { data: initial, claims: EMPTY_CLAIMS, claimed: false };
@@ -17,14 +35,15 @@ function readModelResult(engine, modelClient, id, initial) {
     return { data, claims, claimed: claims.length > 0 };
 }
 /**
- * Project a reactive read into the value `useReactive` caches and returns.
+ * Projects a reactive read into the value that `useReactive` caches and
+ * returns.
  *
- * For a `Model`, this MUST read the row's fields (via `toReactiveSnapshot`),
- * not return the bare instance: MobX tracks property access, so reading the
- * fields inside this tracked function is what subscribes the reaction to them —
- * and the fresh object identity lets `useReactive`'s equality detect an
- * in-place delta update. Returning `modelAsRow(value)` (the live instance, no
- * field read) is why `useAblo(a => a.x.get(id))` used to ignore remote edits.
+ * 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) {
@@ -42,18 +61,19 @@ export function useAblo(modelOrSelect, id, options) {
     const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
     const modelClient = typeof modelOrSelect === 'function' && id !== undefined
         ? engine
-            ? modelOrSelect(engine)
+            ? modelOrSelect(reactiveReads(engine))
             : undefined
         : typeof modelOrSelect === 'function'
             ? undefined
             : modelOrSelect;
-    // Claims live on a non-MobX event emitter (engine.claims), so the useReactive
-    // reactions below cannot track them — we bridge changes through a setState bump.
-    // ONLY the model-row form (`id !== undefined`) actually reads claims, so gate the
-    // subscription on `id`. The selector-only form (`useAblo((a) => a.x.get/getAll)`)
-    // never reads claims; subscribing it to the workspace-global claim stream would
-    // re-render + double-compute it on every claim/presence delta anywhere (a real
-    // storm during AI editing / live collaboration) for a value that can't change.
+    // 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)
@@ -64,7 +84,11 @@ export function useAblo(modelOrSelect, id, options) {
         if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {
             return undefined;
         }
-        return snapshotValue(modelOrSelect(engine));
+        // 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;
@@ -74,5 +98,5 @@ export function useAblo(modelOrSelect, id, options) {
         return selected;
     if (modelOrSelect)
         return modelResult;
-    return engine;
+    return engine === null ? null : rebindEngine(engine);
 }

package/dist/react/useCurrentUserId.d.ts

@@ -1,13 +1,14 @@
 /**
- * Returns the app user ID passed to the nearest `<AbloProvider>`, when
- * the app chose to provide one.
+ * Returns the application user id passed to the nearest `<AbloProvider>`, or
+ * `null` when your app did not provide one.
  *
- * Hosted Ablo identity is resolved server-side from the API key, session,
- * or capability token. This hook is only for app-owned fields like
- * `assigneeId`; it is not required for Ablo sync to connect.
+ * Sync identity is resolved on the server from the API key or session, so this
+ * value is not required for sync to connect. It is here for your app's own
+ * fields — an assignee id, a presence label, a permission check — where the
+ * current user matters to your data rather than to the sync layer. Reach for it
+ * in leaf components that need the id, for example to fill in a mutation
+ * payload.
  *
- * Use this in leaf components that need the current user ID for
- * mutation payloads, presence labels, permission checks, etc.
  * @example
  * function TaskRow({ id }) {
  *   const userId = useCurrentUserId();

package/dist/react/useCurrentUserId.js

@@ -3,15 +3,16 @@ import { useContext } from 'react';
 import { AbloInternalContext } from './internalContext.js';
 import { AbloValidationError } from '../errors.js';
 /**
- * Returns the app user ID passed to the nearest `<AbloProvider>`, when
- * the app chose to provide one.
+ * Returns the application user id passed to the nearest `<AbloProvider>`, or
+ * `null` when your app did not provide one.
  *
- * Hosted Ablo identity is resolved server-side from the API key, session,
- * or capability token. This hook is only for app-owned fields like
- * `assigneeId`; it is not required for Ablo sync to connect.
+ * Sync identity is resolved on the server from the API key or session, so this
+ * value is not required for sync to connect. It is here for your app's own
+ * fields — an assignee id, a presence label, a permission check — where the
+ * current user matters to your data rather than to the sync layer. Reach for it
+ * in leaf components that need the id, for example to fill in a mutation
+ * payload.
  *
- * Use this in leaf components that need the current user ID for
- * mutation payloads, presence labels, permission checks, etc.
  * @example
  * function TaskRow({ id }) {
  *   const userId = useCurrentUserId();

package/dist/react/useErrorListener.d.ts

@@ -1,12 +1,12 @@
 /**
- * Register an imperative callback that fires whenever the provider
- * surfaces an error. Covers engine errors (bootstrap failures,
- * mutation rejections), WebSocket errors, and uncaught exceptions
- * inside `postBootstrap` hooks.
+ * Registers a callback that runs whenever the provider surfaces an error. This
+ * covers engine errors such as bootstrap failures and mutation rejections,
+ * WebSocket errors, and uncaught exceptions thrown inside `postBootstrap`
+ * hooks.
  *
- * Use this for telemetry (Sentry, Datadog), user-facing toasts, or
- * any side effect that should NOT trigger a re-render. The listener
- * is stored in a ref, so re-renders don't thrash the subscription.
+ * Use it for side effects that should not cause a re-render — telemetry,
+ * logging, or a toast. The callback is held in a ref, so a re-render does not
+ * resubscribe.
  *
  * @example
  * function ErrorToaster() {

package/dist/react/useErrorListener.js

@@ -3,14 +3,14 @@ import { useContext, useEffect, useRef } from 'react';
 import { AbloInternalContext } from './internalContext.js';
 import { AbloValidationError } from '../errors.js';
 /**
- * Register an imperative callback that fires whenever the provider
- * surfaces an error. Covers engine errors (bootstrap failures,
- * mutation rejections), WebSocket errors, and uncaught exceptions
- * inside `postBootstrap` hooks.
+ * Registers a callback that runs whenever the provider surfaces an error. This
+ * covers engine errors such as bootstrap failures and mutation rejections,
+ * WebSocket errors, and uncaught exceptions thrown inside `postBootstrap`
+ * hooks.
  *
- * Use this for telemetry (Sentry, Datadog), user-facing toasts, or
- * any side effect that should NOT trigger a re-render. The listener
- * is stored in a ref, so re-renders don't thrash the subscription.
+ * Use it for side effects that should not cause a re-render — telemetry,
+ * logging, or a toast. The callback is held in a ref, so a re-render does not
+ * resubscribe.
  *
  * @example
  * function ErrorToaster() {
@@ -27,10 +27,9 @@ export function useErrorListener(listener) {
         throw new AbloValidationError('useErrorListener: no <AbloProvider> mounted above this component. ' +
             'Wrap your tree with <AbloProvider ...> from @abloatai/ablo/react.', { code: 'no_ablo_provider' });
     }
-    // Stash the latest callback in a ref so the effect subscription
-    // stays stable across renders. Matches the `useEventCallback`
-    // pattern: late-bind the listener so callers can pass inline
-    // arrows without thrashing the subscription.
+    // Hold the latest callback in a ref so the subscription stays stable across
+    // renders. Late-binding the listener this way lets callers pass an inline
+    // arrow without resubscribing on every render.
     const ref = useRef(listener);
     ref.current = listener;
     useEffect(() => {

package/dist/react/useMutationFailureListener.d.ts

@@ -5,15 +5,15 @@ export interface MutationFailurePayload {
     permanent?: boolean;
 }
 /**
- * Register a side-effect listener for mutation failures. Fires whenever
- * the underlying transaction queue rolls back an optimistic write —
- * permanent rejections (validation, FK, auth) and exhausted-retry
- * rollbacks (connection lost mid-burst).
+ * Subscribes a listener to mutation failures. The callback fires whenever the
+ * transaction queue rolls back an optimistic write — both permanent rejections
+ * (a validation, foreign-key, or authorization error) and rollbacks after the
+ * retries are exhausted (for example, the connection drops mid-write).
  *
- * Use this to mount a single `<MutationFailureBoundary>` near the app
- * shell that turns silent pool rollbacks into toasts / banners. The
- * listener is stored in a ref so re-renders don't thrash the
- * subscription — matches `useErrorListener`.
+ * A single listener mounted near the top of your component tree can turn these
+ * otherwise-silent rollbacks into toasts or banners. The callback is held in a
+ * ref, so re-renders do not tear down and re-create the underlying
+ * subscription.
  *
  * @example
  * function MutationFailureBoundary() {

package/dist/react/useMutationFailureListener.js

@@ -3,15 +3,15 @@ import { useContext, useEffect, useRef } from 'react';
 import { AbloInternalContext } from './internalContext.js';
 import { AbloValidationError } from '../errors.js';
 /**
- * Register a side-effect listener for mutation failures. Fires whenever
- * the underlying transaction queue rolls back an optimistic write —
- * permanent rejections (validation, FK, auth) and exhausted-retry
- * rollbacks (connection lost mid-burst).
+ * Subscribes a listener to mutation failures. The callback fires whenever the
+ * transaction queue rolls back an optimistic write — both permanent rejections
+ * (a validation, foreign-key, or authorization error) and rollbacks after the
+ * retries are exhausted (for example, the connection drops mid-write).
  *
- * Use this to mount a single `<MutationFailureBoundary>` near the app
- * shell that turns silent pool rollbacks into toasts / banners. The
- * listener is stored in a ref so re-renders don't thrash the
- * subscription — matches `useErrorListener`.
+ * A single listener mounted near the top of your component tree can turn these
+ * otherwise-silent rollbacks into toasts or banners. The callback is held in a
+ * ref, so re-renders do not tear down and re-create the underlying
+ * subscription.
  *
  * @example
  * function MutationFailureBoundary() {

package/dist/react/useMutators.d.ts

@@ -3,19 +3,19 @@ import type { MutatorDefs } from '../mutators/defineMutators.js';
 import type { UndoScope } from '../mutators/UndoManager.js';
 import type { ResolveSchema } from '../types/global.js';
 /**
- * useMutators — turn a `defineMutators` tree into callable invokers.
+ * 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.
  *
- * The returned object mirrors the mutator tree one-to-one, but each leaf is
- * now a `(args) => Promise<TResult>` function. Internally each invocation:
- *   1. Builds a fresh `Transaction` bound to the current store/org context.
- *   2. Calls the user's mutator with `{ tx, args }`.
- *   3. Returns the mutator's resolved value.
+ * 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.
  *
- * V1 error handling: if the mutator throws, we `console.error` + rethrow.
- * Any writes that already dispatched stay in place (no rollback). That
- * matches the existing behaviour of batch helpers like `saveManyOptimized`
- * and keeps the contract honest — consumers can layer their own try/catch
- * + compensating writes until V2 adds atomicity.
+ * 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.

package/dist/react/useMutators.js

@@ -43,8 +43,8 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
                     // 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 (the slides UI fires
-                    // writes un-awaited) record in *invocation* order and never
+                    // 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 () => {
@@ -64,7 +64,7 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
                             }
                         });
                     }
-                    // Non-recording path — plain transaction, identical to pre-undo V1.
+                    // Non-recording path — plain transaction, no inverse capture.
                     const tx = createTransaction(schema, store, organizationId);
                     try {
                         return await fn({ tx, args });

package/dist/react/useReactive.js

@@ -48,7 +48,7 @@ export function useReactive(compute, equals = defaultEquals) {
     // When `compute` identity changes, its closed-over observable source
     // may have swapped (e.g. useQuery memoized a new QueryView because
     // the where clause changed). The MobX reaction subscribed in
-    // `subscribe` only tracks the observables read on its FIRST run; if
+    // `subscribe` only tracks the observables read on its first run; if
     // the source swaps without a re-subscription, the reaction never
     // re-tracks the new observables and `getSnapshot` keeps returning
     // the stale value forever.
@@ -71,7 +71,7 @@ export function useReactive(compute, equals = defaultEquals) {
         // `compute` is a fresh inline arrow at virtually every call site, so this
         // branch runs on essentially every render. Reconcile the snapshot against
         // the latest closure, but only force a re-subscription when the value
-        // ACTUALLY changed. For the dominant case (same observable source, new
+        // actually changed. For the dominant case (same observable source, new
         // arrow identity, unchanged value) this avoids tearing down + recreating
         // the MobX reaction — and its double-compute — on every render. A genuine
         // source swap (a memoized compute closing over a new observable source)

package/dist/react/useSyncStatus.d.ts

@@ -1,10 +1,8 @@
 /**
- * Reactive sync-status snapshot as a discriminated union. Impossible
- * states (e.g., "connected AND offline") are unrepresentable — each
- * variant carries only the fields that make sense in that state.
- *
- * Inspired by Liveblocks' `useStatus()` and Zero's `useConnectionState()`:
- * one hook, one switch, no six-boolean guessing games.
+ * A snapshot of the current sync status, modeled as a discriminated union so
+ * impossible states — such as "connected and offline" at once — cannot be
+ * represented. Each variant carries only the fields that make sense in that
+ * state, so a single `switch` on `name` narrows to exactly what you can read.
  *
  * Variants:
  * - `initial` — the provider just mounted; no connection attempt yet.

package/dist/react/useUndoScope.d.ts

@@ -2,16 +2,14 @@ import type { Schema } from '../schema/schema.js';
 import type { UndoScope, UndoScopeOptions } from '../mutators/UndoManager.js';
 import type { ResolveSchema } from '../types/global.js';
 /**
- * useUndoScope — per-surface undo/redo for mutator invocations.
+ * Provides per-surface undo and redo for mutator invocations. Each named scope
+ * owns an independent undo/redo stack, so different parts of your app — a deck
+ * editor, a sidebar form — can undo separately without stepping on each other.
  *
- * Zero deliberately does NOT ship a built-in undo API; consumers build one
- * on top of mutation tracking. This is ours.
- *
- * Each named scope owns an independent undo/redo stack. Wire the returned
- * `scope` into `useMutators(schema, mutators, { undoScope: scope })` and the
- * invocations become recorded. `undo()` / `redo()` replay the inverses /
- * forwards as new transactions that do NOT re-record (the manager pushes
- * them between the two stacks explicitly).
+ * Wire the returned `scope` into `useMutators(schema, mutators, { undoScope:
+ * scope })` and those invocations become recorded. `undo()` and `redo()` replay
+ * the captured inverses and forwards as new transactions that do not record
+ * themselves; the manager moves the entry between the two stacks explicitly.
  *
  * @example
  * const { undo, redo, canUndo, canRedo, scope } = useUndoScope('deck-editor');