@tldraw/editor 5.4.2 → 5.5.0-canary.0241f11f2e99

package/src/lib/utils/sync/TLLocalSyncClient.test.ts

@@ -3,6 +3,7 @@ import { IndexKey, promiseWithResolve } from '@tldraw/utils'
 import { Mock, vi } from 'vitest'
 import { createTLStore } from '../../config/createTLStore'
 import { hardReset } from './hardReset'
+import { LocalIndexedDb } from './LocalIndexedDb'
 import { TLLocalSyncClient } from './TLLocalSyncClient'
 
 class BroadcastChannelMock {
@@ -214,6 +215,73 @@ test('pagehide does not write before the initial load has completed', async () =
 	expect(client.db.storeChanges).not.toHaveBeenCalled()
 })
 
+test('diffs received while the client is still loading are applied once it has loaded', async () => {
+	const { client, channel, tick } = testClient()
+	const remotePage = PageRecordType.create({ name: 'remote', index: 'a0' as IndexKey })
+	channel.onmessage?.({
+		data: {
+			type: 'diff',
+			storeId: 'other-tab',
+			schema: client.serializedSchema,
+			changes: { added: { [remotePage.id]: remotePage }, updated: {}, removed: {} },
+		},
+	} as any)
+	expect(client.store.get(remotePage.id)).toBeUndefined()
+
+	await tick()
+	expect(client.store.get(remotePage.id)).toEqual(remotePage)
+
+	// and the first (full) db write includes them rather than overwriting them
+	client.store.put([PageRecordType.create({ name: 'local', index: 'a1' as IndexKey })])
+	await tick()
+	expect(client.db.storeSnapshot).toHaveBeenCalledTimes(1)
+	expect(client.db.storeSnapshot.mock.calls[0][0].snapshot[remotePage.id]).toEqual(remotePage)
+})
+
+test('closing the client persists changes that are still queued', async () => {
+	const { client, tick } = testClient()
+	await tick()
+	client.store.put([PageRecordType.create({ name: 'test', index: 'a0' as IndexKey })])
+	expect(client.db.storeSnapshot).not.toHaveBeenCalled()
+
+	// close before the throttled persist fires
+	client.close()
+	expect(client.db.storeSnapshot).toHaveBeenCalledTimes(1)
+})
+
+test('closing the client while a persist is in flight still persists edits queued during the write', async () => {
+	const idbOperationResult = promiseWithResolve<void>()
+	const { client, tick } = testClient()
+	client.db.storeSnapshot.mockImplementationOnce(() => idbOperationResult)
+	const closeDb = vi.spyOn(client.db, 'close')
+
+	await tick()
+	client.store.put([PageRecordType.create({ name: 'test', index: 'a0' as IndexKey })])
+	await tick()
+	expect(client.db.storeSnapshot).toHaveBeenCalledTimes(1)
+
+	// an edit made while the first write is still in flight, then unmount
+	const page = PageRecordType.create({ name: 'test2', index: 'a1' as IndexKey })
+	client.store.put([page])
+	client.close()
+	expect(client.db.storeChanges).not.toHaveBeenCalled()
+	expect(closeDb).not.toHaveBeenCalled()
+
+	idbOperationResult.resolve()
+	await tick()
+	expect(client.db.storeChanges).toHaveBeenCalledTimes(1)
+	expect(client.db.storeChanges.mock.calls[0][0].changes.added[page.id]).toEqual(page)
+	expect(closeDb).toHaveBeenCalledTimes(1)
+})
+
+test('closing the client with nothing queued does not write to the db', async () => {
+	const { client, tick } = testClient()
+	await tick()
+	client.close()
+	expect(client.db.storeSnapshot).not.toHaveBeenCalled()
+	expect(client.db.storeChanges).not.toHaveBeenCalled()
+})
+
 test('pagehide and visibilitychange listeners are removed when the client closes', async () => {
 	const removeWindowListener = vi.spyOn(window, 'removeEventListener')
 	const removeDocumentListener = vi.spyOn(document, 'removeEventListener')
@@ -228,3 +296,171 @@ test('pagehide and visibilitychange listeners are removed when the client closes
 		removeDocumentListener.mockRestore()
 	}
 })
