@hienlh/ppm 0.18.10 → 0.18.11

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

@@ -1,22 +1,27 @@
 /**
  * TabPool — persistent tab rendering with DOM reparenting.
  *
- * All tab components are mounted ONCE in a hidden off-screen container and
- * never unmounted when moved between panels or split. useLayoutEffect
- * physically moves each tab's wrapper DOM node into the correct panel slot
- * via appendChild (which moves, not clones). Component instances, hooks,
- * and all internal state (xterm buffer, Monaco editor, chat scroll) survive.
+ * All tab components are mounted ONCE and never unmounted when moved between panels or
+ * split. Each tab gets a wrapper element that is created once and portalled into; a
+ * layout effect physically moves that wrapper into the correct panel slot via appendChild
+ * (which moves, not clones). Component instances, hooks, and all internal state (xterm
+ * buffer, Monaco editor, chat scroll) survive.
  *
- * Why not createPortal? Changing a portal's container element causes React
- * to unmount/remount the children — defeating the purpose.
+ * A portal is safe here precisely because the container element is stable: the objection
+ * to portals is that *changing* a portal's container remounts its children, and nothing
+ * ever swaps a wrapper. In exchange React binds its listeners to the wrapper itself, so
+ * they travel with the node — including into another document.
  */
-import { useRef, useLayoutEffect, useEffect, useSyncExternalStore, Suspense, lazy } from "react";
-import { Loader2 } from "lucide-react";
+import { useState, useEffect, useSyncExternalStore, lazy } from "react";
 import { usePanelStore } from "@/stores/panel-store";
 import { useMountedTabsStore } from "@/stores/mounted-tabs-store";
 import type { TabType } from "@/stores/tab-store";
 import { collectTabEntries, filterMountableEntries } from "./tab-pool-collect";
-import { DOCK_PANEL_ID } from "@/stores/panel-utils";
+import { slotRegistry } from "./tab-pool-registry";
+import { ReparentingTab } from "./reparenting-tab";
+import { useWindowPanelReconcile } from "./use-window-panel-reconcile";
+
+export { registerPanelSlot } from "./tab-pool-registry";
 
 // ---------------------------------------------------------------------------
 // Lazy tab components (single source of truth for all tab types)
@@ -39,59 +44,29 @@ const TAB_COMPONENTS: Record<TabType, React.LazyExoticComponent<React.ComponentT
   group: lazy(() => import("@/components/group-chat/group-chat-tab").then((m) => ({ default: m.GroupChatTab }))),
 };
 
-// ---------------------------------------------------------------------------
-// Slot registry — panels register their content container refs here
-// ---------------------------------------------------------------------------
-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;
-  }
-}
-
-const registry = new SlotRegistry();
-
-/** Called by EditorPanel to register its content slot */
-export function registerPanelSlot(panelId: string, el: HTMLDivElement | null) {
-  registry.register(panelId, el);
-}
+const HIDDEN_CONTAINER_STYLE: React.CSSProperties = {
+  position: "fixed",
+  top: 0,
+  left: 0,
+  width: 0,
+  height: 0,
+  overflow: "hidden",
+  pointerEvents: "none",
+  visibility: "hidden",
+};
 
 // ---------------------------------------------------------------------------
