@abloatai/ablo 0.7.0 → 0.9.0

package/dist/react/AbloProvider.js

@@ -1,7 +1,6 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { useContext, useEffect, useMemo, useRef, useState, } from 'react';
-import { Ablo } from '../client/Ablo.js';
 import { createParticipantClaimId, parseParticipantTtlSeconds, resolveParticipantSyncGroups, } from '../sync/participants.js';
 import { SyncContext } from './context.js';
 import { AbloInternalContext } from './internalContext.js';
@@ -32,75 +31,52 @@ function createErrorEmitter() {
     };
 }
 export function AbloProvider(props) {
-    const { schema, url = 'wss://mesh.ablo.finance', userId, teamIds, apiKey, preventUnsavedChanges, onSessionExpired, onError, observability, logger, mutationExecutor, mutationDispatcher, sessionErrorDetector, onlineStatus, configOverrides, syncGroups, scope, bootstrapBaseUrl, maxPoolSize, persistence, bootstrapMode, fallback = _jsx(DefaultFallback, {}), children, } = props;
-    // Account scope is no longer accepted from props. The engine learns
-    // it from auth (capability token) at bootstrap and we read it back
-    // out of `_store.orgId` once `engine.ready()` resolves.
+    const { client, userId, preventUnsavedChanges, onSessionExpired, onError, fallback = _jsx(DefaultFallback, {}), children, } = props;
+    // The client IS the engine — synchronous, never null. This provider is a
+    // REACTIVE binding over it (context + bootstrap gate + error/session
+    // forwarding); it does NOT construct, configure, or own the connection. The
+    // client owns auth, the credential lifecycle (first mint, refresh, and
+    // wake/online/focus re-mint — see `Ablo({ getToken })`), transport, and
+    // `dispose()`. The CONSUMER built the client, so the consumer owns teardown;
+    // the provider never disposes it.
+    const engine = client;
+    const schema = engine.schema;
+    // Account scope isn't a prop — read it from `_store.orgId` once `ready()`
+    // resolves the identity from the client's auth.
     const [resolvedAccountScope, setResolvedAccountScope] = useState(null);
     // ── Error emitter (provider-instance scoped) ─────────────────────
-    //
-    // Built once, reused for the lifetime of this provider. Survives
-    // engine rotations so error listeners don't need to resubscribe.
     const errorEmitterRef = useRef(null);
     if (!errorEmitterRef.current) {
         errorEmitterRef.current = createErrorEmitter();
     }
     const errorEmitter = errorEmitterRef.current;
-    // Stash `onError` in a ref so forwarding it doesn't trigger
-    // engine rotation. The provider wraps it and calls via ref at fire
-    // time, matching the `useEventCallback` idiom.
+    // Stash callbacks in refs so a new identity each render doesn't re-run the
+    // start effect (the `useEventCallback` idiom).
     const onErrorRef = useRef(onError);
     onErrorRef.current = onError;
     useEffect(() => {
         return errorEmitter.subscribe((err) => onErrorRef.current?.(err));
     }, [errorEmitter]);
-    // ── Engine lifecycle keyed on (userId, url) ─────────────────────
+    const onSessionExpiredRef = useRef(onSessionExpired);
+    onSessionExpiredRef.current = onSessionExpired;
+    // Re-key the bootstrap gate when the client INSTANCE changes — a genuinely new
+    // engine is a fresh "first bootstrap". Stable for the common single-client app.
+    const clientGenRef = useRef({ client, gen: 0 });
+    if (clientGenRef.current.client !== client) {
+        clientGenRef.current = { client, gen: clientGenRef.current.gen + 1 };
+    }
+    const engineKey = String(clientGenRef.current.gen);
+    // ── Start + session-error wiring ─────────────────────────────────
     //
-    // The engine rotates when either of these change. For everything
-    // else (mutators, DI, callbacks) we stash in refs so mutations to
-    // those props don't tear down the engine.
-    const engineKey = JSON.stringify({
-        userId: userId ?? null,
-        url,
-        bootstrapMode: bootstrapMode ?? null,
-    });
-    const [engineState, setEngineState] = useState({ key: engineKey, engine: null });
-    // Keep a ref to the current engine key so the rotation effect can
-    // detect late-arriving prop changes without causing React churn.
-    const currentKeyRef = useRef(engineState.key);
-    currentKeyRef.current = engineState.key;
+    // Two reactive jobs only:
+    //   1. Forward a SERVER session-rejection → purge (wipe IndexedDB so the next
+    //      login starts clean) → onSessionExpired (the app redirects). The
+    //      offline/transient-vs-terminal credential logic lives in the CLIENT now.
+    //   2. Drive `ready()` (idempotent) so bootstrap starts on mount, then read the
+    //      resolved org scope for SyncContext.
+    // It does NOT dispose the client (consumer-owned) and does NOT touch auth.
     useEffect(() => {
-        const abort = new AbortController();
-        let isStale = false;
-        setResolvedAccountScope(null);
-        // Construct engine + multiplayer streams for this key.
-        const engineOptions = {
-            baseURL: url,
-            schema,
-            ...(userId ? { user: { id: userId, teamIds } } : {}),
-            apiKey,
-            logger,
-            observability,
-            sessionErrorDetector,
-            onlineStatus,
-            mutationExecutor,
-            mutationDispatcher,
-            configOverrides,
-            // Union raw strings with model-form `scope` resolved through the schema,
-            // so `scope={{ decks: id }}` becomes `deck:<id>` via the model's `scope`.
-            syncGroups: scope
-                ? [...(syncGroups ?? []), ...resolveParticipantSyncGroups(scope, schema)]
-                : syncGroups,
-            bootstrapBaseUrl,
-            maxPoolSize,
-            persistence,
-            ...(bootstrapMode ? { bootstrapMode } : {}),
-            autoStart: false,
-        };
-        const engine = Ablo(engineOptions);
-        setEngineState({ key: engineKey, engine });
-        // Forward session-error events to the consumer. Purge first so
-        // the IndexedDB is wiped before the app redirects to /signin.
+        let stale = false;
         const unsubscribeSession = engine.onSessionError(async (err) => {
             errorEmitter.emit(err);
             try {
@@ -108,55 +84,37 @@ export function AbloProvider(props) {
             }
             catch { }
             try {
-                await onSessionExpired?.();
+                await onSessionExpiredRef.current?.();
             }
             catch (hookErr) {
                 errorEmitter.emit(hookErr);
             }
         });
-        // Drive initial bootstrap. Consumer code that wants to run logic
-        // after the engine is ready calls `useAblo()` and wires its own
-        // `useEffect` — the SDK no longer holds a registry of "post-
-        // bootstrap hooks" because the indirection costs more than it
-        // saves once `useAblo` exists.
-        (async () => {
-            try {
-                await engine.ready();
-                if (isStale || abort.signal.aborted)
-                    return;
-                setResolvedAccountScope(engine._store.orgId ?? null);
-            }
-            catch (err) {
-                if (isStale || abort.signal.aborted)
-                    return;
-                errorEmitter.emit(err);
-            }
-        })();
+        engine
+            .ready()
+            .then(() => {
+            if (stale)
+                return;
+            setResolvedAccountScope(engine._store.orgId ?? null);
+        })
+            .catch((err) => {
+            if (stale)
+                return;
+            errorEmitter.emit(err);
+        });
         return () => {
-            isStale = true;
-            abort.abort();
+            stale = true;
             unsubscribeSession();
-            void engine.dispose();
-            // AbloClient is stateless-ish — participants manage their own
-            // WebSocket connections via `participant.disconnect()`. No client
-            // close is needed.
         };
-        // We intentionally only re-run on engineKey. All other DI is
-        // captured at first render; rotating the engine on every
-        // `mutationExecutor` identity change would destroy the WebSocket.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [engineKey]);
+    }, [engine, errorEmitter]);
     // ── beforeunload + preventUnsavedChanges ─────────────────────────
     useEffect(() => {
         if (typeof window === 'undefined')
             return;
         const handler = (event) => {
-            const engine = engineState.engine;
-            if (!engine)
-                return;
-            // Best-effort: dispose on unload. The async work may not
-            // complete before the tab closes — that's fine for IDB, which
-            // flushes pending writes transactionally.
+            // Best-effort IDB flush on TAB CLOSE — the client is going away with the
+            // page regardless. This is NOT an unmount teardown: the consumer owns the
+            // client's lifecycle and the provider never disposes it on unmount.
             void engine.dispose();
             if (preventUnsavedChanges && engine._store.hasUnsyncedChanges) {
                 event.preventDefault();
@@ -165,30 +123,30 @@ export function AbloProvider(props) {
         };
         window.addEventListener('beforeunload', handler);
         return () => window.removeEventListener('beforeunload', handler);
-    }, [engineState.engine, preventUnsavedChanges]);
+    }, [engine, preventUnsavedChanges]);
     // ── SyncContext value (for useQuery/useOne/useMutate hooks) ──────
+    //
+    // The engine is always present (it's the `client` prop), but its org scope is
+    // unknown until `ready()` resolves identity — so `syncValue` is null until
+    // then, which drives the initial fallback below.
     const syncValue = useMemo(() => {
-        if (!engineState.engine)
-            return null;
         const currentAccountScope = resolvedAccountScope ??
-            engineState.engine._store.orgId;
+            engine._store.orgId;
         if (!currentAccountScope)
             return null;
         return {
-            store: engineState.engine._store,
+            store: engine._store,
             organizationId: currentAccountScope,
             schema,
         };
-    }, [engineState.engine, resolvedAccountScope, schema]);
+    }, [engine, resolvedAccountScope, schema]);
     // ── Internal context (currentUserId + error subscription) ────────
     const internalValue = useMemo(() => ({
         currentUserId: userId ?? null,
         subscribeError: errorEmitter.subscribe,
         emitError: errorEmitter.emit,
-        // `engine` is null until bootstrap finishes; `useSync()` throws
-        // on null so callers are forced to gate with <ClientSideSuspense>.
-        engine: engineState.engine,
-    }), [userId, errorEmitter, engineState.engine]);
+        engine: engine,
+    }), [userId, errorEmitter, engine]);
     // ── Render ───────────────────────────────────────────────────────
     //
     // Two-phase gate (see `BootstrapGate` below for the latch logic):
