@abloatai/ablo 0.9.0 → 0.9.2

package/dist/mutators/UndoManager.d.ts

@@ -34,6 +34,23 @@ export interface UndoScopeOptions {
      * {@link UndoConflictPolicy}.
      */
     conflictPolicy?: UndoConflictPolicy;
+    /**
+     * Which models this surface owns. The scope only records mutations whose
+     * resolved schema key passes this predicate, so a spreadsheet edit never
+     * lands on the deck editor's stack (the equivalent of Yjs scoping by
+     * shared-type set). Omit to track every model — fine for a single-surface
+     * app, wrong when two surfaces with independent Cmd+Z share one store.
+     */
+    tracksModel?: (schemaKey: string) => boolean;
+    /**
+     * Opt into recording undo entries by OBSERVING the local-mutation stream
+     * (the best-practice model: undo listens where all local writes converge —
+     * Yjs/Liveblocks). When false (default), the scope records nothing on its
+     * own and relies on legacy manual `record()` calls. Transitional: a scope
+     * must not mix the two, or shared writes double-count. Flip a surface to
+     * `true` only when its manual-record consumers are removed in the same step.
+     */
+    recordFromStream?: boolean;
 }
 /**
  * A single undo stack for one surface. Access via `UndoManager.getScope(name)`.
@@ -58,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
@@ -72,7 +98,52 @@ export declare class UndoScope<S extends Schema> {
      * Serializing the whole scope closes both holes with one mechanism.
      */
     private tail;
+    /** Predicate selecting which models this surface records (see options). */
+    private readonly tracksModel?;
+    /** registered-name / alias → schema key, built once from the schema. */
+    private readonly schemaKeyByAlias;
+    /** Unsubscribe from the local-mutation stream. */
+    private readonly unsubscribe;
+    /**
+     * True while `undo()`/`redo()` replays ops. Replays write through the same
+     * commit path, so they re-emit on the local-mutation stream; this flag tells
+     * our own listener to ignore them (no echo) — the engine equivalent of Yjs's
+     * `trackedOrigins` exclusion / Liveblocks pausing history during undo.
+     */
+    private replaying;
+    /** Ops collected during the current tick, flushed as ONE entry. */
+    private batch;
+    private flushScheduled;
+    /**
+     * Open grouping session (Liveblocks `history.pause()` / Yjs `stopCapturing`
+     * analogue). While set, stream ops accumulate here ACROSS ticks instead of
+     * flushing per-tick, so a multi-tick action (a drag, a whole streaming AI
+     * response) collapses into ONE Cmd+Z. `endGroup()` flushes it.
+     */
+    private group;
     constructor(schema: S, store: SyncStoreContract, organizationId: string, options?: UndoScopeOptions);
