Background And Goals

Workspace v2 changes the workbench from a single-page, single-context product into a workspace that can hold multiple workstreams, sub-application views, and ticket objects at the same time. From the user’s perspective, the expected experience is close to a browser: several tasks stay open, switching back keeps state, refresh and shared links still land on the right business page, and a modal opened by one sub-application cannot cover another tab.

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.

Business goals:

Technical goals:

Figure A1: Product goals mapped to engineering constraints. The diagram breaks “browser-grade tabs” into concrete system requirements and failure modes.

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.

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

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

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);
}

existing and absorb are not the same feature. existing means “the target already has a stable tab”; absorb means “the current tab does not yet need a new runtime and can carry this navigation.” Without absorb, a placeholder or subapp root would leave useless tabs behind. Without existing, a real duplicate tab would be created.

Difficulty

The difficult part is not sending an event. It is making every entry point converge to the same find / absorb / add / focus / capacity-control path. Otherwise the user sees duplicate tabs, wrong focus, capacity bypass, and inconsistent return paths.

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.

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

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.
  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' });
}

Difficulty

URL is both a user contract and a runtime locator. Users must see shareable business URLs, while the host must know which tab owns a URL change. The resolver and activation state satisfy both constraints.

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.

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.

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');
    },
  });
}

Difficulty

Optimistic UI can reduce interaction latency, but it cannot replace the server fact. Final tab id, pin state, order, and cross-window consistency must return to the BFF tab list.

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.

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

afterFirstScreenReady(() => {
  requestIdleCallback(() => {
    for (const candidate of predictLikelyNextTabs()) {
      if (foregroundTabIsSettling()) break;
      prewarmRuntime(candidate);
    }
  });
});

Difficulty

Keeping everything alive is simple but turns background runtimes into unbounded resource consumers. Keeping nothing alive is safe but destroys the browser-like switch experience. The design preserves user intent in opened tabs while putting a hard cap on live runtimes.

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.

Seto Integration: Start From The Failure

We did not start from a list of Seto APIs. We started from the invariant users need, then mapped each failure to the platform capability we had to wrap.

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

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

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);
}

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

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.

1
2
3
4
5
6
7
8
9
10
11
12

function appendChild(parent, node) {
  const owner = resolveOwnerFromCurrentSandboxCallStack();

  if (parent === rawDocument.body && owner) {
    const overlayRoot = getOverlayRoot(owner.tabId, node);
    overlayRoot.appendChild(node);
    return node;
  }

  return rawAppendChild(parent, node);
}

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.

Difficulty

A hidden runtime can still produce visible side effects. Without tab owner boundaries around sandbox window and document APIs, “hidden” only means invisible; it does not mean safe.

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.

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

function HotTabFrame({ tab, isFocused, location }) {
  return (
    <section
      data-hot-tab-id={tab.id}
      style={{
        visibility: isFocused ? 'visible' : 'hidden',
        pointerEvents: isFocused ? 'auto' : 'none',
      }}
    >
      <Routes location={location}>
        <WorkstreamTabRoutes />
        <SetoHTMLApp />
        <MFSubAppFrame />
      </Routes>
    </section>
  );
}

Switching becomes an ownership update:

1
2
3
4
5
6
7
8

function commitFocusedTab(nextTabId) {
  setVisibleFrame(nextTabId);
  setRuntimeOwner(nextTabId);
  setOverlayOwner(nextTabId);
  publishTabLifecycle('TAB_FOCUSED', nextTabId);
  reportTabSwitchVisible(nextTabId);
}

Difficulty

The focused tab visible to the user must match router location, runtime owner, overlay owner, event owner, and metric owner. If any of them lags behind, the user sees B while the background still behaves like A.

Key Tradeoffs

The design is not a tab bar with a more complex UI. A normal tab bar decides which panel is visible. This system also decides which runtime can write the URL, show overlays, receive events, and consume foreground resources.