Skip to content

A local-first personal finance app

:bug: Using a shared worker to coordinate multiple tabs (#7172)

Michael Clark4f7c3c51a58f
diff --git a/packages/desktop-client/src/browser-preload.browser.js b/packages/desktop-client/src/browser-preload.browser.js
index a659f63727..fe0930e262 100644
--- a/packages/desktop-client/src/browser-preload.browser.js
+++ b/packages/desktop-client/src/browser-preload.browser.js
@@ -6,6 +6,8 @@ import * as Platform from 'loot-core/shared/platform';
// oxlint-disable-next-line typescript-paths/absolute-parent-import
import packageJson from '../package.json';
+import SharedBrowserServerWorker from './shared-browser-server.ts?sharedworker';
+
const backendWorkerUrl = new URL('./browser-server.js', import.meta.url);
// This file installs global variables that the app expects.
@@ -21,9 +23,235 @@ const ACTUAL_VERSION = Platform.isPlaywright
: packageJson.version;
// *** Start the backend ***
+
let worker = null;
+// The regular Worker running the backend, created only on the leader tab
+let localBackendWorker = null;
+
+/**
+ * WorkerBridge wraps a SharedWorker port and presents a Worker-like interface
+ * (onmessage, postMessage, addEventListener, start) to the connection layer.
+ *
+ * The SharedWorker coordinator assigns each tab a role per budget:
+ * - LEADER: this tab runs the backend in a dedicated Worker
+ * - FOLLOWER: this tab routes messages through the SharedWorker to the leader
+ *
+ * Multiple budgets can be open simultaneously — each has its own leader.
+ */
+class WorkerBridge {
+ constructor(sharedPort) {
+ this._sharedPort = sharedPort;
+ this._onmessage = null;
+ this._listeners = [];
+ this._started = false;
+
+ // Listen for all messages from the SharedWorker port
+ sharedPort.addEventListener('message', e => this._onSharedMessage(e));
+ }
+
+ set onmessage(handler) {
+ this._onmessage = handler;
+ // Setting onmessage on a real MessagePort implicitly starts it.
+ // We need to do this explicitly on the underlying port.
+ if (!this._started) {
+ this._started = true;
+ this._sharedPort.start();
+ }
+ }
+
+ get onmessage() {
+ return this._onmessage;
+ }
+
+ postMessage(msg) {
+ // All messages go through the SharedWorker for coordination.
+ // The SharedWorker forwards to the leader's Worker via __to-worker.
+ this._sharedPort.postMessage(msg);
+ }
+
+ addEventListener(type, handler) {
+ this._listeners.push({ type, handler });
+ }
+
+ start() {
+ if (!this._started) {
+ this._started = true;
+ this._sharedPort.start();
+ }
+ }
+
+ _dispatch(event) {
+ if (this._onmessage) this._onmessage(event);
+ for (const { type, handler } of this._listeners) {
+ if (type === 'message') handler(event);
+ }
+ }
+
+ _onSharedMessage(event) {
+ const msg = event.data;
+
+ // Elected as leader: create the real backend Worker on this tab
+ if (msg && msg.type === '__become-leader') {
+ this._createLocalWorker(msg.initMsg, msg.budgetToRestore, msg.pendingMsg);
+ return;
+ }
+
+ // Forward requests from SharedWorker to our local Worker
+ if (msg && msg.type === '__to-worker') {
+ if (localBackendWorker) {
+ localBackendWorker.postMessage(msg.msg);
+ }
+ return;
+ }
+
+ // Leadership transfer: this tab is closing the budget but other tabs
+ // still need it. Terminate our Worker (don't actually close-budget on
+ // the backend) and dispatch a synthetic reply so the UI navigates to
+ // show-budgets normally.
+ if (msg && msg.type === '__close-and-transfer') {
+ console.log('[WorkerBridge] Leadership transferred — terminating Worker');
+ if (localBackendWorker) {
+ localBackendWorker.terminate();
+ localBackendWorker = null;
+ }
+ // Only dispatch a synthetic reply if there's an actual close-budget
+ // request to complete. When requestId is null the eviction was
+ // triggered externally (e.g. another tab deleted this budget).
+ if (msg.requestId) {
+ this._dispatch({
+ data: { type: 'reply', id: msg.requestId, data: {} },
+ });
+ }
+ return;
+ }
+
+ // Role change notification
+ if (msg && msg.type === '__role-change') {
+ console.log(
+ `[WorkerBridge] Role: ${msg.role}${msg.budgetId ? ` (budget: ${msg.budgetId})` : ''}`,
+ );
+ return;
+ }
+
+ // Surface SharedWorker console output in this tab's DevTools
+ if (msg && msg.type === '__shared-worker-console') {
+ const method = console[msg.level] || console.log;
+ method(...msg.args);
+ return;
+ }
+
+ // Respond to heartbeat pings
+ if (msg && msg.type === '__heartbeat-ping') {
+ this._sharedPort.postMessage({ type: '__heartbeat-pong' });
+ return;
+ }
+
+ // Everything else goes to the connection layer
+ this._dispatch(event);
+ }
+
+ _createLocalWorker(initMsg, budgetToRestore, pendingMsg) {
+ if (localBackendWorker) {
+ localBackendWorker.terminate();
+ }
+ localBackendWorker = new Worker(backendWorkerUrl);
+ initSQLBackend(localBackendWorker);
+
+ const sharedPort = this._sharedPort;
+ localBackendWorker.onmessage = workerEvent => {
+ const workerMsg = workerEvent.data;
+ // absurd-sql internal messages are handled by initSQLBackend
+ if (
+ workerMsg &&
+ workerMsg.type &&
+ workerMsg.type.startsWith('__absurd:')
+ ) {
+ return;
+ }
+ // After the backend connects, automatically reload the budget that was
+ // open before the leader left (e.g. page refresh). This lets other tabs
+ // continue working without being sent to the budget list.
+ if (workerMsg.type === 'connect') {
+ if (budgetToRestore) {
+ console.log(
+ `[WorkerBridge] Backend connected, restoring budget "${budgetToRestore}"`,
+ );
+ const id = budgetToRestore;
+ budgetToRestore = null;
+ localBackendWorker.postMessage({
+ id: '__restore-budget',
+ name: 'load-budget',
+ args: { id },
+ catchErrors: true,
+ });
+ // Tell SharedWorker to track the restore request so
+ // currentBudgetId gets updated when the reply arrives.
+ sharedPort.postMessage({
+ type: '__track-restore',
+ requestId: '__restore-budget',
+ budgetId: id,
+ });
+ } else if (pendingMsg) {
+ const toSend = pendingMsg;
+ pendingMsg = null;
+ localBackendWorker.postMessage(toSend);
+ }
+ }
+ sharedPort.postMessage({ type: '__from-worker', msg: workerMsg });
+ };
+
+ localBackendWorker.postMessage(initMsg);
+ }
+}
function createBackendWorker() {
+ // Use SharedWorker as a coordinator for multi-tab, multi-budget support.
+ // Each budget gets its own leader tab running a dedicated Worker. All other
+ // tabs on the same budget are followers — their messages are routed through
+ // the SharedWorker to the leader's Worker.
+ // The SharedWorker never touches SharedArrayBuffer, so this works on all
+ // platforms including iOS/Safari.
+ if (typeof SharedWorker !== 'undefined' && !Platform.isPlaywright) {
+ try {
+ const sharedWorker = new SharedBrowserServerWorker({
+ name: 'actual-backend',
+ });
+
+ const sharedPort = sharedWorker.port;
+ worker = new WorkerBridge(sharedPort);
+ console.log('[WorkerBridge] Connected to SharedWorker coordinator');
+
+ // Don't call start() here. The port must remain un-started so that
+ // messages (especially 'connect') are queued until connectWorker()
+ // sets onmessage, which implicitly starts the port via the bridge.
+
+ if (window.SharedArrayBuffer) {
+ localStorage.removeItem('SharedArrayBufferOverride');
+ }
+
+ sharedPort.postMessage({
+ type: 'init',
+ version: ACTUAL_VERSION,
+ isDev: IS_DEV,
+ publicUrl: process.env.PUBLIC_URL,
+ hash: process.env.REACT_APP_BACKEND_WORKER_HASH,
+ isSharedArrayBufferOverrideEnabled: localStorage.getItem(
+ 'SharedArrayBufferOverride',
+ ),
+ });
+
+ window.addEventListener('beforeunload', () => {
+ sharedPort.postMessage({ type: 'tab-closing' });
+ });
+
+ return;
+ } catch (e) {
+ console.log('SharedWorker failed, falling back to Worker:', e);
+ }
+ }
+
+ // Fallback: regular Worker (Playwright, no SharedWorker support, or failure)
+ console.log('[WorkerBridge] No SharedWorker available, using direct Worker');
worker = new Worker(backendWorkerUrl);
initSQLBackend(worker);
@@ -37,6 +265,7 @@ function createBackendWorker() {
isDev: IS_DEV,
publicUrl: process.env.PUBLIC_URL,
hash: process.env.REACT_APP_BACKEND_WORKER_HASH,
+ hasSharedArrayBuffer: !!window.SharedArrayBuffer,
isSharedArrayBufferOverrideEnabled: localStorage.getItem(
'SharedArrayBufferOverride',
),
diff --git a/packages/desktop-client/src/shared-browser-server-core.test.ts b/packages/desktop-client/src/shared-browser-server-core.test.ts
new file mode 100644
index 0000000000..a06ae5b31e
--- /dev/null
+++ b/packages/desktop-client/src/shared-browser-server-core.test.ts
@@ -0,0 +1,897 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Mock } from 'vitest';
+
+import { createCoordinator } from './shared-browser-server-core';
+
+// ── Types ───────────────────────────────────────────────────────────────
+
+type MockPort = {
+ postMessage: Mock;
+ start: Mock;
+ onmessage: ((event: { data: unknown }) => void) | null;
+};
+
+type Coordinator = ReturnType<typeof createCoordinator>;
+
+// ── Test helpers ────────────────────────────────────────────────────────
+
+function createMockPort(): MockPort {
+ return { postMessage: vi.fn(), start: vi.fn(), onmessage: null };
+}
+
+function setup(): Coordinator {
+ return createCoordinator();
+}
+
+/** Simulate a new tab connecting to the SharedWorker. */
+function connectTab(coordinator: Coordinator): MockPort {
+ const port = createMockPort();
+ coordinator.onconnect({ ports: [port] });
+ return port;
+}
+
+/** Send a message on behalf of a port (as if the tab sent it). */
+function sendMsg(port: MockPort, msg: Record<string, unknown>): void {
+ port.onmessage!({ data: msg });
+}
+
+/** Send the standard init message from a tab. */
+function sendInit(port: MockPort): void {
+ sendMsg(port, { type: 'init', version: '1.0', isDev: false });
+}
+
+/**
+ * Simulate the leader's Worker reporting that the backend is connected.
+ * In the real flow the Worker sends a 'connect' message → the bridge
+ * wraps it in __from-worker → the SharedWorker broadcasts it.
+ */
+function simulateWorkerConnect(leaderPort: MockPort): void {
+ sendMsg(leaderPort, {
+ type: '__from-worker',
+ msg: { type: 'connect' },
+ });
+}
+
+/**
+ * Set up a fully running budget group with one leader tab.
+ * Returns the leader port.
+ */
+function setupBudgetGroup(
+ coordinator: Coordinator,
+ budgetId: string,
+): MockPort {
+ const leader = connectTab(coordinator);
+ sendInit(leader);
+ leader.postMessage.mockClear();
+
+ // Lobby leader → load budget → migrates lobby to real budget
+ sendMsg(leader, {
+ id: 'lb-1',
+ name: 'load-budget',
+ args: { id: budgetId },
+ });
+
+ // Simulate the Worker reporting connect
+ simulateWorkerConnect(leader);
+
+ // Simulate successful load-budget reply
+ sendMsg(leader, {
+ type: '__from-worker',
+ msg: { type: 'reply', id: 'lb-1', result: {} },
+ });
+
+ leader.postMessage.mockClear();
+ return leader;
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────
+
+describe('SharedWorker coordinator', () => {
+ let coordinator: Coordinator;
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ coordinator = setup();
+ });
+
+ afterEach(() => {
+ coordinator.destroy();
+ vi.useRealTimers();
+ });
+
+ // ── Initialization ──────────────────────────────────────────────────
+
+ describe('initialization', () => {
+ it('first tab is elected as lobby leader', () => {
+ const port = connectTab(coordinator);
+ sendInit(port);
+
+ expect(port.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__role-change',
+ role: 'LEADER',
+ budgetId: '__lobby',
+ }),
+ );
+ });
+
+ it('second tab with no connected backend gets UNASSIGNED role', () => {
+ const port1 = connectTab(coordinator);
+ sendInit(port1);
+
+ const port2 = connectTab(coordinator);
+ sendInit(port2);
+
+ // Second tab should be UNASSIGNED (backend is booting, not connected)
+ expect(port2.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__role-change',
+ role: 'UNASSIGNED',
+ }),
+ );
+ });
+
+ it('second tab gets connect message when backend is already running', () => {
+ setupBudgetGroup(coordinator, 'budget-1');
+
+ const port2 = connectTab(coordinator);
+ sendInit(port2);
+
+ expect(port2.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: '__role-change', role: 'UNASSIGNED' }),
+ );
+ expect(port2.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: 'connect' }),
+ );
+ });
+
+ it('caches init message for new leaders', () => {
+ const port1 = connectTab(coordinator);
+ const initMsg = { type: 'init', version: '2.0', isDev: true };
+ sendMsg(port1, initMsg);
+
+ expect(coordinator.getState().cachedInitMsg).toEqual(initMsg);
+ });
+
+ it('sends cached init failure to late-joining tabs', () => {
+ // Set up a leader whose Worker reports init failure
+ const leader = connectTab(coordinator);
+ sendInit(leader);
+ simulateWorkerConnect(leader);
+
+ sendMsg(leader, {
+ type: '__from-worker',
+ msg: { type: 'app-init-failure', error: 'boom' },
+ });
+
+ const port2 = connectTab(coordinator);
+ sendInit(port2);
+
+ expect(port2.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: 'app-init-failure', error: 'boom' }),
+ );
+ });
+ });
+
+ // ── Load budget ─────────────────────────────────────────────────────
+
+ describe('load-budget', () => {
+ it('lobby leader migrates to real budget group on load-budget', () => {
+ const leader = connectTab(coordinator);
+ sendInit(leader);
+ leader.postMessage.mockClear();
+
+ sendMsg(leader, {
+ id: 'lb-1',
+ name: 'load-budget',
+ args: { id: 'my-budget' },
+ });
+
+ const state = coordinator.getState();
+ expect(state.budgetGroups.has('__lobby')).toBe(false);
+ expect(state.budgetGroups.has('my-budget')).toBe(true);
+ expect(state.portToBudget.get(leader)).toBe('my-budget');
+
+ // Should have forwarded load-budget to the Worker
+ expect(leader.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__to-worker',
+ msg: expect.objectContaining({ name: 'load-budget' }),
+ }),
+ );
+ });
+
+ it('second tab joins existing budget as follower', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ const follower = connectTab(coordinator);
+ sendInit(follower);
+ follower.postMessage.mockClear();
+
+ sendMsg(follower, {
+ id: 'lb-2',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+
+ expect(follower.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__role-change',
+ role: 'FOLLOWER',
+ budgetId: 'budget-1',
+ }),
+ );
+
+ // Should also get connect since backend is already running
+ expect(follower.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: 'connect' }),
+ );
+
+ const group = coordinator.getState().budgetGroups.get('budget-1');
+ expect(group.followers.has(follower)).toBe(true);
+ });
+
+ it('new tab on unloaded budget becomes leader for that budget', () => {
+ // Set up budget-1 so the lobby is consumed
+ setupBudgetGroup(coordinator, 'budget-1');
+
+ const tab2 = connectTab(coordinator);
+ sendInit(tab2);
+ tab2.postMessage.mockClear();
+
+ sendMsg(tab2, {
+ id: 'lb-3',
+ name: 'load-budget',
+ args: { id: 'budget-2' },
+ });
+
+ expect(tab2.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__role-change',
+ role: 'LEADER',
+ budgetId: 'budget-2',
+ }),
+ );
+
+ const state = coordinator.getState();
+ expect(state.budgetGroups.has('budget-2')).toBe(true);
+ expect(state.budgetGroups.get('budget-2').leaderPort).toBe(tab2);
+ });
+
+ it('leader switching budgets pushes followers off old budget', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ // Add a follower
+ const follower = connectTab(coordinator);
+ sendInit(follower);
+ sendMsg(follower, {
+ id: 'lb-f',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+ follower.postMessage.mockClear();
+
+ // Leader loads a different budget
+ sendMsg(leader, {
+ id: 'lb-switch',
+ name: 'load-budget',
+ args: { id: 'budget-2' },
+ });
+
+ // Follower should be pushed to show-budgets
+ expect(follower.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: 'push', name: 'show-budgets' }),
+ );
+ });
+ });
+
+ // ── Close budget ────────────────────────────────────────────────────
+
+ describe('close-budget', () => {
+ it('follower gets synthetic reply and leaves group', () => {
+ setupBudgetGroup(coordinator, 'budget-1');
+
+ const follower = connectTab(coordinator);
+ sendInit(follower);
+ sendMsg(follower, {
+ id: 'lb-f',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+ follower.postMessage.mockClear();
+
+ sendMsg(follower, { id: 'cb-1', name: 'close-budget' });
+
+ expect(follower.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: 'reply', id: 'cb-1', data: {} }),
+ );
+
+ const group = coordinator.getState().budgetGroups.get('budget-1');
+ expect(group.followers.has(follower)).toBe(false);
+ expect(coordinator.getState().unassignedPorts.has(follower)).toBe(true);
+ });
+
+ it('leader with followers transfers leadership', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ const follower = connectTab(coordinator);
+ sendInit(follower);
+ sendMsg(follower, {
+ id: 'lb-f',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+ follower.postMessage.mockClear();
+ leader.postMessage.mockClear();
+
+ sendMsg(leader, { id: 'cb-leader', name: 'close-budget' });
+
+ // Leader should get __close-and-transfer
+ expect(leader.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__close-and-transfer',
+ requestId: 'cb-leader',
+ }),
+ );
+
+ // Follower should be promoted to leader
+ expect(follower.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__role-change',
+ role: 'LEADER',
+ budgetId: 'budget-1',
+ }),
+ );
+
+ const group = coordinator.getState().budgetGroups.get('budget-1');
+ expect(group.leaderPort).toBe(follower);
+ });
+
+ it('leader with no followers forwards close to Worker', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+ leader.postMessage.mockClear();
+
+ sendMsg(leader, { id: 'cb-solo', name: 'close-budget' });
+
+ expect(leader.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__to-worker',
+ msg: expect.objectContaining({ name: 'close-budget' }),
+ }),
+ );
+ });
+
+ it('close-budget reply from Worker cleans up group', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ sendMsg(leader, { id: 'cb-solo', name: 'close-budget' });
+
+ // Simulate Worker reply
+ sendMsg(leader, {
+ type: '__from-worker',
+ msg: { type: 'reply', id: 'cb-solo', result: {} },
+ });
+
+ expect(coordinator.getState().budgetGroups.has('budget-1')).toBe(false);
+ });
+ });
+
+ // ── Tab disconnection & failover ────────────────────────────────────
+
+ describe('tab disconnection', () => {
+ it('leader disconnect promotes follower', () => {
+ setupBudgetGroup(coordinator, 'budget-1');
+
+ const follower = connectTab(coordinator);
+ sendInit(follower);
+ sendMsg(follower, {
+ id: 'lb-f',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+ follower.postMessage.mockClear();
+
+ // Find current leader to disconnect it
+ const group = coordinator.getState().budgetGroups.get('budget-1');
+ const leader = group.leaderPort as MockPort;
+
+ // Leader closes tab
+ sendMsg(leader, { type: 'tab-closing' });
+
+ // Follower should be promoted
+ expect(follower.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__role-change',
+ role: 'LEADER',
+ budgetId: 'budget-1',
+ }),
+ );
+
+ const updatedGroup = coordinator.getState().budgetGroups.get('budget-1');
+ expect(updatedGroup.leaderPort).toBe(follower);
+ });
+
+ it('last tab leaving removes budget group', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ sendMsg(leader, { type: 'tab-closing' });
+
+ expect(coordinator.getState().budgetGroups.has('budget-1')).toBe(false);
+ });
+
+ it('follower disconnect cleans up group membership', () => {
+ setupBudgetGroup(coordinator, 'budget-1');
+
+ const follower = connectTab(coordinator);
+ sendInit(follower);
+ sendMsg(follower, {
+ id: 'lb-f',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+
+ const group = coordinator.getState().budgetGroups.get('budget-1');
+ expect(group.followers.has(follower)).toBe(true);
+
+ sendMsg(follower, { type: 'tab-closing' });
+
+ expect(group.followers.has(follower)).toBe(false);
+ });
+ });
+
+ // ── Heartbeat ───────────────────────────────────────────────────────
+
+ describe('heartbeat', () => {
+ it('sends heartbeat pings to all connected ports', () => {
+ const port1 = connectTab(coordinator);
+ sendInit(port1);
+ port1.postMessage.mockClear();
+
+ vi.advanceTimersByTime(10_000);
+
+ expect(port1.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: '__heartbeat-ping' }),
+ );
+ });
+
+ it('removes ports that do not respond to heartbeat', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ // First heartbeat — marks port as pending
+ vi.advanceTimersByTime(10_000);
+ // Second heartbeat — port didn't respond, gets removed
+ vi.advanceTimersByTime(10_000);
+
+ expect(coordinator.getState().connectedPorts.includes(leader)).toBe(
+ false,
+ );
+ });
+
+ it('keeps ports that respond with pong', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ // First heartbeat
+ vi.advanceTimersByTime(10_000);
+ // Respond with pong
+ sendMsg(leader, { type: '__heartbeat-pong' });
+ // Second heartbeat — should NOT remove the port
+ vi.advanceTimersByTime(10_000);
+
+ expect(coordinator.getState().connectedPorts.includes(leader)).toBe(true);
+ });
+ });
+
+ // ── Worker message routing ──────────────────────────────────────────
+
+ describe('Worker message routing', () => {
+ it('routes reply to the port that sent the request', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ const follower = connectTab(coordinator);
+ sendInit(follower);
+ sendMsg(follower, {
+ id: 'lb-f',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+
+ // Follower sends a request
+ follower.postMessage.mockClear();
+ sendMsg(follower, { id: 'req-1', name: 'get-budgets' });
+
+ // Worker replies
+ sendMsg(leader, {
+ type: '__from-worker',
+ msg: { type: 'reply', id: 'req-1', result: ['b1'] },
+ });
+
+ expect(follower.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: 'reply',
+ id: 'req-1',
+ result: ['b1'],
+ }),
+ );
+ });
+
+ it('broadcasts connect to entire group and unassigned ports', () => {
+ const leader = connectTab(coordinator);
+ sendInit(leader);
+
+ // Load budget (still in lobby migration)
+ sendMsg(leader, {
+ id: 'lb-1',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+
+ const unassigned = connectTab(coordinator);
+ sendInit(unassigned);
+ unassigned.postMessage.mockClear();
+
+ // Worker reports connected
+ simulateWorkerConnect(leader);
+
+ expect(unassigned.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: 'connect' }),
+ );
+ });
+
+ it('forwards fire-and-forget messages (no id) to Worker', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ const follower = connectTab(coordinator);
+ sendInit(follower);
+ sendMsg(follower, {
+ id: 'lb-f',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+ leader.postMessage.mockClear();
+
+ // Fire-and-forget message (no id)
+ sendMsg(follower, { type: 'client-connected-to-backend' });
+
+ expect(leader.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__to-worker',
+ msg: expect.objectContaining({
+ type: 'client-connected-to-backend',
+ }),
+ }),
+ );
+ });
+
+ it('unassigned ports route to any connected group', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ const unassigned = connectTab(coordinator);
+ sendInit(unassigned);
+ leader.postMessage.mockClear();
+
+ sendMsg(unassigned, { id: 'req-u', name: 'get-budgets' });
+
+ expect(leader.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__to-worker',
+ msg: expect.objectContaining({ name: 'get-budgets' }),
+ }),
+ );
+ });
+ });
+
+ // ── Budget-replacing operations ─────────────────────────────────────
+
+ describe('budget-replacing operations', () => {
+ it.each(['create-budget', 'import-budget', 'duplicate-budget'])(
+ '%s from follower gets own temporary Worker',
+ (opName: string) => {
+ setupBudgetGroup(coordinator, 'budget-1');
+
+ const follower = connectTab(coordinator);
+ sendInit(follower);
+ sendMsg(follower, {
+ id: 'lb-f',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+ follower.postMessage.mockClear();
+
+ sendMsg(follower, { id: 'op-1', name: opName });
+
+ // Follower should be elected as leader for a temp group
+ expect(follower.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__role-change',
+ role: 'LEADER',
+ }),
+ );
+
+ // The temp group should exist
+ const state = coordinator.getState();
+ const tempBudget = state.portToBudget.get(follower);
+ expect(tempBudget).toMatch(/^__creating-/);
+ },
+ );
+
+ it('create-budget from leader pushes followers off', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ const follower = connectTab(coordinator);
+ sendInit(follower);
+ sendMsg(follower, {
+ id: 'lb-f',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+ follower.postMessage.mockClear();
+
+ sendMsg(leader, { id: 'cb-1', name: 'create-budget' });
+
+ expect(follower.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: 'push', name: 'show-budgets' }),
+ );
+
+ const group = coordinator.getState().budgetGroups.get('budget-1');
+ expect(group.followers.size).toBe(0);
+ });
+
+ it('create-demo-budget evicts existing _demo-budget group', () => {
+ const demoLeader = setupBudgetGroup(coordinator, '_demo-budget');
+
+ const tab2 = connectTab(coordinator);
+ sendInit(tab2);
+ tab2.postMessage.mockClear();
+
+ sendMsg(tab2, { id: 'cdb-1', name: 'create-demo-budget' });
+
+ // Old demo leader should have been evicted
+ expect(demoLeader.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__close-and-transfer',
+ requestId: null,
+ }),
+ );
+ expect(demoLeader.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: 'push', name: 'show-budgets' }),
+ );
+
+ expect(coordinator.getState().budgetGroups.has('_demo-budget')).toBe(
+ false,
+ );
+ });
+
+ it('create-budget with testMode evicts existing _test-budget group', () => {
+ const testLeader = setupBudgetGroup(coordinator, '_test-budget');
+
+ const tab2 = connectTab(coordinator);
+ sendInit(tab2);
+ tab2.postMessage.mockClear();
+
+ sendMsg(tab2, {
+ id: 'ctb-1',
+ name: 'create-budget',
+ args: { testMode: true },
+ });
+
+ expect(testLeader.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__close-and-transfer',
+ requestId: null,
+ }),
+ );
+ });
+
+ it('load-prefs reply renames __creating- temp group to real budget ID', () => {
+ setupBudgetGroup(coordinator, 'budget-1');
+
+ const creator = connectTab(coordinator);
+ sendInit(creator);
+ sendMsg(creator, {
+ id: 'lb-f',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+
+ // Creator sends create-budget → gets temp Worker
+ sendMsg(creator, { id: 'cb-1', name: 'create-budget' });
+
+ const tempId = coordinator.getState().portToBudget.get(creator);
+ expect(tempId).toMatch(/^__creating-/);
+
+ // Simulate backend connect for the temp group
+ simulateWorkerConnect(creator);
+
+ // Track a load-prefs request
+ sendMsg(creator, { id: 'lp-1', name: 'load-prefs' });
+
+ // Worker replies with load-prefs containing the new budget ID
+ sendMsg(creator, {
+ type: '__from-worker',
+ msg: { type: 'reply', id: 'lp-1', result: { id: 'new-budget-123' } },
+ });
+
+ const state = coordinator.getState();
+ expect(state.budgetGroups.has(tempId)).toBe(false);
+ expect(state.budgetGroups.has('new-budget-123')).toBe(true);
+ expect(state.portToBudget.get(creator)).toBe('new-budget-123');
+ });
+ });
+
+ // ── Delete budget ───────────────────────────────────────────────────
+
+ describe('delete-budget', () => {
+ it('evicts the group running the deleted budget', () => {
+ const leader1 = setupBudgetGroup(coordinator, 'budget-1');
+ const leader2 = setupBudgetGroup(coordinator, 'budget-2');
+
+ leader1.postMessage.mockClear();
+
+ // Tab on budget-2 deletes budget-1
+ sendMsg(leader2, {
+ id: 'db-1',
+ name: 'delete-budget',
+ args: { id: 'budget-1' },
+ });
+
+ // budget-1 leader should be evicted
+ expect(leader1.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__close-and-transfer',
+ requestId: null,
+ }),
+ );
+ expect(coordinator.getState().budgetGroups.has('budget-1')).toBe(false);
+ });
+
+ it('spins up temp Worker when no connected group remains after eviction', () => {
+ setupBudgetGroup(coordinator, 'budget-1');
+
+ // A new unassigned tab tries to delete budget-1
+ const deleter = connectTab(coordinator);
+ sendInit(deleter);
+ deleter.postMessage.mockClear();
+
+ sendMsg(deleter, {
+ id: 'db-1',
+ name: 'delete-budget',
+ args: { id: 'budget-1' },
+ });
+
+ // After evicting budget-1, no connected group remains
+ // → deleter should get a temp Worker
+ const tempId = coordinator.getState().portToBudget.get(deleter);
+ expect(tempId).toMatch(/^__deleting-/);
+
+ expect(deleter.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: '__role-change',
+ role: 'LEADER',
+ }),
+ );
+ });
+ });
+
+ // ── Track restore ───────────────────────────────────────────────────
+
+ describe('__track-restore', () => {
+ it('registers a budget restore for reply routing', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ sendMsg(leader, {
+ type: '__track-restore',
+ requestId: 'restore-1',
+ budgetId: 'budget-1',
+ });
+
+ const group = coordinator.getState().budgetGroups.get('budget-1');
+ expect(group.requestToPort.get('restore-1')).toBe(leader);
+ expect(group.requestNames.get('restore-1')).toBe('load-budget');
+ expect(group.requestBudgetIds.get('restore-1')).toBe('budget-1');
+ });
+ });
+
+ // ── Multiple budgets ────────────────────────────────────────────────
+
+ describe('multiple budgets', () => {
+ it('supports multiple independent budget groups', () => {
+ const leader1 = setupBudgetGroup(coordinator, 'budget-1');
+ const leader2 = setupBudgetGroup(coordinator, 'budget-2');
+
+ const state = coordinator.getState();
+ expect(state.budgetGroups.size).toBe(2);
+ expect(state.budgetGroups.get('budget-1').leaderPort).toBe(leader1);
+ expect(state.budgetGroups.get('budget-2').leaderPort).toBe(leader2);
+ });
+
+ it('requests from one group do not leak into another', () => {
+ const leader1 = setupBudgetGroup(coordinator, 'budget-1');
+ const leader2 = setupBudgetGroup(coordinator, 'budget-2');
+
+ // Follower joins budget-1
+ const follower = connectTab(coordinator);
+ sendInit(follower);
+ sendMsg(follower, {
+ id: 'lb-f',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+
+ follower.postMessage.mockClear();
+ leader2.postMessage.mockClear();
+
+ // Follower sends request — should go to budget-1's leader only
+ sendMsg(follower, { id: 'req-1', name: 'some-action' });
+
+ expect(leader1.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: '__to-worker' }),
+ );
+ // leader2 should NOT have received this
+ expect(leader2.postMessage).not.toHaveBeenCalledWith(
+ expect.objectContaining({ type: '__to-worker' }),
+ );
+ });
+ });
+
+ // ── Eviction ────────────────────────────────────────────────────────
+
+ describe('evictGroup', () => {
+ it('evicts followers and leader, sending them to show-budgets', () => {
+ const leader = setupBudgetGroup(coordinator, 'budget-1');
+
+ const f1 = connectTab(coordinator);
+ sendInit(f1);
+ sendMsg(f1, {
+ id: 'lb-f1',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+
+ const f2 = connectTab(coordinator);
+ sendInit(f2);
+ sendMsg(f2, {
+ id: 'lb-f2',
+ name: 'load-budget',
+ args: { id: 'budget-1' },
+ });
+
+ f1.postMessage.mockClear();
+ f2.postMessage.mockClear();
+ leader.postMessage.mockClear();
+
+ // Another tab triggers deletion of budget-1
+ const deleter = connectTab(coordinator);
+ sendInit(deleter);
+ // Set up a second budget so the deleter has a Worker
+ sendMsg(deleter, {
+ id: 'lb-del',
+ name: 'load-budget',
+ args: { id: 'budget-other' },
+ });
+ simulateWorkerConnect(deleter);
+ sendMsg(deleter, {
+ type: '__from-worker',
+ msg: { type: 'reply', id: 'lb-del', result: {} },
+ });
+
+ sendMsg(deleter, {
+ id: 'db-1',
+ name: 'delete-budget',
+ args: { id: 'budget-1' },
+ });
+
+ // All budget-1 tabs should be pushed to show-budgets
+ expect(f1.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: 'push', name: 'show-budgets' }),
+ );
+ expect(f2.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: 'push', name: 'show-budgets' }),
+ );
+ expect(leader.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ type: 'push', name: 'show-budgets' }),
+ );
+
+ expect(coordinator.getState().budgetGroups.has('budget-1')).toBe(false);
+ });
+ });
+});
diff --git a/packages/desktop-client/src/shared-browser-server-core.ts b/packages/desktop-client/src/shared-browser-server-core.ts
new file mode 100644
index 0000000000..5ce814030d
--- /dev/null
+++ b/packages/desktop-client/src/shared-browser-server-core.ts
@@ -0,0 +1,738 @@
+// Core coordinator logic for multi-tab, multi-budget SharedWorker support.
+//
+// This module exports a factory so it can be tested independently.
+// The SharedWorker entry point (shared-browser-server.js) calls
+// createCoordinator() and wires the result to self.onconnect.
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+type ConsoleLevel = 'log' | 'warn' | 'error' | 'info';
+
+/** Minimal port interface (subset of MessagePort used by the coordinator). */
+export type CoordinatorPort = {
+ postMessage(msg: unknown): void;
+ start(): void;
+ onmessage: ((event: { data: Record<string, unknown> }) => void) | null;
+};
+
+type BudgetGroup = {
+ leaderPort: CoordinatorPort;
+ followers: Set<CoordinatorPort>;
+ backendConnected: boolean;
+ requestToPort: Map<string, CoordinatorPort>;
+ requestNames: Map<string, string>;
+ requestBudgetIds: Map<string, string>;
+};
+
+type CoordinatorOptions = {
+ enableConsoleForwarding?: boolean;
+};
+
+// ── Factory ──────────────────────────────────────────────────────────────
+
+export function createCoordinator({
+ enableConsoleForwarding = false,
+}: CoordinatorOptions = {}) {
+ // ── State ──────────────────────────────────────────────────────────────
+
+ const connectedPorts: CoordinatorPort[] = [];
+ let cachedInitMsg: Record<string, unknown> | null = null;
+ let lastAppInitFailure: Record<string, unknown> | null = null;
+ const pendingPongs = new Set<CoordinatorPort>();
+
+ const budgetGroups = new Map<string, BudgetGroup>();
+ const portToBudget = new Map<CoordinatorPort, string>();
+ const unassignedPorts = new Set<CoordinatorPort>();
+
+ // ── Console forwarding ─────────────────────────────────────────────────
+
+ if (enableConsoleForwarding) {
+ const _originalConsole = {
+ log: console.log.bind(console),
+ warn: console.warn.bind(console),
+ error: console.error.bind(console),
+ info: console.info.bind(console),
+ };
+
+ function forwardConsole(level: ConsoleLevel, args: unknown[]) {
+ _originalConsole[level](...args);
+ const serialized = args.map(a => {
+ if (a instanceof Error) return a.stack || a.message;
+ if (typeof a === 'object') {
+ try {
+ return JSON.stringify(a);
+ } catch {
+ return String(a);
+ }
+ }
+ return String(a);
+ });
+ for (const port of connectedPorts) {
+ port.postMessage({
+ type: '__shared-worker-console',
+ level,
+ args: serialized,
+ });
+ }
+ }
+
+ console.log = (...args: unknown[]) => forwardConsole('log', args);
+ console.warn = (...args: unknown[]) => forwardConsole('warn', args);
+ console.error = (...args: unknown[]) => forwardConsole('error', args);
+ console.info = (...args: unknown[]) => forwardConsole('info', args);
+ }
+
+ // ── Helpers ────────────────────────────────────────────────────────────
+
+ function createBudgetGroup(leaderPort: CoordinatorPort): BudgetGroup {
+ return {
+ leaderPort,
+ followers: new Set(),
+ backendConnected: false,
+ requestToPort: new Map(),
+ requestNames: new Map(),
+ requestBudgetIds: new Map(),
+ };
+ }
+
+ function logState(action: string) {
+ const groups: string[] = [];
+ for (const [bid, g] of budgetGroups) {
+ groups.push(`"${bid}": leader + ${g.followers.size} follower(s)`);
+ }
+ console.log(
+ `[SharedWorker] ${action} — ${connectedPorts.length} tab(s), ${unassignedPorts.size} unassigned, groups: [${groups.join(', ') || 'none'}]`,
+ );
+ }
+
+ function broadcastToGroup(
+ budgetId: string,
+ msg: unknown,
+ excludePort: CoordinatorPort | null,
+ ) {
+ const group = budgetGroups.get(budgetId);
+ if (!group) return;
+ if (group.leaderPort !== excludePort) {
+ group.leaderPort.postMessage(msg);
+ }
+ for (const p of group.followers) {
+ if (p !== excludePort) {
+ p.postMessage(msg);
+ }
+ }
+ }
+
+ function broadcastToAllInGroup(budgetId: string, msg: unknown) {
+ broadcastToGroup(budgetId, msg, null);
+ }
+
+ // ── Heartbeat ──────────────────────────────────────────────────────────
+
+ const heartbeatId = setInterval(() => {
+ for (const port of [...pendingPongs]) {
+ pendingPongs.delete(port);
+ removePort(port);
+ }
+ for (const port of connectedPorts) {
+ pendingPongs.add(port);
+ port.postMessage({ type: '__heartbeat-ping' });
+ }
+ }, 10_000);
+
+ // ── Port removal & leader failover ────────────────────────────────────
+
+ function removePort(port: CoordinatorPort) {
+ const idx = connectedPorts.indexOf(port);
+ if (idx !== -1) connectedPorts.splice(idx, 1);
+ unassignedPorts.delete(port);
+
+ const budgetId = portToBudget.get(port);
+ portToBudget.delete(port);
+ if (!budgetId) return;
+
+ const group = budgetGroups.get(budgetId);
+ if (!group) return;
+
+ if (port === group.leaderPort) {
+ if (group.followers.size > 0) {
+ const candidate = group.followers.values().next()
+ .value as CoordinatorPort;
+ group.followers.delete(candidate);
+ console.log(
+ `[SharedWorker] Leader left budget "${budgetId}" — promoting follower`,
+ );
+ electLeader(budgetId, candidate, budgetId);
+ } else {
+ console.log(
+ `[SharedWorker] Last tab left budget "${budgetId}" — removing group`,
+ );
+ budgetGroups.delete(budgetId);
+ }
+ } else {
+ group.followers.delete(port);
+ for (const [id, p] of group.requestToPort) {
+ if (p === port) {
+ group.requestToPort.delete(id);
+ group.requestNames.delete(id);
+ }
+ }
+ }
+ }
+
+ // ── Leader election ───────────────────────────────────────────────────
+
+ function electLeader(
+ budgetId: string,
+ port: CoordinatorPort,
+ budgetToRestore?: string | null,
+ pendingMsg?: Record<string, unknown> | null,
+ ) {
+ let group = budgetGroups.get(budgetId);
+ if (!group) {
+ group = createBudgetGroup(port);
+ budgetGroups.set(budgetId, group);
+ } else {
+ group.leaderPort = port;
+ group.backendConnected = false;
+ group.requestToPort.clear();
+ group.requestNames.clear();
+ group.requestBudgetIds.clear();
+ }
+ const prevBudget = portToBudget.get(port);
+ if (prevBudget && prevBudget !== budgetId) {
+ removePortFromGroup(port, prevBudget);
+ }
+ portToBudget.set(port, budgetId);
+ unassignedPorts.delete(port);
+
+ console.log(
+ `[SharedWorker] Elected leader for "${budgetId}" (${group.followers.size} follower(s))`,
+ );
+ port.postMessage({
+ type: '__role-change',
+ role: 'LEADER',
+ budgetId,
+ });
+ if (cachedInitMsg) {
+ port.postMessage({
+ type: '__become-leader',
+ initMsg: cachedInitMsg,
+ budgetToRestore: budgetToRestore || null,
+ pendingMsg: pendingMsg || null,
+ });
+ }
+ }
+
+ function addFollower(budgetId: string, port: CoordinatorPort) {
+ const group = budgetGroups.get(budgetId);
+ if (!group) return;
+
+ const prevBudget = portToBudget.get(port);
+ if (prevBudget && prevBudget !== budgetId) {
+ removePortFromGroup(port, prevBudget);
+ }
+
+ group.followers.add(port);
+ portToBudget.set(port, budgetId);
+ unassignedPorts.delete(port);
+
+ port.postMessage({
+ type: '__role-change',
+ role: 'FOLLOWER',
+ budgetId,
+ });
+ if (group.backendConnected) {
+ port.postMessage({ type: 'connect' });
+ }
+ }
+
+ function removePortFromGroup(port: CoordinatorPort, budgetId: string) {
+ const group = budgetGroups.get(budgetId);
+ if (!group) return;
+ group.followers.delete(port);
+ for (const [id, p] of group.requestToPort) {
+ if (p === port) {
+ group.requestToPort.delete(id);
+ group.requestNames.delete(id);
+ }
+ }
+ }
+
+ function evictGroup(budgetId: string, excludePort: CoordinatorPort) {
+ const group = budgetGroups.get(budgetId);
+ if (!group) return;
+
+ const evicted: CoordinatorPort[] = [];
+ for (const p of group.followers) {
+ if (p !== excludePort) {
+ p.postMessage({ type: 'push', name: 'show-budgets' });
+ portToBudget.delete(p);
+ unassignedPorts.add(p);
+ evicted.push(p);
+ }
+ }
+ group.followers.clear();
+
+ if (group.leaderPort && group.leaderPort !== excludePort) {
+ group.leaderPort.postMessage({
+ type: '__close-and-transfer',
+ requestId: null,
+ });
+ group.leaderPort.postMessage({ type: 'push', name: 'show-budgets' });
+ portToBudget.delete(group.leaderPort);
+ unassignedPorts.add(group.leaderPort);
+ evicted.push(group.leaderPort);
+ }
+
+ budgetGroups.delete(budgetId);
+ if (evicted.length > 0) {
+ console.log(
+ `[SharedWorker] Evicted ${evicted.length} tab(s) from budget "${budgetId}"`,
+ );
+ }
+ }
+
+ // ── Budget lifecycle helpers ──────────────────────────────────────────
+
+ function handleBudgetLoaded(
+ leaderPort: CoordinatorPort,
+ oldGroupId: string,
+ newBudgetId: string,
+ ) {
+ const oldGroup = budgetGroups.get(oldGroupId);
+ if (!oldGroup) return;
+
+ if (oldGroupId !== newBudgetId) {
+ const existingTarget = budgetGroups.get(newBudgetId);
+ if (existingTarget && existingTarget !== oldGroup) {
+ console.warn(
+ `[SharedWorker] handleBudgetLoaded: conflict — group "${newBudgetId}" already exists`,
+ );
+ return;
+ }
+ budgetGroups.delete(oldGroupId);
+ budgetGroups.set(newBudgetId, oldGroup);
+ portToBudget.set(leaderPort, newBudgetId);
+
+ for (const p of oldGroup.followers) {
+ portToBudget.set(p, newBudgetId);
+ }
+
+ console.log(
+ `[SharedWorker] Budget loaded: "${newBudgetId}" (leader + ${oldGroup.followers.size} follower(s))`,
+ );
+ }
+
+ logState(`Budget "${newBudgetId}" ready`);
+ }
+
+ function handleBudgetClosed(closingPort: CoordinatorPort, budgetId: string) {
+ const group = budgetGroups.get(budgetId);
+ if (!group) return;
+
+ if (closingPort === group.leaderPort && group.followers.size === 0) {
+ budgetGroups.delete(budgetId);
+ portToBudget.delete(closingPort);
+ unassignedPorts.add(closingPort);
+ logState(`Budget "${budgetId}" closed (no tabs remain)`);
+ }
+ }
+
+ function migrateLobbyLeader(
+ port: CoordinatorPort,
+ budgetId: string,
+ pendingMsg: Record<string, unknown>,
+ ) {
+ const lobbyGroup = budgetGroups.get('__lobby');
+ if (lobbyGroup && port === lobbyGroup.leaderPort) {
+ budgetGroups.delete('__lobby');
+ budgetGroups.set(budgetId, lobbyGroup);
+ portToBudget.set(port, budgetId);
+ lobbyGroup.requestToPort.set(pendingMsg.id as string, port);
+ lobbyGroup.requestNames.set(
+ pendingMsg.id as string,
+ pendingMsg.name as string,
+ );
+ lobbyGroup.requestBudgetIds.set(pendingMsg.id as string, budgetId);
+ lobbyGroup.leaderPort.postMessage({
+ type: '__to-worker',
+ msg: pendingMsg,
+ });
+ port.postMessage({
+ type: '__role-change',
+ role: 'LEADER',
+ budgetId,
+ });
+ logState(`Lobby leader now on budget "${budgetId}"`);
+ }
+ }
+
+ // ── Connection handler ────────────────────────────────────────────────
+
+ function onconnect(e: { ports: CoordinatorPort[] }) {
+ const port = e.ports[0];
+ connectedPorts.push(port);
+ unassignedPorts.add(port);
+ logState('Tab connected');
+
+ port.onmessage = function (event: { data: Record<string, unknown> }) {
+ try {
+ const msg = event.data;
+ const portBudget = portToBudget.get(port);
+ const group = portBudget ? budgetGroups.get(portBudget) : null;
+
+ // ── Tab lifecycle ──────────────────────────────────────────
+
+ if (msg.type === 'tab-closing') {
+ pendingPongs.delete(port);
+ removePort(port);
+ logState('Tab closed');
+ return;
+ }
+
+ if (msg.type === '__heartbeat-pong') {
+ pendingPongs.delete(port);
+ return;
+ }
+
+ // ── Initialization ─────────────────────────────────────────
+
+ if (msg.type === 'init') {
+ cachedInitMsg = msg;
+ if (lastAppInitFailure) {
+ port.postMessage(lastAppInitFailure);
+ } else {
+ let anyConnected = false;
+ for (const [, g] of budgetGroups) {
+ if (g.backendConnected) {
+ anyConnected = true;
+ break;
+ }
+ }
+ if (anyConnected) {
+ port.postMessage({ type: '__role-change', role: 'UNASSIGNED' });
+ port.postMessage({ type: 'connect' });
+ } else if (budgetGroups.size > 0) {
+ port.postMessage({ type: '__role-change', role: 'UNASSIGNED' });
+ } else {
+ electLeader('__lobby', port);
+ }
+ }
+ return;
+ }
+
+ // ── Leader tab forwarding Worker messages back ─────────────
+
+ if (msg.type === '__from-worker') {
+ if (!group || port !== group.leaderPort) return;
+ const workerMsg = msg.msg as Record<string, unknown>;
+
+ if (workerMsg.type === 'reply' || workerMsg.type === 'error') {
+ const targetPort = group.requestToPort.get(workerMsg.id as string);
+ if (targetPort) {
+ targetPort.postMessage(workerMsg);
+
+ const name = group.requestNames.get(workerMsg.id as string);
+ if (workerMsg.type === 'reply' && name === 'load-budget') {
+ const budgetId = group.requestBudgetIds.get(
+ workerMsg.id as string,
+ );
+ if (budgetId) {
+ group.requestBudgetIds.delete(workerMsg.id as string);
+ handleBudgetLoaded(port, portBudget!, budgetId);
+ }
+ }
+ if (workerMsg.type === 'reply' && name === 'close-budget') {
+ handleBudgetClosed(targetPort, portBudget!);
+ }
+ if (
+ workerMsg.type === 'reply' &&
+ name === 'load-prefs' &&
+ portBudget &&
+ portBudget.startsWith('__creating-') &&
+ workerMsg.result &&
+ (workerMsg.result as Record<string, unknown>).id
+ ) {
+ handleBudgetLoaded(
+ port,
+ portBudget,
+ (workerMsg.result as Record<string, unknown>).id as string,
+ );
+ }
+
+ group.requestToPort.delete(workerMsg.id as string);
+ group.requestNames.delete(workerMsg.id as string);
+ }
+ } else if (workerMsg.type === 'connect') {
+ group.backendConnected = true;
+ broadcastToAllInGroup(portBudget!, workerMsg);
+ for (const p of unassignedPorts) {
+ p.postMessage(workerMsg);
+ }
+ } else if (workerMsg.type === 'app-init-failure') {
+ lastAppInitFailure = workerMsg;
+ broadcastToAllInGroup(portBudget!, workerMsg);
+ } else {
+ broadcastToAllInGroup(portBudget!, workerMsg);
+ }
+ return;
+ }
+
+ // ── Leader tab registering a budget restore ────────────────
+
+ if (msg.type === '__track-restore') {
+ if (group) {
+ group.requestToPort.set(msg.requestId as string, port);
+ group.requestNames.set(msg.requestId as string, 'load-budget');
+ group.requestBudgetIds.set(
+ msg.requestId as string,
+ msg.budgetId as string,
+ );
+ }
+ return;
+ }
+
+ // ── Request interception & routing ─────────────────────────
+
+ if (
+ msg.name === 'load-budget' &&
+ msg.args &&
+ (msg.args as Record<string, unknown>).id
+ ) {
+ const budgetId = (msg.args as Record<string, unknown>).id as string;
+ const existingGroup = budgetGroups.get(budgetId);
+
+ if (existingGroup && existingGroup.backendConnected) {
+ addFollower(budgetId, port);
+ existingGroup.requestToPort.set(msg.id as string, port);
+ existingGroup.requestNames.set(
+ msg.id as string,
+ msg.name as string,
+ );
+ existingGroup.requestBudgetIds.set(msg.id as string, budgetId);
+ existingGroup.leaderPort.postMessage({
+ type: '__to-worker',
+ msg,
+ });
+ logState(`Tab joined budget "${budgetId}" as follower`);
+ return;
+ }
+
+ if (existingGroup && !existingGroup.backendConnected) {
+ addFollower(budgetId, port);
+ existingGroup.requestToPort.set(msg.id as string, port);
+ existingGroup.requestNames.set(
+ msg.id as string,
+ msg.name as string,
+ );
+ existingGroup.requestBudgetIds.set(msg.id as string, budgetId);
+ existingGroup.leaderPort.postMessage({
+ type: '__to-worker',
+ msg,
+ });
+ logState(
+ `Tab joined budget "${budgetId}" as follower (backend booting)`,
+ );
+ return;
+ }
+
+ if (portBudget === '__lobby') {
+ migrateLobbyLeader(port, budgetId, msg);
+ } else if (group && port === group.leaderPort) {
+ for (const p of group.followers) {
+ p.postMessage({ type: 'push', name: 'show-budgets' });
+ portToBudget.delete(p);
+ unassignedPorts.add(p);
+ }
+ if (group.followers.size > 0) {
+ console.log(
+ `[SharedWorker] Leader switching budgets — pushed ${group.followers.size} follower(s) off "${portBudget}"`,
+ );
+ group.followers.clear();
+ }
+ group.requestToPort.set(msg.id as string, port);
+ group.requestNames.set(msg.id as string, msg.name as string);
+ group.requestBudgetIds.set(msg.id as string, budgetId);
+ group.leaderPort.postMessage({ type: '__to-worker', msg });
+ } else {
+ electLeader(budgetId, port, null, msg);
+ const newGroup = budgetGroups.get(budgetId);
+ if (newGroup) {
+ newGroup.requestToPort.set(msg.id as string, port);
+ newGroup.requestNames.set(msg.id as string, msg.name as string);
+ newGroup.requestBudgetIds.set(msg.id as string, budgetId);
+ }
+ logState(`Tab became leader for new budget "${budgetId}"`);
+ }
+ return;
+ }
+
+ // close-budget: handle leader vs follower
+ if (msg.name === 'close-budget' && group) {
+ if (port === group.leaderPort) {
+ if (group.followers.size > 0) {
+ const newLeader = group.followers.values().next()
+ .value as CoordinatorPort;
+ group.followers.delete(newLeader);
+ console.log(
+ `[SharedWorker] Leader closing budget "${portBudget}" but ${group.followers.size + 1} tab(s) remain — transferring`,
+ );
+ port.postMessage({
+ type: '__close-and-transfer',
+ requestId: msg.id,
+ });
+ electLeader(portBudget!, newLeader, portBudget);
+ portToBudget.delete(port);
+ unassignedPorts.add(port);
+ logState(`Leadership transferred for "${portBudget}"`);
+ return;
+ }
+ group.requestToPort.set(msg.id as string, port);
+ group.requestNames.set(msg.id as string, msg.name as string);
+ group.leaderPort.postMessage({ type: '__to-worker', msg });
+ return;
+ } else {
+ group.followers.delete(port);
+ portToBudget.delete(port);
+ unassignedPorts.add(port);
+ port.postMessage({ type: 'reply', id: msg.id, data: {} });
+ logState(`Follower left budget "${portBudget}"`);
+ return;
+ }
+ }
+
+ // delete-budget: if another group is running this budget, evict it
+ if (msg.name === 'delete-budget' && msg.args) {
+ const targetId = (msg.args as Record<string, unknown>).id as string;
+ if (targetId && budgetGroups.has(targetId)) {
+ evictGroup(targetId, port);
+ logState(`Evicted group for deleted budget "${targetId}"`);
+ }
+ let hasConnected = false;
+ for (const [, g] of budgetGroups) {
+ if (g.backendConnected) {
+ hasConnected = true;
+ break;
+ }
+ }
+ if (!hasConnected) {
+ const tempId = '__deleting-' + Date.now();
+ electLeader(tempId, port, null, msg);
+ const newGroup = budgetGroups.get(tempId);
+ if (newGroup && msg.id) {
+ newGroup.requestToPort.set(msg.id as string, port);
+ newGroup.requestNames.set(msg.id as string, msg.name as string);
+ }
+ logState(`Tab became leader for budget deletion ("${tempId}")`);
+ return;
+ }
+ }
+
+ // Budget-replacing operations
+ if (
+ msg.name === 'create-budget' ||
+ msg.name === 'create-demo-budget' ||
+ msg.name === 'import-budget' ||
+ msg.name === 'duplicate-budget' ||
+ msg.name === 'delete-budget'
+ ) {
+ if (msg.name === 'create-demo-budget') {
+ evictGroup('_demo-budget', port);
+ } else if (
+ msg.name === 'create-budget' &&
+ msg.args &&
+ (msg.args as Record<string, unknown>).testMode
+ ) {
+ evictGroup('_test-budget', port);
+ }
+ if (group && port === group.leaderPort) {
+ for (const p of group.followers) {
+ p.postMessage({ type: 'push', name: 'show-budgets' });
+ portToBudget.delete(p);
+ unassignedPorts.add(p);
+ }
+ if (group.followers.size > 0) {
+ console.log(
+ `[SharedWorker] Budget-replacing "${msg.name}" — pushed ${group.followers.size} tab(s) off "${portBudget}"`,
+ );
+ group.followers.clear();
+ }
+ } else {
+ if (group) {
+ group.followers.delete(port);
+ portToBudget.delete(port);
+ unassignedPorts.add(port);
+ }
+ const tempId = '__creating-' + Date.now();
+ electLeader(tempId, port, null, msg);
+ const newGroup = budgetGroups.get(tempId);
+ if (newGroup && msg.id) {
+ newGroup.requestToPort.set(msg.id as string, port);
+ newGroup.requestNames.set(msg.id as string, msg.name as string);
+ }
+ logState(`Tab became leader for budget creation ("${tempId}")`);
+ return;
+ }
+ }
+
+ // ── Default: track and forward to leader ───────────────────
+
+ let targetGroup = group;
+ if (!targetGroup) {
+ for (const [, g] of budgetGroups) {
+ if (g.backendConnected) {
+ targetGroup = g;
+ break;
+ }
+ }
+ }
+
+ if (targetGroup) {
+ if (msg.id) {
+ targetGroup.requestToPort.set(msg.id as string, port);
+ if (msg.name) {
+ targetGroup.requestNames.set(
+ msg.id as string,
+ msg.name as string,
+ );
+ }
+ if (
+ msg.name === 'load-budget' &&
+ msg.args &&
+ (msg.args as Record<string, unknown>).id
+ ) {
+ targetGroup.requestBudgetIds.set(
+ msg.id as string,
+ (msg.args as Record<string, unknown>).id as string,
+ );
+ }
+ }
+ targetGroup.leaderPort.postMessage({ type: '__to-worker', msg });
+ }
+ } catch (error) {
+ console.error('[SharedWorker] Error in message handler:', error);
+ }
+ };
+
+ port.start();
+ }
+
+ // ── Public API ────────────────────────────────────────────────────────
+
+ function destroy() {
+ clearInterval(heartbeatId);
+ }
+
+ function getState() {
+ return {
+ connectedPorts,
+ cachedInitMsg,
+ lastAppInitFailure,
+ budgetGroups,
+ portToBudget,
+ unassignedPorts,
+ };
+ }
+
+ return { onconnect, destroy, getState };
+}
diff --git a/packages/desktop-client/src/shared-browser-server.ts b/packages/desktop-client/src/shared-browser-server.ts
new file mode 100644
index 0000000000..4bd3de6c10
--- /dev/null
+++ b/packages/desktop-client/src/shared-browser-server.ts
@@ -0,0 +1,11 @@
+// SharedWorker entry point for multi-tab, multi-budget support.
+//
+// All coordinator logic lives in shared-browser-server-core.ts
+// This file simply creates a coordinator with console forwarding
+// enabled and wires it to the SharedWorkerGlobalScope.
+
+import { createCoordinator } from './shared-browser-server-core';
+
+const coordinator = createCoordinator({ enableConsoleForwarding: true });
+(self as unknown as { onconnect: typeof coordinator.onconnect }).onconnect =
+ coordinator.onconnect;
diff --git a/packages/loot-core/src/server/budgetfiles/app.ts b/packages/loot-core/src/server/budgetfiles/app.ts
index 4b7cffe3d4..b3f9b313db 100644
--- a/packages/loot-core/src/server/budgetfiles/app.ts
+++ b/packages/loot-core/src/server/budgetfiles/app.ts
@@ -408,6 +408,11 @@ async function createBudget({
id = testBudgetId || TEST_BUDGET_ID;
if (await fs.exists(fs.getBudgetDir(id))) {
+ // Close the budget first if it's currently loaded, so the
+ // database is properly shut down before we remove its files.
+ if (prefs.getPrefs()?.id === id) {
+ await closeBudget();
+ }
await fs.removeDirRecursively(fs.getBudgetDir(id));
}
} else {
diff --git a/upcoming-release-notes/7172.md b/upcoming-release-notes/7172.md
new file mode 100644
index 0000000000..29ad31d8d9
--- /dev/null
+++ b/upcoming-release-notes/7172.md
@@ -0,0 +1,6 @@
+---
+category: Bugfix
+authors: [MikesGlitch]
+---
+
+Fix multi-tab sync by sharing a single backend via SharedWorker