@hienlh/ppm 0.18.10 → 0.18.12

package/src/web/components/ui/select.tsx

@@ -3,6 +3,7 @@ import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react"
 import { Select as SelectPrimitive } from "radix-ui"
 
 import { cn } from "@/lib/utils"
+import { usePortalContainer } from "./portal-container-context"
 
 function Select({
   ...props
@@ -55,8 +56,9 @@ function SelectContent({
   align = "center",
   ...props
 }: React.ComponentProps<typeof SelectPrimitive.Content>) {
+  const container = usePortalContainer()
   return (
-    <SelectPrimitive.Portal>
+    <SelectPrimitive.Portal container={container}>
       <SelectPrimitive.Content
         data-slot="select-content"
         className={cn(

package/src/web/components/ui/tooltip.tsx

@@ -4,6 +4,7 @@ import * as React from "react"
 import { Tooltip as TooltipPrimitive } from "radix-ui"
 
 import { cn } from "@/lib/utils"
+import { usePortalContainer } from "./portal-container-context"
 
 function TooltipProvider({
   delayDuration = 0,
@@ -36,8 +37,9 @@ function TooltipContent({
   children,
   ...props
 }: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  const container = usePortalContainer()
   return (
-    <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Portal container={container}>
       <TooltipPrimitive.Content
         data-slot="tooltip-content"
         sideOffset={sideOffset}

package/src/web/hooks/use-terminal.ts

@@ -8,6 +8,7 @@ import { useSettingsStore } from "@/stores/settings-store";
 import { buildXtermTheme } from "@/theme/adapters/xterm-adapter";
 import { resolveTheme as resolvePpmTheme } from "@/theme/resolve-theme";
 import { getCurrentAppliedTheme, THEME_CHANGE_EVENT } from "@/theme/apply-theme";
+import { onHostResize } from "@/components/floating-window/pip/pip-resize-signal";
 import type { PpmTheme } from "@/theme/types";
 
 /** Current active PpmTheme → xterm ITheme (prefers the live applied theme). */
@@ -400,10 +401,17 @@ export function useTerminal(
 
     // Keepalive heartbeat + zombie detection (covers suspend/sleep/network drop)
     const heartbeatInterval = setInterval(checkConnection, HEARTBEAT_INTERVAL_MS);
+    // Always the main document: a tab mounts there and is only moved into a
+    // picture-in-picture window afterwards, and this is resolved once at mount.
+    // So a terminal that is visible in PiP while the main tab is hidden is still
+    // treated as hidden and does not reconnect until the main tab comes back —
+    // checkConnection() reads the main document's visibility directly too, so
+    // re-resolving this one would not change that on its own.
+    const hostDoc = container.ownerDocument;
     const onVisibility = () => {
-      if (document.visibilityState === "visible") checkConnection();
+      if (hostDoc.visibilityState === "visible") checkConnection();
     };
-    document.addEventListener("visibilitychange", onVisibility);
+    hostDoc.addEventListener("visibilitychange", onVisibility);
 
     // ResizeObserver for auto-fit — skip when tab is hidden (0 dimensions).
     // Debounced: an on-screen keyboard resizes the container many times as it
@@ -426,6 +434,18 @@ export function useTerminal(
     });
     resizeObserver.observe(container);
 
+    // Host-driven resize (picture-in-picture): the ResizeObserver above only
+    // reports a PiP-driven size seconds later, so refit as soon as the host says
+    // its size changed.
+    const unsubHostResize = onHostResize(container, () => {
+      try {
+        fitAddon.fit();
+        sendResize();
+      } catch {
+        // Ignore fit errors while the tab is detached or tearing down
+      }
+    });
+
     // React to theme changes — the theme-change event fires after CSS vars are
     // applied, covering style, mode, system-OS, and imported-theme swaps.
     const onThemeChange = () => { term.options.theme = currentXtermTheme(); };
@@ -434,10 +454,11 @@ export function useTerminal(
 
     return () => {
       unsubTheme();
+      unsubHostResize();
       if (fitTimer) clearTimeout(fitTimer);
       resizeObserver.disconnect();
       clearInterval(heartbeatInterval);
-      document.removeEventListener("visibilitychange", onVisibility);
+      hostDoc.removeEventListener("visibilitychange", onVisibility);
       if (reconnectTimer.current) clearTimeout(reconnectTimer.current);
       if (readyQuietTimer.current) clearTimeout(readyQuietTimer.current);
       if (readyMaxTimer.current) clearTimeout(readyMaxTimer.current);

package/src/web/stores/panel-store.ts

@@ -17,7 +17,17 @@ import {
   deriveTabId,
   visibleTabs,
   DOCK_PANEL_ID,
+  isWindowPanelId,
 } from "./panel-utils";
+import {
+  makePopOutTab,
+  makeRedockFromWindow,
+  hydrateWindowPanels,
+  stripProjectFromWindowPanels,
+  syncWindowPanel,
+} from "./window-panel-actions";
+import { saveWindowPanels } from "./window-panel-persistence";
+import { useWindowStore } from "@/components/floating-window/window-store";
 import {
   makeToggleDock,
   makeSetDockVisible,
@@ -120,6 +130,16 @@ export interface PanelStore {
   /** Park a terminal from a grid panel into __dock__ without killing the PTY session. */
   redockTab: (tabId: string, fromPanelId: string) => void;
 
+  // Floating-window actions
+  /**
+   * Detach a tab into a floating window, returning the window id — or null when the
+   * request is rejected (mobile, a tab type that cannot detach, or the window cap),
+   * in which case nothing changed and the caller reports it.
+   */
+  popOutTab: (tabId: string, fromPanelId: string) => string | null;
+  /** Send a window's tabs back to the grid and drop its panel. Runs on window close. */
+  redockFromWindow: (windowId: string, originPanelId?: string | null) => void;
+
   // Helpers
   getPanelForTab: (tabId: string) => Panel | undefined;
   isMobile: () => boolean;
@@ -171,6 +191,22 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
     return panelId ?? get().focusedPanelId;
   }
 
+  /**
+   * The focus to commit when a tab was activated in `pid`.
+   *
+   * Focus decides where the next `openTab()` with no explicit panel lands, and a
+   * floating window renders no tab bar — a tab opened inside one would be unreachable
+   * until the window closes, and the id would be persisted with the layout. So
+   * activating a tab that lives in a window leaves focus where it was: the window is
+   * already in front of the user, nothing more is needed to "focus" it.
+   *
+   * Every caller here picks `pid` by scanning the whole `panels` map, which includes
+   * the off-grid window panels.
+   */
+  function focusAfterActivate(pid: string): string {
+    return isWindowPanelId(pid) ? get().focusedPanelId : pid;
+  }
+
   return {
     ...defaultLayout(),
     currentProject: null,
@@ -188,8 +224,13 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
     toggleDockExpanded: () => set((s) => ({ dockExpanded: !s.dockExpanded })),
     openInDock: makeOpenInDock(set, get),
     redockTab: makeRedockTab(set, get),
+    popOutTab: makePopOutTab(set, get),
+    redockFromWindow: makeRedockFromWindow(set, get),
 
     switchProject: (projectName) => {
+      // Window panels are global, not part of any project's layout blob, so they are
+      // merged into the flat map once — before the first project reads it.
+      hydrateWindowPanels(set, get);
       const { currentProject, panels, grid, focusedPanelId, projectGrids, projectFocused, dock, projectDock } = get();
 
       // No-op if same project
@@ -401,18 +442,26 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
         };
       }
 
+      // A window panel is off-grid, so the loop above never reaches it: a floating
+      // window would keep showing a tab of a project that no longer exists.
+      const stripped = stripProjectFromWindowPanels(cleanedPanels, projectName);
+
       set({
         projectGrids: newGrids,
         projectFocused: newFocused,
         projectDock: newProjectDock,
-        panels: cleanedPanels,
+        panels: stripped.panels,
         currentProject: null,
       });
+      saveWindowPanels(stripped.panels);
+      for (const windowId of stripped.windowIdsToClose) useWindowStore.getState().close(windowId);
       // Re-trigger full load from localStorage
       get().switchProject(projectName);
     },
 
     setFocusedPanel: (panelId) => {
+      // Focus drives where the next tab opens, so it must stay on a real, on-grid panel.
+      if (isWindowPanelId(panelId)) return;
       if (get().panels[panelId]) set({ focusedPanelId: panelId });
     },
 
@@ -451,7 +500,7 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
           const existing = p.tabs.find((t) => t.type === "chat" && t.metadata?.sessionId === sid);
           if (existing) {
             set((s) => ({
-              focusedPanelId: p.id,
+              focusedPanelId: focusAfterActivate(p.id),
               panels: {
                 ...s.panels,
                 [p.id]: { ...p, tabs: stampActive(p.tabs, existing.id), activeTabId: existing.id, tabHistory: pushHistory(p.tabHistory, existing.id) },
@@ -469,7 +518,7 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
           const existing = p.tabs.find((t) => t.id === baseId);
           if (existing) {
             set((s) => ({
-              focusedPanelId: p.id,
+              focusedPanelId: focusAfterActivate(p.id),
               panels: {
                 ...s.panels,
                 [p.id]: {
@@ -581,8 +630,12 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
         // no-op for it) so the map-delete would destroy the reserved dock panel, and a
         // later redock (moveTab → __dock__) would silently no-op (to === undefined),
         // leaving the terminal stuck in the grid while an empty dock opens.
+        // A window panel is exempt from the "keep the last panel" rule: that rule
+        // protects the grid from ending up with nothing to render, and a window panel
+        // is not in the grid. Leaving it behind would strand an empty floating window.
         const gridPanelCount = s.grid.flat().length;
-        if (newTabs.length === 0 && gridPanelCount > 1 && pid !== DOCK_PANEL_ID) {
+        const removable = isWindowPanelId(pid) || (gridPanelCount > 1 && pid !== DOCK_PANEL_ID);
+        if (newTabs.length === 0 && removable) {
           const { [pid]: _, ...rest } = s.panels;
           const newGrid = gridRemovePanel(s.grid, pid);
           // Focus must land on a panel still in the grid — Object.keys(rest)
@@ -603,6 +656,9 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
       if (pid === DOCK_PANEL_ID && activeProjectDockTabCount(get) === 0) {
         get().setDockVisible(false);
       }
+
+      // A window that lost its last tab closes with it — it can never show anything again.
+      if (isWindowPanelId(pid)) syncWindowPanel(set, get, pid);
     },
 
     setActiveTab: (tabId, panelId?) => {
@@ -612,7 +668,7 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
       set((s) => {
         const p = s.panels[pid]!;
         return {
-          focusedPanelId: pid,
+          focusedPanelId: focusAfterActivate(pid),
           panels: { ...s.panels, [pid]: { ...p, tabs: stampActive(p.tabs, tabId), activeTabId: tabId, tabHistory: pushHistory(p.tabHistory, tabId) } },
         };
       });
@@ -667,8 +723,13 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
         // Auto-close empty source panel if not last in current grid.
         // Guard: never attempt to remove __dock__ from the grid — it is intentionally
         // absent from grid and gridRemovePanel would be a no-op, but the panels-map
-        // delete would destroy the dock panel entirely.
-        if (fromTabs.length === 0 && gridPanelCount > 1 && fromPanelId !== DOCK_PANEL_ID) {
+        // delete would destroy the dock panel entirely. The dock is reserved and outlives
+        // its tabs; only its visibility follows them.
+        // A window panel is skipped for a different reason: its lifetime belongs to the
+        // floating window, so syncWindowPanel below drops it together with the window
+        // rather than leaving an open, empty one behind.
+        const offGridSource = fromPanelId === DOCK_PANEL_ID || isWindowPanelId(fromPanelId);
+        if (fromTabs.length === 0 && gridPanelCount > 1 && !offGridSource) {
           const { [fromPanelId]: _, ...rest } = s.panels;
           return {
             panels: {
@@ -690,6 +751,10 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
         };
       });
       persist();
+
+      // Moving the last tab out of a window empties it exactly as closing that tab would,
+      // and the window has no tab bar to fill itself from — same owner, same outcome.
+      if (isWindowPanelId(fromPanelId)) syncWindowPanel(set, get, fromPanelId);
     },
 
     splitPanel: (direction, tabId, sourcePanelId, targetPanelId?) => {

package/src/web/stores/panel-utils.ts

@@ -29,6 +29,42 @@ export const DOCK_PANEL_ID = "__dock__";
  */
 export const DOCK_ALLOWED_TAB_TYPES = new Set<TabType>(["terminal", "system-monitor"]);
 
+// ---------------------------------------------------------------------------
+// Floating-window panels
+// ---------------------------------------------------------------------------
+
+/**
+ * Prefix of the reserved panel IDs that host tabs detached into a floating window.
+ * Like the dock, such a panel lives in the `panels` map but is intentionally excluded
+ * from `grid`, so all grid math (MAX_ROWS, split, column count) ignores it. The
+ * window id is the suffix, which is what ties the panel to its window.
+ */
+export const WINDOW_PANEL_PREFIX = "__win__:";
+
+/** Panel ID hosting the tabs of the floating window `windowId`. */
+export function windowPanelId(windowId: string): string {
+  return `${WINDOW_PANEL_PREFIX}${windowId}`;
+}
+
+export function isWindowPanelId(panelId: string): boolean {
+  return panelId.startsWith(WINDOW_PANEL_PREFIX);
+}
+
+/** The window a panel belongs to, or null when it is not a window panel. */
+export function windowIdFromPanelId(panelId: string): string | null {
+  return isWindowPanelId(panelId) ? panelId.slice(WINDOW_PANEL_PREFIX.length) || null : null;
+}
+
+/** Create the off-grid panel for a floating window, with an empty tab list. */
+export function createWindowPanel(windowId: string): Panel {
+  return {
+    id: windowPanelId(windowId),
+    tabs: [],
+    activeTabId: null,
+    tabHistory: [],
+  };
+}
+
 /** Visible/height state for the dock — stored per-project via projectDock map. */
 export interface DockState {
   visible: boolean;

package/src/web/stores/window-panel-actions.ts

@@ -0,0 +1,211 @@
+/**
+ * Action factories for tabs that live in a floating window, for usePanelStore.
+ *
+ * Extracted to keep panel-store.ts near its size budget, mirroring dock-actions.ts.
+ * This module is the ONLY writer of `__win__:` panels, which is what keeps the
+ * invariant cheap to check: a window panel exists in the `panels` map and never in
+ * `grid`, so no grid math (MAX_ROWS, split, column count) can ever see one.
+ *
+ * Second invariant, enforced after every move: `focusedPanelId` is never a window
+ * panel. `moveTab` focuses its target unconditionally, and `resolvePanel()` sends the
+ * next `openTab()` with no explicit panel to the focused one — leaving focus on the
+ * window would silently open new tabs inside it.
+ */
+import type { StoreApi } from "zustand";
+import type { Panel } from "./panel-utils";
+import {
+  createWindowPanel,
+  isWindowPanelId,
+  windowIdFromPanelId,
+  windowPanelId,
+} from "./panel-utils";
+import { persistDock } from "./dock-actions";
+import { loadWindowPanels, saveWindowPanels } from "./window-panel-persistence";
+import { useWindowStore } from "@/components/floating-window/window-store";
+import { MAX_WINDOWS } from "@/components/floating-window/window-geometry";
+import type { PanelStore } from "./panel-store";
+
+type Set = StoreApi<PanelStore>["setState"];
+type Get = StoreApi<PanelStore>["getState"];
+
+/** Tab types that never detach — the monitor already owns a window kind of its own. */
+const NON_POPPABLE_TAB_TYPES = new Set(["system-monitor"]);
+
+/**
+ * A grid panel to hold focus: the preferred one when it is still in the grid, else the
+ * first grid panel. Returns null only for an empty grid (nothing can be focused).
+ */
+function gridFocusTarget(grid: string[][], preferred?: string | null): string | null {
+  const flat = grid.flat();
+  if (preferred && flat.includes(preferred)) return preferred;
+  return flat[0] ?? null;
+}
+
+/**
+ * Persist both halves of a window-panel mutation: the global window-panel blob and the
+ * active project's layout (the other side of a move is a grid panel). persistDock writes
+ * the whole PanelLayout — grid panels, focus and dock — not just the dock.
+ */
+export function persistWindowPanelChange(get: Get): void {
+  saveWindowPanels(get().panels);
+  persistDock(get);
+}
+
+/**
+ * Keep a floating window and its panel in lockstep after a tab left the panel: an empty
+ * tab-host window has no way back to a tab, so it closes with its panel.
+ *
+ * Every way a tab can leave — closed, moved to the grid or the dock, dragged out — ends
+ * here, so the panel and the window are created and destroyed by the same two functions.
+ * Both halves are idempotent: a panel already dropped by the caller and a window already
+ * closed are both no-ops.
+ */
+export function syncWindowPanel(set: Set, get: Get, panelId: string): void {
+  if (get().panels[panelId]?.tabs.length) {
+    saveWindowPanels(get().panels);
+    return;
+  }
+  set((s) => {
+    const { [panelId]: _dropped, ...rest } = s.panels;
+    return { panels: rest };
+  });
+  saveWindowPanels(get().panels);
+  const windowId = windowIdFromPanelId(panelId);
+  if (windowId) useWindowStore.getState().close(windowId);
+}
+
+/**
+ * Merge the persisted window panels into the flat panels map, once per session.
+ *
+ * They are global, so this runs on the first project load and never again — a later
+ * switch must not resurrect a panel the user has since re-docked. Live panels win the
+ * merge; a stale persisted twin can only be older than what is in memory.
+ */
+let windowPanelsHydrated = false;
+
+export function hydrateWindowPanels(set: Set, get: Get): void {
+  if (windowPanelsHydrated) return;
+  windowPanelsHydrated = true;
+  const loaded = loadWindowPanels();
+  if (Object.keys(loaded).length === 0) return;
+  set({ panels: { ...loaded, ...get().panels } });
+}
+
+/**
+ * Detach a tab into a new floating window. Returns the window id, or null when the
+ * request is rejected — in which case nothing is mutated and the caller reports it.
+ */
+export function makePopOutTab(set: Set, get: Get) {
+  return function popOutTab(tabId: string, fromPanelId: string): string | null {
+    // The window layer is desktop-only; on mobile a detached tab would be invisible.
+    if (get().isMobile()) return null;
+
+    const from = get().panels[fromPanelId];
+    const tab = from?.tabs.find((t) => t.id === tabId);
+    if (!tab || NON_POPPABLE_TAB_TYPES.has(tab.type)) return null;
+
+    // Pre-check the cap: at the cap `open()` focuses the oldest window and returns ITS
+    // id, which would attach this tab to an unrelated window.
+    const windowStore = useWindowStore.getState();
+    if (Object.keys(windowStore.windows).length >= MAX_WINDOWS) return null;
+
+    const windowId = windowStore.open("tab-host", { originPanelId: fromPanelId, title: tab.title });
+    const panelId = windowPanelId(windowId);
+    set((s) => ({ panels: { ...s.panels, [panelId]: createWindowPanel(windowId) } }));
+
+    get().moveTab(tabId, fromPanelId, panelId);
+
+    const focus = gridFocusTarget(get().grid, fromPanelId);
+    if (focus) set({ focusedPanelId: focus });
+    persistWindowPanelChange(get);
+    return windowId;
+  };
+}
+
+/**
+ * Send every tab of a window's panel back to the grid and drop the panel.
+ *
+ * Called from the window body's layout-effect cleanup, so it covers every close path
+ * (titlebar ×, keyboard close, a programmatic `close()`), and is a no-op once the panel
+ * is gone — closing an emptied window re-enters here and must not resurrect anything.
+ */
+export function makeRedockFromWindow(set: Set, get: Get) {
+  return function redockFromWindow(windowId: string, originPanelId?: string | null): void {
+    const panelId = windowPanelId(windowId);
+    const panel = get().panels[panelId];
+    if (!panel) return;
+
+    const target = redockTarget(get(), originPanelId);
+    if (target) {
+      for (const tab of [...panel.tabs]) get().moveTab(tab.id, panelId, target);
+    }
+
+    set((s) => {
+      const { [panelId]: _dropped, ...rest } = s.panels;
+      // moveTab focused the target; re-assert it here so the resolved target wins even
+      // when the last moveTab picked a different one (or none ran at all).
+      const focus = gridFocusTarget(s.grid, target ?? s.focusedPanelId);
+      return focus ? { panels: rest, focusedPanelId: focus } : { panels: rest };
+    });
+    persistWindowPanelChange(get);
+
+    // The body can unmount without the window closing: the whole desktop window layer is
+    // dropped below the `md` breakpoint, which re-docks the tabs but would leave the
+    // window entry in `ppm-windows` — restored empty and unfillable on the way back, and
+    // burning one of MAX_WINDOWS on every reload. `close()` is a no-op when the window is
+    // already gone (the ×/keyboard paths), and re-entry here returns early: the panel is
+    // deleted above.
+    useWindowStore.getState().close(windowId);
+  };
+}
+
+/**
+ * Where a detached tab goes home to: its origin panel while that still exists, else the
+ * focused panel when it is a grid panel, else the first grid panel. The origin may be the
+ * dock (a terminal parked there before it was detached) but never another window.
+ */
+function redockTarget(state: PanelStore, originPanelId?: string | null): string | null {
+  if (originPanelId && state.panels[originPanelId] && !isWindowPanelId(originPanelId)) {
+    return originPanelId;
+  }
+  return gridFocusTarget(state.grid, state.focusedPanelId);
+}
+
+/**
+ * Drop a project's tabs from every window panel, returning the panels map to commit and
+ * the windows whose panel is now empty. Used when a project is reloaded: its grid panels
+ * are discarded, and a window still showing one of its tabs would outlive the project.
+ */
+export function stripProjectFromWindowPanels(
+  panels: Record<string, Panel>,
+  projectName: string,
+): { panels: Record<string, Panel>; windowIdsToClose: string[] } {
+  const next: Record<string, Panel> = { ...panels };
+  const windowIdsToClose: string[] = [];
+
+  for (const [id, panel] of Object.entries(panels)) {
+    if (!isWindowPanelId(id)) continue;
+    const tabs = panel.tabs.filter((t) => t.projectId !== projectName);
+    if (tabs.length === panel.tabs.length) continue;
+
+    const windowId = windowIdFromPanelId(id);
+    if (tabs.length === 0) {
+      delete next[id];
+      if (windowId) windowIdsToClose.push(windowId);
+      continue;
+    }
+    const ids = new Set(tabs.map((t) => t.id));
+    const tabHistory = panel.tabHistory.filter((h) => ids.has(h));
+    next[id] = {
+      ...panel,
+      tabs,
+      tabHistory,
+      activeTabId:
+        panel.activeTabId && ids.has(panel.activeTabId)
+          ? panel.activeTabId
+          : (tabHistory[tabHistory.length - 1] ?? tabs[tabs.length - 1]!.id),
+    };
+  }
+
+  return { panels: next, windowIdsToClose };
+}

package/src/web/stores/window-panel-persistence.ts

@@ -0,0 +1,115 @@
+/**
+ * localStorage persistence for the off-grid panels that host detached tabs.
+ *
+ * Deliberately its own global key instead of a field inside `PanelLayout`: floating
+ * windows are global (one `ppm-windows` blob for the whole app) while a PanelLayout is
+ * per project. Folding a global panel into a per-project blob is what forced the
+ * merge/union machinery the dock needs on every project switch. Consequence, accepted:
+ * window panels are not synced to the server workspace — the same limitation the window
+ * geometry already has.
+ */
+import type { Panel } from "./panel-utils";
+import { isWindowPanelId } from "./panel-utils";
+import type { Tab, TabType } from "./tab-store";
+
+const STORAGE_KEY = "ppm-window-panels";
+
+/**
+ * Tab types a persisted window panel may bring back. Written as an exhaustive record so
+ * adding a TabType is a compile error here rather than a silent gap. `system-monitor` is
+ * false because it can never be popped out; everything else a crafted blob names is
+ * rejected, so it cannot mount an arbitrary component in the privileged window slot.
+ */
+const POPPABLE_TAB_TYPES: Record<TabType, boolean> = {
+  terminal: true,
+  chat: true,
+  editor: true,
+  database: true,
+  sqlite: true,
+  postgres: true,
+  "git-diff": true,
+  settings: true,
+  extension: true,
+  "extension-webview": true,
+  "conflict-editor": true,
+  "system-monitor": false,
+  "git-log": true,
+  "ai-resource": true,
+  group: true,
+};
+
+export function isPoppableTabType(type: unknown): type is TabType {
+  return typeof type === "string" && POPPABLE_TAB_TYPES[type as TabType] === true;
+}
+
+function isValidTab(value: unknown): value is Tab {
+  if (!value || typeof value !== "object") return false;
+  const t = value as Record<string, unknown>;
+  return typeof t.id === "string" && !!t.id && typeof t.title === "string" && isPoppableTabType(t.type);
+}
+
+/** Keep only the window panels out of the full panels map, dropping empty ones. */
+function selectWindowPanels(panels: Record<string, Panel>): Record<string, Panel> {
+  const out: Record<string, Panel> = {};
+  for (const [id, panel] of Object.entries(panels)) {
+    if (!isWindowPanelId(id) || panel.tabs.length === 0) continue;
+    out[id] = panel;
+  }
+  return out;
+}
+
+export function saveWindowPanels(panels: Record<string, Panel>): void {
+  try {
+    const windowPanels = selectWindowPanels(panels);
+    if (Object.keys(windowPanels).length === 0) localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, JSON.stringify(windowPanels));
+  } catch {
+    /* quota exceeded or storage disabled — never block a tab move over persistence */
+  }
+}
+
+/** Read persisted window panels, dropping anything malformed or not allowed in a window. */
+export function loadWindowPanels(): Record<string, Panel> {
+  let raw: string | null = null;
+  try {
+    raw = localStorage.getItem(STORAGE_KEY);
+  } catch {
+    return {};
+  }
+  if (!raw) return {};
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+
+  const out: Record<string, Panel> = {};
+  for (const [id, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (!isWindowPanelId(id) || !value || typeof value !== "object") continue;
+    const panel = value as Record<string, unknown>;
+    if (!Array.isArray(panel.tabs)) continue;
+    const tabs = panel.tabs.filter(isValidTab);
+    if (tabs.length === 0) continue;
+    const ids = new Set(tabs.map((t) => t.id));
+    const tabHistory = Array.isArray(panel.tabHistory)
+      ? panel.tabHistory.filter((h): h is string => typeof h === "string" && ids.has(h))
+      : [];
+    const activeTabId =
+      typeof panel.activeTabId === "string" && ids.has(panel.activeTabId)
+        ? panel.activeTabId
+        : (tabHistory[tabHistory.length - 1] ?? tabs[tabs.length - 1]!.id);
+    out[id] = { id, tabs, activeTabId, tabHistory };
+  }
+  return out;
+}
+
+export function clearWindowPanels(): void {
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+  } catch {
+    /* storage disabled */
+  }
+}