@openlivesync/client 1.0.0

package/dist/react-entry.d.ts

@@ -0,0 +1,63 @@
+import React, { ReactNode } from 'react';
+import { LiveSyncClient, StoredChatMessage, Presence, PresenceEntry, LiveSyncClientState } from './index.js';
+
+/**
+ * React bindings for @openlivesync/client.
+ * Provider + hooks; import from "@openlivesync/client/react".
+ */
+
+interface LiveSyncProviderProps {
+    children: ReactNode;
+    /** Pre-created client (call createLiveSyncClient yourself). */
+    client?: LiveSyncClient;
+    /** Or pass config and the provider will create the client and connect on mount. */
+    url?: string;
+    reconnect?: boolean;
+    reconnectIntervalMs?: number;
+    maxReconnectIntervalMs?: number;
+    getAuthToken?: () => string | Promise<string>;
+    presenceThrottleMs?: number;
+}
+/**
+ * Provides the LiveSync client to the tree. Pass either `client` or config (`url`, etc.).
+ * If config is passed, the client is created on mount and connect() is called; disconnect on unmount.
+ */
+declare function LiveSyncProvider(props: LiveSyncProviderProps): React.FunctionComponentElement<React.ProviderProps<LiveSyncClient | null>>;
+declare function useLiveSyncClient(): LiveSyncClient;
+/** Returns current connection status and triggers re-renders when it changes. */
+declare function useConnectionStatus(): LiveSyncClientState["connectionStatus"];
+interface UseRoomOptions {
+    /** Initial presence when joining (optional). */
+    initialPresence?: Presence;
+    /** If true, join the room when roomId is set and leave on cleanup or when roomId changes. */
+    autoJoin?: boolean;
+    /** Optional access token sent with join_room (server can decode for name/email). */
+    accessToken?: string;
+    /** Optional getter for access token (e.g. refreshed token); used when auto-joining. */
+    getAccessToken?: () => string | Promise<string>;
+}
+interface UseRoomReturn {
+    join: (roomId: string, presence?: Presence, accessToken?: string) => void;
+    leave: (roomId?: string) => void;
+    updatePresence: (presence: Presence) => void;
+    broadcastEvent: (event: string, payload?: unknown) => void;
+    presence: Record<string, PresenceEntry>;
+    connectionId: string | null;
+    isInRoom: boolean;
+    currentRoomId: string | null;
+}
+/**
+ * Subscribe to room state and get methods to join/leave/update presence/broadcast.
+ * If autoJoin is true (default), joining happens when roomId is set and leaving on unmount or roomId change.
+ */
+declare function useRoom(roomId: string | null, options?: UseRoomOptions): UseRoomReturn;
+/** Returns presence map for the current room (or empty if not in room). */
+declare function usePresence(roomId: string | null): Record<string, PresenceEntry>;
+interface UseChatReturn {
+    messages: StoredChatMessage[];
+    sendMessage: (message: string, metadata?: Record<string, unknown>) => void;
+}
+/** Returns chat messages for the given room and sendMessage. Ensure the room is joined (e.g. via useRoom). */
+declare function useChat(roomId: string | null): UseChatReturn;
+
+export { LiveSyncProvider, type LiveSyncProviderProps, type UseChatReturn, type UseRoomOptions, type UseRoomReturn, useChat, useConnectionStatus, useLiveSyncClient, usePresence, useRoom };

package/dist/react-entry.js

