Workspace v2 needed tabs that behave more like browser tabs than a UI row. Users keep several business objects open, refresh and shared links still work, and hidden runtimes do not get to steal the URL, overlays, events, or foreground CPU. Most of the work was ownership: who owns intent, URL, tab state, runtime cache, sandbox effects, and the rendered frame.

Figure 0: A generic workbench using browser-like tabs. Users keep several work items open, switch back without reload, and only the focused tab owns URL, overlays, events, and foreground CPU. generated by gpt-image-2.

Background and goals

Workspace v2 changed the workbench from one page with one active context into a place where several workstreams, subapp views, and ticket objects can stay open at the same time. The user expectation is simple and unforgiving:

1. several tasks stay open,
2. switching back keeps state,
3. refresh and shared links still land on the right business page,
4. and a modal opened by one sub-application cannot cover another tab.

Business goals:

Technical goals:

Figure A1: Product goals mapped to engineering constraints. The diagram breaks browser-like tabs into concrete system requirements and failure modes. generated by gpt-image-2.

The final design principle is:

Keep the address bar as a real business URL; use server state to record which tabs are open; keep only a bounded working set warm; and put host-owned boundaries around subapp history, DOM, overlays, and events.

The system has two core questions:

1. Should two entries reuse the same tab? For example, the same workstream should reuse one tab, while its internal view is preserved as URL/subPath state.
2. Which tab owns runtime side effects now? Only the focused tab can write the browser URL, show overlays, receive foreground events, and consume foreground CPU.

Architecture layers

Figure A2: Final layered architecture. Isolation and Observability are intentionally separate: Isolation prevents hidden runtimes from changing the current tab; Observability proves where latency, blocked writes, or regressions happen. generated by gpt-image-2.

Layer 1: Intent Interface

Problem

Users can open the same business object from many entry points: sidebar, tab row, a subapp button, MF event bus, iframe postMessage, or a copied business URL. The expected result is consistent: an already-open object is focused, a new object opens once, and a view inside the same subapp can often navigate within the current tab.

If each entry makes its own decision, users see direct failures: a menu click reuses a tab but a subapp button creates a duplicate; a shared link restores the page but SDK navigation loses the last inner view; one entry respects tab capacity while another bypasses it.

Solution

Subapps only express intent. The host decides how to execute it.

Simplified pseudocode:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

// A subapp sends intent. It does not mutate host state.
function openSubappView(viewType, viewId) {
  emit('TAB_OPEN_REQUEST', { itemType: 'SUBAPP_VIEW', viewType, viewId });
}

// A iframe post event to host
window.parent.postMessage({
  type: 'MF_EVENT',
  payload: {
    type: 'TAB_OPEN_REQUEST',
    data: {
      itemType: 'WORKSTREAM',
      workstreamId: 'from-iframe',
    },
    metadata: {
      source: 'REPORT_CENTER',
      timestamp: Date.now(),
    },
  },
}, targetOrigin);

function handleTabOpenRequest(raw) {
  const input = normalizeAndValidate(raw);

  if (raw.openInNewBrowserTab) {
    window.open(buildBusinessUrl(input));
    return;
  }

  // existing: the target business object already owns a tab.
  const existing = findExistingTab(tabs, input);

  // absorbing: the currently focused tab is a suitable carrier for this navigation.
  const absorbing = findFocusedTabThatCanAbsorb(input);

  // If a subapp root can absorb but an exact tab already exists, prefer the exact tab.
  if (existing && absorbing?.kind === 'subapp-root') {
    focusTab(existing.id, savedUrlOrDefault(existing));
    return;
  }

  if (absorbing) {
    navigateInsideTab(absorbing.id, buildPath(input));
    return;
  }

  if (existing) {
    focusTab(existing.id, savedUrlOrDefault(existing));
    return;
  }

  addTabWithCapacityControl(input);
}

Layer 2: URL And Tab Ownership

Problem

The browser has one address bar, while the workspace can keep multiple tab runtimes alive. We cannot replace business URLs with internal routes such as /tabs/:id.

So the address bar stays as a real business URL:

• /workspace/workstream/:id/...
• /workspace/scheduling/schedule/view/:viewId
• /workspace/audit_workbench/ticket/custom_view/:viewId

Internally, the host extracts business fields from the URL and uses them to decide whether two entries should reuse the same tab.

Figure A3: URL and tab synchronization. The address bar remains a business URL; the host maps it to an internal tab owner. generated by gpt-image-2.

Browser URL -> Tab

This path handles refresh, copied links, and external deep links.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

