@abloatai/ablo 0.35.0 → 0.37.0

package/dist/react/useErrorListener.js

@@ -1,38 +0,0 @@
-'use client';
-import { useContext, useEffect, useRef } from 'react';
-import { AbloInternalContext } from './internalContext.js';
-import { AbloValidationError } from '../transaction/errors.js';
-/**
- * Registers a callback that runs whenever the provider surfaces an error. This
- * covers engine errors such as bootstrap failures and mutation rejections,
- * WebSocket errors, and uncaught exceptions thrown inside `postBootstrap`
- * hooks.
- *
- * Use it for side effects that should not cause a re-render — telemetry,
- * logging, or a toast. The callback is held in a ref, so a re-render does not
- * resubscribe.
- *
- * @example
- * function ErrorToaster() {
- *   useErrorListener((err) => {
- *     toast.error(err.message);
- *     Sentry.captureException(err);
- *   });
- *   return null;
- * }
- */
-export function useErrorListener(listener) {
-    const ctx = useContext(AbloInternalContext);
-    if (!ctx) {
-        throw new AbloValidationError('useErrorListener: no <AbloProvider> mounted above this component. ' +
-            'Wrap your tree with <AbloProvider ...> from @abloatai/ablo/react.', { code: 'no_ablo_provider' });
-    }
-    // Hold the latest callback in a ref so the subscription stays stable across
-    // renders. Late-binding the listener this way lets callers pass an inline
-    // arrow without resubscribing on every render.
-    const ref = useRef(listener);
-    ref.current = listener;
-    useEffect(() => {
-        return ctx.subscribeError((err) => { ref.current(err); });
-    }, [ctx]);
-}

package/dist/react/useMutationFailureListener.d.ts

@@ -1,26 +0,0 @@
-import type { QueuedMutation } from '../transactions/mutations/MutationQueue.js';
-export interface MutationFailurePayload {
-    transaction: QueuedMutation;
-    error: Error;
-    permanent?: boolean;
-}
-/**
- * Subscribes a listener to mutation failures. The callback fires whenever the
- * transaction queue rolls back an optimistic write — both permanent rejections
- * (a validation, foreign-key, or authorization error) and rollbacks after the
- * retries are exhausted (for example, the connection drops mid-write).
- *
- * A single listener mounted near the top of your component tree can turn these
- * otherwise-silent rollbacks into toasts or banners. The callback is held in a
- * ref, so re-renders do not tear down and re-create the underlying
- * subscription.
- *
- * @example
- * function MutationFailureBoundary() {
- *   useMutationFailureListener(({ transaction, error }) => {
- *     toast.error(`Couldn't save ${transaction.modelName}: ${error.message}`);
- *   });
- *   return null;
- * }
- */
-export declare function useMutationFailureListener(listener: (payload: MutationFailurePayload) => void): void;

package/dist/react/useMutationFailureListener.js

@@ -1,38 +0,0 @@
-'use client';
-import { useContext, useEffect, useRef } from 'react';
-import { AbloInternalContext } from './internalContext.js';
-import { AbloValidationError } from '../transaction/errors.js';
-/**
- * Subscribes a listener to mutation failures. The callback fires whenever the
- * transaction queue rolls back an optimistic write — both permanent rejections
- * (a validation, foreign-key, or authorization error) and rollbacks after the
- * retries are exhausted (for example, the connection drops mid-write).
- *
- * A single listener mounted near the top of your component tree can turn these
- * otherwise-silent rollbacks into toasts or banners. The callback is held in a
- * ref, so re-renders do not tear down and re-create the underlying
- * subscription.
- *
- * @example
- * function MutationFailureBoundary() {
- *   useMutationFailureListener(({ transaction, error }) => {
- *     toast.error(`Couldn't save ${transaction.modelName}: ${error.message}`);
- *   });
- *   return null;
- * }
- */
-export function useMutationFailureListener(listener) {
-    const ctx = useContext(AbloInternalContext);
-    if (!ctx) {
-        throw new AbloValidationError('useMutationFailureListener: no <AbloProvider> mounted above this component. ' +
-            'Wrap your tree with <AbloProvider ...> from @abloatai/ablo/react.', { code: 'no_ablo_provider' });
-    }
-    const ref = useRef(listener);
-    ref.current = listener;
-    useEffect(() => {
-        const engine = ctx.engine;
-        if (!engine)
-            return;
-        return engine.onMutationFailure((payload) => { ref.current(payload); });
-    }, [ctx, ctx.engine]);
-}

