[alecgeatches]

What?

Closes #81736.

Follow-up to Y exposure changes in #82621. Sync transport providers registered via the sync.providers filter now receive the Yjs module as a Y option instead of using the global wp.sync.Y.

Stops exposing @wordpress/sync as a WordPress script, which is already the case in the 7.0 and 7.1 WordPress core releases. The wp-sync script handle and the wp.sync global are no longer registered. The package is bundled into its only consumer, @wordpress/core-data, instead.

Why?

Real-time collaboration was removed from the WordPress 7.0 release. As part of that, wp.sync had to be removed from each release branch with a patch (#78085 for wp/7.0, #81683 for wp/7.1). Because trunk was never changed, this workaround will keep needing to be reapplied until it's fixed here.

How?

Remove "wpScript": true from the sync package so it is bundled into @wordpress/core-data instead of being exposed as wp.sync. @wordpress/sync was also added to BUNDLED_PACKAGES so consumer builds bundle their own copy.

Since bundled packages can't use private APIs, the sync internals that core-data needs are now regular exports, and the package no longer depends on @wordpress/private-apis. @wordpress/sync stays in the private-apis allow list, with a comment, because older published copies still call call into those APIs.

Breaking changes

Any external Yjs transport will need to update code to continue working. For example, vip-real-time-collaboration still requires wp-sync and relies on the Y instance exposed from wp.sync. Before this is merged, we should provide adequate time to allow transports to implement the new API.

Here is the VIP transport implementation, which is backwards-compatible: Automattic/vip-real-time-collaboration#226

Testing Instructions

1. npm install && npm run build

2. Load the post editor and confirm window.wp.sync is undefined in the browser console.

3. Enable the "Real-time collaboration" experiment, open the same post in two browser windows, and confirm collaboration still works over the default HTTP polling transport: typing syncs both ways, undo and redo behave, and peer presence is shown.

4. To exercise a third-party WebSocket transport (the pattern that previously required wp.sync), run npm run rtc:ws and confirm collaboration continues to work in a multi-user session:

   websockets-no-global.mov

Use of AI Tools

Claude Code (Fable 5).

[github-actions]

Size Change: -1.26 kB (-0.02%)

Total Size: 7.92 MB

📦 View Changed

Filename	Size	Change
build/scripts/core-data/index.min.js	78.5 kB	+41 kB (+109.64%)	🆘
build/scripts/sync/index.min.js	0 B	-42.3 kB (removed)	🏆

_{compressed-size-action}

[t-hamano]

Thanks for the PR!

I'm not very familiar with this package, but do we also need to update BUNDLED_PACKAGES? Otherwise, @wordpress/sync will be externalized when consumers build plugins/themes for WordPress with @wordpress/scripts.

Before this is merged, we should provide adequate time to allow transports to implement the new API.

What specifically should we do?

[alecgeatches]

do we also need to update BUNDLED_PACKAGES?

Good catch! I've added @wordpress/sync to BUNDLED_PACKAGES so consumer builds bundle their own copy instead. Note that with this PR, sync transport providers should no longer need to import @wordpress/sync at all. They receive the editor's ydoc, awareness, and Y module through the provider options.

Before this is merged, we should provide adequate time to allow transports to implement the new API.

What specifically should we do?

Pretty much what's happening in Automattic/vip-real-time-collaboration#226. There's still some discussion, but assuming this implementation passes muster we'd want to reach out to other RTC implementors and ask them to apply a similar backwards-compatible solution. If we were to merge this PR in Gutenberg before RTC transports are ready, then implementors that use Yjs internally e.g. y-websocket-server would end up importing two copies of Yjs which causes issues. I think we can reach out to relevant folks in Automattic for Dotcom's implementation and in #feature-realtime-collaboration for other folks.

The plan would be to merge a fix on any existing RTC providers, then merge this PR. We could alternatively just introduce the new Y option, and then later come back and remove the wp.sync package, but I don't think we have a lot of providers to wait for. Plus, this only applies to Gutenberg plugin users with the RTC experiment enabled. I'm open to a two-step option (deprecation + remove wp.sync package later) if it's preferred.

[github-actions]

Flaky tests detected in 0dbb84f.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/32868960692
📝 Reported tests:

should be disabled when post is being saved in /test/e2e/specs/editor/various/publish-button.spec.js, passed after 1 failed attempt.

Error: expect(locator).toBeDisabled() failed

Locator:  getByRole('region', { name: 'Editor top bar' }).getByRole('button', { name: 'Publish' })
Expected: disabled
Received: enabled
Timeout:  5000ms

Call log:
  - Expect "toBeDisabled" with timeout 5000ms
  - waiting for getByRole('region', { name: 'Editor top bar' }).getByRole('button', { name: 'Publish' })
    14 × locator resolved to <button type="button" aria-disabled="false" aria-expanded="false" class="components-button editor-post-publish-panel__toggle editor-post-publish-button__button is-primary is-compact">Publish</button>
       - unexpected value "enabled"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/publish-button.spec.js:62:5

should partially select text from block to block in either direction in /test/e2e/specs/editor/various/multi-block-selection.spec.js, passed after 1 failed attempt.

Error: expect(received).toEqual(expected) // deep equality

- Expected  - 1
+ Received  + 1

  Object {
-   "blocks": 2,
+   "blocks": 0,
    "endKey": "content",
    "isFullySelected": false,
    "startKey": "content",
  }

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/multi-block-selection.spec.js:1582:38

[alecgeatches]

Hmm, it looks like #82015 merged in trunk now causes this PR to fail static analysis because of private API usage. These are only consumed by core-data right now.

@ntsekouras Do you have advice on the best way to proceed here? We're removing wp.sync as a global and turning it into a bundled package because wp.sync/RTC are unstable APIs not present in core, but this conflicts with the new linting rule because we use private APIs to expose some RTC internals to core-data. Can we grandfather the sync package in? It seems like we're not supposed to expand the suppressions:

gutenberg/tools/eslint/config.mjs

Lines 140 to 143 in d894939

	// Restrictions applied to every bundled package: a plugin bundling such a
	// package compiles a second copy of private-apis, which cannot unlock objects
	// locked by the WordPress copy and throws at runtime. Existing usage is
	// grandfathered in `tools/eslint/suppressions.json` and may only shrink.

Or is it preferred that we expose those constants/functions as non-private exports? Is there a preferred method to mark the exports as being private in some other way?

[t-hamano]

Hmm, it looks like #82015 merged in trunk now causes this PR to fail static analysis because of private API usage. These are only consumed by core-data right now.

@ntsekouras @ciampo @aduth, Do you have any good ideas regarding this? We are trying to bundle the sync package in this PR to prevent it from being externalized and shipped to core as wp.sync.

[aduth]

An "at a glance" thought without having a chance to look deeply here: If this is meant to be internally consumed, maybe we could mark the package as private, and then key off that in the linter? Otherwise if we continue to publish it and some other project ends up trying to bundle it, they'll likely encounter the exact kinds of issues the lint rule is trying to protect against.

[alecgeatches]

Thank you @aduth! Making sync private makes sense to me, and seems like a good way to tell the linter to ignore it.

One question I'm not sure about. @wordpress/core-data is a published package and declares @wordpress/sync as a dependency. If @wordpress/sync becomes a private package and stops being published, it also seems like @wordpress/core-data would stop getting the latest copy of @wordpress/sync.

If I go to npm's code view of the published core-data and click into package.json, I can see a dependency on "@wordpress/sync": "^1.54.0",, and I think this would stop updating if the package is private.

As far as I can tell, no published GB package currently depends on a private one, so this would be the first case. Any idea on how to handle the dependency issue? One possible solution is to bundle it into core-data/'s file structure because it's the only consumer.

[aduth]

That's a good point, and you're right that it wouldn't work as-is to make it private if the package is depended on by some other package that is published to npm.

Your bundling idea is one option. We could make @wordpress/build handle it such that if it sees a private package, it embeds that into whatever's using it.

It also raises a question as to whether it should be an independent package at all. If @wordpress/core-data is the only consumer, why not have it live in that package?

These are just some off-the-cuff thoughts and I'll try to find some time to think about this more deeply. It may end up that we'd need to make an exception here, though we'd want to have some confidence that the sorts of issues that the linter is trying to protect against won't manifest if we do so.

[ntsekouras]

Or is it preferred that we expose those constants/functions as non-private exports?

I hope I'm not missing any nuance, but I think that would be fine, no? Since the package will be bundled now there is no global to protect, so it's better not to add more suppressions. It'd be good to remove them in this PR.

We should keep @wordpress/sync in the private-apis allow list with a comment(similar to the dataviews one), because older published copies still call the opt-in at load.

It also raises a question as to whether it should be an independent package at all. If @wordpress/core-data is the only consumer, why not have it live in that package?

Even by doing the above first step (remove private APIs), this is something that could still be considered and happen later.

[alecgeatches]

It seems like we have a few concerns blocking this PR:

1. Adding a runtime Y option so that providers can shim Yjs (e.g. Bump typescript from 5.8.3 to 5.9.2 Automattic/vip-real-time-collaboration#22) instead of using wp.sync directly, and ensure providers use the new option.
2. Removing wp.sync from the global namespace.
3. Addressing the new policy from Lint: Prevent private API imports in all bundled packages #82015 and stop using private APIs, by exporting internal functions and bundling differently.

I'd like to get the first problem fixed first, and we can provide the new Y option while still keeping wp.sync available until providers are migrated to the new system. See #82621 for the backwards-compatible Y changes.

Once that is merged and providers are caught up, we can continue with @ntsekouras's suggestion above and bundle sync in the near future in this PR.

[github-actions]

🤖 PR meta 🤖

🎉 Props

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: alecgeatches <alecgeatches@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: chriszarate <czarate@git.wordpress.org>
Co-authored-by: ntsekouras <ntsekouras@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: jaredrethman <jaredrethman@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: -1.47 kB (-0.02%)

Total Size: 8.25 MB

📦 View Changed

Filename	Size	Change
build/scripts/core-data/index.min.js	78.9 kB	+40.4 kB (+104.92%)	🆘
build/scripts/private-apis/index.min.js	1.15 kB	+1 B (+0.09%)
build/scripts/sync/index.min.js	0 B	-41.9 kB (removed)	🏆

_{a37cbc8 Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	645ed27	trunk	% Change
timeToFirstByte	57.35 ms +11.86% -3.75%	56.05 ms +4.91% -2.94%	2.32%
largestContentfulPaint	100 ms +2% -4%	92 ms +8.7% -4.35%	8.7%
lcpMinusTtfb	40.75 ms +3.93% -13.87%	34.35 ms +23.58% -6.11%	18.63%
wpBeforeTemplate	28.04 ms +16.08% -2.78%	27.84 ms +6.03% -1.72%	0.72%
wpTemplate	24.51 ms +4.08% -4.94%	23.57 ms +7% -2.5%	3.99%
wpTotal	53.92 ms +9.85% -4.6%	52.45 ms +5.11% -2.84%	2.8%
wpMemoryUsage	7.63 MB +0% -0%	7.59 MB +0% -0%	0.45%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	645ed27	trunk	% Change
timeToFirstByte	46.8 ms +5.56% -1.6%	47.1 ms +3.61% -2.44%	-0.64%
largestContentfulPaint	100 ms +4% -0%	100 ms +4% -0%	0%
lcpMinusTtfb	53.7 ms +2.98% -0.93%	53.9 ms +1.86% -1.95%	-0.37%
wpBeforeTemplate	25.87 ms +3.9% -1.86%	26.18 ms +5.5% -2.41%	-1.18%
wpTemplate	17.65 ms +3.51% -1.36%	17.36 ms +2.13% -0.75%	1.67%
wpTotal	43.68 ms +6.09% -1.74%	43.89 ms +4.56% -2.23%	-0.48%
wpMemoryUsage	6.25 MB +0% -0%	6.21 MB +0% -0%	0.7%
wpDbQueries	14 +0% -0%	14 +0% -0%	0%

media-processing

Metric	645ed27	trunk	% Change
mediaProcessingJpeg	401.81 ms +1.27% -0.74%	398.5 ms +0.61% -0.51%	0.83%
mediaProcessingAvif	6052.65 ms +0.25% -0.06%	6006.55 ms +0.25% -0.17%	0.77%
mediaProcessingJpegToAvif	4159.23 ms +0.15% -0.17%	4136.08 ms +0.27% -0.26%	0.56%

media-upload

Metric	645ed27	trunk	% Change
jpegUploadProcessing	1433.45 ms +35.82% -2.36%	1407.92 ms +0.96% -0.59%	1.81%
pngUploadProcessing	183.1 ms +17.01% -5.5%	178.25 ms +24.46% -5.04%	2.72%
largeJpegUploadProcessing	1404.5 ms +0.44% -0.11%	1401.53 ms +0.65% -0.24%	0.21%
multipleImageUploadProcessing	1564.72 ms +0.81% -2.11%	1543.35 ms +9.53% -0.35%	1.38%

post-editor

Metric	645ed27	trunk	% Change
serverResponse	317.97 ms +8.43% -6.92%	303.86 ms +8.84% -3.24%	4.64%
firstPaint	187.2 ms +9.43% -28.01%	170.59 ms +8.56% -7.18%	9.74%
domContentLoaded	849.15 ms +7.12% -4.6%	842.09 ms +0.4% -1.83%	0.84%
loaded	850.3 ms +7.11% -4.59%	843.28 ms +0.39% -1.84%	0.83%
firstContentfulPaint	348.45 ms +20.22% -3.73%	344.35 ms +4.48% -4.97%	1.19%
firstBlock	2519.49 ms +1.57% -3.27%	2433.27 ms +0.59% -0.74%	3.54%
type	15.82 ms +2.15% -2.34%	15.45 ms +5.89% -3.04%	2.39%
typeWithoutInspector	15.61 ms +6.28% -2.31%	16.06 ms +3.36% -7.6%	-2.8%
typeWithTopToolbar	20 ms +2.1% -3.85%	18.43 ms +8.3% -2.88%	8.52%
typeContainer	7.02 ms +4.42% -5.98%	7.1 ms +10.14% -5.07%	-1.13%
focus	55.65 ms +6.83% -4.53%	56.29 ms +3.73% -1.71%	-1.14%
firstFocus	167.5 ms +0% -0%	167.41 ms +0% -0%	0.05%
selectAll	398.48 ms +10.7% -0.12%	413.1 ms +1.83% -4.47%	-3.54%
listViewOpen	47.59 ms +9.83% -17.46%	46.97 ms +9.09% -6.83%	1.32%
inserterOpen	19.48 ms +13.86% -12.58%	18.3 ms +4.59% -3.44%	6.45%
inserterHover	2.04 ms +8.82% -14.71%	1.95 ms +7.18% -6.15%	4.62%
inserterSearch	6.53 ms +11.18% -3.22%	6.83 ms +4.98% -4.39%	-4.39%
loadPatterns	520.89 ms +3.04% -1.53%	505.38 ms +1.48% -5.34%	3.07%
wpTotal	309.11 ms +8.62% -7%	295.04 ms +9.09% -3.35%	4.77%
wpMemoryUsage	13.18 MB +0% -0%	13.14 MB +0% -0%	0.28%
wpDbQueries	54 +0% -0%	54 +0% -0%	0%

site-editor

Metric	645ed27	trunk	% Change
serverResponse	499.55 ms +4.13% -4.35%	498.34 ms +3.91% -1.98%	0.24%
firstPaint	272.67 ms +21.77% -25%	295.62 ms +10.18% -22.27%	-7.76%
domContentLoaded	1166.7 ms +1.75% -0.65%	1165.42 ms +0.83% -0.73%	0.11%
loaded	1167.91 ms +1.76% -0.63%	1166.79 ms +0.83% -0.71%	0.1%
firstContentfulPaint	469.51 ms +2.86% -1.64%	461.74 ms +1.82% -1.21%	1.68%
firstBlock	4309.15 ms +1.53% -1.65%	4273.29 ms +0.67% -0.92%	0.84%
type	17.36 ms +2.76% -1.96%	18.47 ms +4.66% -2.6%	-6.01%
navigate	115.66 ms +6.63% -10.18%	112.88 ms +11.16% -8.59%	2.46%
loadPatterns	1320.73 ms +14.89% -1.82%	1406.66 ms +12.02% -7.22%	-6.11%
loadPages	1064.61 ms +2.74% -1.53%	1070.85 ms +1.72% -2.74%	-0.58%
wpTotal	489.63 ms +4.19% -4.45%	488.47 ms +3.99% -2%	0.24%
wpMemoryUsage	12.14 MB +0% -0%	12.10 MB +0% -0%	0.3%
wpDbQueries	43 +2.33% -0%	43.5 +1.15% -1.15%	-1.15%

_{a37cbc8 Run}

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

show a list view in the inspector controls in /test/e2e/specs/editor/blocks/navigation-list-view.spec.js, passed after 1 failed attempt.

Error: apiRequestContext.fetch: socket hang up
Call log:
  - → POST http://localhost:8889/wp-json/wp/v2/navigation
    - user-agent: Playwright/1.63.0 (x64; ubuntu 24.04) node/24.18 CI/1
    - accept: */*
    - accept-encoding: gzip,deflate,br
    - X-WP-Nonce: 599fd87d7c
    - content-type: application/json
    - content-length: 695
    - cookie: wordpress_test_cookie=WP%20Cookie%20check; wordpress_logged_in_23778236db82f19306f247e20a353a99=admin%7C1791129501%7CqoeYu21BOkIyON0iByvP97XgpVJqcYfBZmMaLMLm0s5%7Ce2b5ca2a5c35fb149240c845043860a2b514323142ba40db2bb4209a6e37d00b; wp-settings-time-1=1790956702

    at RequestUtils.rest (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/rest.ts:112:39)
    at RequestUtils.createRecord (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/records.ts:20:14)
    at RequestUtils.createNavigationMenu (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/menus.ts:63:14)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/navigation-list-view.spec.js:58:22

_{a37cbc8 Run}

[ntsekouras]

If I'm not wrong retrySyncConnection and createSyncManager are used by core-data and plugins not need them. In that case maybe it's better to reword the docblocks? e.g. for retrySyncConnection:

Retries the HTTP polling connection now instead of waiting for the next automatic retry. Exported for @wordpress/core-data; plugins don't need it.

[alecgeatches]

Good idea, updated both of those in 92d6e7d.

[ntsekouras]

but can you check that the implementation in this PR is what you both had in mind? Thanks!

I checked the code and the changes are what I had in mind. Thanks!

[alecgeatches]

Hi, @alecgeatches

What blockers do we have here besides needing to refresh the branch? It looks like we want to land this in WP 7.2.

@Mamaduka Are we okay to wait one more week on these changes? I'm confident that the set of known transports have been updated, but I want to leave a bit more time in case we missed any.

[Mamaduka]

Sorry, missed the notification, @alecgeatches!

Yes, it should be okay to merge in a week. Beta 1 is scheduled for October 20th; even landing a couple of days before that should be fine.

[alecgeatches]

@Mamaduka I think we should be ready to merge. Any chance I could get a sign-off here?

[chriszarate]

This part of the comment is still relevant, no?

[chriszarate]

It is covered in the docs, so not necessary to preserve here. 👍

[alecgeatches]

Cool! I think the comments above this cover the migration, and most of the information in this paragraph is now out of date (wp-sync exposed, wp.sync.Y global removed in a future release).