function onRouteChanged(location) {
  // Parse the business URL into "does this route belong to a tab?"
  const resolved = resolveTabFromUrl(location.pathname, appList);

  if (resolved.kind !== 'tab') {
    // Home, redirect, or fallback pages render normally.
    // They do not create tab rows or hot runtime entries.
    renderSingleOutlet();
    return;
  }

  const matched = findOpenedTab(tabs, resolved.input);
  if (matched) {
    focusRuntime(matched.id);
    return;
  }

  // Direct URL recovery:
  // The user opened a valid business URL, but BFF has no opened tab yet.
  addTab(toAddWorkspaceTabRequest(resolved.input));
  focusRuntimeWhenReady(resolved.input);
}

Tab -> Browser URL

This path handles tab clicks.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

function activateTab(tab) {
  // Restore the tab's last business URL, not an internal /tabs/:id URL.
  const path = loadSavedTabUrl(tab.id) ?? buildDefaultBusinessUrl(tab);

  startTabSwitchMetric({ toId: tab.id, targetPath: path });

  // The next history write belongs to this target tab.
  // Some subapps and Seto iframe will keep syncing URL in background
  // using RAW_HISTORY.replaceState
  // We must tell history handler which tab is focusing and actions should be accepted
  // otherwise might causing racing condition and url got changed to other things
  prepareScopedNavigation({ targetTabId: tab.id, url: path });

  navigate(path, {
    state: { workspaceTargetTabId: tab.id },
    flushSync: true,
  });
}

Window -> Window

Tab list mutations are persistent facts, not local React state.

1
2
3
4
5
6
7
8
9
10
11

async function mutateTabs(mutation) {
  // Current window updates optimistically for fast feedback.
  queryClient.setQueryData(tabListKey, applyOptimistic(mutation));

  await bff.mutateTabs(mutation);

  // Other windows do not receive the full state through BroadcastChannel.
  // They only get invalidation and refetch from BFF.
  broadcastChannel.postMessage({ type: 'TAB_LIST_INVALIDATED' });
}

Layer 3: Persistent Tab State

Problem

Users see three concrete failures if tab state is only local: refresh loses the tab row, add/remove/pin feels delayed if every mutation waits for the server, and two browser windows drift apart after one window mutates the tab list.

Backend told me the Tab actions and list would be relatively slow because it involved a lot of services.

Solution

Persistent state is handled by BFF plus React Query.

Figure A3.5: Persistent tab state. React Query makes the current window fast; BFF stores the final fact; BroadcastChannel tells other windows to invalidate and refetch. generated by gpt-image-2.

Simplified flow:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

function useAddTab() {
  return useMutation({
    mutationFn: bff.addTab,

    onMutate(input) {
      // Current window becomes fast immediately.
      addOptimisticTab(input);
    },

    onSuccess(serverTab) {
      // Server id and order are the final facts.
      replaceOptimisticTab(serverTab);
      broadcast('TAB_LIST_INVALIDATED');
    },
  });
}

Layer 4: Runtime Cache

Problem

Users expect recently used tabs to switch back quickly, with scroll, form, and iframe state intact. But if every opened tab keeps a live runtime, the current tab slows down and memory grows without a bound.

The key is to separate three concepts that look similar in UI but have different lifecycles.

Figure A4: Three cache layers. Opened tabs are durable user intent; hot runtime pool is bounded live resource; scoped view cache keeps inner Workstream views. Idle prewarm prepares likely future switches after first screen; it is not unlimited background loading. generated by gpt-image-2.

Hot-pool update:

1
2
3
4
5
6
7
8
9
10

function onTabActivated(tabId) {
  warmPool.touch(tabId);

  for (const evicted of warmPool.evictOverflow()) {
    // Evicting runtime only frees DOM / iframe / JS resources.
    // It does not delete the opened tab from BFF.
    disposeRuntime(evicted.tabId);
  }
}

Idle prewarm:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

afterFirstScreenReady(() => {
  requestIdleCallback(() => {
    for (const candidate of selectIdlePrewarmTabs({ tabs, focusedTabId, hotTabs })) {
      if (foregroundTabIsSettling()) break;
      prewarmRuntime(candidate);
    }
  });
});

function selectIdlePrewarmTabs({ tabs, focusedTabId, hotTabs }) {
  if (!focusedTabId) return [];

  const hotIds = new Set(hotTabs.map(tab => tab.id));
  const recentIds = loadRecentHotTabIds(agentId); // get from localstorage
  // users last time opened tabs

  sortRecentTabsBeforeOtherTabs(recentIds); // prioritize recent tabs than normal tabs for prewarming

  return tabs
    .filter(tab => tab.id !== focusedTabId) // not current tab
    .filter(tab => !hotIds.has(tab.id))     // not tabs in warm pool
    .filter(tab => tab.isLocked !== true)   // not locked tab
    .slice(0, 2);                           // 2 tabs at one time
}

// 1. idle queue select candidate
candidate = {
  id: tab.id,
  location: `tab's URL`,
  runtimeKind: native / subapp / seto,
};