package/dist/react/useMutators.d.ts

@@ -1,56 +0,0 @@
-import type { Schema } from '../transaction/schema/schema.js';
-import type { MutatorDefs } from '../mutators/defineMutators.js';
-import type { UndoScope } from '../mutators/UndoManager.js';
-import type { ResolveSchema } from '../transaction/types/global.js';
-/**
- * Turns a mutator tree built with `defineMutators` into callable invokers. The
- * returned object mirrors that tree one-to-one, but each leaf becomes an
- * `(args) => Promise<TResult>` function.
- *
- * Each invocation builds a fresh `Transaction` bound to the current store and
- * organization, calls your mutator with `{ tx, args }`, and returns whatever
- * the mutator resolves to.
- *
- * If a mutator throws, the error propagates to the caller and any writes it
- * already dispatched stay in place — there is no automatic rollback. Wrap the
- * call in your own try/catch and issue compensating writes when you need to
- * undo a partial change, or pass an `undoScope` (see {@link UseMutatorsOptions})
- * to record inverses for undo and redo.
- */
-/**
- * Map a `MutatorFn` onto its invoker form — strip `tx`, keep `args`/return.
- *
- * Uses nested `infer O` so the `args`/`result` types are extracted from the
- * function signature without binding the `tx` parameter to a specific
- * `Transaction<S>` variance. Function parameters are contravariant, so a
- * match against `MutatorFn<Schema>` would reject mutators declared against
- * a narrower schema (e.g. `Transaction<typeof appSchema>`). The two-step
- * inference sidesteps that without resorting to `any`/`unknown` placeholders.
- */
-export type InvokerFor<F> = F extends (options: infer O) => Promise<infer R> ? O extends {
-    args: infer A;
-} ? (args: A) => Promise<R> : never : never;
-/**
- * The hook's return shape: same tree as the input `MutatorDefs`, every leaf
- * rewritten to its invoker form.
- */
-export type MutatorInvokers<M> = {
-    [K in keyof M]: {
-        [N in keyof M[K]]: InvokerFor<M[K][N]>;
-    };
-};
-/**
- * Options passed to `useMutators`. When `undoScope` is set, every mutator
- * invocation is wrapped in a `RecordingMutation` and its inverses are
- * pushed to the scope as one undo entry.
- */
-export interface UseMutatorsOptions<S extends Schema> {
-    /** Target undo scope for recording inverses. Omit to disable recording. */
-    undoScope?: UndoScope<S>;
-}
-/** Mutator invokers (explicit schema arg). */
-export declare function useMutators<S extends Schema, M extends MutatorDefs<S>>(schema: S, mutators: M, options?: UseMutatorsOptions<S>): MutatorInvokers<M>;
-/** Mutator invokers via the `Register` module augmentation. Schema comes
- * from the `SyncProvider`'s context; the mutator tree is typed against
- * `ResolveSchema` at the call site. */
-export declare function useMutators<M extends ResolveSchema extends Schema ? MutatorDefs<ResolveSchema> : MutatorDefs<Schema>>(mutators: M, options?: UseMutatorsOptions<ResolveSchema extends Schema ? ResolveSchema : Schema>): MutatorInvokers<M>;

package/dist/react/useMutators.js

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

package/dist/react/useReactive.d.ts

