@tldraw/sync-core 4.4.0-next.84d68f44c848 → 4.4.0-next.bde73a32273d

package/src/lib/TLSyncClient.test.ts

@@ -836,4 +836,595 @@ describe('TLSyncClient', () => {
 			// Should track the latest server clock internally
 		})
 	})
+
+	describe('Offline and Reconnection Behavior', () => {
+		beforeEach(() => {
+			client = createClient()
+			socket.mockServerMessage(createConnectMessage())
+			socket.clearSentMessages()
+		})
+
+		it('does not send changes made while offline', () => {
+			// Go offline
+			socket.mockConnectionStatus('offline')
+			socket.clearSentMessages()
+
+			// Make changes while offline
+			const pageId = PageRecordType.createId()
+			store.put([
+				PageRecordType.create({
+					id: pageId,
+					name: 'Offline Page',
+					index: 'a1' as any,
+				}),
+			])
+
+			vi.advanceTimersByTime(100)
+
+			// Should not have sent any messages
+			expect(socket.getSentMessages()).toHaveLength(0)
+
+			// But the page should exist locally
+			expect(store.has(pageId)).toBe(true)
+		})
+
+		it('re-applies offline changes after reconnection and pushes them to server', () => {
+			// Make a change while offline - this is a truly speculative change
+			socket.mockConnectionStatus('offline')
+			socket.clearSentMessages()
+
+			const pageId = PageRecordType.createId()
+			store.put([
+				PageRecordType.create({
+					id: pageId,
+					name: 'Offline Page',
+					index: 'a1' as any,
+				}),
+			])
+			vi.advanceTimersByTime(100)
+
+			// Page exists locally, no messages sent (offline)
+			expect(store.has(pageId)).toBe(true)
+			expect(socket.getSentMessages()).toHaveLength(0)
+
+			// Come back online
+			socket.mockConnectionStatus('online')
+
+			// Get the connect message
+			const connectMsg = socket.getSentMessages().find((m) => m.type === 'connect')
+			expect(connectMsg).toBeDefined()
+
+			// Clear messages before server response
+			socket.clearSentMessages()
+
+			// Server responds with wipe_all (simulating fresh sync)
+			socket.mockServerMessage(
+				createConnectMessage({
+					connectRequestId: (connectMsg as any).connectRequestId,
+					hydrationType: 'wipe_all',
+					diff: {}, // Server has no pages
+				})
+			)
+			vi.advanceTimersByTime(100)
+
+			// The page should still exist locally
+			expect(store.has(pageId)).toBe(true)
+			expect(store.get(pageId)?.name).toBe('Offline Page')
+
+			// The speculative change should have been pushed to the server
+			const messages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			const pushWithPage = messages.find(
+				(msg) => msg.type === 'push' && msg.diff && msg.diff[pageId]
+			)
+			expect(pushWithPage).toBeDefined()
+			expect(pushWithPage!.diff![pageId][0]).toBe(RecordOpType.Put)
+			expect((pushWithPage!.diff![pageId][1] as any).name).toBe('Offline Page')
+		})
+	})
+
+	describe('Push Coalescing (Multiple push() calls → single network message)', () => {
+		/**
+		 * These tests verify that multiple store changes (each triggering push())
+		 * get coalesced into a single TLPushRequest when the throttle fires.
+		 *
+		 * We enable RAF mode so the throttle actually delays execution,
+		 * allowing changes to accumulate before sending.
+		 */
+
+		let rafCallbacks: Array<FrameRequestCallback>
+		let rafId: number
+
+		function flushOneRaf() {
+			if (rafCallbacks.length > 0) {
+				const callbacks = rafCallbacks.splice(0, rafCallbacks.length)
+				const now = performance.now()
+				for (const callback of callbacks) {
+					callback(now)
+				}
+			}
+		}
+
+		function flushThrottle() {
+			// FpsScheduler needs: advance time + flush RAF (potentially twice for tick + flush)
+			// Also need to clear any stale callbacks and keep flushing until stable
+			for (let i = 0; i < 10 && rafCallbacks.length > 0; i++) {
+				vi.advanceTimersByTime(100)
+				flushOneRaf()
+			}
+		}
+
+		beforeEach(() => {
+			// Reset timer to a known state to avoid pollution from previous tests
+			vi.setSystemTime(0)
+
+			// Force RAF behavior so throttle actually delays
+			// @ts-expect-error - testing flag
+			globalThis.__FORCE_RAF_IN_TESTS__ = true
+
+			rafCallbacks = []
+			rafId = 0
+
+			vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+				const id = ++rafId
+				rafCallbacks.push(callback)
+				return id
+			})
+
+			vi.stubGlobal('cancelAnimationFrame', (_id: number) => {})
+
+			// Create client with RAF mode enabled
+			client = createClient()
+			socket.mockServerMessage(createConnectMessage())
+
+			// Flush initial setup and clear
+			flushThrottle()
+			socket.clearSentMessages()
+		})
+
+		afterEach(() => {
+			// @ts-expect-error - testing flag
+			delete globalThis.__FORCE_RAF_IN_TESTS__
+			vi.unstubAllGlobals()
+		})
+
+		it('coalesces 5 store.put() calls into 1 push request', () => {
+			expect((client as any).isConnectedToRoom).toBe(true)
+
+			// Make 5 separate store changes synchronously
+			const pageIds: string[] = []
+			for (let i = 0; i < 5; i++) {
+				const pageId = PageRecordType.createId()
+				pageIds.push(pageId)
+				store.put([
+					PageRecordType.create({
+						id: pageId,
+						name: `Page ${i}`,
+						index: `a${i}` as any,
+					}),
+				])
+			}
+
+			// Before throttle fires: no messages should be sent yet
+			expect(socket.getSentMessages()).toHaveLength(0)
+
+			// Flush the throttle
+			flushThrottle()
+
+			// Should have sent exactly ONE push request containing all 5 pages
+			const messages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			expect(messages).toHaveLength(1)
+			expect(messages[0].type).toBe('push')
+
+			// The single message should contain all 5 page IDs
+			const diff = messages[0].diff || {}
+			expect(Object.keys(diff)).toHaveLength(5)
+			for (const pageId of pageIds) {
+				expect(diff[pageId]).toBeDefined()
+			}
+		})
+
+		it('coalesces create + multiple updates into 1 push with final state', () => {
+			expect((client as any).isConnectedToRoom).toBe(true)
+
+			const pageId = PageRecordType.createId()
+
+			// Create and update the same record multiple times synchronously
+			store.put([
+				PageRecordType.create({
+					id: pageId,
+					name: 'Version 1',
+					index: 'a1' as any,
+				}),
+			])
+			store.update(pageId, (p) => ({ ...p, name: 'Version 2' }))
+			store.update(pageId, (p) => ({ ...p, name: 'Version 3' }))
+			store.update(pageId, (p) => ({ ...p, name: 'Final Version' }))
+
+			// Before throttle fires: no messages
+			expect(socket.getSentMessages()).toHaveLength(0)
+
+			// Flush the throttle
+			flushThrottle()
+
+			// Should have exactly ONE push request
+			const messages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			expect(messages).toHaveLength(1)
+
+			// The diff should have the final state
+			const diff = messages[0].diff!
+			expect(diff[pageId]).toBeDefined()
+			expect(diff[pageId][0]).toBe(RecordOpType.Put)
+			expect((diff[pageId][1] as any).name).toBe('Final Version')
+		})
+
+		it('coalesces create + delete into no diff (cancels out)', () => {
+			const pageId = PageRecordType.createId()
+
+			// Create then immediately delete
+			store.put([
+				PageRecordType.create({
+					id: pageId,
+					name: 'Ephemeral',
+					index: 'a1' as any,
+				}),
+			])
+			store.remove([pageId])
+
+			// Before throttle fires: no messages
+			expect(socket.getSentMessages()).toHaveLength(0)
+
+			// Flush the throttle
+			flushThrottle()
+
+			// Either no message, or message with empty/no diff for this page
+			const messages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			if (messages.length > 0) {
+				const diff = messages[0].diff || {}
+				// The page should NOT be in the diff (add + remove = no-op)
+				expect(diff[pageId]).toBeUndefined()
+			}
+		})
+
+		it('coalesces multiple presence updates into 1 push with final presence (first is Put)', () => {
+			// Multiple presence updates synchronously - first presence ever sent
+			presence.set({
+				id: 'presence:u1' as any,
+				typeName: 'instance_presence',
+				cursor: { x: 0, y: 0 },
+			} as any)
+			presence.set({
+				id: 'presence:u1' as any,
+				typeName: 'instance_presence',
+				cursor: { x: 50, y: 50 },
+			} as any)
+			presence.set({
+				id: 'presence:u1' as any,
+				typeName: 'instance_presence',
+				cursor: { x: 100, y: 100 },
+			} as any)
+
+			// Before throttle fires: no messages
+			expect(socket.getSentMessages()).toHaveLength(0)
+
+			// Flush the throttle
+			flushThrottle()
+
+			// Should have exactly ONE push with final presence
+			const messages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			expect(messages).toHaveLength(1)
+			expect(messages[0].presence).toBeDefined()
+			// First presence is always a Put (full record)
+			expect(messages[0].presence![0]).toBe(RecordOpType.Put)
+			expect((messages[0].presence![1] as any).cursor).toEqual({ x: 100, y: 100 })
+		})
+
+		it('sends subsequent presence updates as Patch after initial Put', () => {
+			// Send initial presence
+			presence.set({
+				id: 'presence:u1' as any,
+				typeName: 'instance_presence',
+				cursor: { x: 0, y: 0 },
+			} as any)
+			flushThrottle()
+
+			// Verify first presence was a Put
+			const firstMessages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			expect(firstMessages).toHaveLength(1)
+			expect(firstMessages[0].presence![0]).toBe(RecordOpType.Put)
+
+			socket.clearSentMessages()
+
+			// Now send multiple presence updates
+			presence.set({
+				id: 'presence:u1' as any,
+				typeName: 'instance_presence',
+				cursor: { x: 50, y: 50 },
+			} as any)
+			presence.set({
+				id: 'presence:u1' as any,
+				typeName: 'instance_presence',
+				cursor: { x: 100, y: 100 },
+			} as any)
+
+			// Before throttle fires: no messages
+			expect(socket.getSentMessages()).toHaveLength(0)
+
+			// Flush the throttle
+			flushThrottle()
+
+			// Should have exactly ONE push with final presence as a Patch
+			const messages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			expect(messages).toHaveLength(1)
+			expect(messages[0].presence).toBeDefined()
+			// Subsequent presence updates should be Patches (only changed fields)
+			expect(messages[0].presence![0]).toBe(RecordOpType.Patch)
+			// The patch should contain the cursor update
+			expect((messages[0].presence![1] as any).cursor).toBeDefined()
+		})
+
+		it('coalesces document changes + presence into 1 push request', () => {
+			const pageId = PageRecordType.createId()
+
+			// Document change
+			store.put([
+				PageRecordType.create({
+					id: pageId,
+					name: 'Test Page',
+					index: 'a1' as any,
+				}),
+			])
+
+			// Presence change
+			presence.set({
+				id: 'presence:u1' as any,
+				typeName: 'instance_presence',
+				cursor: { x: 42, y: 42 },
+			} as any)
+
+			// Before throttle fires: no messages
+			expect(socket.getSentMessages()).toHaveLength(0)
+
+			// Flush the throttle
+			flushThrottle()
+
+			// Should have exactly ONE push with both document and presence
+			const messages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			expect(messages).toHaveLength(1)
+
+			// Has document diff
+			expect(messages[0].diff).toBeDefined()
+			expect(messages[0].diff![pageId]).toBeDefined()
+
+			// Has presence
+			expect(messages[0].presence).toBeDefined()
+		})
+	})
+
+	describe('Rebase Behavior', () => {
+		beforeEach(() => {
+			client = createClient()
+			socket.mockServerMessage(createConnectMessage())
+			socket.clearSentMessages()
+		})
+
+		it('preserves local changes when receiving server patches for other records', () => {
+			// Make a local change
+			const pageId = PageRecordType.createId()
+			store.put([
+				PageRecordType.create({
+					id: pageId,
+					name: 'Local Page',
+					index: 'a1' as any,
+				}),
+			])
+			vi.advanceTimersByTime(100)
+
+			// Receive a server patch for a different record
+			const serverPageId = PageRecordType.createId()
+			socket.mockServerMessage({
+				type: 'data',
+				data: [
+					{
+						type: 'patch',
+						serverClock: 2,
+						diff: {
+							[serverPageId]: [
+								RecordOpType.Put,
+								PageRecordType.create({
+									id: serverPageId,
+									name: 'Server Page',
+									index: 'a2' as any,
+								}),
+							],
+						},
+					},
+				],
+			})
+			vi.advanceTimersByTime(100)
+
+			// Both local and server pages should coexist
+			expect(store.has(pageId)).toBe(true)
+			expect(store.get(pageId)?.name).toBe('Local Page')
+			expect(store.has(serverPageId)).toBe(true)
+			expect(store.get(serverPageId)?.name).toBe('Server Page')
+		})
+	})
+
+	describe('Solo Mode FPS Optimization', () => {
+		it('does not send presence in solo mode', () => {
+			presenceMode.set('solo')
+			client = createClient()
+			socket.mockServerMessage(createConnectMessage())
+			socket.clearSentMessages()
+
+			const presenceRecord = {
+				id: 'presence:user1' as any,
+				typeName: 'instance_presence',
+				cursor: { x: 100, y: 200 },
+			} as TestRecord
+			presence.set(presenceRecord)
+
+			vi.advanceTimersByTime(2000)
+
+			// Should not have sent any presence updates
+			const messages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			const presenceMessages = messages.filter((msg) => msg.presence)
+			expect(presenceMessages).toHaveLength(0)
+		})
+
+		it('still sends document changes in solo mode', () => {
+			presenceMode.set('solo')
+			client = createClient()
+			socket.mockServerMessage(createConnectMessage())
+			socket.clearSentMessages()
+
+			const pageId = PageRecordType.createId()
+			store.put([
+				PageRecordType.create({
+					id: pageId,
+					name: 'Solo Page',
+					index: 'a1' as any,
+				}),
+			])
+
+			vi.advanceTimersByTime(2000)
+
+			// Should have sent the document change
+			const messages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			const docMessages = messages.filter((msg) => msg.diff && Object.keys(msg.diff).length > 0)
+			expect(docMessages.length).toBeGreaterThan(0)
+		})
+	})
+
+	describe('Edge Cases', () => {
+		beforeEach(() => {
+			client = createClient()
+			socket.mockServerMessage(createConnectMessage())
+			socket.clearSentMessages()
+		})
+
+		it('handles update-then-delete of server record correctly', () => {
+			// Create a page via server
+			const pageId = PageRecordType.createId()
+			socket.mockServerMessage({
+				type: 'data',
+				data: [
+					{
+						type: 'patch',
+						serverClock: 2,
+						diff: {
+							[pageId]: [
+								RecordOpType.Put,
+								PageRecordType.create({
+									id: pageId,
+									name: 'Server Page',
+									index: 'a1' as any,
+								}),
+							],
+						},
+					},
+				],
+			})
+			vi.advanceTimersByTime(100)
+			socket.clearSentMessages()
+
+			// Update then delete
+			store.update(pageId, (p) => ({ ...p, name: 'Updated' }))
+			vi.advanceTimersByTime(100)
+			socket.clearSentMessages()
+
+			store.remove([pageId])
+			vi.advanceTimersByTime(100)
+
+			// Page should not exist locally
+			expect(store.has(pageId)).toBe(false)
+
+			// Should have sent a remove operation
+			const messages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			const removeMsg = messages.find(
+				(msg) => msg.diff && msg.diff[pageId] && msg.diff[pageId][0] === RecordOpType.Remove
+			)
+			expect(removeMsg).toBeDefined()
+		})
+
+		it('handles delete-then-recreate of server record with same ID', () => {
+			// Create a page via server
+			const pageId = PageRecordType.createId()
+			socket.mockServerMessage({
+				type: 'data',
+				data: [
+					{
+						type: 'patch',
+						serverClock: 2,
+						diff: {
+							[pageId]: [
+								RecordOpType.Put,
+								PageRecordType.create({
+									id: pageId,
+									name: 'Original',
+									index: 'a1' as any,
+								}),
+							],
+						},
+					},
+				],
+			})
+			vi.advanceTimersByTime(100)
+			socket.clearSentMessages()
+
+			// Delete then recreate with same ID
+			store.remove([pageId])
+			store.put([
+				PageRecordType.create({
+					id: pageId,
+					name: 'Recreated',
+					index: 'a1' as any,
+				}),
+			])
+			vi.advanceTimersByTime(100)
+
+			// Page should exist with new name
+			expect(store.has(pageId)).toBe(true)
+			expect(store.get(pageId)?.name).toBe('Recreated')
+		})
+
+		it('sends patches (not full puts) for updates to server records', () => {
+			// Create a page via server
+			const pageId = PageRecordType.createId()
+			socket.mockServerMessage({
+				type: 'data',
+				data: [
+					{
+						type: 'patch',
+						serverClock: 2,
+						diff: {
+							[pageId]: [
+								RecordOpType.Put,
+								PageRecordType.create({
+									id: pageId,
+									name: 'Server Name',
+									index: 'a1' as any,
+								}),
+							],
+						},
+					},
+				],
+			})
+			vi.advanceTimersByTime(100)
+			socket.clearSentMessages()
+
+			// Local user updates only the name
+			store.update(pageId, (p) => ({ ...p, name: 'Local Name' }))
+			vi.advanceTimersByTime(100)
+
+			// Should send a Patch operation (not Put)
+			const messages = socket.getSentMessages() as TLPushRequest<TestRecord>[]
+			const pushWithPage = messages.find((msg) => msg.diff && msg.diff[pageId])
+			expect(pushWithPage).toBeDefined()
+
+			const op = pushWithPage!.diff![pageId]
+			expect(op[0]).toBe(RecordOpType.Patch)
+			expect((op[1] as any).name).toBeDefined()
+		})
+	})
 })