Workspace v2 Tab System：把浏览器标签页带进工作空间

// 子应用只发意图，不碰宿主内部状态
function openSubappView(viewType, viewId) {
  emit('TAB_OPEN_REQUEST', { itemType: 'SUBAPP_VIEW', viewType, viewId });
}

// iframe 只把意图发给宿主；校验、去重和路由仍由宿主负责。
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：目标业务对象已经有自己的 tab。
  // 例子：用户要打开 view A，而 view A 的独立 tab 已经在 tab list 里。
  const existing = findExistingTab(tabs, input);

  // absorbing：当前 focused tab 是一个可承载内部 view 的 carrier。
  // 例子：用户正在某个 SubApp root / SubApp view 里打开同属一个 app 的 sibling view；
  // 这时更像“在当前 app tab 内导航”，不是“打开一个全新工作上下文”。
  const absorbing = findFocusedTabThatCanAbsorb(input);

  // 这两个概念不是重叠的：
  // - existing 处理“目标是否已经有 tab”；
  // - absorbing 处理“当前 tab 是否可以直接承接这次导航”。
  //
  // 如果当前是 subapp root，并且目标已有精确 tab，优先跳已有 tab；
  // 否则会优先吸收到当前 carrier，避免在同一个子应用里频繁开重复 runtime。
  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) {
  // 浏览器地址栏变化后，先把业务 URL 解析成“它是否属于某个 tab”。
  // appList 用来识别不同子应用的业务路由。
  const resolved = resolveTabFromUrl(location.pathname, appList);

  if (resolved.kind !== 'tab') {
    // Home、redirect、standalone fallback 这类页面不是工作 tab。
    // 它们走普通路由渲染，不创建 tab row，也不进入 hot runtime pool。
    renderSingleOutlet();
    return;
  }

  // 如果服务端 opened tabs 里已经有这个业务对象，只需要聚焦它。
  // 这里不能新增，否则刷新一次就可能多一个重复 tab。
  const matched = findOpenedTab(tabs, resolved.input);
  if (matched) {
    focusRuntime(matched.id);
    return;
  }

  // direct URL recovery:
  // 用户打开的是一个业务 URL，但 BFF 里还没有对应 tab。
  // 宿主要补开 tab，否则页面会变成“没有 tab 行归属”的孤儿页面。
  addTab(toAddWorkspaceTabRequest(resolved.input));
  focusRuntimeWhenReady(resolved.input);
}

function activateTab(tab) {
  // 每个 tab 都记住自己上一次停留的业务 URL。
  // 例如用户在 Workstream tab 内切到了某个 view，下次点回这个 tab 应该回到那个 view，
  // 而不是永远回到 Workstream 默认页。
  const path = loadSavedTabUrl(tab.id) ?? buildDefaultBusinessUrl(tab);

  // 从点击开始计时。后面会分别记录 frame visible、interactive、settled，
  // 防止“页面显示了但还不能点”的时间被旧指标漏掉。
  startTabSwitchMetric({ toId: tab.id, targetPath: path });

  // 告诉沙箱 / iframe 的 history scope：
  // 接下来这次 URL 写入属于目标 tab，而不是某个 hidden runtime 的越界写入。
  prepareScopedNavigation({ targetTabId: tab.id, url: path });

  navigate(path, {
    // React Router 只看到一个全局 history。
    // 这里把目标 tab id 写进 history.state，后续 popstate / hashchange / 沙箱 history
    // 才能判断这次导航应该投递给哪个 runtime。
    state: { workspaceTargetTabId: tab.id },

    // tab 激活是用户输入的直接结果，必须尽快让 focused frame 和 URL 对齐。
    flushSync: true,
  });
}

function onTabMutationSuccess() {
  // 本窗口的缓存先失效。
  queryClient.invalidateQueries(WORKSPACE_TABS_KEY);

  // 其它窗口没有共享 React state，只能收到一个“事实变了”的通知后自己重拉。
  broadcastChannel.postMessage({ type: 'TABS_INVALIDATED' });
}

function onOtherWindowInvalidated() {
  queryClient.invalidateQueries(WORKSPACE_TABS_KEY);
}

function addWorkspaceTab(input) {
  queryClient.setQueryData(WORKSPACE_TABS_KEY, tabs => [
    ...tabs,
    makeTempLockedTab(input),
  ]);

  post('/workspace/api/tab/add', input)
    .then(serverTab => replaceTempTab(serverTab))
    .finally(() => broadcastTabsInvalidated());
}

class WarmPool {
  promote(tabId, location, runtimeKind) {
    // 用户聚焦或预热命中时，把这个 tab 放进 hot set。
    hot.set(tabId, { tabId, location, runtimeKind, lastFocusedAt: now() });

    // iframe 沙箱更重，所以有单独上限；全局 hot frame 也有总上限。
    // 淘汰只会卸载 runtime，不会删除 opened tab。
    evictOldestSandboxIfOverCap();
    evictOldestHotFrameIfOverGlobalCap();

    notifySubscribers();
  }
}

