@abloatai/ablo 0.8.0 → 0.9.0

package/dist/react/AbloProvider.d.ts

@@ -1,10 +1,6 @@
 import { type ReactNode } from 'react';
-import type { Schema, SchemaRecord } from '../schema/schema.js';
+import type { SchemaRecord } from '../schema/schema.js';
 import { Ablo } from '../client/Ablo.js';
-import type { AbloPersistence } from '../client/persistence.js';
-import type { SyncEngineConfig, MutationExecutor, MutationDispatcher, SessionErrorDetector, OnlineStatusProvider, SyncLogger, SyncObservabilityProvider } from '../config/index.js';
-import type { UseMutatorsOptions } from './useMutators.js';
-import type { MutatorDefs } from '../mutators/defineMutators.js';
 import type { ActiveIntent, Peer } from '../types/streams.js';
 import type { EngineParticipant, ParticipantScope, ParticipantStatus } from '../sync/participants.js';
 import { type SyncStoreContract } from './context.js';
@@ -49,140 +45,41 @@ import { type SyncStoreContract } from './context.js';
  */
 export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
     /**
-     * Schema from `defineSchema()`. Determines the typed hook surface.
-     * This is the only prop most apps pass — start here.
-     */
-    schema: Schema<R>;
-    /**
-     * WebSocket URL of the sync server (`wss://...` or `ws://...`).
-     * Hosted apps omit this.
+     * A prebuilt {@link Ablo} client — **the only way to configure the engine.**
+     * Construct it yourself with `Ablo({ schema, apiKey, ... })` and pass the
+     * instance: the CLIENT owns auth, the credential lifecycle, transport, and
+     * connection; this provider is the thin REACTIVE binding over it (context,
+     * the bootstrap gate, error/​session forwarding). Mirrors Stripe
+     * `<Elements stripe={...}>` and a Supabase client passed into a context.
+     *
+     * Memoize it (build it once, e.g. with `useMemo` or module scope) — a new
+     * instance each render re-keys the bootstrap gate and tears down the socket.
      */
-    url?: string;
+    client: Ablo<R>;
     /**
-     * Optional app user id for app-owned fields. Ablo resolves sync
-     * participant identity from auth; this is not required to connect.
+     * The app user id, surfaced via `useCurrentUserId()` for app-owned fields.
+     * Purely informational for the React tree — sync identity is resolved by the
+     * client from its auth, not from this. Optional.
      */
     userId?: string;
