@hienlh/ppm 0.18.10 → 0.18.12

package/docs/system-architecture.md

@@ -2264,10 +2264,87 @@ below the app's existing `z-40` click-away backdrops and `z-50` Radix layers, so
 dropdowns and dialogs always stay reachable above any number of open explorer windows. Below the
 `md` breakpoint the layer never mounts at all; `src/web/components/os-explorer/mobile/` renders the
 same `ExplorerBody` component inside a full-screen bottom sheet instead (`variant="sheet"`).
-
-A window's titlebar is a swappable `chrome` component (`WindowChromeProps` contract) — the OS skin
-picks Windows caption buttons or macOS traffic lights from `src/web/components/os-explorer/skins/`,
-scoped entirely through `[data-skin="windows"|"macos"]` CSS variables layered over PPM's existing
-semantic theme tokens, so both PPM dark and light mode render correctly under either skin with no
-second color table.
+Drag and resize share a `gestureAbandoned()` guard (`use-window-gesture-context.ts`) for the
+pointer-up that still arrives after a mid-gesture window close (e.g. dragging by a titlebar button
+that closes the frame).
+
+**One chrome, every kind.** `WindowSkinChrome` (`window-skin-chrome.tsx`) is the titlebar every
+window kind — explorer, team-member session, system monitor, detached tab — renders: it resolves
+the active OS skin via `useExplorerSkin()` (Settings override, else host platform; Linux → macOS)
+and delegates to that skin's `WindowsWindowChrome` / `MacosWindowChrome`
+(`src/web/components/os-explorer/skins/`), scoped entirely through `[data-skin="windows"|"macos"]`
+CSS variables layered over PPM's existing semantic theme tokens — no second color table. The
+Windows skin's folder glyph draws only for `kind === "explorer"`; every other kind gets the bare
+titlebar. The macOS skin boxes the title between the traffic lights and the PiP button as a flex
+child (so a long title truncates instead of overlapping either), and puts the PiP button at the
+titlebar's right end; the Windows skin puts it left of minimize.
+
+**PiP is a capability of the frame, not of one kind.** `useWindowBodyElement`
+(`use-window-body-element.ts`) creates the single DOM element `FloatingWindow` portals a window's
+content into and publishes it as that window's PiP slot (`window-pip-registry.ts`, keyed by window
+id). `PipCaptionButton` (`pip/pip-caption-button.tsx`), rendered by both skins, moves that slot into
+a `documentPictureInPicture` window and back; it is absent (not disabled) where the API is
+unsupported. `WindowPipPlaceholder` (`window-pip-placeholder.tsx`) takes the body's place in the
+frame while it plays in PiP, with a ≥44px "Bring back" control. The mechanics below (attach/detach,
+style mirroring, key forwarding, resize signalling) apply to whichever window kind currently owns
+the slot — a tab-host window is only the one kind whose body is itself a portal target for another
+component (`TabPool`).
+
+#### Tab-host windows (detaching a tab into its own window)
+
+- **Off-grid panel.** Detaching creates `` `__win__:${windowId}` `` (`windowPanelId()`,
+  `stores/panel-utils.ts`) — same treatment as `__dock__`: lives in `panels`, never in `grid`, so no
+  grid math (rows/columns/split) sees it. `stores/window-panel-actions.ts` is the only writer of
+  these panels and enforces the paired invariant: `focusedPanelId` never points at one (it would
+  send the next `openTab()` with no explicit panel into a window). `popOutTab`/`redockFromWindow`
+  create and destroy the panel and its window together; every close path (titlebar ×, keyboard,
+  reconcile) routes through `redockFromWindow`, which re-docks to the origin panel if it is still in
+  the grid, else the focused grid panel, else the first grid panel. All tab types pop out except
+  `system-monitor`, which already has its own window kind.
+- **No-remount move.** `TabPool` (`components/layout/tab-pool.tsx`) mounts every tab once into a
+  wrapper `div[data-tab-pool-id]` created imperatively in `ReparentingTab`
+  (`components/layout/reparenting-tab.tsx`) and rendered into it via `createPortal` — React attaches
+  its listeners to the wrapper itself, so they keep firing after the node moves, including into
+  another document. A `useLayoutEffect` with no deps calls `appendChild` to move the wrapper into
+  whichever element last registered for the tab's panel id (`slotRegistry`,
+  `components/layout/tab-pool-registry.ts`); `TabHostWindowContent`'s slot `div` is always mounted
+  (never swapped for a placeholder), because it may currently be living inside the PiP document.
+- **Persistence.** Window panels persist to their own global `localStorage["ppm-window-panels"]`
+  key (`stores/window-panel-persistence.ts`), separate from the per-project `ppm-panels-*` blob and
+  not synced to the server — the same limitation window geometry (`ppm-windows`) already has.
+  `WINDOW_KINDS` (`window-store-types.ts`) is the single list both the window store and
+  `window-persistence.ts` filter against; `team-member` is excluded from restore because its body
+  streams a live subagent session that cannot survive a reload.
+- **Reconcile.** The two halves persist separately, so a reload can restore one without the other.
+  `reconcileTabHostWindows` (`stores/window-panel-reconcile.ts`), run once per project via
+  `useWindowPanelReconcile()` after the window layer restores, and unconditionally below `md` (the
+  window layer never mounts there): a panel whose window is gone comes back to the grid; a window
+  with no panel behind it closes.
+- **PiP host.** `attachPipHost`/`isDocumentPipSupported` (`floating-window/pip/pip-host.ts`,
+  `pip-support.ts`) move a window's *slot* element — never a tab's own wrapper — into a
+  `documentPictureInPicture` window, one at a time per page. `pagehide` triggers a synchronous
+  restore (no `await` between it and the DOM move) so a closing PiP document never strips listeners
+  off a still-live terminal. `pip-style-copy.ts` mirrors stylesheets + `adoptedStyleSheets` once and
+  `<html>` class/inline theme CSS vars + `<body>` class **and inline style** on every theme change
+  (the page background is an inline `background: var(--bg)` on `<body>` in `index.html`, not a
+  class), plus a MutationObserver for Vite HMR-injected `<style>` tags. `pip-key-forward.ts`
+  re-dispatches keydown/keyup from the PiP window onto the main window for app-level shortcuts,
+  skipping targets that own their own input (`input`, `.monaco-editor`, `.xterm-helper-textarea`,
+  etc.). `pip-resize-signal.ts` dispatches a non-bubbling `ppm:host-resize` CustomEvent on each
+  `[data-tab-pool-id]` wrapper inside the slot (on attach, every PiP `resize`, and on detach); the
+  terminal and editors subscribe via `onHostResize` and re-fit, because main-window
+  `ResizeObserver`s are late or silent for a PiP-driven size.
+- **Radix portals in PiP.** `PortalContainerProvider` (`components/ui/portal-container-context.tsx`)
+  is mounted inside `ReparentingTab` around each tab's content, fed the PiP document's `body` while
+  that tab's window is in PiP (`usePipPortalContainer`, `window-pip-registry.ts`) — so a tab's own
+  dropdowns/tooltips/dialogs render inside the PiP document instead of opening unreachably in the
+  main window. `undefined` (document default) while docked.
+- **Known limitations** (see the comment block atop `pip/pip-caption-button.tsx`): sonner toasts
+  always render in the main window (one app-root toaster); `useIsMobile()`/Tailwind `md:` read the
+  main window's viewport, not the PiP window's; `onSelect`/`selectionchange` degrades for PiP
+  content; the terminal's reconnect check reads the main document's visibility; Monaco keybindings
+  (Ctrl+Z, Ctrl+F, …) don't fire while the editor sits in PiP (typing still reaches the buffer); a
+  tab-host window's titlebar keeps the tab title captured at pop-out time.
+- **Mobile.** Pop-out and PiP are hidden entirely below `md` (`useIsMobile()`) — never a scaled-down
+  window.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.18.10",
+  "version": "0.18.12",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "SEE LICENSE IN LICENSE",