-// TabPool — renders all tabs in a hidden container, reparents into slots
+// TabPool — renders all tabs into wrappers parked off-screen, reparents into slots
 // ---------------------------------------------------------------------------
 export function TabPool() {
-  const hiddenRef = useRef<HTMLDivElement>(null);
+  // State, not a ref: a tab's wrapper must be appended to a real element on its very
+  // first layout effect, and a parent ref is still null while its children's effects run.
+  const [hiddenContainer, setHiddenContainer] = useState<HTMLDivElement | null>(null);
 
   // Re-render when slots change (panel mount/unmount)
   useSyncExternalStore(
-    (cb) => registry.subscribe(cb),
-    () => registry.getVersion(),
+    (cb) => slotRegistry.subscribe(cb),
+    () => slotRegistry.getVersion(),
   );
 
   const panels = usePanelStore((s) => s.panels);
@@ -99,6 +74,10 @@ export function TabPool() {
   const currentProject = usePanelStore((s) => s.currentProject);
   const projectGrids = usePanelStore((s) => s.projectGrids);
 
+  // Detached tabs and their floating windows are persisted separately, so a reload can
+  // restore one without the other; this repairs the mismatch once per project load.
+  useWindowPanelReconcile();
+
   // Collect tabs from ALL mounted projects (not just active) to preserve
   // tab state across project switches (keep-alive). Each project's
   // PanelLayout stays mounted (CSS hidden), so slots remain registered.
@@ -133,118 +112,25 @@ export function TabPool() {
   }, [visibleKey]);
 
   return (
-    // Off-screen mount point. React mounts tab wrappers here, then
-    // useLayoutEffect moves them into panel slots before the browser paints.
-    <div ref={hiddenRef} style={{ position: "fixed", top: 0, left: 0, width: 0, height: 0, overflow: "hidden", pointerEvents: "none", visibility: "hidden" }}>
-      {tabEntries.map((entry) => (
-        <ReparentingTab
-          key={entry.tabId}
-          tabId={entry.tabId}
-          panelId={entry.panelId}
-          type={entry.type}
-          metadata={entry.metadata}
-          isActive={entry.isActive}
-          hiddenContainer={hiddenRef}
-        />
-      ))}
-    </div>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// ReparentingTab — mounts once, physically moves between panel slots
-// ---------------------------------------------------------------------------
-interface ReparentingTabProps {
-  tabId: string;
-  panelId: string;
-  type: TabType;
-  metadata?: Record<string, unknown>;
-  isActive: boolean;
-  hiddenContainer: React.RefObject<HTMLDivElement | null>;
-}
-
-function ReparentingTab({ tabId, panelId, type, metadata, isActive, hiddenContainer }: ReparentingTabProps) {
-  const wrapperRef = useRef<HTMLDivElement>(null);
-  const Component = TAB_COMPONENTS[type];
-
-  // On unmount: move wrapper back to hidden container so React's removeChild
-  // can find it. Without this, the wrapper stays orphaned in the slot (the DOM
-  // patch swallows the NotFoundError) and covers other tabs.
-  useLayoutEffect(() => {
-    return () => {
-      const wrapper = wrapperRef.current;
-      const hidden = hiddenContainer.current;
-      if (wrapper && hidden && wrapper.parentElement !== hidden) {
-        hidden.appendChild(wrapper);
-      }
-    };
-  }, [hiddenContainer]);
-
-  // Imperatively move the wrapper DOM node 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 wrapper = wrapperRef.current;
-    const slot = registry.get(panelId);
-    if (!wrapper) return;
-
-    // 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) {
-      const hidden = hiddenContainer.current;
-      if (hidden && wrapper.parentElement !== hidden) {
-        hidden.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;
-    }
-  });
-
-  if (!Component) return null;
-
-  return (
-    <div
-      ref={wrapperRef}
-      className="absolute inset-0"
-      style={isActive ? undefined : { display: "none" }}
-      data-tab-pool-id={tabId}
-      onMouseDownCapture={() => {
-        // Tab content is DOM-reparented out of EditorPanel's fiber subtree, so
-        // EditorPanel's onMouseDown never sees clicks on the content body. Set
-        // focus here where panelId is known — keeps focusedPanelId correct for
-        // every tab type. Dock content is excluded so new tabs open in the grid.
-        if (panelId !== DOCK_PANEL_ID) usePanelStore.getState().setFocusedPanel(panelId);
-      }}
-    >
-      <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>
+    // Off-screen parking spot. Tab wrappers live here until a layout effect moves them
+    // into a panel slot, and come back whenever their panel has no slot mounted.
+    <div ref={setHiddenContainer} style={HIDDEN_CONTAINER_STYLE}>
+      {hiddenContainer &&
+        tabEntries.map((entry) => {
+          const Component = TAB_COMPONENTS[entry.type];
+          if (!Component) return null;
+          return (
+            <ReparentingTab
+              key={entry.tabId}
+              tabId={entry.tabId}
+              panelId={entry.panelId}
+              component={Component}
+              metadata={entry.metadata}
+              isActive={entry.isActive}
+              hiddenContainer={hiddenContainer}
+            />
+          );
+        })}
     </div>
   );
 }

package/src/web/components/layout/tab-pop-out-menu-item.tsx

