@tldraw/editor 5.5.0-next.f9308d324e1c → 5.5.0

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

@@ -9,6 +9,9 @@ const STORE_PREFIX = 'TLDRAW_DOCUMENT_v2'
 const LEGACY_ASSET_STORE_PREFIX = 'TLDRAW_ASSET_STORE_v1'
 const dbNameIndexKey = 'TLDRAW_DB_NAME_INDEX_v2'
 
+/** How many session state rows (one per tab) to keep per document when pruning. */
+const MAX_SESSION_STATE_ROWS = 10
+
 /** @internal */
 export const Table = {
 	Records: 'records',
@@ -25,7 +28,7 @@ async function openLocalDb(persistenceKey: string) {
 
 	addDbName(storeId)
 
-	return await openDB<StoreName>(storeId, 4, {
+	const db = await openDB<StoreName>(storeId, 4, {
 		upgrade(database) {
 			if (!database.objectStoreNames.contains(Table.Records)) {
 				database.createObjectStore(Table.Records)
@@ -40,7 +43,16 @@ async function openLocalDb(persistenceKey: string) {
 				database.createObjectStore(Table.Assets)
 			}
 		},
+		// Another tab is deleting (hard reset) or upgrading this database. Its request waits
+		// until every open connection closes, so holding ours would stall it indefinitely.
+		// Closing here lets it proceed; this tab's next write then fails and goes through
+		// the write-failure alert-and-reload path.
+		blocking() {
+			console.warn(`Closing ${storeId} so another tab can delete or upgrade it`)
+			db.close()
+		},
 	})
+	return db
 }
 
 async function migrateLegacyAssetDbIfNeeded(persistenceKey: string) {
@@ -141,26 +153,22 @@ export class LocalIndexedDb {
 			assert(!this.isClosed, 'db is closed')
 			const db = await this.getDb()
 			const tx = db.transaction(names, mode)
-			// need to add a catch here early to prevent unhandled promise rejection
-			// during react-strict-mode where this tx.done promise can be rejected
-			// before we have a chance to await on it
-			const done = tx.done.catch((e: unknown) => {
-				if (!this.isClosed) {
-					throw e
-				}
-			})
+			// Commit failures may arrive before the callback finishes; observe them immediately
+			// while preserving the rejection for the await below.
+			const done = tx.done
+			done.catch(noop)
 			try {
 				return await cb(tx)
 			} finally {
-				if (!this.isClosed) {
-					await done
-				} else {
-					tx.abort()
-				}
+				// let the transaction commit even if close() was called meanwhile, otherwise a
+				// persist racing an unmount is silently rolled back
+				await done
 			}
 		})()
 		this.pendingTransactionSet.add(txPromise)
-		txPromise.finally(() => this.pendingTransactionSet.delete(txPromise))
+		// not `.finally()`: the promise it returns would re-reject with nobody observing it
+		const cleanup = () => this.pendingTransactionSet.delete(txPromise)
+		txPromise.then(cleanup, cleanup)
 		return txPromise
 	}
 
@@ -208,17 +216,19 @@ export class LocalIndexedDb {
 			const schemaStore = tx.objectStore(Table.Schema)
 			const sessionStateStore = tx.objectStore(Table.SessionState)
 
+			const requests: Promise<unknown>[] = []
 			for (const [id, record] of Object.entries(changes.added)) {
-				await recordsStore.put(record, id)
+				requests.push(recordsStore.put(record, id))
 			}
 
 			for (const [_prev, updated] of Object.values(changes.updated)) {
-				await recordsStore.put(updated, updated.id)
+				requests.push(recordsStore.put(updated, updated.id))
 			}
 
 			for (const id of Object.keys(changes.removed)) {
-				await recordsStore.delete(id)
+				requests.push(recordsStore.delete(id))
 			}
+			await Promise.all(requests)
 
 			schemaStore.put(schema.serialize(), Table.Schema)
 			if (sessionStateSnapshot && sessionId) {
@@ -254,9 +264,9 @@ export class LocalIndexedDb {
 
 			await recordsStore.clear()
 
-			for (const [id, record] of Object.entries(snapshot)) {
-				await recordsStore.put(record, id)
-			}
+			await Promise.all(
+				Object.entries(snapshot).map(([id, record]) => recordsStore.put(record, id))
+			)
 
 			schemaStore.put(schema.serialize(), Table.Schema)
 
@@ -275,15 +285,18 @@ export class LocalIndexedDb {
 		})
 	}
 
-	async pruneSessions() {
+	/**
+	 * Drop all but the most recently updated session state rows. The row for `keepSessionId` is never
+	 * deleted: it may be an old row that this tab restored its state from and has not rewritten yet,
+	 * and deleting it would make a later reload fall back to another tab's session state.
+	 */
+	async pruneSessions({ keepSessionId }: { keepSessionId?: string } = {}) {
 		await this.tx('readwrite', [Table.SessionState], async (tx) => {
 			const sessionStateStore = tx.objectStore(Table.SessionState)
-			const all = (await sessionStateStore.getAll()).sort((a, b) => a.updatedAt - b.updatedAt)
-			if (all.length < 10) {
-				await tx.done
-				return
-			}
-			const toDelete = all.slice(0, all.length - 10)
+			const all = ((await sessionStateStore.getAll()) as SessionStateSnapshotRow[])
+				.filter((row) => row.id !== keepSessionId)
+				.sort((a, b) => a.updatedAt - b.updatedAt)
+			const toDelete = all.slice(0, Math.max(0, all.length - MAX_SESSION_STATE_ROWS))
 			for (const { id } of toDelete) {
 				await sessionStateStore.delete(id)
 			}

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 {
@@ -38,9 +39,12 @@ function testClient(channel = new BroadcastChannelMock('test')) {
 
 	client.db.storeSnapshot = vi.fn(() => Promise.resolve())
 	client.db.storeChanges = vi.fn(() => Promise.resolve())
+	client.db.pruneSessions = vi.fn(() => Promise.resolve())
 
 	return {
-		client: client as { db: { storeSnapshot: Mock; storeChanges: Mock } } & typeof client,
+		client: client as {
+			db: { storeSnapshot: Mock; storeChanges: Mock; pruneSessions: Mock }
+		} & typeof client,
 		store,
 		onLoad,
 		onLoadError,
@@ -83,6 +87,23 @@ test('the client connects on instantiation, announcing its schema', async () =>
 	expect(msg).toMatchObject({ type: 'announce', schema: {} })
 })
 
+test('the client prunes stale session state rows after loading, keeping its own', async () => {
+	const { client, onLoad, tick } = testClient()
+	expect(client.db.pruneSessions).not.toHaveBeenCalled()
+	await tick()
+	expect(onLoad).toHaveBeenCalledTimes(1)
+	expect(client.db.pruneSessions).toHaveBeenCalledTimes(1)
+	expect(client.db.pruneSessions).toHaveBeenCalledWith({ keepSessionId: client.sessionId })
+})
+
+test('a failed session prune does not fail the load', async () => {
+	const { client, onLoad, onLoadError, tick } = testClient()
+	client.db.pruneSessions.mockImplementation(() => Promise.reject(new Error('nope')))
+	await tick()
+	expect(onLoad).toHaveBeenCalledTimes(1)
+	expect(onLoadError).not.toHaveBeenCalled()
+})
+
 test('when a client receives an announce with a newer schema version it reloads itself', async () => {
 	const { client, channel, onLoadError, tick } = testClient()
 	await tick()
@@ -214,6 +235,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 +316,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,56 +283,24 @@ 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)
+
+			// Session state rows accumulate one per tab, so trim them on load. Pruning is best-effort
+			// and must never turn a successful load into a failure.
+			this.db.pruneSessions({ keepSessionId: this.sessionId }).catch((e: unknown) => {
+				this.debug('failed to prune session state rows', e)
+			})
 		} catch (e: any) {
 			this.debug('error loading data from store', e)
 			if (this.didDispose) return
@@ -283,15 +310,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 +360,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 +396,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 +412,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 +422,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 +459,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.5.0-next.f9308d324e1c'
+export const version = '5.5.0'
 export const publishDates = {
 	major: '2026-05-06T16:28:18.473Z',
-	minor: '2026-09-04T10:04:53.550Z',
-	patch: '2026-09-04T10:04:53.550Z',
+	minor: '2026-09-30T10:03:27.724Z',
+	patch: '2026-09-30T10:03:27.724Z',
 }