@@ -0,0 +1,151 @@
+import {
+  createLiveSyncClient
+} from "./chunk-MINJGWLX.js";
+
+// src/react-entry.tsx
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+var LiveSyncContext = createContext(null);
+function LiveSyncProvider(props) {
+  const { children, client: clientProp } = props;
+  const configRef = useRef(null);
+  if (!configRef.current && !clientProp && props.url) {
+    configRef.current = {
+      url: props.url,
+      reconnect: props.reconnect,
+      reconnectIntervalMs: props.reconnectIntervalMs,
+      maxReconnectIntervalMs: props.maxReconnectIntervalMs,
+      getAuthToken: props.getAuthToken,
+      presenceThrottleMs: props.presenceThrottleMs
+    };
+  }
+  const config = configRef.current;
+  const clientFromConfig = useMemo(() => {
+    if (clientProp || !config) return null;
+    return createLiveSyncClient(config);
+  }, [clientProp, config?.url]);
+  const client = clientProp ?? clientFromConfig;
+  useEffect(() => {
+    if (!client) return;
+    if (!clientProp && config) {
+      client.connect();
+      return () => client.disconnect();
+    }
+  }, [client, clientProp, config]);
+  if (!client) {
+    throw new Error(
+      "LiveSyncProvider: pass either `client` or config (e.g. `url`) to create the client."
+    );
+  }
+  return React.createElement(LiveSyncContext.Provider, { value: client }, children);
+}
+function useLiveSyncClient() {
+  const client = useContext(LiveSyncContext);
+  if (!client) {
+    throw new Error("useLiveSyncClient must be used within LiveSyncProvider");
+  }
+  return client;
+}
+function useClientState() {
+  const client = useLiveSyncClient();
+  const [state, setState] = useState(
+    () => client.getState()
+  );
+  useEffect(() => {
+    return client.subscribe(setState);
+  }, [client]);
+  return state;
+}
+function useConnectionStatus() {
+  return useClientState().connectionStatus;
+}
+function useRoom(roomId, options = {}) {
+  const { initialPresence, autoJoin = true, accessToken, getAccessToken } = options;
+  const client = useLiveSyncClient();
+  const state = useClientState();
+  const joinedRef = useRef(null);
+  const join = useCallback(
+    (id, presence, token) => {
+      const t = token ?? accessToken;
+      client.joinRoom(id, presence ?? initialPresence, t);
+      joinedRef.current = id;
+    },
+    [client, initialPresence, accessToken]
+  );
+  const leave = useCallback(
+    (id) => {
+      client.leaveRoom(id);
+      if (!id || id === joinedRef.current) joinedRef.current = null;
+    },
+    [client]
+  );
+  useEffect(() => {
+    if (!autoJoin || roomId === null) return;
+    let cancelled = false;
+    (async () => {
+      const token = accessToken ?? (getAccessToken ? await getAccessToken() : void 0);
+      if (!cancelled) {
+        client.joinRoom(roomId, initialPresence, token);
+        joinedRef.current = roomId;
+      }
+    })();
+    return () => {
+      cancelled = true;
+      leave(roomId);
+    };
+  }, [autoJoin, roomId, initialPresence, accessToken, getAccessToken, client, leave]);
+  const updatePresence = useCallback(
+    (presence) => client.updatePresence(presence),
+    [client]
+  );
+  const broadcastEvent = useCallback(
+    (event, payload) => client.broadcastEvent(event, payload),
+    [client]
+  );
+  const isInRoom = state.currentRoomId !== null && state.currentRoomId === roomId;
+  return {
+    join,
+    leave,
+    updatePresence,
+    broadcastEvent,
+    presence: roomId && isInRoom ? state.presence : {},
+    connectionId: isInRoom ? state.connectionId : null,
+    isInRoom,
+    currentRoomId: state.currentRoomId
+  };
+}
+function usePresence(roomId) {
+  useLiveSyncClient();
+  const state = useClientState();
+  const isInRoom = roomId !== null && state.currentRoomId === roomId;
+  return isInRoom ? state.presence : {};
+}
+function useChat(roomId) {
+  const client = useLiveSyncClient();
+  const state = useClientState();
+  const isInRoom = roomId !== null && state.currentRoomId === roomId;
+  const messages = isInRoom ? state.chatMessages : [];
+  const sendMessage = useCallback(
+    (message, metadata) => {
+      client.sendChat(message, metadata);
+    },
+    [client]
+  );
+  return { messages, sendMessage };
+}
+export {
+  LiveSyncProvider,
+  useChat,
+  useConnectionStatus,
+  useLiveSyncClient,
+  usePresence,
+  useRoom
+};
+//# sourceMappingURL=react-entry.js.map

