@abloatai/ablo 0.3.0

package/dist/react/useQuery.d.ts

@@ -0,0 +1,123 @@
+import type { ModelScope } from '../types/index.js';
+import type { Schema } from '../schema/schema.js';
+import type { InferModel } from '../schema/schema.js';
+import type { ResolveSchema } from '../types/global.js';
+/** Narrow model-key union for the zero-arg overload. */
+type GlobalModelKey = ResolveSchema extends {
+    models: infer M;
+} ? keyof M & string : string;
+/** Typed entity shape for a given model key. Falls back to a loose shape
+ * when the resolved schema doesn't extend the full `Schema` contract
+ * (i.e., no global augmentation present). */
+type GlobalEntity<K extends string> = ResolveSchema extends Schema ? K extends keyof ResolveSchema['models'] ? InferModel<ResolveSchema, K> : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Compatibility query hook for entity collections.
+ *
+ * Prefer selector reads for new integrations:
+ *
+ * ```ts
+ * const tasks = useAblo((ablo) =>
+ *   ablo.tasks.list({ where: { status: 'todo' } }),
+ * );
+ * ```
+ *
+ * This hook remains for older string-keyed integrations.
+ *
+ * **Typed overload:**
+ * ```ts
+ * import { schema } from '@/sync/schema';
+ * const chats = useQuery(schema, 'chats', { where: { userId } });
+ * // chats is fully typed: Chat[] with displayTitle, icon, color, etc.
+ * ```
+ *
+ * **Untyped overload (legacy):**
+ * ```ts
+ * const chats = useQuery('Chat');
+ * // chats is Record<string, unknown>[]
+ * ```
+ */
+export interface QueryOptions<T = Record<string, unknown>> {
+    /** Declarative field-level filter. Shallow match: all specified fields must match. */
+    where?: Partial<T>;
+    /** Arbitrary predicate function for complex logic. Applied AFTER where. */
+    filter?: (entity: T) => boolean;
+    /** Sort field name. */
+    orderBy?: keyof T & string;
+    /** Sort direction. Default: 'asc'. */
+    order?: 'asc' | 'desc';
+    /** Max results. */
+    limit?: number;
+    /** Skip N results (pagination). */
+    offset?: number;
+    /** Filter by model scope (live, archived, all). Default: live. */
+    scope?: ModelScope;
+}
+/**
+ * Typed query (explicit schema arg).
+ *
+ * @deprecated Prefer `useAblo((ablo) => ablo.<model>.list(options))` for new
+ * integrations. This overload remains for compatibility with older
+ * string-keyed React code.
+ *
+ * ```ts
+ * const tasks = useQuery(schema, 'tasks', { where: { status: 'todo' } });
+ * // tasks: Task[] — fully typed from Zod shape + computed getters
+ * ```
+ */
+export declare function useQuery<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K, options?: QueryOptions<InferModel<S, K>>): InferModel<S, K>[];
+/**
+ * Typed query (global-augmented): pass just the model key. Resolves
+ * the schema from the `AbloSync` global augmentation the consumer
+ * declared in a `.d.ts`. No `schema` arg at the call site — this is
+ * the Liveblocks-style ergonomic path.
+ *
+ * @deprecated Prefer `useAblo((ablo) => ablo.<model>.list(options))` for new
+ * integrations. This overload remains for compatibility with older
+ * string-keyed React code.
+ *
+ * ```ts
+ * // apps/your-app/src/ablo-sync.d.ts
+ * declare global { interface AbloSync { Schema: typeof schema } }
+ *
+ * // any component
+ * const tasks = useQuery('tasks', { where: { status: 'todo' } });
+ * // tasks: Task[] — typed via the declared global
+ * ```
+ *
+ * When no global augmentation exists, `GlobalEntity` falls back to
+ * `Record<string, unknown>` — same ergonomics as the legacy untyped
+ * overload, with the key still validated against the resolved schema's
+ * model keys when that schema is declared.
+ */
+export declare function useQuery<K extends GlobalModelKey>(modelKey: K, options?: QueryOptions<GlobalEntity<K>>): GlobalEntity<K>[];
+/** @deprecated Prefer selector reads through `useAblo`. */
+export declare function useQuery<T = Record<string, unknown>>(typename: string, options?: QueryOptions<T>): T[];
+/**
+ * Compatibility single-entity lookup. Prefer selector reads:
+ *
+ * ```ts
+ * const task = useAblo((ablo) => ablo.tasks.retrieve(taskId));
+ * ```
+ *
+ * ```ts
+ * // Typed
+ * const task = useOne(schema, 'tasks', taskId);
+ *
+ * // Untyped (legacy)
+ * const task = useOne(taskId);
+ * ```
+ */
+/** @deprecated Prefer `useAblo((ablo) => ablo.<model>.retrieve(id))`. */
+export declare function useOne<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K, id?: string): InferModel<S, K> | undefined;
+/** Typed single-entity lookup via the `AbloSync` global augmentation.
+ *
+ * @deprecated Prefer `useAblo((ablo) => ablo.<model>.retrieve(id))`.
+ *
+ * The pool `.get(id)` call doesn't actually need the typename at runtime
+ * — the return is already keyed by id globally — so the model key serves
+ * as a compile-time narrowing hint for consumers who want the specific
+ * entity type at the call site. */
+export declare function useOne<K extends GlobalModelKey>(modelKey: K, id?: string): GlobalEntity<K> | undefined;
+/** @deprecated Prefer `useAblo((ablo) => ablo.<model>.retrieve(id))`. */
+export declare function useOne<T = Record<string, unknown>>(id?: string): T | undefined;
+export {};

