@abloatai/humans 0.37.0

package/dist/react/AbloProvider.js

@@ -0,0 +1,456 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useContext, useEffect, useMemo, useRef, useState, createContext, } from 'react';
+import { createParticipantClaimId, parseParticipantTtlSeconds, resolveParticipantSyncGroups, } from '../local/sync/participants.js';
+import { SyncContext } from './context.js';
+import { AbloInternalContext } from './internalContext.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+import { useSyncStatus } from './useSyncStatus.js';
+import { DefaultFallback } from './DefaultFallback.js';
+// ── Implementation ───────────────────────────────────────────────────
+/**
+ * Lightweight event emitter for provider-level errors. Lives on the
+ * provider instance (ref-based) so `useErrorListener` subscriptions
+ * survive re-renders without thrashing.
+ */
+function createErrorEmitter() {
+    const listeners = new Set();
+    return {
+        subscribe(fn) {
+            listeners.add(fn);
+            return () => { listeners.delete(fn); };
+        },
+        emit(err) {
+            for (const fn of listeners) {
+                try {
+                    fn(err);
+                }
+                catch { }
+            }
+        },
+    };
+}
+export function AbloProvider(props) {
+    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({ apiKey })`), 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) ─────────────────────
+    const errorEmitterRef = useRef(null);
+    if (!errorEmitterRef.current) {
+        errorEmitterRef.current = createErrorEmitter();
+    }
+    const errorEmitter = errorEmitterRef.current;
+    // 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]);
+    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 ─────────────────────────────────
+    //
+    // Two reactive jobs only:
+    //   1. Forward the client's completed terminal-session transition to
+    //      onSessionExpired. Credential cleanup lives in the CLIENT, so direct
+    //      consumers and React consumers have the same security boundary.
+    //   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(() => {
+        let stale = false;
+        const unsubscribeSession = engine.onSessionError((err) => {
+            errorEmitter.emit(err);
+            void (async () => {
+                try {
+                    await onSessionExpiredRef.current?.();
+                }
+                catch (hookErr) {
+                    errorEmitter.emit(hookErr);
+                }
+            })().catch(() => {
+                // Only a throwing errorEmitter subscriber can land here — it was
+                // already the error-reporting path, so swallow rather than surface
+                // an unhandled rejection loop.
+            });
+        });
+        engine
+            .ready()
+            .then(() => {
+            if (stale)
+                return;
+            setResolvedAccountScope(engine._store.orgId ?? null);
+        })
+            .catch((err) => {
+            if (stale)
+                return;
+            errorEmitter.emit(err);
+        });
+        return () => {
+            stale = true;
+            unsubscribeSession();
+        };
+    }, [engine, errorEmitter]);
+    // ── beforeunload + preventUnsavedChanges ─────────────────────────
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const handler = (event) => {
+            // 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();
+                event.returnValue = '';
+            }
+        };
+        window.addEventListener('beforeunload', handler);
+        return () => { window.removeEventListener('beforeunload', handler); };
+    }, [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(() => {
+        const currentAccountScope = resolvedAccountScope ??
+            engine._store.orgId;
+        if (!currentAccountScope)
+            return null;
+        return {
+            store: engine._store,
+            organizationId: currentAccountScope,
+            schema,
+        };
+    }, [engine, resolvedAccountScope, schema]);
+    // ── Internal context (currentUserId + error subscription) ────────
+    const internalValue = useMemo(() => ({
+        currentUserId: userId ?? null,
+        subscribeError: errorEmitter.subscribe,
+        emitError: errorEmitter.emit,
+        engine: engine,
+    }), [userId, errorEmitter, engine]);
+    // ── Render ───────────────────────────────────────────────────────
+    //
+    // Two-phase gate (see `BootstrapGate` below for the latch logic):
+    //
+    //   1. Engine is null on first render (constructed in the effect
+    //      above, not in render). We render `fallback` directly — there
+    //      is no SyncContext to read status from, and by definition the
+    //      engine hasn't started bootstrapping.
+    //   2. Engine exists. Mount SyncContext. `BootstrapGate` then reads
+    //      `useSyncStatus()` and shows `fallback` only during the very
+    //      first `connecting` transition; children render on every
+    //      subsequent state change, including reconnects and auth
+    //      failures (the app's own UI handles those).
+    //
+    // `fallback === 'passthrough'` short-circuits both branches — children
+    // render immediately without any gate, restoring pre-gate behavior
+    // for consumers who need debug helpers / error boundaries / analytics
+    // to mount before the engine is ready.
+    const passthrough = fallback === 'passthrough';
+    const initialFallback = passthrough ? children : fallback;
+    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 }, engineKey)) }) }));
+}
+/**
+ * Internal gate that renders `fallback` only during the very first
+ * bootstrap pass. Latches open on the first `connected` / `reconnecting`
+ * / `disconnected` transition and stays open — subsequent transient
+ * `connecting` states (hard reconnect after an offline stretch) do NOT
+ * re-show the fallback, because by then the app has already rendered
+ * once and its own reconnect UI should take over.
+ *
+ * Re-keyed on `engineState.key` in the parent so engine rotations
+ * (userId/org/url change) reset the latch — a new engine genuinely IS
+ * a new "first bootstrap" cycle.
+ */
+function BootstrapGate({ fallback, children, }) {
+    const status = useSyncStatus();
+    const [everConnected, setEverConnected] = useState(false);
+    useEffect(() => {
+        if (status.name === 'connected' ||
+            status.name === 'reconnecting' ||
+            status.name === 'disconnected') {
+            setEverConnected(true);
+        }
+    }, [status.name]);
+    const showFallback = !everConnected && status.name === 'connecting';
+    return _jsx(_Fragment, { children: showFallback ? fallback : children });
+}
+const EMPTY_PRESENCE = Object.freeze([]);
+const EMPTY_INTENTS = Object.freeze([]);
+/**
+ * Join multiplayer for a given scope. Returns the participant and its
+ * lifecycle status. Auto-cleans up on unmount or when `paused`
+ * flips to true.
+ *
+ * `useJoin` is the React form of `ablo.<model>.join` — scope-level
+ * read-interest + presence; returns the reactive participant facade
+ * (peers/claims/status).
+ *
+ * The returned `participant` is an `EngineParticipant` — `.presence`
+ * + `.claims` only — backed by the engine's existing socket. For
+ * headless-bot patterns (a separate identity in the same browser
+ * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
+ */
+export function useJoin(opts) {
+    const ctx = useContext(AbloInternalContext);
+    const engine = ctx?.engine ?? null;
+    const { paused = false } = opts;
+    // Resolve the model-form scope ({ reports: id } / refs) THROUGH the schema, so a
+    // model's declared `scope` kind is honored (typename `Report` → `report:<id>`,
+    // not the `type:id` string fallback). Schema appears once the engine is ready;
+    // until then refs resolve by convention, then re-resolve when it arrives.
+    const scopeKey = JSON.stringify(resolveParticipantSyncGroups(opts.scope, engine?.schema).sort());
+    const scopedSyncGroups = useMemo(() => JSON.parse(scopeKey), [scopeKey]);
+    const [claimError, setClaimError] = useState(null);
+    const [claimConnected, setClaimConnected] = useState(false);
+    // Reference-stable participant facade — same socket as entity sync,
+    // so there is no `connect()` / `disconnect()` lifecycle here. The
+    // engine manages the connection; the hook is a thin window onto its
+    // already-attached presence + claim streams.
+    const participant = useMemo(() => {
+        if (!engine)
+            return null;
+        return { presence: engine.presence, claims: engine.claims };
+    }, [engine]);
+    // Status maps to the engine's sync state. `connecting` while the
+    // engine bootstraps; `connected` once `engine.ready()` resolves and
+    // any scoped participant claim has acked; `error` if the claim
+    // fails; `disconnected` while paused or before the engine exists.
+    const syncStatus = useSyncStatus();
+    // Only a write-claim participant waits on a claim ack. A pure reader
+    // (the default) is `connected` as soon as the engine is — its read
+    // interest is fire-and-forget `update_subscription`, not a claim.
+    const needsClaim = !!opts.claim && scopedSyncGroups.length > 0;
+    const status = paused || !engine
+        ? 'disconnected'
+        : claimError
+            ? 'error'
+            : syncStatus.name === 'connected'
+                ? needsClaim && !claimConnected
+                    ? 'connecting'
+                    : 'connected'
+                : syncStatus.name === 'disconnected' || syncStatus.name === 'needs-auth'
+                    ? 'disconnected'
+                    : 'connecting';
+    const error = claimError;
+    // ── Read interest (always) ───────────────────────────────────────
+    // Subscribe the connection to the scope's sync groups while mounted +
+    // connected — the area-of-interest navigation primitive. No claim, no
+    // TTL: a viewer just receives the scope's deltas. Hysteresis (warm TTL)
+    // lives in the store's SubscriptionManager, so a quick unmount/remount
+    // (tab flip) doesn't re-bootstrap.
+    useEffect(() => {
+        const scope = opts.scope;
+        if (paused || !engine || !scope || scopedSyncGroups.length === 0)
+            return;
+        if (syncStatus.name !== 'connected')
+            return;
+        const store = engine._store;
+        // `hydrate` backfills the scope's current state after subscribing
+        // (store handles subscribe-first ordering + single-flight). leaveScope
+        // only moves read interest; the hydrated rows stay in the pool.
+        void store.enterScope?.(scope, { hydrate: opts.hydrate });
+        return () => {
+            void store.leaveScope?.(scope);
+        };
+        // scopeKey is the stable proxy for the resolved groups; same idiom as
+        // the claim effect below.
+    }, [engine, paused, scopeKey, syncStatus.name, opts.hydrate]);
+    // ── Write claim (opt-in: `claim: true`) ─────────────────────────
+    // A claim is the write-claim primitive — distinct from read interest
+    // above. Only sent when the caller opts in; it makes peers observe the
+    // claim and pins the scope so it never warms while held.
+    useEffect(() => {
+        setClaimError(null);
+        setClaimConnected(false);
+        const scope = opts.scope;
+        if (paused || !engine || !opts.claim || !scope || scopedSyncGroups.length === 0)
+            return;
+        if (syncStatus.name !== 'connected')
+            return;
+        const ws = engine._ws;
+        const store = engine._store;
+        let cancelled = false;
+        const claimId = createParticipantClaimId();
+        ws.sendClaim(claimId, scopedSyncGroups, {
+            // Reading the retired spelling IS the compatibility path; it goes at 0.37.0.
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            ttlSeconds: parseParticipantTtlSeconds(opts.ttl ?? opts.ttlSeconds),
+        })
+            .then(() => {
+            if (!cancelled)
+                setClaimConnected(true);
+        })
+            .catch((err) => {
+            if (!cancelled) {
+                setClaimError(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        // Prominence: hold the scope subscribed for as long as the claim lives.
+        void store.pinScope?.(scope);
+        return () => {
+            cancelled = true;
+            ws.sendRelease(claimId);
+            void store.unpinScope?.(scope);
+        };
+        // eslint-disable-next-line @typescript-eslint/no-deprecated -- same compatibility read as above.
+    }, [engine, paused, scopeKey, syncStatus.name, opts.ttl, opts.ttlSeconds, opts.claim]);
+    // Bridge the engine's presence + claims streams into React state.
+    // Plain useState + useEffect is sufficient — mid-frame tearing on a
+    // peer list is harmless (users won't notice one frame of stale
+    // presence). Queries and sync status use useSyncExternalStore
+    // because transactions CAN tear visibly; presence can't.
+    const [peers, setPeers] = useState(EMPTY_PRESENCE);
+    const [claims, setClaims] = useState(EMPTY_INTENTS);
+    useEffect(() => {
+        if (!participant || paused) {
+            setPeers(EMPTY_PRESENCE);
+            setClaims(EMPTY_INTENTS);
+            return;
+        }
+        setPeers(participant.presence.others);
+        setClaims(participant.claims.others);
+        const unsubPresence = participant.presence.onChange(() => {
+            setPeers(participant.presence.others);
+        });
+        const unsubClaims = participant.claims.onChange(() => {
+            setClaims(participant.claims.others);
+        });
+        return () => {
+            unsubPresence();
+            unsubClaims();
+        };
+    }, [participant, paused]);
+    return { participant, peers, claims, status, error };
+}
+/**
+ * Read-only presence: the OTHER participants currently visible to this
+ * connection, bridged to React. Unlike {@link useJoin}, this does
+ * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
+ * it is a pure reader of the engine's already-flowing presence stream.
+ *
+ * Pass `scope` to narrow to the peers on that scope's sync group(s); omit
+ * it to get everyone on the engine's groups. Membership is driven entirely
+ * by the presence channel (set server-side on connect, independent of any
+ * cursor/collaboration traffic), so reading it never affects what the
+ * connection is subscribed to and can't deadlock against a gated channel.
+ *
+ * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
+ * broadcasts while alone — when some OTHER mount already owns the scope's
+ * read interest (scope `leave` is not reference-counted, so a second
+ * `useJoin` on the same scope would warm-drop the owner's
+ * subscription on unmount).
+ *
+ * ```ts
+ * const peers = usePeers({ reports: reportId });
+ * const alone = !peers.some((p) => p.participantKind === 'user');
+ * ```
+ */
+export function usePeers(scope) {
+    const ctx = useContext(AbloInternalContext);
+    const engine = ctx?.engine ?? null;
+    // Resolve scope → groups through the schema (same idiom as useJoin).
+    // The stringified, sorted key is the stable effect dependency.
+    const scopeKey = JSON.stringify(resolveParticipantSyncGroups(scope, engine?.schema).sort());
+    const groups = useMemo(() => JSON.parse(scopeKey), [scopeKey]);
+    const [peers, setPeers] = useState(EMPTY_PRESENCE);
+    useEffect(() => {
+        if (!engine) {
+            setPeers(EMPTY_PRESENCE);
+            return;
+        }
+        const presence = engine.presence;
+        const compute = () => groups.length === 0
+            ? presence.others
+            : presence.others.filter((p) => p.syncGroups.some((g) => groups.includes(g)));
+        // Plain useState + onChange — presence changes on join/leave/activity
+        // only (never on cursor traffic, a separate channel), so this fires
+        // rarely; a frame of stale presence is harmless (same rationale as
+        // useJoin's peers bridge).
+        setPeers(compute());
+        return presence.onChange(() => { setPeers(compute()); });
+    }, [engine, scopeKey]);
+    return peers;
+}
+// ── Escape-hatches: raw engine/store access ──────────────────────────
+/**
+ * Returns the raw `SyncEngine` proxy. Typically you want the typed
+ * hooks (`useQuery`, `useOne`, `useMutate`) — this is for rare cases
+ * where you need direct access (e.g., `sync.tasks.onChange(cb)`).
+ *
+ * The generic parameter narrows the return type to your schema's
+ * model record so call sites get typed `sync.tasks.findMany()` /
+ * `sync.sections.create(...)` without a cast at the call site:
+ *
+ * ```ts
+ * const sync = useSync<(typeof schema)['models']>();
+ * ```
+ *
+ * The runtime value is the exact engine the provider constructed;
+ * the generic just widens the compile-time type.
+ */
+export function useSync() {
+    const ctx = useContext(AbloInternalContext);
+    if (!ctx) {
+        throw new AbloValidationError('useSync: no <AbloProvider> mounted above this component.', { code: 'no_ablo_provider' });
+    }
+    if (!ctx.engine) {
+        throw new AbloValidationError('useSync: the sync engine has not yet initialized. Wrap your ' +
+            'consumer in <ClientSideSuspense> or guard on useSyncStatus().', { code: 'sync_not_ready' });
+    }
+    return rebindProviderEngine(ctx.engine);
+}
+function rebindProviderEngine(engine) {
+    return engine;
+}
+/**
+ * Returns the underlying `SyncStoreContract` (the BaseSyncedStore).
+ * Most consumers should prefer the typed hooks (`useQuery` etc.); this
+ * is for advanced cases like direct InstanceCache access or custom
+ * reactive bridges. Throws if the provider hasn't mounted the store
+ * yet — wrap consumers in `<ClientSideSuspense>` to gate correctly.
+ *
+ * The generic parameter lets consumers widen the return type to a
+ * concrete `BaseSyncedStore<...>` subclass if they track one:
+ *
+ * ```ts
+ * type AppStore = BaseSyncedStore<AppEvents, typeof schema>;
+ * const store = useSyncStore<AppStore>();  // no cast needed at call site
+ * ```
+ *
+ * The runtime value is always the concrete store the SDK constructed,
+ * so widening the type is safe. The bounded generic (`T extends
+ * SyncStoreContract`) keeps the widening honest.
+ */
+export function useSyncStore() {
+    const sync = useContext(SyncContext);
+    if (!sync?.store) {
+        throw new AbloValidationError('useSyncStore: the sync engine has not yet initialized. Wrap ' +
+            'consumers in <ClientSideSuspense> or guard on useSyncStatus().', { code: 'sync_not_ready' });
+    }
+    return sync.store;
+}

package/dist/react/ClientSideSuspense.d.ts

@@ -0,0 +1,36 @@
+import { type ReactNode } from 'react';
+/**
+ * Nested bootstrap gate for a subtree. `<AbloProvider>` already ships
+ * its own built-in gate (via its `fallback` prop) that handles the
+ * common "wait for first bootstrap" case. Use `ClientSideSuspense`
+ * only when you need a SEPARATE gate inside an already-ready provider —
+ * for example, rendering app chrome immediately while gating a single
+ * heavy product surface on its own query resolving.
+ *
+ * Like the provider-level gate, this component latches open on the
+ * first `connected` / `reconnecting` / `disconnected` transition and
+ * stays open. Subsequent transient `connecting` states (hard reconnect
+ * after offline) do NOT re-show the fallback — the app has already
+ * rendered once and its own reconnect UI should take over.
+ *
+ * v0.3.x implementation is non-Suspense: reads `useSyncStatus()` and
+ * conditionally renders. v0.3.x+ will ship a
+ * the React suspense entry point where `useQuery` / `useOne`
+ * actually throw Promises; this component becomes a thin wrapper around
+ * React's real `<Suspense>` at that point.
+ *
+ * @example
+ * <AbloProvider fallback={<AppSkeleton />}>
+ *   <AppChrome />
+ *   <ClientSideSuspense fallback={<CanvasSkeleton />}>
+ *     <HeavyCanvas />
+ *   </ClientSideSuspense>
+ * </AbloProvider>
+ */
+export interface ClientSideSuspenseProps {
+    /** What to render while the nested subtree is waiting for first bootstrap. */
+    fallback: ReactNode;
+    /** What to render once the subtree is cleared to render. */
+    children: ReactNode;
+}
+export declare function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps): import("react").JSX.Element;

package/dist/react/ClientSideSuspense.js

@@ -0,0 +1,17 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { useSyncStatus } from './useSyncStatus.js';
+export function ClientSideSuspense({ fallback, children }) {
+    const status = useSyncStatus();
+    const [everConnected, setEverConnected] = useState(false);
+    useEffect(() => {
+        if (status.name === 'connected' ||
+            status.name === 'reconnecting' ||
+            status.name === 'disconnected') {
+            setEverConnected(true);
+        }
+    }, [status.name]);
+    const showFallback = !everConnected && status.name === 'connecting';
+    return _jsx(_Fragment, { children: showFallback ? fallback : children });
+}

package/dist/react/DefaultFallback.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Neutral loading placeholder — the default value of `<AbloProvider>`'s
+ * `fallback` prop. Rendered during the first bootstrap pass when the
+ * consumer hasn't supplied their own skeleton.
+ *
+ * Design goals:
+ *   - Zero design-system dependency. Inline styles only; no CSS file,
+ *     no UI-lib imports, no Tailwind assumptions.
+ *   - Theme-adaptive. Uses `currentColor` for the ring so the spinner
+ *     inherits the text color from whichever ancestor defines it —
+ *     works in light + dark contexts without a prop.
+ *   - Self-centering. Flex-centered in a full-parent container so the
+ *     common case (provider at the layout root) renders a spinner in
+ *     the middle of the viewport. Consumers who need different
+ *     positioning compose their own fallback and pass it explicitly.
+ *   - Minimal bundle footprint. The whole component + keyframe is ~50
+ *     bytes gzipped.
+ *
+ * Consumers wanting a branded loader should pass `fallback={<YourSkeleton />}`
+ * on `<AbloProvider>`. Consumers wanting NO visual during bootstrap
+ * pass `fallback={null}`. Consumers who want to skip the gate entirely
+ * pass `fallback="passthrough"`.
+ */
+export declare function DefaultFallback(): import("react").JSX.Element;

package/dist/react/DefaultFallback.js

@@ -0,0 +1,43 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Neutral loading placeholder — the default value of `<AbloProvider>`'s
+ * `fallback` prop. Rendered during the first bootstrap pass when the
+ * consumer hasn't supplied their own skeleton.
+ *
+ * Design goals:
+ *   - Zero design-system dependency. Inline styles only; no CSS file,
+ *     no UI-lib imports, no Tailwind assumptions.
+ *   - Theme-adaptive. Uses `currentColor` for the ring so the spinner
+ *     inherits the text color from whichever ancestor defines it —
+ *     works in light + dark contexts without a prop.
+ *   - Self-centering. Flex-centered in a full-parent container so the
+ *     common case (provider at the layout root) renders a spinner in
+ *     the middle of the viewport. Consumers who need different
+ *     positioning compose their own fallback and pass it explicitly.
+ *   - Minimal bundle footprint. The whole component + keyframe is ~50
+ *     bytes gzipped.
+ *
+ * Consumers wanting a branded loader should pass `fallback={<YourSkeleton />}`
+ * on `<AbloProvider>`. Consumers wanting NO visual during bootstrap
+ * pass `fallback={null}`. Consumers who want to skip the gate entirely
+ * pass `fallback="passthrough"`.
+ */
+export function DefaultFallback() {
+    return (_jsxs("div", { role: "status", "aria-live": "polite", "aria-label": "Loading", style: {
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            width: '100%',
+            minHeight: '100vh',
+            color: 'currentColor',
+        }, children: [_jsx("div", { style: {
+                    width: 24,
+                    height: 24,
+                    border: '2px solid currentColor',
+                    borderTopColor: 'transparent',
+                    borderRadius: '50%',
+                    opacity: 0.6,
+                    animation: 'ablo-default-fallback-spin 0.8s linear infinite',
+                } }), _jsx("style", { children: `@keyframes ablo-default-fallback-spin { to { transform: rotate(360deg); } }` })] }));
+}

package/dist/react/context.d.ts

@@ -0,0 +1,55 @@
+import { type ReactNode } from 'react';
+import type { Schema } from '@abloatai/transaction/schema/schema';
+import type { SyncStoreContract } from '../local/storeContract.js';
+export type { SyncStoreContract, LocalMutation, } from '../local/storeContract.js';
+export interface SyncReactContext {
+    store: SyncStoreContract;
+    /** The organization id used as the default scope for reads and writes. */
+    organizationId: string;
+    /**
+     * An optional schema. When provided, hooks that take a model by name (such as
+     * `useQuery('tasks')`) read that model's metadata from this schema, so
+     * callers don't pass a schema at every call site. When omitted, those hooks
+     * require the schema as an argument instead.
+     *
+     * The field is loosely typed here because a single runtime context value is
+     * shared by every hook. Precise per-model types come from your `Register`
+     * module augmentation
+     * (`declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`),
+     * not from this reference.
+     */
+    schema?: Schema;
+}
+export declare const SyncContext: import("react").Context<SyncReactContext | null>;
+/**
+ * Reads the sync store context from inside a provider subtree, throwing a clear
+ * error when no provider is mounted above. `<AbloProvider>` supplies this
+ * context by rendering the internal {@link SyncProvider}; you wire
+ * `<AbloProvider client={ablo}>` rather than touching this directly.
+ */
+export declare function useSyncContext(): SyncReactContext;
+/**
+ * Props for SyncProvider.
+ */
+export interface SyncProviderProps {
+    /** The sync store, which must implement {@link SyncStoreContract}. */
+    store: SyncStoreContract;
+    /** The organization id used as the default scope for reads and writes. */
+    organizationId: string;
+    /**
+     * An optional schema. Provide it to enable hooks that take a model by name
+     * (such as `useQuery('tasks')`); the model types also narrow through your
+     * `Register` augmentation. Omit it to pass the schema to those hooks directly
+     * instead.
+     */
+    schema?: Schema;
+    children?: ReactNode;
+}
+/**
+ * A low-level provider that places a built sync store on React context so the
+ * data hooks can reach it. This is an internal building block: it is not part
+ * of the package's public entry point. Reach for `<AbloProvider>` instead,
+ * which builds the store from your `Ablo({ schema, apiKey })` client and
+ * renders this provider underneath.
+ */
+export declare function SyncProvider({ store, organizationId, schema, children, }: SyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SyncReactContext | null>>;

package/dist/react/context.js

@@ -0,0 +1,29 @@
+'use client';
+import { createContext, createElement, useContext } from 'react';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+export const SyncContext = createContext(null);
+/**
+ * Reads the sync store context from inside a provider subtree, throwing a clear
+ * error when no provider is mounted above. `<AbloProvider>` supplies this
+ * context by rendering the internal {@link SyncProvider}; you wire
+ * `<AbloProvider client={ablo}>` rather than touching this directly.
+ */
+export function useSyncContext() {
+    const ctx = useContext(SyncContext);
+    if (!ctx) {
+        throw new AbloValidationError('Sync hooks must be used within an <AbloProvider>.', {
+            code: 'sync_context_missing_provider',
+        });
+    }
+    return ctx;
+}
+/**
+ * A low-level provider that places a built sync store on React context so the
+ * data hooks can reach it. This is an internal building block: it is not part
+ * of the package's public entry point. Reach for `<AbloProvider>` instead,
+ * which builds the store from your `Ablo({ schema, apiKey })` client and
+ * renders this provider underneath.
+ */
+export function SyncProvider({ store, organizationId, schema, children, }) {
+    return createElement(SyncContext.Provider, { value: { store, organizationId, schema } }, children);
+}