Dock terminal below the right panel on desktop (#466)

BunsDev · web-flow · commit 9b882d6fc3cf · 2026-04-18T15:28:00.000-05:00
- Add a pure helper for counted desktop shells and terminal dock placement
- Portal the existing terminal drawer into a right-panel dock host with inline fallback
- Cover the layout rules with Vitest and document the desktop shell design
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
@@ -39,6 +39,7 @@ import {
   useRef,
   useState,
 } from "react";
+import { createPortal } from "react-dom";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useDebouncedValue } from "@tanstack/react-pacer";
 import { useNavigate } from "@tanstack/react-router";
@@ -236,6 +237,7 @@ import { hasCustomThreadTitle, normalizeThreadTitle } from "~/threadTitle";
 import { resolveLiveModelSelection } from "~/modelSelection";
 import { getProviderModelOptionsByProvider } from "~/providerModels";
 import { enhancePrompt, type PromptEnhancementId } from "../promptEnhancement";
+import { resolveTerminalDockPlacement } from "~/desktopShellLayout";
 
 function preloadThreadTerminalDrawer() {
   return import("./ThreadTerminalDrawer");
@@ -398,6 +400,8 @@ function normalizeVisibleInteractionMode(
 interface ChatViewProps {
   threadId: ThreadId;
   onMinimize?: (() => void) | undefined;
+  rightPanelOpen: boolean;
+  rightPanelTerminalDock: HTMLDivElement | null;
 }
 
 interface RunProjectScriptOptions {
@@ -408,7 +412,12 @@ interface RunProjectScriptOptions {
   rememberAsLastInvoked?: boolean;
 }
 
-export default function ChatView({ threadId, onMinimize }: ChatViewProps) {
+export default function ChatView({
+  threadId,
+  onMinimize,
+  rightPanelOpen,
+  rightPanelTerminalDock,
+}: ChatViewProps) {
   const clientMode = useClientMode();
   const transportState = useTransportState();
   const threads = useStore((store) => store.threads);
@@ -4842,6 +4851,45 @@ export default function ChatView({ threadId, onMinimize }: ChatViewProps) {
     return <ChatHomeEmptyState />;
   }
 
+  const terminalDockPlacement = resolveTerminalDockPlacement({
+    clientMode,
+    rightPanelOpen,
+    hasRightPanelTerminalDock: rightPanelTerminalDock !== null,
+  });
+  const terminalDrawer =
+    activeProject && shouldMountTerminalDrawer ? (
+      <div style={{ display: terminalState.terminalOpen ? undefined : "none" }}>
+        <Suspense
+          fallback={<TerminalDrawerLoadingFallback height={terminalState.terminalHeight} />}
+        >
+          <ThreadTerminalDrawer
+            key={activeThread.id}
+            threadId={activeThread.id}
+            cwd={gitCwd ?? activeProject.cwd}
+            runtimeEnv={threadTerminalRuntimeEnv}
+            height={terminalState.terminalHeight}
+            terminalIds={terminalState.terminalIds}
+            activeTerminalId={terminalState.activeTerminalId}
+            terminalGroups={terminalState.terminalGroups}
+            activeTerminalGroupId={terminalState.activeTerminalGroupId}
+            focusRequestId={terminalFocusRequestId}
+            onSplitTerminal={splitTerminal}
+            onNewTerminal={createNewTerminal}
+            splitShortcutLabel={splitTerminalShortcutLabel ?? undefined}
+            newShortcutLabel={newTerminalShortcutLabel ?? undefined}
+            closeShortcutLabel={closeTerminalShortcutLabel ?? undefined}
+            onActiveTerminalChange={activateTerminal}
+            onCloseTerminal={closeTerminal}
+            onCollapseTerminal={toggleTerminalVisibility}
+            onHeightChange={setTerminalHeight}
+            onAddTerminalContext={addTerminalContextToDraft}
+            onSendTerminalContext={sendSelectedTerminalContext}
+            onPreviewUrl={onPreviewUrl}
+          />
+        </Suspense>
+      </div>
+    ) : null;
+
   return (
     <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-x-hidden bg-background">
       {/* Top bar */}
@@ -5873,38 +5921,9 @@ export default function ChatView({ threadId, onMinimize }: ChatViewProps) {
       {/* Terminal drawer – once mounted, stay mounted to avoid the
           unmount/remount flicker when toggling visibility or switching threads.
           We hide it with display:none when collapsed so the DOM is retained. */}
-      {activeProject && shouldMountTerminalDrawer ? (
-        <div style={{ display: terminalState.terminalOpen ? undefined : "none" }}>
-          <Suspense
-            fallback={<TerminalDrawerLoadingFallback height={terminalState.terminalHeight} />}
-          >
-            <ThreadTerminalDrawer
-              key={activeThread.id}
-              threadId={activeThread.id}
-              cwd={gitCwd ?? activeProject.cwd}
-              runtimeEnv={threadTerminalRuntimeEnv}
-              height={terminalState.terminalHeight}
-              terminalIds={terminalState.terminalIds}
-              activeTerminalId={terminalState.activeTerminalId}
-              terminalGroups={terminalState.terminalGroups}
-              activeTerminalGroupId={terminalState.activeTerminalGroupId}
-              focusRequestId={terminalFocusRequestId}
-              onSplitTerminal={splitTerminal}
-              onNewTerminal={createNewTerminal}
-              splitShortcutLabel={splitTerminalShortcutLabel ?? undefined}
-              newShortcutLabel={newTerminalShortcutLabel ?? undefined}
-              closeShortcutLabel={closeTerminalShortcutLabel ?? undefined}
-              onActiveTerminalChange={activateTerminal}
-              onCloseTerminal={closeTerminal}
-              onCollapseTerminal={toggleTerminalVisibility}
-              onHeightChange={setTerminalHeight}
-              onAddTerminalContext={addTerminalContextToDraft}
-              onSendTerminalContext={sendSelectedTerminalContext}
-              onPreviewUrl={onPreviewUrl}
-            />
-          </Suspense>
-        </div>
-      ) : null}
+      {terminalDockPlacement === "right-panel" && rightPanelTerminalDock && terminalDrawer
+        ? createPortal(terminalDrawer, rightPanelTerminalDock)
+        : terminalDrawer}
 
       <Dialog
         open={pendingProjectScriptRun !== null}
diff --git a/apps/web/src/desktopShellLayout.test.ts b/apps/web/src/desktopShellLayout.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  countCountedDesktopShells,
+  getCountedDesktopShells,
+  resolveTerminalDockPlacement,
+} from "./desktopShellLayout";
+
+describe("desktopShellLayout", () => {
+  it("counts only the approved desktop shells and excludes terminal", () => {
+    expect(
+      getCountedDesktopShells({
+        sidebarOpen: true,
+        previewOpen: true,
+        rightPanelOpen: true,
+        planSidebarOpen: true,
+        terminalOpen: true,
+      }),
+    ).toEqual(["sidebar", "preview", "right-panel", "plan-sidebar"]);
+
+    expect(
+      countCountedDesktopShells({
+        sidebarOpen: true,
+        previewOpen: true,
+        rightPanelOpen: true,
+        planSidebarOpen: true,
+        terminalOpen: true,
+      }),
+    ).toBe(4);
+  });
+
+  it("returns zero when none of the counted desktop shells are open", () => {
+    expect(
+      countCountedDesktopShells({
+        sidebarOpen: false,
+        previewOpen: false,
+        rightPanelOpen: false,
+        planSidebarOpen: false,
+        terminalOpen: true,
+      }),
+    ).toBe(0);
+  });
+
+  it("docks the terminal under the right panel only when the desktop dock host exists", () => {
+    expect(
+      resolveTerminalDockPlacement({
+        clientMode: "desktop",
+        rightPanelOpen: true,
+        hasRightPanelTerminalDock: true,
+      }),
+    ).toBe("right-panel");
+  });
+
+  it("keeps the terminal inline when the right panel is closed", () => {
+    expect(
+      resolveTerminalDockPlacement({
+        clientMode: "desktop",
+        rightPanelOpen: false,
+        hasRightPanelTerminalDock: true,
+      }),
+    ).toBe("inline");
+  });
+
+  it("keeps the terminal inline for mobile even if a dock host exists", () => {
+    expect(
+      resolveTerminalDockPlacement({
+        clientMode: "mobile",
+        rightPanelOpen: true,
+        hasRightPanelTerminalDock: true,
+      }),
+    ).toBe("inline");
+  });
+});
diff --git a/apps/web/src/desktopShellLayout.ts b/apps/web/src/desktopShellLayout.ts
@@ -0,0 +1,38 @@
+export type CountedDesktopShell = "sidebar" | "preview" | "right-panel" | "plan-sidebar";
+
+interface DesktopShellState {
+  sidebarOpen: boolean;
+  previewOpen: boolean;
+  rightPanelOpen: boolean;
+  planSidebarOpen: boolean;
+  terminalOpen: boolean;
+}
+
+interface TerminalDockPlacementInput {
+  clientMode: "desktop" | "mobile";
+  rightPanelOpen: boolean;
+  hasRightPanelTerminalDock: boolean;
+}
+
+export type TerminalDockPlacement = "inline" | "right-panel";
+
+export function getCountedDesktopShells(input: DesktopShellState): CountedDesktopShell[] {
+  const shells: CountedDesktopShell[] = [];
+  if (input.sidebarOpen) shells.push("sidebar");
+  if (input.previewOpen) shells.push("preview");
+  if (input.rightPanelOpen) shells.push("right-panel");
+  if (input.planSidebarOpen) shells.push("plan-sidebar");
+  return shells;
+}
+
+export function countCountedDesktopShells(input: DesktopShellState): number {
+  return getCountedDesktopShells(input).length;
+}
+
+export function resolveTerminalDockPlacement(
+  input: TerminalDockPlacementInput,
+): TerminalDockPlacement {
+  return input.clientMode === "desktop" && input.rightPanelOpen && input.hasRightPanelTerminalDock
+    ? "right-panel"
+    : "inline";
+}
diff --git a/apps/web/src/routes/_chat.$threadId.tsx b/apps/web/src/routes/_chat.$threadId.tsx
@@ -226,6 +226,7 @@ function ChatThreadRouteView() {
 
   // ── Keep-alive flags so lazy content doesn't unmount on tab switch ─
   const [hasOpenedSimulation, setHasOpenedSimulation] = useState(simulationOpen);
+  const [rightPanelTerminalDock, setRightPanelTerminalDock] = useState<HTMLDivElement | null>(null);
 
   const closeCodeViewer = useCallback(() => {
     closeCodeViewerStore();
@@ -236,6 +237,9 @@ function ChatThreadRouteView() {
   const closeSimulation = useCallback(() => {
     closeSimulationStore();
   }, [closeSimulationStore]);
+  const setRightPanelTerminalDockRef = useCallback((node: HTMLDivElement | null) => {
+    setRightPanelTerminalDock(node);
+  }, []);
 
   useEffect(() => {
     const onWindowKeyDown = (event: KeyboardEvent) => {
@@ -330,7 +334,7 @@ function ChatThreadRouteView() {
 
   // ── Right panel content (shared between desktop sidebar & mobile sheet) ──
   const rightPanelContent = (
-    <div className="flex h-full flex-col bg-background">
+    <div className="flex min-h-0 flex-1 flex-col bg-background">
       <RightPanelHeader />
       <div className="relative flex-1 overflow-hidden">
         {rightPanelTab === "workspace" ? (
@@ -404,7 +408,13 @@ function ChatThreadRouteView() {
     return (
       <>
         <SidebarInset className="relative h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground">
-          <ChatView key={threadId} threadId={threadId} onMinimize={onMinimize} />
+          <ChatView
+            key={threadId}
+            threadId={threadId}
+            onMinimize={onMinimize}
+            rightPanelOpen={rightPanelOpen}
+            rightPanelTerminalDock={null}
+          />
         </SidebarInset>
         <RightPanelSheet open={rightPanelOpen} onClose={closeRightPanel}>
           {rightPanelContent}
@@ -417,7 +427,13 @@ function ChatThreadRouteView() {
   return (
     <>
       <SidebarInset className="relative h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground">
-        <ChatView key={threadId} threadId={threadId} onMinimize={onMinimize} />
+        <ChatView
+          key={threadId}
+          threadId={threadId}
+          onMinimize={onMinimize}
+          rightPanelOpen={rightPanelOpen}
+          rightPanelTerminalDock={rightPanelTerminalDock}
+        />
       </SidebarInset>
       <SidebarProvider
         defaultOpen={false}
@@ -438,7 +454,10 @@ function ChatThreadRouteView() {
             storageKey: RIGHT_PANEL_SIDEBAR_WIDTH_STORAGE_KEY,
           }}
         >
-          {rightPanelContent}
+          <div className="flex min-h-0 flex-1 flex-col">
+            {rightPanelContent}
+            <div ref={setRightPanelTerminalDockRef} data-right-panel-terminal-dock="" />
+          </div>
           <SidebarRail />
         </Sidebar>
       </SidebarProvider>
diff --git a/docs/superpowers/plans/2026-04-18-terminal-right-column.md b/docs/superpowers/plans/2026-04-18-terminal-right-column.md
diff --git a/docs/superpowers/specs/2026-04-18-terminal-right-column-design.md b/docs/superpowers/specs/2026-04-18-terminal-right-column-design.md
