@tldraw/sync-core 5.4.0-next.ef99ab47e5ce → 5.5.0-canary.04d1e6c4daff

package/src/lib/NodeSqliteWrapper.test.ts

@@ -272,5 +272,34 @@ describe('NodeSqliteWrapper', () => {
 			// the write was rolled back
 			expect(wrapper.prepare('SELECT * FROM test').all()).toEqual([])
 		})
+
+		it('[NW2] rolls back when COMMIT itself fails, so the connection is not left inside a transaction', () => {
+			// simulate a COMMIT failure (SQLITE_BUSY, I/O error) at the driver level
+			const failingDb = {
+				exec: (sql: string) => {
+					if (sql === 'COMMIT') throw new Error('SQLITE_BUSY: database is locked')
+					return db.exec(sql)
+				},
+				prepare: (sql: string) => db.prepare(sql),
+			}
+			const failingWrapper = new NodeSqliteWrapper(failingDb as any)
+
+			expect(() =>
+				failingWrapper.transaction(() => {
+					failingWrapper
+						.prepare('INSERT INTO test (id, name, value) VALUES (?, ?, ?)')
+						.run(1, 'alice', 100)
+				})
+			).toThrow('SQLITE_BUSY')
+
+			// rolled back, and the next transaction can BEGIN normally
+			expect(wrapper.prepare('SELECT * FROM test').all()).toEqual([])
+			expect(() =>
+				wrapper.transaction(() => {
+					wrapper.prepare('INSERT INTO test (id, name, value) VALUES (?, ?, ?)').run(2, 'bob', 200)
+				})
+			).not.toThrow()
+			expect(wrapper.prepare<{ id: number }>('SELECT id FROM test').all()).toEqual([{ id: 2 }])
+		})
 	})
 })

package/src/lib/NodeSqliteWrapper.ts

@@ -89,11 +89,14 @@ export class NodeSqliteWrapper implements TLSyncSqliteWrapper {
 		let result: T
 		try {
 			result = callback()
+			// COMMIT itself can fail (SQLITE_BUSY from another connection, I/O errors); without a
+			// ROLLBACK the connection would stay inside the transaction and every later BEGIN
+			// would throw "cannot start a transaction within a transaction"
+			this.db.exec('COMMIT')
 		} catch (e) {
 			this.db.exec('ROLLBACK')
 			throw e
 		}
-		this.db.exec('COMMIT')
 		return result
 	}
 }

package/src/lib/SQLiteSyncStorage.test.ts

@@ -1,7 +1,7 @@
 import { DatabaseSync } from 'node:sqlite'
 import { DocumentRecordType, PageRecordType, TLDOCUMENT_ID, TLRecord } from '@tldraw/tlschema'
 import { ZERO_INDEX_KEY } from '@tldraw/utils'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import {
 	contractRecords,
 	contractSchema,
@@ -9,6 +9,7 @@ import {
 	makePage,
 	registerStorageContractTests,
 } from '../test/storageContractSuite'
+import { MAX_TOMBSTONES } from './InMemorySyncStorage'
 import { NodeSqliteWrapper } from './NodeSqliteWrapper'
 import { SQLiteSyncStorage } from './SQLiteSyncStorage'
 
@@ -263,4 +264,62 @@ describe('SQLiteSyncStorage', () => {
 			expect(row?.migrationVersion).toBe(3)
 		})
 	})
