@abloatai/ablo 0.9.1 → 0.9.2

package/dist/client/ApiClient.js

@@ -9,7 +9,6 @@ import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloVal
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, } from './auth.js';
 import { toSeconds } from '../utils/duration.js';
 const DEFAULT_AGENT_LEASE = '10m';
-const DEFAULT_INTENT_LEASE = '2m';
 export function createProtocolClient(options) {
     const env = readProcessEnv();
     const authInput = { options, env };
@@ -100,144 +99,6 @@ export function createProtocolClient(options) {
             schema: null,
         });
     }
-    function createAgent(id, agentOptions) {
-        return {
-            id,
-            async run(runOptions, handler) {
-                if (runOptions.signal?.aborted) {
-                    return { status: 'cancelled' };
-                }
-                let capability = null;
-                let task = null;
-                try {
-                    const leaseOptions = agentOptions.leaseSeconds !== undefined
-                        ? { leaseSeconds: agentOptions.leaseSeconds }
-                        : { lease: agentOptions.lease ?? DEFAULT_AGENT_LEASE };
-                    capability = await capabilities.create({
-                        participantKind: 'agent',
-                        participantId: id,
-                        syncGroups: agentOptions.syncGroups ?? ['default'],
-                        operations: agentOptions.can,
-                        label: agentOptions.label ?? id,
-                        userMeta: agentOptions.userMeta,
-                        ...leaseOptions,
-                    });
-                    const agentClient = capability.client();
-                    task = await agentClient.tasks.create({
-                        prompt: runOptions.prompt,
-                        parentTaskId: runOptions.parentTaskId,
-                        surface: runOptions.surface ?? 'agent',
-                        metadata: runOptions.metadata,
-                    });
-                    const context = createAgentRunContext(agentClient, task);
-                    const value = await handler(context);
-                    await task.close({
-                        costInputTokens: runOptions.costInputTokens,
-                        costOutputTokens: runOptions.costOutputTokens,
-                        costComputeMs: runOptions.costComputeMs,
-                    });
-                    return { status: 'done', task, value };
-                }
-                catch (error) {
-                    if (task) {
-                        await task.close({
-                            costInputTokens: runOptions.costInputTokens,
-                            costOutputTokens: runOptions.costOutputTokens,
-                            costComputeMs: runOptions.costComputeMs,
-                        }).catch(() => { });
-                    }
-                    if (isAbortError(error) || runOptions.signal?.aborted) {
-                        return { status: 'cancelled', task: task ?? undefined, error };
-                    }
-                    return { status: 'failed', task: task ?? undefined, error };
-                }
-                finally {
-                    if (capability) {
-                        await capabilities.revoke(capability.id).catch(() => { });
-                    }
-                }
-            },
-        };
-    }
-    function createAgentRunContext(agentClient, task) {
-        return {
-            task,
-            ablo: agentClient,
-            model(name) {
-                return createAgentModelClient(agentClient, name);
-            },
-        };
-    }
-    function createAgentModelClient(agentClient, name) {
-        const base = agentClient.model(name);
-        return {
-            retrieve(params) {
-                // Reads are never blocked by a claim (coordination.md): a claim
-                // serializes WRITERS, not readers. So — unlike the create/update/
-                // delete paths below — retrieve does NOT apply the agent claimed
-                // default; options pass through and the read path's `'return'`
-                // default keeps a claimed row readable. A caller can still opt into
-                // gating with an explicit `ifClaimed` (developer's choice).
-                return base.retrieve(params);
-            },
-            create(params) {
-                const id = params.id ?? createModelId();
-                return withAgentIntent(agentClient, name, id, params, (commitIntent) => base.create({
-                    ...stripAgentRuntimeOptions(params),
-                    id,
-                    data: params.data,
-                    intent: commitIntent,
-                }));
-            },
-            update(params) {
-                return withAgentIntent(agentClient, name, params.id, params, (commitIntent) => base.update({
-                    ...stripAgentRuntimeOptions(params),
-                    id: params.id,
-                    data: params.data,
-                    intent: commitIntent,
-                }));
-            },
-            delete(params) {
-                return withAgentIntent(agentClient, name, params.id, params, (commitIntent) => base.delete({
-                    ...stripAgentRuntimeOptions(params),
-                    id: params.id,
-                    intent: commitIntent,
-                }));
-            },
-        };
-    }
-    async function withAgentIntent(agentClient, modelName, id, mutationOptions, commit) {
-        const intentInput = mutationOptions?.intent;
-        const targetOverride = intentInput != null && typeof intentInput === 'object' && !isIntentHandleRef(intentInput)
-            ? intentInput.target ?? {}
-            : {};
-        const target = {
-            ...targetOverride,
-            model: targetOverride.model ?? modelName,
-            id: targetOverride.id ?? id,
-            ...(intentInput != null && typeof intentInput === 'object' && !isIntentHandleRef(intentInput) && intentInput.field
-                ? { field: intentInput.field }
-                : {}),
-        };
-        await applyClaimedPolicy(target, withAgentClaimedDefault(mutationOptions), 'wait');
-        if (intentInput == null || isIntentHandleRef(intentInput)) {
-            return commit(intentInput);
-        }
-        const action = typeof intentInput === 'string' ? intentInput : intentInput.action;
-        const intent = await agentClient.intents.create({
-            target,
-            action,
-            ttl: typeof intentInput === 'object'
-                ? intentInput.ttl ?? DEFAULT_INTENT_LEASE
-                : DEFAULT_INTENT_LEASE,
-        });
-        try {
-            return await commit(intent);
-        }
-        finally {
-            await intent.release().catch(() => { });
-        }
-    }
     function normalizeCommitOperation(op, defaults) {
         const model = op.model ?? op.target?.model;
         if (!model) {
@@ -476,51 +337,6 @@ export function createProtocolClient(options) {
             return capabilities.create(options);
         },
     };
-    const tasks = {
-        async create(taskOptions) {
-            const body = await requestJson('/v1/tasks', {
-                method: 'POST',
-                body: JSON.stringify({
-                    prompt: taskOptions.prompt,
-                    parentTaskId: taskOptions.parentTaskId,
-                    surface: taskOptions.surface,
-                    metadata: taskOptions.metadata,
-                }),
-            });
-            const id = body.id ?? body.taskId ?? body.turnId;
-            if (!id) {
-                throw new AbloValidationError('Task create response did not include an id.', { code: 'task_id_missing' });
-            }
-            return {
-                id,
-                turnId: id,
-                promptHash: body.promptHash,
-                openedAt: body.openedAt,
-                close: (stats) => tasks.close(id, stats),
-            };
-        },
-        async close(id, stats) {
-            const body = await requestJson(`/v1/tasks/${encodeURIComponent(id)}/close`, {
-                method: 'POST',
-                body: JSON.stringify({
-                    costInputTokens: stats?.costInputTokens ?? 0,
-                    costOutputTokens: stats?.costOutputTokens ?? 0,
-                    costComputeMs: stats?.costComputeMs ?? 0,
-                }),
-            });
-            const closedId = body.id ?? body.taskId ?? body.turnId ?? id;
-            return {
-                id: closedId,
-                turnId: closedId,
-                closed: body.closed ?? body.alreadyClosed ?? true,
-                alreadyClosed: body.alreadyClosed,
-                endedAt: body.endedAt,
-            };
-        },
-        open(options) {
-            return tasks.create(options);
-        },
-    };
     const intents = {
         async create(intentOptions) {
             const intentId = createIntentId();
@@ -780,35 +596,14 @@ export function createProtocolClient(options) {
         async dispose() { },
         async purge() { },
         capabilities,
-        tasks,
         intents,
         commits,
         model,
-        agent: createAgent,
         async getAuthToken() {
             // Mirror `authHeaders()`: a configured API key wins, else the
             // construction-time auth token. Resolve the (possibly async) key setter.
             return (await resolveApiKeyValue(configuredApiKey)) ?? configuredAuthToken ?? null;
         },
-        async beginTurn(turnOptions) {
-            const task = await tasks.create(turnOptions);
-            let closed = false;
-            const close = async (stats) => {
-                if (closed)
-                    return;
-                closed = true;
-                await task.close(stats);
-            };
-            const dispose = () => {
-                closed = true;
-            };
-            return {
-                turnId: task.id,
-                close,
-                dispose,
-                [Symbol.asyncDispose]: close,
-            };
-        },
     };
 }
 function normalizeIntentId(intent) {
@@ -816,33 +611,6 @@ function normalizeIntentId(intent) {
         return intent;
     return intent?.id;
 }
-function withAgentClaimedDefault(options) {
-    return {
-        ifClaimed: 'fail',
-        ...(options ?? {}),
-    };
-}
-function stripAgentRuntimeOptions(options) {
-    if (!options)
-        return undefined;
-    const { intent: _intent, ifClaimed: _ifClaimed, claimedTimeout: _claimedTimeout, claimedPollInterval: _claimedPollInterval, maxQueueDepth: _maxQueueDepth, ...rest } = options;
-    return rest;
-}
-function isIntentHandleRef(input) {
-    return (typeof input === 'object' &&
-        input !== null &&
-        'id' in input &&
-        typeof input.id === 'string' &&
-        !('action' in input));
-}
-function isAbortError(error) {
-    return (typeof DOMException !== 'undefined' &&
-        error instanceof DOMException &&
-        error.name === 'AbortError') || (typeof error === 'object' &&
-        error !== null &&
-        'name' in error &&
-        error.name === 'AbortError');
-}
 function parseBody(bodyText) {
     if (bodyText.length === 0)
         return null;

package/dist/client/auth.js

@@ -146,8 +146,38 @@ export function resolveBootstrapBaseUrl(input) {
         // legitimately arrive as `wss://…` — normalize it here rather than
         // faceplanting at fetch time. The derive branch below already does this;
         // the override branch silently skipped it.
-        return normalizeAbloHostedBaseUrl(input.bootstrapBaseUrl).replace(/^ws/, 'http');
+        return ensureApiSuffix(normalizeAbloHostedBaseUrl(input.bootstrapBaseUrl).replace(/^ws/, 'http'));
     }
     const url = normalizeAbloHostedBaseUrl(input.url);
-    return `${url.replace(/^ws/, 'http')}/api`;
+    return ensureApiSuffix(url.replace(/^ws/, 'http'));
+}
+/**
+ * Guarantee the HTTP base ends in the `/api` route segment the sync-server
+ * mounts every endpoint under (`apps/sync-server/src/index.ts` — `app.route('/api', …)`).
+ *
+ * The derive branch always appended `/api`; the override branch did NOT,
+ * trusting the caller (apps/web passes `${baseUrl}/api`). But a hosted
+ * customer setting a custom `baseURL`/`bootstrapBaseUrl` (their own subdomain,
+ * staging, etc.) without the suffix sent every credential exchange to
+ * `…/auth/capability` instead of `…/api/auth/capability` → a 404 surfaced as
+ * `exchange_failed`. Since the SDK hardcodes routes relative to this base and
+ * there is no valid Ablo deployment that serves them off the root, normalizing
+ * to a single trailing `/api` here is always correct — and idempotent for
+ * callers who already include it.
+ */
+function ensureApiSuffix(httpBase) {
+    const trimmed = httpBase.replace(/\/+$/, '');
+    try {
+        const u = new URL(trimmed);
+        const segments = u.pathname.split('/').filter(Boolean);
+        if (segments[segments.length - 1] === 'api')
+            return trimmed;
+        u.pathname = `${u.pathname.replace(/\/+$/, '')}/api`;
+        return u.toString().replace(/\/+$/, '');
+    }
+    catch {
+        // Should be unreachable post-`normalizeAbloHostedBaseUrl` (which yields an
+        // absolute URL), but fall back to a string check rather than throwing.
+        return /\/api$/.test(trimmed) ? trimmed : `${trimmed}/api`;
+    }
 }

package/dist/client/httpClient.d.ts

@@ -22,8 +22,8 @@
  * wraps it in a typed proxy facade so server code gets the SAME `client.<model>`
  * surface as the browser client — typed proxies, stateless transport.
  */
-import { type AbloApiClientOptions, type TaskCreateOptions } from './ApiClient.js';
-import type { CommitReceipt, CommitResource, HttpClaimApi, ModelRead, ModelReadOptions, Turn } from './Ablo.js';
+import { type AbloApiClientOptions } from './ApiClient.js';
+import type { CommitReceipt, CommitResource, HttpClaimApi, ModelRead, ModelReadOptions } from './Ablo.js';
 import type { ModelCreateParams, ModelDeleteParams, ModelLoadOptions, ModelRetrieveParams, ModelUpdateParams } from './createModelProxy.js';
 import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
 export interface AbloHttpClientOptions<S extends SchemaRecord> extends Omit<AbloApiClientOptions, 'schema'> {
@@ -47,7 +47,7 @@ export interface HttpModelClient<T, C = T> {
 }
 /**
  * The honest type of the stateless HTTP client: typed model proxies (the
- * request/response subset) + `commits` + `beginTurn` + `dispose`. Reaching for a
+ * request/response subset) + `commits` + `dispose`. Reaching for a
  * stateful-only capability (`get`/`getAll`/`getCount`, `onChange`,
  * `claim.state`/`queue`/`reorder`) is a COMPILE error here, not a latent runtime
  * `undefined` — the type matches what the transport can actually do.
@@ -56,7 +56,6 @@ export type AbloHttpClient<S extends SchemaRecord> = {
     readonly [K in keyof S & string]: HttpModelClient<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
 } & {
     readonly commits: CommitResource;
-    beginTurn(options: TaskCreateOptions): Promise<Turn>;
     dispose(): Promise<void>;
     /** Resolve the bearer credential this client authenticates with (see `AbloApi.getAuthToken`). */
     getAuthToken(): Promise<string | null>;
@@ -65,7 +64,7 @@ export type AbloHttpClient<S extends SchemaRecord> = {
 };
 /**
  * Stateless, typed HTTP client. Each `client.<model>` resolves to the protocol
- * client's `model(name)`; `commits`, `beginTurn`, `tasks`, `dispose`, etc. pass
- * through. No socket is ever opened; identity is the Bearer credential.
+ * client's `model(name)`; `commits`, `dispose`, etc. pass through. No socket is
+ * ever opened; identity is the Bearer credential.
  */
 export declare function createAbloHttpClient<S extends SchemaRecord>(options: AbloHttpClientOptions<S>): AbloHttpClient<S>;

package/dist/client/httpClient.js

@@ -36,14 +36,13 @@ const PROTOCOL_MEMBERS = new Set([
     'dispose',
     'purge',
     'commits',
-    'beginTurn',
     'model',
     'getAuthToken',
 ]);
 /**
  * Stateless, typed HTTP client. Each `client.<model>` resolves to the protocol
- * client's `model(name)`; `commits`, `beginTurn`, `tasks`, `dispose`, etc. pass
- * through. No socket is ever opened; identity is the Bearer credential.
+ * client's `model(name)`; `commits`, `dispose`, etc. pass through. No socket is
+ * ever opened; identity is the Bearer credential.
  */
 export function createAbloHttpClient(options) {
     // The schema is type-level only; the protocol client is schema-agnostic.

package/dist/client/index.d.ts

@@ -32,5 +32,5 @@
 export { Ablo, computeFKDepthPriority, type AbloOptions, type InternalAbloOptions, type ClaimedOptions, type IfClaimedPolicy, type IntentWaitOptions, type ModelCountOptions, type ModelListOptions, type ModelListScope, type ModelLoadOptions, type ModelOperations, type ModelReadOptions, } from './Ablo.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './auth.js';
 export type { AbloPersistence } from './persistence.js';
-export type { AbloApi, AbloApiClientOptions, AbloApiIntents, Agent, AgentIntentInput, AgentIntentOptions, AgentOptions, AgentModelClient, AgentModelReadOptions, AgentModelMutationOptions, AgentRunContext, AgentRunDone, AgentRunFailed, AgentRunCancelled, AgentRunOptions, AgentRunResult, AgentRunStatus, Capability, CapabilityCreateOptions, CapabilityParticipantKind, CapabilityRecord, CapabilityResource, CapabilityRevocation, CapabilityScope, Task, TaskCloseOptions, TaskCloseResult, TaskCreateOptions, TaskResource, } from './ApiClient.js';
+export type { AbloApi, AbloApiClientOptions, AbloApiIntents, Capability, CapabilityCreateOptions, CapabilityParticipantKind, CapabilityRecord, CapabilityResource, CapabilityRevocation, CapabilityScope, } from './ApiClient.js';
 export type { EngineParticipant, JoinedParticipant, ParticipantJoinOptions, ParticipantManager, ParticipantScope, ParticipantStatus, ScopedIntents, ScopedPresence, } from '../sync/participants.js';

package/dist/errorCodes.js

@@ -176,8 +176,8 @@ export const ERROR_CODES = {
     check_violation: wire('validation', 400, false, 'A value violates a database check constraint.'),
     constraint_violation: wire('validation', 400, false, 'A database integrity constraint was violated.'),
     // ── tenant / unknown model (400) ───────────────────────────────────
-    server_execute_unknown_model: wire('tenant', 400, false, 'The server-execute request named a model not in the tenant schema.'),
-    mutate_create_unknown_model: wire('tenant', 400, false, 'A create targeted a model not in the tenant schema.'),
+    server_execute_unknown_model: wire('tenant', 400, false, 'Wrote to a model the server does not know. The server keeps its own copy of the schema — run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` before writing to new or changed models.'),
+    mutate_create_unknown_model: wire('tenant', 400, false, 'Created a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` first — the server keeps its own copy of the schema.'),
     tenant_model_columns_unknown: wire('tenant', 400, false, "The tenant model's columns could not be resolved."),
     tenant_model_missing_organization_id: wire('tenant', 400, false, 'The tenant model is missing the organization_id column required for isolation.'),
     // ── schema migration / declaration (validation) ────────────────────
@@ -286,7 +286,7 @@ export const ERROR_CODES = {
     provisioner_unavailable: wire('server', 503, false, 'No database provisioner is configured.'),
     invalid_model: wire('validation', 400, false, 'The request named an invalid model.'),
     invalid_id: wire('validation', 400, false, 'The request carried an invalid id.'),
-    unknown_model: wire('tenant', 400, false, 'The request named a model not in the tenant schema.'),
+    unknown_model: wire('tenant', 400, false, 'Named a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` — the server keeps its own copy of the schema.'),
     model_not_tenant_scoped: wire('tenant', 400, false, 'The model is not tenant-scoped and cannot be queried this way.'),
     schema_table_invalid: wire('schema', 500, false, "The model's table identifier is invalid."),
     schema_scope_invalid: wire('schema', 500, false, "The model's scope predicate could not be built."),

package/dist/index.js

@@ -61,7 +61,7 @@ export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_UR
 // Participant types live under `Ablo.Participant.*` —
 // `Ablo.Participant.Joined`, `Ablo.Participant.Manager`,
 // `Ablo.Participant.JoinOptions`, etc. Same dot-access shape as
-// `Ablo.Peer`, `Ablo.Claim`, `Ablo.Turn`. No flat re-exports.
+// `Ablo.Peer`, `Ablo.Claim`. No flat re-exports.
 // Advanced — most apps never import this. Principal constructors for
 // delegated agent paths (`Ablo({ kind: 'agent', as: session({...}) })`).
 // The default `Ablo({ schema, apiKey })` resolves identity from the key;

package/dist/interfaces/index.d.ts

@@ -164,10 +164,10 @@ export interface MutationOptions {
         readonly id: string;
     } | null;
     /**
-     * Active agent turn id to stamp on every delta row produced by this
-     * commit. Forwarded as the wire-level `causedByTaskId` field on the
-     * `{ type: 'commit' }` envelope. Set automatically by the SDK while
-     * `beginTurn(...)` is open.
+     * Dormant agent-task lineage field, forwarded as the wire-level
+     * `causedByTaskId`. Turns/tasks were removed from the SDK; nothing
+     * populates this anymore (write attribution rides on the claim/intent
+     * id). Kept optional for wire-compat; always `null` from the client.
      */
     causedByTaskId?: string | null;
 }

package/dist/mutators/UndoManager.d.ts

@@ -75,6 +75,15 @@ export declare class UndoScope<S extends Schema> {
      * observer can never wedge the editor's recording path.
      */
     private readonly recordListeners;
+    /**
+     * Observers notified after ANY stack change — record, undo, redo, or clear.
+     * Distinct from {@link recordListeners} (forward actions only): this fires on
+     * reversals too, so React consumers can keep `canUndo`/`canRedo` live. The
+     * stream-recording path pushes entries WITHOUT a React render, so without this
+     * a freshly-recorded entry leaves `canUndo` stale (snapshot from last render)
+     * and a Cmd+Z handler gated on `canUndo !== false` silently no-ops.
+     */
+    private readonly changeListeners;
     /**
      * Serialization tail. Recording, undo, and redo all chain off this single
      * promise so they run strictly in the order they were *invoked* — never
@@ -175,6 +184,14 @@ export declare class UndoScope<S extends Schema> {
      */
     onRecord(listener: (entry: UndoEntry) => void): () => void;
     private emitRecord;
+    /**
+     * Subscribe to ANY stack change (record/undo/redo/clear). Used by
+     * `useUndoScope` to re-render so `canUndo`/`canRedo` stay live across every
+     * consumer — not just the component that invoked undo/redo. Returns an
+     * unsubscribe function.
+     */
+    onChange(listener: () => void): () => void;
+    private emitChange;
     canUndo(): boolean;
     canRedo(): boolean;
     /**

package/dist/mutators/UndoManager.js

@@ -46,6 +46,15 @@ export class UndoScope {
      * observer can never wedge the editor's recording path.
      */
     recordListeners = new Set();
+    /**
+     * Observers notified after ANY stack change — record, undo, redo, or clear.
+     * Distinct from {@link recordListeners} (forward actions only): this fires on
+     * reversals too, so React consumers can keep `canUndo`/`canRedo` live. The
+     * stream-recording path pushes entries WITHOUT a React render, so without this
+     * a freshly-recorded entry leaves `canUndo` stale (snapshot from last render)
+     * and a Cmd+Z handler gated on `canUndo !== false` silently no-ops.
+     */
+    changeListeners = new Set();
     /**
      * Serialization tail. Recording, undo, and redo all chain off this single
      * promise so they run strictly in the order they were *invoked* — never
@@ -246,6 +255,7 @@ export class UndoScope {
             this.undoStack.shift();
         this.redoStack = [];
         this.emitRecord(entry);
+        this.emitChange();
     }
     /**
      * Subscribe to every recorded mutation. Fires synchronously at the tail of
@@ -275,6 +285,30 @@ export class UndoScope {
             }
         }
     }
+    /**
+     * Subscribe to ANY stack change (record/undo/redo/clear). Used by
+     * `useUndoScope` to re-render so `canUndo`/`canRedo` stay live across every
+     * consumer — not just the component that invoked undo/redo. Returns an
+     * unsubscribe function.
+     */
+    onChange(listener) {
+        this.changeListeners.add(listener);
+        return () => {
+            this.changeListeners.delete(listener);
+        };
+    }
+    emitChange() {
+        for (const listener of this.changeListeners) {
+            try {
+                listener();
+            }
+            catch (err) {
+                if (typeof console !== 'undefined') {
+                    console.error('[UndoScope] onChange listener threw', err);
+                }
+            }
+        }
+    }
     canUndo() {
         return this.undoStack.length > 0;
     }
@@ -302,12 +336,21 @@ export class UndoScope {
             try {
                 await applyOps(tx, ops);
             }
+            catch (err) {
+                // The replay was rejected (e.g. a server 409): the world didn't change,
+                // so restore the entry to the undo stack rather than silently dropping
+                // it (which would also strand it off the redo stack — invisible undo).
+                this.undoStack.push(entry);
+                this.emitChange();
+                throw err;
+            }
             finally {
                 this.replaying = false;
             }
             this.redoStack.push(entry);
             if (this.redoStack.length > this.maxHistory)
                 this.redoStack.shift();
+            this.emitChange();
         });
     }
     /**
@@ -327,12 +370,20 @@ export class UndoScope {
             try {
                 await applyOps(tx, ops);
             }
+            catch (err) {
+                // Symmetric to undo: a rejected re-apply leaves state unchanged, so put
+                // the entry back on the redo stack instead of losing it.
+                this.redoStack.push(entry);
+                this.emitChange();
+                throw err;
+            }
             finally {
                 this.replaying = false;
             }
             this.undoStack.push(entry);
             if (this.undoStack.length > this.maxHistory)
                 this.undoStack.shift();
+            this.emitChange();
         });
     }
     /** Drop all history. Use after bootstrap / sync group change / sync error. */
@@ -340,6 +391,7 @@ export class UndoScope {
         this.undoStack = [];
         this.redoStack = [];
         this.batch = [];
+        this.emitChange();
     }
     /** Introspection — for debug panels / e2e tests. */
     size() {
@@ -353,6 +405,7 @@ export class UndoScope {
     dispose() {
         this.unsubscribe();
         this.recordListeners.clear();
+        this.changeListeners.clear();
         this.batch = [];
     }
 }

package/dist/react/AbloProvider.d.ts

@@ -28,20 +28,30 @@ import { type SyncStoreContract } from './context.js';
 /**
  * Props for `<AbloProvider>`.
  *
- * The default path is one prop:
+ * The one required prop is a prebuilt {@link Ablo} client — the client
+ * owns auth and the credential lifecycle; this provider is the reactive
+ * binding over it (Stripe's `<Elements stripe={...}>` model):
  *
  * ```tsx
- * <AbloProvider schema={schema}>
+ * // Build once at module scope — a new instance per render tears down the socket.
+ * const ablo = Ablo({
+ *   schema,
+ *   getToken: () =>
+ *     fetch('/api/ablo-session', { method: 'POST' })
+ *       .then((r) => r.json())
+ *       .then((d) => d.token),
+ * });
+ *
+ * <AbloProvider client={ablo}>
  *   <App />
  * </AbloProvider>
  * ```
  *
- * That's it for most apps — the provider resolves identity, account
- * scope, and realtime permissions from auth. `userId`/`apiKey`/`url`
- * are situational; the `bootstrapMode`, `persistence`, and `fallback`
- * props are opt-in tuning; and the block tagged "Optional DI (advanced)"
- * below is escape-hatch wiring for tests and platform builders — if you
- * don't recognize a prop there, you don't need it.
+ * That's it for most apps. `userId` is informational; the `fallback`,
+ * `preventUnsavedChanges`, and `on*` props are opt-in app glue; and the
+ * block tagged "Optional DI (advanced)" below is escape-hatch wiring for
+ * tests and platform builders — if you don't recognize a prop there, you
+ * don't need it.
  */
 export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
     /**

package/dist/react/index.d.ts

@@ -27,7 +27,7 @@
  *   useCurrentUserId()        — the provider's userId prop
  *
  * Multiplayer (always available — `<AbloProvider>` always constructs a client):
- *   useAblo((ablo) => ablo.intents.list(...)) — reactive coordination reads
+ *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
  *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
  *   usePresence()             — typed presence view
  *   useIntent(name)           — typed intent dispatcher

package/dist/react/index.js

@@ -27,7 +27,7 @@
  *   useCurrentUserId()        — the provider's userId prop
  *
  * Multiplayer (always available — `<AbloProvider>` always constructs a client):
- *   useAblo((ablo) => ablo.intents.list(...)) — reactive coordination reads
+ *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
  *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
  *   usePresence()             — typed presence view
  *   useIntent(name)           — typed intent dispatcher

package/dist/react/useUndoScope.js

@@ -52,6 +52,13 @@ export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
     useEffect(() => {
         setTick(0);
     }, [scope]);
+    // Re-render on ANY stack change — including entries recorded from the local-
+    // mutation stream, which don't otherwise trigger a React update. Without this
+    // `canUndo`/`canRedo` go stale in every consumer that didn't itself call
+    // undo/redo (e.g. a keyboard handler whose Cmd+Z gate then never fires).
+    useEffect(() => {
+        return scope.onChange(() => setTick((t) => t + 1));
+    }, [scope]);
     const size = scope.size();
     return {
         scope,