@abloatai/ablo 0.3.0

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

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+export interface SyncGroupProviderProps {
+    /** The sync-group identifier — e.g., `matter:abc-123`, `deck:xyz`. */
+    id: string;
+    children: ReactNode;
+}
+export declare function SyncGroupProvider({ id, children }: SyncGroupProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Returns the ID of the nearest `<SyncGroupProvider>`. Throws if
+ * called outside one — sync-group awareness is mandatory by design,
+ * so the error points the consumer at the provider instead of
+ * returning undefined and letting downstream code silently miss scope.
+ *
+ * If a component legitimately renders both inside and outside a
+ * group, structure the tree so the hook is only called on the
+ * inside path (e.g., split into two components). Silent nulls are
+ * never the right answer.
+ */
+export declare function useSyncGroup(): string;

package/dist/react/SyncGroupProvider.js

@@ -0,0 +1,44 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from 'react';
+import { AbloValidationError } from '../errors.js';
+/**
+ * Narrow context for a per-entity sync-group scope. Maps directly onto
+ * Liveblocks' `<RoomProvider id="...">`: wrap a subtree, and any hooks
+ * inside can read `useSyncGroup()` to discover "which entity am I
+ * scoped to?" without threading the ID through props.
+ *
+ * Typical IDs follow the multiplayer sync-group convention: `matter:<id>`,
+ * `deck:<id>`, `project:<id>`. The ID is an opaque string — the
+ * provider doesn't parse it.
+ *
+ * v0.3.0 scope: this is a thin passthrough. Future versions will
+ * scope `useQuery` / `useOne` results to the group automatically.
+ */
+const SyncGroupContext = createContext(null);
+export function SyncGroupProvider({ id, children }) {
+    // Stabilize the context value so consumers memoized on it don't
+    // re-render when the provider re-renders for unrelated reasons.
+    const value = useMemo(() => id, [id]);
+    return _jsx(SyncGroupContext.Provider, { value: value, children: children });
+}
+/**
+ * Returns the ID of the nearest `<SyncGroupProvider>`. Throws if
+ * called outside one — sync-group awareness is mandatory by design,
+ * so the error points the consumer at the provider instead of
+ * returning undefined and letting downstream code silently miss scope.
+ *
+ * If a component legitimately renders both inside and outside a
+ * group, structure the tree so the hook is only called on the
+ * inside path (e.g., split into two components). Silent nulls are
+ * never the right answer.
+ */
+export function useSyncGroup() {
+    const id = useContext(SyncGroupContext);
+    if (!id) {
+        throw new AbloValidationError('useSyncGroup: no <SyncGroupProvider> mounted above this component. ' +
+            'Wrap your tree with <SyncGroupProvider id="matter:..."> from ' +
+            '@ablo/sync-engine/react.', { code: 'no_sync_group_provider' });
+    }
+    return id;
+}

package/dist/react/context.d.ts

@@ -0,0 +1,161 @@
+import { type ReactNode } from 'react';
+import type { Model } from '../Model.js';
+import type { ModelScope } from '../types/index.js';
+import type { QueryView, QueryViewOptions } from '../core/QueryView.js';
+import type { ViewRegistry } from '../core/ViewRegistry.js';
+import type { Schema } from '../schema/schema.js';
+import type { SyncStatus } from '../BaseSyncedStore.js';
+/**
+ * Minimal store interface that the SDK hooks need.
+ * Consumers provide their concrete store (e.g., SyncedStore) that implements this.
+ */
+export interface SyncStoreContract {
+    retrieve(modelClass: abstract new (...args: never[]) => Model, id: string): Model | undefined;
+    queryByClass(modelClass: abstract new (...args: never[]) => Model, options?: {
+        predicate?: (model: Model) => boolean;
+        scope?: ModelScope;
+        orderBy?: keyof Model;
+        order?: 'asc' | 'desc';
+        limit?: number;
+        offset?: number;
+    }): {
+        data: Model[];
+    };
+    /**
+     * Save (create or update) one entity. Calling `save` in a tight loop
+     * produces a single wire commit with one `batchIndex`: the SyncClient
+     * debounces IDB persistence and the server push to one microtask, and
+     * TransactionQueue coalesces every transaction staged in the tick into
+     * one batch. There is intentionally no `saveMany` — Zero, Replicache,
+     * and the rest of the local-first lineage all expose one-row writes
+     * and rely on the implicit tick boundary.
+     *
+     * `skipValidation` exists for trusted bulk paths (AI sandbox layer
+     * generation, PPTX import, hydration) where the producer has already
+     * type-checked and per-row Zod is a measurable cost.
+     */
+    save(model: Model, options?: {
+        skipValidation?: boolean;
+    }): Promise<void>;
+    delete(model: Model): Promise<void>;
+    archive(model: Model): Promise<void>;
+    unarchive(model: Model): Promise<void>;
+    /** The ObjectPool — for entity/collection lookups by ID or typename. */
+    pool: {
+        get(id: string): Model | undefined;
+        getByTypeName(typename: string, scope?: ModelScope): Model[];
+        getByForeignKey(modelName: string, fieldName: string, fieldValue: string): Model[];
+        createFromData(data: Record<string, unknown>): Model | null;
+        hasForeignKeyIndex(typename: string, fieldName: string): boolean;
+        createView<T extends Record<string, unknown>>(typename: string, options?: QueryViewOptions<T>): QueryView<T>;
+        viewRegistry: ViewRegistry;
+    };
+    /**
+     * Reactive sync-status getters. Powered by MobX `computed` inside
+     * `BaseSyncedStore`, so they're safe to read in `observer` components
+     * and inside `reaction(() => store.isReady, ...)`. Consumers that
+     * don't want to touch MobX should prefer the `useSyncStatus()` hook.
+     */
+    readonly isReady: boolean;
+    readonly isSyncing: boolean;
+    readonly isOffline: boolean;
+    readonly isReconnecting: boolean;
+    readonly isError: boolean;
+    readonly hasUnsyncedChanges: boolean;
+    /**
+     * Raw MobX-observable `SyncStatus` record. `useSyncStatus()` reads
+     * `state`, `progress`, `pendingChanges`, `isSessionError`, `error`
+     * from this to build its tagged union. Exposed on the contract so
+     * consumer-facing hooks and test doubles can manipulate it directly.
+     */
+    readonly syncStatus: SyncStatus;
+}
+export interface SyncReactContext {
+    store: SyncStoreContract;
+    /** Current organization ID for default entity context */
+    organizationId: string;
+    /**
+     * Optional schema reference. When set, compatibility hook overloads
+     * (`useQuery('tasks')`, `useOne('tasks', id)`, etc.) resolve their
+     * model metadata from this schema — consumers don't pass `schema` at
+     * every call site. When absent, hooks fall back to the legacy
+     * `(schema, modelKey, …)` signatures so non-opting consumers keep
+     * working unchanged.
+     *
+     * The stored reference is untyped here (`Schema` with default
+     * parameters) because the React context is a single runtime value
+     * shared by every hook. The compile-time types flow from the
+     * consumer's `declare global { interface AbloSync { Schema: ... } }`
+     * augmentation — see `src/types/global.ts`.
+     */
+    schema?: Schema;
+    /**
+     * Optional presence source. When set, `usePresence()` returns this
+     * value cast to the consumer's `ResolvePresence` type (declared via
+     * `interface AbloSync { Presence: ... }`). The SDK doesn't own a
+     * presence wire format — consumers plug whatever backs their cursors,
+     * status, or activity state (a MobX store, a Zustand slice, a custom
+     * subscription). The typed-global gives it a call-site-ergonomic
+     * type without the SDK dictating the transport.
+     */
+    presence?: unknown;
+    /**
+     * Optional intent initiator. Same pattern as presence — consumers
+     * plug a function that turns an intent claim into a handle they
+     * control (WebSocket send, optimistic local update, whatever).
+     * `useIntent(name)` returns a typed invoker for the named intent
+     * from `interface AbloSync { Intents: ... }`.
+     */
+    beginIntent?: (intentName: string, claim: unknown) => unknown;
+}
+export declare const SyncContext: import("react").Context<SyncReactContext | null>;
+/**
+ * Access the sync store from React components.
+ * Must be used within a SyncProvider.
+ */
+export declare function useSyncContext(): SyncReactContext;
+/**
+ * Props for SyncProvider.
+ */
+export interface SyncProviderProps {
+    /** The sync store (must implement SyncStoreContract). */
+    store: SyncStoreContract;
+    /** Current organization ID for default entity context. */
+    organizationId: string;
+    /**
+     * Optional schema. Wire this when you want compatibility string-keyed hooks
+     * (`useQuery('tasks')`) — the schema type also narrows via the
+     * consumer's global `AbloSync` declaration. Omit to keep hooks on
+     * their legacy `(schema, modelKey, …)` signatures.
+     */
+    schema?: Schema;
+    /**
+     * Optional presence source for `usePresence()`. See
+     * {@link SyncReactContext.presence} — the consumer plugs whatever
+     * backs their presence state; the hook returns it with
+     * `ResolvePresence` typing.
+     */
+    presence?: unknown;
+    /**
+     * Optional intent initiator for `useIntent()`. See
+     * {@link SyncReactContext.beginIntent}.
+     */
+    beginIntent?: (intentName: string, claim: unknown) => unknown;
+    children?: ReactNode;
+}
+/**
+ * SyncProvider wires the sync store into React so SDK hooks
+ * (useModel, useModels, useMutations) can access it.
+ *
+ * @example
+ * import { SyncProvider } from '@ablo/sync-engine/react';
+ *
+ * function App() {
+ *   return (
+ *     <SyncProvider store={syncStore} organizationId={orgId}>
+ *       <YourApp />
+ *     </SyncProvider>
+ *   );
+ * }
+ */
+export declare function SyncProvider({ store, organizationId, schema, presence, beginIntent, children, }: SyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SyncReactContext | null>>;

package/dist/react/context.js

@@ -0,0 +1,35 @@
+'use client';
+import { createContext, createElement, useContext } from 'react';
+import { AbloValidationError } from '../errors.js';
+export const SyncContext = createContext(null);
+/**
+ * Access the sync store from React components.
+ * Must be used within a SyncProvider.
+ */
+export function useSyncContext() {
+    const ctx = useContext(SyncContext);
+    if (!ctx) {
+        throw new AbloValidationError('useSyncContext must be used within a SyncProvider', {
+            code: 'sync_context_missing_provider',
+        });
+    }
+    return ctx;
+}
+/**
+ * SyncProvider wires the sync store into React so SDK hooks
+ * (useModel, useModels, useMutations) can access it.
+ *
+ * @example
+ * import { SyncProvider } from '@ablo/sync-engine/react';
+ *
+ * function App() {
+ *   return (
+ *     <SyncProvider store={syncStore} organizationId={orgId}>
+ *       <YourApp />
+ *     </SyncProvider>
+ *   );
+ * }
+ */
+export function SyncProvider({ store, organizationId, schema, presence, beginIntent, children, }) {
+    return createElement(SyncContext.Provider, { value: { store, organizationId, schema, presence, beginIntent } }, children);
+}

package/dist/react/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @ablo/sync-engine/react — React bindings (v0.3.0)
+ *
+ * Umbrella provider:
+ *   <AbloProvider schema={...} userId={...} orgId={...} fallback={<Skeleton/>}>
+ *     — owns sync engine + multiplayer lifecycle; the `fallback` prop
+ *     gates children on first bootstrap. Pass `fallback="passthrough"`
+ *     to disable the gate.
+ *   <SyncGroupProvider id="matter:...">         — per-entity scope
+ *   <ClientSideSuspense fallback={<Skeleton/>}> — NESTED gate inside an
+ *     already-ready provider. Use only when you need a separate gate
+ *     for a heavy subtree (e.g. a canvas) while app chrome renders
+ *     immediately. The provider-level `fallback` is the default path.
+ *
+ * Data hooks:
+ *   useAblo((ablo) => ablo.tasks.retrieve(id)) — primary React read API
+ *   useAblo()                                  — typed client for callbacks/effects
+ *   useQuery/useOne/useReader/useMutate        — compatibility helpers for older
+ *                                                string-keyed integrations
+ *   useMutators(defs, opts?)                   — Zero-style custom mutators
+ *   useUndoScope(name)                         — per-surface undo/redo
+ *
+ * Status + errors:
+ *   useSyncStatus()           — tagged-union lifecycle snapshot
+ *   useErrorListener(cb)      — imperative error callback (Sentry/Datadog)
+ *   useCurrentUserId()        — the provider's userId prop
+ *
+ * Multiplayer (always available — `<AbloProvider>` always constructs a client):
+ *   useAblo((ablo) => ablo.intents.list(...)) — reactive coordination reads
+ *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
+ *   usePresence()             — typed presence view
+ *   useIntent(name)           — typed intent dispatcher
+ *
+ * ── Breaking changes from v0.2.x ───────────────────────────────────
+ * Removed: <SyncProvider>, SyncContext, useSyncContext — folded into
+ *   <AbloProvider>. Access the raw engine with `useSync()`.
+ * Removed: createAbloContext() factory + its returned AbloProvider —
+ *   multiplayer is now always-on inside <AbloProvider>. Schema-typed
+ *   participant hooks ship in a follow-up release.
+ * Removed: withSync (no-op alias of observer). Import observer
+ *   from mobx-react-lite directly if you still need it.
+ * Changed: useSyncStatus() now returns a discriminated union. See the
+ *   migration notes in CHANGELOG.md.
+ */
+export type { DefaultSyncShape, ResolveSchema, ResolvePresence, ResolveIntents, ResolveUserMeta, ResolveModelKey, } from '../types/global.js';
+export { AbloProvider, useParticipant, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseParticipantOptions, type UseParticipantReturn, type MeshParticipantStatus, } from './AbloProvider.js';
+export { SyncGroupProvider, useSyncGroup, type SyncGroupProviderProps, } from './SyncGroupProvider.js';
+export { ClientSideSuspense, type ClientSideSuspenseProps, } from './ClientSideSuspense.js';
+export { DefaultFallback } from './DefaultFallback.js';
+export type { SyncStoreContract } from './context.js';
+export { useSyncStatus, type SyncStatusSnapshot, } from './useSyncStatus.js';
+export { useErrorListener } from './useErrorListener.js';
+export { useMutationFailureListener, type MutationFailurePayload, } from './useMutationFailureListener.js';
+export { useCurrentUserId } from './useCurrentUserId.js';
+export { useReactive } from './useReactive.js';
+export { useQuery, useOne, type QueryOptions } from './useQuery.js';
+export { useMutate, type MutateActions } from './useMutate.js';
+export { useReader, type ReaderActions, type ReaderFindOptions } from './useReader.js';
+export { useMutators, type MutatorInvokers, type InvokerFor, type UseMutatorsOptions, } from './useMutators.js';
+export { useUndoScope, type UseUndoScopeResult } from './useUndoScope.js';
+export { useAblo, type UseAbloHydratedModelResult, type UseAbloModelOptions, type UseAbloModelResult, } from './useAblo.js';
+export { usePresence } from './usePresence.js';
+export { useIntent } from './useIntent.js';
+export { ModelScope } from '../types/index.js';

package/dist/react/index.js

@@ -0,0 +1,73 @@
+/**
+ * @ablo/sync-engine/react — React bindings (v0.3.0)
+ *
+ * Umbrella provider:
+ *   <AbloProvider schema={...} userId={...} orgId={...} fallback={<Skeleton/>}>
+ *     — owns sync engine + multiplayer lifecycle; the `fallback` prop
+ *     gates children on first bootstrap. Pass `fallback="passthrough"`
+ *     to disable the gate.
+ *   <SyncGroupProvider id="matter:...">         — per-entity scope
+ *   <ClientSideSuspense fallback={<Skeleton/>}> — NESTED gate inside an
+ *     already-ready provider. Use only when you need a separate gate
+ *     for a heavy subtree (e.g. a canvas) while app chrome renders
+ *     immediately. The provider-level `fallback` is the default path.
+ *
+ * Data hooks:
+ *   useAblo((ablo) => ablo.tasks.retrieve(id)) — primary React read API
+ *   useAblo()                                  — typed client for callbacks/effects
+ *   useQuery/useOne/useReader/useMutate        — compatibility helpers for older
+ *                                                string-keyed integrations
+ *   useMutators(defs, opts?)                   — Zero-style custom mutators
+ *   useUndoScope(name)                         — per-surface undo/redo
+ *
+ * Status + errors:
+ *   useSyncStatus()           — tagged-union lifecycle snapshot
+ *   useErrorListener(cb)      — imperative error callback (Sentry/Datadog)
+ *   useCurrentUserId()        — the provider's userId prop
+ *
+ * Multiplayer (always available — `<AbloProvider>` always constructs a client):
+ *   useAblo((ablo) => ablo.intents.list(...)) — reactive coordination reads
+ *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
+ *   usePresence()             — typed presence view
+ *   useIntent(name)           — typed intent dispatcher
+ *
+ * ── Breaking changes from v0.2.x ───────────────────────────────────
+ * Removed: <SyncProvider>, SyncContext, useSyncContext — folded into
+ *   <AbloProvider>. Access the raw engine with `useSync()`.
+ * Removed: createAbloContext() factory + its returned AbloProvider —
+ *   multiplayer is now always-on inside <AbloProvider>. Schema-typed
+ *   participant hooks ship in a follow-up release.
+ * Removed: withSync (no-op alias of observer). Import observer
+ *   from mobx-react-lite directly if you still need it.
+ * Changed: useSyncStatus() now returns a discriminated union. See the
+ *   migration notes in CHANGELOG.md.
+ */
+// ── Umbrella provider + lifecycle hooks ────────────────────────────
+export { AbloProvider, useParticipant, useSync, useSyncStore, } from './AbloProvider.js';
+export { SyncGroupProvider, useSyncGroup, } from './SyncGroupProvider.js';
+export { ClientSideSuspense, } from './ClientSideSuspense.js';
+export { DefaultFallback } from './DefaultFallback.js';
+// ── Status + errors + identity ─────────────────────────────────────
+export { useSyncStatus, } from './useSyncStatus.js';
+export { useErrorListener } from './useErrorListener.js';
+export { useMutationFailureListener, } from './useMutationFailureListener.js';
+export { useCurrentUserId } from './useCurrentUserId.js';
+// ── Primitive for building custom reactive hooks ──────────────────
+//
+// Consumers building bespoke hooks on top of the SDK should call
+// `useReactive(() => compute())` instead of reaching for React's
+// lower-level `useSyncExternalStore`. Hides the cached-snapshot
+// contract and handles default structural equality for arrays.
+export { useReactive } from './useReactive.js';
+// ── Data hooks ─────────────────────────────────────────────────────
+export { useQuery, useOne } from './useQuery.js';
+export { useMutate } from './useMutate.js';
+export { useReader } from './useReader.js';
+export { useMutators, } from './useMutators.js';
+export { useUndoScope } from './useUndoScope.js';
+export { useAblo, } from './useAblo.js';
+// ── Presence + intent (typed via AbloSync global augmentation) ─────
+export { usePresence } from './usePresence.js';
+export { useIntent } from './useIntent.js';
+// ── ModelScope re-export ───────────────────────────────────────────
+export { ModelScope } from '../types/index.js';

package/dist/react/internalContext.d.ts

@@ -0,0 +1,35 @@
+import type { Ablo } from '../client/Ablo.js';
+import type { SchemaRecord } from '../schema/schema.js';
+/**
+ * Internal context populated by `<AbloProvider>`. Separate from
+ * `SyncContext` (which carries the store + schema for the data
+ * hooks) because these fields are owned by the umbrella provider
+ * and don't belong on the raw `SyncStoreContract`.
+ *
+ * Consumers should NOT use this directly — access the fields via
+ * the typed hooks (`useCurrentUserId`, `useErrorListener`, etc.).
+ */
+export interface AbloInternalContextValue {
+    /**
+     * Optional app user id when the application passed one. Hosted Ablo
+     * identity is server-derived, so this may be null.
+     */
+    currentUserId: string | null;
+    /** Subscribe to provider-level errors (engine errors, bootstrap failures, session issues). */
+    subscribeError: (listener: (error: Error) => void) => () => void;
+    /** Fire an error to all subscribed listeners. Called internally by the provider. */
+    emitError: (error: Error) => void;
+    /**
+     * The SyncEngine proxy for this provider. `null` before bootstrap
+     * resolves. Exposed through the internal context so `useSync()`
+     * can return it without having to reach into the store — the two
+     * are sibling objects constructed together by `createSyncEngine`
+     * and shouldn't be coerced through each other.
+     *
+     * Typed as `Ablo<SchemaRecord>` on the context because
+     * generics don't flow through React context. `useSync<R>()` widens
+     * via its own generic — runtime value is the concrete engine.
+     */
+    engine: Ablo<SchemaRecord> | null;
+}
+export declare const AbloInternalContext: import("react").Context<AbloInternalContextValue | null>;

package/dist/react/internalContext.js

@@ -0,0 +1,3 @@
+'use client';
+import { createContext } from 'react';
+export const AbloInternalContext = createContext(null);

package/dist/react/useAblo.d.ts

@@ -0,0 +1,72 @@
+import type { Ablo, ResourceIntent } from '../client/Ablo.js';
+import type { ModelOperations } from '../client/createModelProxy.js';
+import type { SchemaRecord } from '../schema/schema.js';
+import type { ResolveSchema } from '../types/global.js';
+/**
+ * Resolved schema-record type for the consumer's app. Reads the
+ * `AbloSync` global augmentation if declared, falls back to the
+ * loose `SchemaRecord` if not. This lets `useAblo()` produce a
+ * fully typed engine handle without the consumer having to pass
+ * `<(typeof schema)['models']>` at every call site.
+ */
+type DefaultModels = ResolveSchema extends {
+    models: infer M;
+} ? M extends SchemaRecord ? M : SchemaRecord : SchemaRecord;
+type ModelResourceSelector<R extends SchemaRecord, T, C> = (ablo: Ablo<R>) => ModelOperations<T, C>;
+type AbloSelector<R extends SchemaRecord, T> = (ablo: Ablo<R>) => T;
+export interface UseAbloModelOptions<T> {
+    /**
+     * Initial row, usually from a Server Component or loader. The hook returns it
+     * until the model resource has a newer row in the local pool.
+     */
+    readonly initial?: T;
+}
+export interface UseAbloModelResult<T> {
+    /** Current row for the id, or `initial` until the row has hydrated. */
+    readonly data: T | undefined;
+    /** Active work claims on this model row. */
+    readonly intents: readonly ResourceIntent[];
+    /** Convenience flag for disabling UI while another participant is active. */
+    readonly busy: boolean;
+}
+export type UseAbloHydratedModelResult<T> = Omit<UseAbloModelResult<T>, 'data'> & {
+    readonly data: T;
+};
+/**
+ * useAblo — access the typed engine instance, or subscribe to a specific
+ * `ablo.<model>` row from inside an `<AbloProvider>` subtree.
+ *
+ * Zero-arg when the consumer declares the `AbloSync` global
+ * augmentation (`declare global { interface AbloSync { Schema:
+ * typeof schema } }`). The default generic resolves through
+ * `ResolveSchema['models']` so call sites stay clean:
+ *
+ * ```ts
+ * // With AbloSync augmentation (recommended):
+ * const ablo = useAblo();
+ * if (!ablo) return <Loading />;
+ * const docs = await ablo.documents.load({ where: { id } });
+ *
+ * // Reactive selector:
+ * const doc = useAblo((ablo) => ablo.documents.retrieve(id)) ?? serverDoc;
+ * const intents = useAblo((ablo) => ablo.intents.list({ resource: 'documents', id }));
+ *
+ * // Without augmentation, pass the schema generic:
+ * const ablo = useAblo<(typeof schema)['models']>();
+ * ```
+ *
+ * Returns `null` while the engine is bootstrapping. Branch on null
+ * and render a loading state (or use `useSyncStatus()` to gate on
+ * `'connected'`) before reaching for model methods.
+ */
+export declare function useAblo<R extends SchemaRecord = DefaultModels>(): Ablo<R> | null;
+export declare function useAblo<R extends SchemaRecord = DefaultModels, T = unknown>(select: AbloSelector<R, T>): T | undefined;
+export declare function useAblo<T, C>(resource: ModelOperations<T, C>, id: string, options: UseAbloModelOptions<T> & {
+    readonly initial: T;
+}): UseAbloHydratedModelResult<T>;
+export declare function useAblo<R extends SchemaRecord = DefaultModels, T = Record<string, unknown>, C = unknown>(select: ModelResourceSelector<R, T, C>, id: string, options: UseAbloModelOptions<T> & {
+    readonly initial: T;
+}): UseAbloHydratedModelResult<T>;
+export declare function useAblo<T, C>(resource: ModelOperations<T, C>, id: string, options?: UseAbloModelOptions<T>): UseAbloModelResult<T>;
+export declare function useAblo<R extends SchemaRecord = DefaultModels, T = Record<string, unknown>, C = unknown>(select: ModelResourceSelector<R, T, C>, id: string, options?: UseAbloModelOptions<T>): UseAbloModelResult<T>;
+export {};

package/dist/react/useAblo.js

@@ -0,0 +1,63 @@
+'use client';
+import { useContext, useEffect, useState } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+import { getModelResourceMeta } from '../client/createModelProxy.js';
+import { Model, modelAsRow } from '../Model.js';
+import { useReactive } from './useReactive.js';
+const EMPTY_INTENTS = Object.freeze([]);
+function readModelResult(engine, resource, id, initial) {
+    if (!resource || id === undefined) {
+        return { data: initial, intents: EMPTY_INTENTS, busy: false };
+    }
+    const data = snapshotValue(resource.retrieve(id) ?? initial);
+    const meta = getModelResourceMeta(resource);
+    const intents = meta && engine
+        ? engine.intents.list({ resource: meta.key, id })
+        : EMPTY_INTENTS;
+    return { data, intents, busy: intents.length > 0 };
+}
+function snapshotValue(value) {
+    if (value instanceof Model) {
+        return modelAsRow(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => snapshotValue(item));
+    }
+    return value;
+}
+export function useAblo(resourceOrSelect, id, options) {
+    const ctx = useContext(AbloInternalContext);
+    const engine = ctx?.engine ?? null;
+    const initial = options?.initial;
+    const hasSelection = resourceOrSelect !== undefined;
+    const isSelectorOnly = typeof resourceOrSelect === 'function' && id === undefined;
+    const resource = typeof resourceOrSelect === 'function' && id !== undefined
+        ? engine
+            ? resourceOrSelect(engine)
+            : undefined
+        : typeof resourceOrSelect === 'function'
+            ? undefined
+            : resourceOrSelect;
+    const [intentVersion, setIntentVersion] = useState(0);
+    useEffect(() => {
+        if (!engine || !hasSelection)
+            return;
+        return engine.intents.subscribe(() => setIntentVersion((version) => version + 1));
+    }, [engine, hasSelection]);
+    const selected = useReactive(() => {
+        void intentVersion;
+        if (!engine || !isSelectorOnly || typeof resourceOrSelect !== 'function') {
+            return undefined;
+        }
+        return snapshotValue(resourceOrSelect(engine));
+    });
+    const modelResult = useReactive(() => {
+        void intentVersion;
+        return readModelResult(engine, resource, id, initial);
+    });
+    if (isSelectorOnly)
+        return selected;
+    if (resourceOrSelect)
+        return modelResult;
+    return engine;
+}

package/dist/react/useCurrentUserId.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Returns the app user ID passed to the nearest `<AbloProvider>`, when
+ * the app chose to provide one.
+ *
+ * Hosted Ablo identity is resolved server-side from the API key, session,
+ * or capability token. This hook is only for app-owned fields like
+ * `assigneeId`; it is not required for Ablo sync to connect.
+ *
+ * Use this in leaf components that need the current user ID for
+ * mutation payloads, presence labels, permission checks, etc.
+ * @example
+ * function TaskRow({ id }) {
+ *   const userId = useCurrentUserId();
+ *   const ablo = useAblo();
+ *   if (!userId) return null;
+ *   return <button onClick={() => ablo?.tasks.update(id, { assigneeId: userId })}>
+ *     Assign to me
+ *   </button>;
+ * }
+ */
+export declare function useCurrentUserId(): string | null;