@hienlh/ppm 0.18.12 → 0.18.14

package/src/types/config.ts

@@ -35,6 +35,23 @@ export interface PpmConfig {
   clawbot?: PPMBotConfig;
   cloud_url?: string;
   query_audit: QueryAuditConfig;
+  tunnel: TunnelConfig;
+}
+
+/**
+ * Persisted named-tunnel state. `namedTunnelToken` is secret-by-contract —
+ * guarded by the config-key denylist and never returned unmasked by any route.
+ * `zoneID`/`accountID` are pinned at setup and re-checked on every reuse.
+ */
+export interface TunnelConfig {
+  mode: "quick" | "named";
+  namedTunnelName?: string;
+  namedTunnelHostname?: string;
+  namedTunnelToken?: string;
+  zoneID?: string;
+  accountID?: string;
+  /** User answered "no domain" — popup must never nag again. */
+  dismissed?: boolean;
 }
 
 export interface QueryAuditConfig {
@@ -131,6 +148,9 @@ export const DEFAULT_CONFIG: PpmConfig = {
     permission_mode: "bypassPermissions",
     debounce_ms: 2000,
   },
+  tunnel: {
+    mode: "quick",
+  },
 };
 
 const VALID_TYPES = ["agent-sdk", "cli", "mock"] as const;
@@ -264,5 +284,16 @@ export function sanitizeConfig(config: PpmConfig): boolean {
     }
   }
 
+  // Only repair `tunnel` when storage itself is malformed (wrong type / bad enum).
+  // Never strip namedTunnel*/zoneID/accountID just because mode is "quick" or the
+  // combination looks "incomplete" — that degrade-to-quick judgment belongs to
+  // the runtime resolver (resolveTunnelConfig), or /disable's "keep the config so
+  // Retry works" contract silently breaks.
+  if (typeof config.tunnel !== "object" || config.tunnel === null ||
+      (config.tunnel.mode !== "quick" && config.tunnel.mode !== "named")) {
+    config.tunnel = structuredClone(DEFAULT_CONFIG.tunnel);
+    dirty = true;
+  }
+
   return dirty;
 }

package/src/web/app.tsx

@@ -27,6 +27,7 @@ import { useServerReload } from "@/hooks/use-server-reload";
 import { CommandPalette } from "@/components/layout/command-palette";
 import { ComparePicker } from "@/components/editor/compare-picker";
 import { BugReportPopup } from "@/components/shared/bug-report-popup";
+import { NamedTunnelSetupPopup } from "@/components/tunnels/named-tunnel/named-tunnel-setup-popup";
 import { ImageOverlay } from "@/components/shared/image-overlay";
 import { DiagramOverlay } from "@/components/shared/diagram-overlay";
 import { BackgroundOutputPanel } from "@/components/chat/background-output-panel";
