use-realtime.ts

use-realtime.tsapps/web/src/hooks/use-realtime.tsraw ← hooks3,775 B← Back to the app
1"use client";
2 
3/**
4 * Page-level realtime wiring: subscribe to `page:<id>` on the shared socket
5 * (lib/realtime.ts), fold frames into the block-patch overlay store, and
6 * expose presence. The frame → overlay mapping (incl. the (b)
7 * `block:changed` refetch-hint) lives in `realtime-frame-handler.ts` —
8 * this hook only wires it to the store + query client.
9 *
10 * The overlay keeps the editor responsive (<200 ms, PRODUCT-SPEC §26) while
11 * TanStack Query remains the source of truth at rest — after a refetch the
12 * overlay for the page is reset.
13 */
14import { useEffect, useMemo, useState } from "react";
15 
16const EMPTY_PRESENCE: Record<string, Presence> = {};
17import { useQueryClient } from "@tanstack/react-query";
18import { authStore } from "@/lib/auth-store";
19import { channelForPage, realtime, type RealtimeStatus } from "@/lib/realtime";
20import { useBlockPatchStore } from "@/stores/block-patch-store";
21import type { Block, BlockPatch, Presence } from "@/lib/types";
22import { handlePageRealtimeFrame } from "./realtime-frame-handler";
23 
24export interface PageRealtime {
25  status: RealtimeStatus;
26  presence: Presence[];
27}
28 
29export function usePageRealtime(pageId: string | null): PageRealtime {
30  const [status, setStatus] = useState<RealtimeStatus>(realtime.connectionStatus);
31  // The store keeps the roster as a userId → peer map (the fold of the
32  // per-peer `presence` frames); expose it as a list.
33  const presenceMap = useBlockPatchStore((s) =>
34    pageId ? (s.presence[pageId] ?? EMPTY_PRESENCE) : EMPTY_PRESENCE,
35  );
36  const presence = useMemo(() => Object.values(presenceMap), [presenceMap]);
37  const qc = useQueryClient();
38 
39  useEffect(() => {
40    const offStatus = realtime.onStatus(setStatus);
41    // Connect lazily — the first page with realtime opens the socket; it
42    // stays open for the tab's lifetime.
43    realtime.connect(() => authStore.accessToken);
44 
45    if (!pageId) return;
46    const channel = channelForPage(pageId);
47    realtime.subscribe(channel);
48 
49    // All page frames fold through the pure handler (realtime-frame-handler);
50    // the actions below bind it to the overlay store + the query client. The
51    // client emitter keys listeners by exact frame type, so register the
52    // handler for each block-overlay frame it must handle.
53    const actions = {
54      upsert: (pid: string, blocks: Block[]) => useBlockPatchStore.getState().upsert(pid, blocks),
55      delete: (pid: string, blockIds: string[]) =>
56        useBlockPatchStore.getState().delete(pid, blockIds),
57      patch: (pid: string, blockId: string, p: BlockPatch) =>
58        useBlockPatchStore.getState().patch(pid, blockId, p),
59      upsertPresence: (pid: string, peer: Presence) =>
60        useBlockPatchStore.getState().upsertPresence(pid, peer),
61      removePresence: (pid: string, userId: string) =>
62        useBlockPatchStore.getState().removePresence(pid, userId),
63      clearBlocks: (pid: string) => useBlockPatchStore.getState().clearBlocks(pid),
64      invalidateBlocks: (pid: string) =>
65        qc.invalidateQueries({ queryKey: ["pages", pid, "blocks"] }),
66    };
67    const frameTypes = [
68      "presence",
69      "presence-leave",
70      "block:upsert",
71      "block:delete",
72      "block:move",
73      "block:changed",
74    ] as const;
75    const offs = frameTypes.map((t) =>
76      realtime.on(t, (event) => handlePageRealtimeFrame(event, actions)),
77    );
78 
79    return () => {
80      for (const off of offs) off();
81      offStatus();
82      realtime.unsubscribe(channel);
83      // Drop the overlay once the page is unmounted; the query cache keeps
84      // its own data and a fresh mount refetches if stale.
85      useBlockPatchStore.getState().reset(pageId);
86    };
87  }, [pageId, qc]);
88 
89  return useMemo(() => ({ status, presence }), [status, presence]);
90}
91