@hienlh/ppm 0.18.10 → 0.18.12

package/src/web/components/floating-window/window-persistence.ts

@@ -7,6 +7,7 @@
  */
 
 import { clampRect, type Bounds, type Rect } from "./window-geometry";
+import { WINDOW_KINDS } from "./window-store-types";
 import type { WindowKind, WindowRuntimeState, WindowVisualState } from "./window-store-types";
 
 const STORAGE_KEY = "ppm-windows";
@@ -20,7 +21,13 @@ export interface PersistedWindow {
   payload?: Record<string, unknown>;
 }
 
-const KINDS: WindowKind[] = ["explorer", "system-monitor"];
+/**
+ * Kinds that may come back after a reload. Derived from WINDOW_KINDS so a new kind is
+ * restorable by default; `team-member` is the one exclusion, because its body streams a
+ * live subagent session that no longer exists after a reload — restoring it would open
+ * an empty shell the user never asked for.
+ */
+const RESTORABLE_KINDS: readonly WindowKind[] = WINDOW_KINDS.filter((k) => k !== "team-member");
 const STATES: WindowVisualState[] = ["normal", "maximized", "minimized"];
 
 function isRect(v: unknown): v is Rect {
@@ -79,7 +86,7 @@ export function loadWindowRects(bounds: Bounds): PersistedWindow[] {
   for (const item of parsed) {
     if (!item || typeof item !== "object") continue;
     const w = item as Record<string, unknown>;
-    if (typeof w.id !== "string" || !KINDS.includes(w.kind as WindowKind)) continue;
+    if (typeof w.id !== "string" || !RESTORABLE_KINDS.includes(w.kind as WindowKind)) continue;
     if (!isRect(w.rect) || !isSerialisable(w.payload)) continue;
     const state = STATES.includes(w.state as WindowVisualState)
       ? (w.state as WindowVisualState)

package/src/web/components/floating-window/window-pip-placeholder.tsx

@@ -0,0 +1,31 @@
+/**
+ * What a floating window shows while its body is playing in a picture-in-picture window.
+ *
+ * It takes the body's place in the frame's flex column — the body element is physically gone
+ * from here, so the two never fight over the space — and it stays in the MAIN document on
+ * purpose: it is the way back. An empty frame would just read as lost content.
+ */
+
+import { cn } from "@/lib/utils";
+import type { PipHandle } from "./pip/pip-host";
+
+export function WindowPipPlaceholder({ pip, minimized }: { pip: PipHandle; minimized: boolean }) {
+  return (
+    <div
+      className={cn(
+        "relative flex-1 min-h-0 flex flex-col items-center justify-center gap-3",
+        "rounded-b-[8px] bg-panel text-center px-4",
+        minimized && "hidden",
+      )}
+    >
+      <span className="text-xs text-text-2">Playing in picture-in-picture</span>
+      <button
+        type="button"
+        onClick={() => pip.detach()}
+        className="min-h-11 min-w-11 px-4 rounded-md border border-border bg-surface-elevated text-sm text-text can-hover:hover:bg-panel-2 transition-colors"
+      >
+        Bring back
+      </button>
+    </div>
+  );
+}

package/src/web/components/floating-window/window-pip-registry.ts

@@ -0,0 +1,69 @@
+/**
+ * The one piece of state a floating window's chrome and its body must agree on, for every
+ * window kind.
+ *
+ * The titlebar and the body are DOM siblings rendered by the window frame, not parent and
+ * child, so React context cannot bridge them: the titlebar needs the body element to hand it
+ * to the PiP host, and the frame needs the resulting handle to show its placeholder. Both
+ * live here, keyed by WINDOW id, and both are dropped in the frame's layout cleanup.
+ *
+ * A tab is a third party — TabPool renders it through a portal into a slot inside the body,
+ * so it reads the handle from here too (by panel id) to point its Radix portals at the PiP
+ * document instead of the main one.
+ */
+
+import { useCallback, useSyncExternalStore } from "react";
+import { windowIdFromPanelId } from "@/stores/panel-utils";
+import type { PipHandle } from "./pip/pip-host";
+
+const slots = new Map<string, HTMLElement>();
+const handles = new Map<string, PipHandle>();
+const listeners = new Set<() => void>();
+
+/** Publish (or, with `null`, retract) the body element a window would pop out. */
+export function publishWindowSlot(windowId: string, el: HTMLElement | null): void {
+  if (el) slots.set(windowId, el);
+  else slots.delete(windowId);
+}
+
+/** The body element of a mounted window, or null. */
+export function windowSlot(windowId: string): HTMLElement | null {
+  return slots.get(windowId) ?? null;
+}
+
+/** Record the PiP handle a window's body is currently living in (`null` clears it). */
+export function setWindowPip(windowId: string, handle: PipHandle | null): void {
+  const current = handles.get(windowId) ?? null;
+  if (current === handle) return;
+  if (handle) handles.set(windowId, handle);
+  else handles.delete(windowId);
+  for (const notify of listeners) notify();
+}
+
+/** The PiP handle for a window, or null when its body is docked in the window. */
+export function windowPip(windowId: string | null | undefined): PipHandle | null {
+  return windowId ? (handles.get(windowId) ?? null) : null;
+}
+
+function subscribe(onChange: () => void): () => void {
+  listeners.add(onChange);
+  return () => {
+    listeners.delete(onChange);
+  };
+}
+
+/** Re-renders when the window's PiP handle appears or goes away. */
+export function useWindowPip(windowId: string | null | undefined): PipHandle | null {
+  const snapshot = useCallback(() => windowPip(windowId), [windowId]);
+  return useSyncExternalStore(subscribe, snapshot);
+}
+
+/**
+ * Portal target for a tab rendered into `panelId`: the PiP document's body while that
+ * panel's window is popped out, otherwise `undefined` (the document default). Never `null` —
+ * Radix reads `null` as "render no portal at all".
+ */
+export function usePipPortalContainer(panelId: string): HTMLElement | undefined {
+  const handle = useWindowPip(windowIdFromPanelId(panelId));
+  return handle?.pipWindow.document.body;
+}

package/src/web/components/floating-window/window-skin-chrome.tsx

@@ -0,0 +1,21 @@
+/**
+ * The single titlebar every floating window wears, whatever its kind.
+ *
+ * It resolves the active OS skin (Settings override, otherwise the host platform) and
+ * delegates to that skin's chrome, so an explorer, a system monitor, a team-member session
+ * and a detached tab are visually the same window — the complaint that produced this file
+ * was two kinds shipping two different titlebars.
+ *
+ * `FloatingWindow` renders the chrome directly with no `<Suspense>` around it, so this entry
+ * point cannot be `lazy()` the way a window body is: it has to resolve synchronously, which
+ * is exactly what a small wrapper component (rather than a whole feature body) affords.
+ */
+
+import { useExplorerSkin } from "@/components/os-explorer/skins/use-explorer-skin";
+import type { WindowChromeProps } from "./window-chrome-contract";
+
+export function WindowSkinChrome(props: WindowChromeProps) {
+  const skin = useExplorerSkin();
+  const Chrome = skin.chrome;
+  return <Chrome {...props} />;
+}

package/src/web/components/floating-window/window-store-types.ts

@@ -2,8 +2,14 @@
 
 import type { Rect } from "./window-geometry";
 
-/** Content families the layer can host. The registry maps each kind to its body component. */
-export type WindowKind = "explorer" | "team-member" | "system-monitor";
+/**
+ * Content families the layer can host. The registry maps each kind to its body component.
+ * Single source of truth: the persistence layer filters this list instead of repeating it,
+ * so a new kind can never be silently dropped on reload.
+ */
+export const WINDOW_KINDS = ["explorer", "team-member", "system-monitor", "tab-host"] as const;
+
+export type WindowKind = (typeof WINDOW_KINDS)[number];
 
 export type WindowVisualState = "normal" | "maximized" | "minimized";
 

package/src/web/components/layout/reparenting-tab.tsx

@@ -0,0 +1,136 @@
+/**
+ * ReparentingTab — one tab component, mounted once, physically moved between panel slots.
+ *
+ * The wrapper element is created imperatively and never re-created, and the tab renders
+ * into it through a portal. That is what makes the node portable: React attaches its
+ * event listeners to the portal container itself, so they keep working after the wrapper
+ * is moved into a panel slot — including a slot that lives in another document, where
+ * the app root's delegated listeners would never match.
+ *
+ * The wrapper's placement is owned here (hidden container ⇄ slot); its children are owned
+ * by React. Nothing outside may re-create the wrapper: a new container element would
+ * remount the tab and destroy exactly the state (xterm buffer, Monaco undo stack, chat
+ * scroll) this component exists to preserve.
+ */
+import { useLayoutEffect, useRef, Suspense, type LazyExoticComponent, type ComponentType } from "react";
+import { createPortal } from "react-dom";
+import { Loader2 } from "lucide-react";
+import { usePanelStore } from "@/stores/panel-store";
+import { DOCK_PANEL_ID, isWindowPanelId } from "@/stores/panel-utils";
+import { PortalContainerProvider } from "@/components/ui/portal-container-context";
+import { usePipPortalContainer } from "@/components/floating-window/window-pip-registry";
+import { slotRegistry } from "./tab-pool-registry";
+
+export interface ReparentingTabProps {
+  tabId: string;
+  panelId: string;
+  component: LazyExoticComponent<ComponentType<{ metadata?: Record<string, unknown>; tabId?: string }>>;
+  metadata?: Record<string, unknown>;
+  isActive: boolean;
+  /** Off-screen parent the wrapper lives in whenever its panel has no slot mounted. */
+  hiddenContainer: HTMLDivElement;
+}
+
+export function ReparentingTab({
+  tabId,
+  panelId,
+  component: Component,
+  metadata,
+  isActive,
+  hiddenContainer,
+}: ReparentingTabProps) {
+  const wrapperRef = useRef<HTMLDivElement | null>(null);
+  if (!wrapperRef.current) {
+    const el = document.createElement("div");
+    el.className = "absolute inset-0";
+    el.dataset.tabPoolId = tabId;
+    wrapperRef.current = el;
+  }
+  const wrapper = wrapperRef.current;
+
+  // Written during render, before any effect, so the click listener below always reads
+  // the panel the tab lives in NOW — a re-docked tab must focus its new panel.
+  const panelIdRef = useRef(panelId);
+  panelIdRef.current = panelId;
+
+  // Mount the wrapper and own its removal. The listener is native and capturing because
+  // the tab content is DOM-reparented out of the panel's fiber subtree: the panel never
+  // sees clicks on the content body, so focus is set here, where the panel is known.
+  useLayoutEffect(() => {
+    if (!wrapper.parentElement) hiddenContainer.appendChild(wrapper);
+    const onMouseDown = () => {
+      const pid = panelIdRef.current;
+      // Off-grid panels are skipped: focus decides where the next tab opens, and it may
+      // never land in the dock or inside a floating window.
+      if (pid === DOCK_PANEL_ID || isWindowPanelId(pid)) return;
+      usePanelStore.getState().setFocusedPanel(pid);
+    };
+    wrapper.addEventListener("mousedown", onMouseDown, true);
+    return () => {
+      wrapper.removeEventListener("mousedown", onMouseDown, true);
+      wrapper.remove();
+    };
+  }, [wrapper, hiddenContainer]);
+
+  useLayoutEffect(() => {
+    wrapper.style.display = isActive ? "" : "none";
+  }, [wrapper, isActive]);
+
+  // Imperatively move the wrapper into the correct panel slot.
+  // appendChild on an already-mounted node moves it (DOM spec — no clone/destroy).
+  // useLayoutEffect runs before paint, so the user never sees the off-screen state.
+  // No deps — must run every render because React's reconciliation may call
+  // insertBefore() to reorder keyed children, moving reparented nodes back
+  // to the hidden container. The early-return guard keeps this cheap.
+  useLayoutEffect(() => {
+    const slot = slotRegistry.get(panelId);
+
+    // Panel slot not mounted (e.g., mobile renders only the focused panel).
+    // Move wrapper back to hidden container so it doesn't overlap in the wrong slot.
+    if (!slot) {
+      if (wrapper.parentElement !== hiddenContainer) hiddenContainer.appendChild(wrapper);
+      return;
+    }
+
+    if (wrapper.parentElement === slot) return;
+
+    // Save scroll positions — appendChild resets them during the DOM move
+    const scrollables: { el: Element; top: number; left: number }[] = [];
+    wrapper.querySelectorAll("*").forEach((el) => {
+      if (el.scrollTop || el.scrollLeft) {
+        scrollables.push({ el, top: el.scrollTop, left: el.scrollLeft });
+      }
+    });
+
+    slot.appendChild(wrapper);
+
+    // Restore scroll positions synchronously before paint
+    for (const { el, top, left } of scrollables) {
+      el.scrollTop = top;
+      el.scrollLeft = left;
+    }
+  });
+
+  // Portal target for the tab's own dropdowns, tooltips and sheets. It belongs here and
+  // not in the floating-window body: the wrapper's React parent is this component, so a
+  // provider mounted around the window body would never reach the tab's primitives, and
+  // a menu opened in a picture-in-picture window would render in the main one — off
+  // screen, unreachable, and stealing the click. `undefined` while docked, which is the
+  // document default.
+  const portalContainer = usePipPortalContainer(panelId);
+
+  return createPortal(
+    <PortalContainerProvider container={portalContainer}>
+      <Suspense
+        fallback={
+          <div className="flex items-center justify-center h-full">
+            <Loader2 className="size-6 animate-spin text-primary" />
+          </div>
+        }
+      >
+        <Component metadata={metadata} tabId={tabId} />
+      </Suspense>
+    </PortalContainerProvider>,
+    wrapper,
+  );
+}

package/src/web/components/layout/tab-bar.tsx

@@ -40,6 +40,7 @@ import { useTabOverflow, getHiddenUnreadDirection } from "@/hooks/use-tab-overfl
 import { useSettingsStore } from "@/stores/settings-store";
 import { tabRowClass, tabAddButtonClass } from "@/lib/tab-bar-style";
 import { DraggableTab } from "./draggable-tab";
+import { TabPopOutMenuItem } from "./tab-pop-out-menu-item";
 import { cn } from "@/lib/utils";
 import type { Tab } from "@/stores/tab-store";
 import { downloadFile } from "@/lib/file-download";
@@ -394,6 +395,7 @@ export const TabBar = memo(function TabBar({ panelId }: TabBarProps) {
               tagColor={sessionId ? sessionTagMap[sessionId]?.color : undefined}
               extraMenuContent={
                 <>
+                  <TabPopOutMenuItem tab={tab} panelId={effectivePanelId} />
                   {dockMoveMenuItems(tab)}
                   {compareMenuItems(tab)}
                   {sessionId && !notiType && (

package/src/web/components/layout/tab-pool-collect.ts

@@ -11,7 +11,7 @@
  * characterization test proves it by asserting the same outputs.
  */
 import type { Panel } from "@/stores/panel-utils";
-import { DOCK_PANEL_ID } from "@/stores/panel-utils";
+import { DOCK_PANEL_ID, isWindowPanelId } from "@/stores/panel-utils";
 import type { TabType } from "@/stores/tab-store";
 
 export interface TabEntry {
@@ -98,6 +98,38 @@ export function collectFromDock(
   }
 }
 
+/**
+ * Collect tab entries from the off-grid panels that host detached tabs (`__win__:*`),
+ * deduplicating via seenTabs.
+ *
+ * Without this pass a popped-out tab is in neither a grid nor the dock, so TabPool would
+ * mount it nowhere and the floating window would stay empty.
+ *
+ * WHY no projectId filter: like the dock, a window panel is global — a detached tab stays
+ * visible across a project switch, because a window the user pulled out explicitly
+ * vanishing on switch reads as data loss.
+ */
+export function collectFromWindowPanels(
+  panels: Record<string, Panel>,
+  seenTabs: Set<string>,
+  tabEntries: TabEntry[],
+): void {
+  for (const [panelId, panel] of Object.entries(panels)) {
+    if (!isWindowPanelId(panelId)) continue;
+    for (const tab of panel.tabs) {
+      if (seenTabs.has(tab.id)) continue;
+      seenTabs.add(tab.id);
+      tabEntries.push({
+        tabId: tab.id,
+        panelId,
+        type: tab.type,
+        metadata: tab.metadata,
+        isActive: tab.id === panel.activeTabId,
+      });
+    }
+  }
+}
+
 /**
  * Collect all tab entries across active and non-active projects, returning
  * the full deduplicated list (sorted by tabId for stable ordering).
@@ -105,7 +137,7 @@ export function collectFromDock(
  * Collection order (intentional — determines dedup precedence):
  *   1. Active project's live grid  (highest priority)
  *   2. Non-active projects' snapshotted grids  (keep-alive)
- *   3. Dock panel (__dock__)  (lowest priority — grid wins on collision)
+ *   3. Window panels (__win__:*) and the dock panel (__dock__)  (grid wins on collision)
  *
  * This mirrors what TabPool does before passing entries to ReparentingTab.
  */
@@ -127,6 +159,10 @@ export function collectTabEntries(
     collectFromGrid(projectGrid, projectName, false, panels, seenTabs, tabEntries);
   }
 
+  // Off-grid panels last, so a tab that is briefly in both a grid panel and an off-grid
+  // one (mid-move) renders in the grid slot the user just dropped it into.
+  collectFromWindowPanels(panels, seenTabs, tabEntries);
+
   // Dock panel — collected last so grid tabs always win dedup.
   // Missing __dock__ (e.g. legacy state, tests without dock) is safe to skip.
   const dockPanel = panels[DOCK_PANEL_ID];

package/src/web/components/layout/tab-pool-registry.ts

@@ -0,0 +1,48 @@
+/**
+ * Slot registry — panels publish the element their tab content should live in.
+ *
+ * Split out of tab-pool.tsx so the pool and the reparenting wrapper can both reach it
+ * without importing each other.
+ *
+ * Registering an element is a subscription event, not a render input: TabPool subscribes
+ * through useSyncExternalStore, so a panel mounting late still gets its tab moved in.
+ */
+type SlotListener = () => void;
+
+class SlotRegistry {
+  private slots = new Map<string, HTMLDivElement>();
+  private listeners = new Set<SlotListener>();
+  private version = 0;
+
+  register(panelId: string, el: HTMLDivElement | null) {
+    if (el) {
+      if (this.slots.get(panelId) === el) return;
+      this.slots.set(panelId, el);
+    } else {
+      if (!this.slots.has(panelId)) return;
+      this.slots.delete(panelId);
+    }
+    this.version++;
+    this.listeners.forEach((fn) => fn());
+  }
+
+  get(panelId: string): HTMLDivElement | undefined {
+    return this.slots.get(panelId);
+  }
+
+  subscribe(fn: SlotListener): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  getVersion(): number {
+    return this.version;
+  }
+}
+
+export const slotRegistry = new SlotRegistry();
+
+/** Called by a panel (grid, dock or floating window) to register its content slot. */
+export function registerPanelSlot(panelId: string, el: HTMLDivElement | null) {
+  slotRegistry.register(panelId, el);
+}