@abloatai/humans 0.61.0 → 0.62.0

package/src/local/client/clientPrelude.ts

@@ -13,12 +13,17 @@
  */
 
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import { AbloValidationError } from '@abloatai/transaction/errors';
 import type { Logger } from '@abloatai/transaction/logger';
 import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
 import {
   createAuthCredentialSource,
   type AuthCredentialSource,
 } from '@abloatai/transaction/auth/credentialSource';
+import {
+  createPresenceSessionSource,
+  type PresenceSessionSource,
+} from '@abloatai/transaction/presence';
 import {
   assertBrowserSafety,
   readProcessEnv,
@@ -47,6 +52,7 @@ export interface ClientPrelude<S extends SchemaRecord> {
    */
   readonly credentialResolver: CredentialProvider | null;
   readonly authCredentials: AuthCredentialSource;
+  readonly presenceSession: PresenceSessionSource;
   readonly logger: Logger;
   readonly url: string;
   /**
@@ -69,6 +75,17 @@ export interface ClientPrelude<S extends SchemaRecord> {
 export function resolveClientPrelude<S extends SchemaRecord>(
   options: AbloOptions<S>,
 ): ClientPrelude<S> {
+  // This package owns the reactive materialiser, not transport selection.
+  // TypeScript can miss excess properties on generic calls and object spreads,
+  // so reject a misplaced selector before resolving any credentials or
+  // constructing local state. The core `Ablo` client owns `transport`.
+  if ('transport' in options) {
+    throw new AbloValidationError(
+      "The reactive client does not accept `transport`. Import `Ablo` from " +
+        "'@abloatai/ablo' when selecting HTTP or WebSocket transport.",
+      { code: 'invalid_options', param: 'transport' },
+    );
+  }
   const env = readProcessEnv();
   const internalOptions = {
     ...options,
@@ -79,9 +96,11 @@ export function resolveClientPrelude<S extends SchemaRecord>(
   const configuredApiKey = resolveApiKey(authInput);
   const configuredAuthToken = resolveAuthToken(authInput);
   const credentialResolver = resolveCredentialResolver(configuredApiKey);
+  const presenceSession = createPresenceSessionSource();
   const authCredentials = createAuthCredentialSource(
     // eslint-disable-next-line @typescript-eslint/no-deprecated -- load-bearing on the self-hosted path; server-internal cap-mint (Phase 3) not shipped
     internalOptions.capabilityToken ?? configuredAuthToken,
+    presenceSession,
   );
   rejectRemovedDatabaseUrlOption(options);
   assertBrowserSafety({
@@ -108,6 +127,7 @@ export function resolveClientPrelude<S extends SchemaRecord>(
     configuredAuthToken,
     credentialResolver,
     authCredentials,
+    presenceSession,
     logger,
     url: resolveBaseURL(authInput),
     participantId,

package/src/local/client/createInternalComponents.ts

@@ -90,6 +90,7 @@ export function createInternalComponents<S extends SchemaRecord>(
     syncGroups: options.syncGroups,
     instantModels: deriveInstantModels(schema),
     getAuthToken: auth?.getAuthToken,
+    presenceSession: auth?.presenceSession,
     runtime,
   });
 
@@ -120,6 +121,7 @@ export function createInternalComponents<S extends SchemaRecord>(
     schema,
     baseUrl: bootstrapBaseUrl,
     getAuthToken: auth?.getAuthToken,
+    presenceSession: auth?.presenceSession,
     runtime,
     // The one canonical log position; the loader reads its floor when a query
     // leaves so a late answer cannot overwrite a row the pool already knows to

package/src/local/client/createModelOperations.ts

@@ -143,6 +143,7 @@ import type {
   HttpModelClient,
 } from '@abloatai/transaction/transport/http';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import type { PresenceSession } from '@abloatai/transaction/presence';
 import {
   capturePointRead,
   prepareReadSet,
@@ -177,6 +178,8 @@ type EntityHalf = Pick<ModelTarget, 'model' | 'id'>;
 // `ModelCollaboration<Item>` and `ModelCollaboration<Invoice>` the same type
 // while reading as though they differed.
 export interface ModelCollaboration {
+  /** Session projections already held by this client's one presence store. */
+  presence(model: string, recordId?: string): readonly PresenceSession[];
   /** Exact point evidence from the HTTP read boundary (stamp captured before data). */
   readPoint(model: string, id: string): Promise<{ data: unknown; stamp: number }>;
   /**
@@ -336,6 +339,9 @@ interface ReactiveModelSurface<T, Fields = T> {
   /** The synchronous local-graph reads. */
   local: LocalReads<T>;
 
+  /** Sessions currently active on this model, optionally narrowed to one record. */
+  presence(recordId?: string): readonly PresenceSession[];
+
   /**
    * 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
@@ -1403,6 +1409,8 @@ export function createModelOperations<T, C>(
   const operations: ModelOperations<T, C> = {
     local,
 
+    presence: (recordId?: string) => collaboration?.presence(registeredModelName, recordId) ?? [],
+
     get,
     read,
 

package/src/local/client/reactiveEngine.ts

@@ -39,7 +39,10 @@ import {
   bindClaimLifetime,
   claimLifetimeOf,
 } from '@abloatai/transaction/claims/lifetime';
-import type { AttachablePresenceStream } from '../../presenceStream.js';
+import {
+  attachPresenceToClient,
+  type AttachablePresence,
+} from '../../presence/index.js';
 import type { ClaimWaitOptions } from '@abloatai/transaction/types/streams';
 import type { Claim } from '@abloatai/transaction/types/streams';
 import { resolveApiKeyValue, resolveBootstrapBaseUrl } from '@abloatai/transaction/auth/apiKey';
@@ -96,7 +99,7 @@ export interface ReactiveEngineInputs<S extends SchemaRecord> extends ClientPrel
   transport: SyncWebSocket;
   /** The humans() plugin's contribution — built by its `init`, already
    *  attached to the connection the context carried. */
-  presence: AttachablePresenceStream;
+  presence: AttachablePresence;
   /**
    * The store cluster `humans().init` constructed from the widened context:
    * this client's runtime, the component graph, and the store. The engine
@@ -183,7 +186,11 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
   // filter own echoes by participant id, seeded in `ready()` alongside the
   // locals above.
   const presenceStream = presence;
-  const claimStream = createClaimStream({ participantId, logger }, transport);
+  const claimStream = createClaimStream(
+    { logger },
+    transport,
+    presenceStream,
+  );
 
   // 6. Validate options up front — fail loudly on obviously wrong inputs so
   //    strangers don't get silent empty results. Validation errors are written
@@ -239,17 +246,11 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
     kind,
     logger,
     validationError: _validationError,
-    onIdentityResolved: ({ userId, participantKind, accountScope, syncGroups, authority }) => {
+    onIdentityResolved: ({ userId, participantKind, accountScope, authority }) => {
       selfParticipantId = userId;
       selfParticipantKind = participantKind;
       _resolvedOrganizationId = accountScope;
       _resolvedIdentity = authority;
-      presenceStream.setParticipant({
-        id: userId,
-        kind: participantKind,
-        syncGroups: [...syncGroups],
-      });
-      claimStream.setParticipant({ id: userId });
     },
   });
   const ready = lifecycle.ready;
@@ -573,6 +574,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
       modelRegistry,
       hydration,
       {
+        presence: (model, recordId) => presenceStream.forModel(model, recordId),
         createClaim: (claimOptions) => publicClaims.create(claimOptions),
         // Lazily referenced: `commits` is declared below this loop, and this
         // only runs when someone actually writes a batch.
@@ -831,6 +833,11 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
       return store.syncStatus;
     },
 
+    // The humans capability owns the connection-backed presence projection.
+    // Keep it on the base client as well as in the plugin surface so the
+    // concrete AbloClient contract and runtime object agree before layering.
+    presence: presenceStream,
+
     schema,
 
     // ── Internal accessors for framework integration ─────────────────
@@ -848,10 +855,6 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
     /** The SyncWebSocket — for collaboration events (selection, cursors). */
     get _ws() { return store.getSyncWebSocket(); },
 
-    /** Presence livestream — same socket as entity sync, no second
-     *  connection. Stable reference across the engine's lifetime. */
-    presence: presenceStream,
-
 	    /** Claim livestream — same socket. Stable reference. */
 	    claims: publicClaims,
 
@@ -859,6 +862,8 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 
   } as Ablo<S>;
 
+  attachPresenceToClient(engine, presenceStream);
+
   Object.defineProperty(engine, kReadEvidence, {
     value: {
       context: cluster.readSetContext,

package/src/local/query/client.ts

@@ -20,6 +20,7 @@ import { classifyRecovery, type RecoveryClass } from '@abloatai/transaction/erro
 import { withAuthHeaders, type AuthTokenGetter } from '@abloatai/transaction/auth/credentialSource';
 import { globalRuntime } from '../context.js';
 import type { RuntimeContext } from '../RuntimeContext.js';
+import type { PresenceSessionSource } from '@abloatai/transaction/presence';
 
 // ── Response validation ─────────────────────────────────────────────────
 //
@@ -78,6 +79,8 @@ export interface PostQueryOptions {
    * effect without rebuilding the client.
    */
   capabilityToken?: string;
+  /** Server-bound attribution shared with the owning WebSocket. */
+  presenceSession?: PresenceSessionSource;
 
   /**
    * An optional hook that tries to recover from a rejected credential. When a
@@ -128,6 +131,7 @@ export async function postQuery(
         options.getAuthToken,
         { 'Content-Type': 'application/json' },
         options.capabilityToken,
+        options.presenceSession,
       );
       const response = await fetch(url, {
         method: 'POST',

package/src/local/sync/BootstrapFetcher.ts

@@ -97,6 +97,8 @@ export interface BootstrapOptions {
    * {@link BootstrapFetcher.setAuthToken}.
    */
   getAuthToken?: AuthTokenGetter;
+  /** Server-bound attribution shared with the owning WebSocket. */
+  presenceSession?: import('@abloatai/transaction/presence').PresenceSessionSource;
   /** The owning client's runtime. Defaults to the module-global bridge. */
   runtime?: RuntimeContext;
 }
@@ -186,13 +188,14 @@ function classifyRequestFailure(
 }
 
 export class BootstrapFetcher {
-	  private options: Required<Omit<BootstrapOptions, 'baseUrl' | 'instantModels' | 'organizationId' | 'cacheScope' | 'getAuthToken' | 'runtime'>> & {
+	  private options: Required<Omit<BootstrapOptions, 'baseUrl' | 'instantModels' | 'organizationId' | 'cacheScope' | 'getAuthToken' | 'presenceSession' | 'runtime'>> & {
 	    baseUrl: string;
 	    instantModels?: string[];
 	    cacheScope: string | null;
 	    organizationId?: string;
 	    authToken?: string;
 	    getAuthToken?: AuthTokenGetter;
+	    presenceSession?: import('@abloatai/transaction/presence').PresenceSessionSource;
 	    runtime?: RuntimeContext;
 	  };
 
@@ -311,7 +314,12 @@ export class BootstrapFetcher {
     try {
       const res = await fetch(`${this.options.baseUrl}/schema`, {
         method: 'GET',
-        headers: withAuthHeaders(this.options.getAuthToken, {}, this.options.authToken),
+        headers: withAuthHeaders(
+          this.options.getAuthToken,
+          {},
+          this.options.authToken,
+          this.options.presenceSession,
+        ),
       });
       if (!res.ok) throw new Error(`schema read-back ${res.status}`);
       const body = (await res.json()) as { models?: unknown };
@@ -768,6 +776,7 @@ export class BootstrapFetcher {
 	      this.options.getAuthToken,
 	      { 'Content-Type': 'application/json' },
 	      this.options.authToken,
+	      this.options.presenceSession,
 	    );
 
     const controller = new AbortController();
@@ -977,7 +986,7 @@ export class BootstrapFetcher {
 	          'Content-Type': 'application/json',
 	          'Cache-Control': 'no-cache, no-store, must-revalidate',
 	          Pragma: 'no-cache',
-	        }, this.options.authToken),
+	        }, this.options.authToken, this.options.presenceSession),
         signal: controller.signal,
         cache: 'no-store', // Force browser to not cache
       });
@@ -1049,7 +1058,7 @@ export class BootstrapFetcher {
         method: 'GET',
         headers: withAuthHeaders(this.options.getAuthToken, {
           'Content-Type': 'application/json',
-        }, this.options.authToken),
+        }, this.options.authToken, this.options.presenceSession),
         signal: controller.signal,
       });
     } catch (error) {

package/src/local/sync/OnDemandLoader.ts

@@ -41,6 +41,7 @@ import type { LoadWhere, Query, WhereClause, WhereOp } from '../query/types.js';
 import { normalizeWhere } from '@abloatai/transaction/client/resources/where';
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import type { LogPositionPort } from '../logPosition.js';
+import type { PresenceSessionSource } from '@abloatai/transaction/presence';
 
 export interface OnDemandLoaderOptions {
   readonly objectPool: InstanceCache;
@@ -58,6 +59,7 @@ export interface OnDemandLoaderOptions {
    * propagate without re-instantiating the coordinator.
    */
   readonly getAuthToken?: () => string | null;
+  readonly presenceSession?: PresenceSessionSource;
   /** @deprecated Use `getAuthToken`. */
   readonly getCapabilityToken?: () => string | null;
   /** The owning client's runtime. Defaults to the module-global bridge. */
@@ -647,6 +649,7 @@ export class OnDemandLoader {
         getAuthToken: this.authTokenProvider ?? undefined,
         recoverCredential: this.credentialRecovery ?? undefined,
         runtime: this.opts.runtime,
+        presenceSession: this.opts.presenceSession,
       },
       { queries: [query] },
     );

package/src/local/sync/SyncWebSocket.ts

@@ -36,7 +36,6 @@ export type {
   SyncCapabilities,
   BootstrapHint,
   BootstrapDataEvent,
-  PresenceUpdate,
   CoreSyncEventMap,
   DefaultCollaborationEvents,
   EventMap,
@@ -129,14 +128,10 @@ export class SyncWebSocket<
 
   /**
    * The open ritual, run by the transport between its `connected` emit and the
-   * heartbeat start: announce presence, tell the server where we left off,
+   * heartbeat start: tell the server where we left off,
    * request the deltas we missed, and start the catch-up poll.
    */
   protected override onOpened(): void {
-    // Send presence update with timezone (server sets presence to "online" on connect,
-    // this improves localTime accuracy by providing the user's actual timezone)
-    this.sendPresenceUpdate('online');
-
     // Immediately request incremental sync based on our stored cursor.
     // `requestIncrementalSync` is async — a bare call inside try/catch is a
     // rejection hole (the catch never sees it); route failures through
@@ -323,42 +318,6 @@ export class SyncWebSocket<
     this.sendAck(syncId);
   }
 
-  /**
-   * Send presence update to server.
-   * Use this for:
-   * - Updating timezone (improves localTime accuracy shown to other users)
-   * - Manual status changes (away, custom status)
-   *
-   * Note: "online" status is automatically set by server on WebSocket connect,
-   * and "offline" is set on disconnect. You don't need to call this for basic online/offline.
-   *
-   * @param status - "online", "away", or custom status string
-   * @param customStatus - Optional custom status message
-   */
-  sendPresenceUpdate(
-    status: 'online' | 'away' | 'offline' = 'online',
-    customStatus?: string
-  ): void {
-    if (!this.isConnected()) return;
-
-    const timezone = (() => {
-      try {
-        return Intl.DateTimeFormat().resolvedOptions().timeZone;
-      } catch {
-        return 'UTC';
-      }
-    })();
-
-    this.send({
-      type: 'presence_update',
-      payload: {
-        status,
-        timezone,
-        ...(customStatus ? { customStatus } : {}),
-      },
-    });
-  }
-
   /**
    * Stop the periodic catchup interval
    */

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/presence/index.ts

@@ -0,0 +1,72 @@
+import {
+  createPresenceProjection,
+  type PresenceProjection,
+  type PresenceProjectionEvents,
+  type PresenceView,
+} from '@abloatai/transaction/presence';
+
+/** 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: PresenceProjectionEvents): 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: PresenceProjectionEvents | null = null,
+): AttachablePresence {
+  let projection: PresenceProjection | null = null;
+  const listeners = new Set<() => void>();
+  let unsubscribe: (() => void) | null = null;
+
+  const notify = (): void => {
+    for (const listener of listeners) listener();
+  };
+
+  const attach = (events: PresenceProjectionEvents): void => {
+    if (projection !== null) return;
+    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,
+    forModel(model, recordId) {
+      return projection?.forModel(model, recordId) ?? [];
+    },
+    dispose() {
+      unsubscribe?.();
+      unsubscribe = null;
+      projection?.dispose();
+      projection = null;
+      listeners.clear();
+    },
+  };
+}