@abloatai/humans 0.37.0

package/dist/presenceStream.js

@@ -0,0 +1,200 @@
+/**
+ * Creates a {@link PresenceStream} over a live sync connection. Presence is the
+ * lightweight, ephemeral "who's here and what are they doing" view: each
+ * participant broadcasts a status and an activity, and sees everyone else's.
+ * The stream is built directly on the sync WebSocket and adds no second
+ * connection. It is the sibling of {@link createClaimStream}, which reuses the
+ * same presence frames.
+ *
+ * There are two ways to construct it:
+ *
+ *   1. Direct — pass an already-open `transport`, for example an agent worker
+ *      or a test.
+ *   2. Deferred — construct without a transport and call `attach(transport)`
+ *      once the connection is ready. The returned stream object is stable from
+ *      construction, so callers can hold the reference and let attachment
+ *      happen later.
+ *
+ * Wire frames:
+ *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
+ *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
+ *       other participants on the same sync groups.
+ *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
+ *       `leave`.
+ */
+import { asyncIteratorFrom } from '@abloatai/transaction/utils/asyncIterator';
+import { participantKindFromWire } from '@abloatai/transaction/coordination/schema';
+import { isTargetTuple, subTarget, wireTarget } from '@abloatai/transaction/coordination';
+export function createPresenceStream(config, transport = null) {
+    const { label, syncGroups, isAgent = false } = config;
+    // Mutable: the host seeds the resolved identity via `setParticipant` once
+    // it is known; the own-echo filter always reads the current value.
+    let participantId = config.participantId;
+    // ── Self ─────────────────────────────────────────────────────────
+    const self = {
+        participantKind: isAgent ? 'agent' : 'user',
+        participantId,
+        label,
+        syncGroups: [...syncGroups],
+        activity: { entityType: 'Unknown', entityId: '', action: 'idle' },
+        lastActive: new Date().toISOString(),
+    };
+    // ── Others ───────────────────────────────────────────────────────
+    const othersById = new Map();
+    let othersSnapshot = Object.freeze([]);
+    const listeners = new Set();
+    const notifyListeners = () => {
+        othersSnapshot = Object.freeze(Array.from(othersById.values()));
+        for (const l of listeners) {
+            try {
+                l();
+            }
+            catch {
+                /* one bad listener doesn't break the others */
+            }
+        }
+    };
+    // ── Wire wiring ──────────────────────────────────────────────────
+    let attached = null;
+    const unsubs = [];
+    function attach(t) {
+        if (attached)
+            return; // idempotent
+        attached = t;
+        // Reconnect: clear roster (Hub sends fresh snapshot), re-announce
+        // own activity (peers don't auto-learn about us across reconnects).
+        unsubs.push(t.subscribe('connected', () => {
+            if (othersById.size > 0) {
+                othersById.clear();
+                othersSnapshot = Object.freeze([]);
+                notifyListeners();
+            }
+            if (self.activity.entityId)
+                sendUpdate(self.activity);
+        }));
+        // Inbound presence frames arrive in the wire vocabulary
+        // (userId / isAgent / timestamp); translate them into the shape this
+        // stream exposes (participantId / participantKind / lastActive).
+        unsubs.push(t.subscribe('presence_update', (event) => {
+            if (event.userId === participantId)
+                return; // own echo
+            if (!event.userId)
+                return;
+            switch (event.kind) {
+                case 'leave':
+                    if (othersById.delete(event.userId))
+                        notifyListeners();
+                    return;
+                // No `undefined` arm: every site that builds a presence frame stamps
+                // `kind`, and the schema now says so, so an unlabelled frame is not a
+                // shape the transport can hand us.
+                case 'enter':
+                case 'update': {
+                    const entry = {
+                        participantKind: participantKindFromWire(event.participantKind, event.isAgent),
+                        participantId: event.userId,
+                        syncGroups: event.syncGroups ?? [],
+                        activity: event.activity
+                            ? {
+                                ...wireTarget(event.activity),
+                                ...subTarget(event.activity),
+                                action: event.activity.action,
+                                ...(event.activity.detail !== undefined
+                                    ? { detail: event.activity.detail }
+                                    : {}),
+                            }
+                            : { entityType: 'Unknown', entityId: '', action: event.status },
+                        lastActive: event.timestamp
+                            ? new Date(event.timestamp).toISOString()
+                            : new Date().toISOString(),
+                    };
+                    othersById.set(event.userId, entry);
+                    notifyListeners();
+                    return;
+                }
+            }
+        }));
+        // If self was already mutated before attach, broadcast it now.
+        if (self.activity.entityId)
+            sendUpdate(self.activity);
+    }
+    if (transport)
+        attach(transport);
+    // ── Outbound ────────────────────────────────────────────────────
+    // Do not include `isAgent` in the payload. The server derives it
+    // authoritatively from the connection's identity, and letting a client
+    // self-declare it once caused human sessions to broadcast as agents to peers.
+    function sendUpdate(activity) {
+        if (!attached?.isConnected())
+            return; // no-op until connected
+        attached.send({
+            type: 'presence_update',
+            payload: { status: 'online', activity },
+        });
+    }
+    function doUpdate(activity) {
+        self.activity = activity;
+        self.lastActive = new Date().toISOString();
+        sendUpdate(activity);
+    }
+    function resolveTarget(target) {
+        if (isTargetTuple(target)) {
+            return { entityType: target[0], entityId: target[1], action: 'unknown' };
+        }
+        return {
+            ...wireTarget(target),
+            ...subTarget(target),
+            action: 'unknown',
+        };
+    }
+    const withVerb = (action) => (target, detail) => {
+        doUpdate({ ...resolveTarget(target), action, detail });
+    };
+    return {
+        self,
+        update: doUpdate,
+        editing: withVerb('editing'),
+        reading: withVerb('reading'),
+        viewing: withVerb('viewing'),
+        idle: () => {
+            doUpdate({ entityType: 'Unknown', entityId: '', action: 'idle' });
+        },
+        get others() {
+            return othersSnapshot;
+        },
+        othersIn: (syncGroup) => othersSnapshot.filter((e) => e.syncGroups.includes(syncGroup)),
+        onChange: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        [Symbol.asyncIterator]() {
+            return asyncIteratorFrom((onChange) => {
+                listeners.add(onChange);
+                return () => {
+                    listeners.delete(onChange);
+                };
+            }, () => othersSnapshot);
+        },
+        attach,
+        setParticipant(participant) {
+            participantId = participant.id;
+            const writable = self;
+            writable.participantId = participant.id;
+            if (participant.kind)
+                writable.participantKind = participant.kind;
+            if (participant.syncGroups)
+                writable.syncGroups = [...participant.syncGroups];
+        },
+        dispose() {
+            for (const off of unsubs)
+                off();
+            unsubs.length = 0;
+            listeners.clear();
+            othersById.clear();
+            othersSnapshot = Object.freeze([]);
+            attached = null;
+        },
+    };
+}

