@abloatai/humans 0.61.0 → 0.63.0

package/dist/presence/index.d.ts

@@ -0,0 +1,20 @@
+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']>;
+    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;
+}
+/** 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?: PresenceTransport | null): AttachablePresence;
+export {};

package/dist/presence/index.js

@@ -0,0 +1,67 @@
+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) {
+    clientPresence.set(client, presence);
+}
+export function presenceOfClient(client) {
+    const presence = clientPresence.get(client);
+    if (presence === undefined)
+        throw new Error('presence is not attached to this client');
+    return presence;
+}
+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)
+            listener();
+    };
+    const attach = (events) => {
+        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/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/AbloProvider.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from 'react';
 import type { 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 { type SyncStoreContract } from './context.js';
 /**
@@ -109,7 +109,7 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
 export declare function AbloProvider<R extends SchemaRecord = SchemaRecord>(props: AbloProviderProps<R>): React.ReactElement;
 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.
  *
@@ -127,7 +127,7 @@ export type { GroupScope };
  * const alone = !peers.some((p) => p.participantKind === 'user');
  * ```
  */
-export declare function usePeers(scope?: GroupScope): readonly Peer[];
+export declare function usePeers(scope?: GroupScope): readonly PresenceSession[];
 /**
  * Returns the raw `SyncEngine` proxy. Typically you want the typed
  * hooks (`useQuery`, `useOne`, `useMutate`) — this is for rare cases

package/dist/react/AbloProvider.js

@@ -7,6 +7,7 @@ import { AbloInternalContext } from './internalContext.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { useSyncStatus } from './useSyncStatus.js';
 import { DefaultFallback } from './DefaultFallback.js';
+import { presenceOfClient } from '../presence/index.js';
 // ── Implementation ───────────────────────────────────────────────────
 /**
  * Lightweight event emitter for provider-level errors. Lives on the
@@ -201,7 +202,7 @@ function BootstrapGate({ fallback, children, }) {
 }
 const EMPTY_PRESENCE = Object.freeze([]);
 /**
- * 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.
  *
@@ -232,10 +233,10 @@ export function usePeers(scope) {
             setPeers(EMPTY_PRESENCE);
             return;
         }
-        const presence = engine.presence;
+        const presence = presenceOfClient(engine);
         const compute = () => 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
         // rarely; a frame of stale presence is harmless.

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

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", "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

@@ -26,6 +26,8 @@ export const PUBLIC_MODEL_VERBS = [
     'list',
     'listAll',
     'local',
+    'presence',
+    'events',
     'create',
     'update',
     'delete',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.61.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.61.0",
+    "@abloatai/transaction": "^0.63.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/Ablo.ts

@@ -99,7 +99,7 @@ export type Ablo<S extends SchemaRecord> = AbloClient<S>;
  * const ablo = Ablo({ schema, session: { endpoint: '/api/ablo-session' } });
  * ```
  *
- * Server-side agents, workers, and services use `@abloatai/transaction`.
+ * Server-side agents, workers, and services use `@abloatai/ablo`.
  */
 export function Ablo<
   const S extends SchemaRecord,