package/dist/react-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react-entry.tsx"],"sourcesContent":["/**\n * React bindings for @openlivesync/client.\n * Provider + hooks; import from \"@openlivesync/client/react\".\n */\n\nimport React, {\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  type ReactNode,\n} from \"react\";\nimport {\n  createLiveSyncClient,\n  type LiveSyncClient,\n  type LiveSyncClientConfig,\n  type LiveSyncClientState,\n} from \"./client.js\";\nimport type { Presence, PresenceEntry, StoredChatMessage } from \"./protocol.js\";\n\nconst LiveSyncContext = createContext<LiveSyncClient | null>(null);\n\nexport interface LiveSyncProviderProps {\n  children: ReactNode;\n  /** Pre-created client (call createLiveSyncClient yourself). */\n  client?: LiveSyncClient;\n  /** Or pass config and the provider will create the client and connect on mount. */\n  url?: string;\n  reconnect?: boolean;\n  reconnectIntervalMs?: number;\n  maxReconnectIntervalMs?: number;\n  getAuthToken?: () => string | Promise<string>;\n  presenceThrottleMs?: number;\n}\n\n/**\n * Provides the LiveSync client to the tree. Pass either `client` or config (`url`, etc.).\n * If config is passed, the client is created on mount and connect() is called; disconnect on unmount.\n */\nexport function LiveSyncProvider(props: LiveSyncProviderProps) {\n  const { children, client: clientProp } = props;\n  const configRef = useRef<LiveSyncClientConfig | null>(null);\n  if (!configRef.current && !clientProp && props.url) {\n    configRef.current = {\n      url: props.url,\n      reconnect: props.reconnect,\n      reconnectIntervalMs: props.reconnectIntervalMs,\n      maxReconnectIntervalMs: props.maxReconnectIntervalMs,\n      getAuthToken: props.getAuthToken,\n      presenceThrottleMs: props.presenceThrottleMs,\n    };\n  }\n  const config = configRef.current;\n\n  const clientFromConfig = useMemo(() => {\n    if (clientProp || !config) return null;\n    return createLiveSyncClient(config);\n  }, [clientProp, config?.url]);\n\n  const client = clientProp ?? clientFromConfig;\n\n  useEffect(() => {\n    if (!client) return;\n    if (!clientProp && config) {\n      client.connect();\n      return () => client.disconnect();\n    }\n  }, [client, clientProp, config]);\n\n  if (!client) {\n    throw new Error(\n      \"LiveSyncProvider: pass either `client` or config (e.g. `url`) to create the client.\"\n    );\n  }\n\n  return React.createElement(LiveSyncContext.Provider, { value: client }, children);\n}\n\nexport function useLiveSyncClient(): LiveSyncClient {\n  const client = useContext(LiveSyncContext);\n  if (!client) {\n    throw new Error(\"useLiveSyncClient must be used within LiveSyncProvider\");\n  }\n  return client;\n}\n\nfunction useClientState(): LiveSyncClientState {\n  const client = useLiveSyncClient();\n  const [state, setState] = useState<LiveSyncClientState>(() =>\n    client.getState()\n  );\n  useEffect(() => {\n    return client.subscribe(setState);\n  }, [client]);\n  return state;\n}\n\n/** Returns current connection status and triggers re-renders when it changes. */\nexport function useConnectionStatus(): LiveSyncClientState[\"connectionStatus\"] {\n  return useClientState().connectionStatus;\n}\n\nexport interface UseRoomOptions {\n  /** Initial presence when joining (optional). */\n  initialPresence?: Presence;\n  /** If true, join the room when roomId is set and leave on cleanup or when roomId changes. */\n  autoJoin?: boolean;\n  /** Optional access token sent with join_room (server can decode for name/email). */\n  accessToken?: string;\n  /** Optional getter for access token (e.g. refreshed token); used when auto-joining. */\n  getAccessToken?: () => string | Promise<string>;\n}\n\nexport interface UseRoomReturn {\n  join: (roomId: string, presence?: Presence, accessToken?: string) => void;\n  leave: (roomId?: string) => void;\n  updatePresence: (presence: Presence) => void;\n  broadcastEvent: (event: string, payload?: unknown) => void;\n  presence: Record<string, PresenceEntry>;\n  connectionId: string | null;\n  isInRoom: boolean;\n  currentRoomId: string | null;\n}\n\n/**\n * Subscribe to room state and get methods to join/leave/update presence/broadcast.\n * If autoJoin is true (default), joining happens when roomId is set and leaving on unmount or roomId change.\n */\nexport function useRoom(\n  roomId: string | null,\n  options: UseRoomOptions = {}\n): UseRoomReturn {\n  const { initialPresence, autoJoin = true, accessToken, getAccessToken } = options;\n  const client = useLiveSyncClient();\n  const state = useClientState();\n  const joinedRef = useRef<string | null>(null);\n\n  const join = useCallback(\n    (id: string, presence?: Presence, token?: string) => {\n      const t = token ?? accessToken;\n      client.joinRoom(id, presence ?? initialPresence, t);\n      joinedRef.current = id;\n    },\n    [client, initialPresence, accessToken]\n  );\n\n  const leave = useCallback(\n    (id?: string) => {\n      client.leaveRoom(id);\n      if (!id || id === joinedRef.current) joinedRef.current = null;\n    },\n    [client]\n  );\n\n  useEffect(() => {\n    if (!autoJoin || roomId === null) return;\n    let cancelled = false;\n    (async () => {\n      const token = accessToken ?? (getAccessToken ? await getAccessToken() : undefined);\n      if (!cancelled) {\n        client.joinRoom(roomId, initialPresence, token);\n        joinedRef.current = roomId;\n      }\n    })();\n    return () => {\n      cancelled = true;\n      leave(roomId);\n    };\n  }, [autoJoin, roomId, initialPresence, accessToken, getAccessToken, client, leave]);\n\n  const updatePresence = useCallback(\n    (presence: Presence) => client.updatePresence(presence),\n    [client]\n  );\n\n  const broadcastEvent = useCallback(\n    (event: string, payload?: unknown) => client.broadcastEvent(event, payload),\n    [client]\n  );\n\n  const isInRoom =\n    state.currentRoomId !== null && state.currentRoomId === roomId;\n\n  return {\n    join,\n    leave,\n    updatePresence,\n    broadcastEvent,\n    presence: roomId && isInRoom ? state.presence : {},\n    connectionId: isInRoom ? state.connectionId : null,\n    isInRoom,\n    currentRoomId: state.currentRoomId,\n  };\n}\n\n/** Returns presence map for the current room (or empty if not in room). */\nexport function usePresence(roomId: string | null): Record<string, PresenceEntry> {\n  useLiveSyncClient(); // ensure we're inside provider\n  const state = useClientState();\n  const isInRoom =\n    roomId !== null &&\n    state.currentRoomId === roomId;\n  return isInRoom ? state.presence : {};\n}\n\nexport interface UseChatReturn {\n  messages: StoredChatMessage[];\n  sendMessage: (message: string, metadata?: Record<string, unknown>) => void;\n}\n\n/** Returns chat messages for the given room and sendMessage. Ensure the room is joined (e.g. via useRoom). */\nexport function useChat(roomId: string | null): UseChatReturn {\n  const client = useLiveSyncClient();\n  const state = useClientState();\n  const isInRoom =\n    roomId !== null && state.currentRoomId === roomId;\n  const messages = isInRoom ? state.chatMessages : [];\n\n  const sendMessage = useCallback(\n    (message: string, metadata?: Record<string, unknown>) => {\n      client.sendChat(message, metadata);\n    },\n    [client]\n  );\n\n  return { messages, sendMessage };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@openlivesync/client",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react-entry.d.ts",
+      "import": "./dist/react-entry.js",
+      "default": "./dist/react-entry.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "react": "^18.3.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  }
+}

