feat: add quick terminal float window with double-ESC trigger

- Implement quick terminal float window feature triggered by double-ESC
- Auto-inherit cwd and connection context from focused block
- Adaptive height: starts at 10% window, grows with content up to 50%
- Position strategy: uses source block width or falls back to layout width
- Add quickTerminalAtom for state management (visible/blockId/opening/closing)
- ESC key handling: single ESC dismisses,透传 vdom mode escape to global
- OSC 7 enhancement: track current working directory to currentCwdAtom
- Add ephemeral 'quick-terminal' node type with dynamic height calculation

Closes wavetermdev#3194

Author: PureLo

frontend/app/store/global-atoms.ts

@@ -126,6 +126,12 @@ function initGlobalAtoms(initOpts: GlobalInitOptions) {
     });
     const reinitVersion = atom(0);
     const rateLimitInfoAtom = atom(null) as PrimitiveAtom<RateLimitInfo>;
+    const quickTerminalAtom = atom({
+        visible: false,
+        blockId: null as string | null,
+        opening: false,
+        closing: false,
+    }) as PrimitiveAtom<{ visible: boolean; blockId: string | null; opening: boolean; closing: boolean }>;
     atoms = {
         // initialized in wave.ts (will not be null inside of application)
         builderId: builderIdAtom,
@@ -149,6 +155,7 @@ function initGlobalAtoms(initOpts: GlobalInitOptions) {
         allConnStatus: allConnStatusAtom,
         reinitVersion,
         waveAIRateLimitInfoAtom: rateLimitInfoAtom,
+        quickTerminalAtom,
     } as GlobalAtomsType;
 }
 

frontend/app/store/global.ts

@@ -38,6 +38,7 @@ import * as WOS from "./wos";
 import { getFileSubject, waveEventSubscribeSingle } from "./wps";
 
 let globalPrimaryTabStartup: boolean = false;