@@ -212,7 +170,7 @@ export function AbloProvider(props) {
     if (!syncValue) {
         return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: initialFallback }));
     }
-    return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: _jsx(SyncContext.Provider, { value: syncValue, children: passthrough ? (children) : (_jsx(BootstrapGate, { fallback: fallback, children: children }, engineState.key)) }) }));
+    return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: _jsx(SyncContext.Provider, { value: syncValue, children: passthrough ? (children) : (_jsx(BootstrapGate, { fallback: fallback, children: children }, engineKey)) }) }));
 }
 /**
  * Internal gate that renders `fallback` only during the very first

package/dist/react/ClientSideSuspense.d.ts

@@ -33,4 +33,4 @@ export interface ClientSideSuspenseProps {
     /** What to render once the subtree is cleared to render. */
     children: ReactNode;
 }
-export declare function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps): import("react").JSX.Element;

package/dist/react/DefaultFallback.d.ts

@@ -21,4 +21,4 @@
  * pass `fallback={null}`. Consumers who want to skip the gate entirely
  * pass `fallback="passthrough"`.
  */
-export declare function DefaultFallback(): import("react/jsx-runtime").JSX.Element;
+export declare function DefaultFallback(): import("react").JSX.Element;

package/dist/react/SyncGroupProvider.d.ts

