@tldraw/sync-core 4.2.0-next.bfd9ab728a80 → 4.2.0-next.bff7e3992d58

package/dist-esm/lib/protocol.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/protocol.ts"],
-  "sourcesContent": ["import { SerializedSchema, UnknownRecord } from '@tldraw/store'\nimport { NetworkDiff, ObjectDiff, RecordOpType } from './diff'\n\nconst TLSYNC_PROTOCOL_VERSION = 7\n\n/**\n * Gets the current tldraw sync protocol version number.\n *\n * This version number is used during WebSocket connection handshake to ensure\n * client and server compatibility. When versions don't match, the connection\n * will be rejected with an incompatibility error.\n *\n * @returns The current protocol version number\n *\n * @example\n * ```ts\n * const version = getTlsyncProtocolVersion()\n * console.log(`Using protocol version: ${version}`)\n * ```\n *\n * @internal\n */\nexport function getTlsyncProtocolVersion() {\n\treturn TLSYNC_PROTOCOL_VERSION\n}\n\n/**\n * Constants defining the different types of protocol incompatibility reasons.\n *\n * These values indicate why a client-server connection was rejected due to\n * version or compatibility issues. Each reason helps diagnose specific problems\n * during the connection handshake.\n *\n * @example\n * ```ts\n * if (error.reason === TLIncompatibilityReason.ClientTooOld) {\n *   showUpgradeMessage('Please update your client')\n * }\n * ```\n *\n * @internal\n * @deprecated Replaced by websocket .close status/reason\n */\nexport const TLIncompatibilityReason = {\n\tClientTooOld: 'clientTooOld',\n\tServerTooOld: 'serverTooOld',\n\tInvalidRecord: 'invalidRecord',\n\tInvalidOperation: 'invalidOperation',\n} as const\n\n/**\n * Union type representing all possible incompatibility reason values.\n *\n * This type represents the different reasons why a client-server connection\n * might fail due to protocol or version mismatches.\n *\n * @example\n * ```ts\n * function handleIncompatibility(reason: TLIncompatibilityReason) {\n *   switch (reason) {\n *     case 'clientTooOld':\n *       return 'Client needs to be updated'\n *     case 'serverTooOld':\n *       return 'Server needs to be updated'\n *   }\n * }\n * ```\n *\n * @internal\n * @deprecated replaced by websocket .close status/reason\n */\nexport type TLIncompatibilityReason =\n\t(typeof TLIncompatibilityReason)[keyof typeof TLIncompatibilityReason]\n\n/**\n * Union type representing all possible message types that can be sent from server to client.\n *\n * This encompasses the complete set of server-originated WebSocket messages in the tldraw\n * sync protocol, including connection establishment, data synchronization, and error handling.\n *\n * @param R - The record type being synchronized (extends UnknownRecord)\n *\n * @example\n * ```ts\n * syncClient.onReceiveMessage((message: TLSocketServerSentEvent<MyRecord>) => {\n *   switch (message.type) {\n *     case 'connect':\n *       console.log('Connected to room with clock:', message.serverClock)\n *       break\n *     case 'data':\n *       console.log('Received data updates:', message.data)\n *       break\n *   }\n * })\n * ```\n *\n * @internal\n */\nexport type TLSocketServerSentEvent<R extends UnknownRecord> =\n\t| {\n\t\t\ttype: 'connect'\n\t\t\thydrationType: 'wipe_all' | 'wipe_presence'\n\t\t\tconnectRequestId: string\n\t\t\tprotocolVersion: number\n\t\t\tschema: SerializedSchema\n\t\t\tdiff: NetworkDiff<R>\n\t\t\tserverClock: number\n\t\t\tisReadonly: boolean\n\t  }\n\t| {\n\t\t\ttype: 'incompatibility_error'\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-deprecated\n\t\t\treason: TLIncompatibilityReason\n\t  }\n\t| {\n\t\t\ttype: 'pong'\n\t  }\n\t| { type: 'data'; data: TLSocketServerSentDataEvent<R>[] }\n\t| { type: 'custom'; data: any }\n\t| TLSocketServerSentDataEvent<R>\n\n/**\n * Union type representing data-related messages sent from server to client.\n *\n * These messages handle the core synchronization operations: applying patches from\n * other clients and confirming the results of client push operations.\n *\n * @param R - The record type being synchronized (extends UnknownRecord)\n *\n * @example\n * ```ts\n * function handleDataEvent(event: TLSocketServerSentDataEvent<MyRecord>) {\n *   if (event.type === 'patch') {\n *     // Apply changes from other clients\n *     applyNetworkDiff(event.diff)\n *   } else if (event.type === 'push_result') {\n *     // Handle result of our push request\n *     if (event.action === 'commit') {\n *       console.log('Changes accepted by server')\n *     }\n *   }\n * }\n * ```\n *\n * @internal\n */\nexport type TLSocketServerSentDataEvent<R extends UnknownRecord> =\n\t| {\n\t\t\ttype: 'patch'\n\t\t\tdiff: NetworkDiff<R>\n\t\t\tserverClock: number\n\t  }\n\t| {\n\t\t\ttype: 'push_result'\n\t\t\tclientClock: number\n\t\t\tserverClock: number\n\t\t\taction: 'discard' | 'commit' | { rebaseWithDiff: NetworkDiff<R> }\n\t  }\n\n/**\n * Interface defining a client-to-server push request message.\n *\n * Push requests are sent when the client wants to synchronize local changes\n * with the server. They contain document changes and optionally presence updates\n * (like cursor position or user selection).\n *\n * @param R - The record type being synchronized (extends UnknownRecord)\n *\n * @example\n * ```ts\n * const pushRequest: TLPushRequest<MyRecord> = {\n *   type: 'push',\n *   clientClock: 15,\n *   diff: {\n *     'shape:abc123': [RecordOpType.Patch, { x: [ValueOpType.Put, 100] }]\n *   },\n *   presence: [RecordOpType.Put, { cursor: { x: 150, y: 200 } }]\n * }\n * socket.sendMessage(pushRequest)\n * ```\n *\n * @internal\n */\nexport interface TLPushRequest<R extends UnknownRecord> {\n\ttype: 'push'\n\tclientClock: number\n\tdiff?: NetworkDiff<R>\n\tpresence?: [typeof RecordOpType.Patch, ObjectDiff] | [typeof RecordOpType.Put, R]\n}\n\n/**\n * Interface defining a client-to-server connection request message.\n *\n * This message initiates a WebSocket connection to a sync room. It includes\n * the client's schema, protocol version, and last known server clock for\n * proper synchronization state management.\n *\n * @example\n * ```ts\n * const connectRequest: TLConnectRequest = {\n *   type: 'connect',\n *   connectRequestId: 'conn-123',\n *   lastServerClock: 42,\n *   protocolVersion: getTlsyncProtocolVersion(),\n *   schema: mySchema.serialize()\n * }\n * socket.sendMessage(connectRequest)\n * ```\n *\n * @internal\n */\nexport interface TLConnectRequest {\n\ttype: 'connect'\n\tconnectRequestId: string\n\tlastServerClock: number\n\tprotocolVersion: number\n\tschema: SerializedSchema\n}\n\n/**\n * Interface defining a client-to-server ping request message.\n *\n * Ping requests are used to measure network latency and ensure the connection\n * is still active. The server responds with a 'pong' message.\n *\n * @example\n * ```ts\n * const pingRequest: TLPingRequest = { type: 'ping' }\n * socket.sendMessage(pingRequest)\n *\n * // Server will respond with { type: 'pong' }\n * ```\n *\n * @internal\n */\nexport interface TLPingRequest {\n\ttype: 'ping'\n}\n\n/**\n * Union type representing all possible message types that can be sent from client to server.\n *\n * This encompasses the complete set of client-originated WebSocket messages in the tldraw\n * sync protocol, covering connection establishment, data synchronization, and connectivity checks.\n *\n * @param R - The record type being synchronized (extends UnknownRecord)\n *\n * @example\n * ```ts\n * function sendMessage(message: TLSocketClientSentEvent<MyRecord>) {\n *   switch (message.type) {\n *     case 'connect':\n *       console.log('Establishing connection...')\n *       break\n *     case 'push':\n *       console.log('Pushing changes:', message.diff)\n *       break\n *     case 'ping':\n *       console.log('Checking connection latency')\n *       break\n *   }\n *   socket.send(JSON.stringify(message))\n * }\n * ```\n *\n * @internal\n */\nexport type TLSocketClientSentEvent<R extends UnknownRecord> =\n\t| TLPushRequest<R>\n\t| TLConnectRequest\n\t| TLPingRequest\n"],
+  "sourcesContent": ["import { SerializedSchema, UnknownRecord } from '@tldraw/store'\nimport { NetworkDiff, ObjectDiff, RecordOpType } from './diff'\n\nconst TLSYNC_PROTOCOL_VERSION = 8\n\n/**\n * Gets the current tldraw sync protocol version number.\n *\n * This version number is used during WebSocket connection handshake to ensure\n * client and server compatibility. When versions don't match, the connection\n * will be rejected with an incompatibility error.\n *\n * @returns The current protocol version number\n *\n * @example\n * ```ts\n * const version = getTlsyncProtocolVersion()\n * console.log(`Using protocol version: ${version}`)\n * ```\n *\n * @internal\n */\nexport function getTlsyncProtocolVersion() {\n\treturn TLSYNC_PROTOCOL_VERSION\n}\n\n/**\n * Constants defining the different types of protocol incompatibility reasons.\n *\n * These values indicate why a client-server connection was rejected due to\n * version or compatibility issues. Each reason helps diagnose specific problems\n * during the connection handshake.\n *\n * @example\n * ```ts\n * if (error.reason === TLIncompatibilityReason.ClientTooOld) {\n *   showUpgradeMessage('Please update your client')\n * }\n * ```\n *\n * @internal\n * @deprecated Replaced by websocket .close status/reason\n */\nexport const TLIncompatibilityReason = {\n\tClientTooOld: 'clientTooOld',\n\tServerTooOld: 'serverTooOld',\n\tInvalidRecord: 'invalidRecord',\n\tInvalidOperation: 'invalidOperation',\n} as const\n\n/**\n * Union type representing all possible incompatibility reason values.\n *\n * This type represents the different reasons why a client-server connection\n * might fail due to protocol or version mismatches.\n *\n * @example\n * ```ts\n * function handleIncompatibility(reason: TLIncompatibilityReason) {\n *   switch (reason) {\n *     case 'clientTooOld':\n *       return 'Client needs to be updated'\n *     case 'serverTooOld':\n *       return 'Server needs to be updated'\n *   }\n * }\n * ```\n *\n * @internal\n * @deprecated replaced by websocket .close status/reason\n */\nexport type TLIncompatibilityReason =\n\t(typeof TLIncompatibilityReason)[keyof typeof TLIncompatibilityReason]\n\n/**\n * Union type representing all possible message types that can be sent from server to client.\n *\n * This encompasses the complete set of server-originated WebSocket messages in the tldraw\n * sync protocol, including connection establishment, data synchronization, and error handling.\n *\n * @param R - The record type being synchronized (extends UnknownRecord)\n *\n * @example\n * ```ts\n * syncClient.onReceiveMessage((message: TLSocketServerSentEvent<MyRecord>) => {\n *   switch (message.type) {\n *     case 'connect':\n *       console.log('Connected to room with clock:', message.serverClock)\n *       break\n *     case 'data':\n *       console.log('Received data updates:', message.data)\n *       break\n *   }\n * })\n * ```\n *\n * @internal\n */\nexport type TLSocketServerSentEvent<R extends UnknownRecord> =\n\t| {\n\t\t\ttype: 'connect'\n\t\t\thydrationType: 'wipe_all' | 'wipe_presence'\n\t\t\tconnectRequestId: string\n\t\t\tprotocolVersion: number\n\t\t\tschema: SerializedSchema\n\t\t\tdiff: NetworkDiff<R>\n\t\t\tserverClock: number\n\t\t\tisReadonly: boolean\n\t  }\n\t| {\n\t\t\ttype: 'incompatibility_error'\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-deprecated\n\t\t\treason: TLIncompatibilityReason\n\t  }\n\t| {\n\t\t\ttype: 'pong'\n\t  }\n\t| { type: 'data'; data: TLSocketServerSentDataEvent<R>[] }\n\t| { type: 'custom'; data: any }\n\t| TLSocketServerSentDataEvent<R>\n\n/**\n * Union type representing data-related messages sent from server to client.\n *\n * These messages handle the core synchronization operations: applying patches from\n * other clients and confirming the results of client push operations.\n *\n * @param R - The record type being synchronized (extends UnknownRecord)\n *\n * @example\n * ```ts\n * function handleDataEvent(event: TLSocketServerSentDataEvent<MyRecord>) {\n *   if (event.type === 'patch') {\n *     // Apply changes from other clients\n *     applyNetworkDiff(event.diff)\n *   } else if (event.type === 'push_result') {\n *     // Handle result of our push request\n *     if (event.action === 'commit') {\n *       console.log('Changes accepted by server')\n *     }\n *   }\n * }\n * ```\n *\n * @internal\n */\nexport type TLSocketServerSentDataEvent<R extends UnknownRecord> =\n\t| {\n\t\t\ttype: 'patch'\n\t\t\tdiff: NetworkDiff<R>\n\t\t\tserverClock: number\n\t  }\n\t| {\n\t\t\ttype: 'push_result'\n\t\t\tclientClock: number\n\t\t\tserverClock: number\n\t\t\taction: 'discard' | 'commit' | { rebaseWithDiff: NetworkDiff<R> }\n\t  }\n\n/**\n * Interface defining a client-to-server push request message.\n *\n * Push requests are sent when the client wants to synchronize local changes\n * with the server. They contain document changes and optionally presence updates\n * (like cursor position or user selection).\n *\n * @param R - The record type being synchronized (extends UnknownRecord)\n *\n * @example\n * ```ts\n * const pushRequest: TLPushRequest<MyRecord> = {\n *   type: 'push',\n *   clientClock: 15,\n *   diff: {\n *     'shape:abc123': [RecordOpType.Patch, { x: [ValueOpType.Put, 100] }]\n *   },\n *   presence: [RecordOpType.Put, { cursor: { x: 150, y: 200 } }]\n * }\n * socket.sendMessage(pushRequest)\n * ```\n *\n * @internal\n */\nexport interface TLPushRequest<R extends UnknownRecord> {\n\ttype: 'push'\n\tclientClock: number\n\tdiff?: NetworkDiff<R>\n\tpresence?: [typeof RecordOpType.Patch, ObjectDiff] | [typeof RecordOpType.Put, R]\n}\n\n/**\n * Interface defining a client-to-server connection request message.\n *\n * This message initiates a WebSocket connection to a sync room. It includes\n * the client's schema, protocol version, and last known server clock for\n * proper synchronization state management.\n *\n * @example\n * ```ts\n * const connectRequest: TLConnectRequest = {\n *   type: 'connect',\n *   connectRequestId: 'conn-123',\n *   lastServerClock: 42,\n *   protocolVersion: getTlsyncProtocolVersion(),\n *   schema: mySchema.serialize()\n * }\n * socket.sendMessage(connectRequest)\n * ```\n *\n * @internal\n */\nexport interface TLConnectRequest {\n\ttype: 'connect'\n\tconnectRequestId: string\n\tlastServerClock: number\n\tprotocolVersion: number\n\tschema: SerializedSchema\n}\n\n/**\n * Interface defining a client-to-server ping request message.\n *\n * Ping requests are used to measure network latency and ensure the connection\n * is still active. The server responds with a 'pong' message.\n *\n * @example\n * ```ts\n * const pingRequest: TLPingRequest = { type: 'ping' }\n * socket.sendMessage(pingRequest)\n *\n * // Server will respond with { type: 'pong' }\n * ```\n *\n * @internal\n */\nexport interface TLPingRequest {\n\ttype: 'ping'\n}\n\n/**\n * Union type representing all possible message types that can be sent from client to server.\n *\n * This encompasses the complete set of client-originated WebSocket messages in the tldraw\n * sync protocol, covering connection establishment, data synchronization, and connectivity checks.\n *\n * @param R - The record type being synchronized (extends UnknownRecord)\n *\n * @example\n * ```ts\n * function sendMessage(message: TLSocketClientSentEvent<MyRecord>) {\n *   switch (message.type) {\n *     case 'connect':\n *       console.log('Establishing connection...')\n *       break\n *     case 'push':\n *       console.log('Pushing changes:', message.diff)\n *       break\n *     case 'ping':\n *       console.log('Checking connection latency')\n *       break\n *   }\n *   socket.send(JSON.stringify(message))\n * }\n * ```\n *\n * @internal\n */\nexport type TLSocketClientSentEvent<R extends UnknownRecord> =\n\t| TLPushRequest<R>\n\t| TLConnectRequest\n\t| TLPingRequest\n"],
   "mappings": "AAGA,MAAM,0BAA0B;AAmBzB,SAAS,2BAA2B;AAC1C,SAAO;AACR;AAmBO,MAAM,0BAA0B;AAAA,EACtC,cAAc;AAAA,EACd,cAAc;AAAA,EACd,eAAe;AAAA,EACf,kBAAkB;AACnB;",
   "names": []
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tldraw/sync-core",
   "description": "tldraw infinite canvas SDK (multiplayer sync).",