-    /** Team IDs the user belongs to. Expanded into sync groups. */
-    teamIds?: string[];
-    /**
-     * API key for engine bootstrap auth. Used by the bootstrap fetch
-     * path; falls back to `credentials: 'include'` (session cookie)
-     * when unset. Browser apps typically omit this and rely on
-     * same-origin session cookies.
-     */
-    apiKey?: string;
-    /**
-     * Static bearer auth token, sent as `Authorization: Bearer <token>` on the
-     * WebSocket upgrade + HTTP. For a token that must be refreshed (e.g. a
-     * short-lived JWT), prefer {@link getToken}.
-     */
-    authToken?: string | null;
     /**
-     * Async resolver for a short-lived bearer token. Called once before the
-     * engine connects (so the first connection carries a fresh token) and then on
-     * a refresh interval ahead of expiry — each result is pushed via
-     * `engine.setAuthToken` without tearing down the connection. Wire this to
-     * a resolver that mints a short-lived session token (`ek_`/`rk_`) — e.g.
-     * `getSyncCapabilityToken` — or your own. Takes precedence over
-     * {@link authEndpoint}.
-     */
-    getToken?: () => Promise<string | null>;
-    /**
-     * Liveblocks/Stripe-style auth endpoint: a URL on YOUR backend that returns
-     * `{ token }` — the `ek_` ephemeral key your server minted for the logged-in
-     * user with `ablo.sessions.create({ user: { id } })`. The provider POSTs to it
-     * (with cookies) to fetch + refresh the bearer, so the browser carries no
-     * secret. Shorthand for a {@link getToken} that does the fetch; ignored when
-     * `getToken` is set.
-     */
-    authEndpoint?: string;
-    /** Optional Zero-style custom mutators. */
-    mutators?: MutatorDefs<Schema<R>>;
-    /** Options forwarded to the internal `useMutators` call (e.g., `undoScope`). */
-    mutatorOptions?: UseMutatorsOptions<Schema<R>>;
-    /**
-     * Block browser tab close when there are unsynced local writes.
-     * Triggers the standard `beforeunload` "Leave site?" prompt.
-     * Browsers ignore custom messages — do not pass one. Consumers
-     * who want telemetry should read
-     * `useSyncStatus().hasUnsyncedChanges` directly.
+     * Block tab close while there are unsynced local writes (the standard
+     * `beforeunload` prompt). Browsers ignore custom messages — don't pass one.
      */
     preventUnsavedChanges?: boolean;
     /**
-     * Milliseconds to tolerate connection loss before `useSyncStatus()`
-     * flips to `disconnected`. Defaults to 5000. Set to 0 to
-     * disable the grace period (immediate transition).
-     *
-     * v0.3.0 scope: reserved for future wiring. Current transition is
-     * driven by the engine's built-in state machine.
-     */
-    lostConnectionTimeout?: number;
-    /**
-     * Fired when the server rejects the session. The provider has
-     * ALREADY called `engine.purge()` (disposed + wiped IndexedDB) by
-     * the time this runs — the callback is for app-level side effects
-     * (e.g., redirect to sign-in, clear analytics identity).
+     * Fired when the server rejects the session. The provider has ALREADY called
+     * `client.purge()` (disposed + wiped IndexedDB) by the time this runs — use it
+     * for app side effects (redirect to sign-in, clear analytics identity).
      */
     onSessionExpired?: () => void | Promise<void>;
     /**
-     * Fired on any error the provider surfaces: engine errors,
-     * WebSocket errors, uncaught `postBootstrap` exceptions. Use for
-     * Sentry / Datadog. Consumers who only want errors inside React
-     * can use the `useErrorListener()` hook instead.
+     * Fired on any error the provider surfaces (engine/WebSocket/bootstrap). For
+     * Sentry/Datadog. React-only consumers can use `useErrorListener()` instead.
      */
     onError?: (error: Error) => void;