+
+	describe('tombstone pruning robustness', () => {
+		const makeTombstones = (count: number) => {
+			const tombstones: Record<string, number> = {}
+			for (let i = 0; i < count; i++) tombstones[`shape:doc${i}`] = i + 1
+			return tombstones
+		}
+		function makeOverfullStorage() {
+			const db = new DatabaseSync(':memory:')
+			const storage = new SQLiteSyncStorage<TLRecord>({
+				sql: new NodeSqliteWrapper(db),
+				snapshot: makeContractSnapshot(contractRecords, {
+					tombstones: makeTombstones(MAX_TOMBSTONES + 500),
+					documentClock: MAX_TOMBSTONES + 501,
+					tombstoneHistoryStartsAtClock: 0,
+				}),
+			})
+			return { db, storage, prune: (storage as any).pruneTombstones as { (): void; flush(): void } }
+		}
+
+		it('[SS18] a prune that fires after the database was closed does not throw', () => {
+			const { db, storage, prune } = makeOverfullStorage()
+			const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+			try {
+				// a delete schedules the throttled prune; the host then closes everything
+				storage.transaction((txn) => txn.delete(contractRecords[1].id))
+				db.close()
+				// the throttle timer fires later, from outside any caller that could catch it
+				expect(() => prune.flush()).not.toThrow()
+				expect(consoleSpy).toHaveBeenCalledWith('Failed to prune tombstones', expect.anything())
+			} finally {
+				consoleSpy.mockRestore()
+			}
+		})
+
+		it('[SS18] a prune whose delete fails leaves the history clock where it was', () => {
+			const { storage, prune } = makeOverfullStorage()
+			const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+			try {
+				const stmts = (storage as any).stmts
+				const originalRun = stmts.deleteTombstonesBefore.run
+				stmts.deleteTombstonesBefore.run = () => {
+					throw new Error('SQLITE_BUSY: database is locked')
+				}
+				prune()
+				expect(() => prune.flush()).not.toThrow()
+				stmts.deleteTombstonesBefore.run = originalRun
+
+				// neither half of the prune applied: the history start was not advanced past
+				// tombstones that still exist
+				const snapshot = storage.getSnapshot()
+				expect(snapshot.tombstoneHistoryStartsAtClock).toBe(0)
+				expect(Object.keys(snapshot.tombstones!).length).toBe(MAX_TOMBSTONES + 500)
+			} finally {
+				consoleSpy.mockRestore()
+			}
+		})
+	})
 })

package/src/lib/SQLiteSyncStorage.ts

@@ -394,7 +394,6 @@ export class SQLiteSyncStorage<R extends UnknownRecord> implements TLSyncStorage
 			const documentClock = snapshot.documentClock ?? snapshot.clock ?? 0
 			const tombstoneHistoryStartsAtClock = snapshot.tombstoneHistoryStartsAtClock ?? documentClock
 