package/dist/react/useQuery.js

@@ -0,0 +1,145 @@
+'use client';
+import { useMemo, useEffect, useRef, useCallback } from 'react';
+import { useSyncContext } from './context.js';
+import { useReactive } from './useReactive.js';
+// ── Stable key helper ───────────────────────────────────────────────
+/**
+ * Produce a stable string key for QueryOptions so useMemo only recreates
+ * the view when the logical query changes.
+ *
+ * - `where` is serialized via JSON.stringify (deterministic for simple values).
+ * - `filter` is a function — we track its reference identity.
+ * - Primitives (orderBy, order, limit, offset, scope) are included directly.
+ */
+function useStableKey(options) {
+    // We use a ref to track the previous filter reference. When it changes
+    // the key changes and the view is recreated.
+    const filterRef = useRef(undefined);
+    // Bump a generation counter when the filter reference changes
+    const genRef = useRef(0);
+    if (options?.filter !== filterRef.current) {
+        filterRef.current = options?.filter;
+        genRef.current++;
+    }
+    return useMemo(() => {
+        if (!options)
+            return '';
+        const parts = [];
+        if (options.where)
+            parts.push('w:' + JSON.stringify(options.where));
+        if (options.filter)
+            parts.push('f:' + genRef.current);
+        if (options.orderBy)
+            parts.push('ob:' + String(options.orderBy));
+        if (options.order)
+            parts.push('o:' + options.order);
+        if (options.limit !== undefined)
+            parts.push('l:' + options.limit);
+        if (options.offset !== undefined)
+            parts.push('off:' + options.offset);
+        if (options.scope)
+            parts.push('s:' + options.scope);
+        return parts.join('|');
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        options?.where ? JSON.stringify(options.where) : '',
+        genRef.current,
+        options?.orderBy,
+        options?.order,
+        options?.limit,
+        options?.offset,
+        options?.scope,
+    ]);
+}
+// ── Implementation ──────────────────────────────────────────────────
+export function useQuery(schemaOrTypename, modelKeyOrOptions, maybeOptions) {
+    const ctx = useSyncContext();
+    const { store } = ctx;
+    let typename;
+    let options;
+    if (typeof schemaOrTypename === 'string') {
+        // First arg is a string. Could be either the new zero-arg typed
+        // overload (a schema model key, resolved via `ctx.schema`) or the
+        // legacy untyped overload (a raw typename like 'Chat'). When a
+        // schema is present on the context and the string maps to a known
+        // model key, we look up the real typename from the schema's
+        // `ModelDef.typename`. Otherwise we treat the string as a typename
+        // directly — preserving the legacy behavior for any non-opting
+        // consumer. Both paths converge on the same runtime lookup.
+        const key = schemaOrTypename;
+        const ctxSchema = ctx.schema;
+        const modelDef = ctxSchema
+            ? ctxSchema.models[key]
+            : undefined;
+        typename = modelDef?.typename ?? key;
+        options = modelKeyOrOptions;
+    }
+    else {
+        // Explicit schema path: useQuery(schema, 'chats', options?)
+        const schema = schemaOrTypename;
+        const modelKey = modelKeyOrOptions;
+        const modelDef = schema.models[modelKey];
+        typename = modelDef?.typename ?? modelKey;
+        options = maybeOptions;
+    }
+    const optionsKey = useStableKey(options);
+    // The QueryView is generic-erased to `Record<string, unknown>`, but
+    // the caller's filter is typed in `T`. Wrap rather than cast: the
+    // view passes a Record at runtime and the wrapper narrows to T —
+    // single typed boundary, no `as unknown as` chain.
+    const userFilter = options?.filter;
+    const viewOptions = options
+        ? {
+            where: options.where,
+            filter: userFilter
+                ? (entity) => userFilter(entity)
+                : undefined,
+            orderBy: options.orderBy,
+            order: options.order,
+            limit: options.limit,
+            offset: options.offset,
+            scope: options.scope,
+        }
+        : undefined;
+    const view = useMemo(() => store.pool.createView(typename, viewOptions), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [store.pool, typename, optionsKey]);
+    useEffect(() => () => view.dispose(), [view]);
+    // Self-subscribing — consumers never wrap their component in
+    // `observer`. `useReactive` tracks the observables read inside the
+    // compute function (`view.results`), recomputes on change, and
+    // returns a stable slice so downstream `.sort()` / `.reverse()`
+    // calls don't trip MobX error 37. The default structural equality
+    // check prevents re-renders when nothing actually moved.
+    //
+    // The compute closure MUST be stable when `view` is stable. Without
+    // useCallback([view]), each render passes a fresh arrow to
+    // useReactive, which then can't distinguish "swapped to a new
+    // QueryView" from "same view, new render" — the wrong call would
+    // either re-subscribe every render (waste) or never re-subscribe
+    // when view actually swaps (stale snapshot bug returning a previous
+    // view's results forever).
+    const compute = useCallback(() => view.results.slice(), [view]);
+    return useReactive(compute);
+}
+export function useOne(schemaOrIdOrKey, modelKeyOrId, maybeId) {
+    const { store } = useSyncContext();
+    if (schemaOrIdOrKey === undefined) {
+        return undefined;
+    }
+    if (typeof schemaOrIdOrKey === 'string') {
+        // Either `useOne(id)` (legacy, one arg) or `useOne(modelKey, id)` (global).
+        // Disambiguate by whether a second arg was passed — both paths
+        // converge on the same runtime pool lookup because entity IDs are
+        // globally unique across model types.
+        if (modelKeyOrId !== undefined) {
+            return store.pool.get(modelKeyOrId);
+        }
+        return store.pool.get(schemaOrIdOrKey);
+    }
+    // Explicit schema path: useOne(schema, 'tasks', id)
+    if (!maybeId)
+        return undefined;
+    return store.pool.get(maybeId);
+}