@@ -0,0 +1,42 @@
+/**
+ * "Open in window" — detaches a tab into a floating window, keeping it live.
+ *
+ * Desktop only: the window layer renders nothing below the md breakpoint, so on a phone
+ * the item would move a tab somewhere the user cannot see (a scaled-down window is never
+ * the answer — see the mobile-first UI rules).
+ */
+import { ExternalLink } from "lucide-react";
+import { toast } from "sonner";
+import { ContextMenuItem, ContextMenuSeparator } from "@/components/ui/context-menu";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import { usePanelStore } from "@/stores/panel-store";
+import type { Tab } from "@/stores/tab-store";
+
+interface TabPopOutMenuItemProps {
+  tab: Tab;
+  /** Panel the tab currently lives in — also where it re-docks when the window closes. */
+  panelId: string;
+}
+
+export function TabPopOutMenuItem({ tab, panelId }: TabPopOutMenuItemProps) {
+  const isMobile = useIsMobile();
+  // The monitor already has a window kind of its own; detaching it would open a second,
+  // duplicate presentation of the same data.
+  if (isMobile || tab.type === "system-monitor") return null;
+
+  return (
+    <>
+      <ContextMenuItem
+        onClick={() => {
+          const windowId = usePanelStore.getState().popOutTab(tab.id, panelId);
+          // The only rejection a desktop user can hit is the shared window cap.
+          if (!windowId) toast.error("Too many windows open — close one first");
+        }}
+      >
+        <ExternalLink className="size-3.5 mr-2" />
+        Open in window
+      </ContextMenuItem>
+      <ContextMenuSeparator />
+    </>
+  );
+}

package/src/web/components/layout/use-window-panel-reconcile.ts

@@ -0,0 +1,48 @@
+/**
+ * One-shot repair of the split between detached tabs and their floating windows.
+ *
+ * The two halves persist to different keys — window geometry is global and restored by
+ * the window layer, panels are restored with the project — so a reload can bring back one
+ * without the other. Runs once per project load, after the window layer has restored
+ * (otherwise every panel would look orphaned), and unconditionally on mobile, where the
+ * window layer renders nothing at all and a workspace synced from a desktop would
+ * otherwise hide its detached tabs with no way to reach them.
+ */
+import { useEffect, useRef } from "react";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import { usePanelStore } from "@/stores/panel-store";
+import { persistWindowPanelChange } from "@/stores/window-panel-actions";
+import { reconcileRunKey, reconcileTabHostWindows } from "@/stores/window-panel-reconcile";
+import { useWindowStore } from "@/components/floating-window/window-store";
+
+export function useWindowPanelReconcile(): void {
+  const isMobile = useIsMobile();
+  const currentProject = usePanelStore((s) => s.currentProject);
+  const restored = useWindowStore((s) => s.restored);
+  const reconciledFor = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!currentProject) return;
+    if (!restored && !isMobile) return;
+    const runKey = reconcileRunKey(currentProject, isMobile);
+    if (reconciledFor.current === runKey) return;
+    reconciledFor.current = runKey;
+
+    const { panels, grid, focusedPanelId } = usePanelStore.getState();
+    // No window layer on mobile ⇒ no window is live ⇒ every detached tab comes home.
+    const liveWindowIds = isMobile
+      ? []
+      : Object.values(useWindowStore.getState().windows)
+          .filter((w) => w.kind === "tab-host")
+          .map((w) => w.id);
+
+    const result = reconcileTabHostWindows({ panels, grid, focusedPanelId, liveWindowIds });
+    if (result.changed) {
+      usePanelStore.setState({ panels: result.panels, focusedPanelId: result.focusedPanelId });
+      // Both halves: the window-panel blob shrank, and the tabs landed in a grid panel
+      // that belongs to the active project's layout.
+      persistWindowPanelChange(usePanelStore.getState);
+    }
+    for (const windowId of result.windowIdsToClose) useWindowStore.getState().close(windowId);
+  }, [currentProject, restored, isMobile]);
+}

package/src/web/components/os-explorer/skins/macos-window-chrome.tsx