package/dist/react/AbloProvider.d.ts

@@ -0,0 +1,242 @@
+import { type ReactNode } from 'react';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { AbloClient as Ablo } from '../client.js';
+import type { Claim, Duration, Peer } from '@abloatai/transaction/types/streams';
+import type { EngineParticipant, ParticipantScope, ParticipantStatus } from '../local/sync/participants.js';
+import { type SyncStoreContract } from './context.js';
+/**
+ * Ablo umbrella provider — owns the sync engine, multiplayer, and
+ * the full lifecycle (Strict-Mode-safe singleton, `beforeunload`,
+ * session-expiry handling, post-bootstrap hooks).
+ *
+ * Design goals:
+ *
+ *   - **One component, one import.** Consumers write the provider
+ *     once at the root; nothing else needs to plumb the engine.
+ *   - **Multiplayer is default.** React consumers are always browsers doing
+ *     multiplayer UI, so `useJoin()` / `useAblo()` are always
+ *     available. No opt-in prop.
+ *   - **Declarative props for app glue.** `preventUnsavedChanges`,
+ *     `onSessionExpired`, `postBootstrap`, `resolveUsers` — each
+ *     absorbs a class of integration code that previously lived in
+ *     userland.
+ *   - **Singleton safety.** The engine lives in a ref and rotates
+ *     only when `userId` / account scope / `url` change. React
+ *     Strict Mode double-mount does not leak a second WebSocket.
+ */
+/**
+ * Props for `<AbloProvider>`.
+ *
+ * The one required prop is a prebuilt {@link Ablo} client — the client
+ * owns auth and the credential lifecycle; this provider is the reactive
+ * binding over it:
+ *
+ * ```tsx
+ * // Build once at module scope — a new instance per render tears down the socket.
+ * // The endpoint string points at your session-mint route (`ablo init`
+ * // scaffolds it); the SDK fetches it and keeps the token fresh.
+ * const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+ *
+ * <AbloProvider client={ablo}>
+ *   <App />
+ * </AbloProvider>
+ * ```
+ *
+ * That's it for most apps. `userId` is informational; the `fallback`,
+ * `preventUnsavedChanges`, and `on*` props are opt-in app glue; and the
+ * block tagged "Optional DI (advanced)" below is escape-hatch wiring for
+ * tests and platform builders — if you don't recognize a prop there, you
+ * don't need it.
+ */
+export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
+    /**
+     * A prebuilt {@link Ablo} client — **the only way to configure the engine.**
+     * Construct it yourself with `Ablo({ schema, apiKey, ... })` and pass the
+     * instance: the CLIENT owns auth, the credential lifecycle, transport, and
+     * connection; this provider is the thin REACTIVE binding over it (context,
+     * the bootstrap gate, error/​session forwarding).
+     *
+     * Memoize it (build it once, e.g. with `useMemo` or module scope) — a new
+     * instance each render re-keys the bootstrap gate and tears down the socket.
+     */
+    client: Ablo<R>;
+    /**
+     * The app user id, surfaced via `useCurrentUserId()` for app-owned fields.
+     * Purely informational for the React tree — sync identity is resolved by the
+     * client from its auth, not from this. Optional.
+     */
+    userId?: string;
+    /**
+     * Block tab close while there are unsynced local writes (the standard
+     * `beforeunload` prompt). Browsers ignore custom messages — don't pass one.
+     */
+    preventUnsavedChanges?: boolean;
+    /**
+     * Fired after the client has completed its terminal authentication cleanup
+     * (or surfaced a cleanup failure). Use it for app side effects such as a
+     * redirect to sign-in or clearing analytics identity.
+     */
+    onSessionExpired?: () => void | Promise<void>;
+    /**
+     * Fired on any error the provider surfaces (engine/WebSocket/bootstrap). For
+     * Sentry/Datadog. React-only consumers can use `useErrorListener()` instead.
+     */
+    onError?: (error: Error) => void;
+    /** @internal placeholder so the old WS-URL prop shape doesn't silently leak in. */
+    url?: never;
+    /**
+     * Rendered in place of `children` during the *first* bootstrap pass —
+     * while the engine is actively transitioning from `initial` →
+     * `connected` and has never successfully connected before. Once the
+     * engine reaches `connected` the gate latches open for the lifetime
+     * of this provider instance; transient `reconnecting` / `needs-auth`
+     * states do NOT re-show the fallback (the app's own UI handles those
+     * by then).
+     *
+     * Defaults to `<DefaultFallback />` — a neutral theme-adaptive
+     * spinner that uses `currentColor`, ships with zero design-system
+     * dependencies, and self-centers in a full-parent container. Pass
+     * your own `<Skeleton />` for a branded loading UX. Pass `null` to
+     * render nothing during bootstrap. Pass the string literal
+     * `"passthrough"` to opt out of the gate entirely — children render
+     * immediately and consumers are responsible for their own gating
+     * (`<ClientSideSuspense>` or manual `useSyncStatus()` checks).
+     * Useful for pages that mount debug helpers, error boundaries, or
+     * analytics that must run pre-ready.
+     */
+    fallback?: ReactNode | 'passthrough';
+    children: ReactNode;
+}
+export declare function AbloProvider<R extends SchemaRecord = SchemaRecord>(props: AbloProviderProps<R>): React.ReactElement;
+export type { EngineParticipant, ParticipantScope, ParticipantStatus };
+/**
+ * Options for `useJoin`. The hook reuses the engine's single
+ * WebSocket and opens a scoped claim on it when `scope` is provided:
+ * one TCP connection, N logical sub-syncgroup participants.
+ */
+export interface UseJoinOptions {
+    readonly scope?: ParticipantScope;
+    /**
+     * Lease TTL for the participant claim, as a compact duration (`'5m'`) or a
+     * number of seconds. The same dial and the same spelling as
+     * `ablo.<model>.join(ids, { ttl })` and every other lease in the SDK.
+     */
+    readonly ttl?: Duration;
+    /**
+     * @deprecated Use `ttl`. Removed in 0.37.0.
+     *
+     * The same rename as on `ParticipantJoinOptions`: one lease, and the seconds
+     * spelling was the one that misled, because it accepted duration strings too.
+     */
+    readonly ttlSeconds?: number | string | null;
+    /** Tear down + don't re-join while true. */
+    readonly paused?: boolean;
+    /**
+     * Acquire a write-claim CLAIM on the scope, in addition to read interest.
+     *
+     * Default `false`: opening a scope subscribes the connection to its deltas
+     * (read interest, via `update_subscription`) but does NOT claim it — a
+     * viewer is not a claimant. Set `true` when the participant intends to
+     * WRITE (editing a report, an agent staking work): the claim is sent so peers
+     * observe it, and the scope is pinned so it stays subscribed (never warms)
+     * for as long as the claim is held.
+     */
+    readonly claim?: boolean;
+    /**
+     * Backfill the scope's CURRENT state into the pool on enter, in addition to
+     * tailing live changes.
+     *
+     * Default `false`: entering a scope subscribes to its FUTURE deltas only — if
+     * the scope's rows aren't already loaded, the view is empty until something
+     * changes. Set `true` when opening an entity that may not be loaded yet (a
+     * deep-linked report, a never-opened ledger) so its current rows are fetched and
+     * injected once, then kept fresh by the live tail. The fetch is single-flight
+     * and runs once per group; a failure soft-fails (the live tail still flows).
+     */
+    readonly hydrate?: boolean;
+}
+export interface UseJoinReturn {
+    readonly participant: EngineParticipant | null;
+    /** Everyone else on the engine's sync groups (`participant.presence.others`), bridged to React. */
+    readonly peers: readonly Peer[];
+    /** Active claim claims by peers (`participant.claims.others`), bridged to React. */
+    readonly claims: readonly Claim[];
+    readonly status: ParticipantStatus;
+    readonly error: Error | null;
+}
+/**
+ * Join multiplayer for a given scope. Returns the participant and its
+ * lifecycle status. Auto-cleans up on unmount or when `paused`
+ * flips to true.
+ *
+ * `useJoin` is the React form of `ablo.<model>.join` — scope-level
+ * read-interest + presence; returns the reactive participant facade
+ * (peers/claims/status).
+ *
+ * The returned `participant` is an `EngineParticipant` — `.presence`
+ * + `.claims` only — backed by the engine's existing socket. For
+ * headless-bot patterns (a separate identity in the same browser
+ * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
+ */
+export declare function useJoin(opts: UseJoinOptions): UseJoinReturn;
+/**
+ * Read-only presence: the OTHER participants currently visible to this
+ * connection, bridged to React. Unlike {@link useJoin}, this does
+ * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
+ * it is a pure reader of the engine's already-flowing presence stream.
+ *
+ * Pass `scope` to narrow to the peers on that scope's sync group(s); omit
+ * it to get everyone on the engine's groups. Membership is driven entirely
+ * by the presence channel (set server-side on connect, independent of any
+ * cursor/collaboration traffic), so reading it never affects what the
+ * connection is subscribed to and can't deadlock against a gated channel.
+ *
+ * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
+ * broadcasts while alone — when some OTHER mount already owns the scope's
+ * read interest (scope `leave` is not reference-counted, so a second
+ * `useJoin` on the same scope would warm-drop the owner's
+ * subscription on unmount).
+ *
+ * ```ts
+ * const peers = usePeers({ reports: reportId });
+ * const alone = !peers.some((p) => p.participantKind === 'user');
+ * ```
+ */
+export declare function usePeers(scope?: ParticipantScope): readonly Peer[];
+/**
+ * Returns the raw `SyncEngine` proxy. Typically you want the typed
+ * hooks (`useQuery`, `useOne`, `useMutate`) — this is for rare cases
+ * where you need direct access (e.g., `sync.tasks.onChange(cb)`).
+ *
+ * The generic parameter narrows the return type to your schema's
+ * model record so call sites get typed `sync.tasks.findMany()` /
+ * `sync.sections.create(...)` without a cast at the call site:
+ *
+ * ```ts
+ * const sync = useSync<(typeof schema)['models']>();
+ * ```
+ *
+ * The runtime value is the exact engine the provider constructed;
+ * the generic just widens the compile-time type.
+ */
+export declare function useSync<R extends SchemaRecord = SchemaRecord>(): Ablo<R>;
+/**
+ * Returns the underlying `SyncStoreContract` (the BaseSyncedStore).
+ * Most consumers should prefer the typed hooks (`useQuery` etc.); this
+ * is for advanced cases like direct InstanceCache access or custom
+ * reactive bridges. Throws if the provider hasn't mounted the store
+ * yet — wrap consumers in `<ClientSideSuspense>` to gate correctly.
+ *
+ * The generic parameter lets consumers widen the return type to a
+ * concrete `BaseSyncedStore<...>` subclass if they track one:
+ *
+ * ```ts
+ * type AppStore = BaseSyncedStore<AppEvents, typeof schema>;
+ * const store = useSyncStore<AppStore>();  // no cast needed at call site
+ * ```
+ *
+ * The runtime value is always the concrete store the SDK constructed,
+ * so widening the type is safe. The bounded generic (`T extends
+ * SyncStoreContract`) keeps the widening honest.
+ */
+export declare function useSyncStore<T extends SyncStoreContract = SyncStoreContract>(): T;