@@ -1,35 +0,0 @@
-/**
- * Subscribe a component to a reactive computation and re-render when
- * the result changes. Concurrent-render safe, referentially stable
- * across renders when the value is unchanged.
- *
- * Thin wrapper over React's `useSyncExternalStore` + MobX `reaction`
- * that hides the three-arg ceremony and the "cached snapshot" rule
- * those primitives impose. Consumers write domain code:
- *
- *   const count = useReactive(() => store.tasks.length);
- *   const todos = useReactive(() => store.tasks.findMany({ status: 'todo' }));
- *   const title = useReactive(() => store.user.name ?? 'Guest');
- *
- * and get values that track MobX observables transparently. No
- * subscribe callbacks, no getSnapshot identity contract, no React
- * concurrent-mode mechanics to reason about.
- *
- * ## Equality
- *
- * The default `equals` is structural for arrays (length + element
- * identity) and `Object.is` for everything else — matches what 99%
- * of UI code expects from a reactive read. Pass a custom `equals`
- * for bespoke shapes (deep objects, tuples, etc.).
- *
- * ## Why not raw useSyncExternalStore?
- *
- * `useSyncExternalStore` is React's low-level primitive for library
- * authors. It leaks concurrent-mode internals (tearing protection,
- * commit-phase subscription) into consumer code and enforces a
- * "getSnapshot must return a cached reference" contract that's easy
- * to violate — violating it causes React error #185 (infinite render
- * loop). This helper lives once and enforces the contract so every
- * caller writes the domain-level code, not the primitive.
- */
-export declare function useReactive<T>(compute: () => T, equals?: (a: T, b: T) => boolean): T;

package/dist/react/useReactive.js

@@ -1,123 +0,0 @@
-'use client';
-import { useCallback, useRef } from 'react';
-import { useSyncExternalStore } from 'react';
-import { reaction } from 'mobx';
-/**
- * Subscribe a component to a reactive computation and re-render when
- * the result changes. Concurrent-render safe, referentially stable
- * across renders when the value is unchanged.
- *
- * Thin wrapper over React's `useSyncExternalStore` + MobX `reaction`
- * that hides the three-arg ceremony and the "cached snapshot" rule
- * those primitives impose. Consumers write domain code:
- *
- *   const count = useReactive(() => store.tasks.length);
- *   const todos = useReactive(() => store.tasks.findMany({ status: 'todo' }));
- *   const title = useReactive(() => store.user.name ?? 'Guest');
- *
- * and get values that track MobX observables transparently. No
- * subscribe callbacks, no getSnapshot identity contract, no React
- * concurrent-mode mechanics to reason about.
- *
- * ## Equality
- *
- * The default `equals` is structural for arrays (length + element
- * identity) and `Object.is` for everything else — matches what 99%
- * of UI code expects from a reactive read. Pass a custom `equals`
- * for bespoke shapes (deep objects, tuples, etc.).
- *
- * ## Why not raw useSyncExternalStore?
- *
- * `useSyncExternalStore` is React's low-level primitive for library
- * authors. It leaks concurrent-mode internals (tearing protection,
- * commit-phase subscription) into consumer code and enforces a
- * "getSnapshot must return a cached reference" contract that's easy
- * to violate — violating it causes React error #185 (infinite render
- * loop). This helper lives once and enforces the contract so every
- * caller writes the domain-level code, not the primitive.
- */
-export function useReactive(compute, equals = defaultEquals) {
-    // Late-binding refs so the subscribe callback stays stable across
-    // re-renders — otherwise React would re-subscribe every render,
-    // which both churns the MobX reaction and leaks listeners.
-    const computeRef = useRef(compute);
-    const equalsRef = useRef(equals);
-    equalsRef.current = equals;
-    // Cached snapshot — referentially stable between reaction fires.
-    const snapshotRef = useRef(null);
-    // When `compute` identity changes, its closed-over observable source
-    // may have swapped (e.g. useQuery memoized a new QueryView because
-    // the where clause changed). The MobX reaction subscribed in
-    // `subscribe` only tracks the observables read on its first run; if
-    // the source swaps without a re-subscription, the reaction never
-    // re-tracks the new observables and `getSnapshot` keeps returning
-    // the stale value forever.
-    //
-    // Detect the swap by reference and:
-    //   1. Recompute the snapshot synchronously so the next render returns
-    //      the fresh value rather than the previous source's last value.
-    //      Reconcile through `equals` so unchanged values keep their
-    //      snapshot identity (avoids unnecessary re-renders downstream).
-    //   2. Bump `subscribeVersion`, which is the dependency for `subscribe`
-    //      below — useSyncExternalStore re-subscribes when subscribe's
-    //      identity changes, the new reaction tracker runs against the
-    //      latest `computeRef.current`, and dependencies for the new
-    //      source are correctly captured.
-    const subscribeVersionRef = useRef(0);
-    if (snapshotRef.current === null) {
-        snapshotRef.current = { value: compute() };
-    }
-    else if (computeRef.current !== compute) {
-        // `compute` is a fresh inline arrow at virtually every call site, so this
-        // branch runs on essentially every render. Reconcile the snapshot against
-        // the latest closure, but only force a re-subscription when the value
-        // actually changed. For the dominant case (same observable source, new
-        // arrow identity, unchanged value) this avoids tearing down + recreating
-        // the MobX reaction — and its double-compute — on every render. A genuine
-        // source swap (a memoized compute closing over a new observable source)
-        // changes the value, which both updates the snapshot and bumps
-        // `subscribeVersion` so the reaction below re-subscribes and re-tracks the
-        // new source's observables.
-        const next = compute();
-        if (!equals(snapshotRef.current.value, next)) {
-            snapshotRef.current = { value: next };
-            subscribeVersionRef.current++;
-        }
-    }
-    // Point the long-lived reaction at the latest closure every render. The
-    // reaction expression reads `computeRef.current` at fire time, so it always
-    // runs the newest compute (and re-tracks its observables) even when we did
-    // not re-subscribe above.
-    computeRef.current = compute;
-    const subscribeVersion = subscribeVersionRef.current;
-    const subscribe = useCallback((onChange) => {
-        return reaction(() => computeRef.current(), (next) => {
-            const current = snapshotRef.current.value;
-            if (!equalsRef.current(current, next)) {
-                snapshotRef.current = { value: next };
-                onChange();
-            }
-        });
-    }, [subscribeVersion]);
-    const getSnapshot = useCallback(() => snapshotRef.current.value, []);
-    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-}
-/**
- * Default equality: structural for arrays, `Object.is` otherwise.
- * Covers the common cases (collection reads, scalar reads) without
- * requiring callers to think about reference identity.
- */
-function defaultEquals(a, b) {
-    if (Object.is(a, b))
-        return true;
-    if (Array.isArray(a) && Array.isArray(b)) {
-        if (a.length !== b.length)
-            return false;
-        for (let i = 0; i < a.length; i++) {
-            if (!Object.is(a[i], b[i]))
-                return false;
-        }
-        return true;
-    }
-    return false;
-}