@@ -1,10 +1,12 @@
 /**
  * Finder-flavoured unified titlebar: traffic lights left (grey when unfocused, hover
- * reveals the glyph), title centred. Height matches the shared `TITLEBAR_HEIGHT` contract
- * constant (not the real Finder 38px) so a minimised window's collapsed height agrees with
- * what `FloatingWindow` reserves for it. The toolbar row (back/forward/view-switch/search)
- * is the existing `ExplorerToolbar` in the window body, tinted by `skins.css` — the chrome
- * slot is only the titlebar itself.
+ * reveals the glyph), title centred, picture-in-picture at the right end. Height matches the
+ * shared `TITLEBAR_HEIGHT` contract constant (not the real Finder 38px) so a minimised
+ * window's collapsed height agrees with what `FloatingWindow` reserves for it.
+ *
+ * Worn by EVERY window kind, not just the explorer: the frame resolves one skin for all of
+ * them. Anything below the titlebar (the explorer's own toolbar row, tinted by `skins.css`)
+ * belongs to the window body — the chrome slot is only the titlebar itself.
  *
  * `data-skin` is set here (not only on the explorer body) because this titlebar is a
  * sibling of the body in the window tree — the `--x-*` vars it reads only resolve on an
@@ -14,6 +16,7 @@
 import { Minus, Plus, X } from "lucide-react";
 import { cn } from "@/lib/utils";
 import { TITLEBAR_HEIGHT, type WindowChromeProps } from "@/components/floating-window/window-chrome-contract";
+import { PipCaptionButton } from "@/components/floating-window/pip/pip-caption-button";
 
 /** The traffic-light colours, plus the unfocused grey — the documented hardcoded hexes. */
 const LIGHTS = [
@@ -23,7 +26,7 @@ const LIGHTS = [
 ] as const;
 
 export function MacosWindowChrome({
-  title, focused, titlebarProps, onMinimize, onToggleMaximize, onClose,
+  id, title, focused, titlebarProps, onMinimize, onToggleMaximize, onClose,
 }: WindowChromeProps) {
   const { className, style, ...rest } = titlebarProps;
   const actions = [onClose, onMinimize, onToggleMaximize];
@@ -56,14 +59,20 @@ export function MacosWindowChrome({
           </button>
         ))}
       </div>
+      {/* A flex child, not an absolutely centred span: the title is boxed between the
+          traffic lights and the caption button, so a long title truncates instead of
+          painting over either of them. Centre is a few px off true middle — acceptable. */}
       <span
         className={cn(
-          "pointer-events-none absolute inset-x-0 truncate text-center text-[13px]",
+          "pointer-events-none flex-1 min-w-0 truncate text-center text-[13px] px-2",
           focused ? "text-text" : "text-text-2",
         )}
       >
         {title}
       </span>
+      <div className="flex items-center pr-2">
+        <PipCaptionButton id={id} />
+      </div>
     </div>
   );
 }

package/src/web/components/os-explorer/skins/windows-window-chrome.tsx

@@ -1,10 +1,14 @@
 /**
- * Windows 11 File Explorer-flavoured titlebar: window icon + title left, caption buttons
- * right (46px wide, close hover red). Height matches the shared `TITLEBAR_HEIGHT` contract
- * constant (not the real Win11 32px) so a minimised window's collapsed height agrees with
- * what `FloatingWindow` reserves for it. The toolbar row (back/forward/breadcrumb/search) is
- * the existing `ExplorerToolbar` in the window body, tinted by `skins.css` — the chrome slot
- * is only the titlebar itself.
+ * Windows 11 File Explorer-flavoured titlebar: title left, caption buttons right (46px wide,
+ * close hover red), picture-in-picture left of minimize. Height matches the shared
+ * `TITLEBAR_HEIGHT` contract constant (not the real Win11 32px) so a minimised window's
+ * collapsed height agrees with what `FloatingWindow` reserves for it.
+ *
+ * Worn by EVERY window kind, not just the explorer: the frame resolves one skin for all of
+ * them. Hence the folder glyph is drawn only for `kind === "explorer"` — it is the File
+ * Explorer's app icon, and a system monitor wearing it would be a lie. Anything below the
+ * titlebar (the explorer's own toolbar row, tinted by `skins.css`) belongs to the window
+ * body — the chrome slot is only the titlebar itself.
  *
  * `data-skin` is set here (not only on the explorer body) because this titlebar is a
  * sibling of the body in the window tree — the `--x-*` vars it reads (`--x-titlebar-bg`,
@@ -14,6 +18,7 @@
 import { Minus, Square, Copy, X } from "lucide-react";
 import { cn } from "@/lib/utils";
 import { TITLEBAR_HEIGHT, type WindowChromeProps } from "@/components/floating-window/window-chrome-contract";
+import { PipCaptionButton } from "@/components/floating-window/pip/pip-caption-button";
 import { WindowsFolderIcon } from "./folder-icon-windows";
 
 /** Windows metric: 46px wide caption buttons, full titlebar height. */
