use-presence.ts

use-presence.tsapps/web/src/hooks/use-presence.tsraw ← hooks6,348 B← Back to the app
1"use client";
2 
3/**
4 * usePresence / useDatabasePresence (TASK-0093) — wire this tab's presence
5 * state to the realtime socket for the active page OR database.
6 *
7 * The emission is ROOM-AGNOSTIC: the {@link PresenceEmitter} sends
8 * `presence` frames carrying only `{cursor, viewing}` (identity is
9 * server-stamped, and the server routes each frame to the socket's LAST
10 * subscribed `page:<id>`/`database:<id>` channel). So the same emitter
11 * lifecycle serves both the page route and the database home — only the
12 * CHANNEL SUBSCRIPTION + the STORE KEY differ (spec R6: "the machinery is
13 * identical").
14 *
15 * Emission lifecycle (shared):
16 *  - the caret is read from the presence caret store (stores/presence-store)
17 *    — the focused Tiptap editor writes it, every blur clears it.
18 *  - `viewing` follows `document.visibilityState` (pagehide → the cursor
19 *    hides immediately; pageshow → it comes back).
20 *  - on unmount (navigation / tab close) the caret store is cleared, the
21 *    emitter disposed, and an explicit `presence-leave` sent (the < 500 ms
22 *    leave fast path; the server also drops the peer on the socket close).
23 *
24 * `usePresence` (the page route layout, next to `usePageRealtime`):
25 * emission only — the page's bar reads presence from `usePageRealtime`.
26 * `useDatabasePresence` (the database home): subscribes the `database:<id>`
27 * channel, runs the same emission, and returns the database's roster from
28 * the store (the avatars-only bar — spec R6, no cursors in the table cells).
29 */
30import { useEffect, useMemo } from "react";
31import { authStore } from "@/lib/auth-store";
32import { channelForPage, realtime } from "@/lib/realtime";
33import { stripRoomKey } from "./realtime-frame-handler";
34import { PresenceEmitter } from "@/lib/presence-emitter";
35import { useBlockPatchStore } from "@/stores/block-patch-store";
36import { usePresenceCaretStore } from "@/stores/presence-store";
37import type { Presence, RealtimeServerEvent } from "@/lib/types";
38 
39const EMPTY_PRESENCE: Record<string, Presence> = {};
40 
41/** The shared emitter lifecycle: caret store + visibility + leave on
42 *  unmount. `active` gates it (a null page id → no emission). */
43function usePresenceEmitter(active: boolean): void {
44  useEffect(() => {
45    if (!active) return;
46    const emitter = new PresenceEmitter({ send: (s) => realtime.sendPresence(s) });
47    const offCaret = usePresenceCaretStore.subscribe((state) => emitter.setCaret(state.caret));
48    emitter.setCaret(usePresenceCaretStore.getState().caret);
49    emitter.setViewing(
50      typeof document === "undefined" ? true : document.visibilityState === "visible",
51    );
52    const onVisibility = (): void => {
53      emitter.setViewing(document.visibilityState === "visible");
54    };
55    document.addEventListener("visibilitychange", onVisibility);
56    // Re-assert on (re)connect: the client's sendPresence no-ops while the
57    // socket isn't OPEN, so the initial frame (sent pre-connect) is dropped
58    // and would otherwise leave this tab's avatar hidden until the next
59    // caret move. `assert()` re-sends the current state immediately.
60    const offStatus = realtime.onStatus((status) => {
61      if (status === "connected") emitter.assert();
62    });
63    return () => {
64      document.removeEventListener("visibilitychange", onVisibility);
65      offCaret();
66      offStatus();
67      emitter.dispose();
68      usePresenceCaretStore.getState().setCaret(null);
69      realtime.sendPresenceLeave(); // immediate leave (fast path).
70    };
71  }, [active]);
72}
73 
74/** Page-route presence emission. The bar reads presence from
75 *  `usePageRealtime` (same store). Call from the page layout. */
76export function usePresence(pageId: string | null): void {
77  usePresenceEmitter(pageId !== null);
78}
79 
80/** Read the page's roster from the store (no subscription — the page route
81 *  layout already runs `usePageRealtime`, which subscribes + folds the
82 *  frames). Used by the PageView header/overlay. */
83export function usePagePresence(pageId: string | null): Presence[] {
84  const presenceMap = useBlockPatchStore((s) =>
85    pageId ? (s.presence[pageId] ?? EMPTY_PRESENCE) : EMPTY_PRESENCE,
86  );
87  return useMemo(() => Object.values(presenceMap), [presenceMap]);
88}
89 
90export interface DatabasePresence {
91  presence: Presence[];
92}
93 
94/** Database-home presence (spec R6): the same machinery as the page, but
95 *  over the `database:<id>` channel + the database's store key. Returns the
96 *  OTHER peers (self excluded) for the header's avatars-only PresenceBar.
97 *
98 * The database home has no block overlay, so it registers ONLY the
99 * presence frame listeners (the full `handlePageRealtimeFrame` folds the
100 * block frames too — unnecessary here). */
101export function useDatabasePresence(databaseId: string | null): DatabasePresence {
102  usePresenceEmitter(databaseId !== null);
103 
104  useEffect(() => {
105    if (!databaseId) return;
106    // Open the socket (idempotent) — the database home has no page layout to
107    // connect it (the page route does this in usePageRealtime).
108    realtime.connect(() => authStore.accessToken);
109    const channel = `database:${databaseId}`;
110    realtime.subscribe(channel);
111    const store = useBlockPatchStore.getState();
112    const onFrame = (event: RealtimeServerEvent): void => {
113      if (event.type === "presence") {
114        store.upsertPresence(stripRoomKey(event.pageId), {
115          userId: event.user.id,
116          name: event.user.name,
117          color: event.user.color,
118          cursor: event.cursor ?? null,
119          viewing: event.viewing,
120          lastSeen: event.lastSeen,
121        });
122      } else if (event.type === "presence-leave") {
123        store.removePresence(stripRoomKey(event.pageId), event.userId);
124      }
125    };
126    const offs = [realtime.on("presence", onFrame), realtime.on("presence-leave", onFrame)];
127    return () => {
128      for (const off of offs) off();
129      realtime.unsubscribe(channel);
130      // Drop the database's roster (page unmount).
131      useBlockPatchStore.getState().reset(databaseId);
132    };
133  }, [databaseId]);
134 
135  const presenceMap = useBlockPatchStore((s) =>
136    databaseId ? (s.presence[databaseId] ?? EMPTY_PRESENCE) : EMPTY_PRESENCE,
137  );
138  return useMemo(() => ({ presence: Object.values(presenceMap) }), [presenceMap]);
139}
140 
141// Re-export for callers that build the page channel key.
142export { channelForPage };
143