@@ -4,7 +4,7 @@ export interface SyncGroupProviderProps {
     id: string;
     children: ReactNode;
 }
-export declare function SyncGroupProvider({ id, children }: SyncGroupProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function SyncGroupProvider({ id, children }: SyncGroupProviderProps): import("react").JSX.Element;
 /**
  * Returns the ID of the nearest `<SyncGroupProvider>`. Throws if
  * called outside one — sync-group awareness is mandatory by design,

package/dist/react/index.d.ts

@@ -13,9 +13,10 @@
  *     immediately. The provider-level `fallback` is the default path.
  *
  * Data hooks:
- *   useAblo((ablo) => ablo.tasks.retrieve(id)) — primary React read API
+ *   useAblo((ablo) => ablo.tasks.get(id))     — primary React read API (sync local snapshot)
  *   useAblo()                                  — typed client for callbacks/effects
- *                                                (reads: ablo.<model>.retrieve/list;
+ *                                                (sync local reads: ablo.<model>.get/getAll;
+ *                                                 async server reads: ablo.<model>.retrieve/list;
  *                                                 writes: ablo.<model>.create/update/delete)
  *   useMutators(defs, opts?)                   — Zero-style custom mutators
  *   useUndoScope(name)                         — per-surface undo/redo

package/dist/react/index.js

@@ -13,9 +13,10 @@
  *     immediately. The provider-level `fallback` is the default path.
  *
  * Data hooks:
- *   useAblo((ablo) => ablo.tasks.retrieve(id)) — primary React read API
+ *   useAblo((ablo) => ablo.tasks.get(id))     — primary React read API (sync local snapshot)
  *   useAblo()                                  — typed client for callbacks/effects
- *                                                (reads: ablo.<model>.retrieve/list;
+ *                                                (sync local reads: ablo.<model>.get/getAll;
+ *                                                 async server reads: ablo.<model>.retrieve/list;
  *                                                 writes: ablo.<model>.create/update/delete)
  *   useMutators(defs, opts?)                   — Zero-style custom mutators
  *   useUndoScope(name)                         — per-surface undo/redo

package/dist/react/useAblo.d.ts

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

package/dist/react/useAblo.js

@@ -9,7 +9,7 @@ function readModelResult(engine, modelClient, id, initial) {
     if (!modelClient || id === undefined) {
         return { data: initial, claims: EMPTY_CLAIMS, claimed: false };
     }
-    const data = snapshotValue(modelClient.retrieve(id) ?? initial);
+    const data = snapshotValue(modelClient.get(id) ?? initial);
     const meta = getModelClientMeta(modelClient);
     const claims = meta && engine
         ? engine.intents.list({ model: meta.key, id })
@@ -29,7 +29,6 @@ export function useAblo(modelOrSelect, id, options) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
     const initial = options?.initial;
-    const hasSelection = modelOrSelect !== undefined;
     const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
     const modelClient = typeof modelOrSelect === 'function' && id !== undefined
         ? engine
@@ -38,14 +37,20 @@ export function useAblo(modelOrSelect, id, options) {
         : typeof modelOrSelect === 'function'
             ? undefined
             : modelOrSelect;
+    // Claims live on a non-MobX event emitter (engine.intents), so the useReactive
+    // reactions below cannot track them — we bridge changes through a setState bump.
+    // ONLY the model-row form (`id !== undefined`) actually reads claims, so gate the
+    // subscription on `id`. The selector-only form (`useAblo((a) => a.x.get/getAll)`)
+    // never reads claims; subscribing it to the workspace-global intent stream would
+    // re-render + double-compute it on every intent/presence delta anywhere (a real
+    // storm during AI editing / live collaboration) for a value that can't change.
     const [claimVersion, setClaimVersion] = useState(0);
     useEffect(() => {
-        if (!engine || !hasSelection)
+        if (!engine || id === undefined)
             return;
         return engine.intents.onChange(() => setClaimVersion((version) => version + 1));
-    }, [engine, hasSelection]);
+    }, [engine, id]);
     const selected = useReactive(() => {
-        void claimVersion;
         if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {
             return undefined;
         }

package/dist/react/useCurrentUserId.d.ts

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

package/dist/react/useCurrentUserId.js

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

package/dist/react/useMutators.js

@@ -34,19 +34,26 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
                 invokers[mutatorName] = async (args) => {
                     // Recording path: wrap the transaction so each write snapshots its
                     // inverse. On success, push the captured entry to the scope.
+                    //
+                    // The whole snapshot → write → record sequence runs on the scope's
+                    // serialization chain so concurrent invocations (the slides UI fires
+                    // writes un-awaited) record in *invocation* order and never
+                    // interleave their shared-model snapshots. See UndoScope.runRecorded.
                     if (undoScope) {
-                        const recording = createRecordingTransaction(schema, store, organizationId);
-                        try {
-                            const result = await fn({ tx: recording.tx, args });
-                            const entry = recording.getEntry(label);
-                            if (entry)
-                                undoScope.record(entry);
-                            return result;
-                        }
-                        catch (err) {
-                            getContext().logger.error(`[useMutators] mutator "${label}" threw`, { error: err });
-                            throw err;
-                        }
+                        return undoScope.runRecorded(async () => {
+                            const recording = createRecordingTransaction(schema, store, organizationId);
+                            try {
+                                const result = await fn({ tx: recording.tx, args });
+                                const entry = recording.getEntry(label);
+                                if (entry)
+                                    undoScope.record(entry);
+                                return result;
+                            }
+                            catch (err) {
+                                getContext().logger.error(`[useMutators] mutator "${label}" threw`, { error: err });
+                                throw err;
+                            }
+                        });
                     }
                     // Non-recording path — plain transaction, identical to pre-undo V1.
                     const tx = createTransaction(schema, store, organizationId);

package/dist/react/useReactive.js

@@ -66,16 +66,29 @@ export function useReactive(compute, equals = defaultEquals) {
     const subscribeVersionRef = useRef(0);
     if (snapshotRef.current === null) {
         snapshotRef.current = { value: compute() };
-        computeRef.current = 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++;
         }
-        computeRef.current = compute;
-        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) => {

package/dist/schema/ddl.d.ts

@@ -22,14 +22,34 @@ import type { MigrationStep, BackfillValue } from './diff.js';
 export interface ProvisionPlan {
     /** The Postgres schema the tables live in (`app_<id>` or `public`). */
     readonly appSchema: string;
-    /** Ordered, idempotent DDL statements. Safe to run repeatedly. */
+    /** Ordered, idempotent DDL statements. Safe to run repeatedly. Executors run
+     *  these together in ONE transaction. */
     readonly statements: readonly string[];
+    /** Post-commit, NON-transactional DDL (`VALIDATE CONSTRAINT`, `CREATE INDEX
+     *  CONCURRENTLY`) — run AFTER {@link statements} commit, each outside any
+     *  transaction, best-effort. Keeps the lock-heavy / scan-heavy work off the
+     *  main transaction so adding a foreign key never freezes a large, live BYO
+     *  table. Optional + back-compat: absent = nothing to run. */
+    readonly concurrent?: readonly string[];
+}
+export interface ProvisionOptions {
+    /**
+     * Emit `DEFERRABLE INITIALLY DEFERRED` FOREIGN KEY constraints for every
+     * `parent: true` belongsTo relation (true ownership edges only — see
+     * {@link foreignKeyStatements}). Off by default: the soft-reference model keeps
+     * out-of-order sync robust on Ablo-managed tables. Turn on for a customer's own
+     * (BYO / dedicated) database, where a clean, navigable relational schema is
+     * wanted and the DB starts empty (nothing for the constraint to fail against).
+     */
+    readonly foreignKeys?: boolean;
 }
 export interface MigrationPlan {
     /** The app Postgres schema the DDL targets (`app_<id>` or `public`). */
     readonly appSchema: string;
-    /** Ordered DDL statements (expand → contract). */
+    /** Ordered DDL statements (expand → contract). Run in ONE transaction. */
     readonly statements: readonly string[];
+    /** Post-commit, non-transactional DDL — see {@link ProvisionPlan.concurrent}. */
+    readonly concurrent?: readonly string[];
 }
 /** Per-app schema name for an app (organization) id. */
 export declare function appSchemaName(organizationId: string): string;
@@ -46,7 +66,7 @@ export declare function sqlType(fieldType: ModelJSON['fields'][string]['type']):
  * itself is the isolation boundary). For `public` the `CREATE SCHEMA` is
  * skipped (it always exists).
  */
-export declare function generateProvisionPlan(schema: SchemaJSON, targetSchema: string): ProvisionPlan;
+export declare function generateProvisionPlan(schema: SchemaJSON, targetSchema: string, opts?: ProvisionOptions): ProvisionPlan;
 /**
  * Lower an ordered migration step list to DDL. `next` is the schema being pushed
  * (the target column shapes are read from it), `prev` the active one (used to
@@ -59,4 +79,7 @@ export declare function generateMigrationPlan(steps: readonly MigrationStep[], o
     /** Constant seed values that let a required-field add / made-required step
      *  set NOT NULL on a non-empty table. Keyed by (model, field). */
     readonly backfills?: readonly BackfillValue[];
+    /** Emit DEFERRABLE FK constraints for `parent: true` edges of newly-created
+     *  models. Off by default — see {@link ProvisionOptions.foreignKeys}. */
+    readonly foreignKeys?: boolean;
 }): MigrationPlan;