package/src/web/components/chat/file-picker.tsx

@@ -77,8 +77,11 @@ export function FilePicker({
     const handler = (e: globalThis.KeyboardEvent) => {
       if (handleKeyDown(e)) e.stopPropagation();
     };
-    document.addEventListener("keydown", handler, true);
-    return () => document.removeEventListener("keydown", handler, true);
+    // The list's own document — in a picture-in-picture window the keys are
+    // delivered there, not to the main document.
+    const doc = listRef.current?.ownerDocument ?? document;
+    doc.addEventListener("keydown", handler, true);
+    return () => doc.removeEventListener("keydown", handler, true);
   }, [visible, handleKeyDown]);
 
   if (!visible || filtered.length === 0) return null;

package/src/web/components/chat/mode-selector.tsx

@@ -39,8 +39,11 @@ export function ModeSelector({ value, onChange, open, onOpenChange }: ModeSelect
         onOpenChange(false);
       }
     };
-    document.addEventListener("mousedown", handler);
-    return () => document.removeEventListener("mousedown", handler);
+    // The panel's own document — in a picture-in-picture window the main
+    // document never sees these clicks, so the panel would never close.
+    const doc = panelRef.current?.ownerDocument ?? document;
+    doc.addEventListener("mousedown", handler);
+    return () => doc.removeEventListener("mousedown", handler);
   }, [open, onOpenChange]);
 
   // Focus current mode on open