+    /**
+     * Open a grouping session: every stream-recorded op until {@link endGroup}
+     * collapses into a single undo entry. Mirrors Liveblocks `history.pause()` —
+     * call on gesture start (pointerdown) or AI-response start. Idempotent-ish:
+     * a second call closes the previous group first.
+     */
+    beginGroup(label?: string): void;
+    /** Close the grouping session and record the accumulated ops as one entry. */
+    endGroup(label?: string): void;
+    /** Resolve a stream mutation's registered name to its schema key, or null. */
+    private resolveSchemaKey;
+    /**
+     * Stream listener — the sole place entries are born. Skips replay echoes
+     * and out-of-scope models, derives the forward+inverse op from the
+     * mutation's `data`/`previousData`, and defers the stack push to a
+     * per-tick flush so a burst of writes (e.g. align 5 layers) becomes ONE
+     * undo step — riding the same tick boundary the TransactionQueue batches on.
+     */
+    private onLocalMutation;
+    private scheduleFlush;
+    /** Coalesce the tick's collected ops into one entry and record it. */
+    private flushBatch;
     /**
      * Run `work` after every previously-enqueued scope operation has settled,
      * in invocation order. The internal `tail` always resolves (failures are
@@ -82,20 +153,24 @@ export declare class UndoScope<S extends Schema> {
     private enqueue;
     /**
      * Run a recording mutator exclusively on the scope's serialization chain.
-     * `useMutators` calls this so the snapshot → write → `record()` sequence is
-     * atomic relative to other invocations, undo, and redo.
+     * Used by the legacy manual-record path (`useMutators` + `RecordingTransaction`)
+     * so the snapshot → write → `record()` sequence is atomic relative to undo/
+     * redo. The stream-recording path doesn't need this (it derives entries from
+     * already-committed mutations); kept until all surfaces migrate off manual.
      */
     runRecorded<T>(work: () => Promise<T>): Promise<T>;
     /**
-     * Internal: record a mutator's inverses. Clears the redo stack.
-     *
-     * Entries here are produced internally by `RecordingTransaction` (trusted),
-     * so the schema check is DEV-ONLY: it catches recorder bugs in dev/test
-     * (rejecting a malformed op at ingestion, with its path, instead of letting
-     * it crash later inside `applyOps`) without paying a Zod parse on every user
-     * action in production. The real validation boundary is `parseUndoEntry`,
-     * applied when entries are deserialized from persistence (untrusted input).
-     * Best practice: validate at trust boundaries, type-check internal calls.
+     * Record one entry onto the undo stack. Clears the redo stack. Fed by
+     * {@link flushBatch}/{@link endGroup} from the local-mutation stream, and
+     * still called directly by the legacy manual-record consumers
+     * (`useMutators`, the AI mutation pipeline) until they migrate. Entries are
+     * built internally (trusted), so the schema check is DEV-ONLY: it catches
+     * recorder bugs in dev/test (rejecting a malformed op at ingestion, with its
+     * path, instead of letting it crash later inside `applyOps`) without paying a
+     * Zod parse on every user action in production. The real validation boundary
+     * is `parseUndoEntry`, applied when entries are deserialized from persistence
+     * (untrusted input). Best practice: validate at trust boundaries, type-check
+     * internal calls.
      */
     record(entry: UndoEntry): void;
     /**
@@ -109,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;
     /**
@@ -134,6 +217,12 @@ export declare class UndoScope<S extends Schema> {
         undo: number;
         redo: number;
     };
+    /**
+     * Detach from the local-mutation stream and drop listeners. Scopes are
+     * cached for the store's lifetime by `UndoManager`, so this is mainly for
+     * tests and explicit teardown.
+     */
+    dispose(): void;
 }
 /**
  * Central registry of named undo scopes. One per-app instance, created once

package/dist/mutators/UndoManager.js

@@ -20,6 +20,9 @@
 import { createTransaction } from './Transaction.js';
 import { parseUndoEntry } from './inverseOp.js';
 import { resolveOps, DEFAULT_UNDO_CONFLICT_POLICY, } from './undoApply.js';
+/** Normalize a registered model name to the queue's lowercased alias form
+ * (mirrors TransactionQueue's `normalizeModelKey`). */
+const normalizeModelAlias = (modelName) => modelName.replace('Model', '').toLowerCase();
 /**
  * A single undo stack for one surface. Access via `UndoManager.getScope(name)`.
  * Consumers call `record(entry)` after each mutator; `undo()` / `redo()` to
@@ -43,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
@@ -57,12 +69,148 @@ export class UndoScope {
      * Serializing the whole scope closes both holes with one mechanism.
      */
     tail = Promise.resolve();