-			// Clear existing data
 			this.sql.exec(`
 				DELETE FROM ${documentsTable};
 				DELETE FROM ${objectsTable};
@@ -410,14 +409,12 @@ export class SQLiteSyncStorage<R extends UnknownRecord> implements TLSyncStorage
 				table.insert.run(doc.state.id, encodeState(doc.state), doc.lastChangedClock)
 			}
 
-			// Insert tombstones
 			if (snapshot.tombstones) {
 				for (const [id, clock] of objectMapEntries(snapshot.tombstones)) {
 					this.stmts.insertTombstone.run(id, clock)
 				}
 			}
 
-			// Insert metadata row
 			this.stmts.updateMetadata.run(
 				documentClock,
 				tombstoneHistoryStartsAtClock,
@@ -513,18 +510,29 @@ export class SQLiteSyncStorage<R extends UnknownRecord> implements TLSyncStorage
 	/** @internal */
 	pruneTombstones = throttle(
 		() => {
-			const tombstoneCount = this.stmts.countTombstones.all()[0].count as number
-			if (tombstoneCount > MAX_TOMBSTONES) {
-				// Get all tombstones sorted by clock ascending (oldest first)
-				const tombstones = this.stmts.iterateTombstones.all()
-
-				const result = computeTombstonePruning({ tombstones, documentClock: this.getClock() })
-				if (result) {
-					this.stmts.setTombstoneHistoryStartsAtClock.run(result.newTombstoneHistoryStartsAtClock)
-					// Delete all tombstones with clock < newTombstoneHistoryStartsAtClock in one operation.
-					// This works because computeTombstonePruning ensures we never split a clock value.
-					this.stmts.deleteTombstonesBefore.run(result.newTombstoneHistoryStartsAtClock)
+			// Runs from a timer, so a host that closed the database right after the last delete
+			// (e.g. `room.close(); db.close()` in onSessionRemoved) would otherwise get an uncaught
+			// throw from here; pruning is best-effort and simply runs again on the next delete.
+			try {
+				const tombstoneCount = this.stmts.countTombstones.all()[0].count as number
+				if (tombstoneCount > MAX_TOMBSTONES) {
+					// Get all tombstones sorted by clock ascending (oldest first)
+					const tombstones = this.stmts.iterateTombstones.all()
+
+					const result = computeTombstonePruning({ tombstones, documentClock: this.getClock() })
+					if (result) {
+						this.sql.transaction(() => {
+							this.stmts.setTombstoneHistoryStartsAtClock.run(
+								result.newTombstoneHistoryStartsAtClock
+							)
+							// Delete all tombstones with clock < newTombstoneHistoryStartsAtClock in one operation.
+							// This works because computeTombstonePruning ensures we never split a clock value.
+							this.stmts.deleteTombstonesBefore.run(result.newTombstoneHistoryStartsAtClock)
+						})
+					}
 				}
+			} catch (e) {
+				console.error('Failed to prune tombstones', e)
 			}
 		},
 		1000,

package/src/lib/TLSyncClient.test.ts

@@ -598,19 +598,55 @@ describe('TLSyncClient', () => {
 			expect(socket.getSentMessages().filter((m) => m.type === 'ping')).toHaveLength(2)
 		})
 
-		it('[CL9] warns and resets the connection after 10 seconds without server interaction', () => {
+		it('[CL9][CL14] resets when pings keep being sent but nothing comes back (half-open socket)', () => {
 			const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
 			client = createClient()
 			socket.mockServerMessage(createConnectMessage())
 
-			// advance time beyond the health check threshold
-			vi.advanceTimersByTime(15000)
+			// pings at 5s/10s go unanswered but the sends still "succeed"
+			vi.advanceTimersByTime(10_000)
+			// health tick at 10s: the oldest unanswered ping (t=5s) is only 5s old — not yet overdue
+			expect(client.isConnectedToRoom).toBe(true)
 
+			vi.advanceTimersByTime(10_000)
+			// health tick at 20s: the t=5s ping is 15s old, past PONG_TIMEOUT — evidence of a dead socket
+			expect(client.isConnectedToRoom).toBe(false)
 			expect(consoleSpy).toHaveBeenCalledWith(
-				expect.stringContaining("Haven't heard from the server in a while")
+				expect.stringContaining("Haven't heard from the server"),
+				expect.objectContaining({ pingOutstandingMs: expect.any(Number) })
 			)
+			consoleSpy.mockRestore()
+		})
+
+		it('[CL14] a pong landing in the same millisecond as the ping still counts as an answer', () => {
+			const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+			client = createClient()
+			socket.mockServerMessage(createConnectMessage())
+
+			// three ping/pong rounds where the pong arrives in the same ms as the ping send
+			for (let i = 0; i < 3; i++) {
+				vi.advanceTimersByTime(5000)
+				socket.mockServerMessage({ type: 'pong' })
+			}
+			expect(client.isConnectedToRoom).toBe(true)
+
+			// then the socket dies: the t=20s ping goes unanswered and must still convict.
+			// Guards the >= in the marker-advance rule: with > the same-ms pongs above would
+			// freeze the marker and the dead socket would never reset.
+			vi.advanceTimersByTime(25_000)
 			expect(client.isConnectedToRoom).toBe(false)
+			consoleSpy.mockRestore()
+		})
 
+		it('[CL14] the unanswered-ping marker clears on connection reset', () => {
+			const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+			client = createClient()
+			socket.mockServerMessage(createConnectMessage())
+
+			// drive a reset via a dead socket
+			vi.advanceTimersByTime(20_000)
+			expect(client.isConnectedToRoom).toBe(false)
+			expect((client as any).firstUnansweredPingAt).toBeNull()
 			consoleSpy.mockRestore()
 		})
 
@@ -626,13 +662,35 @@ describe('TLSyncClient', () => {
 			vi.advanceTimersByTime(4000)
 			expect(client.isConnectedToRoom).toBe(true)
 
-			// at t=20s nothing has been heard since the pong, so the connection resets
-			vi.advanceTimersByTime(10000)
+			// at t=15s the oldest unanswered ping (t=10s) is 5s old — not yet overdue
+			vi.advanceTimersByTime(5000)
+			expect(client.isConnectedToRoom).toBe(true)
+
+			// at t=20s it is exactly PONG_TIMEOUT old — reset
+			vi.advanceTimersByTime(5000)
 			expect(client.isConnectedToRoom).toBe(false)
 
 			consoleSpy.mockRestore()
 		})
 
+		it('[CL9] does not reset a healthy connection when timers wake infrequently (hidden-tab throttling)', () => {
+			const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+			client = createClient()
+			socket.mockServerMessage(createConnectMessage())
+
+			// Chrome batches a hidden tab's timers to ~1/min wakes: the clock jumps, then the
+			// delayed ping + health ticks fire together, and the pong arrives right after.
+			for (let i = 0; i < 3; i++) {
+				vi.setSystemTime(Date.now() + 60_000)
+				vi.advanceTimersByTime(10_000)
+				expect(client.isConnectedToRoom).toBe(true)
+				socket.mockServerMessage({ type: 'pong' })
+			}
+
+			expect(consoleSpy).not.toHaveBeenCalled()
+			consoleSpy.mockRestore()
+		})
+
 		it('[CL11] closes instead of processing the next event when didCancel returns true', () => {
 			let cancelled = false
 			client = createClient({ didCancel: () => cancelled })

package/src/lib/TLSyncClient.ts

@@ -286,6 +286,12 @@ export interface TLPersistentClientSocket<
 
 const PING_INTERVAL = 5000
 const MAX_TIME_TO_WAIT_FOR_SERVER_INTERACTION_BEFORE_RESETTING_CONNECTION = PING_INTERVAL * 2
+/**
+ * How long an unanswered ping may stay outstanding before the connection is considered dead.
+ * Tuned together with MAX_TIME_TO_WAIT_FOR_SERVER_INTERACTION_BEFORE_RESETTING_CONNECTION:
+ * a reset needs both stale interaction and a ping overdue by this much.
+ */
+const PONG_TIMEOUT = PING_INTERVAL * 2
 
 // Should connect support chunking the response to allow for large payloads?
 
@@ -367,6 +373,11 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 	/** The last clock time from the most recent server update */
 	private lastServerClock = -1
 	private lastServerInteractionTimestamp = Date.now()
+	/**
+	 * Send time of the oldest outstanding ping; answered iff `lastServerInteractionTimestamp >= it`
+	 * (any server message counts). Null until the first ping after (re)connect.
+	 */
+	private firstUnansweredPingAt: number | null = null
 
 	/** The queue of in-flight push requests that have not yet been acknowledged by the server */
 	private pendingPushRequests: TLPushRequest<R>[] = []
@@ -600,6 +611,14 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 				this.debug('ping loop', { isConnectedToRoom: this.isConnectedToRoom })
 				if (!this.isConnectedToRoom) return
 				try {
+					// advance the marker only when the previous ping was answered: a half-open socket
+					// that accepts sends but returns nothing must not keep refreshing its own alibi
+					if (
+						this.firstUnansweredPingAt === null ||
+						this.lastServerInteractionTimestamp >= this.firstUnansweredPingAt
+					) {
+						this.firstUnansweredPingAt = Date.now()
+					}
 					this.socket.sendMessage({ type: 'ping' })
 				} catch (error) {
 					console.warn('ping failed, resetting', error)
@@ -618,11 +637,27 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 					MAX_TIME_TO_WAIT_FOR_SERVER_INTERACTION_BEFORE_RESETTING_CONNECTION
 				) {
 					this.debug('health check passed', { timeSinceLastServerInteraction })
-					// last ping was recent, so no need to take any action
 					return
 				}
 
-				console.warn(`Haven't heard from the server in a while, resetting connection...`)
+				// Silence alone is not evidence of a dead socket: in a throttled hidden tab our own ping
+				// loop stops, so the server had nothing to answer. Only reset on an unanswered ping.
+				const firstUnansweredPingAt = this.firstUnansweredPingAt
+				const pingOverdue =
+					firstUnansweredPingAt !== null &&
+					this.lastServerInteractionTimestamp < firstUnansweredPingAt &&
+					Date.now() - firstUnansweredPingAt >= PONG_TIMEOUT
+				if (!pingOverdue) {
+					this.debug('health check stale but no overdue ping', { timeSinceLastServerInteraction })
+					return
+				}
+
+				// A frozen tab can deliver a queued pong only after these catch-up ticks run, so one
+				// spurious reset on unfreeze is still possible — rare, and the reconnect is clean.
+				console.warn(`Haven't heard from the server in a while, resetting connection...`, {
+					timeSinceLastServerInteraction,
+					pingOutstandingMs: Date.now() - firstUnansweredPingAt!,
+				})
 				this.resetConnection()
 			}, PING_INTERVAL * 2)
 		)
