Real-time collaboration: Add support for syncing post meta (#72332)

chriszarate · web-flow · commit 599ccf21dbff · 2025-10-27T13:42:37.000-06:00
* Add support for syncing post meta

* Sync all meta by default

* Add test for non-single meta

* Add CRDT persistence meta key to disallowed set
diff --git a/packages/core-data/src/sync.ts b/packages/core-data/src/sync.ts
@@ -6,6 +6,7 @@ import {
 	CRDT_RECORD_MAP_KEY,
 	LOCAL_EDITOR_ORIGIN,
 	LOCAL_SYNC_MANAGER_ORIGIN,
+	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
 	type SyncManager,
 	createSyncManager,
 } from '@wordpress/sync';
@@ -15,6 +16,7 @@ export {
 	CRDT_RECORD_MAP_KEY,
 	LOCAL_EDITOR_ORIGIN,
 	LOCAL_SYNC_MANAGER_ORIGIN,
+	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
 };
 
 let syncManager: SyncManager;
diff --git a/packages/core-data/src/utils/crdt.ts b/packages/core-data/src/utils/crdt.ts
@@ -21,7 +21,11 @@ import {
 } from './crdt-blocks';
 import { type Post } from '../entity-types/post';
 import { type Type } from '../entity-types';
-import { CRDT_DOC_META_PERSISTENCE_KEY, CRDT_RECORD_MAP_KEY } from '../sync';
+import {
+	CRDT_DOC_META_PERSISTENCE_KEY,
+	CRDT_RECORD_MAP_KEY,
+	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
+} from '../sync';
 import type { WPBlockSelection, WPSelection } from '../types';
 
 export type PostChanges = Partial< Post > & {
@@ -44,6 +48,7 @@ const allowedPostProperties = new Set< string >( [
 	'featured_media',
 	'format',
 	'ping_status',
+	'meta',
 	'slug',
 	'status',
 	'sticky',
@@ -52,6 +57,11 @@ const allowedPostProperties = new Set< string >( [
 	'title',
 ] );
 
+// Post meta keys that should *not* be synced.
+const disallowedPostMetaKeys = new Set< string >( [
+	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
+] );
+
 /**
  * Given a set of local changes to a generic entity record, apply those changes
  * to the local Y.Doc.
@@ -94,13 +104,13 @@ export function defaultApplyChangesToCRDTDoc(
  *
  * @param {CRDTDoc}     ydoc
  * @param {PostChanges} changes
- * @param {Type}        postType
+ * @param {Type}        _postType
  * @return {void}
  */
 export function applyPostChangesToCRDTDoc(
 	ydoc: CRDTDoc,
 	changes: PostChanges,
-	postType: Type // eslint-disable-line @typescript-eslint/no-unused-vars
+	_postType: Type // eslint-disable-line @typescript-eslint/no-unused-vars
 ): void {
 	const ymap = ydoc.getMap( CRDT_RECORD_MAP_KEY );
 
@@ -148,6 +158,36 @@ export function applyPostChangesToCRDTDoc(
 				break;
 			}
 
+			// "Meta" is overloaded term; here, it refers to post meta.
+			case 'meta': {
+				let metaMap = ymap.get( 'meta' ) as Y.Map< unknown >;
+
+				// Initialize.
+				if ( ! ( metaMap instanceof Y.Map ) ) {
+					metaMap = new Y.Map();
+					setValue( metaMap );
+				}
+
+				// Iterate over each meta property in the new value and merge it if it
+				// should be synced.
+				Object.entries( newValue ?? {} ).forEach(
+					( [ metaKey, metaValue ] ) => {
+						if ( disallowedPostMetaKeys.has( metaKey ) ) {
+							return;
+						}
+
+						mergeValue(
+							metaMap.get( metaKey ), // current value in CRDT
+							metaValue, // new value from changes
+							( updatedMetaValue: unknown ): void => {
+								metaMap.set( metaKey, updatedMetaValue );
+							}
+						);
+					}
+				);
+				break;
+			}
+
 			case 'slug': {
 				// Do not sync an empty slug. This indicates that the post is using
 				// the default auto-generated slug.
@@ -200,17 +240,19 @@ export function defaultGetChangesFromCRDTDoc( crdtDoc: CRDTDoc ): ObjectData {
  *
  * @param {CRDTDoc} ydoc
  * @param {Post}    editedRecord
- * @param {Type}    postType
+ * @param {Type}    _postType
  * @return {Partial<PostChanges>} The changes that should be applied to the local record.
  */
 export function getPostChangesFromCRDTDoc(
 	ydoc: CRDTDoc,
 	editedRecord: Post,
-	postType: Type // eslint-disable-line @typescript-eslint/no-unused-vars
+	_postType: Type // eslint-disable-line @typescript-eslint/no-unused-vars
 ): PostChanges {
 	const ymap = ydoc.getMap( CRDT_RECORD_MAP_KEY );
 
-	return Object.fromEntries(
+	let allowedMetaChanges: Post[ 'meta' ] = {};
+
+	const changes = Object.fromEntries(
 		Object.entries( ymap.toJSON() ).filter( ( [ key, newValue ] ) => {
 			if ( ! allowedPostProperties.has( key ) ) {
 				return false;
@@ -271,6 +313,24 @@ export function getPostChangesFromCRDTDoc(
 					return haveValuesChanged( currentValue, newValue );
 				}
 
+				case 'meta': {
+					allowedMetaChanges = Object.fromEntries(
+						Object.entries( newValue ?? {} ).filter(
+							( [ metaKey ] ) =>
+								! disallowedPostMetaKeys.has( metaKey )
+						)
+					);
+
+					// Merge the allowed meta changes with the current meta values since
+					// not all meta properties are synced.
+					const mergedValue = {
+						...( currentValue as PostChanges[ 'meta' ] ),
+						...allowedMetaChanges,
+					};
+
+					return haveValuesChanged( currentValue, mergedValue );
+				}
+
 				case 'status': {
 					// Do not sync an invalid status.
 					if ( 'auto-draft' === newValue ) {
@@ -296,6 +356,17 @@ export function getPostChangesFromCRDTDoc(
 			}
 		} )
 	);
+
+	// Meta changes must be merged with the edited record since not all meta
+	// properties are synced.
+	if ( 'object' === typeof changes.meta ) {
+		changes.meta = {
+			...editedRecord.meta,
+			...allowedMetaChanges,
+		};
+	}
+
+	return changes;
 }
 
 /**
diff --git a/packages/core-data/src/utils/test/crdt.ts b/packages/core-data/src/utils/test/crdt.ts
@@ -1,7 +1,11 @@
 /**
  * WordPress dependencies
  */
-import { CRDT_RECORD_MAP_KEY, Y } from '@wordpress/sync';
+import {
+	CRDT_RECORD_MAP_KEY,
+	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
+	Y,
+} from '@wordpress/sync';
 
 /**
  * External dependencies
@@ -152,6 +156,55 @@ describe( 'crdt', () => {
 			const blocks = map.get( 'blocks' );
 			expect( blocks ).toBeInstanceOf( Y.Array );
 		} );
+
+		it( 'syncs meta fields', () => {
+			const changes = {
+				meta: {
+					some_meta: 'new value',
+				},
+			};
+
+			const metaMap = new Y.Map< unknown >();
+			metaMap.set( 'some_meta', 'old value' );
+			map.set( 'meta', metaMap );
+
+			applyPostChangesToCRDTDoc( doc, changes, mockPostType );
+
+			expect( metaMap.get( 'some_meta' ) ).toBe( 'new value' );
+		} );
+
+		it( 'syncs non-single meta fields', () => {
+			const changes = {
+				meta: {
+					some_meta: [ 'value', 'value 2' ],
+				},
+			};
+
+			const metaMap = new Y.Map< unknown >();
+			metaMap.set( 'some_meta', 'old value' );
+			map.set( 'meta', metaMap );
+
+			applyPostChangesToCRDTDoc( doc, changes, mockPostType );
+
+			expect( metaMap.get( 'some_meta' ) ).toStrictEqual( [
+				'value',
+				'value 2',
+			] );
+		} );
+
+		it( 'initializes meta as Y.Map when not present', () => {
+			const changes = {
+				meta: {
+					custom_field: 'value',
+				},
+			};
+
+			applyPostChangesToCRDTDoc( doc, changes, mockPostType );
+
+			const metaMap = map.get( 'meta' ) as Y.Map< unknown >;
+			expect( metaMap ).toBeInstanceOf( Y.Map );
+			expect( metaMap.get( 'custom_field' ) ).toBe( 'value' );
+		} );
 	} );
 
 	describe( 'getPostChangesFromCRDTDoc', () => {
@@ -250,5 +303,75 @@ describe( 'crdt', () => {
 
 			expect( changes ).toHaveProperty( 'blocks' );
 		} );
+
+		it( 'includes meta in changes', () => {
+			map.set( 'meta', {
+				public_meta: 'new value',
+			} );
+
+			const editedRecord = {
+				meta: {
+					public_meta: 'old value',
+				},
+			} as unknown as Post;
+
+			const changes = getPostChangesFromCRDTDoc(
+				doc,
+				editedRecord,
+				mockPostType
+			);
+
+			expect( changes.meta ).toEqual( {
+				public_meta: 'new value', // from CRDT
+			} );
+		} );
+
+		it( 'includes non-single meta in changes', () => {
+			map.set( 'meta', {
+				public_meta: [ 'value', 'value 2' ],
+			} );
+
+			const editedRecord = {
+				meta: {
+					public_meta: 'value',
+				},
+			} as unknown as Post;
+
+			const changes = getPostChangesFromCRDTDoc(
+				doc,
+				editedRecord,
+				mockPostType
+			);
+
+			expect( changes.meta ).toEqual( {
+				public_meta: [ 'value', 'value 2' ], // from CRDT
+			} );
+		} );
+
+		it( 'excludes disallowed meta keys in changes', () => {
+			map.set( 'meta', {
+				public_meta: 'new value',
+				[ WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE ]: 'exclude me',
+			} );
+
+			const editedRecord = {
+				meta: {
+					public_meta: 'old value',
+				},
+			} as unknown as Post;
+
+			const changes = getPostChangesFromCRDTDoc(
+				doc,
+				editedRecord,
+				mockPostType
+			);
+
+			expect( changes.meta ).toEqual( {
+				public_meta: 'new value', // from CRDT
+			} );
+			expect( changes.meta ).not.toHaveProperty(
+				WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE
+			);
+		} );
 	} );
 } );
diff --git a/packages/sync/README.md b/packages/sync/README.md
@@ -34,6 +34,10 @@ Origin string for CRDT document changes originating from the local editor.
 
 Origin string for CRDT document changes originating from the sync manager.
 
+### WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE
+
+WordPress meta key used to persist the CRDT document for an entity.
+
 ### Y
 
 Exported copy of Yjs so that consumers of this package don't need to install it.
diff --git a/packages/sync/src/index.ts b/packages/sync/src/index.ts
@@ -16,6 +16,7 @@ export {
 	CRDT_RECORD_MAP_KEY,
 	LOCAL_EDITOR_ORIGIN,
 	LOCAL_SYNC_MANAGER_ORIGIN,
+	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
 } from './config';
 export { createSyncManager } from './manager';
 export type * from './types';