package/dist/react/useSyncStatus.d.ts

@@ -1,59 +0,0 @@
-/**
- * A snapshot of the current sync status, modeled as a discriminated union so
- * impossible states — such as "connected and offline" at once — cannot be
- * represented. Each variant carries only the fields that make sense in that
- * state, so a single `switch` on `name` narrows to exactly what you can read.
- *
- * Variants:
- * - `initial` — the provider just mounted; no connection attempt yet.
- * - `connecting` — bootstrap in progress. `progress` is 0–100 and
- *    can drive a determinate progress bar.
- * - `connected` — hydrated and listening. `hasUnsyncedChanges` is
- *    true while local writes are waiting for server ack; flip it into
- *    "Saving…" UI.
- * - `reconnecting` — WebSocket dropped and the client is retrying.
- *    `reason` carries the human-readable close reason when available.
- * - `disconnected` — network failure, server error, or the retry loop
- *    gave up. Show the offline / error UI.
- * - `needs-auth` — server rejected the auth token (1008/4001/4003). The
- *    consumer's `onSessionExpired` callback has already been invoked
- *    by `<AbloProvider>`; this variant exists for UI that wants to
- *    reflect the auth state itself.
- */
-export type SyncStatusSnapshot = {
-    readonly name: 'initial';
-} | {
-    readonly name: 'connecting';
-    readonly progress: number;
-} | {
-    readonly name: 'connected';
-    readonly hasUnsyncedChanges: boolean;
-} | {
-    readonly name: 'reconnecting';
-    readonly reason?: string;
-} | {
-    readonly name: 'disconnected';
-    readonly reason?: string;
-} | {
-    readonly name: 'needs-auth';
-};
-/**
- * Reactive sync-status hook. Bridges MobX `store.syncStatus` +
- * `store.isReady` into React via `useReactive` — concurrent-render
- * safe and immune to the React #185 "getSnapshot should be cached"
- * infinite-loop class of bugs.
- *
- * @example
- * function StatusPill() {
- *   const status = useSyncStatus();
- *   switch (status.name) {
- *     case 'initial':
- *     case 'connecting':     return <Pill progress={status.name === 'connecting' ? status.progress : 0}>Loading…</Pill>;
- *     case 'connected':      return status.hasUnsyncedChanges ? <Pill>Saving…</Pill> : null;
- *     case 'reconnecting':   return <Pill title={status.reason}>Reconnecting…</Pill>;
- *     case 'disconnected':   return <Pill title={status.reason}>Offline</Pill>;
- *     case 'needs-auth':     return null;
- *   }
- * }
- */
-export declare function useSyncStatus(): SyncStatusSnapshot;

