@tldraw/sync-core 4.2.0-canary.f59b349f83fb → 4.2.0-canary.fa5328cd004a

package/src/lib/TLSyncRoom.ts

@@ -156,10 +156,15 @@ export class DocumentState<R extends UnknownRecord> {
 	 *
 	 * @param state - The new record state
 	 * @param clock - The new clock value
+	 * @param legacyAppendMode - If true, string append operations will be converted to Put operations
 	 * @returns Result containing the diff and new DocumentState, or null if no changes, or validation error
 	 */
-	replaceState(state: R, clock: number): Result<[ObjectDiff, DocumentState<R>] | null, Error> {
-		const diff = diffRecord(this.state, state)
+	replaceState(
+		state: R,
+		clock: number,
+		legacyAppendMode = false
+	): Result<[ObjectDiff, DocumentState<R>] | null, Error> {
+		const diff = diffRecord(this.state, state, legacyAppendMode)
 		if (!diff) return Result.ok(null)
 		try {
 			this.recordType.validate(state)
@@ -173,11 +178,16 @@ export class DocumentState<R extends UnknownRecord> {
 	 *
 	 * @param diff - The object diff to apply
 	 * @param clock - The new clock value
+	 * @param legacyAppendMode - If true, string append operations will be converted to Put operations
 	 * @returns Result containing the final diff and new DocumentState, or null if no changes, or validation error
 	 */
-	mergeDiff(diff: ObjectDiff, clock: number): Result<[ObjectDiff, DocumentState<R>] | null, Error> {
+	mergeDiff(
+		diff: ObjectDiff,
+		clock: number,
+		legacyAppendMode = false
+	): Result<[ObjectDiff, DocumentState<R>] | null, Error> {
 		const newState = applyObjectDiff(this.state, diff)
-		return this.replaceState(newState, clock)
+		return this.replaceState(newState, clock, legacyAppendMode)
 	}
 }
 
@@ -720,6 +730,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			meta: session.meta,
 			isReadonly: session.isReadonly,
 			requiresLegacyRejection: session.requiresLegacyRejection,
+			supportsStringAppend: session.supportsStringAppend,
 		})
 
 		try {
@@ -843,10 +854,28 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 			isReadonly: isReadonly ?? false,
 			// this gets set later during handleConnectMessage
 			requiresLegacyRejection: false,
+			supportsStringAppend: true,
 		})
 		return this
 	}
 
+	/**
+	 * Checks if all connected sessions support string append operations (protocol version 8+).
+	 * If any client is on an older version, returns false to enable legacy append mode.
+	 *
+	 * @returns True if all connected sessions are on protocol version 8 or higher
+	 */
+	getCanEmitStringAppend(): boolean {
+		for (const session of this.sessions.values()) {
+			if (session.state === RoomSessionState.Connected) {
+				if (!session.supportsStringAppend) {
+					return false
+				}
+			}
+		}
+		return true
+	}
+
 	/**
 	 * When we send a diff to a client, if that client is on a lower version than us, we need to make
 	 * the diff compatible with their version. At the moment this means migrating each affected record
@@ -1010,6 +1039,10 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 		if (theirProtocolVersion === 6) {
 			theirProtocolVersion++
 		}
+		if (theirProtocolVersion === 7) {
+			theirProtocolVersion++
+			session.supportsStringAppend = false
+		}
 
 		if (theirProtocolVersion == null || theirProtocolVersion < getTlsyncProtocolVersion()) {
 			this.rejectSession(session.sessionId, TLSyncErrorCloseEventReason.CLIENT_TOO_OLD)
@@ -1045,6 +1078,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 				lastInteractionTime: Date.now(),
 				debounceTimer: null,
 				outstandingDataMessages: [],
+				supportsStringAppend: session.supportsStringAppend,
 				meta: session.meta,
 				isReadonly: session.isReadonly,
 				requiresLegacyRejection: session.requiresLegacyRejection,
@@ -1150,6 +1184,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 		const initialDocumentClock = this.documentClock
 		let didPresenceChange = false
 		transaction((rollback) => {
+			const legacyAppendMode = !this.getCanEmitStringAppend()
 			// collect actual ops that resulted from the push
 			// these will be broadcast to other users
 			interface ActualChanges {
@@ -1198,7 +1233,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 				if (doc) {
 					// If there's an existing document, replace it with the new state
 					// but propagate a diff rather than the entire value
-					const diff = doc.replaceState(state, this.clock)
+					const diff = doc.replaceState(state, this.clock, legacyAppendMode)
 					if (!diff.ok) {
 						return fail(TLSyncErrorCloseEventReason.INVALID_RECORD)
 					}
@@ -1238,7 +1273,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 
 				if (downgraded.value === doc.state) {
 					// If the versions are compatible, apply the patch and propagate the patch op
-					const diff = doc.mergeDiff(patch, this.clock)
+					const diff = doc.mergeDiff(patch, this.clock, legacyAppendMode)
 					if (!diff.ok) {
 						return fail(TLSyncErrorCloseEventReason.INVALID_RECORD)
 					}
@@ -1260,7 +1295,7 @@ export class TLSyncRoom<R extends UnknownRecord, SessionMeta> {
 						return fail(TLSyncErrorCloseEventReason.CLIENT_TOO_OLD)
 					}
 					// replace the state with the upgraded version and propagate the patch op
-					const diff = doc.replaceState(upgraded.value, this.clock)
+					const diff = doc.replaceState(upgraded.value, this.clock, legacyAppendMode)
 					if (!diff.ok) {
 						return fail(TLSyncErrorCloseEventReason.INVALID_RECORD)
 					}

package/src/lib/chunk.ts

@@ -83,13 +83,13 @@ export class JsonChunkAssembler {
 
 	/**
 	 * Processes a single message, which can be either a complete JSON object or a chunk.
-	 * For complete JSON objects (starting with '{'), parses immediately.
-	 * For chunks (prefixed with "{number}_"), accumulates until all chunks received.
+	 * For complete JSON objects (starting with '\{'), parses immediately.
+	 * For chunks (prefixed with "\{number\}_"), accumulates until all chunks received.
 	 *
 	 * @param msg - The message to process, either JSON or chunk format
 	 * @returns Result object with data/stringified on success, error object on failure, or null for incomplete chunks
-	 * 	- `{ data: object, stringified: string }` - Successfully parsed complete message
-	 * 	- `{ error: Error }` - Parse error or invalid chunk sequence
+	 * 	- `\{ data: object, stringified: string \}` - Successfully parsed complete message
+	 * 	- `\{ error: Error \}` - Parse error or invalid chunk sequence
 	 * 	- `null` - Chunk received but more chunks expected
 	 *
 	 * @example

package/src/lib/diff.ts

@@ -123,11 +123,11 @@ export type ValueOpType = (typeof ValueOpType)[keyof typeof ValueOpType]
  */
 export type PutOp = [type: typeof ValueOpType.Put, value: unknown]
 /**
- * Operation that appends new values to the end of an array.
+ * Operation that appends new values to the end of an array or string.
  *
  * @internal
  */
-export type AppendOp = [type: typeof ValueOpType.Append, values: unknown[], offset: number]
+export type AppendOp = [type: typeof ValueOpType.Append, value: unknown[] | string, offset: number]
 /**
  * Operation that applies a nested diff to an object or array.
  *
@@ -165,6 +165,7 @@ export interface ObjectDiff {
  *
  * @param prev - The previous version of the record
  * @param next - The next version of the record
+ * @param legacyAppendMode - If true, string append operations will be converted to Put operations
  * @returns An ObjectDiff describing the changes, or null if no changes exist
  *
  * @example
@@ -181,11 +182,20 @@ export interface ObjectDiff {
  *
  * @internal
  */
-export function diffRecord(prev: object, next: object): ObjectDiff | null {
-	return diffObject(prev, next, new Set(['props']))
+export function diffRecord(
+	prev: object,
+	next: object,
+	legacyAppendMode = false
+): ObjectDiff | null {
+	return diffObject(prev, next, new Set(['props', 'meta']), legacyAppendMode)
 }
 
-function diffObject(prev: object, next: object, nestedKeys?: Set<string>): ObjectDiff | null {
+function diffObject(
+	prev: object,
+	next: object,
+	nestedKeys: Set<string> | undefined,
+	legacyAppendMode: boolean
+): ObjectDiff | null {
 	if (prev === next) {
 		return null
 	}
@@ -197,26 +207,22 @@ function diffObject(prev: object, next: object, nestedKeys?: Set<string>): Objec
 			result[key] = [ValueOpType.Delete]
 			continue
 		}
-		// if key is in both places, then compare values
-		const prevVal = (prev as any)[key]
-		const nextVal = (next as any)[key]
-		if (!isEqual(prevVal, nextVal)) {
-			if (nestedKeys?.has(key) && prevVal && nextVal) {
-				const diff = diffObject(prevVal, nextVal)
-				if (diff) {
-					if (!result) result = {}
-					result[key] = [ValueOpType.Patch, diff]
-				}
-			} else if (Array.isArray(nextVal) && Array.isArray(prevVal)) {
-				const op = diffArray(prevVal, nextVal)
-				if (op) {
-					if (!result) result = {}
-					result[key] = op
-				}
-			} else {
+		const prevValue = (prev as any)[key]
+		const nextValue = (next as any)[key]
+		if (
+			nestedKeys?.has(key) ||
+			(Array.isArray(prevValue) && Array.isArray(nextValue)) ||
+			(typeof prevValue === 'string' && typeof nextValue === 'string')
+		) {
+			// if key is in both places, then compare values
+			const diff = diffValue(prevValue, nextValue, legacyAppendMode)
+			if (diff) {
 				if (!result) result = {}
-				result[key] = [ValueOpType.Put, nextVal]
+				result[key] = diff
 			}
+		} else if (!isEqual(prevValue, nextValue)) {
+			if (!result) result = {}
+			result[key] = [ValueOpType.Put, nextValue]
 		}
 	}
 	for (const key of Object.keys(next)) {
@@ -229,19 +235,29 @@ function diffObject(prev: object, next: object, nestedKeys?: Set<string>): Objec
 	return result
 }
 
-function diffValue(valueA: unknown, valueB: unknown): ValueOp | null {
+function diffValue(valueA: unknown, valueB: unknown, legacyAppendMode: boolean): ValueOp | null {
 	if (Object.is(valueA, valueB)) return null
 	if (Array.isArray(valueA) && Array.isArray(valueB)) {
-		return diffArray(valueA, valueB)
+		return diffArray(valueA, valueB, legacyAppendMode)
+	} else if (typeof valueA === 'string' && typeof valueB === 'string') {
+		if (!legacyAppendMode && valueB.startsWith(valueA)) {
+			const appendedText = valueB.slice(valueA.length)
+			return [ValueOpType.Append, appendedText, valueA.length]
+		}
+		return [ValueOpType.Put, valueB]
 	} else if (!valueA || !valueB || typeof valueA !== 'object' || typeof valueB !== 'object') {
 		return isEqual(valueA, valueB) ? null : [ValueOpType.Put, valueB]
 	} else {
-		const diff = diffObject(valueA, valueB)
+		const diff = diffObject(valueA, valueB, undefined, legacyAppendMode)
 		return diff ? [ValueOpType.Patch, diff] : null
 	}
 }
 
-function diffArray(prevArray: unknown[], nextArray: unknown[]): PutOp | AppendOp | PatchOp | null {
+function diffArray(
+	prevArray: unknown[],
+	nextArray: unknown[],
+	legacyAppendMode: boolean
+): PutOp | AppendOp | PatchOp | null {
 	if (Object.is(prevArray, nextArray)) return null
 	// if lengths are equal, check for patch operation
 	if (prevArray.length === nextArray.length) {
@@ -267,7 +283,7 @@ function diffArray(prevArray: unknown[], nextArray: unknown[]): PutOp | AppendOp
 			if (!prevItem || !nextItem) {
 				diff[i] = [ValueOpType.Put, nextItem]
 			} else if (typeof prevItem === 'object' && typeof nextItem === 'object') {
-				const op = diffValue(prevItem, nextItem)
+				const op = diffValue(prevItem, nextItem, legacyAppendMode)
 				if (op) {
 					diff[i] = op
 				}
@@ -341,12 +357,19 @@ export function applyObjectDiff<T extends object>(object: T, objectDiff: ObjectD
 				break
 			}
 			case ValueOpType.Append: {
-				const values = op[1]
+				const value = op[1]
 				const offset = op[2]
-				const arr = object[key as keyof T]
-				if (Array.isArray(arr) && arr.length === offset) {
-					set(key, [...arr, ...values])
+				const currentValue = object[key as keyof T]
+				if (Array.isArray(currentValue) && Array.isArray(value) && currentValue.length === offset) {
+					set(key, [...currentValue, ...value])
+				} else if (
+					typeof currentValue === 'string' &&
+					typeof value === 'string' &&
+					currentValue.length === offset
+				) {
+					set(key, currentValue + value)
 				}
+				// If validation fails (type mismatch or length mismatch), silently ignore
 				break
 			}
 			case ValueOpType.Patch: {

package/src/lib/protocol.ts

@@ -1,7 +1,7 @@
 import { SerializedSchema, UnknownRecord } from '@tldraw/store'
 import { NetworkDiff, ObjectDiff, RecordOpType } from './diff'
 
-const TLSYNC_PROTOCOL_VERSION = 7
+const TLSYNC_PROTOCOL_VERSION = 8
 
 /**
  * Gets the current tldraw sync protocol version number.

package/src/test/TLSocketRoom.test.ts

@@ -159,7 +159,7 @@ describe(TLSocketRoom, () => {
 			type: 'connect' as const,
 			connectRequestId: 'connect-1',
 			lastServerClock: 0,
-			protocolVersion: 7,
+			protocolVersion: 8,
 			schema: store.schema.serialize(),
 		}
 		room.handleSocketMessage(sessionId1, JSON.stringify(connectRequest1))
@@ -168,7 +168,7 @@ describe(TLSocketRoom, () => {
 			type: 'connect' as const,
 			connectRequestId: 'connect-2',
 			lastServerClock: 0,
-			protocolVersion: 7,
+			protocolVersion: 8,
 			schema: store.schema.serialize(),
 		}
 		room.handleSocketMessage(sessionId2, JSON.stringify(connectRequest2))

package/src/test/TLSyncRoom.test.ts

@@ -313,27 +313,28 @@ describe('TLSyncRoom.updateStore', () => {
 		expect(documentClock).toBeLessThan(room.documentClock)
 
 		expect(socketA.__lastMessage).toMatchInlineSnapshot(`
-		{
-		  "data": [
-		    {
-		      "diff": {
-		        "document:document": [
-		          "patch",
-		          {
-		            "name": [
-		              "put",
-		              "My lovely document",
-		            ],
-		          },
-		        ],
-		      },
-		      "serverClock": 1,
-		      "type": "patch",
-		    },
-		  ],
-		  "type": "data",
-		}
-	`)
+			{
+			  "data": [
+			    {
+			      "diff": {
+			        "document:document": [
+			          "patch",
+			          {
+			            "name": [
+			              "append",
+			              "My lovely document",
+			              0,
+			            ],
+			          },
+			        ],
+			      },
+			      "serverClock": 1,
+			      "type": "patch",
+			    },
+			  ],
+			  "type": "data",
+			}
+		`)
 		expect(socketB.__lastMessage).toEqual(socketA.__lastMessage)
 	})
 

package/src/test/TestSocketPair.ts

@@ -62,7 +62,7 @@ export class TestSocketPair<R extends UnknownRecord> {
 	}
 	didReceiveFromClient?: (msg: TLSocketClientSentEvent<R>) => void = undefined
 	clientDisconnected?: () => void = undefined
-	clientSocket: TLPersistentClientSocket<R> = {
+	clientSocket: TLPersistentClientSocket<TLSocketClientSentEvent<R>, TLSocketServerSentEvent<R>> = {
 		connectionStatus: 'offline',
 		onStatusChange: (cb) => {
 			this.callbacks.onStatusChange = cb
@@ -76,7 +76,7 @@ export class TestSocketPair<R extends UnknownRecord> {
 				this.callbacks.onReceiveMessage = null
 			}
 		},
-		sendMessage: (msg: TLSocketClientSentEvent<R>) => {
+		sendMessage: (msg) => {
 			if (this.clientSocket.connectionStatus !== 'online') {
 				throw new Error('trying to send before open')
 			}
@@ -87,6 +87,9 @@ export class TestSocketPair<R extends UnknownRecord> {
 			this.disconnect()
 			this.connect()
 		},
+		close: () => {
+			this.disconnect()
+		},
 	}
 
 	callbacks = {

package/src/test/diff.test.ts

@@ -408,6 +408,155 @@ describe('array diffing comprehensive', () => {
 	})
 })
 
+describe('string appending', () => {
+	describe('basic string appending', () => {
+		it('should handle string appends', () => {
+			const prev = { text: 'Hello' }
+			const next = { text: 'Hello world' }
+
+			expect(diffRecord(prev, next)).toEqual({
+				text: [ValueOpType.Append, ' world', 5],
+			})
+		})
+
+		it('should handle empty string to non-empty', () => {
+			const prev = { text: '' }
+			const next = { text: 'Hello' }
+
+			expect(diffRecord(prev, next)).toEqual({
+				text: [ValueOpType.Append, 'Hello', 0],
+			})
+		})
+
+		it('should use put when string is replaced (not appended)', () => {
+			const prev = { text: 'Hello' }
+			const next = { text: 'Goodbye' }
+
+			expect(diffRecord(prev, next)).toEqual({
+				text: [ValueOpType.Put, 'Goodbye'],
+			})
+		})
+
+		it('should use put when string is shortened', () => {
+			const prev = { text: 'Hello world' }
+			const next = { text: 'Hello' }
+
+			expect(diffRecord(prev, next)).toEqual({
+				text: [ValueOpType.Put, 'Hello'],
+			})
+		})
+
+		it('should handle identical strings', () => {
+			const prev = { text: 'Hello' }
+			const next = { text: 'Hello' }
+
+			expect(diffRecord(prev, next)).toBeNull()
+		})
+
+		it('should handle large text append', () => {
+			const prev = { text: 'Start' }
+			const longText = ' '.repeat(1000) + 'end'
+			const next = { text: 'Start' + longText }
+
+			const diff = diffRecord(prev, next)
+			expect(diff).toEqual({
+				text: [ValueOpType.Append, longText, 5],
+			})
+		})
+	})
+
+	describe('string appending in nested props', () => {
+		it('should handle string appending in nested props', () => {
+			const prev = { id: 'test:1', props: { label: 'Hello' } }
+			const next = { id: 'test:1', props: { label: 'Hello world' } }
+
+			expect(diffRecord(prev, next)).toEqual({
+				props: [ValueOpType.Patch, { label: [ValueOpType.Append, ' world', 5] }],
+			})
+		})
+
+		it('should combine string appending with other property changes', () => {
+			const prev = { text: 'Hello', x: 100 }
+			const next = { text: 'Hello world', x: 200 }
+
+			expect(diffRecord(prev, next)).toEqual({
+				text: [ValueOpType.Append, ' world', 5],
+				x: [ValueOpType.Put, 200],
+			})
+		})
+	})
+
+	describe('apply string appending', () => {
+		it('should apply append operations correctly', () => {
+			const obj = { text: 'Hello' }
+			const diff: ObjectDiff = {
+				text: [ValueOpType.Append, ' world', 5],
+			}
+
+			const result = applyObjectDiff(obj, diff)
+			expect(result).toEqual({ text: 'Hello world' })
+			expect(result).not.toBe(obj)
+		})
+
+		it('should handle append from empty string', () => {
+			const obj = { text: '' }
+			const diff: ObjectDiff = {
+				text: [ValueOpType.Append, 'Hello', 0],
+			}
+
+			const result = applyObjectDiff(obj, diff)
+			expect(result).toEqual({ text: 'Hello' })
+		})
+
+		it('should ignore append operation with wrong offset', () => {
+			const obj = { text: 'Hello' }
+			const diff: ObjectDiff = {
+				text: [ValueOpType.Append, ' world', 10], // Wrong offset
+			}
+
+			const result = applyObjectDiff(obj, diff)
+			expect(result).toBe(obj) // No change, same reference
+		})
+
+		it('should ignore append operation on non-string value', () => {
+			const obj = { text: 123 }
+			const diff: ObjectDiff = {
+				text: [ValueOpType.Append, ' world', 3],
+			}
+
+			const result = applyObjectDiff(obj, diff)
+			expect(result).toBe(obj) // No change, same reference
+		})
+
+		it('should handle multiple stream operations', () => {
+			const obj = { a: 'Hello', b: 'Foo' }
+			const diff: ObjectDiff = {
+				a: [ValueOpType.Append, ' world', 5],
+				b: [ValueOpType.Append, 'bar', 3],
+			}
+
+			const result = applyObjectDiff(obj, diff)
+			expect(result).toEqual({ a: 'Hello world', b: 'Foobar' })
+		})
+
+		it('should integrate with network diff workflow', () => {
+			const prev = { id: 'shape:1', type: 'text', text: 'Hello' }
+			const next = { id: 'shape:1', type: 'text', text: 'Hello world' }
+
+			const recordsDiff = {
+				added: {},
+				updated: { 'shape:1': [prev, next] },
+				removed: {},
+			}
+
+			const networkDiff = getNetworkDiff(recordsDiff)
+			expect(networkDiff).toEqual({
+				'shape:1': [RecordOpType.Patch, { text: [ValueOpType.Append, ' world', 5] }],
+			})
+		})
+	})
+})
+
 describe('applyObjectDiff comprehensive', () => {
 	describe('basic operations', () => {
 		it('should create new object when changes are needed', () => {
@@ -582,3 +731,54 @@ describe('complex scenarios', () => {
 		})
 	})
 })
+
+describe('nested key primitive value bug', () => {
+	it('should handle string changes in nested keys', () => {
+		// This tests the bug where nested keys (like 'props') with primitive values
+		// are silently dropped instead of being diffed properly
+		const prev = { id: 'shape:1', props: 'hello' }
+		const next = { id: 'shape:1', props: 'world' }
+
+		const diff = diffRecord(prev, next)
+
+		// The diff should contain a 'put' operation for props
+		expect(diff).toEqual({
+			props: [ValueOpType.Put, 'world'],
+		})
+	})
+
+	it('should handle string appending in nested keys', () => {
+		const prev = { id: 'shape:1', props: 'hello' }
+		const next = { id: 'shape:1', props: 'hello world' }
+
+		const diff = diffRecord(prev, next)
+
+		// The diff should contain an 'append' operation for props
+		expect(diff).toEqual({
+			props: [ValueOpType.Append, ' world', 5],
+		})
+	})
+
+	it('should handle number changes in nested keys', () => {
+		const prev = { id: 'shape:1', props: 42 }
+		const next = { id: 'shape:1', props: 100 }
+
+		const diff = diffRecord(prev, next)
+
+		expect(diff).toEqual({
+			props: [ValueOpType.Put, 100],
+		})
+	})
+
+	it('should still handle object changes in nested keys normally', () => {
+		const prev = { id: 'shape:1', props: { color: 'red' } }
+		const next = { id: 'shape:1', props: { color: 'blue' } }
+
+		const diff = diffRecord(prev, next)
+
+		// Objects in nested keys should still use patch
+		expect(diff).toEqual({
+			props: [ValueOpType.Patch, { color: [ValueOpType.Put, 'blue'] }],
+		})
+	})
+})