Local-First Architecture: CRDT (Yjs) and Client Databases (IndexedDB, OPFS)

┌────────────────────────────────────────────────────────────────────────┐
│                   LOCAL-FIRST REPLICATION VIA CRDT                     │
│                                                                        │
│ User A (Offline on a train)                 User B (Connected in office)│
│ ┌──────────────────────┐                   ┌──────────────────────┐    │
│ │   React 19 UI        │                   │   React 19 UI        │    │
│ │   (Instant Input)    │                   │   (Instant Input)    │    │
│ └──────────┬───────────┘                   └──────────┬───────────┘    │
│            │ 0 ms latency                             │ 0 ms latency   │
│            ▼                                          ▼                │
│ ┌──────────────────────┐                   ┌──────────────────────┐    │
│ │  Local CRDT Document │                   │  Local CRDT Document │    │
│ │  (Yjs / Y.Doc)       │                   │  (Yjs / Y.Doc)       │    │
│ ├──────────────────────┤                   ├──────────────────────┤    │
│ │ IndexedDB / OPFS     │                   │ IndexedDB / OPFS     │    │
│ │ (Persistence Layer)  │                   │ (Persistence Layer)  │    │
│ └──────────┬───────────┘                   └──────────┬───────────┘    │
│            │                                          │                │
│            │ (Reconnected: binary delta)              │ (Sync Protocol)│
│            └───────────────────► ┌─────────────┐ ◄────┘                │
│                                  │ Relay Server│                       │
│                                  │ (WebSocket) │                       │
│                                  └─────────────┘                       │
│                                  Automatic                             │
│                                  Conflict-Free Convergence!            │
└────────────────────────────────────────────────────────────────────────┘

'use client';

import * as React from 'react';
import * as Y from 'yjs';
import { IndexeddbPersistence } from 'y-indexeddb';
import { WebsocketProvider } from 'y-websocket';

export interface UserAwarenessState {
  user: {
    id: string;
    name: string;
    color: string;
  };
  cursor?: { x: number; y: number } | null;
}

export interface UseLocalFirstDocOptions {
  docId: string;
  websocketUrl?: string;
  currentUser: UserAwarenessState['user'];
}

export interface UseLocalFirstDocReturn<T extends Record<string, unknown>> {
  doc: Y.Doc;
  data: T;
  updateData: (mutator: (map: Y.Map<unknown>) => void) => void;
  isSyncedLocal: boolean;
  isSyncedRemote: boolean;
  collaborators: Array<{ clientId: number; state: UserAwarenessState }>;
  updateCursor: (cursor: { x: number; y: number } | null) => void;
}

export function useLocalFirstDoc<T extends Record<string, unknown>>(
  options: UseLocalFirstDocOptions
): UseLocalFirstDocReturn<T> {
  const { docId, websocketUrl = 'wss://sync.agenticlab.dev/yjs', currentUser } = options;

  // Stable long-lived Y.Doc instance bound to the docId
  const [doc] = React.useState(() => new Y.Doc());
  const ymap = React.useMemo(() => doc.getMap('data'), [doc]);

  const [isSyncedLocal, setIsSyncedLocal] = React.useState(false);
  const [isSyncedRemote, setIsSyncedRemote] = React.useState(false);
  const [collaborators, setCollaborators] = React.useState<
    Array<{ clientId: number; state: UserAwarenessState }>
  >([]);

  const wsProviderRef = React.useRef<WebsocketProvider | null>(null);

  // 1. Initialize local IndexedDB and remote WebSocket sync providers
  React.useEffect(() => {
    const idbProvider = new IndexeddbPersistence(docId, doc);
    idbProvider.on('synced', () => {
      setIsSyncedLocal(true);
    });

    const wsProvider = new WebsocketProvider(websocketUrl, docId, doc, {
      connect: true,
    });
    wsProviderRef.current = wsProvider;

    wsProvider.on('status', (event: { status: 'connected' | 'disconnected' | 'connecting' }) => {
      setIsSyncedRemote(event.status === 'connected');
    });

    // 2. Set up live presence via the Awareness Protocol
    wsProvider.awareness.setLocalStateField('user', currentUser);

    const handleAwarenessChange = () => {
      const states = wsProvider.awareness.getStates();
      const activeCollaborators: Array<{ clientId: number; state: UserAwarenessState }> = [];

      states.forEach((state, clientId) => {
        if (clientId !== doc.clientID && (state as UserAwarenessState).user) {
          activeCollaborators.push({
            clientId,
            state: state as UserAwarenessState,
          });
        }
      });

      setCollaborators(activeCollaborators);
    };

    wsProvider.awareness.on('change', handleAwarenessChange);

    return () => {
      wsProvider.awareness.off('change', handleAwarenessChange);
      wsProvider.destroy();
      idbProvider.destroy();
      doc.destroy();
    };
  }, [docId, doc, websocketUrl, currentUser]);

  // 3. React 19 subscription via useSyncExternalStore for tearing-free renders
  const subscribe = React.useCallback(
    (onStoreChange: () => void) => {
      ymap.observe(onStoreChange);
      return () => {
        ymap.unobserve(onStoreChange);
      };
    },
    [ymap]
  );

  const getSnapshot = React.useCallback((): string => {
    return JSON.stringify(ymap.toJSON());
  }, [ymap]);

  const rawJson = React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
  const data = React.useMemo(() => JSON.parse(rawJson) as T, [rawJson]);

  // Atomic local document mutator executed inside a single transaction
  const updateData = React.useCallback(
    (mutator: (map: Y.Map<unknown>) => void) => {
      doc.transact(() => {
        mutator(ymap);
      });
    },
    [doc, ymap]
  );

  const updateCursor = React.useCallback((cursor: { x: number; y: number } | null) => {
    wsProviderRef.current?.awareness.setLocalStateField('cursor', cursor);
  }, []);

  return {
    doc,
    data,
    updateData,
    isSyncedLocal,
    isSyncedRemote,
    collaborators,
    updateCursor,
  };
}