package/dist/react/useSyncStatus.js

@@ -1,76 +0,0 @@
-'use client';
-import { useCallback } from 'react';
-import { useSyncContext } from './context.js';
-import { useReactive } from './useReactive.js';
-/**
- * Reactive sync-status hook. Bridges MobX `store.syncStatus` +
- * `store.isReady` into React via `useReactive` — concurrent-render
- * safe and immune to the React #185 "getSnapshot should be cached"
- * infinite-loop class of bugs.
- *
- * @example
- * function StatusPill() {
- *   const status = useSyncStatus();
- *   switch (status.name) {
- *     case 'initial':
- *     case 'connecting':     return <Pill progress={status.name === 'connecting' ? status.progress : 0}>Loading…</Pill>;
- *     case 'connected':      return status.hasUnsyncedChanges ? <Pill>Saving…</Pill> : null;
- *     case 'reconnecting':   return <Pill title={status.reason}>Reconnecting…</Pill>;
- *     case 'disconnected':   return <Pill title={status.reason}>Offline</Pill>;
- *     case 'needs-auth':     return null;
- *   }
- * }
- */
-export function useSyncStatus() {
-    const { store } = useSyncContext();
-    // `useReactive` tracks the MobX observables read inside deriveStatus
-    // (syncStatus.state/progress/pendingChanges/isSessionError/error +
-    // the computed isReady), caches the result by shape, and only
-    // notifies React when a variant transition actually occurs.
-    //
-    // Stabilize the closure on `store` identity so useReactive's
-    // swap-detection doesn't see a "swap" every render and unnecessarily
-    // re-subscribe its MobX reaction.
-    const compute = useCallback(() => deriveStatus(store), [store]);
-    return useReactive(compute, sameSnapshot);
-}
-/** Map the current store state into the discriminated union. */
-function deriveStatus(store) {
-    const { state, progress, pendingChanges, isSessionError, error } = store.syncStatus;
-    if (isSessionError) {
-        return { name: 'needs-auth' };
-    }
-    if (state === 'reconnecting') {
-        return { name: 'reconnecting', reason: error?.message };
-    }
-    if (state === 'offline') {
-        return { name: 'disconnected', reason: 'offline' };
-    }
-    if (state === 'error') {
-        return { name: 'disconnected', reason: error?.message };
-    }
-    if (store.isReady) {
-        return { name: 'connected', hasUnsyncedChanges: pendingChanges > 0 };
-    }
-    // state is 'idle' or 'syncing' and not yet ready — bootstrap underway.
-    if (state === 'idle' || state === 'syncing') {
-        return { name: 'connecting', progress };
-    }
-    return { name: 'initial' };
-}
-function sameSnapshot(a, b) {
-    if (a.name !== b.name)
-        return false;
-    switch (a.name) {
-        case 'initial':
-        case 'needs-auth':
-            return true;
-        case 'connecting':
-            return a.progress === b.progress;
-        case 'connected':
-            return a.hasUnsyncedChanges === b.hasUnsyncedChanges;
-        case 'reconnecting':
-        case 'disconnected':
-            return a.reason === b.reason;
-    }
-}

package/dist/react/useUndoScope.d.ts

