[personal-wp] Add multi-tab coordination #3163

akirk · 2026-01-22T04:09:57Z

Based on #3162.

Motivation for the change, related issues

When users open the same persistent site in multiple browser tabs, OPFS (Origin Private File System) conflicts can occur because each tab tries to access the same storage. This PR adds a coordination system so only one tab owns the PHP worker while other tabs operate in "dependent mode".

Screenshots

Implementation details

Tab Coordinator (tab-coordinator.ts): Uses BroadcastChannel API for cross-tab communication with ping/pong discovery, takeover requests, and backup delegation
Boot Logic (boot-site-client.ts): Checks for existing tabs before booting; yields to fresh main tabs or becomes dependent if one exists
Dependent Mode: Tabs without their own worker use the main tab's service worker URL and delegate operations like backup
UI Indicators:
- WorkerStatusIndicator in address bar shows "Main" or "Dependent" badge
- TabInfoWindow in overlay shows WordPress boot time and connected tabs
Edge Cases:
- Main tab reload: Dependent tabs report isDependentMode: true in pong, so reloading main correctly re-establishes as main
- Backup from dependent: Cross-tab messaging delegates backup request to main tab
- Main tab closes: Dependent tabs show "Reload required" indicator

Testing Instructions (or ideally a Blueprint)

Open a persistent site in Tab 1 → should boot normally
Open the same site in Tab 2 → should show "Dependent" badge, Tab 1 shows "Main"
Click badge to open overlay → shows boot time and other tabs count
In Tab 2 overlay, click Backup → download triggers (handled by main tab)
Reload Tab 1 → should re-establish as main (not become dependent)
Close Tab 1 → Tab 2 shows "Reload required"

adamziel · 2026-01-23T13:59:04Z

packages/playground/personal-wp/src/lib/state/redux/boot-site-client.ts

+					const remoteUrl = getRemoteUrl();
+					const scopedSiteUrl = `/scope:${encodeURIComponent(site.slug)}/`;
+
+					const dependentModeClient = {


These methods seem like a less capable version of the original client methods, e.g. goTo()) covers for a few relevant corner-cases. I understand we need this because there's not a playgroundClient we could use to transform playground.pathToInternalUrl()? Could we somehow declare const playground = mainPlaygroundRunningInAnotherTab? e.g. using broadcast channels for communication? We may need a custom Comlink transport but could be doable

Admittedly I am not sure I understand this in-and-out enough but the way I understand it is that the PlaygroundClient basically fulfills navigational tasks for the iframe communication and php worker stuff. Could we refactor out those navigational tasks so that our dependentModeClient could have those and all php worker things would remain in the PlaygroundClient.

adamziel · 2026-01-23T14:00:22Z

packages/playground/personal-wp/src/lib/state/redux/tab-coordinator.ts

