@tldraw/sync 4.1.0-next.b6dfe9bccde9 → 4.1.0-next.cb6f90590225

package/src/useSync.ts

@@ -39,33 +39,122 @@ const MULTIPLAYER_EVENT_NAME = 'multiplayer.client'
 
 const defaultCustomMessageHandler: TLCustomMessageHandler = () => {}
 
-/** @public */
+/**
+ * A store wrapper specifically for remote collaboration that excludes local-only states.
+ * This type represents a tldraw store that is synchronized with a remote multiplayer server.
+ *
+ * Unlike the base TLStoreWithStatus, this excludes 'synced-local' and 'not-synced' states
+ * since remote stores are always either loading, connected to a server, or in an error state.
+ *
+ * @example
+ * ```tsx
+ * function MyCollaborativeApp() {
+ *   const store: RemoteTLStoreWithStatus = useSync({
+ *     uri: 'wss://myserver.com/sync/room-123',
+ *     assets: myAssetStore
+ *   })
+ *
+ *   if (store.status === 'loading') {
+ *     return <div>Connecting to multiplayer session...</div>
+ *   }
+ *
+ *   if (store.status === 'error') {
+ *     return <div>Connection failed: {store.error.message}</div>
+ *   }
+ *
+ *   // store.status === 'synced-remote'
+ *   return <Tldraw store={store.store} />
+ * }
+ * ```
+ *
+ * @public
+ */
 export type RemoteTLStoreWithStatus = Exclude<
 	TLStoreWithStatus,
 	{ status: 'synced-local' } | { status: 'not-synced' }
 >
 
 /**
- * useSync creates a store that is synced with a multiplayer server.
+ * Creates a reactive store synchronized with a multiplayer server for real-time collaboration.
  *
- * The store can be passed directly into the `<Tldraw />` component to enable multiplayer features.
- * It will handle loading states, and enable multiplayer UX like user cursors and following.
+ * This hook manages the complete lifecycle of a collaborative tldraw session, including
+ * WebSocket connection establishment, state synchronization, user presence, and error handling.
+ * The returned store can be passed directly to the Tldraw component to enable multiplayer features.
  *
- * To enable external blob storage, you should also pass in an `assets` object that implements the {@link tldraw#TLAssetStore} interface.
- * If you don't do this, adding large images and videos to rooms will cause performance issues at serialization boundaries.
+ * The store progresses through multiple states:
+ * - `loading`: Establishing connection and synchronizing initial state
+ * - `synced-remote`: Successfully connected and actively synchronizing changes
+ * - `error`: Connection failed or synchronization error occurred
+ *
+ * For optimal performance with media assets, provide an `assets` store that implements
+ * external blob storage. Without this, large images and videos will be stored inline
+ * as base64, causing performance issues during serialization.
+ *
+ * @param opts - Configuration options for multiplayer synchronization
+ *   - `uri` - WebSocket server URI (string or async function returning URI)
+ *   - `assets` - Asset store for blob storage (required for production use)
+ *   - `userInfo` - User information for presence system (can be reactive signal)
+ *   - `getUserPresence` - Optional function to customize presence data
+ *   - `onCustomMessageReceived` - Handler for custom socket messages
+ *   - `roomId` - Room identifier for analytics (internal use)
+ *   - `onMount` - Callback when editor mounts (internal use)
+ *   - `trackAnalyticsEvent` - Analytics event tracker (internal use)
+ *
+ * @returns A reactive store wrapper with connection status and synchronized store
  *
  * @example
  * ```tsx
- * function MyApp() {
- *     const store = useSync({
- *         uri: 'wss://myapp.com/sync/my-test-room',
- *         assets: myAssetStore
- *     })
- *     return <Tldraw store={store} />
+ * // Basic multiplayer setup
+ * function CollaborativeApp() {
+ *   const store = useSync({
+ *     uri: 'wss://myserver.com/sync/room-123',
+ *     assets: myAssetStore,
+ *     userInfo: {
+ *       id: 'user-1',
+ *       name: 'Alice',
+ *       color: '#ff0000'
+ *     }
+ *   })
+ *
+ *   if (store.status === 'loading') {
+ *     return <div>Connecting to collaboration session...</div>
+ *   }
+ *
+ *   if (store.status === 'error') {
+ *     return <div>Failed to connect: {store.error.message}</div>
+ *   }
+ *
+ *   return <Tldraw store={store.store} />
  * }
+ * ```
  *
+ * @example
+ * ```tsx
+ * // Dynamic authentication with reactive user info
+ * import { atom } from '@tldraw/state'
+ *
+ * function AuthenticatedApp() {
+ *   const currentUser = atom('user', { id: 'user-1', name: 'Alice', color: '#ff0000' })
+ *
+ *   const store = useSync({
+ *     uri: async () => {
+ *       const token = await getAuthToken()
+ *       return `wss://myserver.com/sync/room-123?token=${token}`
+ *     },
+ *     assets: authenticatedAssetStore,
+ *     userInfo: currentUser, // Reactive signal
+ *     getUserPresence: (store, user) => {
+ *       return {
+ *         userId: user.id,
+ *         userName: user.name,
+ *         cursor: getCurrentCursor(store)
+ *       }
+ *     }
+ *   })
+ *
+ *   return <Tldraw store={store.store} />
+ * }
  * ```
- * @param opts - Options for the multiplayer sync store. See {@link UseSyncOptions} and {@link tldraw#TLStoreSchemaOptions}.
  *
  * @public
  */