+    /** Predicate selecting which models this surface records (see options). */
+    tracksModel;
+    /** registered-name / alias → schema key, built once from the schema. */
+    schemaKeyByAlias = new Map();
+    /** Unsubscribe from the local-mutation stream. */
+    unsubscribe;
+    /**
+     * True while `undo()`/`redo()` replays ops. Replays write through the same
+     * commit path, so they re-emit on the local-mutation stream; this flag tells
+     * our own listener to ignore them (no echo) — the engine equivalent of Yjs's
+     * `trackedOrigins` exclusion / Liveblocks pausing history during undo.
+     */
+    replaying = false;
+    /** Ops collected during the current tick, flushed as ONE entry. */
+    batch = [];
+    flushScheduled = false;
+    /**
+     * Open grouping session (Liveblocks `history.pause()` / Yjs `stopCapturing`
+     * analogue). While set, stream ops accumulate here ACROSS ticks instead of
+     * flushing per-tick, so a multi-tick action (a drag, a whole streaming AI
+     * response) collapses into ONE Cmd+Z. `endGroup()` flushes it.
+     */
+    group = null;
     constructor(schema, store, organizationId, options = {}) {
         this.schema = schema;
         this.store = store;
         this.organizationId = organizationId;
         this.maxHistory = options.maxHistory ?? 100;
         this.conflictPolicy = options.conflictPolicy ?? DEFAULT_UNDO_CONFLICT_POLICY;
+        this.tracksModel = options.tracksModel;
+        // Build the registered-name → schema-key alias map. The mutation stream
+        // reports `model.getModelName()` (e.g. `'SlideLayer'`), but inverse ops
+        // and the replay transaction are keyed by the SCHEMA key (e.g.
+        // `'slideLayers'`). Map every reasonable spelling to the schema key.
+        for (const schemaKey of Object.keys(this.schema.models)) {
+            const def = this.schema.models[schemaKey];
+            const typename = def?.typename ?? schemaKey;
+            for (const alias of [schemaKey, typename]) {
+                this.schemaKeyByAlias.set(alias, schemaKey);
+                this.schemaKeyByAlias.set(alias.toLowerCase(), schemaKey);
+                this.schemaKeyByAlias.set(normalizeModelAlias(alias), schemaKey);
+            }
+        }
+        // Subscribe to the local-mutation stream ONLY when this scope opts into
+        // stream recording. Transitional flag: surfaces still on the legacy
+        // manual-record path (mutator `RecordingTransaction`, AI pipeline
+        // sessions) keep `recordFromStream: false` so writes aren't double-counted.
+        // Once every surface is migrated, stream recording becomes the only path
+        // and the flag is removed. Optional on the contract so minimal test
+        // doubles can omit it (undo then records nothing).
+        this.unsubscribe =
+            options.recordFromStream && this.store.subscribeLocalMutations
+                ? this.store.subscribeLocalMutations((m) => this.onLocalMutation(m))
+                : () => { };
+    }
+    /**
+     * Open a grouping session: every stream-recorded op until {@link endGroup}
+     * collapses into a single undo entry. Mirrors Liveblocks `history.pause()` —
+     * call on gesture start (pointerdown) or AI-response start. Idempotent-ish:
+     * a second call closes the previous group first.
+     */
+    beginGroup(label) {
+        if (this.group)
+            this.endGroup();
+        this.group = { label, ops: [] };
+    }
+    /** Close the grouping session and record the accumulated ops as one entry. */
+    endGroup(label) {
+        const g = this.group;
+        if (!g)
+            return;
+        this.group = null;
+        const forwards = g.ops.map((c) => c.forward);
+        const inverses = g.ops
+            .map((c) => c.inverse)
+            .filter((i) => i !== null)
+            .reverse();
+        if (forwards.length === 0 && inverses.length === 0)
+            return;
+        this.record({ label: label ?? g.label, inverses, forwards });
+    }
+    /** Resolve a stream mutation's registered name to its schema key, or null. */
+    resolveSchemaKey(modelName) {
+        return (this.schemaKeyByAlias.get(modelName) ??
+            this.schemaKeyByAlias.get(normalizeModelAlias(modelName)) ??
+            null);
+    }
+    /**
+     * Stream listener — the sole place entries are born. Skips replay echoes
+     * and out-of-scope models, derives the forward+inverse op from the
+     * mutation's `data`/`previousData`, and defers the stack push to a
+     * per-tick flush so a burst of writes (e.g. align 5 layers) becomes ONE
+     * undo step — riding the same tick boundary the TransactionQueue batches on.
+     */
+    onLocalMutation(m) {
+        if (this.replaying)
+            return;
+        const schemaKey = this.resolveSchemaKey(m.modelName);
+        if (!schemaKey)
+            return;
+        if (this.tracksModel && !this.tracksModel(schemaKey))
+            return;
+        const ops = buildUndoOps(m, schemaKey);
+        if (!ops)
+            return;
+        // Inside a grouping session, accumulate across ticks (flushed on
+        // endGroup); otherwise coalesce per-tick.
+        if (this.group) {
+            this.group.ops.push(ops);
+            return;
+        }
+        this.batch.push(ops);
+        this.scheduleFlush();
+    }
+    scheduleFlush() {
+        if (this.flushScheduled)
+            return;
+        this.flushScheduled = true;
+        const run = () => {
+            this.flushScheduled = false;
+            this.flushBatch();
+        };
+        if (typeof queueMicrotask === 'function')
+            queueMicrotask(run);
+        else
+            void Promise.resolve().then(run);
+    }
+    /** Coalesce the tick's collected ops into one entry and record it. */
+    flushBatch() {
+        if (this.batch.length === 0)
+            return;
+        const collected = this.batch;
+        this.batch = [];
+        const forwards = collected.map((c) => c.forward);
+        // Undo applies inverses in REVERSE order of how the forwards ran.
+        const inverses = collected
+            .map((c) => c.inverse)
+            .filter((i) => i !== null)
+            .reverse();
+        if (forwards.length === 0 && inverses.length === 0)
+            return;
+        this.record({ inverses, forwards });
     }
     /**
      * Run `work` after every previously-enqueued scope operation has settled,
@@ -77,22 +225,26 @@ export class UndoScope {
     }
     /**
      * Run a recording mutator exclusively on the scope's serialization chain.
-     * `useMutators` calls this so the snapshot → write → `record()` sequence is
-     * atomic relative to other invocations, undo, and redo.
+     * Used by the legacy manual-record path (`useMutators` + `RecordingTransaction`)
+     * so the snapshot → write → `record()` sequence is atomic relative to undo/
+     * redo. The stream-recording path doesn't need this (it derives entries from
+     * already-committed mutations); kept until all surfaces migrate off manual.
      */
     runRecorded(work) {
         return this.enqueue(work);
     }
     /**
-     * Internal: record a mutator's inverses. Clears the redo stack.
-     *
-     * Entries here are produced internally by `RecordingTransaction` (trusted),
-     * so the schema check is DEV-ONLY: it catches recorder bugs in dev/test
-     * (rejecting a malformed op at ingestion, with its path, instead of letting
-     * it crash later inside `applyOps`) without paying a Zod parse on every user
-     * action in production. The real validation boundary is `parseUndoEntry`,
-     * applied when entries are deserialized from persistence (untrusted input).
-     * Best practice: validate at trust boundaries, type-check internal calls.
+     * Record one entry onto the undo stack. Clears the redo stack. Fed by
+     * {@link flushBatch}/{@link endGroup} from the local-mutation stream, and
+     * still called directly by the legacy manual-record consumers
+     * (`useMutators`, the AI mutation pipeline) until they migrate. Entries are
+     * built internally (trusted), so the schema check is DEV-ONLY: it catches
+     * recorder bugs in dev/test (rejecting a malformed op at ingestion, with its
+     * path, instead of letting it crash later inside `applyOps`) without paying a
+     * Zod parse on every user action in production. The real validation boundary
+     * is `parseUndoEntry`, applied when entries are deserialized from persistence
+     * (untrusted input). Best practice: validate at trust boundaries, type-check
+     * internal calls.
      */
     record(entry) {
         if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
@@ -103,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
@@ -132,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;
     }