package/src/client.ts

@@ -0,0 +1,383 @@
+/**
+ * Core WebSocket client for @openlivesync.
+ * Connects to @openlivesync/server, manages room/presence/chat state, and notifies subscribers.
+ */
+
+import type {
+  ClientMessage,
+  ServerMessage,
+  Presence,
+  PresenceEntry,
+  StoredChatMessage,
+} from "./protocol.js";
+import {
+  MSG_JOIN_ROOM,
+  MSG_LEAVE_ROOM,
+  MSG_UPDATE_PRESENCE,
+  MSG_BROADCAST_EVENT,
+  MSG_SEND_CHAT,
+  MSG_ROOM_JOINED,
+  MSG_PRESENCE_UPDATED,
+  MSG_BROADCAST_EVENT_RELAY,
+  MSG_CHAT_MESSAGE,
+  MSG_ERROR,
+} from "./protocol.js";
+
+export type ConnectionStatus = "connecting" | "open" | "closing" | "closed";
+
+export interface LiveSyncClientState {
+  connectionStatus: ConnectionStatus;
+  currentRoomId: string | null;
+  connectionId: string | null;
+  presence: Record<string, PresenceEntry>;
+  chatMessages: StoredChatMessage[];
+  lastError: { code: string; message: string } | null;
+}
+
+export interface LiveSyncClientConfig {
+  /** WebSocket URL (e.g. wss://host/live). */
+  url: string;
+  /** Auto-reconnect on close (default true). */
+  reconnect?: boolean;
+  /** Initial reconnect delay in ms (default 1000). */
+  reconnectIntervalMs?: number;
+  /** Max reconnect delay in ms (default 30000). */
+  maxReconnectIntervalMs?: number;
+  /** Optional: return token for auth; appended as query param (e.g. ?access_token=). */
+  getAuthToken?: () => string | Promise<string>;
+  /** Throttle presence updates in ms (default 100, match server). */
+  presenceThrottleMs?: number;
+}
+
+const DEFAULT_RECONNECT_INTERVAL_MS = 1000;
+const DEFAULT_MAX_RECONNECT_INTERVAL_MS = 30000;
+const DEFAULT_PRESENCE_THROTTLE_MS = 100;
+
+function isServerMessage(msg: unknown): msg is ServerMessage {
+  if (msg === null || typeof msg !== "object" || !("type" in msg)) return false;
+  const t = (msg as { type: string }).type;
+  return [
+    MSG_ROOM_JOINED,
+    MSG_PRESENCE_UPDATED,
+    MSG_BROADCAST_EVENT_RELAY,
+    MSG_CHAT_MESSAGE,
+    MSG_ERROR,
+  ].includes(t);
+}
+
+export interface LiveSyncClient {
+  connect(): void;
+  disconnect(): void;
+  joinRoom(roomId: string, presence?: Presence, accessToken?: string): void;
+  leaveRoom(roomId?: string): void;
+  updatePresence(presence: Presence): void;
+  broadcastEvent(event: string, payload?: unknown): void;
+  sendChat(message: string, metadata?: Record<string, unknown>): void;
+  getConnectionStatus(): ConnectionStatus;
+  getPresence(): Record<string, PresenceEntry>;
+  getChatMessages(): StoredChatMessage[];
+  getCurrentRoomId(): string | null;
+  getState(): LiveSyncClientState;
+  subscribe(listener: (state: LiveSyncClientState) => void): () => void;
+}
+
+export function createLiveSyncClient(config: LiveSyncClientConfig): LiveSyncClient {
+  const {
+    url: baseUrl,
+    reconnect: reconnectEnabled = true,
+    reconnectIntervalMs = DEFAULT_RECONNECT_INTERVAL_MS,
+    maxReconnectIntervalMs = DEFAULT_MAX_RECONNECT_INTERVAL_MS,
+    getAuthToken,
+    presenceThrottleMs = DEFAULT_PRESENCE_THROTTLE_MS,
+  } = config;
+
+  let ws: WebSocket | null = null;
+  let reconnectTimeoutId: ReturnType<typeof setTimeout> | null = null;
+  let nextReconnectMs = reconnectIntervalMs;
+  let intentionalClose = false;
+  let lastPresenceUpdate = 0;
+  let pendingPresence: Presence | null = null;
+
+  const state: LiveSyncClientState = {
+    connectionStatus: "closed",
+    currentRoomId: null,
+    connectionId: null,
+    presence: {},
+    chatMessages: [],
+    lastError: null,
+  };
+
+  const listeners = new Set<(s: LiveSyncClientState) => void>();
+
+  function emit() {
+    const snapshot: LiveSyncClientState = {
+      connectionStatus: state.connectionStatus,
+      currentRoomId: state.currentRoomId,
+      connectionId: state.connectionId,
+      presence: { ...state.presence },
+      chatMessages: [...state.chatMessages],
+      lastError: state.lastError ? { ...state.lastError } : null,
+    };
+    listeners.forEach((cb) => cb(snapshot));
+  }
+
+  function setStatus(status: ConnectionStatus) {
+    state.connectionStatus = status;
+    emit();
+  }
+
+  function send(msg: ClientMessage) {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    ws.send(JSON.stringify(msg));
+  }
+
+  function clearReconnect() {
+    if (reconnectTimeoutId !== null) {
+      clearTimeout(reconnectTimeoutId);
+      reconnectTimeoutId = null;
+    }
+    nextReconnectMs = reconnectIntervalMs;
+  }
+
+  function scheduleReconnect() {
+    if (!reconnectEnabled || intentionalClose) return;
+    clearReconnect();
+    reconnectTimeoutId = setTimeout(() => {
+      reconnectTimeoutId = null;
+      nextReconnectMs = Math.min(
+        nextReconnectMs * 2,
+        maxReconnectIntervalMs
+      );
+      connect();
+    }, nextReconnectMs);
+  }
+
+  function applyPresenceUpdated(
+    joined?: PresenceEntry[],
+    left?: string[],
+    updated?: PresenceEntry[]
+  ) {
+    if (joined) {
+      for (const e of joined) state.presence[e.connectionId] = e;
+    }
+    if (left) {
+      for (const id of left) delete state.presence[id];
+    }
+    if (updated) {
+      for (const e of updated) state.presence[e.connectionId] = e;
+    }
+    emit();
+  }
+
+  function handleMessage(data: string) {
+    let msg: unknown;
+    try {
+      msg = JSON.parse(data) as unknown;
+    } catch {
+      state.lastError = { code: "INVALID_JSON", message: "Invalid JSON from server" };
+      emit();
+      return;
+    }
+    if (!isServerMessage(msg)) {
+      state.lastError = { code: "UNKNOWN_MESSAGE", message: "Unknown message type" };
+      emit();
+      return;
+    }
+    switch (msg.type) {
+      case MSG_ROOM_JOINED: {
+        const { roomId, connectionId, presence, chatHistory } = msg.payload;
+        state.currentRoomId = roomId;
+        state.connectionId = connectionId;
+        state.presence = presence ?? {};
+        state.chatMessages = chatHistory ?? [];
+        state.lastError = null;
+        emit();
+        break;
+      }
+      case MSG_PRESENCE_UPDATED: {
+        const { joined, left, updated } = msg.payload;
+        applyPresenceUpdated(joined, left, updated);
+        break;
+      }
+      case MSG_BROADCAST_EVENT_RELAY:
+        // Application can subscribe to custom events if we add an event emitter; for now we only update state for presence/chat.
+        break;
+      case MSG_CHAT_MESSAGE: {
+        const p = msg.payload;
+        const stored: StoredChatMessage = {
+          id: p.id ?? `${p.connectionId}-${p.createdAt ?? Date.now()}`,
+          roomId: p.roomId,
+          connectionId: p.connectionId,
+          userId: p.userId,
+          message: p.message,
+          metadata: p.metadata,
+          createdAt: p.createdAt ?? Date.now(),
+        };
+        if (state.currentRoomId === p.roomId) {
+          state.chatMessages = [...state.chatMessages, stored];
+          emit();
+        }
+        break;
+      }
+      case MSG_ERROR: {
+        state.lastError = msg.payload;
+        emit();
+        break;
+      }
+    }
+  }
+
+  function reconnectAndRejoin() {
+    const roomId = state.currentRoomId;
+    if (!roomId) return;
+    const presence = pendingPresence ?? (state.connectionId ? state.presence[state.connectionId]?.presence : undefined);
+    send({ type: MSG_JOIN_ROOM, payload: { roomId, presence } });
+  }
+
+  function connect() {
+    if (ws?.readyState === WebSocket.OPEN || ws?.readyState === WebSocket.CONNECTING) {
+      return;
+    }
+    intentionalClose = false;
+    setStatus("connecting");
+
+    (async () => {
+      let url = baseUrl;
+      if (getAuthToken) {
+        try {
+          const token = await getAuthToken();
+          if (token) {
+            const sep = baseUrl.includes("?") ? "&" : "?";
+            url = `${baseUrl}${sep}access_token=${encodeURIComponent(token)}`;
+          }
+        } catch (e) {
+          state.lastError = {
+            code: "AUTH_ERROR",
+            message: e instanceof Error ? e.message : String(e),
+          };
+          setStatus("closed");
+          emit();
+          return;
+        }
+      }
+
+      ws = new WebSocket(url);
+
+      ws.onopen = () => {
+        setStatus("open");
+        nextReconnectMs = reconnectIntervalMs;
+        reconnectAndRejoin();
+      };
+
+      ws.onmessage = (event) => {
+        const data = typeof event.data === "string" ? event.data : event.data.toString();
+        handleMessage(data);
+      };
+
+      ws.onclose = () => {
+        ws = null;
+        setStatus("closed");
+        if (!intentionalClose) {
+          scheduleReconnect();
+        } else {
+          clearReconnect();
+        }
+      };
+
+      ws.onerror = () => {
+        state.lastError = { code: "WEBSOCKET_ERROR", message: "WebSocket error" };
+        emit();
+      };
+    })();
+  }
+
+  function disconnect() {
+    intentionalClose = true;
+    clearReconnect();
+    state.currentRoomId = null;
+    state.connectionId = null;
+    state.presence = {};
+    state.chatMessages = [];
+    pendingPresence = null;
+    if (ws) {
+      setStatus("closing");
+      ws.close();
+      ws = null;
+    }
+    setStatus("closed");
+  }
+
+  function joinRoom(roomId: string, presence?: Presence, accessToken?: string) {
+    if (state.currentRoomId) {
+      send({ type: MSG_LEAVE_ROOM, payload: { roomId: state.currentRoomId } });
+    }
+    state.currentRoomId = roomId;
+    state.presence = {};
+    state.chatMessages = [];
+    pendingPresence = presence ?? null;
+    const payload: { roomId: string; presence?: Presence; accessToken?: string } = { roomId };
+    if (presence !== undefined) payload.presence = presence;
+    if (accessToken !== undefined) payload.accessToken = accessToken;
+    send({ type: MSG_JOIN_ROOM, payload });
+    emit();
+  }
+
+  function leaveRoom(roomId?: string) {
+    const target = roomId ?? state.currentRoomId;
+    if (target) {
+      send({ type: MSG_LEAVE_ROOM, payload: { roomId: target } });
+      if (target === state.currentRoomId) {
+        state.currentRoomId = null;
+        state.connectionId = null;
+        state.presence = {};
+        state.chatMessages = [];
+        pendingPresence = null;
+      }
+      emit();
+    }
+  }
+
+  function updatePresence(presence: Presence) {
+    pendingPresence = presence;
+    const now = Date.now();
+    if (now - lastPresenceUpdate < presenceThrottleMs) return;
+    lastPresenceUpdate = now;
+    send({ type: MSG_UPDATE_PRESENCE, payload: { presence } });
+  }
+
+  function broadcastEvent(event: string, payload?: unknown) {
+    send({ type: MSG_BROADCAST_EVENT, payload: { event, payload } });
+  }
+
+  function sendChat(message: string, metadata?: Record<string, unknown>) {
+    send({ type: MSG_SEND_CHAT, payload: { message, metadata } });
+  }
+
+  function subscribe(listener: (state: LiveSyncClientState) => void): () => void {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  return {
+    connect,
+    disconnect,
+    joinRoom,
+    leaveRoom,
+    updatePresence,
+    broadcastEvent,
+    sendChat,
+    getConnectionStatus: () => state.connectionStatus,
+    getPresence: () => ({ ...state.presence }),
+    getChatMessages: () => [...state.chatMessages],
+    getCurrentRoomId: () => state.currentRoomId,
+    getState: () => ({
+      connectionStatus: state.connectionStatus,
+      currentRoomId: state.currentRoomId,
+      connectionId: state.connectionId,
+      presence: { ...state.presence },
+      chatMessages: [...state.chatMessages],
+      lastError: state.lastError ? { ...state.lastError } : null,
+    }),
+    subscribe,
+  };
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+/**
+ * @openlivesync/client - Browser package for collaboration and presence.
+ */
+
+export { createLiveSyncClient } from "./client.js";
+export type {
+  LiveSyncClient,
+  LiveSyncClientConfig,
+  LiveSyncClientState,
+  ConnectionStatus,
+} from "./client.js";
+
+export type {
+  Presence,
+  UserInfo,
+  ClientMessage,
+  ServerMessage,
+  JoinRoomPayload,
+  LeaveRoomPayload,
+  UpdatePresencePayload,
+  BroadcastEventPayload,
+  SendChatPayload,
+  PresenceEntry,
+  RoomJoinedPayload,
+  PresenceUpdatedPayload,
+  BroadcastEventRelayPayload,
+  ChatMessagePayload,
+  StoredChatMessage,
+  ErrorPayload,
+  ChatMessageInput,
+} from "./protocol.js";
+export {
+  MSG_JOIN_ROOM,
+  MSG_LEAVE_ROOM,
+  MSG_UPDATE_PRESENCE,
+  MSG_BROADCAST_EVENT,
+  MSG_SEND_CHAT,
+  MSG_ROOM_JOINED,
+  MSG_PRESENCE_UPDATED,
+  MSG_BROADCAST_EVENT_RELAY,
+  MSG_CHAT_MESSAGE,
+  MSG_ERROR,
+} from "./protocol.js";