+
+test('closing the client before it has loaded does not write to the db', async () => {
+	const { client, tick } = testClient()
+	client.close()
+	await tick()
+	expect(client.db.storeSnapshot).not.toHaveBeenCalled()
+	expect(client.db.storeChanges).not.toHaveBeenCalled()
+})
+
+test('closing flushes changes that have not reached the next animation frame', async () => {
+	const { client, tick } = testClient()
+	await tick()
+	const page = PageRecordType.create({ name: 'last frame', index: 'a0' as IndexKey })
+	vi.stubGlobal('__FORCE_RAF_IN_TESTS__', true)
+	try {
+		client.store.put([page])
+		client.close()
+		expect(client.db.storeSnapshot).toHaveBeenCalledTimes(1)
+		expect(client.db.storeSnapshot.mock.calls[0][0].snapshot[page.id]).toEqual(page)
+	} finally {
+		vi.unstubAllGlobals()
+	}
+})
+
+test('buffered schema announcements cannot persist before the remaining buffered diffs', async () => {
+	const { client, channel, tick } = testClient()
+	const page = PageRecordType.create({ name: 'remote', index: 'a0' as IndexKey })
+	const schema = client.store.schema.serialize()
+	channel.onmessage?.({
+		data: {
+			type: 'announce',
+			schema: { ...schema, sequences: { ...schema.sequences, 'com.tldraw.page': 0 } },
+		},
+	} as MessageEvent)
+	channel.onmessage?.({
+		data: {
+			type: 'diff',
+			storeId: 'other-tab',
+			schema: client.serializedSchema,
+			changes: { added: { [page.id]: page }, updated: {}, removed: {} },
+		},
+	} as MessageEvent)
+	await tick()
+	expect(client.db.storeSnapshot).toHaveBeenCalledTimes(1)
+	expect(client.db.storeSnapshot.mock.calls[0][0].snapshot[page.id]).toEqual(page)
+	client.close()
+})
+
+test('closing before load cancels a persist scheduled by an early edit', async () => {
+	const load = promiseWithResolve<Awaited<ReturnType<LocalIndexedDb['load']>>>()
+	const loadMock = vi.spyOn(LocalIndexedDb.prototype, 'load').mockImplementationOnce(() => load)
+	try {
+		const { client, tick } = testClient()
+		client.store.put([PageRecordType.create({ name: 'early', index: 'a0' as IndexKey })])
+		client.close()
+		load.resolve({ records: [], schema: undefined, sessionStateSnapshot: undefined })
+		await tick()
+		expect(client.db.storeSnapshot).not.toHaveBeenCalled()
+		expect(client.db.storeChanges).not.toHaveBeenCalled()
+	} finally {
+		loadMock.mockRestore()
+	}
+})
+
+test.each(['close flush', 'in-flight write'] as const)(
+	'a failed %s after close logs the error without disrupting the current page',
+	async (when) => {
+		const { client, tick } = testClient()
+		await tick()
+		const write = promiseWithResolve<void>()
+		client.db.storeSnapshot.mockImplementationOnce(() => write)
+		const error = new Error('write failed')
+		const log = vi.spyOn(console, 'error').mockImplementation(() => {})
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => {})
+		try {
+			client.store.put([PageRecordType.create({ name: 'last edit', index: 'a0' as IndexKey })])
+			if (when === 'in-flight write') await tick()
+			client.close()
+			write.reject(error)
+			await tick()
+			expect(log).toHaveBeenCalledWith('failed to store changes in indexed db', error)
+			expect(alert).not.toHaveBeenCalled()
+			expect(reloadMock).not.toHaveBeenCalled()
+		} finally {
+			log.mockRestore()
+			alert.mockRestore()
+		}
+	}
+)
+
+test('closing with no queued changes cancels a failed-write retry', async () => {
+	const { client, tick } = testClient()
+	await tick()
+	const log = vi.spyOn(console, 'error').mockImplementation(() => {})
+	const alert = vi.spyOn(window, 'alert').mockImplementation(() => {})
+	try {
+		client.db.storeSnapshot.mockRejectedValueOnce(new Error('first write failed'))
+		client.store.put([PageRecordType.create({ name: 'retry', index: 'a0' as IndexKey })])
+		await tick()
+		expect(reloadMock).toHaveBeenCalledTimes(1)
+		client.close()
+		await vi.advanceTimersByTimeAsync(10_000)
+		expect(client.db.storeSnapshot).toHaveBeenCalledTimes(1)
+	} finally {
+		log.mockRestore()
+		alert.mockRestore()
+	}
+})
+
+test('a schema mismatch does not try to refresh without a window', async () => {
+	const { client, channel, tick } = testClient()
+	await tick()
+	vi.advanceTimersByTime(10_000)
+	vi.stubGlobal('window', undefined)
+	try {
+		expect(() =>
+			channel.onmessage?.({
+				data: {
+					type: 'announce',
+					schema: {
+						...client.serializedSchema,
+						schemaVersion: client.serializedSchema.schemaVersion + 1,
+					},
+				},
+			} as MessageEvent)
+		).not.toThrow()
+	} finally {
+		vi.unstubAllGlobals()
+		client.close()
+	}
+})
+
+test('onLoad can close the client without losing buffered remote changes', async () => {
+	const { client, channel, onLoad, tick } = testClient()
+	const page = PageRecordType.create({ name: 'remote', index: 'a0' as IndexKey })
+	channel.onmessage?.({
+		data: {
+			type: 'diff',
+			storeId: 'other-tab',
+			schema: client.serializedSchema,
+			changes: { added: { [page.id]: page }, updated: {}, removed: {} },
+		},
+	} as MessageEvent)
+	onLoad.mockImplementation(() => {
+		client.store.put([PageRecordType.create({ name: 'local', index: 'a1' as IndexKey })])
+		client.close()
+	})
+	await tick()
+	expect(client.db.storeSnapshot.mock.calls[0][0].snapshot[page.id]).toEqual(page)
+})
+
+test('a buffered newer schema reports a load error without announcing a successful load', async () => {
+	const { client, channel, onLoad, onLoadError, tick } = testClient()
+	channel.onmessage?.({
+		data: {
+			type: 'announce',
+			schema: {
+				...client.serializedSchema,
+				schemaVersion: client.serializedSchema.schemaVersion + 1,
+			},
+		},
+	} as MessageEvent)
+	await tick()
+	expect(onLoadError).toHaveBeenCalledTimes(1)
+	expect(onLoad).not.toHaveBeenCalled()
+	client.close()
+	expect(client.db.storeSnapshot).not.toHaveBeenCalled()
+})

