@abloatai/ablo 0.11.1 → 0.12.0

package/dist/client/sessionMint.d.ts

@@ -0,0 +1,15 @@
+import type { SchemaRecord } from '../schema/schema.js';
+import type { AbloSession, CreateSessionParams } from './Ablo.js';
+/** The resolved control-plane context a mint needs. `fetch` is optional — the
+ *  auth helpers fall back to the runtime global when omitted. */
+export interface MintSessionContext {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Mint a session token from an already-resolved `sk_` credential + base URL.
+ * Discriminates the `{ user }` / `{ agent }` union onto the server's two mint
+ * doors and reshapes each flat response into the `AbloSession` resource.
+ */
+export declare function mintSession<S extends SchemaRecord>(params: CreateSessionParams<S>, ctx: MintSessionContext): Promise<AbloSession>;

package/dist/client/sessionMint.js

@@ -0,0 +1,86 @@
+/**
+ * `mintSession` — the ONE implementation behind `sessions.create`, shared by the
+ * stateful `Ablo` client and the stateless protocol / HTTP client so the two can
+ * never drift on HOW a token is minted.
+ *
+ * Minting is a pure control-plane HTTP call (no socket, no synced pool): a backend
+ * holding a secret `sk_` exchanges it for a short-lived scoped token — `ek_` for an
+ * `{ user }` session (full end-user authority) or `rk_` for an `{ agent }` session
+ * (scoped to exactly the operations named in `can`). The two arms map to the
+ * server's two mint doors:
+ *
+ *   `{ user }`  → POST /auth/ephemeral-keys → `ek_`. The user-session door;
+ *                 routing this arm through /auth/capability is structurally
+ *                 impossible — that route rejects participantKind 'user' outright
+ *                 (`invalid_participant_kind`, the 2026-06-11 Pulse cascade where
+ *                 the SDK's own blessed pattern 403'd and integrators fell back to
+ *                 minting humans as agents).
+ *   `{ agent }` → POST /auth/capability → scoped `rk_`. `can: { tasks: ['update'] }`
+ *                 serializes to the wire allowlist (`tasks.update`); the Hub matches
+ *                 it against every registered alias of the model.
+ *
+ * The caller supplies the resolved control-plane credential + base URL in `ctx`;
+ * WHICH key to use (the original `sk_`, never a derived `rk_` the startup exchange
+ * may have installed) is the caller's concern — see the two call sites.
+ *
+ * Type-only imports of `CreateSessionParams` / `AbloSession` keep this module a
+ * leaf (no runtime cycle back to `Ablo.ts`): at runtime it depends on `auth` +
+ * `schema` only.
+ */
+import { exchangeApiKey, mintUserSessionKey } from '../auth/index.js';
+/**
+ * Mint a session token from an already-resolved `sk_` credential + base URL.
+ * Discriminates the `{ user }` / `{ agent }` union onto the server's two mint
+ * doors and reshapes each flat response into the `AbloSession` resource.
+ */
+export async function mintSession(params, ctx) {
+    const { apiKey, baseUrl } = ctx;
+    if (params.user) {
+        const res = await mintUserSessionKey({
+            apiKey,
+            baseUrl,
+            userId: params.user.id,
+            ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
+            ttlSeconds: params.ttlSeconds ?? 900,
+            ...(ctx.fetch ? { fetch: ctx.fetch } : {}),
+        });
+        return {
+            object: 'session',
+            id: res.id,
+            token: res.token,
+            expiresAt: res.expiresAt,
+            organizationId: res.organizationId,
+            // The ephemeral mint stores scope on the key row; reshape its flat
+            // response into the session resource's scope block.
+            scope: {
+                organizationId: res.organizationId,
+                syncGroups: res.syncGroups,
+                operations: [],
+                participantKind: 'user',
+                participantId: res.participantId,
+            },
+            userMeta: params.userMeta ?? { id: res.participantId },
+        };
+    }
+    const operations = Object.entries(params.can).flatMap(([model, ops]) => (ops ?? []).map((op) => `${model.toLowerCase()}.${op}`));
+    const res = await exchangeApiKey({
+        apiKey,
+        baseUrl,
+        participantKind: 'agent',
+        participantId: params.agent.id,
+        ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
+        operations,
+        ttlSeconds: params.ttlSeconds ?? 900,
+        ...(params.userMeta ? { userMeta: params.userMeta } : {}),
+        ...(ctx.fetch ? { fetch: ctx.fetch } : {}),
+    });
+    return {
+        object: 'session',
+        id: res.capabilityId,
+        token: res.token,
+        expiresAt: res.expiresAt,
+        organizationId: res.organizationId,
+        scope: res.scope,
+        userMeta: res.userMeta,
+    };
+}

package/dist/coordination/schema.d.ts

@@ -281,7 +281,7 @@ export declare const modelClaimSchema: z.ZodReadonly<z.ZodObject<{
         agent: "agent";
         system: "system";
     }>>;
-    action: z.ZodString;
+    reason: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     field: z.ZodOptional<z.ZodString>;
     status: z.ZodOptional<z.ZodEnum<{

package/dist/coordination/schema.js

@@ -203,7 +203,9 @@ export const modelClaimSchema = z
     id: z.string(),
     actor: z.string(),
     participantKind: wireParticipantKindSchema,
-    action: z.string(),
+    /** Human-readable phase (`'editing'`). The public SDK field; the WS/HTTP
+     *  wire carries the same value as `action` (healed on read). */
+    reason: z.string(),
     description: z.string().optional(),
     field: z.string().optional(),
     status: z.enum(['active', 'queued']).optional(),

package/dist/errorCodes.d.ts

@@ -156,6 +156,7 @@ export declare const ERROR_CODES: {
     readonly model_claimed: ErrorCodeSpec;
     readonly model_claimed_timeout: ErrorCodeSpec;
     readonly model_claim_not_configured: ErrorCodeSpec;
+    readonly model_watch_not_configured: ErrorCodeSpec;
     readonly stale_context: ErrorCodeSpec;
     readonly idempotency_conflict: ErrorCodeSpec;
     readonly idempotency_key_too_long: ErrorCodeSpec;
@@ -195,6 +196,7 @@ export declare const ERROR_CODES: {
     readonly schema_scope_kind_invalid: ErrorCodeSpec;
     readonly schema_field_not_camelcase: ErrorCodeSpec;
     readonly schema_field_consecutive_caps: ErrorCodeSpec;
+    readonly schema_reserved_field: ErrorCodeSpec;
     readonly schema_grants_shape_invalid: ErrorCodeSpec;
     readonly schema_grants_identifier_unsafe: ErrorCodeSpec;
     readonly schema_grants_relation_kind: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -159,6 +159,7 @@ export const ERROR_CODES = {
     model_claimed: wire('claim', 409, false, 'The model instance is claimed by another participant.'),
     model_claimed_timeout: wire('claim', 409, false, 'Timed out waiting for a model claim to clear.'),
     model_claim_not_configured: client('claim', 'Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically — there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path).'),
+    model_watch_not_configured: client('claim', 'watch() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).'),
     // ── stale context / idempotency (409) ──────────────────────────────
     stale_context: wire('conflict', 409, true, 'The write carried a readAt watermark that is now stale; re-read and retry.'),
     idempotency_conflict: wire('conflict', 409, false, 'The same Idempotency-Key was reused with a different request body.'),
@@ -210,6 +211,7 @@ export const ERROR_CODES = {
     schema_scope_kind_invalid: wire('schema', 400, false, 'A scope kind in the schema is invalid.'),
     schema_field_not_camelcase: wire('schema', 400, false, 'A schema field name is not camelCase.'),
     schema_field_consecutive_caps: wire('schema', 400, false, 'A schema field name has consecutive capital letters.'),
+    schema_reserved_field: client('schema', 'A model redeclared a reserved base field (id, createdAt, updatedAt, organizationId, createdBy) that the SDK provides automatically.'),
     schema_grants_shape_invalid: wire('schema', 400, false, 'A grants declaration has an invalid shape.'),
     schema_grants_identifier_unsafe: wire('schema', 400, false, 'A grants declaration referenced an unsafe identifier.'),
     schema_grants_relation_kind: wire('schema', 400, false, 'A grants relation referenced an invalid kind.'),

package/dist/errors.d.ts

@@ -161,7 +161,9 @@ export interface ClaimContext {
     readonly claimId?: string;
     readonly actor?: string;
     readonly participantKind?: ParticipantKind;
-    readonly action?: string;
+    /** Human-readable phase the holder is in (`'editing'`). Matches the public
+     *  claim surface; the wire summary carries the same value as `action`. */
+    readonly reason?: string;
     readonly description?: string;
     readonly field?: string;
     readonly status?: string;
@@ -186,8 +188,9 @@ export declare function formatClaimedErrorMessage(args: {
  * The target entity is currently claimed by another participant and the caller
  * asked the SDK not to read/write through that claim.
  *
- * Use `ifClaimed: 'wait'` to wait for the claim to clear, or
- * `ifClaimed: 'return'` to inspect active claims yourself.
+ * Pass `ifClaimed: 'return'` to inspect active claims yourself instead of
+ * throwing; to wait for the claim to clear, take `ablo.<model>.claim({ id })`
+ * (it queues fairly) rather than blocking the read.
  */
 export declare class AbloClaimedError extends AbloError {
     readonly type: "AbloClaimedError";

package/dist/errors.js

@@ -162,7 +162,12 @@ export class AbloStaleContextError extends AbloError {
     }
 }
 function claimAction(claim) {
-    return claim?.action;
+    if (!claim)
+        return undefined;
+    // The public `ClaimContext` exposes the phase as `reason`; the wire
+    // `WireClaimSummary` projection still carries it under `action`. Read both.
+    const c = claim;
+    return c.reason ?? c.action;
 }
 function claimDescription(claim) {
     if (!claim)
@@ -208,8 +213,9 @@ export function formatClaimedErrorMessage(args) {
  * The target entity is currently claimed by another participant and the caller
  * asked the SDK not to read/write through that claim.
  *
- * Use `ifClaimed: 'wait'` to wait for the claim to clear, or
- * `ifClaimed: 'return'` to inspect active claims yourself.
+ * Pass `ifClaimed: 'return'` to inspect active claims yourself instead of
+ * throwing; to wait for the claim to clear, take `ablo.<model>.claim({ id })`
+ * (it queues fairly) rather than blocking the read.
  */
 export class AbloClaimedError extends AbloError {
     type = 'AbloClaimedError';

package/dist/index.d.ts

@@ -43,7 +43,6 @@
  * Advanced — opt-in, most apps never import these (each is tagged
  * "Advanced —" at its export below, with the one situation it's for):
  *   • `dataSource` / `abloSource`  — only if your own DB stays canonical
- *   • `session` / `agent`          — only for delegated agent principals
  *   • `defaultPolicy`              — only to customize conflict resolution
  *   • `defineMutators` / `createTransaction` — only for custom mutators
  * If you don't recognize one, you don't need it — the default path covers you.
@@ -51,11 +50,10 @@
 export { Ablo } from './client/Ablo.js';
 export type { MutationExecutor } from './interfaces/index.js';
 export type { HttpClaimApi, InternalAbloOptions } from './client/Ablo.js';
-export { createAbloHttpClient, type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
+export { type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
-export type { AbloOptions, ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './client/Ablo.js';
+export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './client/Ablo.js';
 export type { AbloPersistence } from './client/persistence.js';
-export { session, agent } from './principal.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
 export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
@@ -70,6 +68,8 @@ export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './cl
 export type { WriteOptionsInput } from './client/writeOptionsSchema.js';
 export type { WriteOptions, MutationOptions } from './interfaces/index.js';
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
+export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
+export type { ModelVerb, ListOptionKey, AbloOptionKey } from './surface.js';
 export type { Register, DefaultSyncShape } from './types/global.js';
 export { defineMutators } from './mutators/defineMutators.js';
 export { createTransaction, type Transaction } from './mutators/Transaction.js';

package/dist/index.js

@@ -43,7 +43,6 @@
  * Advanced — opt-in, most apps never import these (each is tagged
  * "Advanced —" at its export below, with the one situation it's for):
  *   • `dataSource` / `abloSource`  — only if your own DB stays canonical
- *   • `session` / `agent`          — only for delegated agent principals
  *   • `defaultPolicy`              — only to customize conflict resolution
  *   • `defineMutators` / `createTransaction` — only for custom mutators
  * If you don't recognize one, you don't need it — the default path covers you.
@@ -56,17 +55,11 @@
 // `import Ablo from '@abloatai/ablo'` works; named export so
 // `import { Ablo }` also compiles.
 export { Ablo } from './client/Ablo.js';
-export { createAbloHttpClient, } from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
 // Participant types live under `Ablo.Participant.*` —
 // `Ablo.Participant.Joined`, `Ablo.Participant.Manager`,
 // `Ablo.Participant.JoinOptions`, etc. Same dot-access shape as
 // `Ablo.Peer`, `Ablo.Claim`. No flat re-exports.
-// Advanced — most apps never import this. Principal constructors for
-// delegated agent paths (`Ablo({ kind: 'agent', as: session({...}) })`).
-// The default `Ablo({ schema, apiKey })` resolves identity from the key;
-// reach for these only when minting a delegated agent principal.
-export { session, agent } from './principal.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
 // Advanced — most apps never import this. Customer-owned storage adapter
@@ -100,6 +93,10 @@ export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './cl
 // Storage-wedge detection — lets app shells render a recovery screen when the
 // IndexedDB backing store is stuck (see core/openIDBWithTimeout.ts).
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
+// Machine-checked surface manifest — the SDK's own description of its public
+// verb/option names, compile-time-bound to the real types (see surface.ts).
+// The MCP `get_api_surface` imports these so docs can't name a phantom verb.
+export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
 // Advanced — most apps never import this. Custom (Zero-style) mutators:
 // `ablo.<model>.create/update/delete` already covers normal writes. Reach
 // for `defineMutators` only when you need a named, multi-step mutation with

package/dist/mutators/RecordingTransaction.js

@@ -59,55 +59,27 @@ function wrapMutateForKey(modelKey, mutate, store, inverses, forwards) {
         // wider shape is exactly right.
         return model.toJSON();
     };
+    // Before-image for the undo inverse. Delegates to `Model.capturePreviousValues`
+    // — the SINGLE shared implementation (the stream path's
+    // `TransactionQueue.extractPreviousData` calls the same method). `fallbackToLive`
+    // is ON here: the manual-record path wants the live value as a last resort for
+    // a field that was neither pre-mutated nor in the original snapshot. (The
+    // stream path passes `false` so it can omit-and-drop instead — that flag is
+    // the one intentional difference between the two callers.)
     const snapshotFields = (id, fieldNames) => {
         const model = store.pool.get(id);
         if (!model)
             return null;
-        const out = {};
-        // `modifiedProperties` is populated by M1's `observe()` listener the
-        // moment the caller mutates an observable field directly. Thanks to
-        // `Model.propertyChanged`'s first-old-wins policy, `.old` holds the TRUE
-        // pre-session baseline even after many in-place mutations (e.g. a drag
-        // frame loop). That makes it the authoritative source for the undo
-        // inverse when the caller pre-mutates before invoking the mutator.
-        //
-        // Fallback chain for models/fields that weren't pre-mutated (so no
-        // `modifiedProperties` entry exists yet): `getOriginalSnapshot()`
-        // (populated on load/`markAsPersisted`/sync-ack), then the live
-        // observable. The live read is correct only when the caller didn't
-        // touch the field first.
-        const original = model.getOriginalSnapshot();
-        for (const f of fieldNames) {
-            if (f === 'id')
-                continue;
-            const mod = model.modifiedProperties.get(f);
-            if (mod) {
-                out[f] = mod.old;
-            }
-            else if (original && f in original) {
-                out[f] = original[f];
-            }
-            else {
-                out[f] = Reflect.get(model, f);
-            }
-        }
-        return out;
+        return model.capturePreviousValues(fieldNames, { fallbackToLive: true });
     };
     // After a mutator's `base.update` succeeds, drop the `modifiedProperties`
-    // entries we snapshotted from. The next mutator call should see THIS
-    // update's result as its baseline, not the pre-session old value. The
-    // transaction queue already captured its frozen copy synchronously inside
-    // `store.save` (via `captureModelChanges`/`extractPreviousData`), so this
-    // clear is safe for server rollback.
+    // entries we snapshotted from so the next mutator call sees THIS update's
+    // result as its baseline, not the pre-session old value. The transaction
+    // queue already captured its frozen copy synchronously inside `store.save`,
+    // so this clear is safe for server rollback. Shared with the stream path via
+    // `Model.consumeModifiedFields`.
     const consumeModifiedFields = (id, fieldNames) => {
-        const model = store.pool.get(id);
-        if (!model)
-            return;
-        for (const f of fieldNames) {
-            if (f === 'id')
-                continue;
-            model.modifiedProperties.delete(f);
-        }
+        store.pool.get(id)?.consumeModifiedFields(fieldNames);
     };
     return {
         // Overloaded — single row or array. The recorder dispatches the

package/dist/react/AbloProvider.d.ts

@@ -15,7 +15,7 @@ import { type SyncStoreContract } from './context.js';
  *   - **One component, one import.** Consumers write the provider
  *     once at the root; nothing else needs to plumb the engine.
  *   - **Multiplayer is default.** React consumers are always browsers doing
- *     multiplayer UI, so `useParticipant()` / `useAblo()` are always
+ *     multiplayer UI, so `useWatch()` / `useAblo()` are always
  *     available. No opt-in prop.
  *   - **Declarative props for app glue.** `preventUnsavedChanges`,
  *     `onSessionExpired`, `postBootstrap`, `resolveUsers` — each
@@ -36,7 +36,7 @@ import { type SyncStoreContract } from './context.js';
  * // Build once at module scope — a new instance per render tears down the socket.
  * const ablo = Ablo({
  *   schema,
- *   getToken: () =>
+ *   apiKey: () =>
  *     fetch('/api/ablo-session', { method: 'POST' })
  *       .then((r) => r.json())
  *       .then((d) => d.token),
@@ -114,18 +114,13 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
 export declare function AbloProvider<R extends SchemaRecord = SchemaRecord>(props: AbloProviderProps<R>): React.ReactElement;
 export type { EngineParticipant, ParticipantScope, ParticipantStatus };
 /**
- * Options for `useParticipant`. The hook reuses the engine's single
+ * Options for `useWatch`. The hook reuses the engine's single
  * WebSocket and opens a scoped claim on it when `scope` is provided:
  * one TCP connection, N logical sub-syncgroup participants.
  */
-export interface UseParticipantOptions {
+export interface UseWatchOptions {
     readonly scope?: ParticipantScope;
-    readonly label?: string;
-    readonly as?: unknown;
     readonly ttlSeconds?: number | string | null;
-    readonly agent?: unknown;
-    readonly idempotencyKey?: string | null;
-    readonly autoRefreshThresholdSeconds?: number | null;
     /** Tear down + don't re-join while true. */
     readonly paused?: boolean;
     /**
@@ -154,7 +149,7 @@ export interface UseParticipantOptions {
 }
 /** @deprecated Use `ParticipantStatus`. */
 export type MeshParticipantStatus = ParticipantStatus;
-export interface UseParticipantReturn {
+export interface UseWatchReturn {
     readonly participant: EngineParticipant | null;
     /** Everyone else on the engine's sync groups (`participant.presence.others`), bridged to React. */
     readonly peers: ReadonlyArray<Peer>;
@@ -168,15 +163,19 @@ export interface UseParticipantReturn {
  * lifecycle status. Auto-cleans up on unmount or when `paused`
  * flips to true.
  *
+ * `useWatch` is the React form of `ablo.<model>.watch` — scope-level
+ * read-interest + presence; returns the reactive participant facade
+ * (peers/claims/status).
+ *
  * The returned `participant` is an `EngineParticipant` — `.presence`
  * + `.claims` only — backed by the engine's existing socket. For
  * headless-bot patterns (a separate identity in the same browser
  * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
  */
-export declare function useParticipant(opts: UseParticipantOptions): UseParticipantReturn;
+export declare function useWatch(opts: UseWatchOptions): UseWatchReturn;
 /**
  * Read-only presence: the OTHER participants currently visible to this
- * connection, bridged to React. Unlike {@link useParticipant}, this does
+ * connection, bridged to React. Unlike {@link useWatch}, this does
  * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
  * it is a pure reader of the engine's already-flowing presence stream.
  *
@@ -189,7 +188,7 @@ export declare function useParticipant(opts: UseParticipantOptions): UseParticip
  * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
  * broadcasts while alone — when some OTHER mount already owns the scope's
  * read interest (scope `leave` is not reference-counted, so a second
- * `useParticipant` on the same scope would warm-drop the owner's
+ * `useWatch` on the same scope would warm-drop the owner's
  * subscription on unmount).
  *
  * ```ts

package/dist/react/AbloProvider.js

@@ -36,7 +36,7 @@ export function AbloProvider(props) {
     // REACTIVE binding over it (context + bootstrap gate + error/session
     // forwarding); it does NOT construct, configure, or own the connection. The
     // client owns auth, the credential lifecycle (first mint, refresh, and
-    // wake/online/focus re-mint — see `Ablo({ getToken })`), transport, and
+    // wake/online/focus re-mint — see `Ablo({ apiKey })`), transport, and
     // `dispose()`. The CONSUMER built the client, so the consumer owns teardown;
     // the provider never disposes it.
     const engine = client;
@@ -204,12 +204,16 @@ const EMPTY_INTENTS = Object.freeze([]);
  * lifecycle status. Auto-cleans up on unmount or when `paused`
  * flips to true.
  *
+ * `useWatch` is the React form of `ablo.<model>.watch` — scope-level
+ * read-interest + presence; returns the reactive participant facade
+ * (peers/claims/status).
+ *
  * The returned `participant` is an `EngineParticipant` — `.presence`
  * + `.claims` only — backed by the engine's existing socket. For
  * headless-bot patterns (a separate identity in the same browser
  * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
  */
-export function useParticipant(opts) {
+export function useWatch(opts) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
     const { paused = false } = opts;
@@ -338,15 +342,11 @@ export function useParticipant(opts) {
             unsubClaims();
         };
     }, [participant, paused]);
-    // `opts.as`, `opts.agent`, `opts.idempotencyKey`, and
-    // `opts.autoRefreshThresholdSeconds` remain migration placeholders
-    // for future capability-mint/attenuation wiring. `scope` is already
-    // active: it opens a multiplexed claim on the engine WebSocket.
     return { participant, peers, claims, status, error };
 }
 /**
  * Read-only presence: the OTHER participants currently visible to this
- * connection, bridged to React. Unlike {@link useParticipant}, this does
+ * connection, bridged to React. Unlike {@link useWatch}, this does
  * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
  * it is a pure reader of the engine's already-flowing presence stream.
  *
@@ -359,7 +359,7 @@ export function useParticipant(opts) {
  * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
  * broadcasts while alone — when some OTHER mount already owns the scope's
  * read interest (scope `leave` is not reference-counted, so a second
- * `useParticipant` on the same scope would warm-drop the owner's
+ * `useWatch` on the same scope would warm-drop the owner's
  * subscription on unmount).
  *
  * ```ts
@@ -370,7 +370,7 @@ export function useParticipant(opts) {
 export function usePeers(scope) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
-    // Resolve scope → groups through the schema (same idiom as useParticipant).
+    // Resolve scope → groups through the schema (same idiom as useWatch).
     // The stringified, sorted key is the stable effect dependency.
     const scopeKey = JSON.stringify(resolveParticipantSyncGroups(scope, engine?.schema).sort());
     const groups = useMemo(() => JSON.parse(scopeKey), [scopeKey]);
@@ -387,7 +387,7 @@ export function usePeers(scope) {
         // Plain useState + onChange — presence changes on join/leave/activity
         // only (never on cursor traffic, a separate channel), so this fires
         // rarely; a frame of stale presence is harmless (same rationale as
-        // useParticipant's peers bridge).
+        // useWatch's peers bridge).
         setPeers(compute());
         return presence.onChange(() => setPeers(compute()));
     }, [engine, scopeKey]);

package/dist/react/context.d.ts

@@ -137,29 +137,12 @@ export interface SyncReactContext {
      * 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 Register { 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 claim initiator. Same pattern as presence — consumers
-     * plug a function that turns an claim claim into a handle they
-     * control (WebSocket send, optimistic local update, whatever).
-     * `useClaim(name)` returns a typed invoker for the named claim
-     * from `interface Register { Claims: ... }`.
-     */
-    beginClaim?: (claimName: 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.
+ * 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.
  */
 export declare function useSyncContext(): SyncReactContext;
 /**
@@ -177,33 +160,15 @@ export interface SyncProviderProps {
      * 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 claim initiator for `useClaim()`. See
-     * {@link SyncReactContext.beginClaim}.
-     */
-    beginClaim?: (claimName: 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 '@abloatai/ablo/react';
+ * SyncProvider — the INTERNAL low-level provider that wires a built sync store
+ * into React so SDK hooks (useModel, useModels, useMutations) can reach it.
  *
- * function App() {
- *   return (
- *     <SyncProvider store={syncStore} organizationId={orgId}>
- *       <YourApp />
- *     </SyncProvider>
- *   );
- * }
+ * 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>`.
  */
-export declare function SyncProvider({ store, organizationId, schema, presence, beginClaim, children, }: SyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SyncReactContext | null>>;
+export declare function SyncProvider({ store, organizationId, schema, children, }: SyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SyncReactContext | null>>;

package/dist/react/context.js

@@ -3,33 +3,28 @@ 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.
+ * 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.
  */
 export function useSyncContext() {
     const ctx = useContext(SyncContext);
     if (!ctx) {
-        throw new AbloValidationError('useSyncContext must be used within a SyncProvider', {
+        throw new AbloValidationError('Sync hooks must be used within an <AbloProvider>.', {
             code: 'sync_context_missing_provider',
         });
     }
     return ctx;
 }
 /**
- * SyncProvider wires the sync store into React so SDK hooks
- * (useModel, useModels, useMutations) can access it.
+ * SyncProvider — the INTERNAL low-level provider that wires a built sync store
+ * into React so SDK hooks (useModel, useModels, useMutations) can reach it.
  *
- * @example
- * import { SyncProvider } from '@abloatai/ablo/react';
- *
- * function App() {
- *   return (
- *     <SyncProvider store={syncStore} organizationId={orgId}>
- *       <YourApp />
- *     </SyncProvider>
- *   );
- * }
+ * 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>`.
  */
-export function SyncProvider({ store, organizationId, schema, presence, beginClaim, children, }) {
-    return createElement(SyncContext.Provider, { value: { store, organizationId, schema, presence, beginClaim } }, children);
+export function SyncProvider({ store, organizationId, schema, children, }) {
+    return createElement(SyncContext.Provider, { value: { store, organizationId, schema } }, children);
 }