@abloatai/humans 0.62.0 → 0.63.0

package/src/presence/readActivity.ts

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

package/src/react/createAbloReact.ts

@@ -29,6 +29,7 @@ import {
 } from './AbloProvider.js';
 import {
   useAbloImpl,
+  useAbloClientImpl,
   type AbloSelector,
   type ModelClientSelector,
   type UseAbloHydratedModelResult,
@@ -38,6 +39,11 @@ import {
 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 {
+  usePresenceImpl,
+  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> {
@@ -60,6 +66,11 @@ export interface AbloReactBinding<S extends SchemaRecord> {
       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[];
 }
 
 /**
@@ -112,5 +123,18 @@ export function createAbloReact<S extends SchemaRecord>(
     return useAbloImpl<S, T, C>(bound, modelOrSelect, id, options);
   }
 
-  return { AbloProvider: BoundAbloProvider, useAblo: useBoundAblo };
+  function useBoundPresence<T, C>(
+    modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<S, T, C>,
+    recordId: string,
+  ): readonly PresenceSession[] {
+    const bound = useContext(BoundClientContext);
+    const engine = useAbloClientImpl(bound);
+    return usePresenceImpl(engine, modelOrSelect, recordId);
+  }
+
+  return {
+    AbloProvider: BoundAbloProvider,
+    useAblo: useBoundAblo,
+    usePresence: useBoundPresence,
+  };
 }

package/src/react/useAblo.ts

@@ -223,12 +223,7 @@ export function useAbloImpl<
   id?: string,
   options?: UseAbloModelOptions<T>,
 ): Ablo<R> | null | UseAbloModelResult<T> | T | undefined {
-  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: Ablo<R> | null =
-    boundClient ?? (ctx?.engine ? rebindEngine<R>(ctx.engine) : null);
+  const engine = useAbloClientImpl(boundClient);
   const initial = options?.initial;
   const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
   const modelClient: ModelOperations<T, C> | undefined =
@@ -278,3 +273,16 @@ export function useAbloImpl<
   if (modelOrSelect) return modelResult;
   return engine;
 }
+
+/** @internal Resolve the bound or legacy provider client through one rebind seam. */
+export function useAbloClientImpl<R extends SchemaRecord>(
+  boundClient: Ablo<R> | null,
+): Ablo<R> | null {
+  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: Ablo<R> | null =
+    boundClient ?? (ctx?.engine ? rebindEngine<R>(ctx.engine) : null);
+  return engine;
+}

package/src/react/usePresence.ts

@@ -0,0 +1,88 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import type { PresenceSession } from '@abloatai/transaction/presence';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+import {
+  getModelClientMeta,
+  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';
+import { useAbloClientImpl } from './useAblo.js';
+
+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 function usePresence<T, C>(
+  modelClient: ModelOperations<T, C>,
+  recordId: string,
+): readonly PresenceSession[];
+export function usePresence<
+  R extends SchemaRecord = DefaultModels,
+  T = Record<string, unknown>,
+  C = unknown,
+>(
+  select: PresenceModelSelector<R, T, C>,
+  recordId: string,
+): readonly PresenceSession[];
+export function usePresence<
+  R extends SchemaRecord = DefaultModels,
+  T = Record<string, unknown>,
+  C = unknown,
+>(
+  modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<R, T, C>,
+  recordId: string,
+): readonly PresenceSession[] {
+  const engine = useAbloClientImpl<R>(null);
+  return usePresenceImpl(engine, modelOrSelect, recordId);
+}
+
+/** @internal Shared by the global hook and schema-bound React factory. */
+export function usePresenceImpl<R extends SchemaRecord, T, C>(
+  engine: Ablo<R> | null,
+  modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<R, T, C>,
+  recordId: string,
+): readonly PresenceSession[] {
+  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/src/react.ts

@@ -3,6 +3,10 @@ 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,

package/src/surface.ts

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