@@ -359,6 +360,10 @@ export function App() {
         {/* Global bug report popup */}
         <BugReportPopup />
 
+        {/* Named-tunnel first-run setup popup — hidden unless auth is on, mode is
+            still quick and the user has not dismissed it (or a cert needs renewal) */}
+        <NamedTunnelSetupPopup />
+
         {/* Global image lightbox */}
         <ImageOverlay />
 

package/src/web/components/chat/chat-history-bar.tsx

@@ -1,5 +1,5 @@
 import { useState, useEffect, useCallback, useRef, type MouseEvent } from "react";
-import { History, Settings2, Loader2, MessageSquare, RefreshCw, Search, Pencil, Check, X, BellOff, Circle, Pin, PinOff, Trash2, Users, Bot, Tags, CalendarX2 } from "lucide-react";
+import { History, Settings2, Loader2, MessageSquare, RefreshCw, Search, Pencil, Check, X, Pin, PinOff, Trash2, Users, Bot, Tags, CalendarX2 } from "lucide-react";
 import { Activity } from "lucide-react";
 import { api, projectUrl } from "@/lib/api-client";
 import { useTabStore } from "@/stores/tab-store";
@@ -8,7 +8,8 @@ import { cn } from "@/lib/utils";
 import { AISettingsSection } from "@/components/settings/ai-settings-section";
 import { TagSettingsSection } from "@/components/settings/tag-settings-section";
 import { SessionContextMenu } from "./session-context-menu";
-import { SessionDebugButton } from "./session-debug-dialog";
+import { SessionDebugDialog } from "./session-debug-dialog";
+import { ChatToolbarOverflowMenu } from "./chat-toolbar-overflow-menu";
 import { UsageDetailPanel } from "./usage-badge";
 import { CodexUsagePanel } from "./codex-usage-panel";
 import { TeamActivityPanel } from "./team-activity-panel";
@@ -82,6 +83,7 @@ export function ChatHistoryBar({
   const [selectedTagId, setSelectedTagId] = useState<number | null>(null);
   const [tagCounts, setTagCounts] = useState<Record<number, number>>({});
   const [showTagSettings, setShowTagSettings] = useState(false);
+  const [debugOpen, setDebugOpen] = useState(false);
   const editInputRef = useRef<HTMLInputElement>(null);
   const openTab = useTabStore((s) => s.openTab);
   const PAGE_SIZE = 50;
@@ -273,112 +275,88 @@ export function ChatHistoryBar({
 
   return (
     <div className="border-b border-border/50">
-      {/* Toolbar row — all buttons on one line */}
+      {/* Toolbar row — status chips scroll on the left, controls stay pinned right.
+          A narrow chat pane must never push the connection indicator out of view. */}
       <div className="flex items-center gap-1 px-2 py-1">
-        {/* History */}
-        <button
-          onClick={() => togglePanel("history")}
-          className={`flex items-center gap-1 px-1.5 py-0.5 rounded text-[11px] transition-colors ${
-            activePanel === "history" ? "text-primary bg-primary/10" : "text-text-secondary hover:text-foreground hover:bg-surface-elevated"
-          }`}
-        >
-          <History className="size-3" />
-          <span>History</span>
-        </button>
-
-        {/* Active provider + AI Settings (combined) */}
-        {sessionId && providerId && providerId !== "mock" ? (
+        <div className="flex min-w-0 flex-1 items-center gap-1 overflow-x-auto scrollbar-none">
+          {/* History */}
           <button
-            onClick={() => togglePanel("config")}
-            className={`flex items-center gap-1 px-1.5 py-0.5 rounded text-[11px] transition-colors ${
-              activePanel === "config" ? "text-primary bg-primary/10" : "text-text-secondary hover:text-foreground hover:bg-surface-elevated"
+            onClick={() => togglePanel("history")}
+            className={`shrink-0 flex items-center gap-1 px-1.5 py-0.5 rounded text-[11px] transition-colors ${
+              activePanel === "history" ? "text-primary bg-primary/10" : "text-text-secondary hover:text-foreground hover:bg-surface-elevated"
             }`}
-            title="AI Settings"
           >
-            <ProviderBadge providerId={providerId} />
-            <span className="capitalize">{providerId}</span>
+            <History className="size-3" />
+            <span>History</span>
           </button>
-        ) : (
-          <button
-            onClick={() => togglePanel("config")}
-            className={`p-1 rounded transition-colors ${
-              activePanel === "config" ? "text-primary bg-primary/10" : "text-text-subtle hover:text-text-secondary hover:bg-surface-elevated"
-            }`}
-            title="AI Settings"
-          >
-            <Settings2 className="size-3" />
-          </button>
-        )}
-
-        {/* Usage & Accounts — Claude and Codex both surface usage + account mgmt here */}
-        {(isClaudeProvider || isCodexProvider) ? (
-          <button
-            onClick={() => togglePanel("usage")}
-            className={`flex items-center gap-1 px-1.5 py-0.5 rounded text-[11px] font-medium tabular-nums transition-colors hover:bg-surface-elevated ${
-              activePanel === "usage" ? "bg-primary/10" : ""
-            } ${usageColor}`}
-            title="Usage limits"
-          >
-            <Activity className="size-3" />
-            {usageInfo.activeAccountLabel && (
-              <span className="text-text-secondary font-normal truncate max-w-[60px]">[{usageInfo.activeAccountLabel}]</span>
-            )}
-            <span>5h:{fiveHourPct != null ? `${fiveHourPct}%` : "--%"}</span>
-            <span className="text-text-subtle">·</span>
-            <span>Wk:{sevenDayPct != null ? `${sevenDayPct}%` : "--%"}</span>
-          </button>
-        ) : null}
-
-        {/* Team activity */}
-        {teamActivity?.hasTeams && (
-          <button
-            onClick={() => {
-              togglePanel("team");
-              onTeamOpen?.();
-            }}
-            className={`relative flex items-center gap-1 px-1.5 py-0.5 rounded text-[11px] transition-colors ${
-              activePanel === "team" ? "text-primary bg-primary/10" : "text-text-secondary hover:text-foreground hover:bg-surface-elevated"
-            }`}
-            title="Team activity"
-          >
-            <Users className="size-3" />
-            <span>Team</span>
-            {(teamActivity.unreadCount ?? 0) > 0 && (
-              <span className="absolute -top-0.5 -right-0.5 size-2 bg-primary rounded-full animate-pulse" />
-            )}
-          </button>
-        )}
 
-        {/* Spacer */}
-        <div className="flex-1" />
+          {/* Active provider + AI Settings (combined) */}
+          {sessionId && providerId && providerId !== "mock" ? (
+            <button
+              onClick={() => togglePanel("config")}
+              className={`shrink-0 flex items-center gap-1 px-1.5 py-0.5 rounded text-[11px] transition-colors ${
+                activePanel === "config" ? "text-primary bg-primary/10" : "text-text-secondary hover:text-foreground hover:bg-surface-elevated"
+              }`}
+              title="AI Settings"
+            >
+              <ProviderBadge providerId={providerId} />
+              <span className="capitalize">{providerId}</span>
+            </button>
+          ) : (
+            <button
+              onClick={() => togglePanel("config")}
+              className={`shrink-0 p-1 rounded transition-colors ${
+                activePanel === "config" ? "text-primary bg-primary/10" : "text-text-subtle hover:text-text-secondary hover:bg-surface-elevated"
+              }`}
+              title="AI Settings"
+            >
+              <Settings2 className="size-3" />
+            </button>
+          )}
 
-        {/* Mark as read */}
-        {hasUnread && sessionId && (
-          <button
-            onClick={() => clearForSession(sessionId)}
-            className="p-1 rounded text-warning hover:text-warning/80 hover:bg-surface-elevated transition-colors"
-            title="Mark as read"
-          >
-            <BellOff className="size-3" />
-          </button>
-        )}
+          {/* Usage & Accounts — Claude and Codex both surface usage + account mgmt here */}
+          {(isClaudeProvider || isCodexProvider) ? (
+            <button
+              onClick={() => togglePanel("usage")}
+              className={`shrink-0 flex items-center gap-1 px-1.5 py-0.5 rounded text-[11px] font-medium tabular-nums transition-colors hover:bg-surface-elevated ${
+                activePanel === "usage" ? "bg-primary/10" : ""
+              } ${usageColor}`}
+              title="Usage limits"
+            >
+              <Activity className="size-3" />
+              {usageInfo.activeAccountLabel && (
+                <span className="text-text-secondary font-normal truncate max-w-[60px]">[{usageInfo.activeAccountLabel}]</span>
+              )}
+              <span>5h:{fiveHourPct != null ? `${fiveHourPct}%` : "--%"}</span>
+              <span className="text-text-subtle">·</span>
+              <span>Wk:{sevenDayPct != null ? `${sevenDayPct}%` : "--%"}</span>
+            </button>
+          ) : null}
 
-        {/* Mark as unread */}
-        {!hasUnread && sessionId && (
-          <button
-            onClick={() => markUnread(sessionId, projectName)}
-            className="p-1 rounded text-primary hover:text-primary/80 hover:bg-surface-elevated transition-colors"
-            title="Mark as unread"
-          >
-            <Circle className="size-3 fill-current" />
-          </button>
-        )}
+          {/* Team activity */}
+          {teamActivity?.hasTeams && (
+            <button
+              onClick={() => {
+                togglePanel("team");
+                onTeamOpen?.();
+              }}
+              className={`shrink-0 relative flex items-center gap-1 px-1.5 py-0.5 rounded text-[11px] transition-colors ${
+                activePanel === "team" ? "text-primary bg-primary/10" : "text-text-secondary hover:text-foreground hover:bg-surface-elevated"
+              }`}
+              title="Team activity"
+            >
+              <Users className="size-3" />
+              <span>Team</span>
+              {(teamActivity.unreadCount ?? 0) > 0 && (
+                <span className="absolute -top-0.5 -right-0.5 size-2 bg-primary rounded-full animate-pulse" />
+              )}
+            </button>
+          )}
 
-        {/* Debug info — copy session IDs + JSONL path */}
-        {sessionId && (
-          <SessionDebugButton sessionId={sessionId} projectName={projectName} />
-        )}
+        </div>
 
+        {/* Pinned controls — always visible, never scrolled away */}
+        <div className="flex shrink-0 items-center gap-1 pl-1">
         {/* Reload messages + connection status */}
         {onReload && (
           <button
@@ -397,8 +375,27 @@ export function ChatHistoryBar({
             <span className={`absolute -top-0.5 -right-0.5 size-1.5 rounded-full ${isConnected ? "bg-success" : "bg-error animate-pulse"}`} />
           </button>
         )}
+
+        {/* Overflow menu — session actions, and the home for future toolbar actions */}
+        {sessionId && (
+          <ChatToolbarOverflowMenu
+            hasUnread={hasUnread}
+            onToggleUnread={() => hasUnread ? clearForSession(sessionId) : markUnread(sessionId, projectName)}
+            onOpenDebug={() => setDebugOpen(true)}
+          />
+        )}
+        </div>
       </div>
 
+      {sessionId && (
+        <SessionDebugDialog
+          sessionId={sessionId}
+          projectName={projectName}
+          open={debugOpen}
+          onOpenChange={setDebugOpen}
+        />
+      )}
+
       {/* Panels — only one visible at a time */}
 
       {/* History panel */}

package/src/web/components/chat/chat-toolbar-overflow-menu.tsx

@@ -0,0 +1,57 @@
+import { BellOff, Bug, Circle, MoreHorizontal } from "lucide-react";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+
+/**
+ * Session actions that do not earn permanent space in the chat toolbar.
+ *
+ * The toolbar's left zone scrolls once the chat panel gets narrow, so every
+ * control pinned on the right competes for the handful of pixels that stay
+ * visible. Only the connection indicator earns that spot; infrequent actions
+ * live behind this trigger, which is also where future toolbar actions belong.
+ */
+export function ChatToolbarOverflowMenu({
+  hasUnread,
+  onToggleUnread,
+  onOpenDebug,
+}: {
+  hasUnread: boolean;
+  onToggleUnread: () => void;
+  onOpenDebug: () => void;
+}) {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          className="flex items-center justify-center size-5 rounded text-text-subtle hover:text-text-secondary hover:bg-surface-elevated transition-colors"
+          title="More actions"
+          aria-label="More actions"
+        >
+          <MoreHorizontal className="size-3.5" />
+        </button>
+      </DropdownMenuTrigger>
+      {/* Anchored above: this toolbar sits at the bottom of the chat pane. */}
+      <DropdownMenuContent align="end" side="top" className="min-w-[190px]">
+        <DropdownMenuItem onClick={onToggleUnread} className="max-md:py-3">
+          {hasUnread ? (
+            <>
+              <BellOff className="size-3.5 text-warning" /> Mark as read
+            </>
+          ) : (
+            <>
+              <Circle className="size-3.5 fill-current text-primary" /> Mark as unread
+            </>
+          )}
+        </DropdownMenuItem>
+        <DropdownMenuItem onClick={onOpenDebug} className="max-md:py-3">
+          <Bug className="size-3.5" /> Session debug info
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/src/web/components/chat/session-debug-dialog.tsx

@@ -308,15 +308,30 @@ function TurnUsageHistory({ sessionId, projectName }: { sessionId: string; proje
   );
 }
 
-/** Toolbar button opening the session's debug facts and transcript maintenance. */
-export function SessionDebugButton({ sessionId, projectName }: { sessionId: string; projectName: string }) {
-  const [open, setOpen] = useState(false);
+/**
+ * Session debug facts and transcript maintenance.
+ *
+ * Controlled by the caller so the trigger can live anywhere — including inside a
+ * dropdown menu, which unmounts its own items on select and would take an
+ * internally-owned dialog down with them.
+ */
+export function SessionDebugDialog({
+  sessionId,
+  projectName,
+  open,
+  onOpenChange,
+}: {
+  sessionId: string;
+  projectName: string;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
   const [info, setInfo] = useState<string | null>(null);
   const [copied, setCopied] = useState(false);
   const isMobile = useIsMobile();
 
-  const openPopup = () => {
-    setOpen(true);
+  useEffect(() => {
+    if (!open) return;
     setCopied(false);
     setInfo(null);
     api.get<DebugInfo>(
@@ -333,7 +348,7 @@ export function SessionDebugButton({ sessionId, projectName }: { sessionId: stri
         ...gatherRenderStats(),
       ].filter(Boolean).join("\n"));
     }).catch(() => setInfo("Failed to load debug info"));
-  };
+  }, [open, sessionId, projectName]);
 
   const copy = () => {
     if (!info) return;
@@ -365,27 +380,20 @@ export function SessionDebugButton({ sessionId, projectName }: { sessionId: stri
     </div>
   );
 
+  if (isMobile) {
+    return (
+      <BottomSheet open={open} onClose={() => onOpenChange(false)} className="popover-solid">
+        <div className="max-h-[85vh] overflow-y-auto px-4 pb-4 pt-1">{body}</div>
+      </BottomSheet>
+    );
+  }
+
   return (
-    <>
-      <button
-        onClick={openPopup}
-        className="p-1 rounded text-text-subtle hover:text-text-secondary hover:bg-surface-elevated transition-colors"
-        title="Session debug info"
-      >
-        <Bug className="size-3" />
-      </button>
-      {isMobile ? (
-        <BottomSheet open={open} onClose={() => setOpen(false)} className="popover-solid">
-          <div className="max-h-[85vh] overflow-y-auto px-4 pb-4 pt-1">{body}</div>
-        </BottomSheet>
-      ) : (
-        <Dialog open={open} onOpenChange={setOpen}>
-          <DialogContent className="sm:max-w-lg">
-            <DialogTitle className="sr-only">Session debug info</DialogTitle>
-            {body}
-          </DialogContent>
-        </Dialog>
-      )}
-    </>
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-lg">
+        <DialogTitle className="sr-only">Session debug info</DialogTitle>
+        {body}
+      </DialogContent>
+    </Dialog>
   );
 }

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

@@ -19,6 +19,7 @@ import { PortalContainerProvider } from "@/components/ui/portal-container-contex
 import { TITLEBAR_HEIGHT } from "./window-chrome-contract";
 import { useWindowBodyElement } from "./use-window-body-element";
 import { WindowPipPlaceholder } from "./window-pip-placeholder";
+import { isPipOnlyWindow } from "./window-pip-registry";
 import { WindowSkinChrome } from "./window-skin-chrome";
 import { windowZIndex, type Bounds, type Rect } from "./window-geometry";
 import { useWindowStore, type WindowRuntimeState } from "./window-store";
@@ -120,6 +121,8 @@ export function FloatingWindow({
     movable: !maximized,
   });
 
+  const hiddenHost = Boolean(pip) && isPipOnlyWindow(win.id);
+
   return (
     <div
       ref={rootRef}
@@ -135,6 +138,10 @@ export function FloatingWindow({
         focused ? "shadow-2xl shadow-black/40" : "shadow-lg shadow-black/20",
         // Transitions are for maximize/restore only; during a gesture they would lag the pointer.
         gesturing ? "transition-none" : "transition-[transform,width,height] duration-150 motion-reduce:transition-none",
+        // A window opened only to carry a tab into PiP is never shown: the user asked for a
+        // PiP, not a window. `hidden` and not an unmount — the body must stay connected, or
+        // the PiP host has nowhere to put the tab back.
+        hiddenHost && "hidden",
       )}
     >
       <WindowSkinChrome
@@ -158,7 +165,7 @@ export function FloatingWindow({
         onClose={close}
       />
 
-      {pip && <WindowPipPlaceholder pip={pip} minimized={minimized} />}
+      {pip && !hiddenHost && <WindowPipPlaceholder pip={pip} minimized={minimized} />}
 
       {!maximized && !minimized && (
         <WindowResizeHandles bind={(handle) => bindResize(handle) as Record<string, unknown>} />

package/src/web/components/floating-window/open-tab-in-pip.ts

@@ -0,0 +1,78 @@
+/**
+ * Send a tab straight into picture-in-picture, without the user ever seeing a window.
+ *
+ * A PiP window can only adopt an element that is already in the page, and it needs somewhere
+ * to put it back. The floating window is that element and that home — so one still opens
+ * here, it is simply never shown: the frame keeps a pip-only window off screen, and closing
+ * PiP closes it, which re-docks the tab into the panel it came from.
+ */
+
+import { usePanelStore } from "@/stores/panel-store";
+import { focusPipDocument } from "./pip/pip-focus-target";
+import { attachPipHost } from "./pip/pip-host";
+import { TITLEBAR_HEIGHT } from "./window-chrome-contract";
+import {
+  clearPipOnlyWindow,
+  markPipOnlyWindow,
+  setWindowPip,
+  whenWindowSlot,
+} from "./window-pip-registry";
+import { useWindowStore } from "./window-store";
+
+export type OpenTabInPipResult = "opened" | "window-cap" | "cancelled";
+
+/** Drop the host window; its own teardown hands the tab back to the panel it came from. */
+function discard(windowId: string): void {
+  clearPipOnlyWindow(windowId);
+  useWindowStore.getState().close(windowId);
+}
+
+/**
+ * Detach a tab into a hidden window and adopt it into a PiP window.
+ *
+ * Rejects when the browser refuses the request (no support, or the click's activation was
+ * already spent); the caller reports that. Call it from a click handler with nothing awaited
+ * before it — the one await inside is a React commit, which leaves the activation valid.
+ */
+export async function openTabInPip(tabId: string, panelId: string): Promise<OpenTabInPipResult> {
+  const windowId = usePanelStore.getState().popOutTab(tabId, panelId);
+  if (!windowId) return "window-cap";
+  markPipOnlyWindow(windowId);
+
+  // The window exists in the store, but its body is created by the frame's layout effect —
+  // one commit away.
+  const slot = await whenWindowSlot(windowId);
+  if (!slot) {
+    discard(windowId);
+    return "cancelled";
+  }
+
+  const rect = useWindowStore.getState().windows[windowId]?.rect;
+  let handle;
+  try {
+    handle = await 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(windowId, null);
+        // Closing PiP means "done with this tab out here", not "give me a window instead":
+        // the tab goes back to its strip.
+        discard(windowId);
+      },
+    });
+  } catch (err) {
+    discard(windowId);
+    throw err;
+  }
+
+  // Null means the window went away while the request was in flight; the host already
+  // restored what it had and called onDetach.
+  if (!handle) return "cancelled";
+
+  setWindowPip(windowId, handle);
+  // A DOM move carries no focus with it: without this the tab is visible in PiP but swallows
+  // nothing until the user clicks it.
+  focusPipDocument(handle.pipWindow.document);
+  return "opened";
+}

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

@@ -24,6 +24,52 @@ const listeners = new Set<() => void>();
 export function publishWindowSlot(windowId: string, el: HTMLElement | null): void {
   if (el) slots.set(windowId, el);
   else slots.delete(windowId);
+  for (const notify of listeners) notify();
+}
+
+/**
+ * Resolve once a window has published its body, or `null` if it never does.
+ *
+ * A window opened to host a picture-in-picture request exists in the store before React has
+ * mounted its frame, so the element the PiP host needs does not exist yet in the click
+ * handler that created it. Waiting is safe: transient activation survives a commit, it is
+ * consuming it twice that the browser refuses.
+ */
+export function whenWindowSlot(windowId: string, timeoutMs = 2000): Promise<HTMLElement | null> {
+  const existing = windowSlot(windowId);
+  if (existing) return Promise.resolve(existing);
+  return new Promise((resolve) => {
+    const settle = (el: HTMLElement | null) => {
+      listeners.delete(check);
+      clearTimeout(timer);
+      resolve(el);
+    };
+    const check = () => {
+      const el = windowSlot(windowId);
+      if (el) settle(el);
+    };
+    const timer = setTimeout(() => settle(null), timeoutMs);
+    listeners.add(check);
+  });
+}
+
+/**
+ * Windows that exist only to carry a tab into picture-in-picture: the frame keeps them off
+ * screen while PiP is up, and closing PiP closes the window, so the tab goes straight back
+ * to its tab strip instead of stranding an empty window the user never asked for.
+ */
+const pipOnly = new Set<string>();
+
+export function markPipOnlyWindow(windowId: string): void {
+  pipOnly.add(windowId);
+}
+
+export function isPipOnlyWindow(windowId: string): boolean {
+  return pipOnly.has(windowId);
+}
+
+export function clearPipOnlyWindow(windowId: string): void {
+  pipOnly.delete(windowId);
 }
 
 /** The body element of a mounted window, or null. */