@abloatai/ablo 0.26.0 → 0.28.0

package/dist/query/client.js

@@ -1,15 +1,15 @@
 /**
- * HTTP client for the generic /sync/query endpoint.
+ * The HTTP client for the sync query endpoint.
  *
- * Thin wrapper over fetch() that:
- *   - POSTs a QueryBatch as JSON
- *   - Sends the bearer credential via withAuthHeaders (Authorization header)
- *   - Throws on non-2xx responses
- *   - Parses the response into a typed QueryBatchResult
+ * {@link postQuery} is a small wrapper over `fetch` that POSTs a
+ * {@link QueryBatch} as JSON to `/sync/query`, attaches the bearer credential
+ * as an `Authorization` header, and parses the response into a typed
+ * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
+ * every query in the batch comes back with an empty result, so a
+ * fire-and-forget caller cannot crash on an unhandled rejection.
  *
- * The higher-level BootstrapHelper methods (fetchDeckSlideLayers,
- * fetchChatMessages, etc.) use this to issue structured queries
- * without duplicating the fetch boilerplate.
+ * Higher-level query helpers build on this to issue structured queries without
+ * repeating the fetch and error-handling boilerplate.
  */
 import { z } from 'zod';
 import { translateHttpError } from '../errors.js';
@@ -18,12 +18,11 @@ import { withAuthHeaders } from '../auth/credentialSource.js';
 import { getContext } from '../context.js';
 // ── Response validation ─────────────────────────────────────────────────
 //