-  "version": "4.2.0-next.bfd9ab728a80",
+  "version": "4.2.0-next.bff7e3992d58",
   "author": {
     "name": "tldraw GB Ltd.",
     "email": "hello@tldraw.com"
@@ -48,17 +48,17 @@
     "@types/uuid-readable": "^0.0.3",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "tldraw": "4.2.0-next.bfd9ab728a80",
+    "tldraw": "4.2.0-next.bff7e3992d58",
     "typescript": "^5.8.3",
     "uuid-by-string": "^4.0.0",
     "uuid-readable": "^0.0.2",
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@tldraw/state": "4.2.0-next.bfd9ab728a80",
-    "@tldraw/store": "4.2.0-next.bfd9ab728a80",
-    "@tldraw/tlschema": "4.2.0-next.bfd9ab728a80",
-    "@tldraw/utils": "4.2.0-next.bfd9ab728a80",
+    "@tldraw/state": "4.2.0-next.bff7e3992d58",
+    "@tldraw/store": "4.2.0-next.bff7e3992d58",
+    "@tldraw/tlschema": "4.2.0-next.bff7e3992d58",
+    "@tldraw/utils": "4.2.0-next.bff7e3992d58",
     "nanoevents": "^7.0.1",
     "ws": "^8.18.0"
   },

