@hocuspocus/provider-react 4.0.0 → 4.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -101,7 +101,7 @@ const EVENT_PROP_MAP = {
101
101
  * </HocuspocusProviderWebsocketComponent>
102
102
  * ```
103
103
  */
104
- function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
104
+ function HocuspocusRoom({ children, name, document, token, sessionAwareness, ...eventHandlers }) {
105
105
  const hocuspocusContext = (0, react.useContext)(HocuspocusContext);
106
106
  if (!hocuspocusContext) throw new Error("HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent");
107
107
  const { websocketProvider } = hocuspocusContext;
@@ -109,7 +109,8 @@ function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
109
109
  name,
110
110
  websocketProvider,
111
111
  document,
112
- token
112
+ token,
113
+ sessionAwareness
113
114
  }));
114
115
  const destroyTimeoutRef = (0, react.useRef)(null);
115
116
  (0, react.useEffect)(() => {
@@ -119,7 +120,8 @@ function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
119
120
  name,
120
121
  websocketProvider,
121
122
  document,
122
- token
123
+ token,
124
+ sessionAwareness
123
125
  }));
124
126
  }
125
127
  }, [
@@ -1 +1 @@
1
- {"version":3,"file":"hocuspocus-provider-react.cjs","names":["HocuspocusProviderWebsocket","HocuspocusProvider"],"sources":["../src/context.ts","../src/HocuspocusProviderWebsocketComponent.tsx","../src/HocuspocusRoom.tsx","../src/hooks/useHocuspocusProvider.ts","../src/hooks/useHocuspocusAwareness.ts","../src/hooks/useHocuspocusConnectionStatus.ts","../src/hooks/useHocuspocusEvent.ts","../src/hooks/useHocuspocusSyncStatus.ts"],"sourcesContent":["import { createContext } from \"react\";\n\nimport type {\n\tHocuspocusContextValue,\n\tHocuspocusRoomContextValue,\n} from \"./types.ts\";\n\n/**\n * Context for the WebSocket connection shared across rooms\n */\nexport const HocuspocusContext =\n\tcreateContext<HocuspocusContextValue | null>(null);\n\n/**\n * Context for the room/document provider\n */\nexport const HocuspocusRoomContext =\n\tcreateContext<HocuspocusRoomContextValue | null>(null);\n","\"use client\";\n\nimport { HocuspocusProviderWebsocket } from \"@hocuspocus/provider\";\nimport { useEffect, useMemo, useRef } from \"react\";\n\nimport { HocuspocusContext } from \"./context.ts\";\nimport type { HocuspocusProviderWebsocketComponentProps } from \"./types.ts\";\n\n/**\n * HocuspocusProviderWebsocketComponent manages the WebSocket connection that is shared across all rooms.\n *\n * This component creates a single WebSocket connection that can be used by multiple\n * HocuspocusRoom components, preventing connection overhead when switching between documents.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom name=\"document-1\">\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusProviderWebsocketComponent({\n\tchildren,\n\turl,\n\twebsocketProvider: externalWebsocketProvider,\n}: HocuspocusProviderWebsocketComponentProps) {\n\tconst websocketRef = useRef<HocuspocusProviderWebsocket | null>(null);\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Create WebSocket provider once on mount.\n\t// Safe in StrictMode: useRef persists across double-renders, so the instance\n\t// is created only once. The deferred destruction in the effect below ensures\n\t// the second mount cancels the pending destroy before it fires.\n\tif (!websocketRef.current && !externalWebsocketProvider) {\n\t\twebsocketRef.current = new HocuspocusProviderWebsocket({\n\t\t\turl: url!,\n\t\t});\n\t}\n\n\tconst websocketProvider =\n\t\texternalWebsocketProvider ??\n\t\t(websocketRef.current as HocuspocusProviderWebsocket);\n\n\t// Cleanup on unmount with deferred destruction to handle StrictMode double-mount\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\treturn () => {\n\t\t\t// Only destroy if we created the websocket (not externally provided)\n\t\t\tif (!externalWebsocketProvider) {\n\t\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\t\tif (websocketRef.current) {\n\t\t\t\t\t\twebsocketRef.current.destroy();\n\t\t\t\t\t\twebsocketRef.current = null;\n\t\t\t\t\t}\n\t\t\t\t}, 0);\n\t\t\t}\n\t\t};\n\t}, [externalWebsocketProvider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\twebsocketProvider,\n\t\t}),\n\t\t[websocketProvider],\n\t);\n\n\treturn (\n\t\t<HocuspocusContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusContext.Provider>\n\t);\n}\n","\"use client\";\n\nimport { HocuspocusProvider } from \"@hocuspocus/provider\";\nimport { useContext, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { HocuspocusContext, HocuspocusRoomContext } from \"./context.ts\";\nimport type { HocuspocusProviderEvents, HocuspocusRoomProps } from \"./types.ts\";\n\n/**\n * Mapping from HocuspocusRoom `on*` prop names to provider event names.\n */\nconst EVENT_PROP_MAP: Record<string, keyof HocuspocusProviderEvents> = {\n\tonOpen: \"open\",\n\tonConnect: \"connect\",\n\tonClose: \"close\",\n\tonDisconnect: \"disconnect\",\n\tonStatus: \"status\",\n\tonSynced: \"synced\",\n\tonUnsyncedChanges: \"unsyncedChanges\",\n\tonMessage: \"message\",\n\tonOutgoingMessage: \"outgoingMessage\",\n\tonStateless: \"stateless\",\n\tonAuthenticated: \"authenticated\",\n\tonAuthenticationFailed: \"authenticationFailed\",\n\tonAwarenessUpdate: \"awarenessUpdate\",\n\tonAwarenessChange: \"awarenessChange\",\n\tonDestroy: \"destroy\",\n};\n\n/**\n * HocuspocusRoom manages the connection to a specific document.\n *\n * It uses the shared WebSocket from HocuspocusProviderWebsocketComponent and creates a document-specific\n * provider that connects on mount and disconnects on unmount.\n *\n * This component handles React's StrictMode gracefully by using deferred destruction,\n * preventing unnecessary reconnections during development double-mounts.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom\n * name=\"document-1\"\n * onAuthenticationFailed={(data) => console.error(data.reason)}\n * >\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusRoom({\n\tchildren,\n\tname,\n\tdocument,\n\ttoken,\n\t...eventHandlers\n}: HocuspocusRoomProps) {\n\tconst hocuspocusContext = useContext(HocuspocusContext);\n\n\tif (!hocuspocusContext) {\n\t\tthrow new Error(\n\t\t\t\"HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent\",\n\t\t);\n\t}\n\n\tconst { websocketProvider } = hocuspocusContext;\n\n\tconst [provider, setProvider] = useState(\n\t\t() =>\n\t\t\tnew HocuspocusProvider({\n\t\t\t\tname,\n\t\t\t\twebsocketProvider,\n\t\t\t\tdocument,\n\t\t\t\ttoken,\n\t\t\t}),\n\t);\n\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Recreate provider when name, document, or token changes.\n\t// Only compare `document`/`token` when the caller actually provided them —\n\t// otherwise the provider's constructor-initialized defaults (auto-created\n\t// Y.Doc, null token) will never match the undefined prop, causing a destroy\n\t// on every render (and in StrictMode, a stray CloseMessage for the current\n\t// doc once the provider is already attached).\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: provider.configuration holds the previous values we compare against — not a reactive dependency\n\tuseEffect(() => {\n\t\tconst shouldRecreate =\n\t\t\tprovider.configuration.name !== name ||\n\t\t\t(document !== undefined &&\n\t\t\t\tprovider.configuration.document !== document) ||\n\t\t\t(token !== undefined && provider.configuration.token !== token) ||\n\t\t\tprovider.configuration.websocketProvider !== websocketProvider;\n\n\t\tif (shouldRecreate) {\n\t\t\tprovider.destroy();\n\t\t\tsetProvider(\n\t\t\t\tnew HocuspocusProvider({\n\t\t\t\t\tname,\n\t\t\t\t\twebsocketProvider,\n\t\t\t\t\tdocument,\n\t\t\t\t\ttoken,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\t// eslint-disable-next-line react-hooks/exhaustive-deps\n\t}, [name, document, token, websocketProvider]);\n\n\t// Attach/detach lifecycle with deferred destruction for StrictMode\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\tprovider.attach();\n\n\t\treturn () => {\n\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\tprovider.destroy();\n\t\t\t}, 0);\n\t\t};\n\t}, [provider]);\n\n\t// Wire up on* event handler props with stable refs\n\tconst handlersRef = useRef(eventHandlers);\n\thandlersRef.current = eventHandlers;\n\n\tuseEffect(() => {\n\t\tconst cleanups: (() => void)[] = [];\n\n\t\tfor (const [propName, eventName] of Object.entries(EVENT_PROP_MAP)) {\n\t\t\tconst listener = (...args: unknown[]) => {\n\t\t\t\tconst handler = handlersRef.current[\n\t\t\t\t\tpropName as keyof typeof handlersRef.current\n\t\t\t\t] as ((...a: unknown[]) => void) | undefined;\n\t\t\t\thandler?.(...args);\n\t\t\t};\n\t\t\tprovider.on(eventName, listener);\n\t\t\tcleanups.push(() => provider.off(eventName, listener));\n\t\t}\n\n\t\treturn () => {\n\t\t\tfor (const cleanup of cleanups) {\n\t\t\t\tcleanup();\n\t\t\t}\n\t\t};\n\t}, [provider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\tprovider,\n\t\t}),\n\t\t[provider],\n\t);\n\n\treturn (\n\t\t<HocuspocusRoomContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusRoomContext.Provider>\n\t);\n}\n","import { useContext } from \"react\";\n\nimport { HocuspocusRoomContext } from \"../context.ts\";\n\n/**\n * Access the HocuspocusProvider instance for the current room.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @returns The HocuspocusProvider instance\n * @throws Error if used outside of HocuspocusRoom\n *\n * @example\n * ```tsx\n * function Editor() {\n * const provider = useHocuspocusProvider()\n *\n * const editor = useEditor({\n * extensions: [\n * Collaboration.configure({ document: provider.document }),\n * CollaborationCursor.configure({ provider }),\n * ],\n * })\n *\n * return <EditorContent editor={editor} />\n * }\n * ```\n */\nexport function useHocuspocusProvider() {\n\tconst context = useContext(HocuspocusRoomContext);\n\n\tif (!context) {\n\t\tthrow new Error(\"useHocuspocusProvider must be used within a HocuspocusRoom\");\n\t}\n\n\treturn context.provider;\n}\n","import { useCallback, useEffect, useRef, useSyncExternalStore } from \"react\";\n\nimport type { CollabUser } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the list of connected users in the document.\n *\n * This hook uses the Yjs awareness protocol to track users currently\n * connected to the document.\n *\n * @returns Array of user objects with their awareness state\n *\n * @example\n * ```tsx\n * function UserList() {\n * const users = useHocuspocusAwareness()\n *\n * return (\n * <div className=\"avatars\">\n * {users.map(user => (\n * <div\n * key={user.clientId}\n * style={{ backgroundColor: user.color }}\n * title={user.name}\n * >\n * {user.name?.[0]}\n * </div>\n * ))}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusAwareness(): CollabUser[] {\n\tconst provider = useHocuspocusProvider();\n\n\tconst versionRef = useRef(0);\n\tconst cacheRef = useRef<{ users: CollabUser[]; version: number }>({\n\t\tusers: [],\n\t\tversion: -1,\n\t});\n\n\t// Reset cache when provider changes so we don't serve stale users\n\t// from a previous provider instance.\n\tuseEffect(() => {\n\t\tversionRef.current++;\n\t\tcacheRef.current = { users: [], version: -1 };\n\t}, [provider]);\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tconst onChange = () => {\n\t\t\t\tversionRef.current++;\n\t\t\t\tonStoreChange();\n\t\t\t};\n\t\t\tprovider.awareness?.on(\"change\", onChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.awareness?.off(\"change\", onChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(() => {\n\t\tconst awareness = provider.awareness;\n\t\tif (!awareness) {\n\t\t\treturn [];\n\t\t}\n\n\t\t// Return cached value if awareness hasn't changed since last snapshot\n\t\tif (cacheRef.current.version === versionRef.current) {\n\t\t\treturn cacheRef.current.users;\n\t\t}\n\n\t\tconst users: CollabUser[] = [];\n\t\tawareness.getStates().forEach((state, clientId) => {\n\t\t\tusers.push({\n\t\t\t\tclientId,\n\t\t\t\t...state,\n\t\t\t});\n\t\t});\n\n\t\tcacheRef.current = { users, version: versionRef.current };\n\t\treturn users;\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { ConnectionStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the connection status of the collaboration provider.\n *\n * This hook uses React's useSyncExternalStore for optimal integration with\n * concurrent rendering features.\n *\n * @returns The current connection status: 'connecting', 'connected', or 'disconnected'\n *\n * @example\n * ```tsx\n * function ConnectionIndicator() {\n * const status = useHocuspocusConnectionStatus()\n *\n * return (\n * <div className={`status-${status}`}>\n * {status === 'connected' ? 'Online' : status === 'connecting' ? 'Connecting...' : 'Offline'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusConnectionStatus(): ConnectionStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"status\", onStoreChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"status\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(\n\t\t(): ConnectionStatus =>\n\t\t\tprovider.configuration.websocketProvider.status as ConnectionStatus,\n\t\t[provider],\n\t);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useEffect, useRef } from \"react\";\n\nimport type { HocuspocusProviderEvents } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to events from the HocuspocusProvider for the current room.\n *\n * The handler is stored in a ref so the subscription stays stable even if\n * the handler identity changes between renders.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @param event - The event name to subscribe to\n * @param handler - Callback invoked when the event fires\n *\n * @example\n * ```tsx\n * function AuthGuard() {\n * useHocuspocusEvent('authenticationFailed', (data) => {\n * console.error('Auth failed:', data.reason)\n * redirectToLogin()\n * })\n *\n * useHocuspocusEvent('close', (data) => {\n * console.log('Connection closed', data.event)\n * })\n *\n * return null\n * }\n * ```\n */\nexport function useHocuspocusEvent<E extends keyof HocuspocusProviderEvents>(\n\tevent: E,\n\thandler: HocuspocusProviderEvents[E] extends undefined\n\t\t? () => void\n\t\t: (data: HocuspocusProviderEvents[E]) => void,\n): void {\n\tconst provider = useHocuspocusProvider();\n\tconst handlerRef = useRef(handler);\n\thandlerRef.current = handler;\n\n\tuseEffect(() => {\n\t\tconst listener = (...args: unknown[]) => {\n\t\t\t(handlerRef.current as (...a: unknown[]) => void)(...args);\n\t\t};\n\t\tprovider.on(event, listener);\n\t\treturn () => {\n\t\t\tprovider.off(event, listener);\n\t\t};\n\t}, [provider, event]);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { SyncStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the sync status of local changes.\n *\n * This hook indicates whether local changes have been synced with the server.\n *\n * @returns The current sync status: 'synced' or 'syncing'\n *\n * @example\n * ```tsx\n * function SaveIndicator() {\n * const syncStatus = useHocuspocusSyncStatus()\n *\n * return (\n * <div>\n * {syncStatus === 'syncing' ? 'Saving...' : 'All changes saved'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusSyncStatus(): SyncStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"synced\", onStoreChange);\n\t\t\tprovider.on(\"unsyncedChanges\", onStoreChange);\n\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"synced\", onStoreChange);\n\t\t\t\tprovider.off(\"unsyncedChanges\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback((): SyncStatus => {\n\t\t// Check if there are unsynced changes\n\t\tif (provider.unsyncedChanges > 0) {\n\t\t\treturn \"syncing\";\n\t\t}\n\t\treturn \"synced\";\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"hocuspocus-provider-react.cjs","names":["HocuspocusProviderWebsocket","HocuspocusProvider"],"sources":["../src/context.ts","../src/HocuspocusProviderWebsocketComponent.tsx","../src/HocuspocusRoom.tsx","../src/hooks/useHocuspocusProvider.ts","../src/hooks/useHocuspocusAwareness.ts","../src/hooks/useHocuspocusConnectionStatus.ts","../src/hooks/useHocuspocusEvent.ts","../src/hooks/useHocuspocusSyncStatus.ts"],"sourcesContent":["import { createContext } from \"react\";\n\nimport type {\n\tHocuspocusContextValue,\n\tHocuspocusRoomContextValue,\n} from \"./types.ts\";\n\n/**\n * Context for the WebSocket connection shared across rooms\n */\nexport const HocuspocusContext =\n\tcreateContext<HocuspocusContextValue | null>(null);\n\n/**\n * Context for the room/document provider\n */\nexport const HocuspocusRoomContext =\n\tcreateContext<HocuspocusRoomContextValue | null>(null);\n","\"use client\";\n\nimport { HocuspocusProviderWebsocket } from \"@hocuspocus/provider\";\nimport { useEffect, useMemo, useRef } from \"react\";\n\nimport { HocuspocusContext } from \"./context.ts\";\nimport type { HocuspocusProviderWebsocketComponentProps } from \"./types.ts\";\n\n/**\n * HocuspocusProviderWebsocketComponent manages the WebSocket connection that is shared across all rooms.\n *\n * This component creates a single WebSocket connection that can be used by multiple\n * HocuspocusRoom components, preventing connection overhead when switching between documents.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom name=\"document-1\">\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusProviderWebsocketComponent({\n\tchildren,\n\turl,\n\twebsocketProvider: externalWebsocketProvider,\n}: HocuspocusProviderWebsocketComponentProps) {\n\tconst websocketRef = useRef<HocuspocusProviderWebsocket | null>(null);\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Create WebSocket provider once on mount.\n\t// Safe in StrictMode: useRef persists across double-renders, so the instance\n\t// is created only once. The deferred destruction in the effect below ensures\n\t// the second mount cancels the pending destroy before it fires.\n\tif (!websocketRef.current && !externalWebsocketProvider) {\n\t\twebsocketRef.current = new HocuspocusProviderWebsocket({\n\t\t\turl: url!,\n\t\t});\n\t}\n\n\tconst websocketProvider =\n\t\texternalWebsocketProvider ??\n\t\t(websocketRef.current as HocuspocusProviderWebsocket);\n\n\t// Cleanup on unmount with deferred destruction to handle StrictMode double-mount\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\treturn () => {\n\t\t\t// Only destroy if we created the websocket (not externally provided)\n\t\t\tif (!externalWebsocketProvider) {\n\t\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\t\tif (websocketRef.current) {\n\t\t\t\t\t\twebsocketRef.current.destroy();\n\t\t\t\t\t\twebsocketRef.current = null;\n\t\t\t\t\t}\n\t\t\t\t}, 0);\n\t\t\t}\n\t\t};\n\t}, [externalWebsocketProvider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\twebsocketProvider,\n\t\t}),\n\t\t[websocketProvider],\n\t);\n\n\treturn (\n\t\t<HocuspocusContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusContext.Provider>\n\t);\n}\n","\"use client\";\n\nimport { HocuspocusProvider } from \"@hocuspocus/provider\";\nimport { useContext, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { HocuspocusContext, HocuspocusRoomContext } from \"./context.ts\";\nimport type { HocuspocusProviderEvents, HocuspocusRoomProps } from \"./types.ts\";\n\n/**\n * Mapping from HocuspocusRoom `on*` prop names to provider event names.\n */\nconst EVENT_PROP_MAP: Record<string, keyof HocuspocusProviderEvents> = {\n\tonOpen: \"open\",\n\tonConnect: \"connect\",\n\tonClose: \"close\",\n\tonDisconnect: \"disconnect\",\n\tonStatus: \"status\",\n\tonSynced: \"synced\",\n\tonUnsyncedChanges: \"unsyncedChanges\",\n\tonMessage: \"message\",\n\tonOutgoingMessage: \"outgoingMessage\",\n\tonStateless: \"stateless\",\n\tonAuthenticated: \"authenticated\",\n\tonAuthenticationFailed: \"authenticationFailed\",\n\tonAwarenessUpdate: \"awarenessUpdate\",\n\tonAwarenessChange: \"awarenessChange\",\n\tonDestroy: \"destroy\",\n};\n\n/**\n * HocuspocusRoom manages the connection to a specific document.\n *\n * It uses the shared WebSocket from HocuspocusProviderWebsocketComponent and creates a document-specific\n * provider that connects on mount and disconnects on unmount.\n *\n * This component handles React's StrictMode gracefully by using deferred destruction,\n * preventing unnecessary reconnections during development double-mounts.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom\n * name=\"document-1\"\n * onAuthenticationFailed={(data) => console.error(data.reason)}\n * >\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusRoom({\n\tchildren,\n\tname,\n\tdocument,\n\ttoken,\n\tsessionAwareness,\n\t...eventHandlers\n}: HocuspocusRoomProps) {\n\tconst hocuspocusContext = useContext(HocuspocusContext);\n\n\tif (!hocuspocusContext) {\n\t\tthrow new Error(\n\t\t\t\"HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent\",\n\t\t);\n\t}\n\n\tconst { websocketProvider } = hocuspocusContext;\n\n\tconst [provider, setProvider] = useState(\n\t\t() =>\n\t\t\tnew HocuspocusProvider({\n\t\t\t\tname,\n\t\t\t\twebsocketProvider,\n\t\t\t\tdocument,\n\t\t\t\ttoken,\n\t\t\t\tsessionAwareness,\n\t\t\t}),\n\t);\n\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Recreate provider when name, document, or token changes.\n\t// Only compare `document`/`token` when the caller actually provided them —\n\t// otherwise the provider's constructor-initialized defaults (auto-created\n\t// Y.Doc, null token) will never match the undefined prop, causing a destroy\n\t// on every render (and in StrictMode, a stray CloseMessage for the current\n\t// doc once the provider is already attached).\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: provider.configuration holds the previous values we compare against — not a reactive dependency\n\tuseEffect(() => {\n\t\tconst shouldRecreate =\n\t\t\tprovider.configuration.name !== name ||\n\t\t\t(document !== undefined &&\n\t\t\t\tprovider.configuration.document !== document) ||\n\t\t\t(token !== undefined && provider.configuration.token !== token) ||\n\t\t\tprovider.configuration.websocketProvider !== websocketProvider;\n\n\t\tif (shouldRecreate) {\n\t\t\tprovider.destroy();\n\t\t\tsetProvider(\n\t\t\t\tnew HocuspocusProvider({\n\t\t\t\t\tname,\n\t\t\t\t\twebsocketProvider,\n\t\t\t\t\tdocument,\n\t\t\t\t\ttoken,\n\t\t\t\t\tsessionAwareness,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\t// eslint-disable-next-line react-hooks/exhaustive-deps\n\t}, [name, document, token, websocketProvider]);\n\n\t// Attach/detach lifecycle with deferred destruction for StrictMode\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\tprovider.attach();\n\n\t\treturn () => {\n\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\tprovider.destroy();\n\t\t\t}, 0);\n\t\t};\n\t}, [provider]);\n\n\t// Wire up on* event handler props with stable refs\n\tconst handlersRef = useRef(eventHandlers);\n\thandlersRef.current = eventHandlers;\n\n\tuseEffect(() => {\n\t\tconst cleanups: (() => void)[] = [];\n\n\t\tfor (const [propName, eventName] of Object.entries(EVENT_PROP_MAP)) {\n\t\t\tconst listener = (...args: unknown[]) => {\n\t\t\t\tconst handler = handlersRef.current[\n\t\t\t\t\tpropName as keyof typeof handlersRef.current\n\t\t\t\t] as ((...a: unknown[]) => void) | undefined;\n\t\t\t\thandler?.(...args);\n\t\t\t};\n\t\t\tprovider.on(eventName, listener);\n\t\t\tcleanups.push(() => provider.off(eventName, listener));\n\t\t}\n\n\t\treturn () => {\n\t\t\tfor (const cleanup of cleanups) {\n\t\t\t\tcleanup();\n\t\t\t}\n\t\t};\n\t}, [provider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\tprovider,\n\t\t}),\n\t\t[provider],\n\t);\n\n\treturn (\n\t\t<HocuspocusRoomContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusRoomContext.Provider>\n\t);\n}\n","import { useContext } from \"react\";\n\nimport { HocuspocusRoomContext } from \"../context.ts\";\n\n/**\n * Access the HocuspocusProvider instance for the current room.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @returns The HocuspocusProvider instance\n * @throws Error if used outside of HocuspocusRoom\n *\n * @example\n * ```tsx\n * function Editor() {\n * const provider = useHocuspocusProvider()\n *\n * const editor = useEditor({\n * extensions: [\n * Collaboration.configure({ document: provider.document }),\n * CollaborationCursor.configure({ provider }),\n * ],\n * })\n *\n * return <EditorContent editor={editor} />\n * }\n * ```\n */\nexport function useHocuspocusProvider() {\n\tconst context = useContext(HocuspocusRoomContext);\n\n\tif (!context) {\n\t\tthrow new Error(\"useHocuspocusProvider must be used within a HocuspocusRoom\");\n\t}\n\n\treturn context.provider;\n}\n","import { useCallback, useEffect, useRef, useSyncExternalStore } from \"react\";\n\nimport type { CollabUser } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the list of connected users in the document.\n *\n * This hook uses the Yjs awareness protocol to track users currently\n * connected to the document.\n *\n * @returns Array of user objects with their awareness state\n *\n * @example\n * ```tsx\n * function UserList() {\n * const users = useHocuspocusAwareness()\n *\n * return (\n * <div className=\"avatars\">\n * {users.map(user => (\n * <div\n * key={user.clientId}\n * style={{ backgroundColor: user.color }}\n * title={user.name}\n * >\n * {user.name?.[0]}\n * </div>\n * ))}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusAwareness(): CollabUser[] {\n\tconst provider = useHocuspocusProvider();\n\n\tconst versionRef = useRef(0);\n\tconst cacheRef = useRef<{ users: CollabUser[]; version: number }>({\n\t\tusers: [],\n\t\tversion: -1,\n\t});\n\n\t// Reset cache when provider changes so we don't serve stale users\n\t// from a previous provider instance.\n\tuseEffect(() => {\n\t\tversionRef.current++;\n\t\tcacheRef.current = { users: [], version: -1 };\n\t}, [provider]);\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tconst onChange = () => {\n\t\t\t\tversionRef.current++;\n\t\t\t\tonStoreChange();\n\t\t\t};\n\t\t\tprovider.awareness?.on(\"change\", onChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.awareness?.off(\"change\", onChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(() => {\n\t\tconst awareness = provider.awareness;\n\t\tif (!awareness) {\n\t\t\treturn [];\n\t\t}\n\n\t\t// Return cached value if awareness hasn't changed since last snapshot\n\t\tif (cacheRef.current.version === versionRef.current) {\n\t\t\treturn cacheRef.current.users;\n\t\t}\n\n\t\tconst users: CollabUser[] = [];\n\t\tawareness.getStates().forEach((state, clientId) => {\n\t\t\tusers.push({\n\t\t\t\tclientId,\n\t\t\t\t...state,\n\t\t\t});\n\t\t});\n\n\t\tcacheRef.current = { users, version: versionRef.current };\n\t\treturn users;\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { ConnectionStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the connection status of the collaboration provider.\n *\n * This hook uses React's useSyncExternalStore for optimal integration with\n * concurrent rendering features.\n *\n * @returns The current connection status: 'connecting', 'connected', or 'disconnected'\n *\n * @example\n * ```tsx\n * function ConnectionIndicator() {\n * const status = useHocuspocusConnectionStatus()\n *\n * return (\n * <div className={`status-${status}`}>\n * {status === 'connected' ? 'Online' : status === 'connecting' ? 'Connecting...' : 'Offline'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusConnectionStatus(): ConnectionStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"status\", onStoreChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"status\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(\n\t\t(): ConnectionStatus =>\n\t\t\tprovider.configuration.websocketProvider.status as ConnectionStatus,\n\t\t[provider],\n\t);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useEffect, useRef } from \"react\";\n\nimport type { HocuspocusProviderEvents } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to events from the HocuspocusProvider for the current room.\n *\n * The handler is stored in a ref so the subscription stays stable even if\n * the handler identity changes between renders.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @param event - The event name to subscribe to\n * @param handler - Callback invoked when the event fires\n *\n * @example\n * ```tsx\n * function AuthGuard() {\n * useHocuspocusEvent('authenticationFailed', (data) => {\n * console.error('Auth failed:', data.reason)\n * redirectToLogin()\n * })\n *\n * useHocuspocusEvent('close', (data) => {\n * console.log('Connection closed', data.event)\n * })\n *\n * return null\n * }\n * ```\n */\nexport function useHocuspocusEvent<E extends keyof HocuspocusProviderEvents>(\n\tevent: E,\n\thandler: HocuspocusProviderEvents[E] extends undefined\n\t\t? () => void\n\t\t: (data: HocuspocusProviderEvents[E]) => void,\n): void {\n\tconst provider = useHocuspocusProvider();\n\tconst handlerRef = useRef(handler);\n\thandlerRef.current = handler;\n\n\tuseEffect(() => {\n\t\tconst listener = (...args: unknown[]) => {\n\t\t\t(handlerRef.current as (...a: unknown[]) => void)(...args);\n\t\t};\n\t\tprovider.on(event, listener);\n\t\treturn () => {\n\t\t\tprovider.off(event, listener);\n\t\t};\n\t}, [provider, event]);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { SyncStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the sync status of local changes.\n *\n * This hook indicates whether local changes have been synced with the server.\n *\n * @returns The current sync status: 'synced' or 'syncing'\n *\n * @example\n * ```tsx\n * function SaveIndicator() {\n * const syncStatus = useHocuspocusSyncStatus()\n *\n * return (\n * <div>\n * {syncStatus === 'syncing' ? 'Saving...' : 'All changes saved'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusSyncStatus(): SyncStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"synced\", onStoreChange);\n\t\t\tprovider.on(\"unsyncedChanges\", onStoreChange);\n\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"synced\", onStoreChange);\n\t\t\t\tprovider.off(\"unsyncedChanges\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback((): SyncStatus => {\n\t\t// Check if there are unsynced changes\n\t\tif (provider.unsyncedChanges > 0) {\n\t\t\treturn \"syncing\";\n\t\t}\n\t\treturn \"synced\";\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n"],"mappings":"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"}
@@ -100,7 +100,7 @@ const EVENT_PROP_MAP = {
100
100
  * </HocuspocusProviderWebsocketComponent>
101
101
  * ```
102
102
  */
103
- function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
103
+ function HocuspocusRoom({ children, name, document, token, sessionAwareness, ...eventHandlers }) {
104
104
  const hocuspocusContext = useContext(HocuspocusContext);
105
105
  if (!hocuspocusContext) throw new Error("HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent");
106
106
  const { websocketProvider } = hocuspocusContext;
@@ -108,7 +108,8 @@ function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
108
108
  name,
109
109
  websocketProvider,
110
110
  document,
111
- token
111
+ token,
112
+ sessionAwareness
112
113
  }));
113
114
  const destroyTimeoutRef = useRef(null);
114
115
  useEffect(() => {
@@ -118,7 +119,8 @@ function HocuspocusRoom({ children, name, document, token, ...eventHandlers }) {
118
119
  name,
119
120
  websocketProvider,
120
121
  document,
121
- token
122
+ token,
123
+ sessionAwareness
122
124
  }));
123
125
  }
124
126
  }, [
@@ -1 +1 @@
1
- {"version":3,"file":"hocuspocus-provider-react.esm.js","names":[],"sources":["../src/context.ts","../src/HocuspocusProviderWebsocketComponent.tsx","../src/HocuspocusRoom.tsx","../src/hooks/useHocuspocusProvider.ts","../src/hooks/useHocuspocusAwareness.ts","../src/hooks/useHocuspocusConnectionStatus.ts","../src/hooks/useHocuspocusEvent.ts","../src/hooks/useHocuspocusSyncStatus.ts"],"sourcesContent":["import { createContext } from \"react\";\n\nimport type {\n\tHocuspocusContextValue,\n\tHocuspocusRoomContextValue,\n} from \"./types.ts\";\n\n/**\n * Context for the WebSocket connection shared across rooms\n */\nexport const HocuspocusContext =\n\tcreateContext<HocuspocusContextValue | null>(null);\n\n/**\n * Context for the room/document provider\n */\nexport const HocuspocusRoomContext =\n\tcreateContext<HocuspocusRoomContextValue | null>(null);\n","\"use client\";\n\nimport { HocuspocusProviderWebsocket } from \"@hocuspocus/provider\";\nimport { useEffect, useMemo, useRef } from \"react\";\n\nimport { HocuspocusContext } from \"./context.ts\";\nimport type { HocuspocusProviderWebsocketComponentProps } from \"./types.ts\";\n\n/**\n * HocuspocusProviderWebsocketComponent manages the WebSocket connection that is shared across all rooms.\n *\n * This component creates a single WebSocket connection that can be used by multiple\n * HocuspocusRoom components, preventing connection overhead when switching between documents.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom name=\"document-1\">\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusProviderWebsocketComponent({\n\tchildren,\n\turl,\n\twebsocketProvider: externalWebsocketProvider,\n}: HocuspocusProviderWebsocketComponentProps) {\n\tconst websocketRef = useRef<HocuspocusProviderWebsocket | null>(null);\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Create WebSocket provider once on mount.\n\t// Safe in StrictMode: useRef persists across double-renders, so the instance\n\t// is created only once. The deferred destruction in the effect below ensures\n\t// the second mount cancels the pending destroy before it fires.\n\tif (!websocketRef.current && !externalWebsocketProvider) {\n\t\twebsocketRef.current = new HocuspocusProviderWebsocket({\n\t\t\turl: url!,\n\t\t});\n\t}\n\n\tconst websocketProvider =\n\t\texternalWebsocketProvider ??\n\t\t(websocketRef.current as HocuspocusProviderWebsocket);\n\n\t// Cleanup on unmount with deferred destruction to handle StrictMode double-mount\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\treturn () => {\n\t\t\t// Only destroy if we created the websocket (not externally provided)\n\t\t\tif (!externalWebsocketProvider) {\n\t\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\t\tif (websocketRef.current) {\n\t\t\t\t\t\twebsocketRef.current.destroy();\n\t\t\t\t\t\twebsocketRef.current = null;\n\t\t\t\t\t}\n\t\t\t\t}, 0);\n\t\t\t}\n\t\t};\n\t}, [externalWebsocketProvider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\twebsocketProvider,\n\t\t}),\n\t\t[websocketProvider],\n\t);\n\n\treturn (\n\t\t<HocuspocusContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusContext.Provider>\n\t);\n}\n","\"use client\";\n\nimport { HocuspocusProvider } from \"@hocuspocus/provider\";\nimport { useContext, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { HocuspocusContext, HocuspocusRoomContext } from \"./context.ts\";\nimport type { HocuspocusProviderEvents, HocuspocusRoomProps } from \"./types.ts\";\n\n/**\n * Mapping from HocuspocusRoom `on*` prop names to provider event names.\n */\nconst EVENT_PROP_MAP: Record<string, keyof HocuspocusProviderEvents> = {\n\tonOpen: \"open\",\n\tonConnect: \"connect\",\n\tonClose: \"close\",\n\tonDisconnect: \"disconnect\",\n\tonStatus: \"status\",\n\tonSynced: \"synced\",\n\tonUnsyncedChanges: \"unsyncedChanges\",\n\tonMessage: \"message\",\n\tonOutgoingMessage: \"outgoingMessage\",\n\tonStateless: \"stateless\",\n\tonAuthenticated: \"authenticated\",\n\tonAuthenticationFailed: \"authenticationFailed\",\n\tonAwarenessUpdate: \"awarenessUpdate\",\n\tonAwarenessChange: \"awarenessChange\",\n\tonDestroy: \"destroy\",\n};\n\n/**\n * HocuspocusRoom manages the connection to a specific document.\n *\n * It uses the shared WebSocket from HocuspocusProviderWebsocketComponent and creates a document-specific\n * provider that connects on mount and disconnects on unmount.\n *\n * This component handles React's StrictMode gracefully by using deferred destruction,\n * preventing unnecessary reconnections during development double-mounts.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom\n * name=\"document-1\"\n * onAuthenticationFailed={(data) => console.error(data.reason)}\n * >\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusRoom({\n\tchildren,\n\tname,\n\tdocument,\n\ttoken,\n\t...eventHandlers\n}: HocuspocusRoomProps) {\n\tconst hocuspocusContext = useContext(HocuspocusContext);\n\n\tif (!hocuspocusContext) {\n\t\tthrow new Error(\n\t\t\t\"HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent\",\n\t\t);\n\t}\n\n\tconst { websocketProvider } = hocuspocusContext;\n\n\tconst [provider, setProvider] = useState(\n\t\t() =>\n\t\t\tnew HocuspocusProvider({\n\t\t\t\tname,\n\t\t\t\twebsocketProvider,\n\t\t\t\tdocument,\n\t\t\t\ttoken,\n\t\t\t}),\n\t);\n\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Recreate provider when name, document, or token changes.\n\t// Only compare `document`/`token` when the caller actually provided them —\n\t// otherwise the provider's constructor-initialized defaults (auto-created\n\t// Y.Doc, null token) will never match the undefined prop, causing a destroy\n\t// on every render (and in StrictMode, a stray CloseMessage for the current\n\t// doc once the provider is already attached).\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: provider.configuration holds the previous values we compare against — not a reactive dependency\n\tuseEffect(() => {\n\t\tconst shouldRecreate =\n\t\t\tprovider.configuration.name !== name ||\n\t\t\t(document !== undefined &&\n\t\t\t\tprovider.configuration.document !== document) ||\n\t\t\t(token !== undefined && provider.configuration.token !== token) ||\n\t\t\tprovider.configuration.websocketProvider !== websocketProvider;\n\n\t\tif (shouldRecreate) {\n\t\t\tprovider.destroy();\n\t\t\tsetProvider(\n\t\t\t\tnew HocuspocusProvider({\n\t\t\t\t\tname,\n\t\t\t\t\twebsocketProvider,\n\t\t\t\t\tdocument,\n\t\t\t\t\ttoken,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\t// eslint-disable-next-line react-hooks/exhaustive-deps\n\t}, [name, document, token, websocketProvider]);\n\n\t// Attach/detach lifecycle with deferred destruction for StrictMode\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\tprovider.attach();\n\n\t\treturn () => {\n\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\tprovider.destroy();\n\t\t\t}, 0);\n\t\t};\n\t}, [provider]);\n\n\t// Wire up on* event handler props with stable refs\n\tconst handlersRef = useRef(eventHandlers);\n\thandlersRef.current = eventHandlers;\n\n\tuseEffect(() => {\n\t\tconst cleanups: (() => void)[] = [];\n\n\t\tfor (const [propName, eventName] of Object.entries(EVENT_PROP_MAP)) {\n\t\t\tconst listener = (...args: unknown[]) => {\n\t\t\t\tconst handler = handlersRef.current[\n\t\t\t\t\tpropName as keyof typeof handlersRef.current\n\t\t\t\t] as ((...a: unknown[]) => void) | undefined;\n\t\t\t\thandler?.(...args);\n\t\t\t};\n\t\t\tprovider.on(eventName, listener);\n\t\t\tcleanups.push(() => provider.off(eventName, listener));\n\t\t}\n\n\t\treturn () => {\n\t\t\tfor (const cleanup of cleanups) {\n\t\t\t\tcleanup();\n\t\t\t}\n\t\t};\n\t}, [provider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\tprovider,\n\t\t}),\n\t\t[provider],\n\t);\n\n\treturn (\n\t\t<HocuspocusRoomContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusRoomContext.Provider>\n\t);\n}\n","import { useContext } from \"react\";\n\nimport { HocuspocusRoomContext } from \"../context.ts\";\n\n/**\n * Access the HocuspocusProvider instance for the current room.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @returns The HocuspocusProvider instance\n * @throws Error if used outside of HocuspocusRoom\n *\n * @example\n * ```tsx\n * function Editor() {\n * const provider = useHocuspocusProvider()\n *\n * const editor = useEditor({\n * extensions: [\n * Collaboration.configure({ document: provider.document }),\n * CollaborationCursor.configure({ provider }),\n * ],\n * })\n *\n * return <EditorContent editor={editor} />\n * }\n * ```\n */\nexport function useHocuspocusProvider() {\n\tconst context = useContext(HocuspocusRoomContext);\n\n\tif (!context) {\n\t\tthrow new Error(\"useHocuspocusProvider must be used within a HocuspocusRoom\");\n\t}\n\n\treturn context.provider;\n}\n","import { useCallback, useEffect, useRef, useSyncExternalStore } from \"react\";\n\nimport type { CollabUser } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the list of connected users in the document.\n *\n * This hook uses the Yjs awareness protocol to track users currently\n * connected to the document.\n *\n * @returns Array of user objects with their awareness state\n *\n * @example\n * ```tsx\n * function UserList() {\n * const users = useHocuspocusAwareness()\n *\n * return (\n * <div className=\"avatars\">\n * {users.map(user => (\n * <div\n * key={user.clientId}\n * style={{ backgroundColor: user.color }}\n * title={user.name}\n * >\n * {user.name?.[0]}\n * </div>\n * ))}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusAwareness(): CollabUser[] {\n\tconst provider = useHocuspocusProvider();\n\n\tconst versionRef = useRef(0);\n\tconst cacheRef = useRef<{ users: CollabUser[]; version: number }>({\n\t\tusers: [],\n\t\tversion: -1,\n\t});\n\n\t// Reset cache when provider changes so we don't serve stale users\n\t// from a previous provider instance.\n\tuseEffect(() => {\n\t\tversionRef.current++;\n\t\tcacheRef.current = { users: [], version: -1 };\n\t}, [provider]);\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tconst onChange = () => {\n\t\t\t\tversionRef.current++;\n\t\t\t\tonStoreChange();\n\t\t\t};\n\t\t\tprovider.awareness?.on(\"change\", onChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.awareness?.off(\"change\", onChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(() => {\n\t\tconst awareness = provider.awareness;\n\t\tif (!awareness) {\n\t\t\treturn [];\n\t\t}\n\n\t\t// Return cached value if awareness hasn't changed since last snapshot\n\t\tif (cacheRef.current.version === versionRef.current) {\n\t\t\treturn cacheRef.current.users;\n\t\t}\n\n\t\tconst users: CollabUser[] = [];\n\t\tawareness.getStates().forEach((state, clientId) => {\n\t\t\tusers.push({\n\t\t\t\tclientId,\n\t\t\t\t...state,\n\t\t\t});\n\t\t});\n\n\t\tcacheRef.current = { users, version: versionRef.current };\n\t\treturn users;\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { ConnectionStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the connection status of the collaboration provider.\n *\n * This hook uses React's useSyncExternalStore for optimal integration with\n * concurrent rendering features.\n *\n * @returns The current connection status: 'connecting', 'connected', or 'disconnected'\n *\n * @example\n * ```tsx\n * function ConnectionIndicator() {\n * const status = useHocuspocusConnectionStatus()\n *\n * return (\n * <div className={`status-${status}`}>\n * {status === 'connected' ? 'Online' : status === 'connecting' ? 'Connecting...' : 'Offline'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusConnectionStatus(): ConnectionStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"status\", onStoreChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"status\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(\n\t\t(): ConnectionStatus =>\n\t\t\tprovider.configuration.websocketProvider.status as ConnectionStatus,\n\t\t[provider],\n\t);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useEffect, useRef } from \"react\";\n\nimport type { HocuspocusProviderEvents } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to events from the HocuspocusProvider for the current room.\n *\n * The handler is stored in a ref so the subscription stays stable even if\n * the handler identity changes between renders.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @param event - The event name to subscribe to\n * @param handler - Callback invoked when the event fires\n *\n * @example\n * ```tsx\n * function AuthGuard() {\n * useHocuspocusEvent('authenticationFailed', (data) => {\n * console.error('Auth failed:', data.reason)\n * redirectToLogin()\n * })\n *\n * useHocuspocusEvent('close', (data) => {\n * console.log('Connection closed', data.event)\n * })\n *\n * return null\n * }\n * ```\n */\nexport function useHocuspocusEvent<E extends keyof HocuspocusProviderEvents>(\n\tevent: E,\n\thandler: HocuspocusProviderEvents[E] extends undefined\n\t\t? () => void\n\t\t: (data: HocuspocusProviderEvents[E]) => void,\n): void {\n\tconst provider = useHocuspocusProvider();\n\tconst handlerRef = useRef(handler);\n\thandlerRef.current = handler;\n\n\tuseEffect(() => {\n\t\tconst listener = (...args: unknown[]) => {\n\t\t\t(handlerRef.current as (...a: unknown[]) => void)(...args);\n\t\t};\n\t\tprovider.on(event, listener);\n\t\treturn () => {\n\t\t\tprovider.off(event, listener);\n\t\t};\n\t}, [provider, event]);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { SyncStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the sync status of local changes.\n *\n * This hook indicates whether local changes have been synced with the server.\n *\n * @returns The current sync status: 'synced' or 'syncing'\n *\n * @example\n * ```tsx\n * function SaveIndicator() {\n * const syncStatus = useHocuspocusSyncStatus()\n *\n * return (\n * <div>\n * {syncStatus === 'syncing' ? 'Saving...' : 'All changes saved'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusSyncStatus(): SyncStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"synced\", onStoreChange);\n\t\t\tprovider.on(\"unsyncedChanges\", onStoreChange);\n\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"synced\", onStoreChange);\n\t\t\t\tprovider.off(\"unsyncedChanges\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback((): SyncStatus => {\n\t\t// Check if there are unsynced changes\n\t\tif (provider.unsyncedChanges > 0) {\n\t\t\treturn \"syncing\";\n\t\t}\n\t\treturn \"synced\";\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n"],"mappings":";;;;;;;;;;AAUA,MAAa,oBACZ,cAA6C,KAAK;;;;AAKnD,MAAa,wBACZ,cAAiD,KAAK;;;;;;;;;;;;;;;;;;;ACMvD,SAAgB,qCAAqC,EACpD,UACA,KACA,mBAAmB,6BAC0B;CAC7C,MAAM,eAAe,OAA2C,KAAK;CACrE,MAAM,oBAAoB,OAA6C,KAAK;AAM5E,KAAI,CAAC,aAAa,WAAW,CAAC,0BAC7B,cAAa,UAAU,IAAI,4BAA4B,EACjD,KACL,CAAC;CAGH,MAAM,oBACL,6BACC,aAAa;AAGf,iBAAgB;AACf,MAAI,kBAAkB,SAAS;AAC9B,gBAAa,kBAAkB,QAAQ;AACvC,qBAAkB,UAAU;;AAG7B,eAAa;AAEZ,OAAI,CAAC,0BACJ,mBAAkB,UAAU,iBAAiB;AAC5C,QAAI,aAAa,SAAS;AACzB,kBAAa,QAAQ,SAAS;AAC9B,kBAAa,UAAU;;MAEtB,EAAE;;IAGL,CAAC,0BAA0B,CAAC;CAE/B,MAAM,eAAe,eACb,EACN,mBACA,GACD,CAAC,kBAAkB,CACnB;AAED,QACC,oBAAC,kBAAkB,UAAnB;EAA4B,OAAO;EACjC;EAC2B;;;;;;;;AChE/B,MAAM,iBAAiE;CACtE,QAAQ;CACR,WAAW;CACX,SAAS;CACT,cAAc;CACd,UAAU;CACV,UAAU;CACV,mBAAmB;CACnB,WAAW;CACX,mBAAmB;CACnB,aAAa;CACb,iBAAiB;CACjB,wBAAwB;CACxB,mBAAmB;CACnB,mBAAmB;CACnB,WAAW;CACX;;;;;;;;;;;;;;;;;;;;;;AAuBD,SAAgB,eAAe,EAC9B,UACA,MACA,UACA,OACA,GAAG,iBACoB;CACvB,MAAM,oBAAoB,WAAW,kBAAkB;AAEvD,KAAI,CAAC,kBACJ,OAAM,IAAI,MACT,4EACA;CAGF,MAAM,EAAE,sBAAsB;CAE9B,MAAM,CAAC,UAAU,eAAe,eAE9B,IAAI,mBAAmB;EACtB;EACA;EACA;EACA;EACA,CAAC,CACH;CAED,MAAM,oBAAoB,OAA6C,KAAK;AAS5E,iBAAgB;AAQf,MANC,SAAS,cAAc,SAAS,QAC/B,aAAa,UACb,SAAS,cAAc,aAAa,YACpC,UAAU,UAAa,SAAS,cAAc,UAAU,SACzD,SAAS,cAAc,sBAAsB,mBAE1B;AACnB,YAAS,SAAS;AAClB,eACC,IAAI,mBAAmB;IACtB;IACA;IACA;IACA;IACA,CAAC,CACF;;IAGA;EAAC;EAAM;EAAU;EAAO;EAAkB,CAAC;AAG9C,iBAAgB;AACf,MAAI,kBAAkB,SAAS;AAC9B,gBAAa,kBAAkB,QAAQ;AACvC,qBAAkB,UAAU;;AAG7B,WAAS,QAAQ;AAEjB,eAAa;AACZ,qBAAkB,UAAU,iBAAiB;AAC5C,aAAS,SAAS;MAChB,EAAE;;IAEJ,CAAC,SAAS,CAAC;CAGd,MAAM,cAAc,OAAO,cAAc;AACzC,aAAY,UAAU;AAEtB,iBAAgB;EACf,MAAM,WAA2B,EAAE;AAEnC,OAAK,MAAM,CAAC,UAAU,cAAc,OAAO,QAAQ,eAAe,EAAE;GACnE,MAAM,YAAY,GAAG,SAAoB;IACxC,MAAM,UAAU,YAAY,QAC3B;AAED,cAAU,GAAG,KAAK;;AAEnB,YAAS,GAAG,WAAW,SAAS;AAChC,YAAS,WAAW,SAAS,IAAI,WAAW,SAAS,CAAC;;AAGvD,eAAa;AACZ,QAAK,MAAM,WAAW,SACrB,UAAS;;IAGT,CAAC,SAAS,CAAC;CAEd,MAAM,eAAe,eACb,EACN,UACA,GACD,CAAC,SAAS,CACV;AAED,QACC,oBAAC,sBAAsB,UAAvB;EAAgC,OAAO;EACrC;EAC+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACnInC,SAAgB,wBAAwB;CACvC,MAAM,UAAU,WAAW,sBAAsB;AAEjD,KAAI,CAAC,QACJ,OAAM,IAAI,MAAM,6DAA6D;AAG9E,QAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACDhB,SAAgB,yBAAuC;CACtD,MAAM,WAAW,uBAAuB;CAExC,MAAM,aAAa,OAAO,EAAE;CAC5B,MAAM,WAAW,OAAiD;EACjE,OAAO,EAAE;EACT,SAAS;EACT,CAAC;AAIF,iBAAgB;AACf,aAAW;AACX,WAAS,UAAU;GAAE,OAAO,EAAE;GAAE,SAAS;GAAI;IAC3C,CAAC,SAAS,CAAC;CAEd,MAAM,YAAY,aAChB,kBAA8B;EAC9B,MAAM,iBAAiB;AACtB,cAAW;AACX,kBAAe;;AAEhB,WAAS,WAAW,GAAG,UAAU,SAAS;AAC1C,eAAa;AACZ,YAAS,WAAW,IAAI,UAAU,SAAS;;IAG7C,CAAC,SAAS,CACV;CAED,MAAM,cAAc,kBAAkB;EACrC,MAAM,YAAY,SAAS;AAC3B,MAAI,CAAC,UACJ,QAAO,EAAE;AAIV,MAAI,SAAS,QAAQ,YAAY,WAAW,QAC3C,QAAO,SAAS,QAAQ;EAGzB,MAAM,QAAsB,EAAE;AAC9B,YAAU,WAAW,CAAC,SAAS,OAAO,aAAa;AAClD,SAAM,KAAK;IACV;IACA,GAAG;IACH,CAAC;IACD;AAEF,WAAS,UAAU;GAAE;GAAO,SAAS,WAAW;GAAS;AACzD,SAAO;IACL,CAAC,SAAS,CAAC;AAEd,QAAO,qBAAqB,WAAW,aAAa,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;AC7DjE,SAAgB,gCAAkD;CACjE,MAAM,WAAW,uBAAuB;CAExC,MAAM,YAAY,aAChB,kBAA8B;AAC9B,WAAS,GAAG,UAAU,cAAc;AACpC,eAAa;AACZ,YAAS,IAAI,UAAU,cAAc;;IAGvC,CAAC,SAAS,CACV;CAED,MAAM,cAAc,kBAElB,SAAS,cAAc,kBAAkB,QAC1C,CAAC,SAAS,CACV;AAED,QAAO,qBAAqB,WAAW,aAAa,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACbjE,SAAgB,mBACf,OACA,SAGO;CACP,MAAM,WAAW,uBAAuB;CACxC,MAAM,aAAa,OAAO,QAAQ;AAClC,YAAW,UAAU;AAErB,iBAAgB;EACf,MAAM,YAAY,GAAG,SAAoB;AACxC,GAAC,WAAW,QAAsC,GAAG,KAAK;;AAE3D,WAAS,GAAG,OAAO,SAAS;AAC5B,eAAa;AACZ,YAAS,IAAI,OAAO,SAAS;;IAE5B,CAAC,UAAU,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;ACzBtB,SAAgB,0BAAsC;CACrD,MAAM,WAAW,uBAAuB;CAExC,MAAM,YAAY,aAChB,kBAA8B;AAC9B,WAAS,GAAG,UAAU,cAAc;AACpC,WAAS,GAAG,mBAAmB,cAAc;AAE7C,eAAa;AACZ,YAAS,IAAI,UAAU,cAAc;AACrC,YAAS,IAAI,mBAAmB,cAAc;;IAGhD,CAAC,SAAS,CACV;CAED,MAAM,cAAc,kBAA8B;AAEjD,MAAI,SAAS,kBAAkB,EAC9B,QAAO;AAER,SAAO;IACL,CAAC,SAAS,CAAC;AAEd,QAAO,qBAAqB,WAAW,aAAa,YAAY"}
1
+ {"version":3,"file":"hocuspocus-provider-react.esm.js","names":[],"sources":["../src/context.ts","../src/HocuspocusProviderWebsocketComponent.tsx","../src/HocuspocusRoom.tsx","../src/hooks/useHocuspocusProvider.ts","../src/hooks/useHocuspocusAwareness.ts","../src/hooks/useHocuspocusConnectionStatus.ts","../src/hooks/useHocuspocusEvent.ts","../src/hooks/useHocuspocusSyncStatus.ts"],"sourcesContent":["import { createContext } from \"react\";\n\nimport type {\n\tHocuspocusContextValue,\n\tHocuspocusRoomContextValue,\n} from \"./types.ts\";\n\n/**\n * Context for the WebSocket connection shared across rooms\n */\nexport const HocuspocusContext =\n\tcreateContext<HocuspocusContextValue | null>(null);\n\n/**\n * Context for the room/document provider\n */\nexport const HocuspocusRoomContext =\n\tcreateContext<HocuspocusRoomContextValue | null>(null);\n","\"use client\";\n\nimport { HocuspocusProviderWebsocket } from \"@hocuspocus/provider\";\nimport { useEffect, useMemo, useRef } from \"react\";\n\nimport { HocuspocusContext } from \"./context.ts\";\nimport type { HocuspocusProviderWebsocketComponentProps } from \"./types.ts\";\n\n/**\n * HocuspocusProviderWebsocketComponent manages the WebSocket connection that is shared across all rooms.\n *\n * This component creates a single WebSocket connection that can be used by multiple\n * HocuspocusRoom components, preventing connection overhead when switching between documents.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom name=\"document-1\">\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusProviderWebsocketComponent({\n\tchildren,\n\turl,\n\twebsocketProvider: externalWebsocketProvider,\n}: HocuspocusProviderWebsocketComponentProps) {\n\tconst websocketRef = useRef<HocuspocusProviderWebsocket | null>(null);\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Create WebSocket provider once on mount.\n\t// Safe in StrictMode: useRef persists across double-renders, so the instance\n\t// is created only once. The deferred destruction in the effect below ensures\n\t// the second mount cancels the pending destroy before it fires.\n\tif (!websocketRef.current && !externalWebsocketProvider) {\n\t\twebsocketRef.current = new HocuspocusProviderWebsocket({\n\t\t\turl: url!,\n\t\t});\n\t}\n\n\tconst websocketProvider =\n\t\texternalWebsocketProvider ??\n\t\t(websocketRef.current as HocuspocusProviderWebsocket);\n\n\t// Cleanup on unmount with deferred destruction to handle StrictMode double-mount\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\treturn () => {\n\t\t\t// Only destroy if we created the websocket (not externally provided)\n\t\t\tif (!externalWebsocketProvider) {\n\t\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\t\tif (websocketRef.current) {\n\t\t\t\t\t\twebsocketRef.current.destroy();\n\t\t\t\t\t\twebsocketRef.current = null;\n\t\t\t\t\t}\n\t\t\t\t}, 0);\n\t\t\t}\n\t\t};\n\t}, [externalWebsocketProvider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\twebsocketProvider,\n\t\t}),\n\t\t[websocketProvider],\n\t);\n\n\treturn (\n\t\t<HocuspocusContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusContext.Provider>\n\t);\n}\n","\"use client\";\n\nimport { HocuspocusProvider } from \"@hocuspocus/provider\";\nimport { useContext, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { HocuspocusContext, HocuspocusRoomContext } from \"./context.ts\";\nimport type { HocuspocusProviderEvents, HocuspocusRoomProps } from \"./types.ts\";\n\n/**\n * Mapping from HocuspocusRoom `on*` prop names to provider event names.\n */\nconst EVENT_PROP_MAP: Record<string, keyof HocuspocusProviderEvents> = {\n\tonOpen: \"open\",\n\tonConnect: \"connect\",\n\tonClose: \"close\",\n\tonDisconnect: \"disconnect\",\n\tonStatus: \"status\",\n\tonSynced: \"synced\",\n\tonUnsyncedChanges: \"unsyncedChanges\",\n\tonMessage: \"message\",\n\tonOutgoingMessage: \"outgoingMessage\",\n\tonStateless: \"stateless\",\n\tonAuthenticated: \"authenticated\",\n\tonAuthenticationFailed: \"authenticationFailed\",\n\tonAwarenessUpdate: \"awarenessUpdate\",\n\tonAwarenessChange: \"awarenessChange\",\n\tonDestroy: \"destroy\",\n};\n\n/**\n * HocuspocusRoom manages the connection to a specific document.\n *\n * It uses the shared WebSocket from HocuspocusProviderWebsocketComponent and creates a document-specific\n * provider that connects on mount and disconnects on unmount.\n *\n * This component handles React's StrictMode gracefully by using deferred destruction,\n * preventing unnecessary reconnections during development double-mounts.\n *\n * @example\n * ```tsx\n * <HocuspocusProviderWebsocketComponent url=\"ws://localhost:1234\">\n * <HocuspocusRoom\n * name=\"document-1\"\n * onAuthenticationFailed={(data) => console.error(data.reason)}\n * >\n * <Editor />\n * </HocuspocusRoom>\n * </HocuspocusProviderWebsocketComponent>\n * ```\n */\nexport function HocuspocusRoom({\n\tchildren,\n\tname,\n\tdocument,\n\ttoken,\n\tsessionAwareness,\n\t...eventHandlers\n}: HocuspocusRoomProps) {\n\tconst hocuspocusContext = useContext(HocuspocusContext);\n\n\tif (!hocuspocusContext) {\n\t\tthrow new Error(\n\t\t\t\"HocuspocusRoom must be used within a HocuspocusProviderWebsocketComponent\",\n\t\t);\n\t}\n\n\tconst { websocketProvider } = hocuspocusContext;\n\n\tconst [provider, setProvider] = useState(\n\t\t() =>\n\t\t\tnew HocuspocusProvider({\n\t\t\t\tname,\n\t\t\t\twebsocketProvider,\n\t\t\t\tdocument,\n\t\t\t\ttoken,\n\t\t\t\tsessionAwareness,\n\t\t\t}),\n\t);\n\n\tconst destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\t// Recreate provider when name, document, or token changes.\n\t// Only compare `document`/`token` when the caller actually provided them —\n\t// otherwise the provider's constructor-initialized defaults (auto-created\n\t// Y.Doc, null token) will never match the undefined prop, causing a destroy\n\t// on every render (and in StrictMode, a stray CloseMessage for the current\n\t// doc once the provider is already attached).\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: provider.configuration holds the previous values we compare against — not a reactive dependency\n\tuseEffect(() => {\n\t\tconst shouldRecreate =\n\t\t\tprovider.configuration.name !== name ||\n\t\t\t(document !== undefined &&\n\t\t\t\tprovider.configuration.document !== document) ||\n\t\t\t(token !== undefined && provider.configuration.token !== token) ||\n\t\t\tprovider.configuration.websocketProvider !== websocketProvider;\n\n\t\tif (shouldRecreate) {\n\t\t\tprovider.destroy();\n\t\t\tsetProvider(\n\t\t\t\tnew HocuspocusProvider({\n\t\t\t\t\tname,\n\t\t\t\t\twebsocketProvider,\n\t\t\t\t\tdocument,\n\t\t\t\t\ttoken,\n\t\t\t\t\tsessionAwareness,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\t// eslint-disable-next-line react-hooks/exhaustive-deps\n\t}, [name, document, token, websocketProvider]);\n\n\t// Attach/detach lifecycle with deferred destruction for StrictMode\n\tuseEffect(() => {\n\t\tif (destroyTimeoutRef.current) {\n\t\t\tclearTimeout(destroyTimeoutRef.current);\n\t\t\tdestroyTimeoutRef.current = null;\n\t\t}\n\n\t\tprovider.attach();\n\n\t\treturn () => {\n\t\t\tdestroyTimeoutRef.current = setTimeout(() => {\n\t\t\t\tprovider.destroy();\n\t\t\t}, 0);\n\t\t};\n\t}, [provider]);\n\n\t// Wire up on* event handler props with stable refs\n\tconst handlersRef = useRef(eventHandlers);\n\thandlersRef.current = eventHandlers;\n\n\tuseEffect(() => {\n\t\tconst cleanups: (() => void)[] = [];\n\n\t\tfor (const [propName, eventName] of Object.entries(EVENT_PROP_MAP)) {\n\t\t\tconst listener = (...args: unknown[]) => {\n\t\t\t\tconst handler = handlersRef.current[\n\t\t\t\t\tpropName as keyof typeof handlersRef.current\n\t\t\t\t] as ((...a: unknown[]) => void) | undefined;\n\t\t\t\thandler?.(...args);\n\t\t\t};\n\t\t\tprovider.on(eventName, listener);\n\t\t\tcleanups.push(() => provider.off(eventName, listener));\n\t\t}\n\n\t\treturn () => {\n\t\t\tfor (const cleanup of cleanups) {\n\t\t\t\tcleanup();\n\t\t\t}\n\t\t};\n\t}, [provider]);\n\n\tconst contextValue = useMemo(\n\t\t() => ({\n\t\t\tprovider,\n\t\t}),\n\t\t[provider],\n\t);\n\n\treturn (\n\t\t<HocuspocusRoomContext.Provider value={contextValue}>\n\t\t\t{children}\n\t\t</HocuspocusRoomContext.Provider>\n\t);\n}\n","import { useContext } from \"react\";\n\nimport { HocuspocusRoomContext } from \"../context.ts\";\n\n/**\n * Access the HocuspocusProvider instance for the current room.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @returns The HocuspocusProvider instance\n * @throws Error if used outside of HocuspocusRoom\n *\n * @example\n * ```tsx\n * function Editor() {\n * const provider = useHocuspocusProvider()\n *\n * const editor = useEditor({\n * extensions: [\n * Collaboration.configure({ document: provider.document }),\n * CollaborationCursor.configure({ provider }),\n * ],\n * })\n *\n * return <EditorContent editor={editor} />\n * }\n * ```\n */\nexport function useHocuspocusProvider() {\n\tconst context = useContext(HocuspocusRoomContext);\n\n\tif (!context) {\n\t\tthrow new Error(\"useHocuspocusProvider must be used within a HocuspocusRoom\");\n\t}\n\n\treturn context.provider;\n}\n","import { useCallback, useEffect, useRef, useSyncExternalStore } from \"react\";\n\nimport type { CollabUser } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the list of connected users in the document.\n *\n * This hook uses the Yjs awareness protocol to track users currently\n * connected to the document.\n *\n * @returns Array of user objects with their awareness state\n *\n * @example\n * ```tsx\n * function UserList() {\n * const users = useHocuspocusAwareness()\n *\n * return (\n * <div className=\"avatars\">\n * {users.map(user => (\n * <div\n * key={user.clientId}\n * style={{ backgroundColor: user.color }}\n * title={user.name}\n * >\n * {user.name?.[0]}\n * </div>\n * ))}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusAwareness(): CollabUser[] {\n\tconst provider = useHocuspocusProvider();\n\n\tconst versionRef = useRef(0);\n\tconst cacheRef = useRef<{ users: CollabUser[]; version: number }>({\n\t\tusers: [],\n\t\tversion: -1,\n\t});\n\n\t// Reset cache when provider changes so we don't serve stale users\n\t// from a previous provider instance.\n\tuseEffect(() => {\n\t\tversionRef.current++;\n\t\tcacheRef.current = { users: [], version: -1 };\n\t}, [provider]);\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tconst onChange = () => {\n\t\t\t\tversionRef.current++;\n\t\t\t\tonStoreChange();\n\t\t\t};\n\t\t\tprovider.awareness?.on(\"change\", onChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.awareness?.off(\"change\", onChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(() => {\n\t\tconst awareness = provider.awareness;\n\t\tif (!awareness) {\n\t\t\treturn [];\n\t\t}\n\n\t\t// Return cached value if awareness hasn't changed since last snapshot\n\t\tif (cacheRef.current.version === versionRef.current) {\n\t\t\treturn cacheRef.current.users;\n\t\t}\n\n\t\tconst users: CollabUser[] = [];\n\t\tawareness.getStates().forEach((state, clientId) => {\n\t\t\tusers.push({\n\t\t\t\tclientId,\n\t\t\t\t...state,\n\t\t\t});\n\t\t});\n\n\t\tcacheRef.current = { users, version: versionRef.current };\n\t\treturn users;\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { ConnectionStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the connection status of the collaboration provider.\n *\n * This hook uses React's useSyncExternalStore for optimal integration with\n * concurrent rendering features.\n *\n * @returns The current connection status: 'connecting', 'connected', or 'disconnected'\n *\n * @example\n * ```tsx\n * function ConnectionIndicator() {\n * const status = useHocuspocusConnectionStatus()\n *\n * return (\n * <div className={`status-${status}`}>\n * {status === 'connected' ? 'Online' : status === 'connecting' ? 'Connecting...' : 'Offline'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusConnectionStatus(): ConnectionStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"status\", onStoreChange);\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"status\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback(\n\t\t(): ConnectionStatus =>\n\t\t\tprovider.configuration.websocketProvider.status as ConnectionStatus,\n\t\t[provider],\n\t);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","import { useEffect, useRef } from \"react\";\n\nimport type { HocuspocusProviderEvents } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to events from the HocuspocusProvider for the current room.\n *\n * The handler is stored in a ref so the subscription stays stable even if\n * the handler identity changes between renders.\n *\n * Must be used within a HocuspocusRoom component.\n *\n * @param event - The event name to subscribe to\n * @param handler - Callback invoked when the event fires\n *\n * @example\n * ```tsx\n * function AuthGuard() {\n * useHocuspocusEvent('authenticationFailed', (data) => {\n * console.error('Auth failed:', data.reason)\n * redirectToLogin()\n * })\n *\n * useHocuspocusEvent('close', (data) => {\n * console.log('Connection closed', data.event)\n * })\n *\n * return null\n * }\n * ```\n */\nexport function useHocuspocusEvent<E extends keyof HocuspocusProviderEvents>(\n\tevent: E,\n\thandler: HocuspocusProviderEvents[E] extends undefined\n\t\t? () => void\n\t\t: (data: HocuspocusProviderEvents[E]) => void,\n): void {\n\tconst provider = useHocuspocusProvider();\n\tconst handlerRef = useRef(handler);\n\thandlerRef.current = handler;\n\n\tuseEffect(() => {\n\t\tconst listener = (...args: unknown[]) => {\n\t\t\t(handlerRef.current as (...a: unknown[]) => void)(...args);\n\t\t};\n\t\tprovider.on(event, listener);\n\t\treturn () => {\n\t\t\tprovider.off(event, listener);\n\t\t};\n\t}, [provider, event]);\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\nimport type { SyncStatus } from \"../types.ts\";\nimport { useHocuspocusProvider } from \"./useHocuspocusProvider.ts\";\n\n/**\n * Subscribe to the sync status of local changes.\n *\n * This hook indicates whether local changes have been synced with the server.\n *\n * @returns The current sync status: 'synced' or 'syncing'\n *\n * @example\n * ```tsx\n * function SaveIndicator() {\n * const syncStatus = useHocuspocusSyncStatus()\n *\n * return (\n * <div>\n * {syncStatus === 'syncing' ? 'Saving...' : 'All changes saved'}\n * </div>\n * )\n * }\n * ```\n */\nexport function useHocuspocusSyncStatus(): SyncStatus {\n\tconst provider = useHocuspocusProvider();\n\n\tconst subscribe = useCallback(\n\t\t(onStoreChange: () => void) => {\n\t\t\tprovider.on(\"synced\", onStoreChange);\n\t\t\tprovider.on(\"unsyncedChanges\", onStoreChange);\n\n\t\t\treturn () => {\n\t\t\t\tprovider.off(\"synced\", onStoreChange);\n\t\t\t\tprovider.off(\"unsyncedChanges\", onStoreChange);\n\t\t\t};\n\t\t},\n\t\t[provider],\n\t);\n\n\tconst getSnapshot = useCallback((): SyncStatus => {\n\t\t// Check if there are unsynced changes\n\t\tif (provider.unsyncedChanges > 0) {\n\t\t\treturn \"syncing\";\n\t\t}\n\t\treturn \"synced\";\n\t}, [provider]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n"],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -64,6 +64,17 @@ interface HocuspocusRoomProps {
64
64
  * JWT token or function that returns a promise resolving to a token
65
65
  */
66
66
  token?: string | (() => Promise<string>) | (() => string);
67
+ /**
68
+ * Enable session-aware multiplexing. When true, the provider embeds a unique
69
+ * sessionId in the documentName field of every message, allowing multiple
70
+ * providers with the same document name on a single WebSocket connection.
71
+ *
72
+ * Only set this to `true` when connecting to a v4 server that does
73
+ * support session awareness.
74
+ *
75
+ * Default: false
76
+ */
77
+ sessionAwareness?: boolean;
67
78
  onOpen?: (data: onOpenParameters) => void;
68
79
  onConnect?: () => void;
69
80
  onClose?: (data: onCloseParameters) => void;
@@ -167,6 +178,7 @@ declare function HocuspocusRoom({
167
178
  name,
168
179
  document,
169
180
  token,
181
+ sessionAwareness,
170
182
  ...eventHandlers
171
183
  }: HocuspocusRoomProps): react.JSX.Element;
172
184
  //#endregion
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hocuspocus/provider-react",
3
- "version": "4.0.0",
3
+ "version": "4.1.1",
4
4
  "description": "React bindings for Hocuspocus provider",
5
5
  "homepage": "https://hocuspocus.dev",
6
6
  "keywords": [
@@ -30,7 +30,7 @@
30
30
  "dist"
31
31
  ],
32
32
  "peerDependencies": {
33
- "@hocuspocus/provider": "^4.0.0",
33
+ "@hocuspocus/provider": "^4.1.1",
34
34
  "react": "^18.0.0 || ^19.0.0",
35
35
  "yjs": "^13.6.8"
36
36
  },
@@ -44,5 +44,5 @@
44
44
  "publishConfig": {
45
45
  "access": "public"
46
46
  },
47
- "gitHead": "1c1b34800f702a06e1ce236e8a175c82876bff42"
47
+ "gitHead": "a07826a1e654edfb89f340fad6fb9492d1c256aa"
48
48
  }
@@ -53,6 +53,7 @@ export function HocuspocusRoom({
53
53
  name,
54
54
  document,
55
55
  token,
56
+ sessionAwareness,
56
57
  ...eventHandlers
57
58
  }: HocuspocusRoomProps) {
58
59
  const hocuspocusContext = useContext(HocuspocusContext);
@@ -72,6 +73,7 @@ export function HocuspocusRoom({
72
73
  websocketProvider,
73
74
  document,
74
75
  token,
76
+ sessionAwareness,
75
77
  }),
76
78
  );
77
79
 
@@ -100,6 +102,7 @@ export function HocuspocusRoom({
100
102
  websocketProvider,
101
103
  document,
102
104
  token,
105
+ sessionAwareness,
103
106
  }),
104
107
  );
105
108
  }
package/src/types.ts CHANGED
@@ -82,6 +82,17 @@ export interface HocuspocusRoomProps {
82
82
  * JWT token or function that returns a promise resolving to a token
83
83
  */
84
84
  token?: string | (() => Promise<string>) | (() => string);
85
+ /**
86
+ * Enable session-aware multiplexing. When true, the provider embeds a unique
87
+ * sessionId in the documentName field of every message, allowing multiple
88
+ * providers with the same document name on a single WebSocket connection.
89
+ *
90
+ * Only set this to `true` when connecting to a v4 server that does
91
+ * support session awareness.
92
+ *
93
+ * Default: false
94
+ */
95
+ sessionAwareness?: boolean;
85
96
 
86
97
  // Event handlers — all optional, called when the provider emits the corresponding event.
87
98
  onOpen?: (data: onOpenParameters) => void;