@abloatai/ablo 0.10.1 → 0.11.0

package/dist/errors.js

@@ -20,6 +20,7 @@
  */
 import { z } from 'zod';
 import { errorCodeSpec, classifyRecovery } from './errorCodes.js';
+import { wireClaimSummarySchema, descriptionFromMeta, } from './coordination/schema.js';
 export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errorCodes.js';
 // ── AbloError hierarchy — the typed error surface ────────────────────
 /** Common shape for all errors thrown by this SDK. */
@@ -160,6 +161,49 @@ export class AbloStaleContextError extends AbloError {
             this.conflicts = options.conflicts;
     }
 }
+function claimAction(claim) {
+    return claim?.action;
+}
+function claimDescription(claim) {
+    if (!claim)
+        return undefined;
+    if ('description' in claim && typeof claim.description === 'string') {
+        return claim.description;
+    }
+    const meta = 'target' in claim ? claim.target?.meta ?? claim.meta : claim.meta;
+    return descriptionFromMeta(meta);
+}
+function claimExpiresAt(claim) {
+    return claim?.expiresAt;
+}
+function claimActor(claim, fallback) {
+    if (claim && 'actor' in claim && typeof claim.actor === 'string') {
+        return claim.actor;
+    }
+    return fallback;
+}
+function secondsUntil(ms, now = Date.now()) {
+    if (ms === undefined || !Number.isFinite(ms))
+        return undefined;
+    return Math.max(0, Math.ceil((ms - now) / 1000));
+}
+export function formatClaimedErrorMessage(args) {
+    const holder = claimActor(args.claim, args.heldBy);
+    const action = claimAction(args.claim);
+    const description = claimDescription(args.claim);
+    const expiresIn = secondsUntil(claimExpiresAt(args.claim));
+    if (!holder && !action && !description) {
+        return args.fallback ?? `Model row is claimed: ${args.targetLabel}.`;
+    }
+    const actor = holder ?? 'another participant';
+    const actionPart = action ? ` (${action})` : '';
+    const descriptionPart = description ? `: ${description}` : '';
+    const expiresPart = expiresIn !== undefined ? ` - expires in ${expiresIn}s` : '';
+    const policyPart = args.policyReason
+        ? ` Policy reason: ${args.policyReason}.`
+        : '';
+    return `Claimed by ${actor}${actionPart}${descriptionPart}${expiresPart} on ${args.targetLabel}.${policyPart}`;
+}
 /**
  * The target entity is currently claimed by another participant and the caller
  * asked the SDK not to read/write through that claim.
@@ -176,6 +220,30 @@ export class AbloClaimedError extends AbloError {
             this.claims = options.claims;
     }
 }
+/**
+ * The `/`-joined human label for a claim target — `model/id/field`, dropping
+ * absent parts, falling back to `'target'`. The one place this join lived in
+ * three copies (client `Ablo`, HTTP `ApiClient`, `awaitClaimGrant`).
+ */
+export function claimTargetLabel(target) {
+    return [target.model, target.id, target.field].filter(Boolean).join('/') || 'target';
+}
+/**
+ * Build the {@link AbloClaimedError} for a contended `ablo.<model>` write — the
+ * single factory shared by the realtime client (`Ablo`) and the HTTP client
+ * (`ApiClient`), which carried byte-identical copies. The first claim is the
+ * holder whose metadata shapes the message.
+ */
+export function claimedError(target, claims, code) {
+    const label = claimTargetLabel(target);
+    const holder = claims[0];
+    return new AbloClaimedError(formatClaimedErrorMessage({
+        targetLabel: label,
+        heldBy: holder?.actor,
+        claim: holder,
+        fallback: `Model row is claimed: ${label} held by another participant.`,
+    }), { code, claims });
+}
 /**
  * A scoped credential was denied — either the key is unknown / revoked /
  * expired (`capability_invalid`), or the connection's resolved scope
@@ -282,6 +350,10 @@ const NestedErrorShapeSchema = z
     message: OptionalWireStringSchema,
     field: OptionalWireStringSchema,
     requiredCapability: RequiredCapabilityWireSchema.optional().catch(undefined),
+    heldBy: OptionalWireStringSchema,
+    policyReason: OptionalWireStringSchema,
+    heldByClaim: wireClaimSummarySchema.optional().catch(undefined),
+    claims: z.array(wireClaimSummarySchema).optional().catch(undefined),
 })
     .passthrough();
 const ErrorFieldSchema = z
@@ -298,6 +370,10 @@ const ErrorBodyShapeSchema = z
     reason: OptionalWireStringSchema,
     message: OptionalWireStringSchema,
     requiredCapability: RequiredCapabilityWireSchema.optional().catch(undefined),
+    heldBy: OptionalWireStringSchema,
+    policyReason: OptionalWireStringSchema,
+    heldByClaim: wireClaimSummarySchema.optional().catch(undefined),
+    claims: z.array(wireClaimSummarySchema).optional().catch(undefined),
 })
     .passthrough();
 function parseErrorBodyShape(body) {
@@ -341,7 +417,7 @@ export function toAbloError(err) {
  * hierarchy and loses `code`/`httpStatus`/retryability.
  */
 export function errorFromWire(message, opts = {}) {
-    const { code, requestId, requiredCapability } = opts;
+    const { code, requestId, requiredCapability, claims } = opts;
     // Effective status: an explicit HTTP status wins; otherwise fall back to
     // the code's canonical status from the registry (undefined for unknown /
     // forward-compat codes, which then map to the base AbloError).
@@ -349,7 +425,7 @@ export function errorFromWire(message, opts = {}) {
     // Wire boundary: an incoming code is an arbitrary string (a newer server
     // may send a code this SDK predates). Cast to ErrorCode here — the one
     // sanctioned crossing — so internal producers stay statically checked.
-    const publicCode = (code === 'intent_conflict' ? 'claim_conflict' : code);
+    const publicCode = (code === 'claim_conflict' ? 'claim_conflict' : code);
     const baseOpts = { code: publicCode, httpStatus, requestId };
     // ── Code-first specials (transport-independent) ──────────────────────
     // A scoped credential was denied — route through CapabilityError so callers
@@ -360,8 +436,8 @@ export function errorFromWire(message, opts = {}) {
     // Claim enforcement (rides 409): the target entity is held by another
     // participant. Discriminate on code BEFORE the generic 409→idempotency
     // mapping so a claim rejection surfaces as AbloClaimedError.
-    if (code === 'intent_conflict' || code === 'claim_conflict' || code === 'entity_claimed') {
-        return new AbloClaimedError(message, baseOpts);
+    if (code === 'claim_conflict' || code === 'claim_conflict' || code === 'entity_claimed') {
+        return new AbloClaimedError(message, { ...baseOpts, claims });
     }
     // A write whose `readAt` watermark went stale — callers re-read and retry.
     if (code === 'stale_context') {
@@ -404,7 +480,20 @@ export function translateHttpError(status, body, requestId) {
         flatError ??
         (typeof body === 'string' ? body : `HTTP ${status}`);
     const requiredCapability = nested?.requiredCapability ?? parsed.requiredCapability;
-    return errorFromWire(message, { code, httpStatus: status, requestId, requiredCapability });
+    const claims = parsed.claims ??
+        nested?.claims ??
+        (parsed.heldByClaim
+            ? [parsed.heldByClaim]
+            : nested?.heldByClaim
+                ? [nested.heldByClaim]
+                : undefined);
+    return errorFromWire(message, {
+        code,
+        httpStatus: status,
+        requestId,
+        requiredCapability,
+        claims,
+    });
 }
 /**
  * Whether an HTTP error body carries a code {@link translateHttpError} can read

package/dist/interfaces/index.d.ts

@@ -160,13 +160,17 @@ export interface MutationOptions {
     wait?: 'queued' | 'confirmed';
     readAt?: number | null;
     onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
-    intent?: string | {
+    /** Claim-pin attribution: the id (or `{ id }`) of the claim this write
+     *  belongs to. Distinct from the `claim` HANDLE on the model write params —
+     *  this is the low-level reference the commit carries to bypass the holder's
+     *  own pin. (Was `intent` before the claim-vocabulary unification.) */
+    claimRef?: string | {
         readonly id: string;
     } | null;
     /**
      * Dormant agent-task lineage field, forwarded as the wire-level
      * `causedByTaskId`. Turns/tasks were removed from the SDK; nothing
-     * populates this anymore (write attribution rides on the claim/intent
+     * populates this anymore (write attribution rides on the claim
      * id). Kept optional for wire-compat; always `null` from the client.
      */
     causedByTaskId?: string | null;
@@ -175,9 +179,9 @@ export interface MutationOptions {
  * The `MutationOptions` subset carried per-write through the offline
  * transaction lane (SyncClient → TransactionQueue → wire operation).
  * ONE shared type so the proxy's public params, the queue, and the wire
- * can never narrow each other silently again — `wait` and `intent` are
+ * can never narrow each other silently again — `wait` and `claim` are
  * deliberately absent because they resolve client-side before staging
- * (`wait` at the proxy's confirmation await, `intent` server-side via
+ * (`wait` at the proxy's confirmation await, `claim` server-side via
  * the active lease on the entity).
  */
 export type WriteOptions = Pick<MutationOptions, 'readAt' | 'onStale' | 'idempotencyKey' | 'label'>;

package/dist/policy/index.d.ts

@@ -15,5 +15,5 @@
  * };
  * ```
  */
-export type { Conflict, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, IntentHeldConflict, } from './types.js';
+export type { Conflict, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, ClaimHeldConflict, } from './types.js';
 export { defaultPolicy, capabilityPreemptPolicy } from './types.js';

package/dist/policy/types.d.ts

@@ -2,12 +2,12 @@
  * Conflict policy — the engine detects, the policy decides.
  *
  * Two conflict shapes today: `stale_context` (a write whose `readAt`
- * is older than the latest delta on the target) and `intent_held`
+ * is older than the latest delta on the target) and `claim_held`
  * (a participant claims a target someone else is already claiming).
  * Adding new shapes is additive on the discriminated union.
  */
 import type { ParticipantRef } from '../types/streams.js';
-export type ConflictKind = 'stale_context' | 'intent_held';
+export type ConflictKind = 'stale_context' | 'claim_held';
 /** Fields shared by every conflict shape. */
 interface ConflictBase {
     readonly committer: ParticipantRef;
@@ -40,19 +40,19 @@ export interface StaleContextConflict extends ConflictBase {
      */
     readonly conflictingFields?: readonly string[];
 }
-export interface IntentHeldConflict extends ConflictBase {
-    readonly kind: 'intent_held';
+export interface ClaimHeldConflict extends ConflictBase {
+    readonly kind: 'claim_held';
     readonly heldBy: ParticipantRef;
-    readonly intentId: string;
+    readonly claimId: string;
     readonly entityType: string;
     readonly entityId: string;
-    /** Holder's intent expiry (ms since epoch). */
+    /** Holder's claim expiry (ms since epoch). */
     readonly expiresAt: number;
     /**
      * The committer's granted capability operations (the key's allowlist). A
      * policy is a pure function of the conflict value, so it can only authorize
      * on what's carried here — this is what lets a policy express "preempt iff
-     * the committer holds `intent.preempt`" (see `capabilityPreemptPolicy`).
+     * the committer holds `claim.preempt`" (see `capabilityPreemptPolicy`).
      * Empty for a human session with no allowlist.
      */
     readonly committerOperations: readonly string[];
@@ -61,7 +61,7 @@ export interface IntentHeldConflict extends ConflictBase {
  * The discriminated union the policy receives. Switch on `.kind` to
  * narrow to the variant.
  */
-export type Conflict = StaleContextConflict | IntentHeldConflict;
+export type Conflict = StaleContextConflict | ClaimHeldConflict;
 /** What the policy returns. */
 export type ConflictDecision = {
     readonly action: 'reject';
@@ -72,8 +72,8 @@ export type ConflictDecision = {
 }
 /**
  * Evict the current holder and grant the target to the committer. Only
- * meaningful for an `intent_held` conflict at claim time (`intent_begin`):
- * the holder receives an `intent_lost` (reason `'preempted'`) and the
+ * meaningful for an `claim_held` conflict at claim time (`claim_begin`):
+ * the holder receives an `claim_lost` (reason `'preempted'`) and the
  * preemptor takes the lease, jumping ahead of any FIFO waiters. This is the
  * authorization seam for preemption — a policy returns `preempt` only for a
  * committer it deems higher-priority (e.g. a supervisor over its sub-agents,
@@ -100,12 +100,12 @@ export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<
 /**
  * Default: reject every conflict. Safe fallback when no custom policy
  * is wired — the engine never silently allows a stale or
- * intent-conflicting write through.
+ * claim-conflicting write through.
  */
 export declare const defaultPolicy: ConflictPolicy;
 /**
- * Capability-gated preemption. An `intent_held` conflict is PREEMPTED when the
- * committer holds the `intent.preempt` operation in its capability allowlist
+ * Capability-gated preemption. An `claim_held` conflict is PREEMPTED when the
+ * committer holds the `claim.preempt` operation in its capability allowlist
  * (the holder is evicted, the committer takes the lease); everything else falls
  * back to `defaultPolicy` (reject). Opt-in — wire it as a `conflictPolicies`
  * global to let a privileged identity jump a held entity without a bespoke

package/dist/policy/types.js

@@ -2,31 +2,31 @@
  * Conflict policy — the engine detects, the policy decides.
  *
  * Two conflict shapes today: `stale_context` (a write whose `readAt`
- * is older than the latest delta on the target) and `intent_held`
+ * is older than the latest delta on the target) and `claim_held`
  * (a participant claims a target someone else is already claiming).
  * Adding new shapes is additive on the discriminated union.
  */
 /**
  * Default: reject every conflict. Safe fallback when no custom policy
  * is wired — the engine never silently allows a stale or
- * intent-conflicting write through.
+ * claim-conflicting write through.
  */
 export const defaultPolicy = (conflict) => ({
     action: 'reject',
-    reason: conflict.kind === 'stale_context' ? 'stale_context' : 'intent_conflict',
+    reason: conflict.kind === 'stale_context' ? 'stale_context' : 'claim_conflict',
 });
 /**
- * Capability-gated preemption. An `intent_held` conflict is PREEMPTED when the
- * committer holds the `intent.preempt` operation in its capability allowlist
+ * Capability-gated preemption. An `claim_held` conflict is PREEMPTED when the
+ * committer holds the `claim.preempt` operation in its capability allowlist
  * (the holder is evicted, the committer takes the lease); everything else falls
  * back to `defaultPolicy` (reject). Opt-in — wire it as a `conflictPolicies`
  * global to let a privileged identity jump a held entity without a bespoke
  * policy. The authorization is the capability, not an identity string.
  */
 export const capabilityPreemptPolicy = (conflict) => {
-    if (conflict.kind === 'intent_held' &&
-        conflict.committerOperations.includes('intent.preempt')) {
-        return { action: 'preempt', reason: 'capability:intent.preempt' };
+    if (conflict.kind === 'claim_held' &&
+        conflict.committerOperations.includes('claim.preempt')) {
+        return { action: 'preempt', reason: 'capability:claim.preempt' };
     }
     return defaultPolicy(conflict);
 };

package/dist/react/AbloProvider.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from 'react';
 import type { SchemaRecord } from '../schema/schema.js';
 import { Ablo } from '../client/Ablo.js';
-import type { ActiveIntent, Peer } from '../types/streams.js';
+import type { ActiveClaim, Peer } from '../types/streams.js';
 import type { EngineParticipant, ParticipantScope, ParticipantStatus } from '../sync/participants.js';
 import { type SyncStoreContract } from './context.js';
 /**
@@ -128,6 +128,29 @@ export interface UseParticipantOptions {
     readonly autoRefreshThresholdSeconds?: number | null;
     /** Tear down + don't re-join while true. */
     readonly paused?: boolean;
+    /**
+     * Acquire a write-claim CLAIM on the scope, in addition to read interest.
+     *
+     * Default `false`: opening a scope subscribes the connection to its deltas
+     * (read interest, via `update_subscription`) but does NOT claim it — a
+     * viewer is not a claimant. Set `true` when the participant intends to
+     * WRITE (editing a deck, an agent staking work): the claim is sent so peers
+     * observe it, and the scope is pinned so it stays subscribed (never warms)
+     * for as long as the claim is held.
+     */
+    readonly claim?: boolean;
+    /**
+     * Backfill the scope's CURRENT state into the pool on enter, in addition to
+     * tailing live changes.
+     *
+     * Default `false`: entering a scope subscribes to its FUTURE deltas only — if
+     * the scope's rows aren't already loaded, the view is empty until something
+     * changes. Set `true` when opening an entity that may not be loaded yet (a
+     * deep-linked deck, a never-opened sheet) so its current rows are fetched and
+     * injected once, then kept fresh by the live tail. The fetch is single-flight
+     * and runs once per group; a failure soft-fails (the live tail still flows).
+     */
+    readonly hydrate?: boolean;
 }
 /** @deprecated Use `ParticipantStatus`. */
 export type MeshParticipantStatus = ParticipantStatus;
@@ -135,8 +158,8 @@ export interface UseParticipantReturn {
     readonly participant: EngineParticipant | null;
     /** Everyone else on the engine's sync groups (`participant.presence.others`), bridged to React. */
     readonly peers: ReadonlyArray<Peer>;
-    /** Active intent claims by peers (`participant.intents.others`), bridged to React. */
-    readonly claims: ReadonlyArray<ActiveIntent>;
+    /** Active claim claims by peers (`participant.claims.others`), bridged to React. */
+    readonly claims: ReadonlyArray<ActiveClaim>;
     readonly status: ParticipantStatus;
     readonly error: Error | null;
 }
@@ -146,11 +169,35 @@ export interface UseParticipantReturn {
  * flips to true.
  *
  * The returned `participant` is an `EngineParticipant` — `.presence`
- * + `.intents` only — backed by the engine's existing socket. For
+ * + `.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;
+/**
+ * Read-only presence: the OTHER participants currently visible to this
+ * connection, bridged to React. Unlike {@link useParticipant}, 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.
+ *
+ * Pass `scope` to narrow to the peers on that scope's sync group(s); omit
+ * it to get everyone on the engine's groups. Membership is driven entirely
+ * by the presence channel (set server-side on connect, independent of any
+ * cursor/collaboration traffic), so reading it never affects what the
+ * connection is subscribed to and can't deadlock against a gated channel.
+ *
+ * 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
+ * subscription on unmount).
+ *
+ * ```ts
+ * const peers = usePeers({ slideDecks: deckId });
+ * const alone = !peers.some((p) => p.participantKind === 'user');
+ * ```
+ */
+export declare function usePeers(scope?: ParticipantScope): ReadonlyArray<Peer>;
 /**
  * Returns the raw `SyncEngine` proxy. Typically you want the typed
  * hooks (`useQuery`, `useOne`, `useMutate`) — this is for rare cases

package/dist/react/AbloProvider.js

@@ -205,7 +205,7 @@ const EMPTY_INTENTS = Object.freeze([]);
  * flips to true.
  *
  * The returned `participant` is an `EngineParticipant` — `.presence`
- * + `.intents` only — backed by the engine's existing socket. For
+ * + `.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.
  */
@@ -224,18 +224,21 @@ export function useParticipant(opts) {
     // Reference-stable participant facade — same socket as entity sync,
     // so there is no `connect()` / `disconnect()` lifecycle here. The
     // engine manages the connection; the hook is a thin window onto its
-    // already-attached presence + intent streams.
+    // already-attached presence + claim streams.
     const participant = useMemo(() => {
         if (!engine)
             return null;
-        return { presence: engine.presence, intents: engine.intents };
+        return { presence: engine.presence, claims: engine.claims };
     }, [engine]);
     // Status maps to the engine's sync state. `connecting` while the
     // engine bootstraps; `connected` once `engine.ready()` resolves and
     // any scoped participant claim has acked; `error` if the claim
     // fails; `disconnected` while paused or before the engine exists.
     const syncStatus = useSyncStatus();
-    const needsClaim = scopedSyncGroups.length > 0;
+    // Only a write-claim participant waits on a claim ack. A pure reader
+    // (the default) is `connected` as soon as the engine is — its read
+    // interest is fire-and-forget `update_subscription`, not a claim.
+    const needsClaim = !!opts.claim && scopedSyncGroups.length > 0;
     const status = paused || !engine
         ? 'disconnected'
         : claimError
@@ -248,16 +251,45 @@ export function useParticipant(opts) {
                     ? 'disconnected'
                     : 'connecting';
     const error = claimError;
+    // ── Read interest (always) ───────────────────────────────────────
+    // 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
+    // (tab flip) doesn't re-bootstrap.
+    useEffect(() => {
+        const scope = opts.scope;
+        if (paused || !engine || !scope || scopedSyncGroups.length === 0)
+            return;
+        if (syncStatus.name !== 'connected')
+            return;
+        const store = engine._store;
+        // `hydrate` backfills the scope's current state after subscribing
+        // (store handles subscribe-first ordering + single-flight). leaveScope
+        // only moves read interest; the hydrated rows stay in the pool.
+        void store.enterScope?.(scope, { hydrate: opts.hydrate });
+        return () => {
+            void store.leaveScope?.(scope);
+        };
+        // scopeKey is the stable proxy for the resolved groups; same idiom as
+        // the claim effect below.
+    }, [engine, paused, scopeKey, syncStatus.name, opts.hydrate]);
+    // ── Write claim (opt-in: `claim: true`) ─────────────────────────
+    // A claim is the write-claim primitive — distinct from read interest
+    // above. Only sent when the caller opts in; it makes peers observe the
+    // claim and pins the scope so it never warms while held.
     useEffect(() => {
         setClaimError(null);
         setClaimConnected(false);
-        if (paused || !engine || scopedSyncGroups.length === 0)
+        const scope = opts.scope;
+        if (paused || !engine || !opts.claim || !scope || scopedSyncGroups.length === 0)
             return;
         if (syncStatus.name !== 'connected')
             return;
         const ws = engine._ws;
         if (!ws)
             return;
+        const store = engine._store;
         let cancelled = false;
         const claimId = createParticipantClaimId();
         ws.sendClaim(claimId, scopedSyncGroups, {
@@ -272,12 +304,15 @@ export function useParticipant(opts) {
                 setClaimError(err instanceof Error ? err : new Error(String(err)));
             }
         });
+        // Prominence: hold the scope subscribed for as long as the claim lives.
+        void store.pinScope?.(scope);
         return () => {
             cancelled = true;
             ws.sendRelease(claimId);
+            void store.unpinScope?.(scope);
         };
-    }, [engine, paused, scopeKey, syncStatus.name, opts.ttlSeconds]);
-    // Bridge the engine's presence + intents streams into React state.
+    }, [engine, paused, scopeKey, syncStatus.name, opts.ttlSeconds, opts.claim]);
+    // Bridge the engine's presence + claims streams into React state.
     // Plain useState + useEffect is sufficient — mid-frame tearing on a
     // peer list is harmless (users won't notice one frame of stale
     // presence). Queries and sync status use useSyncExternalStore
@@ -291,16 +326,16 @@ export function useParticipant(opts) {
             return;
         }
         setPeers(participant.presence.others);
-        setClaims(participant.intents.others);
+        setClaims(participant.claims.others);
         const unsubPresence = participant.presence.onChange(() => {
             setPeers(participant.presence.others);
         });
-        const unsubIntents = participant.intents.onChange(() => {
-            setClaims(participant.intents.others);
+        const unsubClaims = participant.claims.onChange(() => {
+            setClaims(participant.claims.others);
         });
         return () => {
             unsubPresence();
-            unsubIntents();
+            unsubClaims();
         };
     }, [participant, paused]);
     // `opts.as`, `opts.agent`, `opts.idempotencyKey`, and
@@ -309,6 +344,55 @@ export function useParticipant(opts) {
     // 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
+ * 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.
+ *
+ * Pass `scope` to narrow to the peers on that scope's sync group(s); omit
+ * it to get everyone on the engine's groups. Membership is driven entirely
+ * by the presence channel (set server-side on connect, independent of any
+ * cursor/collaboration traffic), so reading it never affects what the
+ * connection is subscribed to and can't deadlock against a gated channel.
+ *
+ * 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
+ * subscription on unmount).
+ *
+ * ```ts
+ * const peers = usePeers({ slideDecks: deckId });
+ * const alone = !peers.some((p) => p.participantKind === 'user');
+ * ```
+ */
+export function usePeers(scope) {
+    const ctx = useContext(AbloInternalContext);
+    const engine = ctx?.engine ?? null;
+    // Resolve scope → groups through the schema (same idiom as useParticipant).
+    // 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]);
+    const [peers, setPeers] = useState(EMPTY_PRESENCE);
+    useEffect(() => {
+        if (!engine) {
+            setPeers(EMPTY_PRESENCE);
+            return;
+        }
+        const presence = engine.presence;
+        const compute = () => groups.length === 0
+            ? presence.others
+            : presence.others.filter((p) => p.syncGroups.some((g) => groups.includes(g)));
+        // 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).
+        setPeers(compute());
+        return presence.onChange(() => setPeers(compute()));
+    }, [engine, scopeKey]);
+    return peers;
+}
 // ── Escape-hatches: raw engine/store access ──────────────────────────
 /**
  * Returns the raw `SyncEngine` proxy. Typically you want the typed

package/dist/react/context.d.ts

@@ -5,6 +5,7 @@ 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/
@@ -93,6 +94,22 @@ export interface SyncStoreContract {
     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`
@@ -131,13 +148,13 @@ export interface SyncReactContext {
      */
     presence?: unknown;
     /**
-     * Optional intent initiator. Same pattern as presence — consumers
-     * plug a function that turns an intent claim into a handle they
+     * 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).
-     * `useIntent(name)` returns a typed invoker for the named intent
-     * from `interface Register { Intents: ... }`.
+     * `useClaim(name)` returns a typed invoker for the named claim
+     * from `interface Register { Claims: ... }`.
      */
-    beginIntent?: (intentName: string, claim: unknown) => unknown;
+    beginClaim?: (claimName: string, claim: unknown) => unknown;
 }
 export declare const SyncContext: import("react").Context<SyncReactContext | null>;
 /**
@@ -168,10 +185,10 @@ export interface SyncProviderProps {
      */
     presence?: unknown;
     /**
-     * Optional intent initiator for `useIntent()`. See
-     * {@link SyncReactContext.beginIntent}.
+     * Optional claim initiator for `useClaim()`. See
+     * {@link SyncReactContext.beginClaim}.
      */
-    beginIntent?: (intentName: string, claim: unknown) => unknown;
+    beginClaim?: (claimName: string, claim: unknown) => unknown;
     children?: ReactNode;
 }
 /**
@@ -189,4 +206,4 @@ export interface SyncProviderProps {
  *   );
  * }
  */
-export declare function SyncProvider({ store, organizationId, schema, presence, beginIntent, children, }: SyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SyncReactContext | null>>;
+export declare function SyncProvider({ store, organizationId, schema, presence, beginClaim, children, }: SyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SyncReactContext | null>>;

package/dist/react/context.js

@@ -30,6 +30,6 @@ export function useSyncContext() {
  *   );
  * }
  */
-export function SyncProvider({ store, organizationId, schema, presence, beginIntent, children, }) {
-    return createElement(SyncContext.Provider, { value: { store, organizationId, schema, presence, beginIntent } }, children);
+export function SyncProvider({ store, organizationId, schema, presence, beginClaim, children, }) {
+    return createElement(SyncContext.Provider, { value: { store, organizationId, schema, presence, beginClaim } }, children);
 }