@abloatai/humans 0.61.0 → 0.63.0

package/src/local/sync/createClaimStream.ts

@@ -5,10 +5,8 @@
  * everyone else's, and watch the wait queue when a claim is contended.
  *
  * The stream is built directly on the sync WebSocket and shares that one
- * connection. It learns about other participants' claims from the same
- * `presence_update` frames the {@link createPresenceStream} presence stream
- * consumes — the server piggybacks each participant's `activeClaims` on every
- * presence frame — and sends its own claims as `claim_begin` and
+ * connection. It learns about other sessions' claims from the normalized
+ * presence projection and sends its own claims as `claim_begin` and
  * `claim_abandon` frames.
  *
  * Wire frames:
@@ -16,16 +14,15 @@
  *       entityId, description, field?, estimatedMs? }`.
  *   • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
  *       entityId? }`.
- *   • Inbound, via presence — `event.activeClaims`, each stamped with
- *       `declaredAt` and `expiresAt`.
+ *   • Inbound, via presence — authoritative `claim` activities.
  *   • Inbound `claim_rejected` — the server refused the claim, with conflict
  *       metadata.
  */
 
 import type {
   WsTransport,
-  PresenceUpdate,
 } from '@abloatai/transaction/transport/websocket';
+import type { PresenceSession } from '@abloatai/transaction/presence';
 import type {
   ClaimOptions,
   ClaimTarget,
@@ -79,12 +76,15 @@ function claimLabel(type: string, id: string, field?: string): string {
 }
 
 export interface ClaimStreamConfig {
-  /** Identity used to filter our own active claims out of `others`. */
-  participantId: string;
   /** Where the coordination trace is logged. Defaults to silent. */
   logger?: Logger;
 }
 
+export interface ClaimPresenceSource {
+  readonly others: readonly PresenceSession[];
+  onChange(listener: () => void): () => void;
+}
+
 /**
  * How long a heartbeat waits for its `claim_heartbeat_ack` before giving up
  * as transient (the auto-heartbeat loop's next tick retries). Comfortably
@@ -107,14 +107,6 @@ export interface AttachableClaimStream extends ClaimStream {
    */
   claim(target: PresenceTarget, opts?: ClaimOptions, claimId?: string): Claim;
   attach(transport: ClaimTransport): void;
-  /**
-   * Seeds the participant identity once the host resolves it. The stream can
-   * be built before identity is known — a hosted client learns who it is
-   * from its credential's scope during connect — and until then the
-   * construction-time id (possibly empty) would let the participant's own
-   * claims into `others`. Idempotent; later frames filter on the new id.
-   */
-  setParticipant(participant: { id: string }): void;
   dispose(): void;
 }
 
@@ -144,10 +136,8 @@ interface OwnGrant {
 export function createClaimStream(
   config: ClaimStreamConfig,
   transport: ClaimTransport | null = null,
+  presence: ClaimPresenceSource | null = null,
 ): AttachableClaimStream {
-  // Mutable: the host seeds the resolved identity via `setParticipant` once
-  // it is known; the own-claim filter always reads the current value.
-  let participantId = config.participantId;
   const logger = config.logger ?? noopLogger;
 
   // ── State: others' open claims, keyed by claimId ───────────────
@@ -247,54 +237,7 @@ export function createClaimStream(
     if (attached) return;
     attached = t;
 
-    // (1) Inbound presence frames carry every participant's full
-    //     active-claim set. Prune previous claims by holder, then
-    //     re-add from the frame — the frame is authoritative for that
-    //     participant's open claims at that moment.
-    unsubs.push(
-      t.subscribe('presence_update', (event: PresenceUpdate) => {
-        if (!event.userId) return;
-        if (event.userId === participantId) return;
-
-        let mutated = false;
-
-        if (event.kind === 'leave') {
-          for (const [id, claim] of activeByClaimId) {
-            if (claim.heldBy === event.userId) {
-              activeByClaimId.delete(id);
-              mutated = true;
-            }
-          }
-          if (mutated) notifyListeners();
-          return;
-        }
-
-        for (const [id, claim] of activeByClaimId) {
-          if (claim.heldBy === event.userId) {
-            activeByClaimId.delete(id);
-            mutated = true;
-          }
-        }
-        for (const claim of event.activeClaims ?? []) {
-          // Terminal-status entries (committed / expired / canceled) are
-          // one-shot "this claim ended" signals. The holder sweep above
-          // already removed the prior active entry; skipping the re-add
-          // drops it from `others`, which is what resolves a contender's
-          // `settled()`. Absent status means active (wire back-compat).
-          if (claim.status && claim.status !== 'active') continue;
-          observeForeignClaim(
-            event.userId,
-            claim,
-            event.participantKind,
-            event.isAgent,
-          );
-          mutated = true;
-        }
-        if (mutated) notifyListeners();
-      }),
-    );
-
-    // (2) Server-side rejection frames.
+    // Server-side rejection frames.
     unsubs.push(
       t.subscribe('claim_rejected', (rejection) => {
         if (!rejection.claimId) return;
@@ -476,6 +419,46 @@ export function createClaimStream(
 
   if (transport) attach(transport);
 
+  const refreshPresenceClaims = (): void => {
+    if (presence === null) return;
+    activeByClaimId.clear();
+    for (const session of presence.others) {
+      for (const activity of session.activities) {
+        if (
+          activity.operation !== 'claim'
+          || activity.source !== 'claim'
+          || activity.target.id === undefined
+        ) continue;
+        const claimId = activity.id.startsWith('claim:')
+          ? activity.id.slice('claim:'.length)
+          : activity.id;
+        observeForeignClaim(
+          session.participant.id,
+          {
+            claimId,
+            entityType: activity.target.model,
+            entityId: activity.target.id,
+            ...(activity.target.field !== undefined
+              ? { field: activity.target.field }
+              : {}),
+            ...(activity.target.fields !== undefined
+              ? { fields: activity.target.fields }
+              : {}),
+            description: 'claim',
+            declaredAt: Date.parse(activity.startedAt),
+            expiresAt: Date.parse(activity.expiresAt),
+          },
+          session.participant.kind,
+        );
+      }
+    }
+    notifyListeners();
+  };
+  if (presence !== null) {
+    refreshPresenceClaims();
+    unsubs.push(presence.onChange(refreshPresenceClaims));
+  }
+
   // ── Outbound ────────────────────────────────────────────────────
   function sendBegin(claimId: string, claim: OwnClaim): void {
     if (!attached?.isConnected()) return;
@@ -705,9 +688,6 @@ export function createClaimStream(
       );
     },
     attach,
-    setParticipant(participant: { id: string }): void {
-      participantId = participant.id;
-    },
     dispose(): void {
       for (const off of unsubs) off();
       unsubs.length = 0;

package/src/local/sync/socketEventWiring.ts

@@ -9,7 +9,6 @@ import type { SyncStatus } from '../storeContract.js';
 import type {
   BootstrapHint,
   BootstrapDataEvent,
-  PresenceUpdate,
   SyncWebSocket,
   EventMap,
 } from './SyncWebSocket.js';
@@ -31,7 +30,6 @@ export interface SocketEventHost<TCollaboration extends EventMap<TCollaboration>
   applyDeltaFrame(deltas: SyncDelta[]): void;
   handleBootstrapRequired(hint: BootstrapHint): void;
   handleBootstrapData(data: BootstrapDataEvent): void;
-  handlePresenceUpdate(data: PresenceUpdate): void;
   performCredentialRefresh(): Promise<'refreshed' | 'session_error' | 'network_error'>;
   handleTerminalSessionError(error: Error): void;
   nudgeReconnect(): void;
@@ -93,11 +91,6 @@ export function wireSocketEvents<TCollaboration extends EventMap<TCollaboration>
       deps.handleBootstrapData(data);
     });
 
-    const onPresenceUpdate = deps.syncWebSocket.subscribe('presence_update', (...args) => {
-      const data = args[0];
-      deps.handlePresenceUpdate(data);
-    });
-
     // Error events
     const onError = deps.syncWebSocket.subscribe('error', (error: Error) => {
       if (error.message === 'Network is offline' || error.message === 'WebSocket connection failed') {
@@ -189,7 +182,7 @@ export function wireSocketEvents<TCollaboration extends EventMap<TCollaboration>
     deps.disposers.push(
       onConnected, onDisconnected, onReconnecting,
       onDelta, onDeltaBatch, onBootstrapRequired,
-      onBootstrapData, onPresenceUpdate,
+      onBootstrapData,
       onError, onSessionError, onHandshakeFailed, onReconnectFailed,
       () => { deps.areaOfInterest.dispose(); },
     );

package/src/local/transactions/mutations/MutationQueue.ts

@@ -246,6 +246,8 @@ export class MutationQueue extends EventEmitter {
   private isProcessing = false;
   private processTimer?: NodeJS.Timeout;
   private processScheduled = false;
+  private disposed = false;
+  private retryTimers = new Set<ReturnType<typeof setTimeout>>();
 
   // Staging area for transactions created in the same event-loop tick. Each one
   // lands here first, then a microtask commits them together.
@@ -331,10 +333,11 @@ export class MutationQueue extends EventEmitter {
       isDefinitiveRejection: (error) => this.isDefinitiveRejection(error),
       isPermanentError: (error) => this.isPermanentError(error),
       scheduleRetry: (delayMs) => {
+        if (this.disposed) return;
         if (this.commitRetryTimer !== null) clearTimeout(this.commitRetryTimer);
         this.commitRetryTimer = setTimeout(() => {
           this.commitRetryTimer = null;
-          void this.processCommitLane();
+          if (!this.disposed) void this.processCommitLane();
         }, delayMs);
       },
       emitCommitLifecycle: (event, payload) => { this.emitCommitLifecycle(event, payload); },
@@ -463,6 +466,7 @@ export class MutationQueue extends EventEmitter {
       isPermanentError: (error) => this.isPermanentError(error),
       rollbackOptimistic: (transaction, reason, error) => this.rollbackOptimistic(transaction, reason, error),
       enqueue: (transaction) => { this.enqueue(transaction); },
+      scheduleRetry: (callback, delayMs) => { this.scheduleRetry(callback, delayMs); },
       getLastPermanentErrorSignature: () => this.lastPermanentErrorSig,
       setLastPermanentErrorSignature: (signature) => { this.lastPermanentErrorSig = signature; },
       emit: (event, payload) => this.emit(event, payload),
@@ -968,6 +972,7 @@ export class MutationQueue extends EventEmitter {
     clientTxId = transactionId,
     correlationId?: string,
   ): void {
+    if (this.disposed) return;
     const previous = this.replicationLagTimeouts.get(transactionId);
     if (previous) clearTimeout(previous);
     this.replicationLagErrors.delete(transactionId);
@@ -1182,6 +1187,7 @@ export class MutationQueue extends EventEmitter {
    * {@link drainPending} resumes the work when the owner decides to drain.
    */
   setConnectionState(state: 'connected' | 'disconnected'): void {
+    if (this.disposed) return;
     if (state === 'connected') {
       if (this.commitOfflineGraceTimer !== null) {
         clearTimeout(this.commitOfflineGraceTimer);
@@ -1400,13 +1406,15 @@ export class MutationQueue extends EventEmitter {
   }
 
   private scheduleProcessing(immediate = false): void {
+    if (this.disposed) return;
     scheduleProcessingExternal(this.processingSchedulerContext, immediate);
   }
 
   private async processBatch(): Promise<void> {
+    if (this.disposed) return;
     if (this.modelProcessingPromise) {
       await this.modelProcessingPromise;
-      if (this.executionQueue.length > 0) await this.processBatch();
+      if (!this.disposed && this.executionQueue.length > 0) await this.processBatch();
       return;
     }
     const processing = processBatch(this.batchProcessingContext);
@@ -1500,9 +1508,19 @@ export class MutationQueue extends EventEmitter {
   // Schedule the retry-and-reconciliation wait for a transaction's confirming
   // delta; see {@link DeltaConfirmationTracker} in `./deltaConfirmation.js`.
   private scheduleDeltaConfirmationTimeout(tx: QueuedMutation, timeoutMs: number): void {
+    if (this.disposed) return;
     this.deltaConfirmation.scheduleDeltaConfirmationTimeout(tx, timeoutMs);
   }
 
+  private scheduleRetry(callback: () => void, delayMs: number): void {
+    if (this.disposed) return;
+    const timer = setTimeout(() => {
+      this.retryTimers.delete(timer);
+      if (!this.disposed) callback();
+    }, delayMs);
+    this.retryTimers.add(timer);
+  }
+
   /**
    * Resolves once the given transaction is confirmed and rejects if it fails.
    * The confirming delta's timeout is handled by
@@ -1566,6 +1584,7 @@ export class MutationQueue extends EventEmitter {
   }
 
   private async processCommitLane(): Promise<void> {
+    if (this.disposed) return;
     await processCommitLane(this.commitLaneContext);
   }
 
@@ -1854,6 +1873,9 @@ export class MutationQueue extends EventEmitter {
    * clears all timers and stored transactions, and removes event listeners.
    */
   dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+
     // Cancel all active optimistic updates
     for (const [, optimistic] of this.localMutationPort.updates) {
       this.emit('optimistic:rollback', {
@@ -1888,6 +1910,8 @@ export class MutationQueue extends EventEmitter {
       clearTimeout(this.commitRetryTimer);
       this.commitRetryTimer = null;
     }
+    for (const timer of this.retryTimers) clearTimeout(timer);
+    this.retryTimers.clear();
 
     // Clear store
     this.store.clear();

package/src/local/transactions/mutations/deltaConfirmation.ts

@@ -49,6 +49,7 @@ export class DeltaConfirmationTracker {
 
   // Track retry attempts per transaction for exponential backoff
   private deltaConfirmationRetries = new Map<string, number>();
+  private disposed = false;
 
   private readonly runtime: RuntimeContext;
 
@@ -162,6 +163,7 @@ export class DeltaConfirmationTracker {
   // server has already confirmed. A rollback happens only on an explicit server
   // rejection, never on a timeout.
   scheduleDeltaConfirmationTimeout(tx: QueuedMutation, timeoutMs: number): void {
+    if (this.disposed) return;
     // Cancel any existing timeout for this transaction
     this.cancelDeltaConfirmationTimeout(tx.id);
 
@@ -289,6 +291,7 @@ export class DeltaConfirmationTracker {
    * would keep the process alive and fire callbacks against a cleared store.
    */
   dispose(): void {
+    this.disposed = true;
     for (const timeoutHandle of this.deltaConfirmationTimeouts.values()) {
       clearTimeout(timeoutHandle);
     }

package/src/local/transactions/mutations/failureHandling.ts

@@ -19,6 +19,7 @@ export interface FailureHandlingContext {
     error?: Error,
   ) => Promise<void>;
   readonly enqueue: (transaction: QueuedMutation) => void;
+  readonly scheduleRetry: (callback: () => void, delayMs: number) => void;
   readonly getLastPermanentErrorSignature: () => string | undefined;
   readonly setLastPermanentErrorSignature: (signature: string) => void;
   readonly emit: (event: string, payload: object) => boolean;
@@ -102,7 +103,7 @@ export async function handleFailure(
     );
 
     ctx.store.updateStatus(transaction.id, 'pending');
-    setTimeout(() => {
+    ctx.scheduleRetry(() => {
       // The queue may have shut down or the tx may have been settled
       // (e.g. delta-confirmed) while we backed off.
       if (ctx.store.get(transaction.id)?.status !== 'pending') return;

package/src/presence/index.ts

@@ -0,0 +1,101 @@
+import {
+  createPresenceProjection,
+  type PresenceProjection,
+  type PresenceProjectionEvents,
+  type PresenceView,
+} from '@abloatai/transaction/presence';
+import type { PresenceTarget } from '@abloatai/transaction/presence';
+import {
+  startReadActivity,
+  type ReadActivityLifetime,
+  type ReadActivityTransport,
+} from './readActivity.js';
+
+type PresenceTransport = PresenceProjectionEvents & ReadActivityTransport;
+
+/** Reactive-client presence backed by the client's existing live connection. */
+export interface ReactivePresence extends PresenceView {
+  forModel(model: string, recordId?: string): ReturnType<PresenceProjection['forModel']>;
+  onChange(listener: () => void): () => void;
+}
+
+/** Lifecycle hooks kept inside the humans composition boundary. */
+export interface AttachablePresence extends ReactivePresence {
+  attach(transport: PresenceTransport): void;
+  startRead(target: PresenceTarget): () => void;
+  dispose(): void;
+}
+
+const clientPresence = new WeakMap<object, ReactivePresence>();
+
+/** Framework bridge that does not consume a string key on the model namespace. */
+export function attachPresenceToClient(client: object, presence: ReactivePresence): void {
+  clientPresence.set(client, presence);
+}
+
+export function presenceOfClient(client: object): ReactivePresence {
+  const presence = clientPresence.get(client);
+  if (presence === undefined) throw new Error('presence is not attached to this client');
+  return presence;
+}
+
+export function createPresence(
+  transport: PresenceTransport | null = null,
+): AttachablePresence {
+  let projection: PresenceProjection | null = null;
+  let attachedTransport: PresenceTransport | null = null;
+  const listeners = new Set<() => void>();
+  const reads = new Set<ReadActivityLifetime>();
+  let unsubscribe: (() => void) | null = null;
+
+  const notify = (): void => {
+    for (const listener of listeners) listener();
+  };
+
+  const attach = (events: PresenceTransport): void => {
+    if (projection !== null) return;
+    attachedTransport = events;
+    projection = createPresenceProjection(events);
+    unsubscribe = projection.subscribe(notify);
+    notify();
+  };
+
+  if (transport !== null) attach(transport);
+
+  return {
+    get active() { return projection?.active ?? []; },
+    get others() { return projection?.others ?? []; },
+    onChange(listener) {
+      listeners.add(listener);
+      return () => { listeners.delete(listener); };
+    },
+    attach,
+    startRead(target) {
+      if (attachedTransport === null) {
+        throw new Error('presence is not attached to a duplex transport');
+      }
+      const lifetime = startReadActivity(
+        attachedTransport,
+        target,
+        () => { reads.delete(lifetime); },
+      );
+      reads.add(lifetime);
+      return () => {
+        lifetime.stop();
+      };
+    },
+    forModel(model, recordId) {
+      return projection?.forModel(model, recordId) ?? [];
+    },
+    dispose() {
+      for (const read of reads) read.dispose();
+      reads.clear();
+      unsubscribe?.();
+      unsubscribe = null;
+      projection?.dispose();
+      projection = null;
+      attachedTransport = null;
+      listeners.clear();
+    },
+  };
+}

package/src/presence/readActivity.ts

@@ -0,0 +1,149 @@
+import type {
+  PresenceCommand,
+  PresenceTarget,
+} from '@abloatai/transaction/presence';
+import { LEASE_TTL_MS } from '@abloatai/transaction/wire';
+
+/** The connection slice needed to keep one session-owned read alive. */
+export interface ReadActivityTransport {
+  isConnected(): boolean;
+  sendPresenceCommand(command: PresenceCommand): void;
+  subscribe(event: 'connected', listener: () => void): () => void;
+}
+
+export interface ReadActivityLifetime {
+  /** End the read and remove it from the server, reconnecting briefly if needed. */
+  stop(): void;
+  /** Tear down local resources when the owning client itself is disposed. */
+  dispose(): void;
+}
+
+const READ_TTL_MS = LEASE_TTL_MS;
+const READ_REFRESH_MS = READ_TTL_MS / 3;
+let fallbackActivitySequence = 0;
+const noop = (): void => undefined;
+
+function readActivityId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return `read:${crypto.randomUUID()}`;
+  }
+  fallbackActivitySequence += 1;
+  return `read:${Date.now().toString(36)}:${fallbackActivitySequence.toString(36)}`;
+}
+
+function unref(timer: ReturnType<typeof setTimeout>): void {
+  const candidate: unknown = timer;
+  if (
+    typeof candidate === 'object' &&
+    candidate !== null &&
+    'unref' in candidate &&
+    typeof candidate.unref === 'function'
+  ) {
+    (candidate as { unref(): void }).unref();
+  }
+}
+
+/**
+ * Own the lease mechanics for one declared read. React only starts and stops
+ * this lifetime; command ids, refreshes, reconnect recovery, and offline
+ * cleanup remain inside the presence subsystem.
+ */
+export function startReadActivity(
+  transport: ReadActivityTransport,
+  target: PresenceTarget,
+  onFinished: () => void = noop,
+): ReadActivityLifetime {
+  const activityId = readActivityId();
+  let active = true;
+  let disposed = false;
+  let removeOnConnect: (() => void) | null = null;
+  let removalExpiry: ReturnType<typeof setTimeout> | null = null;
+  let finished = false;
+
+  const finish = (): void => {
+    if (finished) return;
+    finished = true;
+    onFinished();
+  };
+
+  const send = (command: PresenceCommand): boolean => {
+    if (!transport.isConnected()) return false;
+    try {
+      transport.sendPresenceCommand(command);
+      return true;
+    } catch (error) {
+      // The socket can close between the state check and the synchronous send.
+      // Reconnect handling retries; a failure while still connected is real.
+      if (transport.isConnected()) throw error;
+      return false;
+    }
+  };
+
+  const upsert = (): void => {
+    if (!active || disposed) return;
+    send({ type: 'read.upsert', activityId, target, ttlMs: READ_TTL_MS });
+  };
+
+  const unsubscribeConnected = transport.subscribe('connected', upsert);
+  upsert();
+
+  const refreshTimer = setInterval(() => {
+    if (!active || disposed) return;
+    send({ type: 'read.refresh', activityId, ttlMs: READ_TTL_MS });
+  }, READ_REFRESH_MS);
+  unref(refreshTimer);
+
+  const clearResources = (): void => {
+    unsubscribeConnected();
+    clearInterval(refreshTimer);
+    removeOnConnect?.();
+    removeOnConnect = null;
+    if (removalExpiry !== null) clearTimeout(removalExpiry);
+    removalExpiry = null;
+  };
+
+  const stop = (): void => {
+    if (!active || disposed) return;
+    active = false;
+    unsubscribeConnected();
+    clearInterval(refreshTimer);
+
+    const remove = (): void => {
+      if (disposed) return;
+      if (!send({ type: 'read.remove', activityId })) return;
+      removeOnConnect?.();
+      removeOnConnect = null;
+      if (removalExpiry !== null) clearTimeout(removalExpiry);
+      removalExpiry = null;
+      finish();
+    };
+
+    if (transport.isConnected()) {
+      remove();
+      return;
+    }
+
+    // If the component leaves offline, remove on the next reconnect so the
+    // resumed logical session cannot briefly show a departed viewer. Once the
+    // lease expires server-side, there is nothing left to remove.
+    removeOnConnect = transport.subscribe('connected', remove);
+    removalExpiry = setTimeout(() => {
+      removeOnConnect?.();
+      removeOnConnect = null;
+      removalExpiry = null;
+      finish();
+    }, READ_TTL_MS);
+    unref(removalExpiry);
+  };
+
+  return {
+    stop,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      active = false;
+      clearResources();
+      finish();
+    },
+  };
+}

package/src/react/AbloProvider.tsx

@@ -12,7 +12,7 @@ import {
 } from 'react';
 import type { Schema, SchemaRecord } from '@abloatai/transaction/schema/schema';
 import type { AbloClient as Ablo } from '../client.js';
-import type { Peer } from '@abloatai/transaction/types/streams';
+import type { PresenceSession } from '@abloatai/transaction/presence';
 import type { GroupScope } from '../local/sync/scopeGroups.js';
 import { resolveScopeGroups } from '../local/sync/scopeGroups.js';
 import { SyncContext, type SyncStoreContract } from './context.js';
@@ -20,6 +20,7 @@ import { AbloInternalContext, type AbloInternalContextValue } from './internalCo
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { useSyncStatus } from './useSyncStatus.js';
 import { DefaultFallback } from './DefaultFallback.js';
+import { presenceOfClient } from '../presence/index.js';
 
 /**
  * Ablo umbrella provider — owns the sync engine, multiplayer, and
@@ -380,12 +381,12 @@ function BootstrapGate({
 }
 
 
-const EMPTY_PRESENCE: readonly Peer[] = Object.freeze([]);
+const EMPTY_PRESENCE: readonly PresenceSession[] = Object.freeze([]);
 
 export type { GroupScope };
 
 /**
- * Read-only presence: the OTHER participants currently visible to this
+ * Read-only presence: the other sessions currently visible to this
  * connection, bridged to React. This is a pure reader of the engine's
  * already-flowing presence stream; it does not mutate connection groups.
  *
@@ -403,7 +404,7 @@ export type { GroupScope };
  * const alone = !peers.some((p) => p.participantKind === 'user');
  * ```
  */
-export function usePeers(scope?: GroupScope): readonly Peer[] {
+export function usePeers(scope?: GroupScope): readonly PresenceSession[] {
   const ctx = useContext(AbloInternalContext);
   const engine = ctx?.engine ?? null;
 
@@ -414,19 +415,23 @@ export function usePeers(scope?: GroupScope): readonly Peer[] {
   );
   const groups = useMemo(() => JSON.parse(scopeKey) as string[], [scopeKey]);
 
-  const [peers, setPeers] = useState<readonly Peer[]>(EMPTY_PRESENCE);
+  const [peers, setPeers] = useState<readonly PresenceSession[]>(EMPTY_PRESENCE);
 
   useEffect(() => {
     if (!engine) {
       setPeers(EMPTY_PRESENCE);
       return;
     }
-    const presence = engine.presence;
-    const compute = (): readonly Peer[] =>
+    const presence = presenceOfClient(engine);
+    const compute = (): readonly PresenceSession[] =>
       groups.length === 0
         ? presence.others
-        : presence.others.filter((p) =>
-            p.syncGroups.some((g) => groups.includes(g)),
+        : presence.others.filter((session) =>
+            session.activities.some(({ target }) =>
+              target.id !== undefined && groups.includes(
+                `${target.model.toLowerCase()}:${target.id}`,
+              ),
+            ),
           );
     // Plain useState + onChange — presence changes on connect/disconnect/activity
     // only (never on cursor traffic, a separate channel), so this fires