package/src/web/components/chat/model-selector.tsx

@@ -50,8 +50,11 @@ export function ModelSelector({ value, onChange, projectName, providerId, disabl
         setOpen(false);
       }
     };
-    document.addEventListener("mousedown", handler);
-    return () => document.removeEventListener("mousedown", handler);
+    // The panel's own document — in a picture-in-picture window the main
+    // document never sees these clicks, so the panel would never close.
+    const doc = panelRef.current?.ownerDocument ?? document;
+    doc.addEventListener("mousedown", handler);
+    return () => doc.removeEventListener("mousedown", handler);
   }, [open]);
 
   // Focus current on open

package/src/web/components/chat/model-thinking-selector.tsx

@@ -69,8 +69,11 @@ export function ModelThinkingSelector({
     const handler = (e: MouseEvent) => {
       if (panelRef.current && !panelRef.current.contains(e.target as Node)) setOpen(false);
     };
-    document.addEventListener("mousedown", handler);
-    return () => document.removeEventListener("mousedown", handler);
+    // The panel's own document — in a picture-in-picture window the main
+    // document never sees these clicks, so the panel would never close.
+    const doc = panelRef.current?.ownerDocument ?? document;
+    doc.addEventListener("mousedown", handler);
+    return () => doc.removeEventListener("mousedown", handler);
   }, [open, isMobile]);
 
   const current = models.find((m) => m.value === model);

package/src/web/components/chat/provider-selector.tsx

@@ -45,8 +45,11 @@ export function ProviderSelector({ value, onChange, projectName }: ProviderSelec
         setOpen(false);
       }
     };
-    document.addEventListener("mousedown", handler);
-    return () => document.removeEventListener("mousedown", handler);
+    // The panel's own document — in a picture-in-picture window the main
+    // document never sees these clicks, so the panel would never close.
+    const doc = panelRef.current?.ownerDocument ?? document;
+    doc.addEventListener("mousedown", handler);
+    return () => doc.removeEventListener("mousedown", handler);
   }, [open]);
 
   // Focus current on open

package/src/web/components/chat/slash-command-picker.tsx

@@ -117,8 +117,11 @@ export function SlashCommandPicker({
     const handler = (e: globalThis.KeyboardEvent) => {
       if (handleKeyDown(e)) e.stopPropagation();
     };
-    document.addEventListener("keydown", handler, true);
-    return () => document.removeEventListener("keydown", handler, true);
+    // The list's own document — in a picture-in-picture window the keys are
+    // delivered there, not to the main document.
+    const doc = listRef.current?.ownerDocument ?? document;
+    doc.addEventListener("keydown", handler, true);
+    return () => doc.removeEventListener("keydown", handler, true);
   }, [visible, handleKeyDown]);
 
   const handleRefresh = useCallback(() => {

package/src/web/components/editor/code-editor.tsx

@@ -22,6 +22,7 @@ import type { DbQueryResult } from "../database/use-database";
 // Single source of truth: the explorer decides whether a double-click can open a file at
 // all from these very sets, so they must not be redeclared here.
 import { AUDIO_EXTS, IMAGE_EXTS, SQLITE_EXTS, VIDEO_EXTS } from "@/components/os-explorer/can-open-in-ppm";
+import { onHostResize } from "@/components/floating-window/pip/pip-resize-signal";
 
 const MarkdownRenderer = lazy(() =>
   import("@/components/shared/markdown-renderer").then((m) => ({ default: m.MarkdownRenderer }))
@@ -247,6 +248,12 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
     };
   }, [isMobile]);
 