@@ -153,10 +330,27 @@ export class UndoScope {
                 return;
             const tx = createTransaction(this.schema, this.store, this.organizationId);
             const ops = resolveOps(entry.inverses, entry.forwards, this.store, this.conflictPolicy);
-            await applyOps(tx, ops);
+            // Suppress our own stream listener so replayed writes don't record as
+            // new undo entries. Cleared in `finally` even if a replay op throws.
+            this.replaying = true;
+            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();
         });
     }
     /**
@@ -172,21 +366,96 @@ export class UndoScope {
                 return;
             const tx = createTransaction(this.schema, this.store, this.organizationId);
             const ops = resolveOps(entry.forwards, entry.inverses, this.store, this.conflictPolicy);
-            await applyOps(tx, ops);
+            this.replaying = true;
+            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. */
     clear() {
         this.undoStack = [];
         this.redoStack = [];
+        this.batch = [];
+        this.emitChange();
     }
     /** Introspection — for debug panels / e2e tests. */
     size() {
         return { undo: this.undoStack.length, redo: this.redoStack.length };
     }
+    /**
+     * Detach from the local-mutation stream and drop listeners. Scopes are
+     * cached for the store's lifetime by `UndoManager`, so this is mainly for
+     * tests and explicit teardown.
+     */
+    dispose() {
+        this.unsubscribe();
+        this.recordListeners.clear();
+        this.changeListeners.clear();
+        this.batch = [];
+    }
+}
+/**
+ * Derive the forward + inverse op for a single local mutation. Returns null
+ * when the mutation can't be reversed (e.g. an update with no captured
+ * previous values), so the caller can drop it rather than push a half-entry.
+ */
+function buildUndoOps(m, modelKey) {
+    const id = m.modelId;
+    const stripId = (o) => {
+        const out = { ...(o ?? {}) };
+        delete out.id;
+        return out;
+    };
+    switch (m.type) {
+        case 'create':
+            return {
+                forward: { kind: 'create', modelKey, data: { ...stripId(m.data), id } },
+                inverse: { kind: 'delete', modelKey, id },
+            };
+        case 'update': {
+            const next = stripId(m.data);
+            const prev = stripId(m.previousData);
+            return {
+                forward: { kind: 'update', modelKey, patch: { id, ...next } },
+                // No previous values captured → not reversible; drop the inverse.
+                inverse: Object.keys(prev).length > 0
+                    ? { kind: 'update', modelKey, patch: { id, ...prev } }
+                    : null,
+            };
+        }
+        case 'delete':
+            return {
+                forward: { kind: 'delete', modelKey, id },
+                inverse: { kind: 'create', modelKey, data: { ...stripId(m.previousData), id } },
+            };
+        case 'archive':
+            return {
+                forward: { kind: 'update', modelKey, patch: { id, archivedAt: new Date() } },
+                inverse: { kind: 'update', modelKey, patch: { id, archivedAt: null } },
+            };
+        case 'unarchive':
+            return {
+                forward: { kind: 'update', modelKey, patch: { id, archivedAt: null } },
+                inverse: { kind: 'update', modelKey, patch: { id, archivedAt: new Date() } },
+            };
+        default:
+            return null;
+    }
 }
 // ── Manager ────────────────────────────────────────────────────────────────
 /**

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/context.d.ts

@@ -5,11 +5,42 @@ import type { QueryView, QueryViewOptions } from '../core/QueryView.js';
 import type { ViewRegistry } from '../core/ViewRegistry.js';
 import type { Schema } from '../schema/schema.js';
 import type { SyncStatus } from '../BaseSyncedStore.js';
+/**
+ * A single LOCAL mutation as observed off the commit stream — the substrate
+ * the undo system records from. One is emitted per local create/update/
+ * delete/archive (remote/collaborator deltas never appear here: they apply
+ * through a separate pool path that doesn't queue mutations). `previousData`
+ * holds the pre-edit field values (captured from the model's
+ * `modifiedProperties` first-old-wins baseline), so an inverse op is fully
+ * derivable from the event alone — no separate snapshot pass.
+ *
+ * This mirrors how Yjs's `UndoManager` derives reverse-ops by observing the
+ * doc and Liveblocks' `room.history` records room ops: undo listens to the
+ * one place all local writes converge, rather than wrapping the write call.
+ */
+export interface LocalMutation {
+    type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+    /** Registered model name (e.g. `'SlideLayer'`); resolved to a schema key by the recorder. */
+    modelName: string;
+    modelId: string;
+    /** New field values (create/update). */
+    data?: Record<string, unknown> | null;
+    /** Pre-edit field values (update → inverse patch; delete → full re-create row). */
+    previousData?: Record<string, unknown> | null;
+}
 /**
  * Minimal store interface that the SDK hooks need.
  * Consumers provide their concrete store (e.g., SyncedStore) that implements this.
  */
 export interface SyncStoreContract {
+    /**
+     * Subscribe to the LOCAL mutation stream (optimistic, pre-ack) for undo
+     * recording. Optional so minimal test doubles can omit it — when absent,
+     * undo scopes simply record nothing. The concrete store
+     * (`BaseSyncedStore`) wires this to the TransactionQueue's
+     * `transaction:created` event. Returns an unsubscribe function.
+     */
+    subscribeLocalMutations?(handler: (mutation: LocalMutation) => void): () => void;
     retrieve(modelClass: abstract new (...args: never[]) => Model, id: string): Model | undefined;
     queryByClass(modelClass: abstract new (...args: never[]) => Model, options?: {
         predicate?: (model: Model) => boolean;

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,