package/dist/react/useReactive.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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

@@ -0,0 +1,111 @@
+'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() };
+        computeRef.current = compute;
+    }
+    else if (computeRef.current !== compute) {
+        const next = compute();
+        if (!equals(snapshotRef.current.value, next)) {
+            snapshotRef.current = { value: next };
+        }
+        computeRef.current = compute;
+        subscribeVersionRef.current++;
+    }
+    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();
+            }
+        });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [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/useReader.d.ts

@@ -0,0 +1,69 @@
+import type { Schema, InferModel } from '../schema/schema.js';
+import type { ResolveSchema } from '../types/global.js';
+import type { SyncStoreContract } from './context.js';
+type GlobalReaderKey = ResolveSchema extends {
+    models: infer M;
+} ? keyof M & string : string;
+type GlobalReaderActions<K extends string> = ResolveSchema extends Schema ? K extends keyof ResolveSchema['models'] & string ? ReaderActions<ResolveSchema, K> : ReaderActions<Schema, string> : ReaderActions<Schema, string>;
+/**
+ * Compatibility schema-typed imperative reader. Returns functions for one-off lookups
+ * without subscribing the component to collection changes.
+ *
+ * Prefer `useAblo()` and call `ablo.<model>.retrieve/list` inside callbacks and
+ * effects in new integrations. This hook remains for older string-keyed code.
+ *
+ * Use this inside event handlers, mutation callbacks, or effects where you
+ * need a current snapshot of the pool but don't want to trigger re-renders
+ * on every entity change.
+ *
+ * For reactive reads, use selector reads through
+ * `useAblo((ablo) => ablo.<model>.retrieve(id))`.
+ *
+ * @example
+ * import { schema } from '@ablo/schema';
+ * import { useReader } from '@ablo/sync-engine/react';
+ *
+ * function useTaskMutations() {
+ *   const read = useReader(schema, 'tasks');
+ *
+ *   return {
+ *     create: async (data) => {
+ *       // Imperative read — uses FK index when available (O(1))
+ *       const existing = read.findMany({ where: { projectId: data.projectId } });
+ *       const order = existing.reduce((m, t) => Math.max(m, t.order ?? 0), 0) + 1;
+ *       // ...
+ *     },
+ *   };
+ * }
+ */
+export interface ReaderFindOptions<T> {
+    /** Equality filter — uses FK index when the field is registered. */
+    where?: Partial<T>;
+    /** Predicate applied AFTER `where` filtering. */
+    filter?: (entity: T) => boolean;
+    /** Sort field. */
+    orderBy?: keyof T & string;
+    /** Sort direction. Default: 'asc'. */
+    order?: 'asc' | 'desc';
+    /** Max results. */
+    limit?: number;
+    /** Skip N results. */
+    offset?: number;
+}
+export interface ReaderActions<S extends Schema, K extends keyof S['models'] & string> {
+    /** Get a single entity by id. Returns undefined if not in pool. */
+    retrieve: (id: string) => InferModel<S, K> | undefined;
+    /** Read a collection with optional filters. Snapshot — not reactive. */
+    list: (options?: ReaderFindOptions<InferModel<S, K>>) => InferModel<S, K>[];
+    /** Count entities matching the options. */
+    count: (options?: ReaderFindOptions<InferModel<S, K>>) => number;
+}
+/**
+ * Pure factory — testable without React. `useReader` wraps this in useMemo.
+ */
+export declare function createReaderActions<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K, store: SyncStoreContract): ReaderActions<S, K>;
+/** @deprecated Prefer `useAblo()` plus `ablo.<model>.retrieve/list` in callbacks/effects. */
+export declare function useReader<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K): ReaderActions<S, K>;
+/** @deprecated Prefer `useAblo()` plus `ablo.<model>.retrieve/list` in callbacks/effects. */
+export declare function useReader<K extends GlobalReaderKey>(modelKey: K): GlobalReaderActions<K>;
+export {};