@@ -117,7 +117,15 @@ export function Ablo<const S extends SchemaRecord>(
   //    resolver, the base URL, the logger, and this participant's identity —
   //    and fails on a misconfiguration before anything is constructed.
   const prelude = resolveClientPrelude(options);
-  const { internalOptions, authCredentials, logger, url, participantId, kind } = prelude;
+  const {
+    internalOptions,
+    authCredentials,
+    presenceSession,
+    logger,
+    url,
+    participantId,
+    kind,
+  } = prelude;
 
   // 2. The connection, built here in the composition root — before the plugin
   //    list resolves, so `PluginContext.transport` carries the instance a
@@ -134,6 +142,7 @@ export function Ablo<const S extends SchemaRecord>(
         baseUrl: url,
         kind,
         getAuthToken: authCredentials.getAuthToken,
+        presenceSession,
         collaborationEvents: [...(internalOptions.collaborationEvents ?? [])],
         syncGroups: [...(internalOptions.syncGroups ?? [])],
         deferConnect: true,
@@ -223,7 +232,7 @@ export function Ablo<const S extends SchemaRecord>(
 //
 // One default import, with types hung underneath via namespace dots:
 // `import { Ablo } from "@abloatai/humans"` gets the factory, its return type, and
-// every type a typical consumer references (`Ablo.Peer`,
+// every type a typical consumer references (`Ablo.PresenceSession`,
 // and so on) — all purely type-level, with zero runtime cost.
 //
 // The types still live in their canonical homes (`types/streams`, `principal`,
@@ -272,10 +281,10 @@ export namespace Ablo {
   export type Duration = _Streams.Duration;
 
   // ── Real-time multiplayer (flat — heterogeneous cluster) ──────────
-  export type PresenceStream = _Streams.PresenceStream;
+  export type Presence = import('./presence/index.js').ReactivePresence;
+  export type PresenceSession = import('@abloatai/transaction/presence').PresenceSession;
+  export type PresenceActivity = import('@abloatai/transaction/presence').PresenceActivity;
   export type ClaimStream = _Streams.ClaimStream;
-  export type Peer = _Streams.Peer;
-  export type Activity = _Streams.Activity;
   export type Claim = _Streams.Claim;
   export type ClaimRejection = _Streams.ClaimRejection;
   export type ClaimLost = _Streams.ClaimLost;

package/src/client.ts

@@ -18,7 +18,6 @@ import type {
   InferCreate,
   InferRow,
 } from '@abloatai/transaction/schema/schema';
-import type { PresenceStream } from '@abloatai/transaction/types/streams';
 import type { InstanceCache } from './local/InstanceCache.js';
 import type { SyncStoreContract } from './react/context.js';
 import type { SyncWebSocket, CoreSyncEventMap } from './local/sync/SyncWebSocket.js';
@@ -31,6 +30,7 @@ import type {
 import type { EffectiveAuthority } from '@abloatai/transaction/auth';
 import type { ReadDependency } from '@abloatai/transaction/coordination';
 import type { CapturedRow } from '@abloatai/transaction/transport/http';
+import type { ReactivePresence } from './presence/index.js';
 export type { LocalReadOptions } from './local/client/resourceTypes.js';
 
 /** The typed sync engine client — one property per model in the schema */
@@ -232,20 +232,15 @@ export type AbloClient<S extends SchemaRecord> = {
    */
   readonly syncStatus: SyncStatus;
 
-  /** The underlying schema */
-  readonly schema: Schema<S>;
-
   /**
-   * A real-time presence livestream — who else is connected on this engine's
-   * sync groups, what they're doing, and a write surface for announcing this
-   * user's own activity. It rides the engine's existing WebSocket; opening a
-   * participant for presence does not open a second socket. See
-   * {@link PresenceStream}.
-   *
-   * The reference is stable for the engine's lifetime — the underlying connection
-   * is rotated on `dispose()`, but this object stays the same.
+   * Session-owned live activity projected from this client's existing
+   * connection. Use `active` for every visible activity, `others` to exclude
+   * this session, and `forModel(model, id?)` for a model-native view.
    */
-  readonly presence: PresenceStream;
+  readonly presence: ReactivePresence;
+
+  /** The underlying schema */
+  readonly schema: Schema<S>;
 
   /**
    * @internal The supported coordination API is `ablo.<model>.claim`. This

package/src/humans.ts

@@ -7,7 +7,7 @@
  */
 import type { AbloPlugin, PluginContext, AppliedChange } from './plugin.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
-import { createPresenceStream, type AttachablePresenceStream } from './presenceStream.js';
+import { createPresence, type AttachablePresence } from './presence/index.js';
 import {
   buildStoreCluster,
   kStoreCluster,
@@ -16,7 +16,7 @@ import {
 } from './local/client/storeCluster.js';
 
 export interface HumansSurface {
-  readonly presence: AttachablePresenceStream;
+  readonly presence: AttachablePresence;
   readonly [kStoreCluster]?: StoreCluster;
 }
 
@@ -45,14 +45,7 @@ export function humans() {
         applyChanges = (changes) => { cluster.store.applyChangesToPool(changes); };
       }
       return {
-        presence: createPresenceStream(
-          {
-            participantId: context.participant?.id ?? '',
-            syncGroups: [...(context.syncGroups ?? [])],
-            isAgent: context.participant?.kind === 'agent',
-          },
-          context.transport ?? null,
-        ),
+        presence: createPresence(context.transport ?? null),
         ...(cluster ? { [kStoreCluster]: cluster } : {}),
       };
     },

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/BaseSyncedStore.ts

@@ -35,7 +35,6 @@ import {
   type GroupRemovedPayload,
   type BootstrapHint,
   type BootstrapDataEvent,
-  type PresenceUpdate,
   type EventMap,
   type DefaultCollaborationEvents,
   type SyncWebSocketEventMap,
@@ -238,7 +237,6 @@ export type {
   GroupRemovedPayload,
   BootstrapHint,
   BootstrapDataEvent,
-  PresenceUpdate,
 };
 
 // deriveSyncPlanFromSchema derives a sync plan from a schema and is
@@ -1500,7 +1498,6 @@ export class BaseSyncedStore<
       applyDeltaFrame: (deltas) => { this.applyDeltaFrame(deltas); },
       handleBootstrapRequired: (hint) => { this.handleBootstrapRequired(hint); },
       handleBootstrapData: (data) => { this.handleBootstrapData(data); },
-      handlePresenceUpdate: (data) => { this.handlePresenceUpdate(data); },
       performCredentialRefresh: () => this.performCredentialRefresh(),
       handleTerminalSessionError: (error) => { this.terminalSessionLifecycle.start(error); },
       nudgeReconnect: () => { this.nudgeReconnect(); },
@@ -1935,9 +1932,6 @@ export class BaseSyncedStore<
     this.updateSyncStatus({ state: 'syncing' });
   }
 
-  /** Handle presence_update event. Override in subclass. */
-  protected handlePresenceUpdate(_data: PresenceUpdate): void {}
-
   // ── Pending changes tracking ─────────────────────────────────────────────
 
   protected incrementPendingChanges(): void {