-// Each result slot is an array of rows (or an object for bundled
-// responses). Server-side per-query failures surface here as `[]`, but
-// the server logs them via `console.error('[query.error] ...')` — alert
-// on that prefix, not on emptiness. Parsing through Zod normalizes
-// `null` slots into empty arrays so downstream callers never see raw
-// null.
+// Each result slot is an array of rows, or an object for a bundled response.
+// A per-query failure on the server surfaces here as an empty array rather
+// than an error, so emptiness alone does not distinguish "no rows" from
+// "the query failed." Parsing through Zod normalizes a `null` slot into an
+// empty array, so callers never receive a raw null.
 const QueryResultSchema = z
     .union([z.array(z.unknown()), z.record(z.string(), z.unknown()), z.null()])
     .transform((val) => {
@@ -37,20 +36,24 @@ const QueryBatchResultSchema = z
 })
     .passthrough();
 /**
- * POST a batch of queries to /sync/query. Returns the parsed
- * QueryBatchResult. Throws a descriptive error on HTTP failure.
+ * Sends a batch of queries to `/sync/query` and returns the parsed
+ * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
+ * every query in the batch comes back with an empty result, which keeps a
+ * fire-and-forget caller from crashing on an unhandled rejection. A 401 may
+ * first be handed to {@link PostQueryOptions.recoverCredential} for a single
+ * retry.
  *
- * The server guarantees results[i] corresponds to queries[i] in the
- * request — callers can rely on index alignment to extract typed
- * results from a multi-query batch.
+ * The response preserves order: `results[i]` corresponds to the query at
+ * `queries[i]`, so callers can rely on index alignment to pull typed results
+ * out of a multi-query batch.
  */
 export async function postQuery(options, batch) {
     const url = `${options.baseUrl}/sync/query`;
     const timeout = options.fetchTimeout ?? 30_000;
-    // At most TWO attempts: the original request, plus ONE replay after a
-    // successful credential recovery (see `recoverCredential`). Bounded by
-    // construction — a second auth rejection falls through to the log+empty
-    // path, so a wedged credential can never retry-loop.
+    // At most two attempts: the original request, plus one replay after a
+    // successful credential recovery (see `recoverCredential`). A second auth
+    // rejection falls through to the log-and-empty path, so a wedged credential
+    // can never retry-loop.
     for (let attempt = 0;; attempt++) {
         // Race the fetch against a timeout so hung requests don't block
         // the calling helper indefinitely. Fresh controller per attempt.
@@ -67,13 +70,13 @@ export async function postQuery(options, batch) {
                 signal: controller.signal,
             });
             if (!response.ok) {
-                // Build the typed AbloError for this HTTP failure (same code→class
-                // map the throwing paths use) so the log is tagged + carries a
-                // registry `code` (e.g. AbloAuthenticationError/session_expired on a
-                // 401) instead of a bare status. We deliberately DON'T throw —
-                // fire-and-forget callers would kill the Next.js router on an
-                // unhandled rejection — and still return empty slots, but the failure
-                // is now legible as an Ablo error.
+                // Build the typed AbloError for this HTTP failure (the same
+                // code-to-class map the throwing paths use) so the log carries a
+                // registry `code` — for example an authentication error with
+                // `session_expired` on a 401 — rather than a bare status. This path
+                // deliberately does not throw, since a fire-and-forget caller could
+                // crash on an unhandled rejection. It returns empty slots while still
+                // logging a legible Ablo error.
                 let body = null;
                 try {
                     body = await response.clone().json();
@@ -82,13 +85,12 @@ export async function postQuery(options, batch) {
                     // non-JSON error page — translateHttpError falls back to status text
                 }
                 const err = translateHttpError(response.status, body);
-                // 401 → hand the failure to the auth-recovery backbone, ONCE. The
-                // class routes the decision: `access_credential_expiry` re-mints
-                // silently and replays; `session_expiry` reports terminal session
-                // loss (sign-out is the FSM's call, not ours); everything else stops.
-                // A bare 401 with no readable code is classified as an expired access
-                // key — the NetworkProbe precedent: the only terminal path is the
-                // re-mint itself resolving null, never an ambiguous status.
+                // On a 401, hand the failure to the recovery hook once. The recovery
+                // class routes the outcome: an expired access credential is re-minted
+                // and the request replays; a lost session is terminal and stops here;
+                // anything else stops. A bare 401 with no readable code is treated as
+                // an expired access credential, so the only terminal path is the
+                // re-mint itself coming back empty, never an ambiguous status.
                 if (attempt === 0 && response.status === 401 && options.recoverCredential) {
                     const recovery = typeof err.code === 'string'
                         ? classifyRecovery(err.code)
@@ -101,11 +103,11 @@ export async function postQuery(options, batch) {
                         continue;
                     }
                 }
-                // Routed through the gated logger so it obeys ABLO_LOG_LEVEL like
-                // everything else: a consumer-register `warn` (their models + the
-                // typed message + a wire `code`) with the forensics on a `debug`
-                // companion. Actionable and not self-healing — the read returns
-                // empty until the underlying cause (auth, network) is resolved.
+                // Logged through the level-gated logger, so it honors ABLO_LOG_LEVEL:
+                // a `warn` line the app developer can read (the models, the typed
+                // message, and a wire `code`), with the forensic detail on a companion
+                // `debug` line. The read stays empty until the underlying cause, such
+                // as auth or network, is resolved.
                 const models = batch.queries.map((q) => q.model).join(', ');
                 getContext().logger.warn(`Could not load ${models} — ${err.message} (code: ${err.code ?? response.status}). No results were returned.`);
                 getContext().logger.debug('[postQuery.error] query http failure', {

package/dist/query/types.d.ts

@@ -1,44 +1,25 @@
 /**
- * Structured query types for the generic /sync/query endpoint.
+ * Structured query types for the `/sync/query` endpoint.
  *
- * Zero-shaped ZQL-ish wire format: `where` is a flat list of `[col, op, val]`
- * tuples (AND'd together), and `related` is a list of schema-declared
- * relation names to traverse. The server compiler reads the schema's
- * relation metadata to turn `related: ['layers']` into the right JOIN.
+ * A query describes a filtered read in a compact wire format. `where` is a flat
+ * list of `[column, operator, value]` conditions combined with AND, and
+ * `related` names the schema relations to fetch alongside each row. The server
+ * compiles a query against your schema: it reads the model's relation metadata
+ * to turn `related: ['layers']` into the right join, and turns each condition
+ * into a WHERE fragment. The protocol carries no model-specific logic, so
+ * adding a model or relation is a schema change rather than a server change.
  *
- * # Why this shape
- *
- * An earlier revision used equality-only `where: Record<string, unknown>`
- * plus a PK-only `ids: string[]` batch field. That worked for simple cases
- * but collapsed on two real workloads:
- *
- *   1. "Fetch all layers for these slide IDs" — the IDs are foreign keys
- *      (`SlideLayer.slideId`), not primary keys. The old `ids` field
- *      filtered on `id`, silently returning empty.
- *
- *   2. "Fetch all layers for this deck" — needs a JOIN through
- *      `slides.deck_id → slide_layers.slide_id`. Equality-only `where` had
- *      no way to express it, so the Go server hardcoded a dispatch case.
- *
- * Both are generic patterns ("batch by FK column", "filter via relation")
- * that should be first-class in the protocol, not model-specific escape
- * hatches on the server. This shape matches Zero's ZQL:
- *
- *   - `where('slideId', 'IN', ids)` → `['slideId', 'IN', ids]`
- *   - `.related('layers')` → `related: ['layers']`
- *
- * The server's compiler stays schema-driven: given a model name, it reads
- * the schema's declared relations to emit JOIN SQL, and given a `[col, op,
- * val]` tuple it emits a WHERE fragment — never a switch on specific model
- * names. Adding a new model or relation is a schema change, not a server
- * change.
+ * The `IN` operator lets you batch a read by any column, including a foreign
+ * key — for example, fetching every layer whose `slideId` falls in a set of
+ * ids.
  */
 /** Primitive operand types allowed in a where clause. */
 export type WherePrimitive = string | number | boolean | null;
 /**
- * Comparison operators. Mirrors Zero's ZQL set so client authors can
- * lean on familiar semantics and server compilers that already target
- * ZQL stay portable.
+ * The comparison operators a {@link WhereClause} may use: equality and
+ * inequality, ordering, set membership (`IN` / `NOT IN`), null checks
+ * (`IS` / `IS NOT`), and case-sensitive or case-insensitive pattern
+ * matching (`LIKE`, `ILIKE`, and their negations).
  */
 export type WhereOp = '=' | '!=' | '<' | '<=' | '>' | '>=' | 'IN' | 'NOT IN' | 'IS' | 'IS NOT' | 'LIKE' | 'NOT LIKE' | 'ILIKE' | 'NOT ILIKE';
 /**
@@ -77,20 +58,17 @@ export interface Query {
      */
     model: string;
     /**
-     * List of where clauses AND'd together. Empty or omitted means "no
-     * filter" (still subject to server-side org scoping).
-     *
-     * Use `['col', 'IN', values]` to batch by any column — the old
-     * primary-key-only `ids` field is subsumed by this form.
+     * The conditions to filter by, combined with AND. Empty or omitted returns
+     * every row the caller may see; reads are still scoped to the caller's
+     * organization on the server. Use `['col', 'IN', values]` to batch a read by
+     * any column.
      */
     where?: readonly WhereClause[];
     /**
-     * Relation names declared in the schema for this model. The server's
-     * compiler resolves each name via the schema's relation metadata
-     * (`relation.hasMany` / `relation.belongsTo`) and emits the JOIN
-     * SQL — no model-specific dispatch on the server.
-     *
-     * Results come back as nested objects under the relation key:
+     * The relations to fetch with each row, named as they are declared on this
+     * model in the schema. The server resolves each name from the schema's
+     * relation metadata and joins the related rows in. They come back nested
+     * under the relation key:
      *
      *   { __typename: 'Slide', id: '…', layers: [{ __typename: 'SlideLayer', … }] }
      */
@@ -119,25 +97,24 @@ export interface QueryBatch {
 /** Response body from POST /sync/query. */
 export interface QueryBatchResult {
     /**
-     * Per-query results in request order. `results[i]` corresponds to
-     * `queries[i]`. Each element is an array of rows for array-shaped
-     * queries, or a bundled object for providers that return multiple
-     * collections under named keys.
-     *
-     * Each row carries `__typename` for client-side model dispatch, plus
-     * any `related` keys nested under the row.
+     * The result of each query, in request order: `results[i]` corresponds to
+     * `queries[i]`. Each element is an array of rows, or an object bundling
+     * several named row collections when the source returns more than one. Every
+     * row carries a `__typename` field naming its model, so callers can dispatch
+     * on it, along with any requested `related` rows nested under their relation
+     * key.
      *
-     * Failed queries surface as empty arrays. The server logs them via
-     * `console.error('[query.error] ...')` — alert on that prefix rather
-     * than trying to infer failure from empty results. A tagged-union
-     * wire shape that forces caller acknowledgement is the right next
-     * step once every `postQuery` consumer is updated at once.
+     * A query that fails on the server comes back as an empty array, which is
+     * indistinguishable from a query that simply matched nothing — treat an empty
+     * result as "no rows", not as proof the query succeeded. The element type is
+     * `unknown` because one batch can mix row shapes, so narrow each result
+     * before use.
      */
     results: unknown[];
     /**
-     * Server watermark observed after the batch ran. Public model reads
-     * expose this as `stamp` and callers thread it into `commits.create({
-     * readAt })` to reject stale writes.
+     * The server watermark observed after the batch ran. Model reads expose this
+     * as `stamp`, and callers thread it into `commits.create({ readAt })` so the
+     * server can reject a write built on stale data.
      */
     lastSyncId?: number;
 }

package/dist/query/types.js

@@ -1,36 +1,16 @@
 /**
- * Structured query types for the generic /sync/query endpoint.
- *
- * Zero-shaped ZQL-ish wire format: `where` is a flat list of `[col, op, val]`
- * tuples (AND'd together), and `related` is a list of schema-declared
- * relation names to traverse. The server compiler reads the schema's
- * relation metadata to turn `related: ['layers']` into the right JOIN.
- *
- * # Why this shape
- *
- * An earlier revision used equality-only `where: Record<string, unknown>`
- * plus a PK-only `ids: string[]` batch field. That worked for simple cases
- * but collapsed on two real workloads:
- *
- *   1. "Fetch all layers for these slide IDs" — the IDs are foreign keys
- *      (`SlideLayer.slideId`), not primary keys. The old `ids` field
- *      filtered on `id`, silently returning empty.
- *
- *   2. "Fetch all layers for this deck" — needs a JOIN through
- *      `slides.deck_id → slide_layers.slide_id`. Equality-only `where` had
- *      no way to express it, so the Go server hardcoded a dispatch case.
- *
- * Both are generic patterns ("batch by FK column", "filter via relation")
- * that should be first-class in the protocol, not model-specific escape
- * hatches on the server. This shape matches Zero's ZQL:
- *
- *   - `where('slideId', 'IN', ids)` → `['slideId', 'IN', ids]`
- *   - `.related('layers')` → `related: ['layers']`
- *
- * The server's compiler stays schema-driven: given a model name, it reads
- * the schema's declared relations to emit JOIN SQL, and given a `[col, op,
- * val]` tuple it emits a WHERE fragment — never a switch on specific model
- * names. Adding a new model or relation is a schema change, not a server
- * change.
+ * Structured query types for the `/sync/query` endpoint.
+ *
+ * A query describes a filtered read in a compact wire format. `where` is a flat
+ * list of `[column, operator, value]` conditions combined with AND, and
+ * `related` names the schema relations to fetch alongside each row. The server
+ * compiles a query against your schema: it reads the model's relation metadata
+ * to turn `related: ['layers']` into the right join, and turns each condition
+ * into a WHERE fragment. The protocol carries no model-specific logic, so
+ * adding a model or relation is a schema change rather than a server change.
+ *
+ * The `IN` operator lets you batch a read by any column, including a foreign
+ * key — for example, fetching every layer whose `slideId` falls in a set of
+ * ids.
  */
 export {};

package/dist/react/AbloProvider.d.ts

@@ -213,7 +213,7 @@ export declare function useSync<R extends SchemaRecord = SchemaRecord>(): Ablo<R
 /**
  * Returns the underlying `SyncStoreContract` (the BaseSyncedStore).
  * Most consumers should prefer the typed hooks (`useQuery` etc.); this
- * is for advanced cases like direct ObjectPool access or custom
+ * is for advanced cases like direct InstanceCache access or custom
  * reactive bridges. Throws if the provider hasn't mounted the store
  * yet — wrap consumers in `<ClientSideSuspense>` to gate correctly.
  *

package/dist/react/AbloProvider.js

@@ -266,7 +266,7 @@ export function useWatch(opts) {
     // Subscribe the connection to the scope's sync groups while mounted +
     // connected — the area-of-interest navigation primitive. No claim, no
     // TTL: a viewer just receives the scope's deltas. Hysteresis (warm TTL)
-    // lives in the store's AreaOfInterestManager, so a quick unmount/remount
+    // lives in the store's SubscriptionManager, so a quick unmount/remount
     // (tab flip) doesn't re-bootstrap.
     useEffect(() => {
         const scope = opts.scope;
@@ -431,7 +431,7 @@ export function useSync() {
 /**
  * Returns the underlying `SyncStoreContract` (the BaseSyncedStore).
  * Most consumers should prefer the typed hooks (`useQuery` etc.); this
- * is for advanced cases like direct ObjectPool access or custom
+ * is for advanced cases like direct InstanceCache access or custom
  * reactive bridges. Throws if the provider hasn't mounted the store
  * yet — wrap consumers in `<ClientSideSuspense>` to gate correctly.
  *

package/dist/react/context.d.ts

@@ -4,55 +4,52 @@ 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';