+  // Host-driven resize (picture-in-picture): `automaticLayout` never fires for
+  // a size driven by another document, and after the return the editor keeps
+  // the PiP size until it is told to lay out again.
+  // Re-runs on loading/error because the container only exists once the file rendered.
+  useEffect(() => onHostResize(containerRef.current, () => editorRef.current?.layout()), [loading, error]);
+
   // CodeLens: inline Run buttons between SQL statements
   const codeLensDisposable = useRef<MonacoType.IDisposable[]>([]);
   const runSqlRef = useRef(runSqlInViewer);
@@ -820,10 +827,13 @@ function SqlResultPanel({ result, error, loading, connName, onClose, onOpenInTab
     e.preventDefault();
     const startY = e.clientY;
     const startH = panelHeight;
+    // The handle's own document — the editor may be living in a PiP window,
+    // where the main document never sees these pointer events.
+    const doc = e.currentTarget.ownerDocument;
     const onMove = (ev: MouseEvent) => setPanelHeight(Math.max(80, startH + (startY - ev.clientY)));
-    const onUp = () => { document.removeEventListener("mousemove", onMove); document.removeEventListener("mouseup", onUp); };
-    document.addEventListener("mousemove", onMove);
-    document.addEventListener("mouseup", onUp);
+    const onUp = () => { doc.removeEventListener("mousemove", onMove); doc.removeEventListener("mouseup", onUp); };
+    doc.addEventListener("mousemove", onMove);
+    doc.addEventListener("mouseup", onUp);
   }, [panelHeight]);
 
   return (

package/src/web/components/editor/conflict-editor.tsx

@@ -5,6 +5,7 @@ import { api, projectUrl } from "@/lib/api-client";
 import { useShallow } from "zustand/react/shallow";
 import { useSettingsStore } from "@/stores/settings-store";
 import { useMonacoTheme } from "@/lib/use-monaco-theme";
+import { onHostResize } from "@/components/floating-window/pip/pip-resize-signal";
 import { Loader2 } from "lucide-react";
 
 function getMonacoLanguage(filename: string): string {
@@ -117,6 +118,14 @@ export function ConflictEditor({ metadata }: ConflictEditorProps) {
     return () => ro.disconnect();
   }, []);
 
+  // Host-driven resize (picture-in-picture): `automaticLayout` never fires for a
+  // size driven by another document, and the editor keeps the PiP size after the
+  // return. Re-runs on loading/error because the container renders only then.
+  useEffect(
+    () => onHostResize(containerRef.current, () => editorRef.current?.layout()),
+    [loading, error],
+  );
+
   // Load file content
   useEffect(() => {
     if (!filePath || !projectName) return;

package/src/web/components/editor/diff-viewer.tsx

@@ -4,6 +4,7 @@ import { api, projectUrl } from "@/lib/api-client";
 import { useShallow } from "zustand/react/shallow";
 import { useSettingsStore } from "@/stores/settings-store";
 import { useMonacoTheme } from "@/lib/use-monaco-theme";
+import { onHostResize } from "@/components/floating-window/pip/pip-resize-signal";
 import { Loader2, FileCode, WrapText } from "lucide-react";
 
 function getMonacoLanguage(filename: string): string {
@@ -60,6 +61,14 @@ export function DiffViewer({ metadata }: DiffViewerProps) {
     return () => ro.disconnect();
   }, [loading, error]);
 
+  // Host-driven resize (picture-in-picture): `automaticLayout` never fires for a
+  // size driven by another document, and the editor keeps the PiP size after the
+  // return. Re-runs on loading/error because the container renders only then.
+  useEffect(
+    () => onHostResize(containerRef.current, () => diffEditorRef.current?.layout()),
+    [loading, error],
+  );
+
   useEffect(() => {
     if (isInline) return;
     if (!projectName) return;

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

@@ -1,16 +1,25 @@
 /**
- * One floating window: geometry, gestures, keyboard, and a chrome slot.
+ * One floating window: geometry, gestures, keyboard, the skinned chrome, and the body
+ * element every kind renders into.
  *
  * Geometry is written straight to the element instead of through React state — a drag emits
  * a pointermove per frame and re-rendering the window (and its content) on each one is what
  * makes a window manager feel heavy. The store is written only when a gesture ends, which is
  * also the moment the rect is rounded to whole pixels.
+ *
+ * Picture-in-picture is a capability of the FRAME, not of any one kind: the body element is
+ * published as this window's PiP slot, so an explorer, a system monitor, a team-member
+ * session and a detached tab all pop out through the same titlebar button.
  */
 
 import { useCallback, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
 import { cn } from "@/lib/utils";
-import { DefaultWindowChrome } from "./default-window-chrome";
-import { TITLEBAR_HEIGHT, type WindowChrome } from "./window-chrome-contract";
+import { PortalContainerProvider } from "@/components/ui/portal-container-context";
+import { TITLEBAR_HEIGHT } from "./window-chrome-contract";
+import { useWindowBodyElement } from "./use-window-body-element";
+import { WindowPipPlaceholder } from "./window-pip-placeholder";
+import { WindowSkinChrome } from "./window-skin-chrome";
 import { windowZIndex, type Bounds, type Rect } from "./window-geometry";
 import { useWindowStore, type WindowRuntimeState } from "./window-store";
 import { useWindowDrag } from "./use-window-drag";
@@ -28,8 +37,6 @@ export interface FloatingWindowProps {
   getScale: () => number;
   /** Told when a gesture starts/ends so the layer can raise its capture overlay. */
   onGestureActive: (active: boolean) => void;
-  /** Skin component for the titlebar; owns its own hooks and state. */
-  chrome?: WindowChrome;
   children: ReactNode;
 }
 
@@ -47,7 +54,6 @@ export function FloatingWindow({
   focused,
   getScale,
   onGestureActive,
-  chrome,
   children,
 }: FloatingWindowProps) {
   const rootRef = useRef<HTMLDivElement>(null);
@@ -57,6 +63,8 @@ export function FloatingWindow({
   const minimized = win.state === "minimized";
   const rect: Rect = maximized ? { x: 0, y: 0, w: bounds.w, h: bounds.h } : win.rect;
 
+  const { body, pip } = useWindowBodyElement(win.id, rootRef, minimized);
+
   // Latest committed geometry, read at the first frame of a gesture (never mid-gesture,
   // where it would compound the cumulative movement).
   const rectRef = useRef(rect);
@@ -112,8 +120,6 @@ export function FloatingWindow({
     movable: !maximized,
   });
 
-  const Chrome = chrome ?? DefaultWindowChrome;
-
   return (
     <div
       ref={rootRef}
@@ -131,7 +137,7 @@ export function FloatingWindow({
         gesturing ? "transition-none" : "transition-[transform,width,height] duration-150 motion-reduce:transition-none",
       )}
     >
-      <Chrome
+      <WindowSkinChrome
         id={win.id}
         kind={win.kind}
         title={title}
@@ -152,16 +158,18 @@ export function FloatingWindow({
         onClose={close}
       />
 
-
-      {/* Always mounted, even minimized — content owns per-window state (explorer history,
-          selection, filter) that a remount would wipe. Hidden via CSS, not unmounted. */}
-      <div className={cn("relative flex-1 min-h-0 overflow-hidden rounded-b-[8px] bg-panel", minimized && "hidden")}>
-        {children}
-      </div>
+      {pip && <WindowPipPlaceholder pip={pip} minimized={minimized} />}
 
       {!maximized && !minimized && (
         <WindowResizeHandles bind={(handle) => bindResize(handle) as Record<string, unknown>} />
       )}
+
+      {/* Radix primitives inside the content must portal into whichever document the body
+          currently lives in; `undefined` (never `null`) restores the document default. */}
+      {createPortal(
+        <PortalContainerProvider container={pip?.pipWindow.document.body}>{children}</PortalContainerProvider>,
+        body,
+      )}
     </div>
   );
 }

package/src/web/components/floating-window/pip/pip-caption-button.tsx

@@ -0,0 +1,108 @@
+/**
+ * Titlebar button that moves a floating window's body into a Document Picture-in-Picture
+ * window and back. Every skin renders it, so every window kind gets the capability — the
+ * skin only supplies the box (`className`) that matches its own caption metric.
+ *
+ * The button is absent, never disabled, where the API is missing (Firefox, Safari, any
+ * non-secure context) — a caption button that only ever explains itself is worse than no
+ * button at all.
+ *
+ * Known limitations while a window's body runs in PiP; expected behaviour, not regressions:
+ *  - Toasts render in the main window. Sonner mounts one toaster at the app root and it
+ *    stays there, so a message raised from the PiP body appears behind it.
+ *  - `useIsMobile()` and Tailwind `md:` variants read the MAIN window's viewport, so the
+ *    content keeps its desktop layout in a narrow PiP window instead of switching to mobile.
+ *  - React's `onSelect`/`selectionchange` is delegated from the document the app root is
+ *    mounted in; selection-driven UI degrades for content living in the PiP document.
+ *  - `use-terminal`'s reconnect check reads the main document's visibility, so a hidden
+ *    main tab is treated as hidden even while its terminal is visible in PiP.
+ *  - Monaco chords (Ctrl+Z, Ctrl+F, …) do not fire while the editor sits in PiP: typing
+ *    reaches the buffer, but the keybinding dispatcher listens on the window the editor was
+ *    created in. Undo works again as soon as the body is brought back.
+ *  - A tab-host titlebar shows the tab title captured at pop-out time; a tab renamed
+ *    afterwards (a chat acquiring a name) keeps the old caption until it is popped out again.
+ */
+
+import { PictureInPicture2 } from "lucide-react";
+import { toast } from "sonner";
+import { cn } from "@/lib/utils";
+import { TITLEBAR_HEIGHT } from "../window-chrome-contract";
+import { useWindowStore } from "../window-store";
+import { setWindowPip, windowPip, windowSlot, useWindowPip } from "../window-pip-registry";
+import { activePipHost, attachPipHost } from "./pip-host";
+import { focusPipDocument } from "./pip-focus-target";
+import { isDocumentPipSupported } from "./pip-support";
+
+export interface PipCaptionButtonProps {
+  /** Window id — the registry key for both the body element and the resulting handle. */
+  id: string;
+  /** The skin's caption-button box. Defaults to a compact icon button. */
+  className?: string;
+}
+
+const DEFAULT_BOX =
+  "grid place-items-center size-6 rounded text-text-2 can-hover:hover:bg-surface-elevated can-hover:hover:text-text transition-colors";
+
+export function PipCaptionButton({ id, className }: PipCaptionButtonProps) {
+  const pip = useWindowPip(id);
+
+  if (!isDocumentPipSupported()) return null;
+
+  const togglePip = () => {
+    const active = windowPip(id);
+    if (active) {
+      active.detach();
+      return;
+    }
+
+    const slot = windowSlot(id);
+    if (!slot) {
+      toast.error("This window has nothing to pop out yet");
+      return;
+    }
+    const rect = useWindowStore.getState().windows[id]?.rect;
+
+    // attachPipHost() is the first call that can consume the click's transient
+    // activation; anything awaited before it costs the gesture and the request is
+    // rejected. Only synchronous store/registry reads may precede it. The PiP window
+    // shows the body alone, so the titlebar comes off the requested height.
+    attachPipHost(slot, {
+      // A zero falls through to the host's minimum size rather than a magic default.
+      width: rect?.w ?? 0,
+      height: rect ? rect.h - TITLEBAR_HEIGHT : 0,
+      onDetach: () => setWindowPip(id, null),
+    })
+      .then((handle) => {
+        // The window can be closed before this resolves, in which case onDetach has
+        // already cleared the state and storing the handle would strand a dead one.
+        // A null handle is that same case, detected inside the host. The slot check
+        // covers a body that unmounted and came back: the new one is not this one.
+        if (!handle || activePipHost() !== handle) return;
+        if (windowSlot(id) !== slot) {
+          handle.detach();
+          return;
+        }
+        setWindowPip(id, handle);
+        // A DOM move carries no focus with it: without this the popped-out terminal or
+        // editor is visible but swallows nothing until the user clicks it.
+        focusPipDocument(handle.pipWindow.document);
+      })
+      .catch(() => {
+        toast.error("Could not open the picture-in-picture window");
+      });
+  };
+
+  const label = pip ? "Bring back from picture-in-picture" : "Open in picture-in-picture";
+  return (
+    <button
+      type="button"
+      title={label}
+      aria-label={label}
+      aria-pressed={Boolean(pip)}
+      className={cn(className ?? DEFAULT_BOX, pip && "text-primary")}
+      onClick={togglePip}
+    >
+      <PictureInPicture2 className="size-3.5" />
+    </button>
+  );
+}

package/src/web/components/floating-window/pip/pip-focus-target.ts

@@ -0,0 +1,58 @@
+/**
+ * Picks what to focus inside a freshly opened PiP window.
+ *
+ * Moving a subtree into another document does not move focus with it, so a popped-out
+ * terminal or editor would sit there swallowing nothing until the user clicked it. The
+ * order below is "the thing you type into first": xterm's hidden helper textarea, Monaco's
+ * edit context or textarea, then any other text surface, and only then the first focusable
+ * control.
+ *
+ * A panel slot can hold several tabs (the inactive ones are `display: none`), so hidden
+ * candidates are skipped — focusing one of those steals input from the visible tab.
+ */
+
+/** The subset of an element this module touches; keeps the helper testable without a DOM. */
+export interface FocusCandidate {
+  focus(): void;
+  checkVisibility?(): boolean;
+  readonly offsetParent?: unknown;
+}
+
+/** Text surfaces first, in the order a user would expect to type into them. */
+export const PIP_FOCUS_SELECTORS = [
+  ".xterm-helper-textarea",
+  ".native-edit-context",
+  "textarea",
+  "[contenteditable]",
+  'button, [href], input, select, [tabindex]:not([tabindex="-1"])',
+];
+
+function isVisible(el: FocusCandidate): boolean {
+  // checkVisibility() is the accurate answer (display, content-visibility, hidden
+  // attribute) and exists wherever Document PiP does; offsetParent is the fallback
+  // for a test double or an older engine.
+  if (typeof el.checkVisibility === "function") return el.checkVisibility();
+  return el.offsetParent !== null && el.offsetParent !== undefined;
+}
+
+/**
+ * First visible match for the selector list, or null.
+ *
+ * Takes a query function rather than a root node so the caller keeps its own element type
+ * (`doc.querySelectorAll<HTMLElement>`) and a test can pass a plain fake.
+ */
+export function pipFocusTarget<T extends FocusCandidate>(
+  query: (selector: string) => Iterable<T>,
+): T | null {
+  for (const selector of PIP_FOCUS_SELECTORS) {
+    for (const el of query(selector)) {
+      if (isVisible(el)) return el;
+    }
+  }
+  return null;
+}
+
+/** Focus the popped-out tab's primary input so the user can type straight away. */
+export function focusPipDocument(doc: Document): void {
+  pipFocusTarget<HTMLElement>((selector) => doc.querySelectorAll<HTMLElement>(selector))?.focus();
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Size math for the PiP window request.
+ *
+ * Kept free of DOM reads (the screen bounds are an argument) so it is unit
+ * testable and so a caller can pass a floating window rect straight through.
+ */
+
+export interface PipSize {
+  width: number;
+  height: number;
+}
+
+/** Below this a terminal/editor is unusable, and Chromium rejects tiny sizes. */
+export const MIN_PIP_WIDTH = 320;
+export const MIN_PIP_HEIGHT = 240;
+
+/** Fallback bounds when no screen is available (SSR, tests). */
+const FALLBACK_BOUNDS: PipSize = { width: 1920, height: 1080 };
+
+function clampAxis(value: number, min: number, max: number): number {
+  // Non-finite input (NaN from an unmeasured rect) collapses to the minimum
+  // rather than propagating into the request.
+  if (!Number.isFinite(value)) return min;
+  return Math.round(Math.min(Math.max(value, min), Math.max(min, max)));
+}
+
+/** Read the usable screen area; safe to call without a window. */
+export function screenBounds(): PipSize {
+  if (typeof window === "undefined" || !window.screen) return FALLBACK_BOUNDS;
+  const { availWidth, availHeight } = window.screen;
+  return {
+    width: Number.isFinite(availWidth) && availWidth > 0 ? availWidth : FALLBACK_BOUNDS.width,
+    height: Number.isFinite(availHeight) && availHeight > 0 ? availHeight : FALLBACK_BOUNDS.height,
+  };
+}
+
+/**
+ * Clamp a requested inner size to [min, screen] and round to whole CSS px.
+ * Chromium may still ignore the hint entirely — never assume the result.
+ */
+export function clampPipSize(size: PipSize, bounds: PipSize = screenBounds()): PipSize {
+  return {
+    width: clampAxis(size.width, MIN_PIP_WIDTH, bounds.width),
+    height: clampAxis(size.height, MIN_PIP_HEIGHT, bounds.height),
+  };
+}