@abloatai/humans 0.62.0 → 0.63.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { Ablo } from './Ablo.js';
 export type { AbloOptions, AbloReads, CredentialProvider, InternalAbloOptions, ModelClaim, ModelTarget, } 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, PipelineStage, PluginById, TransportCapabilities, } from './plugin.js';
 export { defineMutators, type MutatorDefs, type MutatorFn, } from './local/mutators/defineMutators.js';
 export { createTransaction, type Transaction, type ReaderFindOptions, } from './local/mutators/Transaction.js';

package/dist/local/InstanceCache.js

@@ -1019,7 +1019,7 @@ export class InstanceCache {
         });
     }
     startGC() {
-        if (this.gcTimer)
+        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

package/dist/local/client/createModelOperations.d.ts

@@ -23,10 +23,16 @@ import type { ClaimApi, ClaimAttemptEvent, LocalCountOptions, LocalReadOptions }
 import type { HttpModelClient } 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 { type ReadSetContext } from '@abloatai/transaction/internal/read-set';
 export interface ModelClientMeta {
     readonly key: string;
     readonly typename: string;
+    readonly presence?: {
+        get(recordId: string): readonly PresenceSession[];
+        subscribe(listener: () => void): () => void;
+        read(recordId: string): () => void;
+    };
 }
 export declare function getModelClientMeta(modelClient: unknown): ModelClientMeta | undefined;
 /**
@@ -37,6 +43,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;
@@ -138,6 +151,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
@@ -192,6 +207,8 @@ interface ReactiveModelSurface<T, Fields = T> {
     local: LocalReads<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
@@ -222,6 +239,10 @@ interface ReactiveModelSurface<T, Fields = T> {
     /** Subscribe to changes; the callback runs on every change. */
     onChange(callback: (entities: T[]) => void, options?: LocalReadOptions<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;
+}
 /**
  * Everything reachable as `ablo.<model>` on a reactive client.
  *

package/dist/local/client/createModelOperations.js

@@ -30,15 +30,40 @@ import { declaredMeta } from '@abloatai/transaction/claims';
 import { ModelScope } from '@abloatai/transaction/types';
 import { bindClaimLifetime, claimLifetimeOf, } from '@abloatai/transaction/claims/lifetime';
 import { claimQueueView, resolveClaimContentionOptions, } from '@abloatai/transaction/client/resources/modelOperations';
+import { modelEventInputSchema } from '@abloatai/transaction/collaboration';
 import { capturePointRead, prepareReadSet, } from '@abloatai/transaction/internal/read-set';
 const ignoreSeparatelyObservedMutationFailure = () => undefined;
 const ignoreBestEffortClaimReleaseFailure = () => undefined;
+const ignoreBestEffortScopeFailure = () => undefined;
 const modelClientMeta = new WeakMap();
 export function getModelClientMeta(modelClient) {
     if (typeof modelClient !== 'object' || modelClient === null)
         return undefined;
     return modelClientMeta.get(modelClient);
 }
+function subscribeInModelScope(collaboration, scope, subscribe) {
+    let stopped = false;
+    let entered = false;
+    let unsubscribe = 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);
+    };
+}
 export function createModelOperations(schemaKey, registeredModelName, objectPool, syncClient, registry, 
 /**
  * The one thing this factory asks of the loader: fetch rows for a model.
@@ -830,6 +855,50 @@ hydration, collaboration, readSetContext) {
     const operations = {
         local,
         presence: (recordId) => 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,
         // No automatic scope enrolment on bulk `list`: that would subscribe to an
@@ -1019,6 +1088,21 @@ hydration, collaboration, readSetContext) {
     modelClientMeta.set(operations, {
         key: schemaKey,
         typename: registeredModelName,
+        ...(collaboration
+            ? {
+                presence: {
+                    get: (recordId) => collaboration.presence(registeredModelName, recordId),
+                    subscribe: (listener) => collaboration.onPresenceChange(listener),
+                    read: (recordId) => {
+                        const scope = { [schemaKey]: recordId };
+                        return subscribeInModelScope(collaboration, scope, () => collaboration.startReadPresence({
+                            model: registeredModelName,
+                            id: recordId,
+                        }));
+                    },
+                },
+            }
+            : {}),
     });
     return operations;
 }

package/dist/local/client/reactiveEngine.js

@@ -29,6 +29,7 @@ import { modelReadResponseSchema, commitRecordSchema, commitRecordListSchema, co
 import { translateHttpError, } from '@abloatai/transaction/errors';
 import { kReadEvidence, prepareReadSet, } from '@abloatai/transaction/internal/read-set';
 import { contextOnChange } from '../sync/contextOnChange.js';
+import { resolveScopeGroups } from '../sync/scopeGroups.js';
 export function buildReactiveEngine(inputs) {
     const { options, internalOptions, url, logger, configuredApiKey, configuredAuthToken, credentialResolver, authCredentials, transport, participantId, kind, presence, cluster, } = inputs;
     const schema = options.schema;
@@ -394,6 +395,20 @@ export function buildReactiveEngine(inputs) {
         const registeredModelName = modelDef.typename ?? schemaKey;
         modelProxies[schemaKey] = createModelOperations(schemaKey, registeredModelName, objectPool, syncClient, modelRegistry, 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.
@@ -432,6 +447,7 @@ export function buildReactiveEngine(inputs) {
             // 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/dist/local/transactions/mutations/MutationQueue.d.ts

@@ -116,6 +116,8 @@ export declare class MutationQueue extends EventEmitter {
     private isProcessing;
     private processTimer?;
     private processScheduled;
+    private disposed;
+    private retryTimers;
     private createdTransactions;
     private commitScheduled;
     private inFlightByModel;
@@ -343,6 +345,7 @@ export declare class MutationQueue extends EventEmitter {
      */
     onDeltaReceived(syncId: number, _transactionId?: string, correlationId?: string): void;
     private scheduleDeltaConfirmationTimeout;
+    private scheduleRetry;
     /**
      * Resolves once the given transaction is confirmed and rejects if it fails.
      * The confirming delta's timeout is handled by

package/dist/local/transactions/mutations/MutationQueue.js

@@ -74,6 +74,8 @@ export class MutationQueue extends EventEmitter {
     isProcessing = false;
     processTimer;
     processScheduled = false;
+    disposed = false;
+    retryTimers = new Set();
     // Staging area for transactions created in the same event-loop tick. Each one
     // lands here first, then a microtask commits them together.
     createdTransactions = [];
@@ -149,11 +151,14 @@ 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); },
@@ -276,6 +281,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),
@@ -655,6 +661,8 @@ export class MutationQueue extends EventEmitter {
      * optimistic state, or remove the durable replay envelope.
      */
     scheduleReplicationLagTimeout(transactionId, clientTxId = transactionId, correlationId) {
+        if (this.disposed)
+            return;
         const previous = this.replicationLagTimeouts.get(transactionId);
         if (previous)
             clearTimeout(previous);
@@ -846,6 +854,8 @@ export class MutationQueue extends EventEmitter {
      * {@link drainPending} resumes the work when the owner decides to drain.
      */
     setConnectionState(state) {
+        if (this.disposed)
+            return;
         if (state === 'connected') {
             if (this.commitOfflineGraceTimer !== null) {
                 clearTimeout(this.commitOfflineGraceTimer);
@@ -1013,12 +1023,16 @@ export class MutationQueue extends EventEmitter {
         enqueueTransaction(this.queueCoalescingContext, transaction);
     }
     scheduleProcessing(immediate = false) {
+        if (this.disposed)
+            return;
         scheduleProcessingExternal(this.processingSchedulerContext, immediate);
     }
     async processBatch() {
+        if (this.disposed)
+            return;
         if (this.modelProcessingPromise) {
             await this.modelProcessingPromise;
-            if (this.executionQueue.length > 0)
+            if (!this.disposed && this.executionQueue.length > 0)
                 await this.processBatch();
             return;
         }
@@ -1103,8 +1117,20 @@ export class MutationQueue extends EventEmitter {
     // Schedule the retry-and-reconciliation wait for a transaction's confirming
     // delta; see {@link DeltaConfirmationTracker} in `./deltaConfirmation.js`.
     scheduleDeltaConfirmationTimeout(tx, timeoutMs) {
+        if (this.disposed)
+            return;
         this.deltaConfirmation.scheduleDeltaConfirmationTimeout(tx, timeoutMs);
     }
+    scheduleRetry(callback, delayMs) {
+        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
@@ -1156,6 +1182,8 @@ export class MutationQueue extends EventEmitter {
         return enqueueCommit(this.commitApiContext, clientTxId, operations, options);
     }
     async processCommitLane() {
+        if (this.disposed)
+            return;
         await processCommitLane(this.commitLaneContext);
     }
     waitForCommitReceipt(clientTxId) {
@@ -1388,6 +1416,9 @@ export class MutationQueue extends EventEmitter {
      * clears all timers and stored transactions, and removes event listeners.
      */
     dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
         // Cancel all active optimistic updates
         for (const [, optimistic] of this.localMutationPort.updates) {
             this.emit('optimistic:rollback', {
@@ -1419,6 +1450,9 @@ 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();
         this.localMutationPort.updates.clear();

package/dist/local/transactions/mutations/deltaConfirmation.d.ts

@@ -40,6 +40,7 @@ export declare class DeltaConfirmationTracker {
     private static readonly DELTA_MAX_TIMEOUT_MS;
     private deltaConfirmationTimeouts;
     private deltaConfirmationRetries;
+    private disposed;
     private readonly runtime;
     constructor(ctx: DeltaConfirmationContext);
     /** Applied-cursor alias, kept so the read sites below stay legible. */

package/dist/local/transactions/mutations/deltaConfirmation.js

@@ -20,6 +20,7 @@ export class DeltaConfirmationTracker {
     deltaConfirmationTimeouts = new Map();
     // Track retry attempts per transaction for exponential backoff
     deltaConfirmationRetries = new Map();
+    disposed = false;
     runtime;
     constructor(ctx) {
         this.ctx = ctx;
@@ -113,6 +114,8 @@ export class DeltaConfirmationTracker {
     // server has already confirmed. A rollback happens only on an explicit server
     // rejection, never on a timeout.
     scheduleDeltaConfirmationTimeout(tx, timeoutMs) {
+        if (this.disposed)
+            return;
         // Cancel any existing timeout for this transaction
         this.cancelDeltaConfirmationTimeout(tx.id);
         // Deliberately not an async callback: the body is fully synchronous, and
@@ -226,6 +229,7 @@ export class DeltaConfirmationTracker {
      * would keep the process alive and fire callbacks against a cleared store.
      */
     dispose() {
+        this.disposed = true;
         for (const timeoutHandle of this.deltaConfirmationTimeouts.values()) {
             clearTimeout(timeoutHandle);
         }

package/dist/local/transactions/mutations/failureHandling.d.ts

@@ -9,6 +9,7 @@ export interface FailureHandlingContext {
     readonly isPermanentError: (error: Error) => boolean;
     readonly rollbackOptimistic: (transaction: QueuedMutation, reason: string, 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;

package/dist/local/transactions/mutations/failureHandling.js

@@ -54,7 +54,7 @@ export async function handleFailure(ctx, transaction, error) {
         // stall unrelated commits.
         const delay = transientRetryDelayMs(error, transaction.attempts, ctx.config.retryBackoff);
         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')

package/dist/presence/index.d.ts

@@ -1,4 +1,7 @@
 import { type PresenceProjection, type PresenceProjectionEvents, type PresenceView } from '@abloatai/transaction/presence';
+import type { PresenceTarget } from '@abloatai/transaction/presence';
+import { 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']>;
@@ -6,10 +9,12 @@ 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;
 }
 /** Framework bridge that does not consume a string key on the model namespace. */
 export declare function attachPresenceToClient(client: object, presence: ReactivePresence): void;
 export declare function presenceOfClient(client: object): ReactivePresence;
-export declare function createPresence(transport?: PresenceProjectionEvents | null): AttachablePresence;
+export declare function createPresence(transport?: PresenceTransport | null): AttachablePresence;
+export {};

package/dist/presence/index.js

@@ -1,4 +1,5 @@
 import { createPresenceProjection, } from '@abloatai/transaction/presence';
+import { startReadActivity, } from './readActivity.js';
 const clientPresence = new WeakMap();
 /** Framework bridge that does not consume a string key on the model namespace. */
 export function attachPresenceToClient(client, presence) {
@@ -12,7 +13,9 @@ export function presenceOfClient(client) {
 }
 export function createPresence(transport = null) {
     let projection = null;
+    let attachedTransport = null;
     const listeners = new Set();
+    const reads = new Set();
     let unsubscribe = null;
     const notify = () => {
         for (const listener of listeners)
@@ -21,6 +24,7 @@ export function createPresence(transport = null) {
     const attach = (events) => {
         if (projection !== null)
             return;
+        attachedTransport = events;
         projection = createPresenceProjection(events);
         unsubscribe = projection.subscribe(notify);
         notify();
@@ -35,14 +39,28 @@ export function createPresence(transport = null) {
             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/dist/presence/readActivity.d.ts

@@ -0,0 +1,19 @@
+import type { PresenceCommand, PresenceTarget } from '@abloatai/transaction/presence';
+/** 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;
+}
+/**
+ * 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 declare function startReadActivity(transport: ReadActivityTransport, target: PresenceTarget, onFinished?: () => void): ReadActivityLifetime;

package/dist/presence/readActivity.js

@@ -0,0 +1,122 @@
+import { LEASE_TTL_MS } from '@abloatai/transaction/wire';
+const READ_TTL_MS = LEASE_TTL_MS;
+const READ_REFRESH_MS = READ_TTL_MS / 3;
+let fallbackActivitySequence = 0;
+const noop = () => undefined;
+function readActivityId() {
+    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) {
+    const candidate = timer;
+    if (typeof candidate === 'object' &&
+        candidate !== null &&
+        'unref' in candidate &&
+        typeof candidate.unref === 'function') {
+        candidate.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, target, onFinished = noop) {
+    const activityId = readActivityId();
+    let active = true;
+    let disposed = false;
+    let removeOnConnect = null;
+    let removalExpiry = null;
+    let finished = false;
+    const finish = () => {
+        if (finished)
+            return;
+        finished = true;
+        onFinished();
+    };
+    const send = (command) => {
+        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 = () => {
+        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 = () => {
+        unsubscribeConnected();
+        clearInterval(refreshTimer);
+        removeOnConnect?.();
+        removeOnConnect = null;
+        if (removalExpiry !== null)
+            clearTimeout(removalExpiry);
+        removalExpiry = null;
+    };
+    const stop = () => {
+        if (!active || disposed)
+            return;
+        active = false;
+        unsubscribeConnected();
+        clearInterval(refreshTimer);
+        const remove = () => {
+            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/dist/react/createAbloReact.d.ts

@@ -25,6 +25,8 @@ import { type AbloSelector, type ModelClientSelector, type UseAbloHydratedModelR
 import type { AbloClient as Ablo } from '../client.js';
 import type { ModelOperations } from '../local/client/createModelOperations.js';
 import type { Schema, SchemaRecord } from '@abloatai/transaction/schema/schema';
+import { type PresenceModelSelector } from './usePresence.js';
+import type { PresenceSession } from '@abloatai/transaction/presence';
 /** What a binding returns: the provider and the hook, with `S` fixed. */
 export interface AbloReactBinding<S extends SchemaRecord> {
     /** `AbloProvider` with its `client` prop typed `Ablo<S>` — same component,
@@ -40,6 +42,8 @@ export interface AbloReactBinding<S extends SchemaRecord> {
         }): UseAbloHydratedModelResult<T>;
         <T, C>(modelClientOrSelect: ModelOperations<T, C> | ModelClientSelector<S, T, C>, id: string, options?: UseAbloModelOptions<T>): UseAbloModelResult<T>;
     };
+    /** Declare and reactively read record presence with the same model clients. */
+    usePresence: <T, C>(modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<S, T, C>, recordId: string) => readonly PresenceSession[];
 }
 /**
  * Bind the react surface to one schema. The schema value is taken for