@@ -1,34 +0,0 @@
-import type { Schema } from '../transaction/schema/schema.js';
-import type { UndoScope, UndoScopeOptions } from '../mutators/UndoManager.js';
-import type { ResolveSchema } from '../transaction/types/global.js';
-/**
- * Provides per-surface undo and redo for mutator invocations. Each named scope
- * owns an independent undo/redo stack, so different parts of your app — a main
- * editor, a sidebar form — can undo separately without stepping on each other.
- *
- * Wire the returned `scope` into `useMutators(schema, mutators, { undoScope:
- * scope })` and those invocations become recorded. `undo()` and `redo()` replay
- * the captured inverses and forwards as new transactions that do not record
- * themselves; the manager moves the entry between the two stacks explicitly.
- *
- * @example
- * const { undo, redo, canUndo, canRedo, scope } = useUndoScope('report-editor');
- * const mutate = useMutators(schema, reportMutators, { undoScope: scope });
- *
- * // Cmd+Z handler
- * useHotkey('mod+z', () => { if (canUndo) void undo(); });
- */
-export interface UseUndoScopeResult<S extends Schema> {
-    /** Pass to `useMutators(..., { undoScope })` to enable recording. */
-    scope: UndoScope<S>;
-    undo: () => Promise<void>;
-    redo: () => Promise<void>;
-    canUndo: boolean;
-    canRedo: boolean;
-    /** Drop history. Use after sync errors / auth context changes. */
-    clear: () => void;
-}
-/** Per-surface undo/redo (explicit schema arg). */
-export declare function useUndoScope<S extends Schema>(schema: S, name: string, options?: UndoScopeOptions): UseUndoScopeResult<S>;
-/** Per-surface undo/redo via the `Register` module augmentation. */
-export declare function useUndoScope(name: string, options?: UndoScopeOptions): UseUndoScopeResult<ResolveSchema extends Schema ? ResolveSchema : Schema>;

package/dist/react/useUndoScope.js

@@ -1,81 +0,0 @@
-'use client';
-import { useEffect, useMemo, useState } from 'react';
-import { UndoManager } from '../mutators/UndoManager.js';
-import { useSyncContext } from './context.js';
-import { AbloValidationError } from '../transaction/errors.js';
-// Module-level weak registry: `SyncStoreContract` → `UndoManager`.
-// A single app wiring through one SyncProvider shares one manager across
-// every useUndoScope call, so scopes with the same name are identity-equal.
-// Storage erases the generic — `UndoManager<S>` is invariant in S, so
-// the WeakMap can't hold the precise type alongside the typed factory
-// signature. We re-assert at retrieval; the contract is "scope keys
-// are unique per-app and the schema is the same across every call
-// for that key."
-const managers = new WeakMap();
-function getManager(key, factory) {
-    let m = managers.get(key);
-    if (!m) {
-        // Generic-erasure boundary at storage. Concentrating the cast
-        // here so the retrieval path doesn't have to repeat it.
-        const created = factory();
-        managers.set(key, created);
-        m = created;
-    }
-    // Single typed cast at retrieval — `as UndoManager<S>` would be
-    // rejected (TS sees `UndoManager<Schema>` and `UndoManager<S>` as
-    // unrelated), but we're at the runtime/static schema-identity
-    // boundary the contract above pins.
-    return m;
-}
-export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
-    const { store, organizationId, schema: ctxSchema } = useSyncContext();
-    const isExplicit = typeof schemaOrName !== 'string';
-    const schema = isExplicit ? (schemaOrName) : ctxSchema;
-    const name = isExplicit ? nameOrOptions : schemaOrName;
-    const options = (isExplicit ? maybeOptions : nameOrOptions);
-    if (!schema) {
-        throw new AbloValidationError('useUndoScope: no schema available. Pass the schema as the first arg, ' +
-            'or build the <AbloProvider> above with `Ablo({ schema })` so the ' +
-            'zero-arg overload can read it from context.', { code: 'undo_scope_schema_missing' });
-    }
-    const scope = useMemo(() => {
-        // Store is the identity for the manager — one per SyncProvider.
-        const manager = getManager(store, () => new UndoManager(schema, store, organizationId));
-        return manager.getScope(name, options);
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [store, organizationId, name]);
-    // Local tick forces re-render after undo/redo/clear so canUndo/canRedo
-    // reflect the new stack sizes. The scope itself doesn't emit React-
-    // friendly notifications; callers that want cross-component reactivity
-    // can wire a mobx observable or custom event bus on top.
-    const [, setTick] = useState(0);
-    // Reset tick when scope identity changes (new store / new orgId).
-    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,
-        undo: async () => {
-            await scope.undo();
-            setTick((t) => t + 1);
-        },
-        redo: async () => {
-            await scope.redo();
-            setTick((t) => t + 1);
-        },
-        canUndo: size.undo > 0,
-        canRedo: size.redo > 0,
-        clear: () => {
-            scope.clear();
-            setTick((t) => t + 1);
-        },
-    };
-}