// 2. Put in WarmPool
warmPool.promote(candidate);

// 3. WarmPool notifies React
useWarmPool(pool) subscribe snapshot through useSyncExternalStore;

// 4. WorkspaceContentHost rerender hotTabs
hotTabs.map(tab => <HotTabFrame tab={tab} isFocused={...} />);

// 5. HotTabFrame mount runtime
<WorkstreamTabRoutes
  location={tab.location}
  tabId={tab.id}
  runtimeTabInitialLocation={tab.location}
/>

Layer 5: Isolation Boundary

Problem

After the user switches to tab B, a subapp inside tab A can still be alive in the background. If we only hide the DOM, users can still see these failures:

Figure A5: Seto integration and tab isolation. Seto loads the HTMLSandbox; the Workspace host adds tab ownership around Seto lifecycle and sandbox window boundaries. generated by gpt-image-2.

Seto Integration

Seto capabilities used:

Integration order:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

function SetoTabRuntime({ tabId, entry, initialUrl }) {
  const root = getCurrentHotTabRoot(tabId);
  let sandboxRef = null;

  return (
    <HTMLSandbox
      entry={entry}
      url={initialUrl}

      // DOM must mount into this tab's frame, not a global container.
      getContainer={() => root}

      onSandboxReady={(sandbox) => {
        sandboxRef = sandbox;

        registerRuntimeFrame({
          tabId,
          window: sandbox.raw.win,
          rawHistory: sandbox.raw.win.RAW_HISTORY,
        });

        installScopedHistory(tabId, sandbox.raw.win);
        installScopedParentProxy(tabId, sandbox.raw.win);
        installScopedEventBridge(tabId, sandbox.raw.win);
      }}
    />
  );
}

History / Window Scope

Seto architecture has a lot of history:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

function scopedPushState(state, unused, url) {
  const target = getNavigationTargetFromStateOrPreparedScope(state, url);

  if (target.tabId !== currentRuntime.tabId) {
    recordScopeDrop({
      reason: 'history-write-to-wrong-tab',
      from: currentRuntime.tabId,
      to: target.tabId,
      url,
    });
    return;
  }

  rawHistory.pushState({ ...state, workspaceTargetTabId: target.tabId }, unused, url);
}

// Seto internal raw history
frame.rawHistory.pushState = frame.patchedPushState;
frame.rawHistory.replaceState = frame.patchedReplaceState;

// Seto iframe expose to subapps' window.history
Object.defineProperty(frame.iframeWin, 'history', {
  get() {
    return frame.scopedHistory;
  },
});

window.parent is also a Proxy, not the raw host window:

1
2
3
4

parentProxy.get('history')  -> scopedHistory
parentProxy.get('document') -> scopedDocumentFacade
parentProxy.get('__workspaceMFEventBus__') -> scopedEventBus

Subapps still use the same interface shape, but every capability they receive is already scoped by tab.

Event Scope

Only receive event from active tab.

1
2
3
4
5
6
7

function publishTabLifecycle(type, targetTabId) {
  for (const runtime of runtimeRegistry.all()) {
    if (runtime.tabId !== targetTabId) continue;
    runtime.eventBus.emit(type, { tabId: targetTabId });
  }
}

DOM / Overlay Scope

The user-facing issue is simple: a popup or dropdown looks like UI of the current tab, but many libraries append it to global document.body. If the host does not intercept that, hidden tab overlays can cover the current tab or dropdowns can drift because their coordinate system changed.

Overlay types are different:

• Select, Dropdown, and Tooltip are floating overlays and need trigger-relative positioning.
• Modal, Drawer, Toast, and Notification are content overlays and should be constrained to the tab content area.
• Large-overlay geometry heuristics should only apply to position: fixed, otherwise absolute dropdowns drift.

Step 1: make document APIs resolve inside the tab

When code inside the sandbox calls:

1
2
3

document.body
document.querySelector(...)
document.getElementsByClassName(...)

we do not let it see the host’s global document by default. We resolve the current sandbox first, find its registered tab root, and answer from that root.

1
2
3
4
5
6
7
8
9
10

docUse('body', ctx => {
  return scopedRoot(ctx) ?? realDocument.body;
});

docUse('querySelector', ctx => {
  const root = scopedRoot(ctx);
  if (!root) return realDocument.querySelector(...ctx.args);

  return root.querySelector(...ctx.args);
});

Step 2: create two overlay roots for each tab

For every registered tab root, we create:

1
2
3
4
5
6

HotTabFrame(tab A)
  └── Seto app content root

workspace-overlay-root
  └── workspace-subapp-overlay-root[data-tab-id="tab A"]
        └── workspace-subapp-content-overlay-root

This split matters. A Modal should be contained with the tab, but a Dropdown often depends on trigger coordinates. If we force every overlay into the same content root, dropdowns can drift.

