Workspace v2 tab system: browser tabs inside a workspace

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

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

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 the iframe sandbox 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,
  });
}

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

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

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

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 / sandbox,
};

// 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}
/>

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

  return (
    <Sandbox
      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);
      }}
    />
  );
}

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

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

// the sandbox iframe exposes this to subapps as window.history
Object.defineProperty(frame.iframeWin, 'history', {
  get() {
    return frame.scopedHistory;
  },
});

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

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

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

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

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

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

document.body.appendChild(node);

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

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

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

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

function commitFocusedTab(nextTabId) {
  // 1. URL owner for sandbox runtimes.
  // This records which tab is currently allowed to mirror sandbox history
  // writes into the real browser address bar.
  setFocusedSandboxRuntimeTab(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);
}