package/src/lib/utils/sync/TLLocalSyncClient.ts

@@ -9,6 +9,7 @@ import {
 	extractSessionStateFromLegacySnapshot,
 	loadSessionStateSnapshotIntoStore,
 } from '../../config/TLSessionStateSnapshot'
+import { refreshPage } from '../runtime'
 import { showCantReadFromIndexDbAlert, showCantWriteToIndexDbAlert } from './alerts'
 import { LocalIndexedDb } from './LocalIndexedDb'
 
@@ -108,7 +109,6 @@ export class TLLocalSyncClient {
 		this.persistenceKey = persistenceKey
 		this.sessionId = sessionId
 		this.db = new LocalIndexedDb(persistenceKey)
-		this.disposables.add(() => this.db.close())
 
 		this.serializedSchema = this.store.schema.serialize()
 		this.$sessionStateSnapshot = createSessionStateSnapshotSignal(this.store)
@@ -179,6 +179,65 @@ export class TLLocalSyncClient {
 		this.debug('connecting')
 		let data: UnpackPromise<ReturnType<LocalIndexedDb['load']>> | undefined
 
+		const handleMessage = (msg: Message) => {
+			// if their schema is earlier than ours, we need to tell them so they can refresh
+			// if their schema is later than ours, we need to refresh
+			const res = this.store.schema.getMigrationsSince(msg.schema)
+
+			if (!res.ok) {
+				this.isReloading = true
+				// we are older, refresh
+				// but add a safety check to make sure we don't get in an infinite loop
+				const timeSinceInit = Date.now() - this.initTime
+				if (timeSinceInit < 5000) {
+					// This tab was just reloaded, but is out of date compared to other tabs.
+					// Not expecting this to ever happen. It should only happen if we roll back a release that incremented
+					// the schema version (which we should never do)
+					// Or maybe during development if you have multiple local tabs open running the app on prod mode and you
+					// check out an older commit. Dev server should be fine.
+					onLoadError(new Error('Schema mismatch, please close other tabs and reload the page'))
+					return false
+				}
+				this.debug('reloading')
+				if (typeof window !== 'undefined') refreshPage()
+				return false
+			} else if (res.value.length > 0) {
+				// they are older, tell them to refresh and not write any more data
+				this.debug('telling them to reload')
+				this.channel.postMessage({ type: 'announce', schema: this.serializedSchema })
+				// schedule a full db write in case they wrote data anyway
+				this.shouldDoFullDBWrite = true
+				this.schedulePersist()
+				return true
+			}
+			// otherwise, all good, same version :)
+			if (msg.type === 'diff') {
+				this.debug('applying diff')
+				transact(() => {
+					this.store.mergeRemoteChanges(() => {
+						this.store.applyDiff(msg.changes as any)
+					})
+				})
+			}
+			return true
+		}
+
+		// Listen from the start and buffer until we've loaded: diffs other tabs broadcast while
+		// we're still reading from IndexedDB would otherwise be dropped, then erased by our first
+		// (full) db write.
+		let bufferedMessages: Message[] | null = []
+		this.channel.onmessage = ({ data }) => {
+			this.debug('got message', data)
+			if (bufferedMessages) {
+				bufferedMessages.push(data as Message)
+			} else {
+				handleMessage(data as Message)
+			}
+		}
+		this.disposables.add(() => {
+			this.channel.close()
+		})
+
 		try {
 			data = await this.db.load({ sessionId: this.sessionId })
 		} catch (error: any) {
@@ -224,55 +283,17 @@ export class TLLocalSyncClient {
 					})
 				}
 			}