-    observability?: SyncObservabilityProvider;
-    logger?: SyncLogger;
-    mutationExecutor?: MutationExecutor;
-    mutationDispatcher?: MutationDispatcher;
-    sessionErrorDetector?: SessionErrorDetector;
-    onlineStatus?: OnlineStatusProvider;
-    configOverrides?: SyncEngineConfig;
-    /**
-     * Raw sync-group strings for the initial connection. Prefer {@link scope} —
-     * the model form (`{ decks: deckId }`) that the engine resolves through the
-     * schema's `scope`, so you never hand-write a `deck:<id>` string. Both merge.
-     */
-    syncGroups?: string[];
-    /**
-     * Model-form connection scope: `{ decks: deckId, documents: documentId }` or
-     * entity refs. Resolved through the schema's per-model `scope` into group
-     * strings (so typename `SlideDeck` → `deck:<id>`), unioned with {@link syncGroups}.
-     * Memoize the object if it's derived, to avoid rotating the engine each render.
-     */
-    scope?: ParticipantScope;
-    bootstrapBaseUrl?: string;
-    maxPoolSize?: number;
-    /**
-     * Local persistence mode for the underlying `Ablo` client. Defaults
-     * to `volatile` — pass `'indexeddb'` to opt back into offline-queue +
-     * reload-surviving cache in a browser. See `AbloOptions.persistence`
-     * for the full semantics.
-     */
-    persistence?: AbloPersistence;
-    /**
-     * How aggressively this provider pulls baseline state at startup.
-     *
-     *  - `'full'` (default): pull every delta in the configured sync
-     *    groups before the engine reports ready — a local replica of the
-     *    org's tenant plane. Right for collaborative editors and any page
-     *    that reads a lot of shared state.
-     *  - `'none'`: open the connection and process live deltas only — no
-     *    baseline fetch. Reads round-trip via `ablo.<model>.retrieve(...)`
-     *    and subscriptions populate the pool lazily. Right for read-light
-     *    pages (a mostly-static dashboard, a settings screen) that don't
-     *    want to download the whole org to render.
-     *
-     * Note: `'none'` still opens the realtime connection — it skips the
-     * baseline pull, not the socket. A fully connection-free mode for
-     * pages that do zero multiplayer is a separate follow-up (the socket
-     * open lives inside `engine.ready()`, so deferring it needs
-     * engine-level lazy-connect support, not just a provider prop).
-     *
-     * Mirrors `AbloOptions.bootstrapMode`. Changing it rotates the engine.
-     */
-    bootstrapMode?: 'full' | 'none';
+    /** @internal placeholder so the old WS-URL prop shape doesn't silently leak in. */
+    url?: never;
     /**
      * Rendered in place of `children` during the *first* bootstrap pass —
      * while the engine is actively transitioning from `initial` →

package/dist/react/AbloProvider.js

@@ -1,11 +1,10 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { useContext, useEffect, useMemo, useRef, useState, } from 'react';
-import { Ablo } from '../client/Ablo.js';
 import { createParticipantClaimId, parseParticipantTtlSeconds, resolveParticipantSyncGroups, } from '../sync/participants.js';
 import { SyncContext } from './context.js';
 import { AbloInternalContext } from './internalContext.js';
-import { AbloValidationError, AbloAuthenticationError } from '../errors.js';
+import { AbloValidationError } from '../errors.js';
 import { useSyncStatus } from './useSyncStatus.js';
 import { DefaultFallback } from './DefaultFallback.js';
 // ── Implementation ───────────────────────────────────────────────────
@@ -32,95 +31,52 @@ function createErrorEmitter() {
     };
 }
 export function AbloProvider(props) {
-    const { schema, url = 'wss://mesh.ablo.finance', userId, teamIds, apiKey, authToken, getToken, authEndpoint, preventUnsavedChanges, onSessionExpired, onError, observability, logger, mutationExecutor, mutationDispatcher, sessionErrorDetector, onlineStatus, configOverrides, syncGroups, scope, bootstrapBaseUrl, maxPoolSize, persistence, bootstrapMode, fallback = _jsx(DefaultFallback, {}), children, } = props;
-    // Account scope is no longer accepted from props. The engine learns
-    // it from auth (capability token) at bootstrap and we read it back
-    // out of `_store.orgId` once `engine.ready()` resolves.
+    const { client, userId, preventUnsavedChanges, onSessionExpired, onError, fallback = _jsx(DefaultFallback, {}), children, } = props;
+    // The client IS the engine — synchronous, never null. This provider is a
+    // REACTIVE binding over it (context + bootstrap gate + error/session
+    // forwarding); it does NOT construct, configure, or own the connection. The
+    // client owns auth, the credential lifecycle (first mint, refresh, and
+    // wake/online/focus re-mint — see `Ablo({ getToken })`), transport, and
+    // `dispose()`. The CONSUMER built the client, so the consumer owns teardown;
+    // the provider never disposes it.
+    const engine = client;
+    const schema = engine.schema;
+    // Account scope isn't a prop — read it from `_store.orgId` once `ready()`
+    // resolves the identity from the client's auth.
     const [resolvedAccountScope, setResolvedAccountScope] = useState(null);
     // ── Error emitter (provider-instance scoped) ─────────────────────
-    //
-    // Built once, reused for the lifetime of this provider. Survives
-    // engine rotations so error listeners don't need to resubscribe.
     const errorEmitterRef = useRef(null);
     if (!errorEmitterRef.current) {
         errorEmitterRef.current = createErrorEmitter();
     }
     const errorEmitter = errorEmitterRef.current;
-    // Stash `onError` in a ref so forwarding it doesn't trigger
-    // engine rotation. The provider wraps it and calls via ref at fire
-    // time, matching the `useEventCallback` idiom.
+    // Stash callbacks in refs so a new identity each render doesn't re-run the
+    // start effect (the `useEventCallback` idiom).
     const onErrorRef = useRef(onError);
     onErrorRef.current = onError;
     useEffect(() => {
         return errorEmitter.subscribe((err) => onErrorRef.current?.(err));
     }, [errorEmitter]);
-    // Stash the token resolver in a ref so a new function identity each render
-    // does not re-key (tear down) the engine. Read at fire time in the connect +
-    // refresh paths below — same `useEventCallback` idiom as `onError`. `getToken`
-    // wins; otherwise `authEndpoint` is fetched for `{ token }`.
-    const tokenFromEndpoint = authEndpoint
-        ? async () => {
-            const res = await fetch(authEndpoint, {
-                method: 'POST',
-                credentials: 'include',
-                headers: { 'Content-Type': 'application/json' },
-            });
-            if (!res.ok)
-                return null;
-            const body = (await res.json());
-            return body.token ?? null;
-        }
-        : undefined;
-    const getTokenRef = useRef(getToken ?? tokenFromEndpoint);
-    getTokenRef.current = getToken ?? tokenFromEndpoint;
-    // ── Engine lifecycle keyed on (userId, url) ─────────────────────
+    const onSessionExpiredRef = useRef(onSessionExpired);
+    onSessionExpiredRef.current = onSessionExpired;
+    // Re-key the bootstrap gate when the client INSTANCE changes — a genuinely new
+    // engine is a fresh "first bootstrap". Stable for the common single-client app.
+    const clientGenRef = useRef({ client, gen: 0 });
+    if (clientGenRef.current.client !== client) {
+        clientGenRef.current = { client, gen: clientGenRef.current.gen + 1 };
+    }
+    const engineKey = String(clientGenRef.current.gen);
+    // ── Start + session-error wiring ─────────────────────────────────
     //
-    // The engine rotates when either of these change. For everything
-    // else (mutators, DI, callbacks) we stash in refs so mutations to
-    // those props don't tear down the engine.
-    const engineKey = JSON.stringify({
-        userId: userId ?? null,
-        url,
-        bootstrapMode: bootstrapMode ?? null,
-    });
-    const [engineState, setEngineState] = useState({ key: engineKey, engine: null });
-    // Keep a ref to the current engine key so the rotation effect can
-    // detect late-arriving prop changes without causing React churn.
-    const currentKeyRef = useRef(engineState.key);
-    currentKeyRef.current = engineState.key;
+    // Two reactive jobs only:
+    //   1. Forward a SERVER session-rejection → purge (wipe IndexedDB so the next
+    //      login starts clean) → onSessionExpired (the app redirects). The
+    //      offline/transient-vs-terminal credential logic lives in the CLIENT now.
+    //   2. Drive `ready()` (idempotent) so bootstrap starts on mount, then read the
+    //      resolved org scope for SyncContext.
+    // It does NOT dispose the client (consumer-owned) and does NOT touch auth.
     useEffect(() => {
-        const abort = new AbortController();
-        let isStale = false;
-        setResolvedAccountScope(null);
-        // Construct engine + multiplayer streams for this key.
-        const engineOptions = {
-            baseURL: url,
-            schema,
-            ...(userId ? { user: { id: userId, teamIds } } : {}),
-            apiKey,
-            ...(authToken ? { authToken } : {}),
-            logger,
-            observability,
-            sessionErrorDetector,
-            onlineStatus,
-            mutationExecutor,
-            mutationDispatcher,
-            configOverrides,
-            // Union raw strings with model-form `scope` resolved through the schema,
-            // so `scope={{ decks: id }}` becomes `deck:<id>` via the model's `scope`.
-            syncGroups: scope
-                ? [...(syncGroups ?? []), ...resolveParticipantSyncGroups(scope, schema)]
-                : syncGroups,
-            bootstrapBaseUrl,
-            maxPoolSize,
-            persistence,
-            ...(bootstrapMode ? { bootstrapMode } : {}),
-            autoStart: false,
-        };
-        const engine = Ablo(engineOptions);
-        setEngineState({ key: engineKey, engine });
-        // Forward session-error events to the consumer. Purge first so
-        // the IndexedDB is wiped before the app redirects to /signin.
+        let stale = false;
         const unsubscribeSession = engine.onSessionError(async (err) => {
             errorEmitter.emit(err);
             try {
@@ -128,130 +84,37 @@ export function AbloProvider(props) {
             }
             catch { }
             try {
-                await onSessionExpired?.();
+                await onSessionExpiredRef.current?.();
             }
             catch (hookErr) {
                 errorEmitter.emit(hookErr);
             }
         });
-        // Drive initial bootstrap. Consumer code that wants to run logic
-        // after the engine is ready calls `useAblo()` and wires its own
-        // `useEffect` — the SDK no longer holds a registry of "post-
-        // bootstrap hooks" because the indirection costs more than it
-        // saves once `useAblo` exists.
-        (async () => {
-            try {
-                // Resolve a fresh bearer token BEFORE `ready()` (which connects —
-                // the engine is built with `autoStart: false`), so the first WS
-                // upgrade + bootstrap carry it. No race: nothing has connected yet.
-                const fetchToken = getTokenRef.current;
-                if (fetchToken) {
-                    const token = await fetchToken();
-                    if (isStale || abort.signal.aborted)
-                        return;
-                    if (token) {
-                        engine.setAuthToken(token);
-                    }
-                    else {
-                        // A configured `getToken` that resolves to falsy means "no active
-                        // session" — the session-token resolver (e.g. `getSyncCapabilityToken`)
-                        // returns null when logged out, the session hasn't hydrated, or the
-                        // mint endpoint rejects. Its contract is "the provider then surfaces
-                        // the usual unauthenticated path rather than connecting with a bad token."
-                        //
-                        // We MUST short-circuit here rather than fall through to
-                        // `engine.ready()`. On apps/web's identity path (org + user.id are
-                        // both supplied) `resolveParticipantIdentity` takes the
-                        // trust-the-caller Branch 3, which does NOT validate the (absent)
-                        // token — so init would proceed into `store.initialize()` and open
-                        // IndexedDB *before* any auth-bearing bootstrap/WS call. If storage
-                        // is at all wedged the no-session condition then surfaces only as an
-                        // opaque `IndexedDB "ablo_databases" open did not resolve within
-                        // 10000ms` stall, never the real auth error. Surface `session_expired`
-                        // explicitly and let the app redirect to sign-in.
-                        //
-                        // Unlike the server-detected `onSessionError` handler above, we do
-                        // NOT purge: nothing connected or wrote this mount, so any cached
-                        // IndexedDB belongs to a prior session and is reconciled by the next
-                        // valid bootstrap — purging here would drop a still-valid offline
-                        // queue on a merely transient null token.
-                        const authErr = new AbloAuthenticationError('No session token available — getToken() resolved to null. The ' +
-                            'session is missing or expired; sign in again.', { code: 'session_expired' });
-                        errorEmitter.emit(authErr);
-                        try {
-                            await onSessionExpired?.();
-                        }
-                        catch (hookErr) {
-                            errorEmitter.emit(hookErr);
-                        }
-                        return;
-                    }
-                }
-                await engine.ready();
-                if (isStale || abort.signal.aborted)
-                    return;
-                setResolvedAccountScope(engine._store.orgId ?? null);
-            }
-            catch (err) {
-                if (isStale || abort.signal.aborted)
-                    return;
-                errorEmitter.emit(err);
-            }
-        })();
+        engine
+            .ready()
+            .then(() => {
+            if (stale)
+                return;
+            setResolvedAccountScope(engine._store.orgId ?? null);
+        })
+            .catch((err) => {
+            if (stale)
+                return;
+            errorEmitter.emit(err);
+        });
         return () => {
-            isStale = true;
-            abort.abort();
+            stale = true;
             unsubscribeSession();
-            void engine.dispose();
-            // AbloClient is stateless-ish — participants manage their own
-            // WebSocket connections via `participant.disconnect()`. No client
-            // close is needed.
         };
-        // We intentionally only re-run on engineKey. All other DI is
-        // captured at first render; rotating the engine on every
-        // `mutationExecutor` identity change would destroy the WebSocket.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [engineKey]);
-    // ── Bearer-token refresh ─────────────────────────────────────────
-    //
-    // Short-lived tokens (the sync-server JWT defaults to 15m) must be rolled
-    // before they expire or the next reconnect/HTTP call fails auth. Re-resolve
-    // ahead of expiry and push via `engine.setAuthToken`, which swaps the token
-    // on the live WebSocket + bootstrap header without tearing down the engine.
-    // Only runs when a `getToken` resolver is wired (cookie deployments skip it).
-    useEffect(() => {
-        const engine = engineState.engine;
-        if (!engine || !getTokenRef.current)
-            return;
-        // Comfortably inside the 15m JWT lifetime; a missed tick is recovered by
-        // the next one well before expiry.
-        const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
-        const id = setInterval(() => {
-            void (async () => {
-                try {
-                    const token = await getTokenRef.current?.();
-                    if (token)
-                        engine.setAuthToken(token);
-                }
-                catch {
-                    // Transient (offline / session check). The next tick retries; the
-                    // engine keeps using the still-valid current token until then.
-                }
-            })();
-        }, REFRESH_INTERVAL_MS);
-        return () => clearInterval(id);
-    }, [engineState.engine]);
+    }, [engine, errorEmitter]);
     // ── beforeunload + preventUnsavedChanges ─────────────────────────
     useEffect(() => {
         if (typeof window === 'undefined')
             return;
         const handler = (event) => {
-            const engine = engineState.engine;
-            if (!engine)
-                return;
-            // Best-effort: dispose on unload. The async work may not
-            // complete before the tab closes — that's fine for IDB, which
-            // flushes pending writes transactionally.
+            // Best-effort IDB flush on TAB CLOSE — the client is going away with the
+            // page regardless. This is NOT an unmount teardown: the consumer owns the
+            // client's lifecycle and the provider never disposes it on unmount.
             void engine.dispose();
             if (preventUnsavedChanges && engine._store.hasUnsyncedChanges) {
                 event.preventDefault();
@@ -260,30 +123,30 @@ export function AbloProvider(props) {
         };
         window.addEventListener('beforeunload', handler);
         return () => window.removeEventListener('beforeunload', handler);
-    }, [engineState.engine, preventUnsavedChanges]);
+    }, [engine, preventUnsavedChanges]);
     // ── SyncContext value (for useQuery/useOne/useMutate hooks) ──────
+    //
+    // The engine is always present (it's the `client` prop), but its org scope is
+    // unknown until `ready()` resolves identity — so `syncValue` is null until
+    // then, which drives the initial fallback below.
     const syncValue = useMemo(() => {
-        if (!engineState.engine)
-            return null;
         const currentAccountScope = resolvedAccountScope ??
-            engineState.engine._store.orgId;
+            engine._store.orgId;
         if (!currentAccountScope)
             return null;
         return {
-            store: engineState.engine._store,
+            store: engine._store,
             organizationId: currentAccountScope,
             schema,
         };
-    }, [engineState.engine, resolvedAccountScope, schema]);
+    }, [engine, resolvedAccountScope, schema]);
     // ── Internal context (currentUserId + error subscription) ────────
     const internalValue = useMemo(() => ({
         currentUserId: userId ?? null,
         subscribeError: errorEmitter.subscribe,
         emitError: errorEmitter.emit,
-        // `engine` is null until bootstrap finishes; `useSync()` throws
-        // on null so callers are forced to gate with <ClientSideSuspense>.
-        engine: engineState.engine,
-    }), [userId, errorEmitter, engineState.engine]);
+        engine: engine,
+    }), [userId, errorEmitter, engine]);
     // ── Render ───────────────────────────────────────────────────────
     //
     // Two-phase gate (see `BootstrapGate` below for the latch logic):
@@ -307,7 +170,7 @@ export function AbloProvider(props) {
     if (!syncValue) {
         return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: initialFallback }));
     }
-    return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: _jsx(SyncContext.Provider, { value: syncValue, children: passthrough ? (children) : (_jsx(BootstrapGate, { fallback: fallback, children: children }, engineState.key)) }) }));
+    return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: _jsx(SyncContext.Provider, { value: syncValue, children: passthrough ? (children) : (_jsx(BootstrapGate, { fallback: fallback, children: children }, engineKey)) }) }));
 }
 /**
  * Internal gate that renders `fallback` only during the very first

package/dist/react/useAblo.d.ts

@@ -45,11 +45,11 @@ export type UseAbloHydratedModelResult<T> = Omit<UseAbloModelResult<T>, 'data'>
  * // With Register augmentation (recommended):
  * const ablo = useAblo();
  * if (!ablo) return <Loading />;
- * const doc = await ablo.documents.retrieve(id); // async server read
+ * const doc = await ablo.documents.retrieve({ id }); // async server read
  *
  * // Reactive selector (sync local-graph snapshot):
  * const doc = useAblo((ablo) => ablo.documents.get(id)) ?? serverDoc;
- * const active = useAblo((ablo) => ablo.documents.claim.state(id));
+ * const active = useAblo((ablo) => ablo.documents.claim.state({ id }));
  *
  * // Without augmentation, pass the schema generic:
  * const ablo = useAblo<(typeof schema)['models']>();

package/dist/react/useCurrentUserId.d.ts

@@ -13,7 +13,7 @@
  *   const userId = useCurrentUserId();
  *   const ablo = useAblo();
  *   if (!userId) return null;
- *   return <button onClick={() => ablo?.tasks.update(id, { assigneeId: userId })}>
+ *   return <button onClick={() => ablo?.tasks.update({ id, data: { assigneeId: userId } })}>
  *     Assign to me
  *   </button>;
  * }

package/dist/react/useCurrentUserId.js

@@ -17,7 +17,7 @@ import { AbloValidationError } from '../errors.js';
  *   const userId = useCurrentUserId();
  *   const ablo = useAblo();
  *   if (!userId) return null;
- *   return <button onClick={() => ablo?.tasks.update(id, { assigneeId: userId })}>
+ *   return <button onClick={() => ablo?.tasks.update({ id, data: { assigneeId: userId } })}>
  *     Assign to me
  *   </button>;
  * }

package/dist/react/useMutators.js

@@ -34,19 +34,26 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
                 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 (the slides UI fires
+                    // writes un-awaited) record in *invocation* order and never
+                    // interleave their shared-model snapshots. See UndoScope.runRecorded.
                     if (undoScope) {
-                        const recording = createRecordingTransaction(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) {
-                            getContext().logger.error(`[useMutators] mutator "${label}" threw`, { error: err });
-                            throw err;
-                        }
+                        return undoScope.runRecorded(async () => {
+                            const recording = createRecordingTransaction(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) {
+                                getContext().logger.error(`[useMutators] mutator "${label}" threw`, { error: err });
+                                throw err;
+                            }
+                        });
                     }
                     // Non-recording path — plain transaction, identical to pre-undo V1.
                     const tx = createTransaction(schema, store, organizationId);