package/dist/react/useReader.js

@@ -0,0 +1,73 @@
+'use client';
+import { useMemo } from 'react';
+import { useSyncContext } from './context.js';
+import { AbloValidationError } from '../errors.js';
+/**
+ * Pure factory — testable without React. `useReader` wraps this in useMemo.
+ */
+export function createReaderActions(schema, modelKey, store) {
+    const modelDef = schema.models[modelKey];
+    const typename = modelDef?.typename ?? modelKey;
+    function read(options) {
+        // FK index fast path: single-field `where` on a registered FK index → O(1) lookup.
+        let candidates;
+        const whereEntries = options?.where ? Object.entries(options.where) : [];
+        const singleWhere = whereEntries.length === 1 ? whereEntries[0] : undefined;
+        if (singleWhere &&
+            typeof singleWhere[1] === 'string' &&
+            store.pool.hasForeignKeyIndex(typename, singleWhere[0])) {
+            candidates = store.pool.getByForeignKey(typename, singleWhere[0], singleWhere[1]);
+        }
+        else {
+            candidates = store.pool.getByTypeName(typename);
+            if (options?.where) {
+                candidates = candidates.filter((entity) => {
+                    for (const [field, value] of whereEntries) {
+                        if (entity[field] !== value)
+                            return false;
+                    }
+                    return true;
+                });
+            }
+        }
+        let results = candidates;
+        if (options?.filter) {
+            results = results.filter(options.filter);
+        }
+        if (options?.orderBy) {
+            const field = options.orderBy;
+            const dir = options.order === 'desc' ? -1 : 1;
+            results = [...results].sort((a, b) => {
+                const av = a[field];
+                const bv = b[field];
+                if (av === bv)
+                    return 0;
+                if (av == null)
+                    return 1;
+                if (bv == null)
+                    return -1;
+                return av < bv ? -dir : dir;
+            });
+        }
+        if (options?.offset)
+            results = results.slice(options.offset);
+        if (options?.limit !== undefined)
+            results = results.slice(0, options.limit);
+        return results;
+    }
+    return {
+        retrieve: (id) => store.pool.get(id),
+        list: (options) => read(options),
+        count: (options) => read(options).length,
+    };
+}
+export function useReader(schemaOrKey, maybeKey) {
+    const { store, schema: ctxSchema } = useSyncContext();
+    const resolvedSchema = typeof schemaOrKey === 'string' ? ctxSchema : schemaOrKey;
+    const resolvedKey = typeof schemaOrKey === 'string' ? schemaOrKey : maybeKey;
+    if (!resolvedSchema) {
+        throw new AbloValidationError('useReader: no schema available. Pass the schema as the first arg ' +
+            'or wire SyncProvider with a `schema` prop when using the zero-arg overload.', { code: 'reader_schema_missing' });
+    }
+    return useMemo(() => createReaderActions(resolvedSchema, resolvedKey, store), [store, resolvedSchema, resolvedKey]);
+}

package/dist/react/useSyncStatus.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Reactive sync-status snapshot as a discriminated union. Impossible
+ * states (e.g., "connected AND offline") are unrepresentable — each
+ * variant carries only the fields that make sense in that state.
+ *
+ * Inspired by Liveblocks' `useStatus()` and Zero's `useConnectionState()`:
+ * one hook, one switch, no six-boolean guessing games.
+ *
+ * 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 session (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;