Step 3: intercept append and route the node

When a library does something like:

1

document.body.appendChild(node);

or Seto runtime inserts body children into the scoped root, we classify the node before keeping it there.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

function routeRuntimeBodyNode(node, tabRoot) {
  if (!isElement(node)) return;

  const target = chooseOverlayTarget(node);

  if (target) {
    target.appendChild(node);
    return;
  }

  rawAppendChild(tabRoot, node);
}

function chooseOverlayTarget(node) {
  // Dropdown / tooltip / popover / listbox must stay on the floating plane.
  if (hasFloatingDescendant(node) || isPositionedOverlay(node)) {
    return tabOverlayRoot;
  }

  // Modal / drawer / toast / large blocking UI goes to content overlay root.
  if (hasDialogDescendant(node) || isLargeOverlay(node)) {
    return tabContentOverlayRoot;
  }

  // Normal app DOM remains in the tab content root.
  return null;
}

Step 4: hide overlay roots that do not belong to the focused tab

Warm pool keeps hidden tabs mounted, so their overlay roots may still exist. On focus change, Workspace updates the visible overlay owner:

1
2
3

useLayoutEffect(() => {
  setFocusedWorkspaceOverlayTab(effectiveFocusedTabId);
}, [effectiveFocusedTabId]);

Then overlay roots are toggled by tab id:

1
2
3
4
5
6
7
8

function updateSubappOverlayFocus(root) {
  const tabId = root.getAttribute('data-workspace-overlay-tab-id');
  const visible = tabId === focusedWorkspaceOverlayTabId;

  root.style.display = visible ? '' : 'none';
  root.style.visibility = visible ? 'visible' : 'hidden';
  root.style.pointerEvents = 'none';
}

Foreground Leasing

We must protect and prioritize activated tab tasks and postpone other background tabs tasks so that the performance during switching won’t be laggy.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

// trigger: when user focus on a tab
beginWorkspaceForegroundTabTask({
  tabId: targetTabId,
  reason: 'tab_activation',
});

function beginWorkspaceForegroundTabTask({ tabId, reason }) {
  foregroundLease = {
    tabId,
    reason,
    expiresAt: Date.now() + WORKSPACE_FOREGROUND_TASK_LEASE_MS,
  };
}

// before other tabs' tasks execute, tasks like: prewarm、lifecycle prime will trigger

if (shouldDeferWorkspaceBackgroundTask({ tabId: candidate.id })) {
  scheduleNext(1000);
  return;
}

function shouldDeferWorkspaceBackgroundTask({ tabId }) {
  const lease = activeForegroundLease();

  // it is not under protect period
  if (!lease) return false;

  // null represent it is the protect period
  if (lease.tabId === null) return true;

  // only execute focused tab's tasks, others postpone.
  return tabId !== lease.tabId;
}

Layer 6: Rendered Runtimes

Problem

The user sees one current tab, but the host may keep native Workstream, Seto iframe, and MF subapp runtimes alive. If these runtimes are treated as ordinary React components, users see direct failures:

Solution

Every hot tab gets a stable frame. The frame is not decoration; it normalizes different runtimes into host semantics.

Switching becomes an ownership update:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

function commitFocusedTab(nextTabId) {
  // 1. URL owner for Seto runtimes.
  // This records which tab is currently allowed to mirror sandbox history
  // writes into the real browser address bar.
  setFocusedSetoRuntimeTab(nextTabId);

  // 2. Overlay owner.
  // Each tab-owned overlay root carries data-workspace-overlay-tab-id.
  // This shows only the overlay root for the focused tab and hides overlays
  // that still exist in hidden warm-pool tabs.
  setFocusedWorkspaceOverlayTab(nextTabId);

  // 3. Runtime owner.
  // Promote the focused tab into the warm pool. If it is already hot, refresh
  // its LRU position; if it is cold, create a HotTabFrame for it.
  warmPool.promote(nextTabId, currentLocation, runtimeKind);

  // 4. Lifecycle owner.
  // Emit TAB_BLURRED for the previous tab and TAB_FOCUSED for the next tab.
  // The payload carries tabId, so subapps and SDK listeners can ignore events
  // that do not belong to their own tab.
  publishTabLifecycleTransition(prevTabId, nextTabId);

  // 5. Metric owner.
  // Once the focused HotTabFrame is actually visible on the next animation
  // frame, mark tab-switch-visible. This separates “shell selected a tab”
  // from “the target tab is visible to the user”.
  notifyTabSwitchFrameVisible(nextTabId);
}

Key tradeoffs

The tab row is the easy part. The harder part is the ownership model: which runtime may write the URL, which tab owns DOM and overlays, which listeners receive foreground events, and which work may use foreground CPU. Once those rules are explicit, the workspace starts behaving like tabs instead of hidden pages stepping on each other.