+ *
+ * @param tabs - List of tabs to check
+ */
+export function requestStaleTabsShutdown(tabs: TabInfo[]): void {


This comes from the worry that people will have super long running tabs. AFAIK we don't have a mechanism to check with the server if there is a new version of playground. This is mostly to avoid people sitting on stale and outdated tabs for months.

adamziel · 2026-01-23T14:00:51Z

packages/playground/personal-wp/src/lib/state/redux/tab-coordinator.ts

+ * @param targetTabId - The tab ID to shut down
+ * @param reason - Why the tab should shut down
+ */
+export function requestTabShutdown(


This is only called once, in the function below. Can we either inline it or not export it?

I'll remove the export.

adamziel · 2026-01-23T14:03:16Z

packages/playground/personal-wp/src/lib/state/redux/tab-coordinator.ts

+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const PING_TIMEOUT_MS = 150;
+
+let channel: BroadcastChannel | null = null;


Just to name it: these are local variables that are not managed by redux even though this file lives in state/redux. It seems fine. I don't expect we'll need to run multiple redux stores that run independent tab coordination.

adamziel · 2026-01-23T14:04:13Z

packages/playground/personal-wp/src/lib/state/redux/tab-coordinator.ts

+let siteResetCallback: (() => void) | null = null;
+let beforeUnloadHandler: (() => void) | null = null;
+
+// Clean up on Vite HMR to prevent duplicate listeners


This is weird, is there a general way of expressing this that doesn't depend on vite or encode vite-specific APIs?

This is a remainder of debugging some weirdnes, I think I can remove it.

adamziel · 2026-01-23T14:10:27Z

packages/playground/personal-wp/src/lib/hooks/use-takeover.ts

+ */
+export function useRemoteBackup() {
+	const clientInfo = usePlaygroundClientInfo();
+	const activeSite = useActiveSite();
+	const [isRequestingBackup, setIsRequestingBackup] = useState(false);
+
+	const isDependentMode = clientInfo?.isDependentMode ?? false;
+
+	const requestBackup = useCallback(async (): Promise<boolean> => {
+		if (!activeSite || !isDependentMode || isRequestingBackup) {
+			return false;
+		}
+
+		setIsRequestingBackup(true);
+		try {
+			const success = await requestRemoteBackup(activeSite.slug);
+			return success;
+		} finally {
+			setIsRequestingBackup(false);
+		}
+	}, [activeSite, isDependentMode, isRequestingBackup]);
+
+	return {
+		requestBackup,
+		isRequestingBackup,
+		isDependentMode,
+		canRequestBackup: isDependentMode && !!activeSite,
+	};
+}


The structure seems pretty generic, maybe later on it will make sense to have a generic cross-tab client and a useCrossTabRPC( "backup" ) call? Let's watch how this evolves. Nothing blocking or actionable in this comment.

adamziel · 2026-01-23T14:12:18Z

packages/playground/personal-wp/src/lib/state/redux/boot-site-client.ts

+					// This callback is called when another tab requests to take over as main
+					// We switch to dependent mode without showing an error
+					const remoteUrl = getRemoteUrl();
+					const scopedSiteUrl = `/scope:${encodeURIComponent(site.slug)}/`;


We have a helper for this in

wordpress-playground/packages/php-wasm/scopes/src/index.ts

Line 75 in aecea42

export function setURLScope(url: URL | string, scope: string | null): URL {

. encodeURIComponent may be a useful addition

Hm, our scope is actually hardcoded to default.

adamziel

I left some comments, none of which need to be addressed before shipping this. Feel free to merge anytime.

- Remove export from requestTabShutdown (only used internally) - Remove Vite HMR cleanup code (dev-only, accept occasional HMR quirks)

akirk added the [Feature] Personal Playground label Jan 22, 2026

akirk changed the title ~~[Website] Personal Playground: Add multi-tab coordination~~ [website] Personal Playground: Add multi-tab coordination Jan 22, 2026

akirk force-pushed the persistent/multi-tab-coordination branch from a75d636 to add3bab Compare January 22, 2026 14:41

akirk force-pushed the persistent/backup-reminder branch 2 times, most recently from 1555eba to 4da5ad5 Compare January 23, 2026 05:03

akirk force-pushed the persistent/multi-tab-coordination branch from add3bab to 7cdbb30 Compare January 23, 2026 05:03

akirk mentioned this pull request Jan 23, 2026

[personal-wp] Introduce a user-focused Personal Playground #3174

Closed

akirk changed the title ~~[website] Personal Playground: Add multi-tab coordination~~ [personal-wp] Add multi-tab coordination Jan 23, 2026

akirk force-pushed the persistent/backup-reminder branch from 4da5ad5 to 817712c Compare January 23, 2026 12:07

akirk force-pushed the persistent/multi-tab-coordination branch from 7cdbb30 to c1b2abd Compare January 23, 2026 12:07

akirk force-pushed the persistent/backup-reminder branch from 817712c to 7158776 Compare January 23, 2026 13:17

akirk force-pushed the persistent/multi-tab-coordination branch from c1b2abd to c94e2d5 Compare January 23, 2026 13:17

adamziel reviewed Jan 23, 2026

View reviewed changes

adamziel approved these changes Jan 23, 2026

View reviewed changes

akirk force-pushed the persistent/backup-reminder branch from 7158776 to b72b187 Compare January 23, 2026 16:09

akirk force-pushed the persistent/multi-tab-coordination branch 3 times, most recently from 48a1290 to 55a7f29 Compare January 26, 2026 09:27

Base automatically changed from persistent/backup-reminder to trunk January 27, 2026 12:05

akirk added 2 commits January 27, 2026 13:06

Add multi-tab coordination for personal sites

c470fd6

Address review feedback on tab coordinator

45accb9

- Remove export from requestTabShutdown (only used internally) - Remove Vite HMR cleanup code (dev-only, accept occasional HMR quirks)

akirk force-pushed the persistent/multi-tab-coordination branch from 55a7f29 to 45accb9 Compare January 27, 2026 12:07

akirk merged commit 989ddcf into trunk Jan 27, 2026
35 checks passed

akirk deleted the persistent/multi-tab-coordination branch January 27, 2026 12:24

[personal-wp] Add multi-tab coordination #3163

[personal-wp] Add multi-tab coordination #3163

Uh oh!

Conversation

akirk commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation for the change, related issues

Screenshots

Implementation details

Testing Instructions (or ideally a Blueprint)

Uh oh!

adamziel Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akirk Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamziel Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamziel left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

akirk commented Jan 22, 2026 •

edited

Loading

adamziel Jan 23, 2026 •

edited

Loading

akirk Jan 23, 2026 •

edited

Loading

adamziel Jan 23, 2026 •

edited

Loading

adamziel left a comment •

edited

Loading