@@ -267,39 +356,125 @@ export function useSync(opts: UseSyncOptions & TLStoreSchemaOptions): RemoteTLSt
 }
 
 /**
- * Options for the {@link useSync} hook.
+ * Configuration options for the {@link useSync} hook to establish multiplayer collaboration.
+ *
+ * This interface defines the required and optional settings for connecting to a multiplayer
+ * server, managing user presence, handling assets, and customizing the collaboration experience.
+ *
+ * @example
+ * ```tsx
+ * const syncOptions: UseSyncOptions = {
+ *   uri: 'wss://myserver.com/sync/room-123',
+ *   assets: myAssetStore,
+ *   userInfo: {
+ *     id: 'user-1',
+ *     name: 'Alice',
+ *     color: '#ff0000'
+ *   },
+ *   getUserPresence: (store, user) => ({
+ *     userId: user.id,
+ *     userName: user.name,
+ *     cursor: getCursorPosition()
+ *   })
+ * }
+ * ```
+ *
  * @public
  */
 export interface UseSyncOptions {
 	/**
-	 * The URI of the multiplayer server. This must include the protocol,
+	 * The WebSocket URI of the multiplayer server for real-time synchronization.
 	 *
-	 *   e.g. `wss://server.example.com/my-room` or `ws://localhost:5858/my-room`.
+	 * Must include the protocol (wss:// for secure, ws:// for local development).
+	 * HTTP/HTTPS URLs will be automatically upgraded to WebSocket connections.
 	 *
-	 * Note that the protocol can also be `https` or `http` and it will upgrade to a websocket
-	 * connection.
+	 * Can be a static string or a function that returns a URI (useful for dynamic
+	 * authentication tokens or room routing). The function is called on each
+	 * connection attempt, allowing for token refresh and dynamic routing.
 	 *
-	 * Optionally, you can pass a function which will be called each time a connection is
-	 * established to get the URI. This is useful if you need to include e.g. a short-lived session
-	 * token for authentication.
+	 * Reserved query parameters `sessionId` and `storeId` are automatically added
+	 * by the sync system and should not be included in your URI.
+	 *
+	 * @example
+	 * ```ts
+	 * // Static URI
+	 * uri: 'wss://myserver.com/sync/room-123'
+	 *
+	 * // Dynamic URI with authentication
+	 * uri: async () => {
+	 *   const token = await getAuthToken()
+	 *   return `wss://myserver.com/sync/room-123?token=${token}`
+	 * }
+	 * ```
 	 */
 	uri: string | (() => string | Promise<string>)
+
 	/**
-	 * A signal that contains the user information needed for multiplayer features.
-	 * This should be synchronized with the `userPreferences` configuration for the main `<Tldraw />` component.
-	 * If not provided, a default implementation based on localStorage will be used.
+	 * User information for multiplayer presence and identification.
+	 *
+	 * Can be a static object or a reactive signal that updates when user
+	 * information changes. The presence system automatically updates when
+	 * reactive signals change, allowing real-time user profile updates.
+	 *
+	 * Should be synchronized with the `userPreferences` prop of the main
+	 * Tldraw component for consistent user experience. If not provided,
+	 * defaults to localStorage-based user preferences.
+	 *
+	 * @example
+	 * ```ts
+	 * // Static user info
+	 * userInfo: { id: 'user-123', name: 'Alice', color: '#ff0000' }
+	 *
+	 * // Reactive user info
+	 * const userSignal = atom('user', { id: 'user-123', name: 'Alice', color: '#ff0000' })
+	 * userInfo: userSignal
+	 * ```
 	 */
 	userInfo?: TLPresenceUserInfo | Signal<TLPresenceUserInfo>
+
 	/**
-	 * The asset store for blob storage. See {@link tldraw#TLAssetStore}.
+	 * Asset store implementation for handling file uploads and storage.
+	 *
+	 * Required for production applications to handle images, videos, and other
+	 * media efficiently. Without an asset store, files are stored inline as
+	 * base64, which causes performance issues with large files.
 	 *
-	 * If you don't have time to implement blob storage and just want to get started, you can use the inline base64 asset store. {@link tldraw#inlineBase64AssetStore}
-	 * Note that storing base64 blobs inline in JSON is very inefficient and will cause performance issues quickly with large images and videos.
+	 * The asset store must implement upload (for new files) and resolve
+	 * (for displaying existing files) methods. For prototyping, you can use
+	 * {@link tldraw#inlineBase64AssetStore} but this is not recommended for production.
+	 *
+	 * @example
+	 * ```ts
+	 * const myAssetStore: TLAssetStore = {
+	 *   upload: async (asset, file) => {
+	 *     const url = await uploadToCloudStorage(file)
+	 *     return { src: url }
+	 *   },
+	 *   resolve: (asset, context) => {
+	 *     return getOptimizedUrl(asset.src, context)
+	 *   }
+	 * }
+	 * ```
 	 */
 	assets: TLAssetStore
 
 	/**
-	 * A handler for custom socket messages.
+	 * Handler for receiving custom messages sent through the multiplayer connection.
+	 *
+	 * Use this to implement custom communication channels between clients beyond
+	 * the standard shape and presence synchronization. Messages are sent using
+	 * the TLSyncClient's sendMessage method.
+	 *
+	 * @param data - The custom message data received from another client
+	 *
+	 * @example
+	 * ```ts
+	 * onCustomMessageReceived: (data) => {
+	 *   if (data.type === 'chat') {
+	 *     displayChatMessage(data.message, data.userId)
+	 *   }
+	 * }
+	 * ```
 	 */
 	onCustomMessageReceived?(data: any): void
 
@@ -311,10 +486,36 @@ export interface UseSyncOptions {
 	trackAnalyticsEvent?(name: string, data: { [key: string]: any }): void
 
 	/**
-	 * A reactive function that returns a {@link @tldraw/tlschema#TLInstancePresence} object. The
-	 * result of this function will be synchronized across all clients to display presence
-	 * indicators such as cursors. See {@link @tldraw/tlschema#getDefaultUserPresence} for
+	 * A reactive function that returns a {@link @tldraw/tlschema#TLInstancePresence} object.
+	 *
+	 * This function is called reactively whenever the store state changes and
+	 * determines what presence information to broadcast to other clients. The
+	 * result is synchronized across all connected clients for displaying cursors,
+	 * selections, and other collaborative indicators.
+	 *
+	 * If not provided, uses the default implementation which includes standard
+	 * cursor position and selection state. Custom implementations allow you to
+	 * add additional presence data like current tool, view state, or custom status.
+	 *
+	 * See {@link @tldraw/tlschema#getDefaultUserPresence} for
 	 * the default implementation of this function.
+	 *
+	 * @param store - The current TLStore
+	 * @param user - The current user information
+	 * @returns Presence state to broadcast to other clients, or null to hide presence
+	 *
+	 * @example
+	 * ```ts
+	 * getUserPresence: (store, user) => {
+	 *   return {
+	 *     userId: user.id,
+	 *     userName: user.name,
+	 *     cursor: { x: 100, y: 200 },
+	 *     currentTool: 'select',
+	 *     isActive: true
+	 *   }
+	 * }
+	 * ```
 	 */
 	getUserPresence?(store: TLStore, user: TLPresenceUserInfo): TLPresenceStateInfo | null
 }

package/src/useSyncDemo.test.ts

@@ -0,0 +1,189 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Mock modules before imports
+vi.mock('./useSync')
+vi.mock('react', async () => {
+	const actual = await vi.importActual('react')
+	return {
+		...actual,
+		useMemo: vi.fn((fn, _deps) => fn()),
+		useCallback: vi.fn((fn, _deps) => fn),
+	}
+})
+vi.mock('tldraw', async () => {
+	const actual = await vi.importActual('tldraw')
+	return {
+		...actual,
+		useShallowObjectIdentity: vi.fn((obj) => obj),
+		uniqueId: vi.fn(() => 'mock-unique-id'),
+		getHashForString: vi.fn((str) => `hash-${str}`),
+	}
+})
+
+import {
+	TLAsset,
+	defaultBindingUtils,
+	defaultShapeUtils,
+	getHashForString,
+	uniqueId,
+	useShallowObjectIdentity,
+} from 'tldraw'
+import { useSync } from './useSync'
+import { useSyncDemo } from './useSyncDemo'
+
+// Mock fetch globally
+const mockFetch = vi.fn() as any
+global.fetch = mockFetch
+
+// Mock console.error and alert to avoid noise in tests
+const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+const alertSpy = vi.spyOn(window, 'alert').mockImplementation(() => {})
+
+describe('useSyncDemo', () => {
+	beforeEach(() => {
+		vi.clearAllMocks()
+		consoleSpy.mockClear()
+		alertSpy.mockClear()
+		vi.mocked(useSync).mockReturnValue({ status: 'loading' } as any)
+		vi.mocked(useShallowObjectIdentity).mockImplementation((obj) => obj)
+		vi.mocked(uniqueId).mockReturnValue('mock-unique-id')
+		vi.mocked(getHashForString).mockImplementation((str) => `hash-${str}`)
+	})
+
+	describe('core functionality', () => {
+		it('should construct correct URI with room ID encoding', () => {
+			const roomIdWithSpecialChars = 'room with spaces & symbols!'
+			useSyncDemo({ roomId: roomIdWithSpecialChars })
+
+			const useSyncCall = vi.mocked(useSync).mock.calls[0][0]
+			expect(useSyncCall.uri).toContain(encodeURIComponent(roomIdWithSpecialChars))
+			expect(useSyncCall.roomId).toBe(roomIdWithSpecialChars)
+		})
+
+		it('should use custom host when provided', () => {
+			const customHost = 'https://custom.server.com'
+			useSyncDemo({ roomId: 'test-room', host: customHost })
+
+			const useSyncCall = vi.mocked(useSync).mock.calls[0][0]
+			expect(useSyncCall.uri).toBe(`${customHost}/connect/test-room`)
+		})
+
+		it('should merge custom shape utils with defaults', () => {
+			const customShapeUtils = [{ type: 'custom-shape' } as any]
+			useSyncDemo({ roomId: 'test-room', shapeUtils: customShapeUtils } as any)
+
+			const useSyncCall = vi.mocked(useSync).mock.calls[0][0]
+			expect((useSyncCall as any).shapeUtils).toEqual([...defaultShapeUtils, ...customShapeUtils])
+		})
+
+		it('should merge custom binding utils with defaults', () => {
+			const customBindingUtils = [{ type: 'custom-binding' } as any]
+			useSyncDemo({ roomId: 'test-room', bindingUtils: customBindingUtils } as any)
+
+			const useSyncCall = vi.mocked(useSync).mock.calls[0][0]
+			expect((useSyncCall as any).bindingUtils).toEqual([
+				...defaultBindingUtils,
+				...customBindingUtils,
+			])
+		})
+	})
+
+	describe('asset upload restrictions', () => {
+		it('should block uploads for tldraw domains', async () => {
+			useSyncDemo({ roomId: 'test-room', host: 'https://demo.tldraw.xyz' })
+
+			const useSyncCall = vi.mocked(useSync).mock.calls[0][0]
+			const assetStore = useSyncCall.assets
+			const file = new File(['test content'], 'test-file.jpg')
+
+			await expect(assetStore.upload({} as TLAsset, file)).rejects.toThrow(
+				'Uploading images is disabled in this demo.'
+			)
+			expect(alertSpy).toHaveBeenCalledWith('Uploading images is disabled in this demo.')
+		})
+
+		it('should allow uploads for non-tldraw domains', async () => {
+			useSyncDemo({ roomId: 'test-room', host: 'https://demo.server.com' })
+
+			const useSyncCall = vi.mocked(useSync).mock.calls[0][0]
+			const assetStore = useSyncCall.assets
+			const file = new File(['test content'], 'test-file.jpg')
+
+			vi.mocked(mockFetch).mockResolvedValueOnce(new Response())
+			vi.mocked(uniqueId).mockReturnValueOnce('unique-123')
+
+			const result = await assetStore.upload({} as TLAsset, file)
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				'https://demo.server.com/uploads/unique-123-test-file-jpg',
+				expect.objectContaining({ method: 'POST', body: file })
+			)
+			expect(result).toEqual({ src: 'https://demo.server.com/uploads/unique-123-test-file-jpg' })
+		})
+	})
+
+	describe('bookmark asset creation', () => {
+		it('should create bookmark assets with metadata when successful', async () => {
+			const mockEditor = { registerExternalAssetHandler: vi.fn() } as any
+			useSyncDemo({ roomId: 'test-room', host: 'https://demo.server.com' })
+
+			const useSyncCall = vi.mocked(useSync).mock.calls[0][0]
+			useSyncCall.onMount!(mockEditor)
+
+			const handlerFunction = mockEditor.registerExternalAssetHandler.mock.calls[0][1]
+			const testUrl = 'https://example.com'
+			const mockMeta = { title: 'Example', description: 'Test' }
+
+			vi.mocked(mockFetch).mockResolvedValueOnce({
+				json: () => Promise.resolve(mockMeta),
+			} as Response)
+			vi.mocked(getHashForString).mockReturnValueOnce('url-hash-123')
+
+			const result = await handlerFunction({ url: testUrl })
+
+			expect(result.type).toBe('bookmark')
+			expect(result.props.src).toBe(testUrl)
+			expect(result.props.title).toBe('Example')
+		})
+
+		it('should handle bookmark creation errors gracefully', async () => {
+			const mockEditor = { registerExternalAssetHandler: vi.fn() } as any
+			useSyncDemo({ roomId: 'test-room' })
+
+			const useSyncCall = vi.mocked(useSync).mock.calls[0][0]
+			useSyncCall.onMount!(mockEditor)
+
+			const handlerFunction = mockEditor.registerExternalAssetHandler.mock.calls[0][1]
+			const testUrl = 'https://example.com'
+
+			vi.mocked(mockFetch).mockRejectedValueOnce(new Error('Network error'))
+			vi.mocked(getHashForString).mockReturnValueOnce('url-hash-123')
+
+			const result = await handlerFunction({ url: testUrl })
+
+			expect(consoleSpy).toHaveBeenCalledWith(expect.any(Error))
+			expect(result.props.title).toBe('')
+			expect(result.props.description).toBe('')
+		})
+	})
+
+	describe('file name sanitization', () => {
+		it('should sanitize file names in upload URLs', async () => {
+			useSyncDemo({ roomId: 'test-room', host: 'https://demo.server.com' })
+
+			const useSyncCall = vi.mocked(useSync).mock.calls[0][0]
+			const assetStore = useSyncCall.assets
+			const file = new File(['test'], 'file with spaces & symbols!.jpg')
+
+			vi.mocked(mockFetch).mockResolvedValueOnce(new Response())
+			vi.mocked(uniqueId).mockReturnValueOnce('unique-123')
+
+			await assetStore.upload({} as TLAsset, file)
+
+			expect(mockFetch).toHaveBeenCalledWith(
+				'https://demo.server.com/uploads/unique-123-file-with-spaces---symbols--jpg',
+				expect.any(Object)
+			)
+		})
+	})
+})

