Add floating terminal layout support

adamt94 · adamt94 · commit 2343d3d3405e · 2026-04-25T15:06:39.000+01:00
- add terminal layout setting and contract schema
- render the thread terminal as a floating dialog when enabled
- switch package scripts to run under Bun
diff --git a/apps/desktop/src/clientPersistence.test.ts b/apps/desktop/src/clientPersistence.test.ts
@@ -61,6 +61,7 @@ const clientSettings: ClientSettings = {
   sidebarProjectSortOrder: "manual",
   sidebarThreadSortOrder: "created_at",
   timestampFormat: "24-hour",
+  terminalLayout: "floating",
 };
 
 const savedRegistryRecord: PersistedSavedEnvironmentRecord = {
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
@@ -11,6 +11,7 @@ import {
   type ServerProvider,
   type ResolvedKeybindingsConfig,
   type ScopedThreadRef,
+  type TerminalLayout,
   type ThreadId,
   type TurnId,
   type KeybindingCommand,
@@ -33,7 +34,7 @@ import {
 import { projectScriptCwd, projectScriptRuntimeEnv } from "@t3tools/shared/projectScripts";
 import { truncate } from "@t3tools/shared/String";
 import { Debouncer } from "@tanstack/react-pacer";
-import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { memo, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
 import { useNavigate, useSearch } from "@tanstack/react-router";
 import { useShallow } from "zustand/react/shallow";
 import { useGitStatus } from "~/lib/gitStatusState";
@@ -102,7 +103,7 @@ import { BranchToolbar } from "./BranchToolbar";
 import { resolveShortcutCommand, shortcutLabelForCommand } from "../keybindings";
 import PlanSidebar from "./PlanSidebar";
 import ThreadTerminalDrawer from "./ThreadTerminalDrawer";
-import { ChevronDownIcon } from "lucide-react";
+import { ChevronDownIcon, XIcon } from "lucide-react";
 import { cn, randomUUID } from "~/lib/utils";
 import { stackedThreadToast, toastManager } from "./ui/toast";
 import { decodeProjectScriptKeybindingRule } from "~/lib/projectScriptKeybindings";
@@ -418,6 +419,7 @@ interface PersistentThreadTerminalDrawerProps {
   newShortcutLabel: string | undefined;
   closeShortcutLabel: string | undefined;
   keybindings: ResolvedKeybindingsConfig;
+  terminalLayout: TerminalLayout;
   onAddTerminalContext: (selection: TerminalContextSelection) => void;
 }
 
@@ -431,6 +433,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
   newShortcutLabel,
   closeShortcutLabel,
   keybindings,
+  terminalLayout,
   onAddTerminalContext,
 }: PersistentThreadTerminalDrawerProps) {
   const serverThread = useStore(useMemo(() => createThreadSelectorByRef(threadRef), [threadRef]));
@@ -449,7 +452,9 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
   const storeNewTerminal = useTerminalStateStore((state) => state.newTerminal);
   const storeSetActiveTerminal = useTerminalStateStore((state) => state.setActiveTerminal);
   const storeCloseTerminal = useTerminalStateStore((state) => state.closeTerminal);
+  const storeSetTerminalOpen = useTerminalStateStore((state) => state.setTerminalOpen);
   const [localFocusRequestId, setLocalFocusRequestId] = useState(0);
+  const floatingTerminalTitleId = useId();
   const worktreePath = serverThread?.worktreePath ?? draftThread?.worktreePath ?? null;
   const effectiveWorktreePath = useMemo(() => {
     if (launchContext !== null) {
@@ -549,39 +554,81 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
     },
     [onAddTerminalContext, visible],
   );
+  const closeTerminalWindow = useCallback(() => {
+    storeSetTerminalOpen(threadRef, false);
+  }, [storeSetTerminalOpen, threadRef]);
 
   if (!project || !terminalState.terminalOpen || !cwd) {
     return null;
   }
 
-  return (
-    <div className={visible ? undefined : "hidden"}>
-      <ThreadTerminalDrawer
-        threadRef={threadRef}
-        threadId={threadId}
-        cwd={cwd}
-        worktreePath={effectiveWorktreePath}
-        runtimeEnv={runtimeEnv}
-        visible={visible}
-        height={terminalState.terminalHeight}
-        terminalIds={terminalState.terminalIds}
-        activeTerminalId={terminalState.activeTerminalId}
-        terminalGroups={terminalState.terminalGroups}
-        activeTerminalGroupId={terminalState.activeTerminalGroupId}
-        focusRequestId={focusRequestId + localFocusRequestId + (visible ? 1 : 0)}
-        onSplitTerminal={splitTerminal}
-        onNewTerminal={createNewTerminal}
-        splitShortcutLabel={visible ? splitShortcutLabel : undefined}
-        newShortcutLabel={visible ? newShortcutLabel : undefined}
-        closeShortcutLabel={visible ? closeShortcutLabel : undefined}
-        keybindings={keybindings}
-        onActiveTerminalChange={activateTerminal}
-        onCloseTerminal={closeTerminal}
-        onHeightChange={setTerminalHeight}
-        onAddTerminalContext={handleAddTerminalContext}
-      />
-    </div>
-  );
+  const drawer = (
+    <ThreadTerminalDrawer
+      threadRef={threadRef}
+      threadId={threadId}
+      cwd={cwd}
+      worktreePath={effectiveWorktreePath}
+      runtimeEnv={runtimeEnv}
+      visible={visible}
+      height={terminalState.terminalHeight}
+      terminalIds={terminalState.terminalIds}
+      activeTerminalId={terminalState.activeTerminalId}
+      terminalGroups={terminalState.terminalGroups}
+      activeTerminalGroupId={terminalState.activeTerminalGroupId}
+      focusRequestId={focusRequestId + localFocusRequestId + (visible ? 1 : 0)}
+      onSplitTerminal={splitTerminal}
+      onNewTerminal={createNewTerminal}
+      splitShortcutLabel={visible ? splitShortcutLabel : undefined}
+      newShortcutLabel={visible ? newShortcutLabel : undefined}
+      closeShortcutLabel={visible ? closeShortcutLabel : undefined}
+      keybindings={keybindings}
+      onActiveTerminalChange={activateTerminal}
+      onCloseTerminal={closeTerminal}
+      onHeightChange={setTerminalHeight}
+      onAddTerminalContext={handleAddTerminalContext}
+      layout={terminalLayout}
+    />
+  );
+
+  if (terminalLayout === "floating") {
+    return (
+      <div
+        className={cn(
+          "fixed inset-0 z-50 bg-black/32 backdrop-blur-sm",
+          visible ? "grid grid-rows-[1fr_auto_3fr] justify-items-center p-4" : "hidden",
+        )}
+        onMouseDown={(event) => {
+          if (event.target === event.currentTarget) {
+            closeTerminalWindow();
+          }
+        }}
+      >
+        <div
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby={floatingTerminalTitleId}
+          className="w-[min(96vw,72rem)] max-w-[min(96vw,72rem)] overflow-hidden rounded-lg border bg-background p-0 shadow-xl"
+        >
+          <div className="flex h-8 shrink-0 items-center justify-between border-b border-border/80 px-2">
+            <h2 id={floatingTerminalTitleId} className="text-xs font-medium leading-none">
+              Terminal
+            </h2>
+            <button
+              type="button"
+              className="inline-flex size-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+              onClick={closeTerminalWindow}
+              aria-label="Close terminal window"
+            >
+              <XIcon className="size-3.5" />
+            </button>
+          </div>
+          {drawer}
+        </div>
+      </div>
+    );
+  }
+
+  return <div className={visible ? undefined : "hidden"}>{drawer}</div>;
 });
 
 export default function ChatView(props: ChatViewProps) {
@@ -3263,6 +3310,7 @@ export default function ChatView(props: ChatViewProps) {
           availableEditors={availableEditors}
           terminalAvailable={activeProject !== undefined}
           terminalOpen={terminalState.terminalOpen}
+          terminalLayout={settings.terminalLayout}
           terminalToggleShortcutLabel={terminalToggleShortcutLabel}
           diffToggleShortcutLabel={diffPanelShortcutLabel}
           gitCwd={gitCwd}
@@ -3477,6 +3525,7 @@ export default function ChatView(props: ChatViewProps) {
           newShortcutLabel={newTerminalShortcutLabel ?? undefined}
           closeShortcutLabel={closeTerminalShortcutLabel ?? undefined}
           keybindings={keybindings}
+          terminalLayout={settings.terminalLayout}
           onAddTerminalContext={addTerminalContextToDraft}
         />
       ))}
diff --git a/apps/web/src/components/ThreadTerminalDrawer.tsx b/apps/web/src/components/ThreadTerminalDrawer.tsx
@@ -3,6 +3,7 @@ import { Plus, SquareSplitHorizontal, TerminalSquare, Trash2, XIcon } from "luci
 import {
   type ResolvedKeybindingsConfig,
   type ScopedThreadRef,
+  type TerminalLayout,
   type TerminalEvent,
   type TerminalSessionSnapshot,
   type ThreadId,
@@ -20,6 +21,7 @@ import {
 } from "react";
 import { Popover, PopoverPopup, PopoverTrigger } from "~/components/ui/popover";
 import { type TerminalContextSelection } from "~/lib/terminalContext";
+import { cn } from "~/lib/utils";
 import { openInPreferredEditor } from "../editorPreferences";
 import {
   collectWrappedTerminalLinkLine,
@@ -821,6 +823,7 @@ interface ThreadTerminalDrawerProps {
   onHeightChange: (height: number) => void;
   onAddTerminalContext: (selection: TerminalContextSelection) => void;
   keybindings: ResolvedKeybindingsConfig;
+  layout?: TerminalLayout;
 }
 
 interface TerminalActionButtonProps {
@@ -875,6 +878,7 @@ export default function ThreadTerminalDrawer({
   onHeightChange,
   onAddTerminalContext,
   keybindings,
+  layout = "docked",
 }: ThreadTerminalDrawerProps) {
   const [drawerHeight, setDrawerHeight] = useState(() => clampDrawerHeight(height));
   const [resizeEpoch, setResizeEpoch] = useState(0);
@@ -1111,7 +1115,10 @@ export default function ThreadTerminalDrawer({
 
   return (
     <aside
-      className="thread-terminal-drawer relative flex min-w-0 shrink-0 flex-col overflow-hidden border-t border-border/80 bg-background"
+      className={cn(
+        "thread-terminal-drawer relative flex min-w-0 shrink-0 flex-col overflow-hidden bg-background",
+        layout === "docked" ? "border-t border-border/80" : "border-0",
+      )}
       style={{ height: `${drawerHeight}px` }}
     >
       <div
diff --git a/apps/web/src/components/chat/ChatHeader.tsx b/apps/web/src/components/chat/ChatHeader.tsx
@@ -3,6 +3,7 @@ import {
   type EditorId,
   type ProjectScript,
   type ResolvedKeybindingsConfig,
+  type TerminalLayout,
   type ThreadId,
 } from "@t3tools/contracts";
 import { scopeThreadRef } from "@t3tools/client-runtime";
@@ -31,6 +32,7 @@ interface ChatHeaderProps {
   availableEditors: ReadonlyArray<EditorId>;
   terminalAvailable: boolean;
   terminalOpen: boolean;
+  terminalLayout: TerminalLayout;
   terminalToggleShortcutLabel: string | null;
   diffToggleShortcutLabel: string | null;
   gitCwd: string | null;
@@ -57,6 +59,7 @@ export const ChatHeader = memo(function ChatHeader({
   availableEditors,
   terminalAvailable,
   terminalOpen,
+  terminalLayout,
   terminalToggleShortcutLabel,
   diffToggleShortcutLabel,
   gitCwd,
@@ -68,6 +71,9 @@ export const ChatHeader = memo(function ChatHeader({
   onToggleTerminal,
   onToggleDiff,
 }: ChatHeaderProps) {
+  const terminalSurfaceLabel =
+    terminalLayout === "floating" ? "terminal window" : "terminal drawer";
+
   return (
     <div className="@container/header-actions flex min-w-0 flex-1 items-center gap-2">
       <div className="flex min-w-0 flex-1 items-center gap-2 overflow-hidden sm:gap-3">
@@ -122,7 +128,7 @@ export const ChatHeader = memo(function ChatHeader({
                 className="shrink-0"
                 pressed={terminalOpen}
                 onPressedChange={onToggleTerminal}
-                aria-label="Toggle terminal drawer"
+                aria-label={`Toggle ${terminalSurfaceLabel}`}
                 variant="outline"
                 size="xs"
                 disabled={!terminalAvailable}
@@ -135,8 +141,8 @@ export const ChatHeader = memo(function ChatHeader({
             {!terminalAvailable
               ? "Terminal is unavailable until this thread has an active project."
               : terminalToggleShortcutLabel
-                ? `Toggle terminal drawer (${terminalToggleShortcutLabel})`
-                : "Toggle terminal drawer"}
+                ? `Toggle ${terminalSurfaceLabel} (${terminalToggleShortcutLabel})`
+                : `Toggle ${terminalSurfaceLabel}`}
           </TooltipPopup>
         </Tooltip>
         <Tooltip>
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -100,6 +100,11 @@ const TIMESTAMP_FORMAT_LABELS = {
   "24-hour": "24-hour",
 } as const;
 
+const TERMINAL_LAYOUT_LABELS = {
+  docked: "Docked",
+  floating: "Floating",
+} as const;
+
 type InstallProviderSettings = {
   provider: ProviderKind;
   title: string;
@@ -475,6 +480,9 @@ export function useSettingsRestore(onRestored?: () => void) {
       ...(settings.autoOpenPlanSidebar !== DEFAULT_UNIFIED_SETTINGS.autoOpenPlanSidebar
         ? ["Task sidebar"]
         : []),
+      ...(settings.terminalLayout !== DEFAULT_UNIFIED_SETTINGS.terminalLayout
+        ? ["Terminal layout"]
+        : []),
       ...(settings.enableAssistantStreaming !== DEFAULT_UNIFIED_SETTINGS.enableAssistantStreaming
         ? ["Assistant output"]
         : []),
@@ -503,6 +511,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       settings.defaultThreadEnvMode,
       settings.diffWordWrap,
       settings.enableAssistantStreaming,
+      settings.terminalLayout,
       settings.timestampFormat,
       theme,
     ],
@@ -975,6 +984,45 @@ export function GeneralSettingsPanel() {
           }
         />
 
+        <SettingsRow
+          title="Terminal layout"
+          description="Choose whether the terminal opens docked under chat or in a floating window."
+          resetAction={
+            settings.terminalLayout !== DEFAULT_UNIFIED_SETTINGS.terminalLayout ? (
+              <SettingResetButton
+                label="terminal layout"
+                onClick={() =>
+                  updateSettings({
+                    terminalLayout: DEFAULT_UNIFIED_SETTINGS.terminalLayout,
+                  })
+                }
+              />
+            ) : null
+          }
+          control={
+            <Select
+              value={settings.terminalLayout}
+              onValueChange={(value) => {
+                if (value === "docked" || value === "floating") {
+                  updateSettings({ terminalLayout: value });
+                }
+              }}
+            >
+              <SelectTrigger className="w-full sm:w-40" aria-label="Terminal layout">
+                <SelectValue>{TERMINAL_LAYOUT_LABELS[settings.terminalLayout]}</SelectValue>
+              </SelectTrigger>
+              <SelectPopup align="end" alignItemWithTrigger={false}>
+                <SelectItem hideIndicator value="docked">
+                  {TERMINAL_LAYOUT_LABELS.docked}
+                </SelectItem>
+                <SelectItem hideIndicator value="floating">
+                  {TERMINAL_LAYOUT_LABELS.floating}
+                </SelectItem>
+              </SelectPopup>
+            </Select>
+          }
+        />
+
         <SettingsRow
           title="New threads"
           description="Pick the default workspace mode for newly created draft threads."
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
@@ -541,6 +541,7 @@ describe("wsApi", () => {
       sidebarProjectSortOrder: "manual" as const,
       sidebarThreadSortOrder: "created_at" as const,
       timestampFormat: "24-hour" as const,
+      terminalLayout: "floating" as const,
     };
     const getClientSettings = vi.fn().mockResolvedValue({
       ...clientSettings,
@@ -600,6 +601,7 @@ describe("wsApi", () => {
       sidebarProjectSortOrder: "manual" as const,
       sidebarThreadSortOrder: "created_at" as const,
       timestampFormat: "24-hour" as const,
+      terminalLayout: "floating" as const,
     };
 
     await api.persistence.setClientSettings(clientSettings);
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