@@ -23,7 +28,7 @@ const CAPTION_BUTTON =
 const CLOSE_BUTTON = cn(CAPTION_BUTTON, "can-hover:hover:!bg-[#c42b1c] can-hover:hover:!text-white");
 
 export function WindowsWindowChrome({
-  title, state, focused, titlebarProps, onMinimize, onToggleMaximize, onClose,
+  id, kind, title, state, focused, titlebarProps, onMinimize, onToggleMaximize, onClose,
 }: WindowChromeProps) {
   const { className, style, ...rest } = titlebarProps;
   return (
@@ -39,9 +44,10 @@ export function WindowsWindowChrome({
       )}
     >
       <div className="flex flex-1 min-w-0 items-center gap-2 px-2.5 cursor-default">
-        <WindowsFolderIcon className="size-4 shrink-0" />
+        {kind === "explorer" && <WindowsFolderIcon className="size-4 shrink-0" />}
         <span className={cn("truncate text-[12px]", focused ? "text-text" : "text-text-2")}>{title}</span>
       </div>
+      <PipCaptionButton id={id} className={CAPTION_BUTTON} />
       <button type="button" aria-label="Minimize window" className={CAPTION_BUTTON} onClick={onMinimize}>
         <Minus className="size-3.5" />
       </button>

package/src/web/components/ui/context-menu.tsx

@@ -3,6 +3,7 @@ import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react"
 import { ContextMenu as ContextMenuPrimitive } from "radix-ui"
 
 import { cn } from "@/lib/utils"
+import { usePortalContainer } from "./portal-container-context"
 
 function ContextMenu({
   ...props
@@ -27,10 +28,16 @@ function ContextMenuGroup({
 }
 
 function ContextMenuPortal({
+  container,
   ...props
 }: React.ComponentProps<typeof ContextMenuPrimitive.Portal>) {
+  const contextContainer = usePortalContainer()
   return (
-    <ContextMenuPrimitive.Portal data-slot="context-menu-portal" {...props} />
+    <ContextMenuPrimitive.Portal
+      data-slot="context-menu-portal"
+      container={container ?? contextContainer}
+      {...props}
+    />
   )
 }
 
@@ -96,7 +103,7 @@ function ContextMenuContent({
   ...props
 }: React.ComponentProps<typeof ContextMenuPrimitive.Content>) {
   return (
-    <ContextMenuPrimitive.Portal>
+    <ContextMenuPortal>
       <ContextMenuPrimitive.Content
         data-slot="context-menu-content"
         className={cn(
@@ -105,7 +112,7 @@ function ContextMenuContent({
         )}
         {...props}
       />
-    </ContextMenuPrimitive.Portal>
+    </ContextMenuPortal>
   )
 }
 

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

@@ -4,6 +4,7 @@ import { Dialog as DialogPrimitive } from "radix-ui"
 
 import { cn } from "@/lib/utils"
 import { Button } from "@/components/ui/button"
+import { usePortalContainer } from "./portal-container-context"
 
 function Dialog({
   ...props
@@ -18,9 +19,17 @@ function DialogTrigger({
 }
 
 function DialogPortal({
+  container,
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Portal>) {
-  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />
+  const contextContainer = usePortalContainer()
+  return (
+    <DialogPrimitive.Portal
+      data-slot="dialog-portal"
+      container={container ?? contextContainer}
+      {...props}
+    />
+  )
 }
 
 function DialogClose({

package/src/web/components/ui/dropdown-menu.tsx

@@ -5,6 +5,7 @@ import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react"
 import { DropdownMenu as DropdownMenuPrimitive } from "radix-ui"
 
 import { cn } from "@/lib/utils"
+import { usePortalContainer } from "./portal-container-context"
 
 function DropdownMenu({
   ...props
@@ -13,10 +14,16 @@ function DropdownMenu({
 }
 
 function DropdownMenuPortal({
+  container,
   ...props
 }: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>) {
+  const contextContainer = usePortalContainer()
   return (
-    <DropdownMenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />
+    <DropdownMenuPrimitive.Portal
+      data-slot="dropdown-menu-portal"
+      container={container ?? contextContainer}
+      {...props}
+    />
   )
 }
 
@@ -37,7 +44,7 @@ function DropdownMenuContent({
   ...props
 }: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
   return (
-    <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPortal>
       <DropdownMenuPrimitive.Content
         data-slot="dropdown-menu-content"
         sideOffset={sideOffset}
@@ -47,7 +54,7 @@ function DropdownMenuContent({
         )}
         {...props}
       />
-    </DropdownMenuPrimitive.Portal>
+    </DropdownMenuPortal>
   )
 }
 

package/src/web/components/ui/mobile-bottom-sheet.tsx

@@ -11,6 +11,7 @@ import { createPortal } from "react-dom";
 import { cn } from "@/lib/utils";
 import { useSwipeToDismiss } from "@/hooks/use-swipe-to-dismiss";
 import { useVisualViewport } from "@/hooks/use-visual-viewport";
+import { usePortalContainer } from "./portal-container-context";
 
 /* ------------------------------------------------------------------ */
 /*  Core BottomSheet — reusable everywhere                             */
@@ -33,6 +34,7 @@ interface BottomSheetProps {
 export function BottomSheet({ open, onClose, children, className, zIndex = 50 }: BottomSheetProps) {
   const { dragY, swipeHandlers, dragStyle, backdropOpacity, isDragging } =
     useSwipeToDismiss(onClose);
+  const portalContainer = usePortalContainer();
 
   // Keyboard-aware geometry. The backdrop deliberately keeps covering the whole
   // layout viewport while only the panel tracks the keyboard: if the two ever
@@ -89,7 +91,7 @@ export function BottomSheet({ open, onClose, children, className, zIndex = 50 }:
         {children}
       </div>
     </div>,
-    sheetPortalTarget(),
+    sheetPortalTarget(portalContainer),
   );
 }
 
@@ -103,10 +105,11 @@ export function BottomSheet({ open, onClose, children, className, zIndex = 50 }:
  * the event fired on (`body`), finds no match, and drops the event — every
  * button inside a dock tab goes dead while native listeners still fire.
  * `#root` carries no styles, so keeping the portal inside it leaves stacking
- * order untouched.
+ * order untouched. A caller-supplied `container` (`PortalContainerProvider`)
+ * wins over both fallbacks.
  */
-function sheetPortalTarget(): HTMLElement {
-  return document.getElementById("root") ?? document.body;
+function sheetPortalTarget(container?: HTMLElement): HTMLElement {
+  return container ?? document.getElementById("root") ?? document.body;
 }
 
 /* ------------------------------------------------------------------ */

package/src/web/components/ui/portal-container-context.tsx

@@ -0,0 +1,40 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+/**
+ * Shared portal target for every Radix/portal-based primitive under
+ * `components/ui/`. `undefined` means "the document's default target" — Radix
+ * primitives fall back to `document.body`, `mobile-bottom-sheet.tsx` falls
+ * back to `#root`. Never pass `null`: Radix's `container` prop only applies
+ * its own default when the value is `undefined`, and `null` renders no
+ * portal at all.
+ *
+ * With no provider mounted, `usePortalContainer()` returns `undefined` and
+ * every primitive behaves exactly as it did before this context existed.
+ */
+const PortalContainerContext = createContext<HTMLElement | undefined>(
+  undefined,
+);
+
+/**
+ * Mounts a portal target for all descendant Radix primitives. Pass
+ * `undefined` to explicitly restore the document default (e.g. once a
+ * picture-in-picture window closes).
+ */
+export function PortalContainerProvider({
+  container,
+  children,
+}: {
+  container: HTMLElement | undefined;
+  children: ReactNode;
+}) {
+  return (
+    <PortalContainerContext.Provider value={container}>
+      {children}
+    </PortalContainerContext.Provider>
+  );
+}
+
+/** The caller-supplied portal container, or `undefined` outside any provider. */
+export function usePortalContainer(): HTMLElement | undefined {
+  return useContext(PortalContainerContext);
+}