package/src/useSyncDemo.ts

@@ -44,12 +44,19 @@ export interface UseSyncDemoOptions {
 }
 
 /**
- * Depending on the environment this package is used in, process.env may not be available. Wrap
- * `process.env` accesses in this to make sure they don't fail.
+ * Safely accesses environment variables across different bundling environments.
+ *
+ * Depending on the environment this package is used in, process.env may not be available. This function
+ * wraps `process.env` accesses in a try/catch to prevent runtime errors in environments where process
+ * is not defined.
  *
  * The reason that this is just a try/catch and not a dynamic check e.g. `process &&
  * process.env[key]` is that many bundlers implement `process.env.WHATEVER` using compile-time
  * string replacement, rather than actually creating a runtime implementation of a `process` object.
+ *
+ * @param cb - Callback function that accesses an environment variable
+ * @returns The environment variable value if available, otherwise undefined
+ * @internal
  */
 function getEnv(cb: () => string | undefined): string | undefined {
 	try {
@@ -124,6 +131,16 @@ export function useSyncDemo(
 	})
 }
 
+/**
+ * Determines whether file uploads should be disabled for a given host.
+ *
+ * Uploads are disabled for production tldraw domains to prevent abuse of the demo server
+ * infrastructure. This includes tldraw.com and tldraw.xyz domains and their subdomains.
+ *
+ * @param host - The host URL to check for upload restrictions
+ * @returns True if uploads should be disabled, false otherwise
+ * @internal
+ */
 function shouldDisallowUploads(host: string) {
 	const disallowedHosts = ['tldraw.com', 'tldraw.xyz']
 	return disallowedHosts.some(
@@ -131,6 +148,33 @@ function shouldDisallowUploads(host: string) {
 	)
 }
 
+/**
+ * Creates an asset store implementation optimized for the tldraw demo server.
+ *
+ * This asset store handles file uploads to the demo server and provides intelligent
+ * asset resolution with automatic image optimization based on network conditions,
+ * screen density, and display size. It includes safeguards to prevent uploads to
+ * production domains and optimizes images through the tldraw image processing service.
+ *
+ * @param host - The demo server host URL for file uploads and asset resolution
+ * @returns A TLAssetStore implementation with upload and resolve capabilities
+ * @example
+ * ```ts
+ * const assetStore = createDemoAssetStore('https://demo.tldraw.xyz')
+ *
+ * // Upload a file
+ * const result = await assetStore.upload(asset, file)
+ * console.log('Uploaded to:', result.src)
+ *
+ * // Resolve optimized asset URL
+ * const optimizedUrl = assetStore.resolve(imageAsset, {
+ *   steppedScreenScale: 1.5,
+ *   dpr: 2,
+ *   networkEffectiveType: '4g'
+ * })
+ * ```
+ * @internal
+ */
 function createDemoAssetStore(host: string): TLAssetStore {
 	return {
 		upload: async (_asset, file) => {
@@ -211,6 +255,28 @@ function createDemoAssetStore(host: string): TLAssetStore {
 	}
 }
 
+/**
+ * Creates a bookmark asset by fetching metadata from a URL using the demo server.
+ *
+ * This function uses the demo server's bookmark unfurling service to extract metadata
+ * like title, description, favicon, and preview image from a given URL. If the metadata
+ * fetch fails, it returns a blank bookmark asset with just the URL.
+ *
+ * @param host - The demo server host URL to use for bookmark unfurling
+ * @param url - The URL to create a bookmark asset from
+ * @returns A promise that resolves to a TLAsset of type 'bookmark' with extracted metadata
+ * @example
+ * ```ts
+ * const asset = await createAssetFromUrlUsingDemoServer(
+ *   'https://demo.tldraw.xyz',
+ *   'https://example.com'
+ * )
+ *
+ * console.log(asset.props.title) // "Example Domain"
+ * console.log(asset.props.description) // "This domain is for use in illustrative examples..."
+ * ```
+ * @internal
+ */
 async function createAssetFromUrlUsingDemoServer(host: string, url: string): Promise<TLAsset> {
 	const urlHash = getHashForString(url)
 	try {