+const QuickTerminalInitialState = { visible: false, blockId: null as string | null, opening: false, closing: false };
 
 function initGlobal(initOpts: GlobalInitOptions) {
     globalPrimaryTabStartup = initOpts.primaryTabStartup ?? false;
@@ -570,6 +571,32 @@ function getFocusedBlockId(): string {
     return focusedLayoutNode?.data?.blockId;
 }
 
+function getInheritedContextFromBlock(blockId: string | null): { cwd: string | null; connection: string | null } {
+    if (blockId == null) {
+        return { cwd: null, connection: null };
+    }
+
+    const blockAtom = WOS.getWaveObjectAtom<Block>(WOS.makeORef("block", blockId));
+    const blockData = globalStore.get(blockAtom);
+    const blockComponentModel = getBlockComponentModel(blockId);
+    const liveCwdAtom = (blockComponentModel?.viewModel as any)?.termRef?.current?.currentCwdAtom as
+        | PrimitiveAtom<string | null>
+        | undefined;
+    const liveCwd = liveCwdAtom ? globalStore.get(liveCwdAtom) : null;
+    const cwd = typeof liveCwd === "string" ? liveCwd : typeof blockData?.meta?.["cmd:cwd"] === "string" ? blockData.meta["cmd:cwd"] : null;
+
+    let connection = typeof blockData?.meta?.connection === "string" ? blockData.meta.connection : null;
+    const shellProcFullStatusAtom = (blockComponentModel?.viewModel as any)?.shellProcFullStatus as
+        | PrimitiveAtom<BlockControllerRuntimeStatus>
+        | undefined;
+    const runtimeStatus = shellProcFullStatusAtom ? globalStore.get(shellProcFullStatusAtom) : null;
+    if (typeof runtimeStatus?.shellprocconnname === "string") {
+        connection = runtimeStatus.shellprocconnname;
+    }
+
+    return { cwd, connection };
+}
+
 // pass null to refocus the currently focused block
 function refocusNode(blockId: string) {
     if (blockId == null) {
@@ -673,6 +700,60 @@ function recordTEvent(event: string, props?: TEventProps) {
     RpcApi.RecordTEventCommand(TabRpcClient, { event, props }, { noresponse: true });
 }
 
+async function toggleQuickTerminal(): Promise<boolean> {
+    const layoutModel = getLayoutModelForStaticTab();
+    const quickTermState = globalStore.get(atoms.quickTerminalAtom);
+
+    if (quickTermState.opening || quickTermState.closing) {
+        return true;
+    }
+
+    if (quickTermState.visible && quickTermState.blockId) {
+        // Dismiss: close the ephemeral node
+        // Set closing flag to prevent race condition with double-ESC
+        globalStore.set(atoms.quickTerminalAtom, { ...quickTermState, closing: true });
+        const quickTerminalNode = layoutModel.getNodeByBlockId(quickTermState.blockId);
+        if (quickTerminalNode != null) {
+            await layoutModel.closeNode(quickTerminalNode.id);
+        } else {
+            await ObjectService.DeleteBlock(quickTermState.blockId);
+        }
+        globalStore.set(atoms.quickTerminalAtom, QuickTerminalInitialState);
+        return true;
+    }
+
+    // Summon: inherit connection info and current working directory from the focused block when possible.
+    const focusedBlockId = getFocusedBlockId();
+    const { cwd, connection } = getInheritedContextFromBlock(focusedBlockId);
+
+    // Create ephemeral terminal block with custom quick terminal sizing
+    const blockDef: BlockDef = {
+        meta: {
+            view: "term",
+            controller: "shell",
+            ...(connection != null && { connection }),
+            ...(cwd != null && { "cmd:cwd": cwd }),
+        },
+    };
+
+    globalStore.set(atoms.quickTerminalAtom, { ...QuickTerminalInitialState, opening: true });
+
+    let blockId: string | null = null;
+    try {
+        const rtOpts: RuntimeOpts = { termsize: { rows: 25, cols: 80 } };
+        blockId = await ObjectService.CreateBlock(blockDef, rtOpts);
+        layoutModel.newQuickTerminalNode(blockId, focusedBlockId);
+        globalStore.set(atoms.quickTerminalAtom, { visible: true, blockId, opening: false, closing: false });
+        return true;
+    } catch (error) {
+        globalStore.set(atoms.quickTerminalAtom, QuickTerminalInitialState);
+        if (blockId != null) {
+            fireAndForget(() => ObjectService.DeleteBlock(blockId));
+        }
+        throw error;
+    }
+}
+
 export {
     atoms,
     createBlock,
@@ -683,6 +764,7 @@ export {
     getAllBlockComponentModels,
     getApi,
     getBlockComponentModel,
+    getInheritedContextFromBlock,
     getBlockMetaKeyAtom,
     getBlockTermDurableAtom,
     getTabMetaKeyAtom,
@@ -715,6 +797,7 @@ export {
     setNodeFocus,
     setPlatform,
     subscribeToConnEvents,
+    toggleQuickTerminal,
     unregisterBlockComponentModel,
     useBlockAtom,
     useBlockCache,

frontend/app/store/keymodel.ts

@@ -13,11 +13,13 @@ import {
     getApi,
     getBlockComponentModel,
     getFocusedBlockId,
+    getInheritedContextFromBlock,
     getSettingsKeyAtom,
     globalStore,
     recordTEvent,
     refocusNode,
     replaceBlock,
+    toggleQuickTerminal,
     WOS,
 } from "@/app/store/global";
 import { getActiveTabModel } from "@/app/store/tab-model";
@@ -42,6 +44,10 @@ let globalKeybindingsDisabled = false;
 let activeChord: string | null = null;
 let chordTimeout: NodeJS.Timeout = null;
 
+// Quick terminal double-ESC tracking
+let lastEscapeTime: number = 0;
+const QUICK_TERM_DOUBLE_ESC_TIMEOUT = 300; // milliseconds
+
 function resetChord() {
     activeChord = null;
     if (chordTimeout) {
@@ -361,15 +367,12 @@ function getDefaultNewBlockDef(): BlockDef {
     const layoutModel = getLayoutModelForStaticTab();
     const focusedNode = globalStore.get(layoutModel.focusedNode);
     if (focusedNode != null) {
-        const blockAtom = WOS.getWaveObjectAtom<Block>(WOS.makeORef("block", focusedNode.data?.blockId));
-        const blockData = globalStore.get(blockAtom);
-        if (blockData?.meta?.view == "term") {
-            if (blockData?.meta?.["cmd:cwd"] != null) {
-                termBlockDef.meta["cmd:cwd"] = blockData.meta["cmd:cwd"];
-            }
+        const { cwd, connection } = getInheritedContextFromBlock(focusedNode.data?.blockId);
+        if (cwd != null) {
+            termBlockDef.meta["cmd:cwd"] = cwd;
         }
-        if (blockData?.meta?.connection != null) {
-            termBlockDef.meta.connection = blockData.meta.connection;
+        if (connection != null) {
+            termBlockDef.meta.connection = connection;
         }
     }
     return termBlockDef;
@@ -726,6 +729,36 @@ function registerGlobalKeys() {
     }
     globalKeyMap.set("Cmd:f", activateSearch);
     globalKeyMap.set("Escape", () => {
+        const now = Date.now();
+        const quickTermState = globalStore.get(atoms.quickTerminalAtom);
+
+        // Handle quick terminal toggle on double-ESC
+        if (quickTermState.visible) {
+            // If quick terminal is open, single ESC dismisses it
+            // Skip if already closing to prevent double-close
+            if (!quickTermState.closing) {
+                fireAndForget(() => toggleQuickTerminal());
+            }
+            lastEscapeTime = 0; // Reset to prevent stale double-ESC detection
+            return true;
+        }
+
+        if (quickTermState.opening || quickTermState.closing) {
+            lastEscapeTime = 0;
+            return true;
+        }
+
+        // Check for double-ESC to summon quick terminal
+        if (now - lastEscapeTime < QUICK_TERM_DOUBLE_ESC_TIMEOUT) {
+            // Double ESC detected - summon quick terminal
+            fireAndForget(() => toggleQuickTerminal());
+            lastEscapeTime = 0; // Reset after handling
+            return true;
+        }
+
+        lastEscapeTime = now;
+
+        // Existing ESC behavior (modals, search)
         if (modalsModel.hasOpenModals()) {
             modalsModel.popModal();
             return true;

frontend/app/view/term/osc-handlers.ts

@@ -218,7 +218,7 @@ export function handleOsc52Command(data: string, blockId: string, loaded: boolea
 
 // for xterm handlers, we return true always because we "own" OSC 7.
 // even if it is invalid we dont want to propagate to other handlers
-export function handleOsc7Command(data: string, blockId: string, loaded: boolean): boolean {
+export function handleOsc7Command(data: string, blockId: string, loaded: boolean, termWrap: TermWrap): boolean {
     if (!loaded) {
         return true;
     }
@@ -261,6 +261,8 @@ export function handleOsc7Command(data: string, blockId: string, loaded: boolean
         return true;
     }
 
+    globalStore.set(termWrap.currentCwdAtom, pathPart);
+
     setTimeout(() => {
         fireAndForget(async () => {
             await RpcApi.SetMetaCommand(TabRpcClient, {

frontend/app/view/term/term-model.ts

@@ -671,6 +671,10 @@ export class TermViewModel implements ViewModel {
         }
         const blockData = globalStore.get(this.blockAtom);
         if (blockData.meta?.["term:mode"] == "vdom") {
+            // Don't consume Escape key - let it propagate to global handler for quick terminal close
+            if (keyutil.checkKeyPressed(waveEvent, "Escape")) {
+                return false;
+            }
             const vdomModel = this.getVDomModel();
             return vdomModel?.keyDownHandler(waveEvent);
         }

frontend/app/view/term/termwrap.ts

@@ -7,6 +7,7 @@ import { getFileSubject } from "@/app/store/wps";
 import { RpcApi } from "@/app/store/wshclientapi";
 import { TabRpcClient } from "@/app/store/wshrpcutil";
 import {
+    atoms,
     fetchWaveFile,
     getApi,
     getOverrideConfigAtom,
@@ -16,6 +17,7 @@ import {
     openLink,
     WOS,
 } from "@/store/global";
+import { getLayoutModelForStaticTab } from "@/layout/index";
 import * as services from "@/store/services";
 import { PLATFORM, PlatformMacOS } from "@/util/platformutil";
 import { base64ToArray, fireAndForget } from "@/util/util";
@@ -99,8 +101,10 @@ export class TermWrap {
     lastUpdated: number;
     promptMarkers: TermTypes.IMarker[] = [];
     shellIntegrationStatusAtom: jotai.PrimitiveAtom<ShellIntegrationStatus | null>;
+    currentCwdAtom: jotai.PrimitiveAtom<string | null>;
     lastCommandAtom: jotai.PrimitiveAtom<string | null>;
     claudeCodeActiveAtom: jotai.PrimitiveAtom<boolean>;
+    contentHeightRows: number;
     nodeModel: BlockNodeModel; // this can be null
     hoveredLinkUri: string | null = null;
     onLinkHover?: (uri: string | null, mouseX: number, mouseY: number) => void;
@@ -120,6 +124,7 @@ export class TermWrap {
     lastMode2026ResetTs: number = 0;
     inSyncTransaction: boolean = false;
     inRepaintTransaction: boolean = false;
+    syncQuickTerminalHeight_debounced: () => void;
 
     constructor(
         tabId: string,
@@ -139,8 +144,10 @@ export class TermWrap {
         this.lastUpdated = Date.now();
         this.promptMarkers = [];
         this.shellIntegrationStatusAtom = jotai.atom(null) as jotai.PrimitiveAtom<ShellIntegrationStatus | null>;
+        this.currentCwdAtom = jotai.atom(null) as jotai.PrimitiveAtom<string | null>;
         this.lastCommandAtom = jotai.atom(null) as jotai.PrimitiveAtom<string | null>;
         this.claudeCodeActiveAtom = jotai.atom(false);
+        this.contentHeightRows = 0;
         this.webglEnabledAtom = jotai.atom(false) as jotai.PrimitiveAtom<boolean>;
         this.terminal = new Terminal(options);
         this.fitAddon = new FitAddon();
@@ -182,7 +189,7 @@ export class TermWrap {
         // Register OSC handlers
         this.terminal.parser.registerOscHandler(7, (data: string) => {
             try {
-                return handleOsc7Command(data, this.blockId, this.loaded);
+                return handleOsc7Command(data, this.blockId, this.loaded, this);
             } catch (e) {
                 console.error("[termwrap] osc 7 handler error", this.blockId, e);
                 return false;
@@ -280,6 +287,7 @@ export class TermWrap {
         this.mainFileSubject = null;
         this.heldData = [];
         this.handleResize_debounced = debounce(50, this.handleResize.bind(this));
+        this.syncQuickTerminalHeight_debounced = debounce(16, this.syncQuickTerminalHeight.bind(this));
         this.terminal.open(this.connectElem);
 
         const dragoverHandler = (e: DragEvent) => {
@@ -475,6 +483,7 @@ export class TermWrap {
         if (msg.fileop == "truncate") {
             this.terminal.clear();
             this.heldData = [];
+            this.syncQuickTerminalHeight_debounced();
         } else if (msg.fileop == "append") {
             const decodedData = base64ToArray(msg.data64);
             if (this.loaded) {
@@ -508,6 +517,7 @@ export class TermWrap {
                 this.dataBytesProcessed += data.length;
             }
             this.lastUpdated = Date.now();
+            this.syncQuickTerminalHeight_debounced();
             resolve();
         });
         return prtn;
@@ -575,13 +585,31 @@ export class TermWrap {
             );
             RpcApi.ControllerInputCommand(TabRpcClient, { blockid: this.blockId, termsize: termSize });
         }
+        this.syncQuickTerminalHeight_debounced();
         dlog("resize", `${this.terminal.rows}x${this.terminal.cols}`, `${oldRows}x${oldCols}`, this.hasResized);
         if (!this.hasResized) {
             this.hasResized = true;
             this.resyncController("initial resize");
         }
     }
 
+    private getContentHeightRows(): number {
+        return Math.max(1, this.terminal.buffer.active.baseY + this.terminal.buffer.active.cursorY + 1);
+    }
+
+    private syncQuickTerminalHeight() {
+        const nextRows = this.getContentHeightRows();
+        this.contentHeightRows = nextRows;
+
+        const quickTermState = globalStore.get(atoms.quickTerminalAtom);
+        if (quickTermState.blockId !== this.blockId) {
+            return;
+        }
+
+        const layoutModel = getLayoutModelForStaticTab();
+        layoutModel?.updateTree(false);
+    }
+
     processAndCacheData() {
         if (this.dataBytesProcessed < MinDataProcessedForCache) {
             return;