package/src/index.ts

@@ -26,7 +26,7 @@ export {
 	type TLSocketServerSentDataEvent,
 	type TLSocketServerSentEvent,
 } from './lib/protocol'
-export { RoomSessionState, type RoomSession } from './lib/RoomSession'
+export { RoomSessionState, type RoomSession, type RoomSessionBase } from './lib/RoomSession'
 export type { PersistedRoomSnapshotForSupabase } from './lib/server-types'
 export type { WebSocketMinimal } from './lib/ServerSocketAdapter'
 export { TLRemoteSyncError } from './lib/TLRemoteSyncError'

package/src/lib/RoomSession.test.ts

@@ -54,6 +54,7 @@ describe('RoomSession state transitions', () => {
 		const initialSession: RoomSession<TLRecord, { userId: string }> = {
 			state: RoomSessionState.AwaitingConnectMessage,
 			sessionStartTime: Date.now(),
+			supportsStringAppend: true,
 			...baseSessionData,
 		}
 
@@ -67,6 +68,7 @@ describe('RoomSession state transitions', () => {
 			isReadonly: initialSession.isReadonly,
 			requiresLegacyRejection: initialSession.requiresLegacyRejection,
 			serializedSchema: mockSerializedSchema,
+			supportsStringAppend: true,
 			lastInteractionTime: Date.now(),
 			debounceTimer: null,
 			outstandingDataMessages: [],
@@ -81,6 +83,7 @@ describe('RoomSession state transitions', () => {
 			meta: connectedSession.meta,
 			isReadonly: connectedSession.isReadonly,
 			requiresLegacyRejection: connectedSession.requiresLegacyRejection,
+			supportsStringAppend: connectedSession.supportsStringAppend,
 			cancellationTime: Date.now(),
 		}
 

package/src/lib/RoomSession.ts

@@ -64,6 +64,28 @@ export const SESSION_REMOVAL_WAIT_TIME = 5000
  */
 export const SESSION_IDLE_TIMEOUT = 20000
 
+/**
+ * Base properties shared by all room session states.
+ *
+ * @internal
+ */
+export interface RoomSessionBase<R extends UnknownRecord, Meta> {
+	/** Unique identifier for this session */
+	sessionId: string
+	/** Presence identifier for live cursor/selection tracking, if available */
+	presenceId: string | null
+	/** WebSocket connection wrapper for this session */
+	socket: TLRoomSocket<R>
+	/** Custom metadata associated with this session */
+	meta: Meta
+	/** Whether this session has read-only permissions */
+	isReadonly: boolean
+	/** Whether this session requires legacy protocol rejection handling */
+	requiresLegacyRejection: boolean
+	/** Whether this session supports string append operations */
+	supportsStringAppend: boolean
+}
+
 /**
  * Represents a client session within a collaborative room, tracking the connection
  * state, permissions, and synchronization details for a single user.
@@ -93,51 +115,21 @@ export const SESSION_IDLE_TIMEOUT = 20000
  * @internal
  */
 export type RoomSession<R extends UnknownRecord, Meta> =
-	| {
+	| (RoomSessionBase<R, Meta> & {
 			/** Current state of the session */
 			state: typeof RoomSessionState.AwaitingConnectMessage
-			/** Unique identifier for this session */
-			sessionId: string
-			/** Presence identifier for live cursor/selection tracking, if available */
-			presenceId: string | null
-			/** WebSocket connection wrapper for this session */
-			socket: TLRoomSocket<R>
 			/** Timestamp when the session was created */
 			sessionStartTime: number
-			/** Custom metadata associated with this session */
-			meta: Meta
-			/** Whether this session has read-only permissions */
-			isReadonly: boolean
-			/** Whether this session requires legacy protocol rejection handling */
-			requiresLegacyRejection: boolean
-	  }
-	| {
+	  })
+	| (RoomSessionBase<R, Meta> & {
 			/** Current state of the session */
 			state: typeof RoomSessionState.AwaitingRemoval
-			/** Unique identifier for this session */
-			sessionId: string
-			/** Presence identifier for live cursor/selection tracking, if available */
-			presenceId: string | null
-			/** WebSocket connection wrapper for this session */
-			socket: TLRoomSocket<R>
 			/** Timestamp when the session was marked for removal */
 			cancellationTime: number
-			/** Custom metadata associated with this session */
-			meta: Meta
-			/** Whether this session has read-only permissions */
-			isReadonly: boolean
-			/** Whether this session requires legacy protocol rejection handling */
-			requiresLegacyRejection: boolean
-	  }
-	| {
+	  })
+	| (RoomSessionBase<R, Meta> & {
 			/** Current state of the session */
 			state: typeof RoomSessionState.Connected
-			/** Unique identifier for this session */
-			sessionId: string
-			/** Presence identifier for live cursor/selection tracking, if available */
-			presenceId: string | null
-			/** WebSocket connection wrapper for this session */
-			socket: TLRoomSocket<R>
 			/** Serialized schema information for this connected session */
 			serializedSchema: SerializedSchema
 			/** Timestamp of the last interaction or message from this session */
@@ -146,10 +138,4 @@ export type RoomSession<R extends UnknownRecord, Meta> =
 			debounceTimer: ReturnType<typeof setTimeout> | null
 			/** Queue of data messages waiting to be sent to this session */
 			outstandingDataMessages: TLSocketServerSentDataEvent<R>[]
-			/** Custom metadata associated with this session */
-			meta: Meta
-			/** Whether this session has read-only permissions */
-			isReadonly: boolean
-			/** Whether this session requires legacy protocol rejection handling */
-			requiresLegacyRejection: boolean
-	  }
+	  })

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/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)
 	})