@abloatai/ablo 0.25.0 → 0.27.0

package/dist/react/context.d.ts

@@ -1,174 +1,55 @@
 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';
-import type { ParticipantScope } from '../sync/participants.js';
-/**
- * A single LOCAL mutation as observed off the commit stream — the substrate
- * the undo system records from. One is emitted per local create/update/
- * delete/archive (remote/collaborator deltas never appear here: they apply
- * through a separate pool path that doesn't queue mutations). `previousData`
- * holds the pre-edit field values (captured from the model's
- * `modifiedProperties` first-old-wins baseline), so an inverse op is fully
- * derivable from the event alone — no separate snapshot pass.
- *
- * This mirrors how Yjs's `UndoManager` derives reverse-ops by observing the
- * doc and Liveblocks' `room.history` records room ops: undo listens to the
- * one place all local writes converge, rather than wrapping the write call.
- */
-export interface LocalMutation {
-    type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
-    /** Registered model name (e.g. `'SlideLayer'`); resolved to a schema key by the recorder. */
-    modelName: string;
-    modelId: string;
-    /** New field values (create/update). */
-    data?: Record<string, unknown> | null;
-    /** Pre-edit field values (update → inverse patch; delete → full re-create row). */
-    previousData?: Record<string, unknown> | null;
-}
-/**
- * Minimal store interface that the SDK hooks need.
- * Consumers provide their concrete store (e.g., SyncedStore) that implements this.
- */
-export interface SyncStoreContract {
-    /**
-     * Subscribe to the LOCAL mutation stream (optimistic, pre-ack) for undo
-     * recording. Optional so minimal test doubles can omit it — when absent,
-     * undo scopes simply record nothing. The concrete store
-     * (`BaseSyncedStore`) wires this to the TransactionQueue's
-     * `transaction:created` event. Returns an unsubscribe function.
-     */
-    subscribeLocalMutations?(handler: (mutation: LocalMutation) => void): () => void;
-    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;
-    /**
-     * Area-of-interest (dynamic read subscription). `enterScope`/`leaveScope`
-     * move the connection's read interest as the user navigates (open/close a
-     * deck, sheet, doc); `pinScope`/`unpinScope` express prominence (an active
-     * claim keeps a group subscribed). Each resolves the scope through the same
-     * resolver the claim path uses, so read interest and write claims agree on
-     * the sync-group string. Optional so minimal test doubles can omit them;
-     * no-ops before the socket exists. The concrete store (`BaseSyncedStore`)
-     * forwards to its `AreaOfInterestManager`.
-     */
-    enterScope?(scope: ParticipantScope, opts?: {
-        hydrate?: boolean;
-    }): Promise<void>;
-    leaveScope?(scope: ParticipantScope): Promise<void>;
-    pinScope?(scope: ParticipantScope): Promise<void>;
-    unpinScope?(scope: ParticipantScope): Promise<void>;
-    /**
-     * 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;
-}
+import type { SyncStoreContract } from '../core/storeContract.js';
+export type { SyncStoreContract, LocalMutation } from '../core/storeContract.js';
 export interface SyncReactContext {
     store: SyncStoreContract;
-    /** Current organization ID for default entity context */
+    /** The organization id used as the default scope for reads and writes. */
     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.
+     * 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 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 module '@abloatai/ablo' { interface Register { Schema: ... } }`
-     * augmentation — see `src/types/global.ts`.
+     * 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>;
 /**
- * Access the sync store from React components. The context is provided by
- * `<AbloProvider>` (which renders the internal {@link SyncProvider}); public
- * consumers wire `<AbloProvider client={ablo}>`, never this directly.
+ * 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 (must implement SyncStoreContract). */
+    /** The sync store, which must implement {@link SyncStoreContract}. */
     store: SyncStoreContract;
-    /** Current organization ID for default entity context. */
+    /** The organization id used as the default scope for reads and writes. */
     organizationId: string;
     /**
-     * Optional schema. Wire this when you want compatibility string-keyed hooks
-     * (`useQuery('tasks')`) — the schema type also narrows via the
-     * consumer's `Register` registration. Omit to keep hooks on
-     * their legacy `(schema, modelKey, …)` signatures.
+     * 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;
 }
 /**
- * SyncProvider — the INTERNAL low-level provider that wires a built sync store
- * into React so SDK hooks (useModel, useModels, useMutations) can reach it.
- *
- * Public consumers do NOT use this directly (it is not exported from
- * `@abloatai/ablo/react`). `<AbloProvider client={ablo}>` constructs the
- * store from your `Ablo({ schema, apiKey })` client and renders this provider
- * underneath — reach for `<AbloProvider>`.
+ * 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

@@ -3,9 +3,10 @@ import { createContext, createElement, useContext } from 'react';
 import { AbloValidationError } from '../errors.js';
 export const SyncContext = createContext(null);
 /**
- * Access the sync store from React components. The context is provided by
- * `<AbloProvider>` (which renders the internal {@link SyncProvider}); public
- * consumers wire `<AbloProvider client={ablo}>`, never this directly.
+ * 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);
@@ -17,13 +18,11 @@ export function useSyncContext() {
     return ctx;
 }
 /**
- * SyncProvider — the INTERNAL low-level provider that wires a built sync store
- * into React so SDK hooks (useModel, useModels, useMutations) can reach it.
- *
- * Public consumers do NOT use this directly (it is not exported from
- * `@abloatai/ablo/react`). `<AbloProvider client={ablo}>` constructs the
- * store from your `Ablo({ schema, apiKey })` client and renders this provider
- * underneath — reach for `<AbloProvider>`.
+ * 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);

package/dist/react/index.d.ts

@@ -1,48 +1,47 @@
 /**
- * @abloatai/ablo/react — React bindings (v0.3.0)
+ * React bindings for `@abloatai/ablo`.
  *
- * Umbrella provider:
- *   const ablo = Ablo({ schema, apiKey })   // build once — module scope or useMemo
+ * # Provider
+ *
+ * Build a client once — at module scope or with `useMemo` — and wrap your tree:
+ *
+ *   const ablo = Ablo({ schema, apiKey })
  *   <AbloProvider client={ablo} fallback={<Skeleton/>}>
- *     — `client` is the only required prop (construct it yourself; the provider
- *     is the thin reactive binding, like `<Elements stripe={...}>`). `userId`
- *     is optional + informational. Owns sync engine + multiplayer lifecycle;
- *     the `fallback` prop
- *     gates children on first bootstrap. Pass `fallback="passthrough"`
- *     to disable the gate.
- *   <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.get(id))     — primary React read API (sync local snapshot)
- *   useAblo()                                  — typed client for callbacks/effects
- *                                                (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
- *
- * 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.<model>.claim.state(...)) — reactive coordination reads
- *   useWatch({ scope }) — join multiplayer for a scope, get peers/claims
- *
- * ── 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.
+ *
+ * `client` is the only required prop; you construct it, and the provider is the
+ * thin reactive binding around it. The provider owns the sync-engine and
+ * multiplayer lifecycle. Its `fallback` gates children until the first sync
+ * bootstrap completes — pass `fallback="passthrough"` to render children
+ * immediately. `userId` is optional and informational.
+ *
+ * {@link ClientSideSuspense} adds a nested gate inside an already-ready
+ * provider. Reach for it only when a heavy subtree, such as a canvas, needs its
+ * own gate while the rest of the app renders right away; the provider-level
+ * `fallback` is the usual path.
+ *
+ * # Data hooks
+ *
+ *   useAblo((ablo) => ablo.tasks.get(id))  — subscribe to a local snapshot (the main read API)
+ *   useAblo()                              — the typed client, for callbacks and effects:
+ *                                            synchronous local reads (`ablo.<model>.get`/`getAll`),
+ *                                            async server reads (`retrieve`/`list`),
+ *                                            and writes (`create`/`update`/`delete`)
+ *   useMutators(defs, opts?)               — define custom mutators
+ *   useUndoScope(name)                     — per-surface undo and redo
+ *
+ * # Status and errors
+ *
+ *   useSyncStatus()       — a discriminated-union snapshot of the sync lifecycle
+ *   useErrorListener(cb)  — an imperative error callback, for telemetry or toasts
+ *   useCurrentUserId()    — the provider's `userId` prop
+ *
+ * # Multiplayer
+ *
+ * Multiplayer is always available, because `<AbloProvider>` always constructs a
+ * client:
+ *
+ *   useAblo((ablo) => ablo.<model>.claim.state(...))  — reactive coordination reads
+ *   useWatch({ scope })                               — join a scope to get its peers and claims
  */
 export type { DefaultSyncShape, ResolveSchema, ResolvePresence, ResolveClaims, ResolveUserMeta, ResolveModelKey, } from '../types/global.js';
 export { AbloProvider, useWatch, usePeers, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseWatchOptions, type UseWatchReturn, type MeshParticipantStatus, } from './AbloProvider.js';

package/dist/react/index.js

@@ -1,48 +1,47 @@
 /**
- * @abloatai/ablo/react — React bindings (v0.3.0)
+ * React bindings for `@abloatai/ablo`.
  *
- * Umbrella provider:
- *   const ablo = Ablo({ schema, apiKey })   // build once — module scope or useMemo
+ * # Provider
+ *
+ * Build a client once — at module scope or with `useMemo` — and wrap your tree:
+ *
+ *   const ablo = Ablo({ schema, apiKey })
  *   <AbloProvider client={ablo} fallback={<Skeleton/>}>
- *     — `client` is the only required prop (construct it yourself; the provider
- *     is the thin reactive binding, like `<Elements stripe={...}>`). `userId`
- *     is optional + informational. Owns sync engine + multiplayer lifecycle;
- *     the `fallback` prop
- *     gates children on first bootstrap. Pass `fallback="passthrough"`
- *     to disable the gate.
- *   <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.get(id))     — primary React read API (sync local snapshot)
- *   useAblo()                                  — typed client for callbacks/effects
- *                                                (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
+ * `client` is the only required prop; you construct it, and the provider is the
+ * thin reactive binding around it. The provider owns the sync-engine and
+ * multiplayer lifecycle. Its `fallback` gates children until the first sync
+ * bootstrap completes — pass `fallback="passthrough"` to render children
+ * immediately. `userId` is optional and informational.
+ *
+ * {@link ClientSideSuspense} adds a nested gate inside an already-ready
+ * provider. Reach for it only when a heavy subtree, such as a canvas, needs its
+ * own gate while the rest of the app renders right away; the provider-level
+ * `fallback` is the usual path.
+ *
+ * # Data hooks
+ *
+ *   useAblo((ablo) => ablo.tasks.get(id))  — subscribe to a local snapshot (the main read API)
+ *   useAblo()                              — the typed client, for callbacks and effects:
+ *                                            synchronous local reads (`ablo.<model>.get`/`getAll`),
+ *                                            async server reads (`retrieve`/`list`),
+ *                                            and writes (`create`/`update`/`delete`)
+ *   useMutators(defs, opts?)               — define custom mutators
+ *   useUndoScope(name)                     — per-surface undo and redo
+ *
+ * # Status and errors
+ *
+ *   useSyncStatus()       — a discriminated-union snapshot of the sync lifecycle
+ *   useErrorListener(cb)  — an imperative error callback, for telemetry or toasts
+ *   useCurrentUserId()    — the provider's `userId` prop
  *
- * Status + errors:
- *   useSyncStatus()           — tagged-union lifecycle snapshot
- *   useErrorListener(cb)      — imperative error callback (Sentry/Datadog)
- *   useCurrentUserId()        — the provider's userId prop
+ * # Multiplayer
  *
- * Multiplayer (always available — `<AbloProvider>` always constructs a client):
- *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
- *   useWatch({ scope }) — join multiplayer for a scope, get peers/claims
+ * Multiplayer is always available, because `<AbloProvider>` always constructs a
+ * client:
  *
- * ── 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.
+ *   useAblo((ablo) => ablo.<model>.claim.state(...))  — reactive coordination reads
+ *   useWatch({ scope })                               — join a scope to get its peers and claims
  */
 // ── Umbrella provider + lifecycle hooks ────────────────────────────
 export { AbloProvider, useWatch, usePeers, useSync, useSyncStore, } from './AbloProvider.js';

package/dist/react/internalContext.d.ts

@@ -1,34 +1,32 @@
 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.).
+ * The context that `<AbloProvider>` populates for its own hooks. It is kept
+ * separate from the data-hook context, which carries the store and schema,
+ * because these fields belong to the provider rather than to the store. Read
+ * them through the typed hooks such as `useCurrentUserId` and
+ * `useErrorListener` rather than reaching into this context directly.
  */
 export interface AbloInternalContextValue {
     /**
-     * Optional app user id when the application passed one. Hosted Ablo
-     * identity is server-derived, so this may be null.
+     * The application user id, when your app passed one to `<AbloProvider>`. Sync
+     * identity is derived on the server from the API key, so this is `null`
+     * unless you set it, and it is not required for sync to work.
      */
     currentUserId: string | null;
-    /** Subscribe to provider-level errors (engine errors, bootstrap failures, session issues). */
+    /** Subscribe to provider-level errors: engine errors, bootstrap failures, and session issues. */
     subscribeError: (listener: (error: Error) => void) => () => void;
-    /** Fire an error to all subscribed listeners. Called internally by the provider. */
+    /** Emit an error to every subscribed listener. The provider calls this for you. */
     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.
+     * The typed `Ablo` client for this provider, or `null` until the first sync
+     * bootstrap resolves. It is held here so `useSync()` can return it without
+     * reaching into the store; the client and the store are sibling objects, and
+     * neither is derived from the 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.
+     * It is typed loosely as `Ablo<SchemaRecord>` because generics do not flow
+     * through React context. `useSync<R>()` restores the precise type through its
+     * own generic; the runtime value is the fully typed client.
      */
     engine: Ablo<SchemaRecord> | null;
 }

package/dist/react/useAblo.d.ts

@@ -3,11 +3,10 @@ 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
- * `Register` module 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.
+ * The app's resolved schema-record type. It reads your `Register` module
+ * augmentation when you declare one and falls back to the loose
+ * {@link SchemaRecord} otherwise, so `useAblo()` returns a fully typed client
+ * without you passing `<(typeof schema)['models']>` at every call site.
  */
 type DefaultModels = ResolveSchema extends {
     models: infer M;
@@ -16,48 +15,50 @@ type ModelClientSelector<R extends SchemaRecord, T, C> = (ablo: Ablo<R>) => Mode
 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 client has a newer row in the local pool.
+     * An initial row, usually from a server component or a route loader. The hook
+     * returns it until sync delivers a newer row for the same id.
      */
     readonly initial?: T;
 }
 export interface UseAbloModelResult<T> {
-    /** Current row for the id, or `initial` until the row has hydrated. */
+    /** The current row for the id, or `initial` until the row has synced. */
     readonly data: T | undefined;
-    /** Active work claims on this model row. */
+    /** The work claims currently held on this row by any participant. */
     readonly claims: readonly ModelClaim[];
-    /** Convenience flag for disabling UI while another participant is active. */
+    /** True while another participant holds a claim — handy for disabling UI. */
     readonly claimed: 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.
+ * Reads Ablo from inside an `<AbloProvider>` subtree. Called with no arguments
+ * it returns the typed client for use in callbacks and effects; called with a
+ * selector it subscribes the component to a reactive read — such as one
+ * `ablo.<model>` row — and re-renders when that read changes.
  *
- * Zero-arg when the consumer declares the `Register` global
- * augmentation (`declare module '@abloatai/ablo' { interface Register { Schema:
- * typeof schema } }`). The default generic resolves through
- * `ResolveSchema['models']` so call sites stay clean:
+ * You can call it with no type arguments once you declare the `Register` module
+ * augmentation (`declare module '@abloatai/ablo' { interface Register {
+ * Schema: typeof schema } }`); the default type then resolves through your
+ * schema's models, so call sites stay clean:
  *
  * ```ts
- * // With Register augmentation (recommended):
+ * // With the Register augmentation (recommended):
  * const ablo = useAblo();
  * if (!ablo) return <Loading />;
  * const doc = await ablo.documents.retrieve({ id }); // async server read
  *
- * // Reactive selector (sync local-graph snapshot):
+ * // Reactive selector (a synchronous local 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:
+ * // Without the augmentation, pass the schema as a type argument:
  * 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.
+ * The no-argument form returns `null` while the engine is still bootstrapping.
+ * Branch on `null` and render a loading state — or gate on `useSyncStatus()`
+ * reaching `'connected'` — before calling 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;

package/dist/react/useAblo.js

@@ -17,14 +17,15 @@ function readModelResult(engine, modelClient, id, initial) {
     return { data, claims, claimed: claims.length > 0 };
 }
 /**
- * Project a reactive read into the value `useReactive` caches and returns.
+ * Projects a reactive read into the value that `useReactive` caches and
+ * returns.
  *
- * For a `Model`, this MUST read the row's fields (via `toReactiveSnapshot`),
- * not return the bare instance: MobX tracks property access, so reading the
- * fields inside this tracked function is what subscribes the reaction to them —
- * and the fresh object identity lets `useReactive`'s equality detect an
- * in-place delta update. Returning `modelAsRow(value)` (the live instance, no
- * field read) is why `useAblo(a => a.x.get(id))` used to ignore remote edits.
+ * For a `Model`, this reads the row's fields through `toReactiveSnapshot`
+ * rather than returning the instance itself. Property access is what subscribes
+ * the reaction to those fields, so the read has to happen inside this tracked
+ * function; returning the live instance without reading its fields would leave
+ * the component blind to later edits. The fresh object it produces also lets
+ * `useReactive`'s equality check detect an in-place update.
  */
 function snapshotValue(value) {
     if (value instanceof Model) {
@@ -47,18 +48,19 @@ export function useAblo(modelOrSelect, id, options) {
         : typeof modelOrSelect === 'function'
             ? undefined
             : modelOrSelect;
-    // Claims live on a non-MobX event emitter (engine.claims), 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 claim stream would
-    // re-render + double-compute it on every claim/presence delta anywhere (a real
-    // storm during AI editing / live collaboration) for a value that can't change.
+    // Claims arrive through an event emitter (engine.claims), not through MobX, so
+    // the useReactive reactions below cannot track them; we bridge changes with a
+    // setState bump instead. Only the model-row form (`id !== undefined`) reads
+    // claims, so we subscribe only when `id` is set. The selector-only form never
+    // reads claims, and subscribing it to the workspace-wide claim stream would
+    // re-render and recompute it on every claim or presence change anywhere — a
+    // real storm during AI editing or live collaboration — for a value that cannot
+    // change.
     const [claimVersion, setClaimVersion] = useState(0);
     useEffect(() => {
         if (!engine || id === undefined)
             return;
-        return engine.claims.onChange(() => setClaimVersion((version) => version + 1));
+        return engine.claims.onChange(() => { setClaimVersion((version) => version + 1); });
     }, [engine, id]);
     const selected = useReactive(() => {
         if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {