@abloatai/humans 0.62.0 → 0.63.0

package/dist/react/createAbloReact.js

@@ -22,7 +22,8 @@
  */
 import { createContext, createElement, useContext } from 'react';
 import { AbloProvider, } from './AbloProvider.js';
-import { useAbloImpl, } from './useAblo.js';
+import { useAbloImpl, useAbloClientImpl, } from './useAblo.js';
+import { usePresenceImpl, } from './usePresence.js';
 /**
  * Bind the react surface to one schema. The schema value is taken for
  * inference — write `createAbloReact(schema)`, never a hand-spelled type
@@ -44,5 +45,14 @@ export function createAbloReact(schema) {
         const bound = useContext(BoundClientContext);
         return useAbloImpl(bound, modelOrSelect, id, options);
     }
-    return { AbloProvider: BoundAbloProvider, useAblo: useBoundAblo };
+    function useBoundPresence(modelOrSelect, recordId) {
+        const bound = useContext(BoundClientContext);
+        const engine = useAbloClientImpl(bound);
+        return usePresenceImpl(engine, modelOrSelect, recordId);
+    }
+    return {
+        AbloProvider: BoundAbloProvider,
+        useAblo: useBoundAblo,
+        usePresence: useBoundPresence,
+    };
 }

package/dist/react/useAblo.d.ts

@@ -93,4 +93,6 @@ export declare function useAblo<R extends SchemaRecord = DefaultModels, T = Reco
  * legacy mount migrates.
  */
 export declare function useAbloImpl<R extends SchemaRecord, T = Record<string, unknown>, C = unknown>(boundClient: Ablo<R> | null, modelOrSelect?: ModelOperations<T, C> | ModelClientSelector<R, T, C> | AbloSelector<R, T>, id?: string, options?: UseAbloModelOptions<T>): Ablo<R> | null | UseAbloModelResult<T> | T | undefined;
+/** @internal Resolve the bound or legacy provider client through one rebind seam. */
+export declare function useAbloClientImpl<R extends SchemaRecord>(boundClient: Ablo<R> | null): Ablo<R> | null;
 export {};

package/dist/react/useAblo.js

@@ -70,11 +70,7 @@ export function useAblo(modelOrSelect, id, options) {
  * legacy mount migrates.
  */
 export function useAbloImpl(boundClient, modelOrSelect, id, options) {
-    const ctx = useContext(AbloInternalContext);
-    // The bound client wins — it is already `Ablo<R>`, no rebinding. The
-    // fallback is the ONE remaining schema rebind in the SDK; it retires with
-    // the last legacy provider mount (docs/plans/typed-react-binding.md).
-    const engine = boundClient ?? (ctx?.engine ? rebindEngine(ctx.engine) : null);
+    const engine = useAbloClientImpl(boundClient);
     const initial = options?.initial;
     const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
     const modelClient = typeof modelOrSelect === 'function' && id !== undefined
@@ -118,3 +114,12 @@ export function useAbloImpl(boundClient, modelOrSelect, id, options) {
         return modelResult;
     return engine;
 }
+/** @internal Resolve the bound or legacy provider client through one rebind seam. */
+export function useAbloClientImpl(boundClient) {
+    const ctx = useContext(AbloInternalContext);
+    // The bound client wins — it is already `Ablo<R>`, no rebinding. The
+    // fallback is the ONE remaining schema rebind in the SDK; it retires with
+    // the last legacy provider mount (docs/plans/typed-react-binding.md).
+    const engine = boundClient ?? (ctx?.engine ? rebindEngine(ctx.engine) : null);
+    return engine;
+}

package/dist/react/usePresence.d.ts

@@ -0,0 +1,19 @@
+import type { PresenceSession } from '@abloatai/transaction/presence';
+import { type ModelOperations } from '../local/client/createModelOperations.js';
+import type { AbloClient as Ablo } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { ResolveSchema } from '@abloatai/transaction/types/global';
+type DefaultModels = ResolveSchema extends {
+    models: infer M;
+} ? M extends SchemaRecord ? M : SchemaRecord : SchemaRecord;
+export type PresenceModelSelector<R extends SchemaRecord, T, C> = (ablo: Ablo<R>) => ModelOperations<T, C>;
+/**
+ * Declare that this component is reading one row and return every live session
+ * reading or otherwise acting on that row. Ablo owns the lease, refresh,
+ * reconnect, and cleanup mechanics for the component's lifetime.
+ */
+export declare function usePresence<T, C>(modelClient: ModelOperations<T, C>, recordId: string): readonly PresenceSession[];
+export declare function usePresence<R extends SchemaRecord = DefaultModels, T = Record<string, unknown>, C = unknown>(select: PresenceModelSelector<R, T, C>, recordId: string): readonly PresenceSession[];
+/** @internal Shared by the global hook and schema-bound React factory. */
+export declare function usePresenceImpl<R extends SchemaRecord, T, C>(engine: Ablo<R> | null, modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<R, T, C>, recordId: string): readonly PresenceSession[];
+export {};

package/dist/react/usePresence.js

@@ -0,0 +1,28 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+import { getModelClientMeta, } from '../local/client/createModelOperations.js';
+import { useAbloClientImpl } from './useAblo.js';
+export function usePresence(modelOrSelect, recordId) {
+    const engine = useAbloClientImpl(null);
+    return usePresenceImpl(engine, modelOrSelect, recordId);
+}
+/** @internal Shared by the global hook and schema-bound React factory. */
+export function usePresenceImpl(engine, modelOrSelect, recordId) {
+    if (recordId.length === 0) {
+        throw new AbloValidationError('usePresence requires a non-empty record id.', { code: 'invalid_request', param: 'recordId' });
+    }
+    const modelClient = typeof modelOrSelect === 'function'
+        ? engine
+            ? modelOrSelect(engine)
+            : null
+        : modelOrSelect;
+    const presence = modelClient ? getModelClientMeta(modelClient)?.presence : undefined;
+    if (modelClient !== null && presence === undefined) {
+        throw new AbloValidationError('usePresence requires a model from the reactive Ablo client.', { code: 'invalid_request', param: 'modelClient' });
+    }
+    const [, render] = useState(0);
+    useEffect(() => presence?.subscribe(() => { render((version) => version + 1); }), [presence]);
+    useEffect(() => presence?.read(recordId), [presence, recordId]);
+    return presence?.get(recordId) ?? [];
+}

package/dist/react.d.ts

@@ -3,6 +3,7 @@ export { useReactive } from './useReactive.js';
 export { useCurrentUserId } from './react/useCurrentUserId.js';
 export { useErrorListener } from './react/useErrorListener.js';
 export { useSyncStatus, type SyncStatusSnapshot } from './react/useSyncStatus.js';
+export { usePresence, type PresenceModelSelector, } from './react/usePresence.js';
 export { useMutationFailureListener, type MutationFailurePayload, } from './react/useMutationFailureListener.js';
 export { AbloProvider, usePeers, useSync, useSyncStore, type AbloProviderProps, type GroupScope, } from './react/AbloProvider.js';
 export { ClientSideSuspense, type ClientSideSuspenseProps, } from './react/ClientSideSuspense.js';

package/dist/react.js

@@ -3,6 +3,7 @@ export { useReactive } from './useReactive.js';
 export { useCurrentUserId } from './react/useCurrentUserId.js';
 export { useErrorListener } from './react/useErrorListener.js';
 export { useSyncStatus } from './react/useSyncStatus.js';
+export { usePresence, } from './react/usePresence.js';
 export { useMutationFailureListener, } from './react/useMutationFailureListener.js';
 export { AbloProvider, usePeers, useSync, useSyncStore, } from './react/AbloProvider.js';
 export { ClientSideSuspense, } from './react/ClientSideSuspense.js';

package/dist/surface.d.ts

@@ -19,7 +19,7 @@
  * tuple, so it is the one list of model-verb names a generated summary can
  * describe.
  */
-export declare const PUBLIC_MODEL_VERBS: readonly ["get", "read", "list", "listAll", "local", "presence", "create", "update", "delete", "claim", "onChange"];
+export declare const PUBLIC_MODEL_VERBS: readonly ["get", "read", "list", "listAll", "local", "presence", "events", "create", "update", "delete", "claim", "onChange"];
 /**
  * The option keys accepted by `local.list` and `onChange`, matching the
  * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named

package/dist/surface.js

@@ -27,6 +27,7 @@ export const PUBLIC_MODEL_VERBS = [
     'listAll',
     'local',
     'presence',
+    'events',
     'create',
     'update',
     'delete',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -84,7 +84,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.62.0",
+    "@abloatai/transaction": "^0.63.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/index.ts

@@ -9,6 +9,7 @@ export type {
 } from './Ablo.js';
 export { humans, type HumansSurface } from './humans.js';
 export type { AbloClient } from './client.js';
+export type { CollaborationEventContext } from '@abloatai/transaction/collaboration';
 export type {
   AbloPlugin,
   MergedSurface,

package/src/local/InstanceCache.ts

@@ -1257,7 +1257,7 @@ export class InstanceCache {
   }
 
   private startGC(): void {
-    if (this.gcTimer) return;
+    if (this.gcTimer || this.config.gcInterval <= 0) return;
     this.gcTimer = setInterval(() => this.gc(), this.config.gcInterval);
     // Don't hold a headless Node process open just for pool GC — without
     // this, an agent that never calls disconnect() can never exit. No-op in

package/src/local/client/createModelOperations.ts

@@ -144,6 +144,13 @@ import type {
 } from '@abloatai/transaction/transport/http';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
 import type { PresenceSession } from '@abloatai/transaction/presence';
+import type {
+  CollaborationEventContext,
+  ModelEventEnvelope,
+  ModelEventInput,
+  ModelEventTarget,
+} from '@abloatai/transaction/collaboration';
+import { modelEventInputSchema } from '@abloatai/transaction/collaboration';
 import {
   capturePointRead,
   prepareReadSet,
@@ -152,10 +159,16 @@ import {
 
 const ignoreSeparatelyObservedMutationFailure = (): undefined => undefined;
 const ignoreBestEffortClaimReleaseFailure = (): undefined => undefined;
+const ignoreBestEffortScopeFailure = (): undefined => undefined;
 
 export interface ModelClientMeta {
   readonly key: string;
   readonly typename: string;
+  readonly presence?: {
+    get(recordId: string): readonly PresenceSession[];
+    subscribe(listener: () => void): () => void;
+    read(recordId: string): () => void;
+  };
 }
 
 const modelClientMeta = new WeakMap<object, ModelClientMeta>();
@@ -180,6 +193,13 @@ type EntityHalf = Pick<ModelTarget, 'model' | 'id'>;
 export interface ModelCollaboration {
   /** Session projections already held by this client's one presence store. */
   presence(model: string, recordId?: string): readonly PresenceSession[];
+  /** Subscribe once to the connection-owned presence projection. */
+  onPresenceChange(listener: () => void): () => void;
+  /** Start one session-owned read activity and return its cleanup. */
+  startReadPresence(target: EntityHalf): () => void;
+  modelEventTarget(recordId: string): ModelEventTarget;
+  sendModelEvent(input: ModelEventInput): void;
+  onModelEvent(listener: (event: ModelEventEnvelope) => void): () => void;
   /** Exact point evidence from the HTTP read boundary (stamp captured before data). */
   readPoint(model: string, id: string): Promise<{ data: unknown; stamp: number }>;
   /**
@@ -281,6 +301,8 @@ export interface ModelCollaboration {
    * test doubles can omit it.
    */
   enterScope?(scope: Record<string, string>): void | Promise<void>;
+  /** Release read interest previously acquired through {@link enterScope}. */
+  leaveScope?(scope: Record<string, string>): void | Promise<void>;
   /**
    * Pins a scope's sync group(s) — write intent: a row this client holds an
    * active claim on stays subscribed regardless of navigation. Same
@@ -342,6 +364,9 @@ interface ReactiveModelSurface<T, Fields = T> {
   /** Sessions currently active on this model, optionally narrowed to one record. */
   presence(recordId?: string): readonly PresenceSession[];
 
+  /** Lossy, model-record-addressed application events such as cursor or selection. */
+  events: ModelEvents;
+
   /**
    * Claim a row so other writers wait or are rejected until you're done, and
    * inspect or manage that coordination through the same namespace. Call it to
@@ -377,6 +402,50 @@ interface ReactiveModelSurface<T, Fields = T> {
   ): () => void;
 }
 
+export interface ModelEvents {
+  send(
+    recordId: string,
+    event: string,
+    payload: Readonly<Record<string, unknown>>,
+  ): void;
+  subscribe(
+    recordId: string,
+    event: string,
+    handler: (
+      payload: Readonly<Record<string, unknown>>,
+      context: CollaborationEventContext,
+    ) => void,
+  ): () => void;
+}
+
+function subscribeInModelScope(
+  collaboration: ModelCollaboration,
+  scope: Record<string, string>,
+  subscribe: () => () => void,
+): () => void {
+  let stopped = false;
+  let entered = false;
+  let unsubscribe: (() => void) | null = null;
+
+  void Promise.resolve(collaboration.enterScope?.(scope))
+    .then(() => {
+      entered = true;
+      if (stopped) {
+        void collaboration.leaveScope?.(scope);
+        return;
+      }
+      unsubscribe = subscribe();
+    })
+    .catch(ignoreBestEffortScopeFailure);
+
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    unsubscribe?.();
+    if (entered) void collaboration.leaveScope?.(scope);
+  };
+}
+
 /**
  * Everything reachable as `ablo.<model>` on a reactive client.
  *
@@ -1411,6 +1480,52 @@ export function createModelOperations<T, C>(
 
     presence: (recordId?: string) => collaboration?.presence(registeredModelName, recordId) ?? [],
 
+    events: {
+      send(recordId, event, payload) {
+        if (!collaboration) return;
+        const target = collaboration.modelEventTarget(recordId);
+        const parsed = modelEventInputSchema.safeParse({ target, event, payload });
+        if (!parsed.success) {
+          throw new AbloValidationError('Invalid model event.', {
+            code: 'invalid_request',
+            param: 'event',
+            cause: parsed.error,
+          });
+        }
+        const scope = { [schemaKey]: recordId };
+        void Promise.resolve(collaboration.enterScope?.(scope))
+          .then(() => { collaboration.sendModelEvent(parsed.data); })
+          .finally(() => { void collaboration.leaveScope?.(scope); });
+      },
+      subscribe(recordId, event, handler) {
+        if (!collaboration) return () => undefined;
+        const target = collaboration.modelEventTarget(recordId);
+        const parsed = modelEventInputSchema.safeParse({ target, event, payload: {} });
+        if (!parsed.success) {
+          throw new AbloValidationError('Invalid model event subscription.', {
+            code: 'invalid_request',
+            param: 'event',
+            cause: parsed.error,
+          });
+        }
+        const scope = { [schemaKey]: recordId };
+        return subscribeInModelScope(collaboration, scope, () =>
+          collaboration.onModelEvent((incoming) => {
+            if (
+              incoming.target.model !== target.model ||
+              incoming.target.id !== target.id ||
+              incoming.target.syncGroup !== target.syncGroup ||
+              incoming.event !== parsed.data.event
+            ) return;
+            handler(incoming.payload, {
+              sender: incoming.sender,
+              sentAt: incoming.sentAt,
+            });
+          }),
+        );
+      },
+    },
+
     get,
     read,
 
@@ -1666,6 +1781,23 @@ export function createModelOperations<T, C>(
   modelClientMeta.set(operations, {
     key: schemaKey,
     typename: registeredModelName,
+    ...(collaboration
+      ? {
+          presence: {
+            get: (recordId: string) => collaboration.presence(registeredModelName, recordId),
+            subscribe: (listener: () => void) => collaboration.onPresenceChange(listener),
+            read: (recordId: string) => {
+              const scope = { [schemaKey]: recordId };
+              return subscribeInModelScope(collaboration, scope, () =>
+                collaboration.startReadPresence({
+                  model: registeredModelName,
+                  id: recordId,
+                }),
+              );
+            },
+          },
+        }
+      : {}),
   });
 
   return operations;

package/src/local/client/reactiveEngine.ts

@@ -78,6 +78,7 @@ import {
   prepareReadSet,
 } from '@abloatai/transaction/internal/read-set';
 import { contextOnChange } from '../sync/contextOnChange.js';
+import { resolveScopeGroups } from '../sync/scopeGroups.js';
 import type { ReadDependency } from '@abloatai/transaction/coordination';
 import type { CapturedRow } from '@abloatai/transaction/transport/http';
 
@@ -575,6 +576,20 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
       hydration,
       {
         presence: (model, recordId) => presenceStream.forModel(model, recordId),
+        onPresenceChange: (listener) => presenceStream.onChange(listener),
+        startReadPresence: (target) => presenceStream.startRead(target),
+        modelEventTarget: (recordId) => {
+          const syncGroup = resolveScopeGroups({ [schemaKey]: recordId }, schema)[0];
+          if (syncGroup === undefined) {
+            throw new AbloValidationError('A model event requires a record scope.', {
+              code: 'invalid_request',
+              param: 'recordId',
+            });
+          }
+          return { model: registeredModelName, id: recordId, syncGroup };
+        },
+        sendModelEvent: (input) => { transport.sendModelEvent(input); },
+        onModelEvent: (listener) => transport.subscribe('model_event', listener),
         createClaim: (claimOptions) => publicClaims.create(claimOptions),
         // Lazily referenced: `commits` is declared below this loop, and this
         // only runs when someone actually writes a batch.
@@ -617,6 +632,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
         // stay fire-and-forget. It's soft either way — the store swallows
         // reconcile errors so read interest never makes a read reject or stall.
         enterScope: (scope) => store.enterScope(scope),
+        leaveScope: (scope) => store.leaveScope(scope),
         pinScope: (scope) => store.pinScope(scope),
       },
       readSetContext,

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

@@ -4,6 +4,14 @@ import {
   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 {
@@ -13,7 +21,8 @@ export interface ReactivePresence extends PresenceView {
 
 /** Lifecycle hooks kept inside the humans composition boundary. */
 export interface AttachablePresence extends ReactivePresence {
-  attach(transport: PresenceProjectionEvents): void;
+  attach(transport: PresenceTransport): void;
+  startRead(target: PresenceTarget): () => void;
   dispose(): void;
 }
 
@@ -31,18 +40,21 @@ export function presenceOfClient(client: object): ReactivePresence {
 }
 
 export function createPresence(
-  transport: PresenceProjectionEvents | null = null,
+  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: PresenceProjectionEvents): void => {
+  const attach = (events: PresenceTransport): void => {
     if (projection !== null) return;
+    attachedTransport = events;
     projection = createPresenceProjection(events);
     unsubscribe = projection.subscribe(notify);
     notify();
@@ -58,14 +70,31 @@ export function createPresence(
       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();
     },
   };