if (resolved.kind === 'nonTab') {
  // 非 tab 页面走普通路由，不放进 HotTabStack。
  return <Outlet />;
}

return (
  <HotTabStack>
    {hotTabs.map(tab => (
      <HotTabFrame
        tab={tab}
        // 只有 focused tab 可见、可交互；其它 hot tab 保留 runtime，但不接收前台事件。
        isFocused={tab.id === focusedTabId}

        // focused tab 用当前浏览器 URL；后台 hot tab 用自己上次保存的 URL。
        location={tab.id === focusedTabId ? currentLocation : tab.location}
      />
    ))}
  </HotTabStack>
);

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

  return sortRecentTabsBeforeOtherTabs(tabs, recentIds)
    .filter(tab => tab.id !== focusedTabId)
    .filter(tab => !hotIds.has(tab.id))
    .filter(tab => tab.isLocked !== true)
    .slice(0, 2);
}

// 1. idle queue 选出 candidate。
const candidate = {
  id: tab.id,
  location: tab.location,
  runtimeKind: tab.runtimeKind, // native / subapp / sandbox
};

// 2. WarmPool promote 这个 candidate。
warmPool.promote(candidate);

// 3. React 通过 useSyncExternalStore 订阅 WarmPool。
const hotTabs = useWarmPool(warmPool);

// 4. WorkspaceContentHost 重新渲染 hot tab 列表。
hotTabs.map(tab => <HotTabFrame key={tab.id} tab={tab} />);

// 5. HotTabFrame 在用户点回前先把 runtime mount 好。

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

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

      // DOM 必须挂到这个 tab 的 frame 里，不能挂到全局容器。
      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);
}

// 沙箱内部的 raw history 才是 sandbox 真正使用的 surface。
frame.rawHistory.pushState = frame.patchedPushState;
frame.rawHistory.replaceState = frame.patchedReplaceState;

// 子应用仍然看到 window.history，但拿到的是 scopedHistory。
Object.defineProperty(frame.iframeWin, 'history', {
  get() {
    return frame.scopedHistory;
  }
});

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

function addEventListener(type, listener) {
  if (type !== 'popstate' && type !== 'hashchange') {
    return rawAddEventListener(type, listener);
  }

  rawAddEventListener(type, event => {
    if (resolveTargetTabForEvent(event) === currentFrame.tabId) {
      listener(event);
    } else {
      reportScopeDrop('event_drop');
    }
  });
}

scopedEventBus.listen(listener) {
  if (!listener.listensTo('TAB_FOCUSED', 'TAB_BLURRED')) {
    return hostBus.listen(listener);
  }

  return hostBus.listen(payload => {
    if (payload.data.tabId === currentFrame.tabId) {
      listener(payload);
    }
  });
}

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

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

  const target = chooseOverlayTarget(node);

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

  rawAppendChild(tabRoot, node);
}

function chooseOverlayTarget(node) {
  if (hasFloatingDescendant(node) || isPositionedOverlay(node)) {
    return tabOverlayRoot;
  }

  if (hasDialogDescendant(node) || isLargeOverlay(node)) {
    return tabContentOverlayRoot;
  }

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

// 用户聚焦 tab 时触发。
beginWorkspaceForegroundTabTask({
  tabId: targetTabId,
  reason: 'tab_activation',
});

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

// prewarm / lifecycle prime 等后台任务执行前先检查：
if (shouldDeferWorkspaceBackgroundTask({ tabId: candidate.id })) {
  scheduleNext(1000);
  return;
}

function shouldDeferWorkspaceBackgroundTask({ tabId }) {
  const lease = activeForegroundLease();
  if (!lease) return false;
  if (lease.tabId === null) return true;
  return tabId !== lease.tabId;
}

function HotTabFrame({ tab, isFocused, location }) {
  return (
    <section
      data-hot-tab-id={tab.id}
      style={{
        visibility: isFocused ? 'visible' : 'hidden',
        pointerEvents: isFocused ? 'auto' : 'none',
      }}
    >
      {/* focused tab 用当前 URL；hidden hot tab 用保存的 location。 */}
      <Routes location={location}>
        <WorkstreamTabRoutes />
      </Routes>
    </section>
  );
}

function commitFocusedTab(nextTabId) {
  // 1. 沙箱 runtime 的 URL owner。
  setFocusedSandboxRuntimeTab(nextTabId);

  // 2. overlay owner。
  setFocusedWorkspaceOverlayTab(nextTabId);

  // 3. runtime owner。
  warmPool.promote(nextTabId, currentLocation, runtimeKind);

  // 4. lifecycle owner。
  publishTabLifecycleTransition(prevTabId, nextTabId);

  // 5. metric owner。
  notifyTabSwitchFrameVisible(nextTabId);
}