-
-			this.channel.onmessage = ({ data }) => {
-				this.debug('got message', data)
-				const msg = data as Message
-				// if their schema is earlier than ours, we need to tell them so they can refresh
-				// if their schema is later than ours, we need to refresh
-				const res = this.store.schema.getMigrationsSince(msg.schema)
-
-				if (!res.ok) {
-					// we are older, refresh
-					// but add a safety check to make sure we don't get in an infinite loop
-					const timeSinceInit = Date.now() - this.initTime
-					if (timeSinceInit < 5000) {
-						// This tab was just reloaded, but is out of date compared to other tabs.
-						// Not expecting this to ever happen. It should only happen if we roll back a release that incremented
-						// the schema version (which we should never do)
-						// Or maybe during development if you have multiple local tabs open running the app on prod mode and you
-						// check out an older commit. Dev server should be fine.
-						onLoadError(new Error('Schema mismatch, please close other tabs and reload the page'))
-						return
-					}
-					this.debug('reloading')
-					this.isReloading = true
-					window?.location?.reload?.()
-					return
-				} else if (res.value.length > 0) {
-					// they are older, tell them to refresh and not write any more data
-					this.debug('telling them to reload')
-					this.channel.postMessage({ type: 'announce', schema: this.serializedSchema })
-					// schedule a full db write in case they wrote data anyway
-					this.shouldDoFullDBWrite = true
-					this.persistIfNeeded()
-					return
-				}
-				// otherwise, all good, same version :)
-				if (msg.type === 'diff') {
-					this.debug('applying diff')
-					transact(() => {
-						this.store.mergeRemoteChanges(() => {
-							this.store.applyDiff(msg.changes as any)
-						})
-					})
-				}
+			// Older-schema announcements schedule writes, so drain every diff before those writes
+			// or an onLoad callback that immediately closes the client can capture a snapshot.
+			const messages = bufferedMessages
+			bufferedMessages = null
+			for (const message of messages) {
+				if (!handleMessage(message)) return
 			}
-			this.channel.postMessage({ type: 'announce', schema: this.serializedSchema })
-			this.disposables.add(() => {
-				this.channel.close()
-			})
 			this.didLoad = true
+			if (this.diffQueue.length > 0) this.schedulePersist()
+
+			this.channel.postMessage({ type: 'announce', schema: this.serializedSchema })
 			onLoad(this)
 		} catch (e: any) {
 			this.debug('error loading data from store', e)
@@ -283,15 +304,43 @@ export class TLLocalSyncClient {
 	}
 
 	close() {
+		if (this.didDispose) return
 		this.debug('closing')
 		this.didDispose = true
+		// Store listeners normally run on the next frame; collect the last edits before removal.
+		this.store._flushHistory()
 		this.disposables.forEach((d) => d())
+		if (this.scheduledPersistTimeout) {
+			clearTimeout(this.scheduledPersistTimeout)
+			this.scheduledPersistTimeout = null
+		}
 		if (typeof window !== 'undefined' && (window as any).tlsync === this) {
 			delete (window as any).tlsync
 		}
+		this.flushAndCloseDb()
+	}
+
+	/**
+	 * Flush queued changes so edits made in the last PERSIST_THROTTLE_MS before unmount aren't lost,
+	 * then close the db. Never flushes before load (a full write then would wipe the db with an empty
+	 * store), and only when something is queued: shouldDoFullDBWrite stays true until the first
+	 * persist, so an unconditional flush would rewrite the whole document on every no-op close.
+	 */
+	private flushAndCloseDb() {
+		// A persist in flight can't be joined (persistIfNeeded bails while one is running) and,
+		// now that we're disposed, won't schedule a follow-up. Edits queued during that write
+		// would be lost if the db closed now, so wait for it and flush again.
+		if (this.persistPromise) {
+			this.persistPromise.then(() => this.flushAndCloseDb())
+			return
+		}
+		if (this.didLoad && this.diffQueue.length > 0) this.persistIfNeeded()
+		// the db waits for the transaction the flush just opened before actually closing
+		this.db.close()
 	}
 
 	private isPersisting = false
+	private persistPromise: Promise<void> | null = null
 	private didLastWriteError = false
 	// eslint-disable-next-line no-restricted-globals
 	private scheduledPersistTimeout: ReturnType<typeof setTimeout> | null = null
@@ -305,6 +354,8 @@ export class TLLocalSyncClient {
 	private schedulePersist() {
 		this.debug('schedulePersist', this.scheduledPersistTimeout)
 		if (this.scheduledPersistTimeout) return
+		// A deferred persist would try to write to a database that is closing or already closed.
+		if (this.didDispose) return
 		// eslint-disable-next-line no-restricted-globals
 		this.scheduledPersistTimeout = setTimeout(
 			() => {
@@ -339,6 +390,8 @@ export class TLLocalSyncClient {
 			this.scheduledPersistTimeout = null
 		}
 
+		if (!this.didLoad) return
+
 		// if a persist is already in progress, we don't need to do anything -
 		// if there are still outstanding changes once it's finished, it'll
 		// schedule another persist
@@ -353,7 +406,7 @@ export class TLLocalSyncClient {
 
 		// if we're scheduled for a full write or if we have changes outstanding, let's persist them!
 		if (this.shouldDoFullDBWrite || this.diffQueue.length > 0) {
-			this.doPersist()
+			this.persistPromise = this.doPersist()
 		}
 	}
 
@@ -363,7 +416,6 @@ export class TLLocalSyncClient {
 	 */
 	private async doPersist() {
 		assert(!this.isPersisting, 'persist already in progress')
-		if (this.didDispose) return
 		this.isPersisting = true
 
 		this.debug('doPersist start')
@@ -401,14 +453,14 @@ export class TLLocalSyncClient {
 			this.didLastWriteError = true
 			console.error('failed to store changes in indexed db', e)
 
-			showCantWriteToIndexDbAlert()
-			if (typeof window !== 'undefined') {
-				// adios
-				window.location.reload()
+			if (!this.didDispose && typeof window !== 'undefined') {
+				showCantWriteToIndexDbAlert()
+				refreshPage()
 			}
 		}
 
 		this.isPersisting = false
+		this.persistPromise = null
 		this.debug('doPersist end')
 
 		// changes might have come in between when we started the persist and

package/src/version.ts

@@ -1,9 +1,9 @@
 // This file is automatically generated by internal/scripts/refresh-assets.ts.
 // Do not edit manually. Or do, I'm a comment, not a cop.
 
-export const version = '5.4.2'
+export const version = '5.5.0-canary.0241f11f2e99'
 export const publishDates = {
 	major: '2026-05-06T16:28:18.473Z',
-	minor: '2026-09-02T11:04:02.901Z',
-	patch: '2026-09-10T12:05:42.789Z',
+	minor: '2026-09-10T11:28:47.056Z',
+	patch: '2026-09-10T11:28:47.056Z',
 }