@@ -684,6 +719,7 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 		}
 		this.lastPushedPresenceState = null
 		this.isConnectedToRoom = false
+		this.firstUnansweredPingAt = null
 		this.pendingPushRequests = []
 		this.incomingDiffBuffer = []
 		this.unsentChanges.nextDiff = undefined

package/src/lib/TLSyncRoom.ts

@@ -258,7 +258,8 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 	}, 1000)
 
 	private scheduleFollowUpPrune() {
-		if (this.pruneTimer) return
+		// don't leave a stray timer on a room the host has already torn down
+		if (this._isClosed || this.pruneTimer) return
 		this.pruneTimer = setTimeout(this.pruneSessions, SESSION_REMOVAL_WAIT_TIME + 100)
 	}
 
@@ -273,11 +274,27 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 	 * and stops background processes.
 	 */
 	close() {
+		this._isClosed = true
 		this.disposables.forEach((d) => d())
 		this.sessions.forEach((session) => {
-			session.socket.close()
+			this.clearDebounceTimer(session)
+			try {
+				session.socket.close()
+			} catch {
+				// noop, one bad socket must not leave the rest open
+			}
 		})
-		this._isClosed = true
+		// forgetting the sessions is what makes late socket close/error events no-ops, so
+		// nothing can emit session_removed / room_became_empty on a closed room
+		this.sessions.clear()
+	}
+
+	private clearDebounceTimer(session: RoomSession<R, SessionMeta>) {
+		if (session.state === RoomSessionState.Connected && session.debounceTimer !== null) {
+			clearTimeout(session.debounceTimer)
+			session.debounceTimer = null
+			session.outstandingDataMessages = []
+		}
 	}
 
 	/**
@@ -519,6 +536,12 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			// place, so sockets that defer serialization don't see an emptied array
 			const data = session.outstandingDataMessages
 			session.outstandingDataMessages = []
+			if (!session.socket.isOpen) {
+				// same as the immediate-send path: send() into a closed socket throws on
+				// some runtimes (Cloudflare), and here that would be from inside a timer
+				this.cancelSession(sessionId)
+				return
+			}
 			session.socket.sendMessage({ type: 'data', data })
 		}
 	}
@@ -532,6 +555,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 		}
 
 		this.sessions.delete(sessionId)
+		this.clearDebounceTimer(session)
 
 		try {
 			if (fatalReason) {
@@ -570,6 +594,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			return
 		}
 
+		this.clearDebounceTimer(session)
 		this.sessions.set(sessionId, {
 			state: RoomSessionState.AwaitingRemoval,
 			sessionId,
@@ -692,7 +717,13 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 		objectAccess?: TLObjectStoreAccess
 	}) {
 		const { sessionId, socket, meta, isReadonly, objectAccess } = opts
+		// a connect racing close() would otherwise create a session nothing ever prunes
+		if (this._isClosed) {
+			socket.close()
+			return this
+		}
 		const existing = this.sessions.get(sessionId)
+		if (existing) this.clearDebounceTimer(existing)
 		this.sessions.set(sessionId, {
 			state: RoomSessionState.AwaitingConnectMessage,
 			sessionId,
@@ -741,6 +772,11 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			supportsStringAppend,
 		} = opts
 
+		if (this._isClosed) {
+			socket.close()
+			return
+		}
+
 		const migrations = this.schema.getMigrationsSince(serializedSchema)
 		const requiresDownMigrations = migrations.ok ? migrations.value.length > 0 : false
 

package/src/lib/TLSyncStorage.test.ts

@@ -122,6 +122,43 @@ describe('loadSnapshotIntoStorage', () => {
 		expect(storage.getClock()).toBe(5)
 	})
 
+	it('[SL3] does not delete while a key iterator is open (better-sqlite3 rejects that)', () => {
+		const extraPage = makePage('extra', 'Extra')
+		const storage = new InMemorySyncStorage<TLRecord>({
+			snapshot: makeContractSnapshot([...contractRecords, extraPage]),
+		})
+
+		storage.transaction((txn) => {
+			// better-sqlite3 throws on any write while a statement iterator is still open; mimic
+			// that so a delete issued from inside `for (const id of txn.keys())` fails loudly
+			let openIterators = 0
+			const guarded: typeof txn = Object.create(txn, {
+				keys: {
+					value: function* () {
+						openIterators++
+						try {
+							yield* Array.from(txn.keys())
+						} finally {
+							openIterators--
+						}
+					},
+				},
+				delete: {
+					value: (id: string) => {
+						if (openIterators > 0) {
+							throw new Error('This database connection is busy executing a query')
+						}
+						return txn.delete(id)
+					},
+				},
+			})
+			loadSnapshotIntoStorage(guarded, contractSchema, makeContractSnapshot(contractRecords))
+		})
+
+		expect(storage.documents.has(extraPage.id)).toBe(false)
+		expect(storage.tombstones.has(extraPage.id)).toBe(true)
+	})
+
 	it('[SL4] persists the snapshot schema and migrates loaded records to the current version', () => {
 		interface TestRecord extends BaseRecord<'test', RecordId<TestRecord>> {
 			value: number

package/src/lib/TLSyncStorage.ts

@@ -1,6 +1,6 @@
 import { StoreSchema, SynchronousStorage, UnknownRecord } from '@tldraw/store'
+import { TLStoreSnapshot } from '@tldraw/tlschema'
 import { assert, isEqual, objectMapEntriesIterable, objectMapValues } from '@tldraw/utils'
-import { TLStoreSnapshot } from 'tldraw'
 import { diffRecord, NetworkDiff, RecordOpType } from './diff'
 import { RoomSnapshot } from './TLSyncRoom'
 
@@ -205,7 +205,9 @@ export function loadSnapshotIntoStorage<R extends UnknownRecord>(
 		if (isEqual(existing, doc.state)) continue
 		txn.set(doc.state.id, doc.state as R)
 	}
-	for (const id of txn.keys()) {
+	// materialize the keys first: some SQLite drivers (better-sqlite3) refuse writes while a
+	// statement iterator is open, so deleting during `keys()` would throw
+	for (const id of Array.from(txn.keys())) {
 		if (!docIds.has(id)) {
 			txn.delete(id)
 		}

package/src/lib/chunk.test.ts

@@ -134,6 +134,40 @@ describe('chunk (CH1–CH3)', () => {
 		`)
 		})
 	})
+
+	describe('surrogate pairs (CH9)', () => {
+		it('[CH9] never splits a surrogate pair across two chunks', () => {
+			// WebSocket.send converts each chunk to a USVString, so a lone surrogate would arrive
+			// as U+FFFD and the reassembled message would carry corrupted text
+			const emoji = '\u{1F600}'
+			const isHigh = (code: number) => code >= 0xd800 && code <= 0xdbff
+			const isLow = (code: number) => code >= 0xdc00 && code <= 0xdfff
+			const msgs = [
+				...Array.from(
+					{ length: 8 },
+					(_, padding) => 'x'.repeat(padding) + emoji + 'y'.repeat(6) + emoji
+				),
+				// adjacent pairs: after a nudge the next boundary lands on another pair
+				'x' + emoji.repeat(3),
+			]
+			for (const msg of msgs) {
+				for (const maxSize of [3, 4, 5, 6, 7, 8]) {
+					const chunks = chunk(msg, maxSize)
+					const bodies = chunks.map((c) => c.slice(c.indexOf('_') + 1))
+					expect(bodies.join('')).toBe(msg)
+					for (const [i, body] of bodies.entries()) {
+						expect(body.length).toBeGreaterThan(0)
+						expect(isHigh(body.charCodeAt(body.length - 1))).toBe(false)
+						expect(isLow(body.charCodeAt(0))).toBe(false)
+						// keeping a pair whole may cost one character over the CH3 bound, never more
+						expect(chunks[i].length).toBeLessThanOrEqual(
+							Math.max(maxSize, chunks[i].indexOf('_') + 2) + 1
+						)
+					}
+				}
+			}
+		})
+	})
 })
 
 const testObject = {} as any

package/src/lib/chunk.ts

@@ -38,7 +38,18 @@ export function chunk(msg: string, maxSafeMessageSize = MAX_SAFE_MESSAGE_SIZE) {
 		let offset = msg.length
 		while (offset > 0) {
 			const prefix = `${chunkNumber}_`
-			const chunkSize = Math.max(Math.min(maxSafeMessageSize - prefix.length, offset), 1)
+			let chunkSize = Math.max(Math.min(maxSafeMessageSize - prefix.length, offset), 1)
+			// Never split a surrogate pair across chunks: WebSocket.send converts each chunk to a
+			// USVString, turning a lone surrogate into U+FFFD, so the reassembled JSON silently
+			// carries corrupted text. Shrink by one so the pair moves whole into the preceding
+			// chunk; a single-character chunk grows by one instead (one over the CH3 bound, see CH9).
+			if (
+				chunkSize < offset &&
+				isLowSurrogate(msg.charCodeAt(offset - chunkSize)) &&
+				isHighSurrogate(msg.charCodeAt(offset - chunkSize - 1))
+			) {
+				chunkSize += chunkSize > 1 ? -1 : 1
+			}
 			chunks.unshift(prefix + msg.slice(offset - chunkSize, offset))
 			offset -= chunkSize
 			chunkNumber++
@@ -47,6 +58,14 @@ export function chunk(msg: string, maxSafeMessageSize = MAX_SAFE_MESSAGE_SIZE) {
 	}
 }
 
+function isHighSurrogate(code: number) {
+	return code >= 0xd800 && code <= 0xdbff
+}
+
+function isLowSurrogate(code: number) {
+	return code >= 0xdc00 && code <= 0xdfff
+}
+
 // The 's' flag (dotAll) makes '.' match any character including line terminators
 // like U+2028 and U+2029, which are commonly introduced via copy/paste from Word
 const chunkRe = /^(\d+)_(.*)$/s