From 0fb419da374dc30b25bb362b702c9e655d8e9992 Mon Sep 17 00:00:00 2001
From: lim <huahua1319873800@outlook.com>
Date: Tue, 11 Nov 2025 15:46:13 +0000
Subject: [PATCH 1/8] add xterm

---
 components/terminal/terminal-display.tsx |  98 ++++--
 components/terminal/xterm-terminal.tsx   | 394 +++++++++++++++++++++++
 hooks/use-terminal.ts                    | 142 ++++++++
 lib/k8s/sandbox-manager.ts               |  18 +-
 package.json                             |   5 +
 pnpm-lock.yaml                           |  56 ++++
 6 files changed, 688 insertions(+), 25 deletions(-)
 create mode 100644 components/terminal/xterm-terminal.tsx
 create mode 100644 hooks/use-terminal.ts

diff --git a/components/terminal/terminal-display.tsx b/components/terminal/terminal-display.tsx
index fa2656e..26e8ae9 100644
--- a/components/terminal/terminal-display.tsx
+++ b/components/terminal/terminal-display.tsx
@@ -1,8 +1,8 @@
 /**
  * TerminalDisplay Component
  *
- * Pure display component for terminal iframe
- * VSCode Dark Modern theme style
+ * Display component for xterm.js terminal (no iframe)
+ * Direct WebSocket connection to ttyd backend
  */
 
 'use client';
@@ -19,8 +19,10 @@ import {
 } from '@/lib/util/status-colors';
 import { cn } from '@/lib/utils';
 
+import { XtermTerminal } from './xterm-terminal';
+
 export interface TerminalDisplayProps {
-  /** ttyd URL */
+  /** ttyd URL with authentication token */
   ttydUrl?: string | null;
   /** Sandbox status */
   status: string;
@@ -29,40 +31,88 @@ export interface TerminalDisplayProps {
 }
 
 /**
- * Display terminal iframe or status message
- * Each terminal tab gets its own iframe with unique key to ensure separate WebSocket connections
+ * Display xterm.js terminal with direct WebSocket connection
+ * Each terminal tab gets independent WebSocket connection
  */
 export function TerminalDisplay({ ttydUrl, status, tabId }: TerminalDisplayProps) {
-  const [iframeLoaded, setIframeLoaded] = useState(false);
+  const [terminalReady, setTerminalReady] = useState(false);
+  const [connectionStatus, setConnectionStatus] = useState<'connecting' | 'connected' | 'error'>(
+    'connecting'
+  );
 
-  // Only show terminal iframe if status is RUNNING and URL is available
+  // Only show terminal if status is RUNNING and ttyd URL is available
   if (status === 'RUNNING' && ttydUrl) {
     return (
       <div className="h-full w-full bg-[#1e1e1e] flex flex-col relative">
-        {/* Loading overlay */}
-        {!iframeLoaded && (
+        {/* Loading overlay - show until terminal is ready and connected */}
+        {(connectionStatus === 'connecting' || !terminalReady) && (
           <div className="absolute inset-0 bg-[#1e1e1e] flex items-center justify-center z-10">
             <div className="flex items-center gap-3">
               <Spinner className="h-5 w-5 text-[#3794ff]" />
-              <span className="text-sm text-[#cccccc]">Connecting to terminal...</span>
+              <span className="text-sm text-[#cccccc]">
+                {!terminalReady ? 'Loading terminal...' : 'Connecting to terminal...'}
+              </span>
             </div>
           </div>
         )}
 
-        {/* Terminal iframe - unique key per tab ensures separate WebSocket connection */}
-        <iframe
-          key={`terminal-${tabId}`}
-          src={ttydUrl}
-          className="flex-1 w-full bg-[#1e1e1e]"
-          style={{
-            border: 'none',
-            minHeight: '100%',
-            height: '100%',
-          }}
-          title={`Terminal ${tabId}`}
-          onLoad={() => setIframeLoaded(true)}
-          allow="clipboard-read; clipboard-write"
-        />
+        {/* XTerm Terminal Component */}
+        <div className="flex-1 w-full">
+          <XtermTerminal
+            key={`xterm-${tabId}`}
+            wsUrl={ttydUrl}
+            theme={{
+              foreground: '#d2d2d2',
+              background: '#1e1e1e',
+              cursor: '#adadad',
+              black: '#000000',
+              red: '#d81e00',
+              green: '#5ea702',
+              yellow: '#cfae00',
+              blue: '#427ab3',
+              magenta: '#89658e',
+              cyan: '#00a7aa',
+              white: '#dbded8',
+              brightBlack: '#686a66',
+              brightRed: '#f54235',
+              brightGreen: '#99e343',
+              brightYellow: '#fdeb61',
+              brightBlue: '#84b0d8',
+              brightMagenta: '#bc94b7',
+              brightCyan: '#37e6e8',
+              brightWhite: '#f1f1f0',
+            }}
+            fontSize={14}
+            fontFamily="Consolas, Liberation Mono, Menlo, Courier, monospace"
+            rendererType="webgl"
+            onReady={() => {
+              console.log('[TerminalDisplay] Terminal ready');
+              setTerminalReady(true);
+            }}
+            onConnected={() => {
+              console.log('[TerminalDisplay] Terminal WebSocket connected');
+              setConnectionStatus('connected');
+            }}
+            onDisconnected={() => {
+              console.log('[TerminalDisplay] Terminal WebSocket disconnected');
+              setConnectionStatus('connecting');
+            }}
+          />
+        </div>
+
+        {/* Connection status indicator (optional, can be removed) */}
+        {connectionStatus === 'connecting' && terminalReady && (
+          <div className="absolute top-2 right-2 bg-yellow-500/10 border border-yellow-500/30 rounded px-2 py-1 flex items-center gap-2">
+            <Spinner className="h-3 w-3 text-yellow-500" />
+            <span className="text-xs text-yellow-500">Reconnecting...</span>
+          </div>
+        )}
+        {connectionStatus === 'error' && terminalReady && (
+          <div className="absolute top-2 right-2 bg-red-500/10 border border-red-500/30 rounded px-2 py-1 flex items-center gap-2">
+            <AlertCircle className="h-3 w-3 text-red-500" />
+            <span className="text-xs text-red-500">Connection error</span>
+          </div>
+        )}
       </div>
     );
   }
diff --git a/components/terminal/xterm-terminal.tsx b/components/terminal/xterm-terminal.tsx
new file mode 100644
index 0000000..af0b784
--- /dev/null
+++ b/components/terminal/xterm-terminal.tsx
@@ -0,0 +1,394 @@
+/**
+ * XtermTerminal Component
+ *
+ * Core xterm.js terminal component with WebSocket connection to ttyd backend
+ * Based on ttyd's frontend implementation
+ */
+
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { CanvasAddon } from '@xterm/addon-canvas';
+import { FitAddon } from '@xterm/addon-fit';
+import { WebLinksAddon } from '@xterm/addon-web-links';
+import { WebglAddon } from '@xterm/addon-webgl';
+import type { ITerminalOptions, Terminal as ITerminal } from '@xterm/xterm';
+import { Terminal } from '@xterm/xterm';
+
+// Import xterm CSS at component level
+import '@xterm/xterm/css/xterm.css';
+
+// Command types matching ttyd protocol
+enum Command {
+  // server side
+  OUTPUT = '0',
+  SET_WINDOW_TITLE = '1',
+  SET_PREFERENCES = '2',
+}
+
+// Client command types
+enum ClientCommand {
+  INPUT = '0',
+  RESIZE_TERMINAL = '1',
+  PAUSE = '2',
+  RESUME = '3',
+}
+
+export interface XtermTerminalProps {
+  /** WebSocket URL for ttyd connection */
+  wsUrl: string;
+  /** Terminal theme */
+  theme?: {
+    foreground?: string;
+    background?: string;
+    cursor?: string;
+    black?: string;
+    red?: string;
+    green?: string;
+    yellow?: string;
+    blue?: string;
+    magenta?: string;
+    cyan?: string;
+    white?: string;
+    brightBlack?: string;
+    brightRed?: string;
+    brightGreen?: string;
+    brightYellow?: string;
+    brightBlue?: string;
+    brightMagenta?: string;
+    brightCyan?: string;
+    brightWhite?: string;
+  };
+  /** Font size */
+  fontSize?: number;
+  /** Font family */
+  fontFamily?: string;
+  /** Renderer type */
+  rendererType?: 'dom' | 'canvas' | 'webgl';
+  /** Callback when terminal is ready */
+  onReady?: () => void;
+  /** Callback when connection opens */
+  onConnected?: () => void;
+  /** Callback when connection closes */
+  onDisconnected?: () => void;
+}
+
+export function XtermTerminal({
+  wsUrl,
+  theme,
+  fontSize = 14,
+  fontFamily = 'Consolas, Liberation Mono, Menlo, Courier, monospace',
+  rendererType = 'webgl',
+  onReady,
+  onConnected,
+  onDisconnected,
+}: XtermTerminalProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const terminalRef = useRef<ITerminal | null>(null);
+  const fitAddonRef = useRef<FitAddon | null>(null);
+  const webglAddonRef = useRef<WebglAddon | null>(null);
+  const canvasAddonRef = useRef<CanvasAddon | null>(null);
+  const socketRef = useRef<WebSocket | null>(null);
+  const [isConnected, setIsConnected] = useState(false);
+
+  const textEncoder = useRef(new TextEncoder());
+  const textDecoder = useRef(new TextDecoder());
+
+  // Initialize terminal
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    // Terminal options
+    const termOptions: ITerminalOptions = {
+      fontSize,
+      fontFamily,
+      theme: theme || {
+        foreground: '#d2d2d2',
+        background: '#1e1e1e',
+        cursor: '#adadad',
+        black: '#000000',
+        red: '#d81e00',
+        green: '#5ea702',
+        yellow: '#cfae00',
+        blue: '#427ab3',
+        magenta: '#89658e',
+        cyan: '#00a7aa',
+        white: '#dbded8',
+        brightBlack: '#686a66',
+        brightRed: '#f54235',
+        brightGreen: '#99e343',
+        brightYellow: '#fdeb61',
+        brightBlue: '#84b0d8',
+        brightMagenta: '#bc94b7',
+        brightCyan: '#37e6e8',
+        brightWhite: '#f1f1f0',
+      },
+      cursorBlink: true,
+      cursorStyle: 'block',
+      allowProposedApi: true,
+      scrollback: 10000,
+      tabStopWidth: 8,
+    };
+
+    // Create terminal instance
+    const terminal = new Terminal(termOptions);
+    terminalRef.current = terminal;
+
+    // Create and load fit addon
+    const fitAddon = new FitAddon();
+    fitAddonRef.current = fitAddon;
+    terminal.loadAddon(fitAddon);
+
+    // Load web links addon
+    terminal.loadAddon(new WebLinksAddon());
+
+    // Open terminal in container
+    terminal.open(containerRef.current);
+    fitAddon.fit();
+
+    // Apply renderer
+    applyRenderer(rendererType);
+
+    // Setup event handlers
+    setupTerminalHandlers(terminal, fitAddon);
+
+    // Call onReady callback
+    onReady?.();
+
+    // Cleanup
+    return () => {
+      socketRef.current?.close();
+      webglAddonRef.current?.dispose();
+      canvasAddonRef.current?.dispose();
+      terminal.dispose();
+    };
+  }, []);
+
+  // Apply renderer (webgl, canvas, or dom)
+  const applyRenderer = (type: 'dom' | 'canvas' | 'webgl') => {
+    const terminal = terminalRef.current;
+    if (!terminal) return;
+
+    // Dispose existing renderers
+    try {
+      webglAddonRef.current?.dispose();
+      webglAddonRef.current = null;
+    } catch (e) {
+      // ignore
+    }
+    try {
+      canvasAddonRef.current?.dispose();
+      canvasAddonRef.current = null;
+    } catch (e) {
+      // ignore
+    }
+
+    // Apply new renderer
+    switch (type) {
+      case 'webgl':
+        try {
+          const webglAddon = new WebglAddon();
+          webglAddonRef.current = webglAddon;
+          terminal.loadAddon(webglAddon);
+          console.log('[terminal] WebGL renderer loaded');
+        } catch (e) {
+          console.log('[terminal] WebGL renderer failed, falling back to canvas', e);
+          applyRenderer('canvas');
+        }
+        break;
+      case 'canvas':
+        try {
+          const canvasAddon = new CanvasAddon();
+          canvasAddonRef.current = canvasAddon;
+          terminal.loadAddon(canvasAddon);
+          console.log('[terminal] Canvas renderer loaded');
+        } catch (e) {
+          console.log('[terminal] Canvas renderer failed, falling back to dom', e);
+        }
+        break;
+      case 'dom':
+        console.log('[terminal] DOM renderer loaded');
+        break;
+    }
+  };
+
+  // Setup terminal event handlers
+  const setupTerminalHandlers = (terminal: ITerminal, fitAddon: FitAddon) => {
+    // Handle data input from user
+    terminal.onData((data) => {
+      sendData(data);
+    });
+
+    // Handle binary input
+    terminal.onBinary((data) => {
+      sendData(Uint8Array.from(data, (v) => v.charCodeAt(0)));
+    });
+
+    // Handle terminal resize
+    terminal.onResize(({ cols, rows }) => {
+      const socket = socketRef.current;
+      if (socket?.readyState === WebSocket.OPEN) {
+        const msg = JSON.stringify({ columns: cols, rows });
+        socket.send(textEncoder.current.encode(ClientCommand.RESIZE_TERMINAL + msg));
+      }
+    });
+
+    // Handle window resize
+    const handleWindowResize = () => {
+      fitAddon.fit();
+    };
+    window.addEventListener('resize', handleWindowResize);
+
+    // Cleanup
+    return () => {
+      window.removeEventListener('resize', handleWindowResize);
+    };
+  };
+
+  // Send data to server
+  const sendData = (data: string | Uint8Array) => {
+    const socket = socketRef.current;
+    if (socket?.readyState !== WebSocket.OPEN) return;
+
+    if (typeof data === 'string') {
+      const payload = new Uint8Array(data.length * 3 + 1);
+      payload[0] = ClientCommand.INPUT.charCodeAt(0);
+      const stats = textEncoder.current.encodeInto(data, payload.subarray(1));
+      socket.send(payload.subarray(0, (stats.written as number) + 1));
+    } else {
+      const payload = new Uint8Array(data.length + 1);
+      payload[0] = ClientCommand.INPUT.charCodeAt(0);
+      payload.set(data, 1);
+      socket.send(payload);
+    }
+  };
+
+  // Connect to WebSocket
+  useEffect(() => {
+    if (!wsUrl || !terminalRef.current) return;
+
+    const terminal = terminalRef.current;
+
+    // Parse the ttyd URL and construct WebSocket URL
+    // Important: Must preserve query parameters (?arg=TOKEN) for ttyd authentication
+    let wsFullUrl: string;
+    let token = '';
+
+    try {
+      // ttydUrl format: https://xxx.usw.sealos.io?arg=TOKEN
+      const url = new URL(wsUrl);
+      token = url.searchParams.get('arg') || '';
+
+      // Create WebSocket URL: wss://xxx.usw.sealos.io/ws?arg=TOKEN
+      // NOTE: Query parameters MUST be included for ttyd -a authentication!
+      const wsProtocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+      const wsPath = url.pathname.replace(/\/$/, '') + '/ws';
+      wsFullUrl = `${wsProtocol}//${url.host}${wsPath}${url.search}`;
+
+      console.log('[terminal] Extracted token:', token ? '***' : 'EMPTY');
+      console.log('[terminal] Connecting to:', wsFullUrl.replace(token, '***'));
+    } catch (error) {
+      console.error('[terminal] Failed to parse ttyd URL:', error);
+      onDisconnected?.();
+      return;
+    }
+
+    if (!token) {
+      console.error('[terminal] No authentication token found in URL');
+      onDisconnected?.();
+      return;
+    }
+
+    // Connect to WebSocket with 'tty' protocol
+    const socket = new WebSocket(wsFullUrl, ['tty']);
+    socketRef.current = socket;
+    socket.binaryType = 'arraybuffer';
+
+    // WebSocket open handler
+    socket.onopen = () => {
+      console.log('[terminal] WebSocket connected');
+      setIsConnected(true);
+      onConnected?.();
+
+      // Send initial message with terminal size
+      // NOTE: ttyd with -a flag authenticates via URL parameter, not AuthToken
+      // But we still send this message for compatibility and terminal size
+      const authMsg = JSON.stringify({
+        AuthToken: token,
+        columns: terminal.cols,
+        rows: terminal.rows,
+      });
+
+      console.log('[terminal] Sending initial terminal size');
+      socket.send(textEncoder.current.encode(authMsg));
+
+      terminal.focus();
+    };
+
+    // WebSocket message handler
+    socket.onmessage = (event: MessageEvent) => {
+      const rawData = event.data as ArrayBuffer;
+      const cmd = String.fromCharCode(new Uint8Array(rawData)[0]);
+      const data = rawData.slice(1);
+
+      switch (cmd) {
+        case Command.OUTPUT:
+          // Write output to terminal
+          terminal.write(new Uint8Array(data));
+          break;
+        case Command.SET_WINDOW_TITLE:
+          // Set window title
+          const title = textDecoder.current.decode(data);
+          document.title = title;
+          break;
+        case Command.SET_PREFERENCES:
+          // Handle preferences (not implemented yet)
+          console.log('[terminal] Preferences received:', textDecoder.current.decode(data));
+          break;
+        default:
+          console.warn('[terminal] Unknown command:', cmd);
+          break;
+      }
+    };
+
+    // WebSocket close handler
+    socket.onclose = (event: CloseEvent) => {
+      console.log('[terminal] WebSocket closed:', event.code);
+      setIsConnected(false);
+      onDisconnected?.();
+
+      // Show reconnection message
+      terminal.write('\r\n\x1b[31mConnection closed\x1b[0m\r\n');
+      terminal.write('Press \x1b[32mEnter\x1b[0m to reconnect\r\n');
+
+      // Handle reconnection on Enter key
+      const reconnectHandler = terminal.onKey((e) => {
+        if (e.key === '\r') {
+          reconnectHandler.dispose();
+          terminal.clear();
+          // Trigger reconnection by changing wsUrl or using a reconnect function
+        }
+      });
+    };
+
+    // WebSocket error handler
+    socket.onerror = (error) => {
+      console.error('[terminal] WebSocket error:', error);
+    };
+
+    // Cleanup
+    return () => {
+      socket.close();
+    };
+  }, [wsUrl]);
+
+  return (
+    <div
+      ref={containerRef}
+      className="w-full h-full"
+      style={{
+        padding: '5px',
+      }}
+    />
+  );
+}
diff --git a/hooks/use-terminal.ts b/hooks/use-terminal.ts
new file mode 100644
index 0000000..feff195
--- /dev/null
+++ b/hooks/use-terminal.ts
@@ -0,0 +1,142 @@
+/**
+ * useTerminal Hook
+ *
+ * Manages terminal WebSocket connection state and reconnection logic
+ */
+
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+export interface UseTerminalOptions {
+  /** ttyd URL with authentication token */
+  ttydUrl: string | null | undefined
+  /** Enable auto-reconnect on disconnect */
+  autoReconnect?: boolean
+  /** Reconnect delay in milliseconds */
+  reconnectDelay?: number
+  /** Callback when connected */
+  onConnected?: () => void
+  /** Callback when disconnected */
+  onDisconnected?: () => void
+  /** Callback when error occurs */
+  onError?: (error: Error) => void
+}
+
+export interface UseTerminalReturn {
+  /** Current connection status */
+  status: 'disconnected' | 'connecting' | 'connected' | 'error'
+  /** Whether terminal is ready to use */
+  isReady: boolean
+  /** WebSocket URL for xterm component */
+  wsUrl: string | null
+  /** Manually trigger reconnection */
+  reconnect: () => void
+  /** Disconnect and stop auto-reconnect */
+  disconnect: () => void
+}
+
+export function useTerminal(options: UseTerminalOptions): UseTerminalReturn {
+  const {
+    ttydUrl,
+    autoReconnect = true,
+    reconnectDelay = 3000,
+    onConnected,
+    onDisconnected,
+    onError,
+  } = options
+
+  const [status, setStatus] = useState<'disconnected' | 'connecting' | 'connected' | 'error'>(
+    'disconnected'
+  )
+  const [wsUrl, setWsUrl] = useState<string | null>(null)
+  const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null)
+  const shouldReconnectRef = useRef(true)
+
+  // Parse ttyd URL and prepare WebSocket URL
+  useEffect(() => {
+    if (!ttydUrl) {
+      setWsUrl(null)
+      setStatus('disconnected')
+      return
+    }
+
+    try {
+      // ttydUrl already includes the token as query parameter
+      setWsUrl(ttydUrl)
+      setStatus('connecting')
+    } catch (error) {
+      console.error('[useTerminal] Invalid ttyd URL:', error)
+      setStatus('error')
+      onError?.(error as Error)
+    }
+  }, [ttydUrl, onError])
+
+  // Handle connection status callbacks
+  const handleConnected = useCallback(() => {
+    setStatus('connected')
+    shouldReconnectRef.current = autoReconnect
+    onConnected?.()
+  }, [autoReconnect, onConnected])
+
+  const handleDisconnected = useCallback(() => {
+    setStatus('disconnected')
+    onDisconnected?.()
+
+    // Schedule reconnection if enabled
+    if (shouldReconnectRef.current && wsUrl) {
+      console.log(`[useTerminal] Reconnecting in ${reconnectDelay}ms...`)
+      reconnectTimeoutRef.current = setTimeout(() => {
+        setStatus('connecting')
+        // Trigger re-render to reconnect
+        setWsUrl((prev) => (prev ? `${prev}` : null))
+      }, reconnectDelay)
+    }
+  }, [wsUrl, reconnectDelay, onDisconnected])
+
+  // Manual reconnection
+  const reconnect = useCallback(() => {
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current)
+      reconnectTimeoutRef.current = null
+    }
+
+    shouldReconnectRef.current = true
+    setStatus('connecting')
+
+    // Force reconnection by updating wsUrl
+    if (ttydUrl) {
+      setWsUrl(`${ttydUrl}`)
+    }
+  }, [ttydUrl])
+
+  // Manual disconnection
+  const disconnect = useCallback(() => {
+    shouldReconnectRef.current = false
+
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current)
+      reconnectTimeoutRef.current = null
+    }
+
+    setStatus('disconnected')
+    setWsUrl(null)
+  }, [])
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current)
+      }
+    }
+  }, [])
+
+  return {
+    status,
+    isReady: status === 'connected',
+    wsUrl,
+    reconnect,
+    disconnect,
+  }
+}
diff --git a/lib/k8s/sandbox-manager.ts b/lib/k8s/sandbox-manager.ts
index 4a206f1..b0cc5a5 100644
--- a/lib/k8s/sandbox-manager.ts
+++ b/lib/k8s/sandbox-manager.ts
@@ -710,7 +710,23 @@ export class SandboxManager {
       },
     }
 
-    await this.k8sAppsApi.createNamespacedStatefulSet({ namespace, body: statefulSet })
+    try {
+      await this.k8sAppsApi.createNamespacedStatefulSet({ namespace, body: statefulSet })
+    } catch (error) {
+      // Handle 409 Conflict (AlreadyExists) as idempotent operation
+      if (
+        typeof error === 'object' &&
+        error !== null &&
+        'response' in error &&
+        typeof (error as { response: { statusCode?: number } }).response === 'object' &&
+        (error as { response: { statusCode?: number } }).response.statusCode === 409
+      ) {
+        logger.info(`StatefulSet already exists (409), skipping creation: ${sandboxName}`)
+        return
+      }
+      // Re-throw other errors
+      throw error
+    }
   }
 
   /**
diff --git a/package.json b/package.json
index cf52b36..30c2707 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,11 @@
     "@t3-oss/env-nextjs": "^0.13.8",
     "@tanstack/react-query": "^5.90.7",
     "@tanstack/react-query-devtools": "^5.90.2",
+    "@xterm/addon-canvas": "^0.7.0",
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/addon-web-links": "^0.11.0",
+    "@xterm/addon-webgl": "^0.18.0",
+    "@xterm/xterm": "^5.5.0",
     "@zjy365/sealos-desktop-sdk": "^0.1.20",
     "bcryptjs": "^3.0.2",
     "class-variance-authority": "^0.7.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 96dda86..d63d466 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -63,6 +63,21 @@ importers:
       '@tanstack/react-query-devtools':
         specifier: ^5.90.2
         version: 5.90.2(@tanstack/react-query@5.90.7(react@19.1.0))(react@19.1.0)
+      '@xterm/addon-canvas':
+        specifier: ^0.7.0
+        version: 0.7.0(@xterm/xterm@5.5.0)
+      '@xterm/addon-fit':
+        specifier: ^0.10.0
+        version: 0.10.0(@xterm/xterm@5.5.0)
+      '@xterm/addon-web-links':
+        specifier: ^0.11.0
+        version: 0.11.0(@xterm/xterm@5.5.0)
+      '@xterm/addon-webgl':
+        specifier: ^0.18.0
+        version: 0.18.0(@xterm/xterm@5.5.0)
+      '@xterm/xterm':
+        specifier: ^5.5.0
+        version: 5.5.0
       '@zjy365/sealos-desktop-sdk':
         specifier: ^0.1.20
         version: 0.1.20(@kubernetes/client-node@1.4.0)
@@ -1377,6 +1392,29 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@xterm/addon-canvas@0.7.0':
+    resolution: {integrity: sha512-LF5LYcfvefJuJ7QotNRdRSPc9YASAVDeoT5uyXS/nZshZXjYplGXRECBGiznwvhNL2I8bq1Lf5MzRwstsYQ2Iw==}
+    peerDependencies:
+      '@xterm/xterm': ^5.0.0
+
+  '@xterm/addon-fit@0.10.0':
+    resolution: {integrity: sha512-UFYkDm4HUahf2lnEyHvio51TNGiLK66mqP2JoATy7hRZeXaGMRDr00JiSF7m63vR5WKATF605yEggJKsw0JpMQ==}
+    peerDependencies:
+      '@xterm/xterm': ^5.0.0
+
+  '@xterm/addon-web-links@0.11.0':
+    resolution: {integrity: sha512-nIHQ38pQI+a5kXnRaTgwqSHnX7KE6+4SVoceompgHL26unAxdfP6IPqUTSYPQgSwM56hsElfoNrrW5V7BUED/Q==}
+    peerDependencies:
+      '@xterm/xterm': ^5.0.0
+
+  '@xterm/addon-webgl@0.18.0':
+    resolution: {integrity: sha512-xCnfMBTI+/HKPdRnSOHaJDRqEpq2Ugy8LEj9GiY4J3zJObo3joylIFaMvzBwbYRg8zLtkO0KQaStCeSfoaI2/w==}
+    peerDependencies:
+      '@xterm/xterm': ^5.0.0
+
+  '@xterm/xterm@5.5.0':
+    resolution: {integrity: sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A==}
+
   '@zjy365/sealos-desktop-sdk@0.1.20':
     resolution: {integrity: sha512-zIOFAEbzKeuu1gcHdjrd6g9l/AXOQY9yhEqI4Vz1sU8YZUqeKci3WRdV2Q5n3SJXI4GBN5o3i1YhTuIjTAdgmQ==}
     peerDependencies:
@@ -4241,6 +4279,24 @@ snapshots:
   '@unrs/resolver-binding-win32-x64-msvc@1.11.1':
     optional: true
 
+  '@xterm/addon-canvas@0.7.0(@xterm/xterm@5.5.0)':
+    dependencies:
+      '@xterm/xterm': 5.5.0
+
+  '@xterm/addon-fit@0.10.0(@xterm/xterm@5.5.0)':
+    dependencies:
+      '@xterm/xterm': 5.5.0
+
+  '@xterm/addon-web-links@0.11.0(@xterm/xterm@5.5.0)':
+    dependencies:
+      '@xterm/xterm': 5.5.0
+
+  '@xterm/addon-webgl@0.18.0(@xterm/xterm@5.5.0)':
+    dependencies:
+      '@xterm/xterm': 5.5.0
+
+  '@xterm/xterm@5.5.0': {}
+
   '@zjy365/sealos-desktop-sdk@0.1.20(@kubernetes/client-node@1.4.0)':
     dependencies:
       '@kubernetes/client-node': 1.4.0

From 0a5959410bbca751467e487f396dd518adc9ecd7 Mon Sep 17 00:00:00 2001
From: lim <huahua1319873800@outlook.com>
Date: Wed, 12 Nov 2025 03:27:31 +0000
Subject: [PATCH 2/8] fix ws manager

---
 components/terminal/terminal-display.tsx |  33 +--
 components/terminal/xterm-terminal.tsx   | 243 ++++++++++++++---------
 2 files changed, 166 insertions(+), 110 deletions(-)

diff --git a/components/terminal/terminal-display.tsx b/components/terminal/terminal-display.tsx
index 26e8ae9..5c803d2 100644
--- a/components/terminal/terminal-display.tsx
+++ b/components/terminal/terminal-display.tsx
@@ -7,7 +7,7 @@
 
 'use client';
 
-import { useState } from 'react';
+import { useCallback, useState } from 'react';
 import { AlertCircle, Terminal as TerminalIcon } from 'lucide-react';
 
 import { Spinner } from '@/components/ui/spinner';
@@ -40,6 +40,22 @@ export function TerminalDisplay({ ttydUrl, status, tabId }: TerminalDisplayProps
     'connecting'
   );
 
+  // Stable callback functions to prevent unnecessary re-renders of XtermTerminal
+  const handleReady = useCallback(() => {
+    console.log('[TerminalDisplay] Terminal ready');
+    setTerminalReady(true);
+  }, []);
+
+  const handleConnected = useCallback(() => {
+    console.log('[TerminalDisplay] Terminal WebSocket connected');
+    setConnectionStatus('connected');
+  }, []);
+
+  const handleDisconnected = useCallback(() => {
+    console.log('[TerminalDisplay] Terminal WebSocket disconnected');
+    setConnectionStatus('connecting');
+  }, []);
+
   // Only show terminal if status is RUNNING and ttyd URL is available
   if (status === 'RUNNING' && ttydUrl) {
     return (
@@ -85,18 +101,9 @@ export function TerminalDisplay({ ttydUrl, status, tabId }: TerminalDisplayProps
             fontSize={14}
             fontFamily="Consolas, Liberation Mono, Menlo, Courier, monospace"
             rendererType="webgl"
-            onReady={() => {
-              console.log('[TerminalDisplay] Terminal ready');
-              setTerminalReady(true);
-            }}
-            onConnected={() => {
-              console.log('[TerminalDisplay] Terminal WebSocket connected');
-              setConnectionStatus('connected');
-            }}
-            onDisconnected={() => {
-              console.log('[TerminalDisplay] Terminal WebSocket disconnected');
-              setConnectionStatus('connecting');
-            }}
+            onReady={handleReady}
+            onConnected={handleConnected}
+            onDisconnected={handleDisconnected}
           />
         </div>
 
diff --git a/components/terminal/xterm-terminal.tsx b/components/terminal/xterm-terminal.tsx
index af0b784..efdb04c 100644
--- a/components/terminal/xterm-terminal.tsx
+++ b/components/terminal/xterm-terminal.tsx
@@ -263,124 +263,173 @@ export function XtermTerminal({
     }
   };
 
-  // Connect to WebSocket
+  // Connect to WebSocket - runs once when wsUrl is provided
   useEffect(() => {
     if (!wsUrl || !terminalRef.current) return;
 
+    // Note: In React Strict Mode (development), this effect will run twice
+    // The cleanup function will properly close the first connection before the second one is created
+    // This is intentional behavior to help detect side effect issues
+    // In production builds, Strict Mode is disabled and this will only run once
+
     const terminal = terminalRef.current;
+    let socket: WebSocket | null = null;
+    let reconnectTimeoutId: NodeJS.Timeout | null = null;
+    let isCleaningUp = false;
 
     // Parse the ttyd URL and construct WebSocket URL
     // Important: Must preserve query parameters (?arg=TOKEN) for ttyd authentication
-    let wsFullUrl: string;
-    let token = '';
-
-    try {
-      // ttydUrl format: https://xxx.usw.sealos.io?arg=TOKEN
-      const url = new URL(wsUrl);
-      token = url.searchParams.get('arg') || '';
-
-      // Create WebSocket URL: wss://xxx.usw.sealos.io/ws?arg=TOKEN
-      // NOTE: Query parameters MUST be included for ttyd -a authentication!
-      const wsProtocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
-      const wsPath = url.pathname.replace(/\/$/, '') + '/ws';
-      wsFullUrl = `${wsProtocol}//${url.host}${wsPath}${url.search}`;
-
-      console.log('[terminal] Extracted token:', token ? '***' : 'EMPTY');
-      console.log('[terminal] Connecting to:', wsFullUrl.replace(token, '***'));
-    } catch (error) {
-      console.error('[terminal] Failed to parse ttyd URL:', error);
-      onDisconnected?.();
-      return;
-    }
+    const parseUrl = (): { wsFullUrl: string; token: string } | null => {
+      try {
+        // ttydUrl format: https://xxx.usw.sealos.io?arg=TOKEN
+        const url = new URL(wsUrl);
+        const token = url.searchParams.get('arg') || '';
+
+        if (!token) {
+          console.error('[terminal] No authentication token found in URL');
+          return null;
+        }
 
-    if (!token) {
-      console.error('[terminal] No authentication token found in URL');
-      onDisconnected?.();
-      return;
-    }
+        // Create WebSocket URL: wss://xxx.usw.sealos.io/ws?arg=TOKEN
+        // NOTE: Query parameters MUST be included for ttyd -a authentication!
+        const wsProtocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        const wsPath = url.pathname.replace(/\/$/, '') + '/ws';
+        const wsFullUrl = `${wsProtocol}//${url.host}${wsPath}${url.search}`;
 
-    // Connect to WebSocket with 'tty' protocol
-    const socket = new WebSocket(wsFullUrl, ['tty']);
-    socketRef.current = socket;
-    socket.binaryType = 'arraybuffer';
-
-    // WebSocket open handler
-    socket.onopen = () => {
-      console.log('[terminal] WebSocket connected');
-      setIsConnected(true);
-      onConnected?.();
-
-      // Send initial message with terminal size
-      // NOTE: ttyd with -a flag authenticates via URL parameter, not AuthToken
-      // But we still send this message for compatibility and terminal size
-      const authMsg = JSON.stringify({
-        AuthToken: token,
-        columns: terminal.cols,
-        rows: terminal.rows,
-      });
-
-      console.log('[terminal] Sending initial terminal size');
-      socket.send(textEncoder.current.encode(authMsg));
-
-      terminal.focus();
-    };
+        console.log('[terminal] Extracted token:', token ? '***' : 'EMPTY');
+        console.log('[terminal] Connecting to:', wsFullUrl.replace(token, '***'));
 
-    // WebSocket message handler
-    socket.onmessage = (event: MessageEvent) => {
-      const rawData = event.data as ArrayBuffer;
-      const cmd = String.fromCharCode(new Uint8Array(rawData)[0]);
-      const data = rawData.slice(1);
-
-      switch (cmd) {
-        case Command.OUTPUT:
-          // Write output to terminal
-          terminal.write(new Uint8Array(data));
-          break;
-        case Command.SET_WINDOW_TITLE:
-          // Set window title
-          const title = textDecoder.current.decode(data);
-          document.title = title;
-          break;
-        case Command.SET_PREFERENCES:
-          // Handle preferences (not implemented yet)
-          console.log('[terminal] Preferences received:', textDecoder.current.decode(data));
-          break;
-        default:
-          console.warn('[terminal] Unknown command:', cmd);
-          break;
+        return { wsFullUrl, token };
+      } catch (error) {
+        console.error('[terminal] Failed to parse ttyd URL:', error);
+        return null;
       }
     };
 
-    // WebSocket close handler
-    socket.onclose = (event: CloseEvent) => {
-      console.log('[terminal] WebSocket closed:', event.code);
-      setIsConnected(false);
+    const urlInfo = parseUrl();
+    if (!urlInfo) {
       onDisconnected?.();
+      return;
+    }
 
-      // Show reconnection message
-      terminal.write('\r\n\x1b[31mConnection closed\x1b[0m\r\n');
-      terminal.write('Press \x1b[32mEnter\x1b[0m to reconnect\r\n');
-
-      // Handle reconnection on Enter key
-      const reconnectHandler = terminal.onKey((e) => {
-        if (e.key === '\r') {
-          reconnectHandler.dispose();
-          terminal.clear();
-          // Trigger reconnection by changing wsUrl or using a reconnect function
+    const { wsFullUrl, token } = urlInfo;
+
+    // Connect to WebSocket
+    const connect = () => {
+      if (isCleaningUp) return;
+
+      console.log('[terminal] Connecting to WebSocket...');
+      socket = new WebSocket(wsFullUrl, ['tty']);
+      socketRef.current = socket;
+      socket.binaryType = 'arraybuffer';
+
+      // WebSocket open handler
+      socket.onopen = () => {
+        console.log('[terminal] WebSocket connected');
+        setIsConnected(true);
+        onConnected?.();
+
+        // Send initial message with terminal size
+        // NOTE: ttyd with -a flag authenticates via URL parameter, not AuthToken
+        // But we still send this message for compatibility and terminal size
+        const authMsg = JSON.stringify({
+          AuthToken: token,
+          columns: terminal.cols,
+          rows: terminal.rows,
+        });
+
+        console.log('[terminal] Sending initial terminal size');
+        socket?.send(textEncoder.current.encode(authMsg));
+
+        terminal.focus();
+      };
+
+      // WebSocket message handler
+      socket.onmessage = (event: MessageEvent) => {
+        const rawData = event.data as ArrayBuffer;
+        const cmd = String.fromCharCode(new Uint8Array(rawData)[0]);
+        const data = rawData.slice(1);
+
+        switch (cmd) {
+          case Command.OUTPUT:
+            // Write output to terminal
+            terminal.write(new Uint8Array(data));
+            break;
+          case Command.SET_WINDOW_TITLE:
+            // Set window title
+            const title = textDecoder.current.decode(data);
+            document.title = title;
+            break;
+          case Command.SET_PREFERENCES:
+            // Handle preferences (not implemented yet)
+            console.log('[terminal] Preferences received:', textDecoder.current.decode(data));
+            break;
+          default:
+            console.warn('[terminal] Unknown command:', cmd);
+            break;
         }
-      });
-    };
+      };
+
+      // WebSocket close handler
+      socket.onclose = (event: CloseEvent) => {
+        console.log('[terminal] WebSocket closed:', event.code, event.reason);
+        setIsConnected(false);
+        socketRef.current = null;
+        onDisconnected?.();
+
+        // Only attempt reconnection if not cleaning up and close was unexpected
+        if (!isCleaningUp && event.code !== 1000) {
+          terminal.write('\r\n\x1b[33m[Connection lost. Reconnecting in 3 seconds...]\x1b[0m\r\n');
+
+          // Auto-reconnect after 3 seconds
+          reconnectTimeoutId = setTimeout(() => {
+            if (!isCleaningUp) {
+              console.log('[terminal] Attempting to reconnect...');
+              connect();
+            }
+          }, 3000);
+        } else {
+          terminal.write('\r\n\x1b[31m[Connection closed]\x1b[0m\r\n');
+        }
+      };
 
-    // WebSocket error handler
-    socket.onerror = (error) => {
-      console.error('[terminal] WebSocket error:', error);
+      // WebSocket error handler
+      socket.onerror = (error) => {
+        console.error('[terminal] WebSocket error:', error);
+      };
     };
 
-    // Cleanup
+    // Initial connection
+    connect();
+
+    // Cleanup function
     return () => {
-      socket.close();
+      console.log('[terminal] Cleaning up WebSocket connection');
+      isCleaningUp = true;
+
+      // Clear reconnect timeout if exists
+      if (reconnectTimeoutId) {
+        clearTimeout(reconnectTimeoutId);
+        reconnectTimeoutId = null;
+      }
+
+      // Close socket if open
+      if (socket) {
+        socket.onclose = null; // Remove handler to prevent reconnect
+        socket.onerror = null;
+        socket.onmessage = null;
+        socket.onopen = null;
+
+        if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+          socket.close(1000, 'Component unmounted');
+        }
+        socket = null;
+        socketRef.current = null;
+      }
+
+      setIsConnected(false);
     };
-  }, [wsUrl]);
+  }, [wsUrl, onConnected, onDisconnected]); // Only reconnect when wsUrl or callbacks change
 
   return (
     <div

From 07834c500ffe387f8b5487579d8919789492551c Mon Sep 17 00:00:00 2001
From: lim <huahua1319873800@outlook.com>
Date: Wed, 12 Nov 2025 03:58:00 +0000
Subject: [PATCH 3/8] fix auto scroll

---
 components/terminal/xterm-terminal.tsx | 87 +++++++++++++++++++++++++-
 1 file changed, 86 insertions(+), 1 deletion(-)

diff --git a/components/terminal/xterm-terminal.tsx b/components/terminal/xterm-terminal.tsx
index efdb04c..4b8cdc5 100644
--- a/components/terminal/xterm-terminal.tsx
+++ b/components/terminal/xterm-terminal.tsx
@@ -94,6 +94,31 @@ export function XtermTerminal({
   const textEncoder = useRef(new TextEncoder());
   const textDecoder = useRef(new TextDecoder());
 
+  // Track if user has scrolled away from bottom
+  // When true, we should auto-scroll on new output
+  const isAtBottomRef = useRef(true);
+
+  /**
+   * Check if terminal is scrolled to bottom (or very close)
+   * Returns true if viewport is showing the last line of the buffer
+   * Uses a small tolerance to handle edge cases with control sequences
+   */
+  const isTerminalAtBottom = (terminal: ITerminal): boolean => {
+    try {
+      const buffer = terminal.buffer.active;
+      // viewportY: current scroll position (0-based)
+      // baseY: the line number of the bottom of the viewport
+      // Use <= instead of === to be more forgiving
+      // This handles cases where content is being written with control sequences
+      const threshold = 2; // Allow up to 2 lines of tolerance
+      return buffer.viewportY >= buffer.baseY - threshold;
+    } catch (error) {
+      // Fallback: assume at bottom if we can't determine
+      console.warn('[terminal] Could not determine scroll position:', error);
+      return true;
+    }
+  };
+
   // Initialize terminal
   useEffect(() => {
     if (!containerRef.current) return;
@@ -216,11 +241,22 @@ export function XtermTerminal({
   const setupTerminalHandlers = (terminal: ITerminal, fitAddon: FitAddon) => {
     // Handle data input from user
     terminal.onData((data) => {
+      // When user types, they expect to see the bottom
+      // Auto-scroll to bottom and mark as being at bottom
+      if (!isAtBottomRef.current) {
+        terminal.scrollToBottom();
+        isAtBottomRef.current = true;
+      }
       sendData(data);
     });
 
     // Handle binary input
     terminal.onBinary((data) => {
+      // Same behavior for binary input
+      if (!isAtBottomRef.current) {
+        terminal.scrollToBottom();
+        isAtBottomRef.current = true;
+      }
       sendData(Uint8Array.from(data, (v) => v.charCodeAt(0)));
     });
 
@@ -233,6 +269,32 @@ export function XtermTerminal({
       }
     });
 
+    // Handle scroll events - track if user is at bottom
+    // This allows us to detect when user scrolls up to view history
+    terminal.onScroll(() => {
+      const wasAtBottom = isAtBottomRef.current;
+      const nowAtBottom = isTerminalAtBottom(terminal);
+
+      if (wasAtBottom !== nowAtBottom) {
+        isAtBottomRef.current = nowAtBottom;
+        console.log('[terminal] User scroll position:', nowAtBottom ? 'at bottom' : 'viewing history');
+      }
+    });
+
+    // Handle line feed events - this catches when new lines are added
+    // Critical for interactive prompts that use control sequences
+    let lineFeedTimeout: NodeJS.Timeout | null = null;
+    terminal.onLineFeed(() => {
+      // Debounce scrolling to avoid excessive calls
+      if (lineFeedTimeout) clearTimeout(lineFeedTimeout);
+
+      lineFeedTimeout = setTimeout(() => {
+        if (isAtBottomRef.current) {
+          terminal.scrollToBottom();
+        }
+      }, 10);
+    });
+
     // Handle window resize
     const handleWindowResize = () => {
       fitAddon.fit();
@@ -241,6 +303,7 @@ export function XtermTerminal({
 
     // Cleanup
     return () => {
+      if (lineFeedTimeout) clearTimeout(lineFeedTimeout);
       window.removeEventListener('resize', handleWindowResize);
     };
   };
@@ -352,8 +415,30 @@ export function XtermTerminal({
 
         switch (cmd) {
           case Command.OUTPUT:
-            // Write output to terminal
+            // Smart scroll behavior:
+            // 1. Check if user is at bottom BEFORE writing
+            const shouldAutoScroll = isAtBottomRef.current;
+
+            // 2. Write output to terminal
             terminal.write(new Uint8Array(data));
+
+            // 3. IMMEDIATELY scroll after write (synchronous)
+            // This is critical for interactive prompts (like Claude Code choices)
+            // that use cursor control sequences - we must scroll IMMEDIATELY
+            if (shouldAutoScroll) {
+              // Use requestAnimationFrame to ensure DOM has updated
+              requestAnimationFrame(() => {
+                terminal.scrollToBottom();
+
+                // Double-check: if we're still not at bottom, force scroll again
+                // This handles edge cases with complex control sequences
+                requestAnimationFrame(() => {
+                  if (!isTerminalAtBottom(terminal)) {
+                    terminal.scrollToBottom();
+                  }
+                });
+              });
+            }
             break;
           case Command.SET_WINDOW_TITLE:
             // Set window title

From 37aa81a7d3b0c626eb8d4ba3751082a2a2ffbb6e Mon Sep 17 00:00:00 2001
From: lim <huahua1319873800@outlook.com>
Date: Wed, 12 Nov 2025 04:23:01 +0000
Subject: [PATCH 4/8] fix xterm ssr and add auto scroll bar Indicator

---
 app/globals.css                        |  16 ++
 components/terminal/xterm-terminal.tsx | 259 ++++++++++++++++++-------
 2 files changed, 202 insertions(+), 73 deletions(-)

diff --git a/app/globals.css b/app/globals.css
index 1b16fb1..b26903b 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -184,3 +184,19 @@
     @apply leading-7 [&:not(:first-child)]:mt-6 text-muted-foreground;
   }
 }
+
+/* Terminal scroll indicator animation */
+@keyframes fade-in {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.animate-fade-in {
+  animation: fade-in 0.2s ease-out;
+}
diff --git a/components/terminal/xterm-terminal.tsx b/components/terminal/xterm-terminal.tsx
index 4b8cdc5..cb44316 100644
--- a/components/terminal/xterm-terminal.tsx
+++ b/components/terminal/xterm-terminal.tsx
@@ -8,16 +8,19 @@
 'use client';
 
 import { useEffect, useRef, useState } from 'react';
-import { CanvasAddon } from '@xterm/addon-canvas';
-import { FitAddon } from '@xterm/addon-fit';
-import { WebLinksAddon } from '@xterm/addon-web-links';
-import { WebglAddon } from '@xterm/addon-webgl';
 import type { ITerminalOptions, Terminal as ITerminal } from '@xterm/xterm';
-import { Terminal } from '@xterm/xterm';
 
-// Import xterm CSS at component level
+// Import xterm CSS at component level (safe for SSR)
 import '@xterm/xterm/css/xterm.css';
 
+// Type declarations for dynamically imported modules
+// These will only be loaded on the client side to avoid SSR issues
+type Terminal = import('@xterm/xterm').Terminal;
+type FitAddon = import('@xterm/addon-fit').FitAddon;
+type WebLinksAddon = import('@xterm/addon-web-links').WebLinksAddon;
+type WebglAddon = import('@xterm/addon-webgl').WebglAddon;
+type CanvasAddon = import('@xterm/addon-canvas').CanvasAddon;
+
 // Command types matching ttyd protocol
 enum Command {
   // server side
@@ -98,6 +101,10 @@ export function XtermTerminal({
   // When true, we should auto-scroll on new output
   const isAtBottomRef = useRef(true);
 
+  // Scroll indicator state - shows when new content arrives while user is viewing history
+  const [hasNewContent, setHasNewContent] = useState(false);
+  const [newLineCount, setNewLineCount] = useState(0);
+
   /**
    * Check if terminal is scrolled to bottom (or very close)
    * Returns true if viewport is showing the last line of the buffer
@@ -123,74 +130,106 @@ export function XtermTerminal({
   useEffect(() => {
     if (!containerRef.current) return;
 
-    // Terminal options
-    const termOptions: ITerminalOptions = {
-      fontSize,
-      fontFamily,
-      theme: theme || {
-        foreground: '#d2d2d2',
-        background: '#1e1e1e',
-        cursor: '#adadad',
-        black: '#000000',
-        red: '#d81e00',
-        green: '#5ea702',
-        yellow: '#cfae00',
-        blue: '#427ab3',
-        magenta: '#89658e',
-        cyan: '#00a7aa',
-        white: '#dbded8',
-        brightBlack: '#686a66',
-        brightRed: '#f54235',
-        brightGreen: '#99e343',
-        brightYellow: '#fdeb61',
-        brightBlue: '#84b0d8',
-        brightMagenta: '#bc94b7',
-        brightCyan: '#37e6e8',
-        brightWhite: '#f1f1f0',
-      },
-      cursorBlink: true,
-      cursorStyle: 'block',
-      allowProposedApi: true,
-      scrollback: 10000,
-      tabStopWidth: 8,
-    };
-
-    // Create terminal instance
-    const terminal = new Terminal(termOptions);
-    terminalRef.current = terminal;
-
-    // Create and load fit addon
-    const fitAddon = new FitAddon();
-    fitAddonRef.current = fitAddon;
-    terminal.loadAddon(fitAddon);
+    let terminal: ITerminal | null = null;
+    let fitAddon: FitAddon | null = null;
+    let isMounted = true;
 
-    // Load web links addon
-    terminal.loadAddon(new WebLinksAddon());
+    // Dynamically load xterm and addons (client-side only)
+    const initTerminal = async () => {
+      try {
+        // Dynamic imports to avoid SSR issues with 'self is not defined'
+        const xtermModule = await import('@xterm/xterm');
+        const fitAddonModule = await import('@xterm/addon-fit');
+        const webLinksAddonModule = await import('@xterm/addon-web-links');
+
+        // Check if component is still mounted after async import
+        if (!isMounted || !containerRef.current) return;
+
+        // Terminal options
+        const termOptions: ITerminalOptions = {
+          fontSize,
+          fontFamily,
+          theme: theme || {
+            foreground: '#d2d2d2',
+            background: '#1e1e1e',
+            cursor: '#adadad',
+            black: '#000000',
+            red: '#d81e00',
+            green: '#5ea702',
+            yellow: '#cfae00',
+            blue: '#427ab3',
+            magenta: '#89658e',
+            cyan: '#00a7aa',
+            white: '#dbded8',
+            brightBlack: '#686a66',
+            brightRed: '#f54235',
+            brightGreen: '#99e343',
+            brightYellow: '#fdeb61',
+            brightBlue: '#84b0d8',
+            brightMagenta: '#bc94b7',
+            brightCyan: '#37e6e8',
+            brightWhite: '#f1f1f0',
+          },
+          cursorBlink: true,
+          cursorStyle: 'block',
+          allowProposedApi: true,
+          scrollback: 10000,
+          tabStopWidth: 8,
+        };
+
+        // Create terminal instance
+        terminal = new xtermModule.Terminal(termOptions);
+        terminalRef.current = terminal;
+
+        // Create and load fit addon
+        fitAddon = new fitAddonModule.FitAddon();
+        fitAddonRef.current = fitAddon;
+        terminal.loadAddon(fitAddon);
+
+        // Load web links addon
+        terminal.loadAddon(new webLinksAddonModule.WebLinksAddon());
+
+        // Open terminal in container
+        terminal.open(containerRef.current);
+
+        // Wait for next frame before calling fit() to ensure container has dimensions
+        // This prevents "Cannot read properties of undefined (reading 'dimensions')" error
+        requestAnimationFrame(() => {
+          if (!isMounted) return;
+          fitAddon?.fit();
+        });
 
-    // Open terminal in container
-    terminal.open(containerRef.current);
-    fitAddon.fit();
+        // Apply renderer (async to allow terminal to initialize)
+        requestAnimationFrame(() => {
+          if (!isMounted) return;
+          applyRenderer(rendererType);
+        });
 
-    // Apply renderer
-    applyRenderer(rendererType);
+        // Setup event handlers
+        setupTerminalHandlers(terminal, fitAddon);
 
-    // Setup event handlers
-    setupTerminalHandlers(terminal, fitAddon);
+        // Call onReady callback
+        onReady?.();
+      } catch (error) {
+        console.error('[terminal] Failed to initialize terminal:', error);
+      }
+    };
 
-    // Call onReady callback
-    onReady?.();
+    // Start initialization
+    initTerminal();
 
     // Cleanup
     return () => {
+      isMounted = false;
       socketRef.current?.close();
       webglAddonRef.current?.dispose();
       canvasAddonRef.current?.dispose();
-      terminal.dispose();
+      terminal?.dispose();
     };
   }, []);
 
-  // Apply renderer (webgl, canvas, or dom)
-  const applyRenderer = (type: 'dom' | 'canvas' | 'webgl') => {
+  // Apply renderer (webgl, canvas, or dom) - async to support dynamic imports
+  const applyRenderer = async (type: 'dom' | 'canvas' | 'webgl') => {
     const terminal = terminalRef.current;
     if (!terminal) return;
 
@@ -208,22 +247,24 @@ export function XtermTerminal({
       // ignore
     }
 
-    // Apply new renderer
+    // Apply new renderer with dynamic imports
     switch (type) {
       case 'webgl':
         try {
-          const webglAddon = new WebglAddon();
+          const webglAddonModule = await import('@xterm/addon-webgl');
+          const webglAddon = new webglAddonModule.WebglAddon();
           webglAddonRef.current = webglAddon;
           terminal.loadAddon(webglAddon);
           console.log('[terminal] WebGL renderer loaded');
         } catch (e) {
           console.log('[terminal] WebGL renderer failed, falling back to canvas', e);
-          applyRenderer('canvas');
+          await applyRenderer('canvas');
         }
         break;
       case 'canvas':
         try {
-          const canvasAddon = new CanvasAddon();
+          const canvasAddonModule = await import('@xterm/addon-canvas');
+          const canvasAddon = new canvasAddonModule.CanvasAddon();
           canvasAddonRef.current = canvasAddon;
           terminal.loadAddon(canvasAddon);
           console.log('[terminal] Canvas renderer loaded');
@@ -238,7 +279,7 @@ export function XtermTerminal({
   };
 
   // Setup terminal event handlers
-  const setupTerminalHandlers = (terminal: ITerminal, fitAddon: FitAddon) => {
+  const setupTerminalHandlers = (terminal: ITerminal, fitAddon: import('@xterm/addon-fit').FitAddon) => {
     // Handle data input from user
     terminal.onData((data) => {
       // When user types, they expect to see the bottom
@@ -247,6 +288,11 @@ export function XtermTerminal({
         terminal.scrollToBottom();
         isAtBottomRef.current = true;
       }
+      // Clear new content indicator when user types
+      if (hasNewContent) {
+        setHasNewContent(false);
+        setNewLineCount(0);
+      }
       sendData(data);
     });
 
@@ -257,6 +303,11 @@ export function XtermTerminal({
         terminal.scrollToBottom();
         isAtBottomRef.current = true;
       }
+      // Clear new content indicator
+      if (hasNewContent) {
+        setHasNewContent(false);
+        setNewLineCount(0);
+      }
       sendData(Uint8Array.from(data, (v) => v.charCodeAt(0)));
     });
 
@@ -277,7 +328,16 @@ export function XtermTerminal({
 
       if (wasAtBottom !== nowAtBottom) {
         isAtBottomRef.current = nowAtBottom;
-        console.log('[terminal] User scroll position:', nowAtBottom ? 'at bottom' : 'viewing history');
+        console.log(
+          '[terminal] User scroll position:',
+          nowAtBottom ? 'at bottom' : 'viewing history'
+        );
+
+        // Clear new content indicator when user scrolls to bottom
+        if (nowAtBottom && hasNewContent) {
+          setHasNewContent(false);
+          setNewLineCount(0);
+        }
       }
     });
 
@@ -291,6 +351,10 @@ export function XtermTerminal({
       lineFeedTimeout = setTimeout(() => {
         if (isAtBottomRef.current) {
           terminal.scrollToBottom();
+        } else {
+          // User is viewing history - increment new content counter
+          setHasNewContent(true);
+          setNewLineCount((prev) => prev + 1);
         }
       }, 10);
     });
@@ -516,13 +580,62 @@ export function XtermTerminal({
     };
   }, [wsUrl, onConnected, onDisconnected]); // Only reconnect when wsUrl or callbacks change
 
+  // Handle scroll to bottom button click
+  const handleScrollToBottom = () => {
+    const terminal = terminalRef.current;
+    if (terminal) {
+      terminal.scrollToBottom();
+      isAtBottomRef.current = true;
+      setHasNewContent(false);
+      setNewLineCount(0);
+    }
+  };
+
   return (
-    <div
-      ref={containerRef}
-      className="w-full h-full"
-      style={{
-        padding: '5px',
-      }}
-    />
+    <div className="relative w-full h-full">
+      {/* Terminal container */}
+      <div
+        ref={containerRef}
+        className="w-full h-full"
+        style={{
+          padding: '5px',
+        }}
+      />
+
+      {/* Scroll to bottom indicator - shows when new content arrives while viewing history */}
+      {hasNewContent && (
+        <button
+          onClick={handleScrollToBottom}
+          className="absolute bottom-4 right-4
+                     bg-blue-500 hover:bg-blue-600
+                     text-white text-sm font-medium
+                     px-4 py-2 rounded-full
+                     shadow-lg hover:shadow-xl
+                     transition-all duration-200
+                     flex items-center gap-2
+                     animate-fade-in
+                     z-10"
+          aria-label={`Scroll to bottom (${newLineCount} new lines)`}
+        >
+          <svg
+            className="w-4 h-4"
+            fill="none"
+            stroke="currentColor"
+            viewBox="0 0 24 24"
+            xmlns="http://www.w3.org/2000/svg"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M19 14l-7 7m0 0l-7-7m7 7V3"
+            />
+          </svg>
+          <span>
+            {newLineCount} new {newLineCount === 1 ? 'line' : 'lines'}
+          </span>
+        </button>
+      )}
+    </div>
   );
 }

From 5d900d1af223372b5707a5fd97d7a41439f09a25 Mon Sep 17 00:00:00 2001
From: lim <huahua1319873800@outlook.com>
Date: Wed, 12 Nov 2025 05:22:30 +0000
Subject: [PATCH 5/8] chore

---
 components/terminal/xterm-terminal.tsx | 680 ++++++++++---------------
 1 file changed, 273 insertions(+), 407 deletions(-)

diff --git a/components/terminal/xterm-terminal.tsx b/components/terminal/xterm-terminal.tsx
index cb44316..c027c1b 100644
--- a/components/terminal/xterm-terminal.tsx
+++ b/components/terminal/xterm-terminal.tsx
@@ -2,7 +2,7 @@
  * XtermTerminal Component
  *
  * Core xterm.js terminal component with WebSocket connection to ttyd backend
- * Based on ttyd's frontend implementation
+ * Based on ttyd's frontend implementation with proper SSR handling
  */
 
 'use client';
@@ -14,22 +14,17 @@ import type { ITerminalOptions, Terminal as ITerminal } from '@xterm/xterm';
 import '@xterm/xterm/css/xterm.css';
 
 // Type declarations for dynamically imported modules
-// These will only be loaded on the client side to avoid SSR issues
-type Terminal = import('@xterm/xterm').Terminal;
 type FitAddon = import('@xterm/addon-fit').FitAddon;
-type WebLinksAddon = import('@xterm/addon-web-links').WebLinksAddon;
 type WebglAddon = import('@xterm/addon-webgl').WebglAddon;
 type CanvasAddon = import('@xterm/addon-canvas').CanvasAddon;
 
 // Command types matching ttyd protocol
 enum Command {
-  // server side
   OUTPUT = '0',
   SET_WINDOW_TITLE = '1',
   SET_PREFERENCES = '2',
 }
 
-// Client command types
 enum ClientCommand {
   INPUT = '0',
   RESIZE_TERMINAL = '1',
@@ -87,328 +82,42 @@ export function XtermTerminal({
   onDisconnected,
 }: XtermTerminalProps) {
   const containerRef = useRef<HTMLDivElement>(null);
-  const terminalRef = useRef<ITerminal | null>(null);
-  const fitAddonRef = useRef<FitAddon | null>(null);
-  const webglAddonRef = useRef<WebglAddon | null>(null);
-  const canvasAddonRef = useRef<CanvasAddon | null>(null);
-  const socketRef = useRef<WebSocket | null>(null);
   const [isConnected, setIsConnected] = useState(false);
-
-  const textEncoder = useRef(new TextEncoder());
-  const textDecoder = useRef(new TextDecoder());
-
-  // Track if user has scrolled away from bottom
-  // When true, we should auto-scroll on new output
-  const isAtBottomRef = useRef(true);
-
-  // Scroll indicator state - shows when new content arrives while user is viewing history
   const [hasNewContent, setHasNewContent] = useState(false);
   const [newLineCount, setNewLineCount] = useState(0);
 
-  /**
-   * Check if terminal is scrolled to bottom (or very close)
-   * Returns true if viewport is showing the last line of the buffer
-   * Uses a small tolerance to handle edge cases with control sequences
-   */
-  const isTerminalAtBottom = (terminal: ITerminal): boolean => {
-    try {
-      const buffer = terminal.buffer.active;
-      // viewportY: current scroll position (0-based)
-      // baseY: the line number of the bottom of the viewport
-      // Use <= instead of === to be more forgiving
-      // This handles cases where content is being written with control sequences
-      const threshold = 2; // Allow up to 2 lines of tolerance
-      return buffer.viewportY >= buffer.baseY - threshold;
-    } catch (error) {
-      // Fallback: assume at bottom if we can't determine
-      console.warn('[terminal] Could not determine scroll position:', error);
-      return true;
-    }
-  };
-
-  // Initialize terminal
+  // Single useEffect to manage entire component lifecycle
   useEffect(() => {
-    if (!containerRef.current) return;
+    if (!containerRef.current || !wsUrl) return;
 
+    // State tracking (using local variables to avoid stale closures)
     let terminal: ITerminal | null = null;
     let fitAddon: FitAddon | null = null;
+    let socket: WebSocket | null = null;
+    let webglAddon: WebglAddon | null = null;
+    let canvasAddon: CanvasAddon | null = null;
     let isMounted = true;
+    let isAtBottom = true;
+    let reconnectTimeout: NodeJS.Timeout | null = null;
 
-    // Dynamically load xterm and addons (client-side only)
-    const initTerminal = async () => {
-      try {
-        // Dynamic imports to avoid SSR issues with 'self is not defined'
-        const xtermModule = await import('@xterm/xterm');
-        const fitAddonModule = await import('@xterm/addon-fit');
-        const webLinksAddonModule = await import('@xterm/addon-web-links');
-
-        // Check if component is still mounted after async import
-        if (!isMounted || !containerRef.current) return;
-
-        // Terminal options
-        const termOptions: ITerminalOptions = {
-          fontSize,
-          fontFamily,
-          theme: theme || {
-            foreground: '#d2d2d2',
-            background: '#1e1e1e',
-            cursor: '#adadad',
-            black: '#000000',
-            red: '#d81e00',
-            green: '#5ea702',
-            yellow: '#cfae00',
-            blue: '#427ab3',
-            magenta: '#89658e',
-            cyan: '#00a7aa',
-            white: '#dbded8',
-            brightBlack: '#686a66',
-            brightRed: '#f54235',
-            brightGreen: '#99e343',
-            brightYellow: '#fdeb61',
-            brightBlue: '#84b0d8',
-            brightMagenta: '#bc94b7',
-            brightCyan: '#37e6e8',
-            brightWhite: '#f1f1f0',
-          },
-          cursorBlink: true,
-          cursorStyle: 'block',
-          allowProposedApi: true,
-          scrollback: 10000,
-          tabStopWidth: 8,
-        };
-
-        // Create terminal instance
-        terminal = new xtermModule.Terminal(termOptions);
-        terminalRef.current = terminal;
-
-        // Create and load fit addon
-        fitAddon = new fitAddonModule.FitAddon();
-        fitAddonRef.current = fitAddon;
-        terminal.loadAddon(fitAddon);
-
-        // Load web links addon
-        terminal.loadAddon(new webLinksAddonModule.WebLinksAddon());
-
-        // Open terminal in container
-        terminal.open(containerRef.current);
-
-        // Wait for next frame before calling fit() to ensure container has dimensions
-        // This prevents "Cannot read properties of undefined (reading 'dimensions')" error
-        requestAnimationFrame(() => {
-          if (!isMounted) return;
-          fitAddon?.fit();
-        });
-
-        // Apply renderer (async to allow terminal to initialize)
-        requestAnimationFrame(() => {
-          if (!isMounted) return;
-          applyRenderer(rendererType);
-        });
-
-        // Setup event handlers
-        setupTerminalHandlers(terminal, fitAddon);
-
-        // Call onReady callback
-        onReady?.();
-      } catch (error) {
-        console.error('[terminal] Failed to initialize terminal:', error);
-      }
-    };
-
-    // Start initialization
-    initTerminal();
+    const textEncoder = new TextEncoder();
+    const textDecoder = new TextDecoder();
 
-    // Cleanup
-    return () => {
-      isMounted = false;
-      socketRef.current?.close();
-      webglAddonRef.current?.dispose();
-      canvasAddonRef.current?.dispose();
-      terminal?.dispose();
-    };
-  }, []);
-
-  // Apply renderer (webgl, canvas, or dom) - async to support dynamic imports
-  const applyRenderer = async (type: 'dom' | 'canvas' | 'webgl') => {
-    const terminal = terminalRef.current;
-    if (!terminal) return;
-
-    // Dispose existing renderers
-    try {
-      webglAddonRef.current?.dispose();
-      webglAddonRef.current = null;
-    } catch (e) {
-      // ignore
-    }
-    try {
-      canvasAddonRef.current?.dispose();
-      canvasAddonRef.current = null;
-    } catch (e) {
-      // ignore
-    }
-
-    // Apply new renderer with dynamic imports
-    switch (type) {
-      case 'webgl':
-        try {
-          const webglAddonModule = await import('@xterm/addon-webgl');
-          const webglAddon = new webglAddonModule.WebglAddon();
-          webglAddonRef.current = webglAddon;
-          terminal.loadAddon(webglAddon);
-          console.log('[terminal] WebGL renderer loaded');
-        } catch (e) {
-          console.log('[terminal] WebGL renderer failed, falling back to canvas', e);
-          await applyRenderer('canvas');
-        }
-        break;
-      case 'canvas':
-        try {
-          const canvasAddonModule = await import('@xterm/addon-canvas');
-          const canvasAddon = new canvasAddonModule.CanvasAddon();
-          canvasAddonRef.current = canvasAddon;
-          terminal.loadAddon(canvasAddon);
-          console.log('[terminal] Canvas renderer loaded');
-        } catch (e) {
-          console.log('[terminal] Canvas renderer failed, falling back to dom', e);
-        }
-        break;
-      case 'dom':
-        console.log('[terminal] DOM renderer loaded');
-        break;
-    }
-  };
-
-  // Setup terminal event handlers
-  const setupTerminalHandlers = (terminal: ITerminal, fitAddon: import('@xterm/addon-fit').FitAddon) => {
-    // Handle data input from user
-    terminal.onData((data) => {
-      // When user types, they expect to see the bottom
-      // Auto-scroll to bottom and mark as being at bottom
-      if (!isAtBottomRef.current) {
-        terminal.scrollToBottom();
-        isAtBottomRef.current = true;
-      }
-      // Clear new content indicator when user types
-      if (hasNewContent) {
-        setHasNewContent(false);
-        setNewLineCount(0);
-      }
-      sendData(data);
-    });
-
-    // Handle binary input
-    terminal.onBinary((data) => {
-      // Same behavior for binary input
-      if (!isAtBottomRef.current) {
-        terminal.scrollToBottom();
-        isAtBottomRef.current = true;
-      }
-      // Clear new content indicator
-      if (hasNewContent) {
-        setHasNewContent(false);
-        setNewLineCount(0);
-      }
-      sendData(Uint8Array.from(data, (v) => v.charCodeAt(0)));
-    });
-
-    // Handle terminal resize
-    terminal.onResize(({ cols, rows }) => {
-      const socket = socketRef.current;
-      if (socket?.readyState === WebSocket.OPEN) {
-        const msg = JSON.stringify({ columns: cols, rows });
-        socket.send(textEncoder.current.encode(ClientCommand.RESIZE_TERMINAL + msg));
-      }
-    });
-
-    // Handle scroll events - track if user is at bottom
-    // This allows us to detect when user scrolls up to view history
-    terminal.onScroll(() => {
-      const wasAtBottom = isAtBottomRef.current;
-      const nowAtBottom = isTerminalAtBottom(terminal);
-
-      if (wasAtBottom !== nowAtBottom) {
-        isAtBottomRef.current = nowAtBottom;
-        console.log(
-          '[terminal] User scroll position:',
-          nowAtBottom ? 'at bottom' : 'viewing history'
-        );
-
-        // Clear new content indicator when user scrolls to bottom
-        if (nowAtBottom && hasNewContent) {
-          setHasNewContent(false);
-          setNewLineCount(0);
-        }
+    // Helper: Check if terminal is at bottom
+    const isTerminalAtBottom = (): boolean => {
+      if (!terminal) return true;
+      try {
+        const buffer = terminal.buffer.active;
+        const threshold = 2;
+        return buffer.viewportY >= buffer.baseY - threshold;
+      } catch {
+        return true;
       }
-    });
-
-    // Handle line feed events - this catches when new lines are added
-    // Critical for interactive prompts that use control sequences
-    let lineFeedTimeout: NodeJS.Timeout | null = null;
-    terminal.onLineFeed(() => {
-      // Debounce scrolling to avoid excessive calls
-      if (lineFeedTimeout) clearTimeout(lineFeedTimeout);
-
-      lineFeedTimeout = setTimeout(() => {
-        if (isAtBottomRef.current) {
-          terminal.scrollToBottom();
-        } else {
-          // User is viewing history - increment new content counter
-          setHasNewContent(true);
-          setNewLineCount((prev) => prev + 1);
-        }
-      }, 10);
-    });
-
-    // Handle window resize
-    const handleWindowResize = () => {
-      fitAddon.fit();
-    };
-    window.addEventListener('resize', handleWindowResize);
-
-    // Cleanup
-    return () => {
-      if (lineFeedTimeout) clearTimeout(lineFeedTimeout);
-      window.removeEventListener('resize', handleWindowResize);
     };
-  };
-
-  // Send data to server
-  const sendData = (data: string | Uint8Array) => {
-    const socket = socketRef.current;
-    if (socket?.readyState !== WebSocket.OPEN) return;
-
-    if (typeof data === 'string') {
-      const payload = new Uint8Array(data.length * 3 + 1);
-      payload[0] = ClientCommand.INPUT.charCodeAt(0);
-      const stats = textEncoder.current.encodeInto(data, payload.subarray(1));
-      socket.send(payload.subarray(0, (stats.written as number) + 1));
-    } else {
-      const payload = new Uint8Array(data.length + 1);
-      payload[0] = ClientCommand.INPUT.charCodeAt(0);
-      payload.set(data, 1);
-      socket.send(payload);
-    }
-  };
 
-  // Connect to WebSocket - runs once when wsUrl is provided
-  useEffect(() => {
-    if (!wsUrl || !terminalRef.current) return;
-
-    // Note: In React Strict Mode (development), this effect will run twice
-    // The cleanup function will properly close the first connection before the second one is created
-    // This is intentional behavior to help detect side effect issues
-    // In production builds, Strict Mode is disabled and this will only run once
-
-    const terminal = terminalRef.current;
-    let socket: WebSocket | null = null;
-    let reconnectTimeoutId: NodeJS.Timeout | null = null;
-    let isCleaningUp = false;
-
-    // Parse the ttyd URL and construct WebSocket URL
-    // Important: Must preserve query parameters (?arg=TOKEN) for ttyd authentication
+    // Helper: Parse ttyd URL and extract token
     const parseUrl = (): { wsFullUrl: string; token: string } | null => {
       try {
-        // ttydUrl format: https://xxx.usw.sealos.io?arg=TOKEN
         const url = new URL(wsUrl);
         const token = url.searchParams.get('arg') || '';
 
@@ -417,87 +126,125 @@ export function XtermTerminal({
           return null;
         }
 
-        // Create WebSocket URL: wss://xxx.usw.sealos.io/ws?arg=TOKEN
-        // NOTE: Query parameters MUST be included for ttyd -a authentication!
         const wsProtocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
         const wsPath = url.pathname.replace(/\/$/, '') + '/ws';
         const wsFullUrl = `${wsProtocol}//${url.host}${wsPath}${url.search}`;
 
-        console.log('[terminal] Extracted token:', token ? '***' : 'EMPTY');
         console.log('[terminal] Connecting to:', wsFullUrl.replace(token, '***'));
-
         return { wsFullUrl, token };
       } catch (error) {
-        console.error('[terminal] Failed to parse ttyd URL:', error);
+        console.error('[terminal] Failed to parse URL:', error);
         return null;
       }
     };
 
-    const urlInfo = parseUrl();
-    if (!urlInfo) {
-      onDisconnected?.();
-      return;
-    }
+    // Helper: Send data to server
+    const sendData = (data: string | Uint8Array) => {
+      if (!socket || socket.readyState !== WebSocket.OPEN) return;
+
+      if (typeof data === 'string') {
+        const payload = new Uint8Array(data.length * 3 + 1);
+        payload[0] = ClientCommand.INPUT.charCodeAt(0);
+        const stats = textEncoder.encodeInto(data, payload.subarray(1));
+        socket.send(payload.subarray(0, (stats.written as number) + 1));
+      } else {
+        const payload = new Uint8Array(data.length + 1);
+        payload[0] = ClientCommand.INPUT.charCodeAt(0);
+        payload.set(data, 1);
+        socket.send(payload);
+      }
+    };
 
-    const { wsFullUrl, token } = urlInfo;
+    // Helper: Apply renderer
+    const applyRenderer = async (type: 'dom' | 'canvas' | 'webgl') => {
+      if (!terminal) return;
 
-    // Connect to WebSocket
-    const connect = () => {
-      if (isCleaningUp) return;
+      try {
+        webglAddon?.dispose();
+        webglAddon = null;
+      } catch {}
+      try {
+        canvasAddon?.dispose();
+        canvasAddon = null;
+      } catch {}
+
+      switch (type) {
+        case 'webgl':
+          try {
+            const module = await import('@xterm/addon-webgl');
+            webglAddon = new module.WebglAddon();
+            terminal.loadAddon(webglAddon);
+            console.log('[terminal] WebGL renderer loaded');
+          } catch (e) {
+            console.log('[terminal] WebGL failed, falling back to canvas', e);
+            await applyRenderer('canvas');
+          }
+          break;
+        case 'canvas':
+          try {
+            const module = await import('@xterm/addon-canvas');
+            canvasAddon = new module.CanvasAddon();
+            terminal.loadAddon(canvasAddon);
+            console.log('[terminal] Canvas renderer loaded');
+          } catch (e) {
+            console.log('[terminal] Canvas failed, using DOM', e);
+          }
+          break;
+        case 'dom':
+          console.log('[terminal] DOM renderer loaded');
+          break;
+      }
+    };
+
+    // Helper: Connect WebSocket
+    const connectWebSocket = () => {
+      if (!terminal || !isMounted) return;
+
+      const urlInfo = parseUrl();
+      if (!urlInfo) {
+        onDisconnected?.();
+        return;
+      }
+
+      const { wsFullUrl, token } = urlInfo;
 
-      console.log('[terminal] Connecting to WebSocket...');
+      console.log('[terminal] Creating WebSocket connection...');
       socket = new WebSocket(wsFullUrl, ['tty']);
-      socketRef.current = socket;
       socket.binaryType = 'arraybuffer';
 
-      // WebSocket open handler
       socket.onopen = () => {
+        if (!isMounted) return;
         console.log('[terminal] WebSocket connected');
         setIsConnected(true);
         onConnected?.();
 
         // Send initial message with terminal size
-        // NOTE: ttyd with -a flag authenticates via URL parameter, not AuthToken
-        // But we still send this message for compatibility and terminal size
         const authMsg = JSON.stringify({
           AuthToken: token,
-          columns: terminal.cols,
-          rows: terminal.rows,
+          columns: terminal!.cols,
+          rows: terminal!.rows,
         });
-
-        console.log('[terminal] Sending initial terminal size');
-        socket?.send(textEncoder.current.encode(authMsg));
-
-        terminal.focus();
+        socket?.send(textEncoder.encode(authMsg));
+        terminal!.focus();
       };
 
-      // WebSocket message handler
       socket.onmessage = (event: MessageEvent) => {
+        if (!terminal || !isMounted) return;
+
         const rawData = event.data as ArrayBuffer;
         const cmd = String.fromCharCode(new Uint8Array(rawData)[0]);
         const data = rawData.slice(1);
 
         switch (cmd) {
           case Command.OUTPUT:
-            // Smart scroll behavior:
-            // 1. Check if user is at bottom BEFORE writing
-            const shouldAutoScroll = isAtBottomRef.current;
-
-            // 2. Write output to terminal
+            const shouldAutoScroll = isAtBottom;
             terminal.write(new Uint8Array(data));
 
-            // 3. IMMEDIATELY scroll after write (synchronous)
-            // This is critical for interactive prompts (like Claude Code choices)
-            // that use cursor control sequences - we must scroll IMMEDIATELY
             if (shouldAutoScroll) {
-              // Use requestAnimationFrame to ensure DOM has updated
               requestAnimationFrame(() => {
-                terminal.scrollToBottom();
-
-                // Double-check: if we're still not at bottom, force scroll again
-                // This handles edge cases with complex control sequences
+                terminal?.scrollToBottom();
                 requestAnimationFrame(() => {
-                  if (!isTerminalAtBottom(terminal)) {
+                  if (terminal && !isTerminalAtBottom()) {
                     terminal.scrollToBottom();
                   }
                 });
@@ -505,104 +252,223 @@ export function XtermTerminal({
             }
             break;
           case Command.SET_WINDOW_TITLE:
-            // Set window title
-            const title = textDecoder.current.decode(data);
-            document.title = title;
+            document.title = textDecoder.decode(data);
             break;
           case Command.SET_PREFERENCES:
-            // Handle preferences (not implemented yet)
-            console.log('[terminal] Preferences received:', textDecoder.current.decode(data));
+            console.log('[terminal] Preferences:', textDecoder.decode(data));
             break;
           default:
             console.warn('[terminal] Unknown command:', cmd);
-            break;
         }
       };
 
-      // WebSocket close handler
       socket.onclose = (event: CloseEvent) => {
+        if (!isMounted) return;
+
         console.log('[terminal] WebSocket closed:', event.code, event.reason);
         setIsConnected(false);
-        socketRef.current = null;
+        socket = null;
         onDisconnected?.();
 
-        // Only attempt reconnection if not cleaning up and close was unexpected
-        if (!isCleaningUp && event.code !== 1000) {
-          terminal.write('\r\n\x1b[33m[Connection lost. Reconnecting in 3 seconds...]\x1b[0m\r\n');
-
-          // Auto-reconnect after 3 seconds
-          reconnectTimeoutId = setTimeout(() => {
-            if (!isCleaningUp) {
-              console.log('[terminal] Attempting to reconnect...');
-              connect();
-            }
+        // Auto-reconnect if unexpected close
+        if (event.code !== 1000) {
+          terminal?.write('\r\n\x1b[33m[Connection lost. Reconnecting in 3s...]\x1b[0m\r\n');
+          reconnectTimeout = setTimeout(() => {
+            if (isMounted) connectWebSocket();
           }, 3000);
         } else {
-          terminal.write('\r\n\x1b[31m[Connection closed]\x1b[0m\r\n');
+          terminal?.write('\r\n\x1b[31m[Connection closed]\x1b[0m\r\n');
         }
       };
 
-      // WebSocket error handler
       socket.onerror = (error) => {
         console.error('[terminal] WebSocket error:', error);
       };
     };
 
-    // Initial connection
-    connect();
+    // Main initialization function
+    const init = async () => {
+      try {
+        // Dynamic imports
+        const [xtermModule, fitAddonModule, webLinksModule] = await Promise.all([
+          import('@xterm/xterm'),
+          import('@xterm/addon-fit'),
+          import('@xterm/addon-web-links'),
+        ]);
 
-    // Cleanup function
-    return () => {
-      console.log('[terminal] Cleaning up WebSocket connection');
-      isCleaningUp = true;
+        if (!isMounted || !containerRef.current) return;
+
+        // Create terminal
+        const termOptions: ITerminalOptions = {
+          fontSize,
+          fontFamily,
+          theme: theme || {
+            foreground: '#d2d2d2',
+            background: '#1e1e1e',
+            cursor: '#adadad',
+            black: '#000000',
+            red: '#d81e00',
+            green: '#5ea702',
+            yellow: '#cfae00',
+            blue: '#427ab3',
+            magenta: '#89658e',
+            cyan: '#00a7aa',
+            white: '#dbded8',
+            brightBlack: '#686a66',
+            brightRed: '#f54235',
+            brightGreen: '#99e343',
+            brightYellow: '#fdeb61',
+            brightBlue: '#84b0d8',
+            brightMagenta: '#bc94b7',
+            brightCyan: '#37e6e8',
+            brightWhite: '#f1f1f0',
+          },
+          cursorBlink: true,
+          cursorStyle: 'block',
+          allowProposedApi: true,
+          scrollback: 10000,
+          tabStopWidth: 8,
+        };
 
-      // Clear reconnect timeout if exists
-      if (reconnectTimeoutId) {
-        clearTimeout(reconnectTimeoutId);
-        reconnectTimeoutId = null;
+        terminal = new xtermModule.Terminal(termOptions);
+
+        // Load addons
+        fitAddon = new fitAddonModule.FitAddon();
+        terminal.loadAddon(fitAddon);
+        terminal.loadAddon(new webLinksModule.WebLinksAddon());
+
+        // Open terminal
+        terminal.open(containerRef.current);
+
+        // Fit terminal
+        requestAnimationFrame(() => {
+          if (!isMounted) return;
+          fitAddon?.fit();
+        });
+
+        // Apply renderer
+        requestAnimationFrame(() => {
+          if (!isMounted) return;
+          applyRenderer(rendererType);
+        });
+
+        // Setup event handlers
+        terminal.onData((data) => {
+          if (!isAtBottom) {
+            terminal?.scrollToBottom();
+            isAtBottom = true;
+          }
+          if (hasNewContent) {
+            setHasNewContent(false);
+            setNewLineCount(0);
+          }
+          sendData(data);
+        });
+
+        terminal.onBinary((data) => {
+          if (!isAtBottom) {
+            terminal?.scrollToBottom();
+            isAtBottom = true;
+          }
+          if (hasNewContent) {
+            setHasNewContent(false);
+            setNewLineCount(0);
+          }
+          sendData(Uint8Array.from(data, (v) => v.charCodeAt(0)));
+        });
+
+        terminal.onResize(({ cols, rows }) => {
+          if (socket?.readyState === WebSocket.OPEN) {
+            const msg = JSON.stringify({ columns: cols, rows });
+            socket.send(textEncoder.encode(ClientCommand.RESIZE_TERMINAL + msg));
+          }
+        });
+
+        terminal.onScroll(() => {
+          const wasAtBottom = isAtBottom;
+          const nowAtBottom = isTerminalAtBottom();
+
+          if (wasAtBottom !== nowAtBottom) {
+            isAtBottom = nowAtBottom;
+            if (nowAtBottom && hasNewContent) {
+              setHasNewContent(false);
+              setNewLineCount(0);
+            }
+          }
+        });
+
+        let lineFeedTimeout: NodeJS.Timeout | null = null;
+        terminal.onLineFeed(() => {
+          if (lineFeedTimeout) clearTimeout(lineFeedTimeout);
+          lineFeedTimeout = setTimeout(() => {
+            if (isAtBottom) {
+              terminal?.scrollToBottom();
+            } else {
+              setHasNewContent(true);
+              setNewLineCount((prev) => prev + 1);
+            }
+          }, 10);
+        });
+
+        // Handle window resize
+        const handleResize = () => fitAddon?.fit();
+        window.addEventListener('resize', handleResize);
+
+        // Call onReady callback
+        onReady?.();
+
+        // Connect WebSocket AFTER terminal is fully initialized
+        connectWebSocket();
+
+        console.log('[terminal] Initialization complete');
+      } catch (error) {
+        console.error('[terminal] Initialization failed:', error);
       }
+    };
+
+    // Start initialization
+    init();
+
+    // Cleanup
+    return () => {
+      console.log('[terminal] Cleaning up');
+      isMounted = false;
+
+      if (reconnectTimeout) clearTimeout(reconnectTimeout);
 
-      // Close socket if open
       if (socket) {
-        socket.onclose = null; // Remove handler to prevent reconnect
+        socket.onclose = null;
         socket.onerror = null;
         socket.onmessage = null;
         socket.onopen = null;
-
         if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
           socket.close(1000, 'Component unmounted');
         }
-        socket = null;
-        socketRef.current = null;
       }
 
+      try {
+        webglAddon?.dispose();
+      } catch {}
+      try {
+        canvasAddon?.dispose();
+      } catch {}
+
+      terminal?.dispose();
       setIsConnected(false);
     };
-  }, [wsUrl, onConnected, onDisconnected]); // Only reconnect when wsUrl or callbacks change
+  }, [wsUrl]); // Only re-run when wsUrl changes
 
-  // Handle scroll to bottom button click
+  // Handle scroll to bottom
   const handleScrollToBottom = () => {
-    const terminal = terminalRef.current;
-    if (terminal) {
-      terminal.scrollToBottom();
-      isAtBottomRef.current = true;
-      setHasNewContent(false);
-      setNewLineCount(0);
-    }
+    // This is handled internally now
+    setHasNewContent(false);
+    setNewLineCount(0);
   };
 
   return (
     <div className="relative w-full h-full">
-      {/* Terminal container */}
-      <div
-        ref={containerRef}
-        className="w-full h-full"
-        style={{
-          padding: '5px',
-        }}
-      />
-
-      {/* Scroll to bottom indicator - shows when new content arrives while viewing history */}
+      <div ref={containerRef} className="w-full h-full" style={{ padding: '5px' }} />
+
       {hasNewContent && (
         <button
           onClick={handleScrollToBottom}

From 4b6d433784dadc2764705feed2f331aa55edec54 Mon Sep 17 00:00:00 2001
From: lim <huahua1319873800@outlook.com>
Date: Wed, 12 Nov 2025 05:27:41 +0000
Subject: [PATCH 6/8] chore

---
 components/terminal/xterm-terminal.tsx | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/components/terminal/xterm-terminal.tsx b/components/terminal/xterm-terminal.tsx
index c027c1b..8ab9495 100644
--- a/components/terminal/xterm-terminal.tsx
+++ b/components/terminal/xterm-terminal.tsx
@@ -82,6 +82,7 @@ export function XtermTerminal({
   onDisconnected,
 }: XtermTerminalProps) {
   const containerRef = useRef<HTMLDivElement>(null);
+  const terminalRef = useRef<ITerminal | null>(null); // Expose terminal via ref
   const [isConnected, setIsConnected] = useState(false);
   const [hasNewContent, setHasNewContent] = useState(false);
   const [newLineCount, setNewLineCount] = useState(0);
@@ -331,6 +332,7 @@ export function XtermTerminal({
         };
 
         terminal = new xtermModule.Terminal(termOptions);
+        terminalRef.current = terminal; // Store in ref for external access
 
         // Load addons
         fitAddon = new fitAddonModule.FitAddon();
@@ -454,13 +456,20 @@ export function XtermTerminal({
       } catch {}
 
       terminal?.dispose();
+      terminalRef.current = null; // Clear ref
       setIsConnected(false);
     };
   }, [wsUrl]); // Only re-run when wsUrl changes
 
-  // Handle scroll to bottom
+  // Handle scroll to bottom button click
   const handleScrollToBottom = () => {
-    // This is handled internally now
+    const terminal = terminalRef.current;
+    if (terminal) {
+      // Actually scroll the terminal to bottom
+      terminal.scrollToBottom();
+      console.log('[terminal] User clicked scroll to bottom button');
+    }
+    // Clear the indicator
     setHasNewContent(false);
     setNewLineCount(0);
   };

From 3ee3a2b08df02a71a74e8cf8f82beae3b42b9ee6 Mon Sep 17 00:00:00 2001
From: lim <huahua1319873800@outlook.com>
Date: Wed, 12 Nov 2025 06:32:10 +0000
Subject: [PATCH 7/8] Fixed the bug where deleting STS did not delete PVC.

---
 app/api/projects/route.ts                  |  65 +++++-
 app/projects/page.tsx                      |  11 +-
 components/terminal/terminal-container.tsx |  67 ++++--
 components/terminal/terminal-display.tsx   |  95 +++++---
 components/terminal/xterm-terminal.tsx     | 249 +++++++++++++--------
 hooks/use-projects.ts                      |  62 +++--
 lib/k8s/sandbox-manager.ts                 |  49 ++++
 7 files changed, 417 insertions(+), 181 deletions(-)

diff --git a/app/api/projects/route.ts b/app/api/projects/route.ts
index e071ba5..d54ffeb 100644
--- a/app/api/projects/route.ts
+++ b/app/api/projects/route.ts
@@ -57,21 +57,70 @@ type ProjectWithRelations = Project & {
 type GetProjectsResponse = ProjectWithRelations[]
 
 export const GET = withAuth<GetProjectsResponse>(async (req, _context, session) => {
-  // Get optional namespace filter from query params
+  // Get query parameters for filtering
   const { searchParams } = new URL(req.url)
-  const namespace = searchParams.get('namespace')
+  const allParam = searchParams.get('all')
+  const keywordParam = searchParams.get('keyword')
+  const createdFromParam = searchParams.get('createdFrom')
+  const createdToParam = searchParams.get('createdTo')
 
   // Build where clause
   const whereClause: Prisma.ProjectWhereInput = {
     userId: session.user.id,
   }
 
-  // Add namespace filter if provided (filter projects by sandbox namespace)
-  if (namespace) {
-    whereClause.sandboxes = {
-      some: {
-        k8sNamespace: namespace,
+  // Add keyword filter if provided (searches in both name and description)
+  if (keywordParam) {
+    whereClause.OR = [
+      {
+        name: {
+          contains: keywordParam,
+          mode: 'insensitive',
+        },
+      },
+      {
+        description: {
+          contains: keywordParam,
+          mode: 'insensitive',
+        },
       },
+    ]
+  }
+
+  // Add createdAt date filters if provided
+  const createdAtFilter: { gte?: Date; lte?: Date } = {}
+  if (createdFromParam) {
+    const createdFrom = new Date(createdFromParam)
+    if (!isNaN(createdFrom.getTime())) {
+      createdAtFilter.gte = createdFrom
+    }
+  }
+  if (createdToParam) {
+    const createdTo = new Date(createdToParam)
+    if (!isNaN(createdTo.getTime())) {
+      createdAtFilter.lte = createdTo
+    }
+  }
+  if (Object.keys(createdAtFilter).length > 0) {
+    whereClause.createdAt = createdAtFilter
+  }
+
+  // Add namespace filter from user's kubeconfig (unless 'all' parameter is provided)
+  if (allParam !== 'true') {
+    try {
+      const k8sService = await getK8sServiceForUser(session.user.id)
+      const namespace = k8sService.getDefaultNamespace()
+      whereClause.sandboxes = {
+        some: {
+          k8sNamespace: namespace,
+        },
+      }
+    } catch {
+      // If user doesn't have kubeconfig configured, log warning but don't fail
+      // Return empty array instead of filtering by namespace
+      logger.warn(
+        `User ${session.user.id} does not have KUBECONFIG configured, returning all projects`
+      )
     }
   }
 
@@ -88,7 +137,7 @@ export const GET = withAuth<GetProjectsResponse>(async (req, _context, session)
   })
 
   logger.info(
-    `Fetched ${projects.length} projects for user ${session.user.id}${namespace ? ` in namespace ${namespace}` : ''}`
+    `Fetched ${projects.length} projects for user ${session.user.id}${allParam === 'true' ? ' (all namespaces)' : ''}`
   )
 
   return NextResponse.json(projects)
diff --git a/app/projects/page.tsx b/app/projects/page.tsx
index 5902d57..88d8890 100644
--- a/app/projects/page.tsx
+++ b/app/projects/page.tsx
@@ -12,16 +12,11 @@ import PageHeader from '@/components/features/projectList/PageHeader';
 import ProjectCard from '@/components/features/projectList/ProjectCard';
 import { Spinner } from '@/components/ui/spinner';
 import { useProjects } from '@/hooks/use-projects';
-import { useSealos } from '@/provider/sealos';
 
 export default function ProjectsPage() {
-  const { sealosNs } = useSealos();
-
   // Fetch projects with automatic polling (every 3 seconds)
-  // Pass sealosNs if in Sealos environment for namespace filtering
-  const { data: projects, isLoading } = useProjects({
-    namespace: sealosNs,
-  });
+  // Namespace is automatically determined from user's kubeconfig
+  const { data: projects, isLoading } = useProjects();
 
   if (isLoading) {
     return (
@@ -53,4 +48,4 @@ export default function ProjectsPage() {
       </div>
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/components/terminal/terminal-container.tsx b/components/terminal/terminal-container.tsx
index 73b9586..72aed35 100644
--- a/components/terminal/terminal-container.tsx
+++ b/components/terminal/terminal-container.tsx
@@ -1,9 +1,14 @@
 /**
  * TerminalContainer Component
  *
- * Main container that combines toolbar and display
- * Manages tab state and renders separate terminal instances for each tab
- * Each tab gets its own iframe with independent WebSocket connection
+ * Root container component that manages terminal tabs and combines toolbar with display area.
+ * Implements multi-tab functionality where each tab maintains an independent terminal instance.
+ *
+ * Architecture:
+ * - Tab state management (add, close, switch)
+ * - Renders all tabs but only shows the active one (maintains state)
+ * - Passes project and sandbox data to child components
+ * - Each tab gets unique terminal instance with independent WebSocket
  */
 
 'use client';
@@ -14,6 +19,10 @@ import type { Prisma } from '@prisma/client';
 import { TerminalDisplay } from './terminal-display';
 import { type Tab, TerminalToolbar } from './terminal-toolbar';
 
+// ============================================================================
+// Types
+// ============================================================================
+
 type Project = Prisma.ProjectGetPayload<{
   include: {
     sandboxes: true;
@@ -24,24 +33,31 @@ type Project = Prisma.ProjectGetPayload<{
 type Sandbox = Prisma.SandboxGetPayload<object>;
 
 export interface TerminalContainerProps {
-  /** Project data */
   project: Project;
-  /** Sandbox data */
   sandbox: Sandbox | undefined;
 }
 
-/**
- * Terminal container with toolbar and display
- * Renders separate terminal instances for each tab to ensure independent WebSocket connections
- */
+// ============================================================================
+// Component
+// ============================================================================
+
 export function TerminalContainer({ project, sandbox }: TerminalContainerProps) {
-  // Tab management
+  // =========================================================================
+  // Tab State Management
+  // =========================================================================
+
   const [tabs, setTabs] = useState<Tab[]>([{ id: '1', name: 'Terminal 1' }]);
   const [activeTabId, setActiveTabId] = useState('1');
 
-  // Tab operations
+  // =========================================================================
+  // Tab Operations
+  // =========================================================================
+
+  /**
+   * Create and activate a new terminal tab
+   */
   const handleTabAdd = () => {
-    const newId = Date.now().toString(); // Use timestamp for unique ID
+    const newId = Date.now().toString();
     const newTab: Tab = {
       id: newId,
       name: `Terminal ${tabs.length + 1}`,
@@ -50,24 +66,36 @@ export function TerminalContainer({ project, sandbox }: TerminalContainerProps)
     setActiveTabId(newId);
   };
 
+  /**
+   * Close a terminal tab
+   * Maintains at least one tab and switches to first tab if closing active tab
+   */
   const handleTabClose = (id: string) => {
-    if (tabs.length === 1) return; // Keep at least one terminal
+    if (tabs.length === 1) return;
 
-    const newTabs = tabs.filter((t) => t.id !== id);
-    setTabs(newTabs);
+    const remainingTabs = tabs.filter((t) => t.id !== id);
+    setTabs(remainingTabs);
 
+    // Switch to first tab if we're closing the active tab
     if (activeTabId === id) {
-      setActiveTabId(newTabs[0].id);
+      setActiveTabId(remainingTabs[0].id);
     }
   };
 
+  /**
+   * Switch to a different tab
+   */
   const handleTabSelect = (id: string) => {
     setActiveTabId(id);
   };
 
+  // =========================================================================
+  // Render
+  // =========================================================================
+
   return (
     <div className="flex flex-col h-full bg-[#1e1e1e]">
-      {/* Toolbar */}
+      {/* Toolbar with tabs and operations */}
       <TerminalToolbar
         project={project}
         sandbox={sandbox}
@@ -78,7 +106,7 @@ export function TerminalContainer({ project, sandbox }: TerminalContainerProps)
         onTabAdd={handleTabAdd}
       />
 
-      {/* Terminal Displays - render all tabs but only show active one */}
+      {/* Terminal display area with tab switching */}
       <div className="flex-1 bg-black relative">
         {tabs.map((tab) => (
           <div
@@ -88,6 +116,7 @@ export function TerminalContainer({ project, sandbox }: TerminalContainerProps)
               display: tab.id === activeTabId ? 'block' : 'none',
             }}
           >
+            {/* Each tab maintains its own terminal instance */}
             <TerminalDisplay
               key={tab.id}
               ttydUrl={sandbox?.ttydUrl}
@@ -99,4 +128,4 @@ export function TerminalContainer({ project, sandbox }: TerminalContainerProps)
       </div>
     </div>
   );
-}
+}
\ No newline at end of file
diff --git a/components/terminal/terminal-display.tsx b/components/terminal/terminal-display.tsx
index 5c803d2..4da0477 100644
--- a/components/terminal/terminal-display.tsx
+++ b/components/terminal/terminal-display.tsx
@@ -1,8 +1,14 @@
 /**
  * TerminalDisplay Component
  *
- * Display component for xterm.js terminal (no iframe)
- * Direct WebSocket connection to ttyd backend
+ * Wrapper component for XtermTerminal that manages connection states and loading UI.
+ * Displays appropriate status messages when terminal is not ready or sandbox is not running.
+ *
+ * Features:
+ * - Loading overlays during initialization and connection
+ * - Status-based conditional rendering
+ * - Connection status indicators
+ * - Automatic reconnection feedback
  */
 
 'use client';
@@ -21,58 +27,74 @@ import { cn } from '@/lib/utils';
 
 import { XtermTerminal } from './xterm-terminal';
 
+// ============================================================================
+// Types
+// ============================================================================
+
 export interface TerminalDisplayProps {
-  /** ttyd URL with authentication token */
   ttydUrl?: string | null;
-  /** Sandbox status */
   status: string;
-  /** Unique tab ID for this terminal instance */
   tabId: string;
 }
 
-/**
- * Display xterm.js terminal with direct WebSocket connection
- * Each terminal tab gets independent WebSocket connection
- */
+type ConnectionStatus = 'connecting' | 'connected' | 'error';
+
+// ============================================================================
+// Component
+// ============================================================================
+
 export function TerminalDisplay({ ttydUrl, status, tabId }: TerminalDisplayProps) {
+  // =========================================================================
+  // State Management
+  // =========================================================================
+
   const [terminalReady, setTerminalReady] = useState(false);
-  const [connectionStatus, setConnectionStatus] = useState<'connecting' | 'connected' | 'error'>(
-    'connecting'
-  );
+  const [connectionStatus, setConnectionStatus] = useState<ConnectionStatus>('connecting');
+
+  // =========================================================================
+  // Event Handlers
+  // =========================================================================
 
-  // Stable callback functions to prevent unnecessary re-renders of XtermTerminal
   const handleReady = useCallback(() => {
-    console.log('[TerminalDisplay] Terminal ready');
+    console.log('[TerminalDisplay] Terminal initialized successfully');
     setTerminalReady(true);
   }, []);
 
   const handleConnected = useCallback(() => {
-    console.log('[TerminalDisplay] Terminal WebSocket connected');
+    console.log('[TerminalDisplay] WebSocket connection established');
     setConnectionStatus('connected');
   }, []);
 
   const handleDisconnected = useCallback(() => {
-    console.log('[TerminalDisplay] Terminal WebSocket disconnected');
+    console.log('[TerminalDisplay] WebSocket connection closed');
     setConnectionStatus('connecting');
   }, []);
 
-  // Only show terminal if status is RUNNING and ttyd URL is available
+  // =========================================================================
+  // Conditional Rendering Logic
+  // =========================================================================
+
+  // Only render terminal when sandbox is running and ttyd URL is available
   if (status === 'RUNNING' && ttydUrl) {
+    const isLoading = connectionStatus === 'connecting' || !terminalReady;
+    const showReconnectIndicator = connectionStatus === 'connecting' && terminalReady;
+    const showErrorIndicator = connectionStatus === 'error' && terminalReady;
+
     return (
       <div className="h-full w-full bg-[#1e1e1e] flex flex-col relative">
-        {/* Loading overlay - show until terminal is ready and connected */}
-        {(connectionStatus === 'connecting' || !terminalReady) && (
+        {/* Loading Overlay */}
+        {isLoading && (
           <div className="absolute inset-0 bg-[#1e1e1e] flex items-center justify-center z-10">
             <div className="flex items-center gap-3">
               <Spinner className="h-5 w-5 text-[#3794ff]" />
               <span className="text-sm text-[#cccccc]">
-                {!terminalReady ? 'Loading terminal...' : 'Connecting to terminal...'}
+                {!terminalReady ? 'Initializing terminal...' : 'Establishing connection...'}
               </span>
             </div>
           </div>
         )}
 
-        {/* XTerm Terminal Component */}
+        {/* Terminal Instance */}
         <div className="flex-1 w-full">
           <XtermTerminal
             key={`xterm-${tabId}`}
@@ -107,36 +129,41 @@ export function TerminalDisplay({ ttydUrl, status, tabId }: TerminalDisplayProps
           />
         </div>
 
-        {/* Connection status indicator (optional, can be removed) */}
-        {connectionStatus === 'connecting' && terminalReady && (
+        {/* Connection Status Indicators */}
+        {showReconnectIndicator && (
           <div className="absolute top-2 right-2 bg-yellow-500/10 border border-yellow-500/30 rounded px-2 py-1 flex items-center gap-2">
             <Spinner className="h-3 w-3 text-yellow-500" />
             <span className="text-xs text-yellow-500">Reconnecting...</span>
           </div>
         )}
-        {connectionStatus === 'error' && terminalReady && (
+
+        {showErrorIndicator && (
           <div className="absolute top-2 right-2 bg-red-500/10 border border-red-500/30 rounded px-2 py-1 flex items-center gap-2">
             <AlertCircle className="h-3 w-3 text-red-500" />
-            <span className="text-xs text-red-500">Connection error</span>
+            <span className="text-xs text-red-500">Connection failed</span>
           </div>
         )}
       </div>
     );
   }
 
-  // Show status message for non-running states
+  // =========================================================================
+  // Status Message Display
+  // =========================================================================
+
+  // Show appropriate status message when terminal is not available
+  const StatusIcon = shouldShowSpinner(status)
+    ? Spinner
+    : isErrorStatus(status)
+      ? AlertCircle
+      : TerminalIcon;
+
   return (
     <div className="h-full w-full bg-[#1e1e1e] flex items-center justify-center">
       <div className="flex items-center gap-3">
-        {shouldShowSpinner(status) ? (
-          <Spinner className={cn('h-5 w-5', getStatusIconColor(status))} />
-        ) : isErrorStatus(status) ? (
-          <AlertCircle className={cn('h-5 w-5', getStatusIconColor(status))} />
-        ) : (
-          <TerminalIcon className={cn('h-5 w-5', getStatusIconColor(status))} />
-        )}
+        <StatusIcon className={cn('h-5 w-5', getStatusIconColor(status))} />
         <span className="text-sm text-[#cccccc]">{getStatusMessage(status)}</span>
       </div>
     </div>
   );
-}
+}
\ No newline at end of file
diff --git a/components/terminal/xterm-terminal.tsx b/components/terminal/xterm-terminal.tsx
index 8ab9495..7d996b0 100644
--- a/components/terminal/xterm-terminal.tsx
+++ b/components/terminal/xterm-terminal.tsx
@@ -1,24 +1,32 @@
 /**
  * XtermTerminal Component
  *
- * Core xterm.js terminal component with WebSocket connection to ttyd backend
- * Based on ttyd's frontend implementation with proper SSR handling
+ * Terminal component built with xterm.js, supporting WebSocket connection to ttyd backend.
+ * Implements dynamic imports for SSR compatibility and proper lifecycle management.
+ *
+ * Features:
+ * - SSR-safe dynamic module loading
+ * - WebSocket auto-reconnection
+ * - Smart scroll behavior with indicator
+ * - Multiple renderer support (WebGL, Canvas, DOM)
+ * - Proper cleanup and memory management
  */
 
 'use client';
 
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { ITerminalOptions, Terminal as ITerminal } from '@xterm/xterm';
 
-// Import xterm CSS at component level (safe for SSR)
 import '@xterm/xterm/css/xterm.css';
 
-// Type declarations for dynamically imported modules
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
 type FitAddon = import('@xterm/addon-fit').FitAddon;
 type WebglAddon = import('@xterm/addon-webgl').WebglAddon;
 type CanvasAddon = import('@xterm/addon-canvas').CanvasAddon;
 
-// Command types matching ttyd protocol
 enum Command {
   OUTPUT = '0',
   SET_WINDOW_TITLE = '1',
@@ -33,9 +41,7 @@ enum ClientCommand {
 }
 
 export interface XtermTerminalProps {
-  /** WebSocket URL for ttyd connection */
   wsUrl: string;
-  /** Terminal theme */
   theme?: {
     foreground?: string;
     background?: string;
@@ -57,20 +63,18 @@ export interface XtermTerminalProps {
     brightCyan?: string;
     brightWhite?: string;
   };
-  /** Font size */
   fontSize?: number;
-  /** Font family */
   fontFamily?: string;
-  /** Renderer type */
   rendererType?: 'dom' | 'canvas' | 'webgl';
-  /** Callback when terminal is ready */
   onReady?: () => void;
-  /** Callback when connection opens */
   onConnected?: () => void;
-  /** Callback when connection closes */
   onDisconnected?: () => void;
 }
 
+// ============================================================================
+// Component
+// ============================================================================
+
 export function XtermTerminal({
   wsUrl,
   theme,
@@ -81,17 +85,90 @@ export function XtermTerminal({
   onConnected,
   onDisconnected,
 }: XtermTerminalProps) {
+  // =========================================================================
+  // State & Refs
+  // =========================================================================
+
   const containerRef = useRef<HTMLDivElement>(null);
-  const terminalRef = useRef<ITerminal | null>(null); // Expose terminal via ref
-  const [isConnected, setIsConnected] = useState(false);
+  const terminalRef = useRef<ITerminal | null>(null);
+  const hasNewContentRef = useRef(false);
+  const newLineCountRef = useRef(0);
+
   const [hasNewContent, setHasNewContent] = useState(false);
   const [newLineCount, setNewLineCount] = useState(0);
 
-  // Single useEffect to manage entire component lifecycle
+  // =========================================================================
+  // Memoized Configuration
+  // =========================================================================
+
+  const terminalOptions: ITerminalOptions = useMemo(
+    () => ({
+      fontSize,
+      fontFamily,
+      theme: theme || {
+        foreground: '#d2d2d2',
+        background: '#1e1e1e',
+        cursor: '#adadad',
+        black: '#000000',
+        red: '#d81e00',
+        green: '#5ea702',
+        yellow: '#cfae00',
+        blue: '#427ab3',
+        magenta: '#89658e',
+        cyan: '#00a7aa',
+        white: '#dbded8',
+        brightBlack: '#686a66',
+        brightRed: '#f54235',
+        brightGreen: '#99e343',
+        brightYellow: '#fdeb61',
+        brightBlue: '#84b0d8',
+        brightMagenta: '#bc94b7',
+        brightCyan: '#37e6e8',
+        brightWhite: '#f1f1f0',
+      },
+      cursorBlink: true,
+      cursorStyle: 'block',
+      allowProposedApi: true,
+      scrollback: 10000,
+      tabStopWidth: 8,
+    }),
+    [fontSize, fontFamily, theme]
+  );
+
+  // =========================================================================
+  // Callbacks
+  // =========================================================================
+
+  const handleScrollToBottom = useCallback(() => {
+    const terminal = terminalRef.current;
+    if (terminal) {
+      terminal.scrollToBottom();
+      console.log('[terminal] User scrolled to bottom');
+    }
+    setHasNewContent(false);
+    setNewLineCount(0);
+  }, []);
+
+  // Wrap callbacks to ensure stability
+  const stableOnReady = useCallback(() => {
+    onReady?.();
+  }, [onReady]);
+
+  const stableOnConnected = useCallback(() => {
+    onConnected?.();
+  }, [onConnected]);
+
+  const stableOnDisconnected = useCallback(() => {
+    onDisconnected?.();
+  }, [onDisconnected]);
+
+  // =========================================================================
+  // Main Effect - Terminal Lifecycle Management
+  // =========================================================================
+
   useEffect(() => {
     if (!containerRef.current || !wsUrl) return;
 
-    // State tracking (using local variables to avoid stale closures)
     let terminal: ITerminal | null = null;
     let fitAddon: FitAddon | null = null;
     let socket: WebSocket | null = null;
@@ -104,7 +181,10 @@ export function XtermTerminal({
     const textEncoder = new TextEncoder();
     const textDecoder = new TextDecoder();
 
-    // Helper: Check if terminal is at bottom
+    // -----------------------------------------------------------------------
+    // Helper: Check if at bottom
+    // -----------------------------------------------------------------------
+
     const isTerminalAtBottom = (): boolean => {
       if (!terminal) return true;
       try {
@@ -116,7 +196,10 @@ export function XtermTerminal({
       }
     };
 
-    // Helper: Parse ttyd URL and extract token
+    // -----------------------------------------------------------------------
+    // Helper: Parse WebSocket URL
+    // -----------------------------------------------------------------------
+
     const parseUrl = (): { wsFullUrl: string; token: string } | null => {
       try {
         const url = new URL(wsUrl);
@@ -139,7 +222,10 @@ export function XtermTerminal({
       }
     };
 
+    // -----------------------------------------------------------------------
     // Helper: Send data to server
+    // -----------------------------------------------------------------------
+
     const sendData = (data: string | Uint8Array) => {
       if (!socket || socket.readyState !== WebSocket.OPEN) return;
 
@@ -156,10 +242,14 @@ export function XtermTerminal({
       }
     };
 
+    // -----------------------------------------------------------------------
     // Helper: Apply renderer
+    // -----------------------------------------------------------------------
+
     const applyRenderer = async (type: 'dom' | 'canvas' | 'webgl') => {
       if (!terminal) return;
 
+      // Cleanup existing renderers
       try {
         webglAddon?.dispose();
         webglAddon = null;
@@ -169,11 +259,12 @@ export function XtermTerminal({
         canvasAddon = null;
       } catch {}
 
+      // Apply new renderer
       switch (type) {
         case 'webgl':
           try {
-            const module = await import('@xterm/addon-webgl');
-            webglAddon = new module.WebglAddon();
+            const { WebglAddon: WebglAddonClass } = await import('@xterm/addon-webgl');
+            webglAddon = new WebglAddonClass();
             terminal.loadAddon(webglAddon);
             console.log('[terminal] WebGL renderer loaded');
           } catch (e) {
@@ -183,8 +274,8 @@ export function XtermTerminal({
           break;
         case 'canvas':
           try {
-            const module = await import('@xterm/addon-canvas');
-            canvasAddon = new module.CanvasAddon();
+            const { CanvasAddon: CanvasAddonClass } = await import('@xterm/addon-canvas');
+            canvasAddon = new CanvasAddonClass();
             terminal.loadAddon(canvasAddon);
             console.log('[terminal] Canvas renderer loaded');
           } catch (e) {
@@ -197,13 +288,16 @@ export function XtermTerminal({
       }
     };
 
+    // -----------------------------------------------------------------------
     // Helper: Connect WebSocket
+    // -----------------------------------------------------------------------
+
     const connectWebSocket = () => {
       if (!terminal || !isMounted) return;
 
       const urlInfo = parseUrl();
       if (!urlInfo) {
-        onDisconnected?.();
+        stableOnDisconnected();
         return;
       }
 
@@ -216,10 +310,8 @@ export function XtermTerminal({
       socket.onopen = () => {
         if (!isMounted) return;
         console.log('[terminal] WebSocket connected');
-        setIsConnected(true);
-        onConnected?.();
+        stableOnConnected();
 
-        // Send initial message with terminal size
         const authMsg = JSON.stringify({
           AuthToken: token,
           columns: terminal!.cols,
@@ -267,11 +359,9 @@ export function XtermTerminal({
         if (!isMounted) return;
 
         console.log('[terminal] WebSocket closed:', event.code, event.reason);
-        setIsConnected(false);
         socket = null;
-        onDisconnected?.();
+        stableOnDisconnected();
 
-        // Auto-reconnect if unexpected close
         if (event.code !== 1000) {
           terminal?.write('\r\n\x1b[33m[Connection lost. Reconnecting in 3s...]\x1b[0m\r\n');
           reconnectTimeout = setTimeout(() => {
@@ -287,10 +377,12 @@ export function XtermTerminal({
       };
     };
 
-    // Main initialization function
+    // -----------------------------------------------------------------------
+    // Main initialization
+    // -----------------------------------------------------------------------
+
     const init = async () => {
       try {
-        // Dynamic imports
         const [xtermModule, fitAddonModule, webLinksModule] = await Promise.all([
           import('@xterm/xterm'),
           import('@xterm/addon-fit'),
@@ -299,56 +391,20 @@ export function XtermTerminal({
 
         if (!isMounted || !containerRef.current) return;
 
-        // Create terminal
-        const termOptions: ITerminalOptions = {
-          fontSize,
-          fontFamily,
-          theme: theme || {
-            foreground: '#d2d2d2',
-            background: '#1e1e1e',
-            cursor: '#adadad',
-            black: '#000000',
-            red: '#d81e00',
-            green: '#5ea702',
-            yellow: '#cfae00',
-            blue: '#427ab3',
-            magenta: '#89658e',
-            cyan: '#00a7aa',
-            white: '#dbded8',
-            brightBlack: '#686a66',
-            brightRed: '#f54235',
-            brightGreen: '#99e343',
-            brightYellow: '#fdeb61',
-            brightBlue: '#84b0d8',
-            brightMagenta: '#bc94b7',
-            brightCyan: '#37e6e8',
-            brightWhite: '#f1f1f0',
-          },
-          cursorBlink: true,
-          cursorStyle: 'block',
-          allowProposedApi: true,
-          scrollback: 10000,
-          tabStopWidth: 8,
-        };
-
-        terminal = new xtermModule.Terminal(termOptions);
-        terminalRef.current = terminal; // Store in ref for external access
-
-        // Load addons
+        terminal = new xtermModule.Terminal(terminalOptions);
+        terminalRef.current = terminal;
+
         fitAddon = new fitAddonModule.FitAddon();
         terminal.loadAddon(fitAddon);
         terminal.loadAddon(new webLinksModule.WebLinksAddon());
 
-        // Open terminal
         terminal.open(containerRef.current);
 
-        // Fit terminal
         requestAnimationFrame(() => {
           if (!isMounted) return;
           fitAddon?.fit();
         });
 
-        // Apply renderer
         requestAnimationFrame(() => {
           if (!isMounted) return;
           applyRenderer(rendererType);
@@ -360,7 +416,9 @@ export function XtermTerminal({
             terminal?.scrollToBottom();
             isAtBottom = true;
           }
-          if (hasNewContent) {
+          if (hasNewContentRef.current) {
+            hasNewContentRef.current = false;
+            newLineCountRef.current = 0;
             setHasNewContent(false);
             setNewLineCount(0);
           }
@@ -372,7 +430,9 @@ export function XtermTerminal({
             terminal?.scrollToBottom();
             isAtBottom = true;
           }
-          if (hasNewContent) {
+          if (hasNewContentRef.current) {
+            hasNewContentRef.current = false;
+            newLineCountRef.current = 0;
             setHasNewContent(false);
             setNewLineCount(0);
           }
@@ -392,7 +452,9 @@ export function XtermTerminal({
 
           if (wasAtBottom !== nowAtBottom) {
             isAtBottom = nowAtBottom;
-            if (nowAtBottom && hasNewContent) {
+            if (nowAtBottom && hasNewContentRef.current) {
+              hasNewContentRef.current = false;
+              newLineCountRef.current = 0;
               setHasNewContent(false);
               setNewLineCount(0);
             }
@@ -406,20 +468,18 @@ export function XtermTerminal({
             if (isAtBottom) {
               terminal?.scrollToBottom();
             } else {
+              hasNewContentRef.current = true;
+              newLineCountRef.current += 1;
               setHasNewContent(true);
-              setNewLineCount((prev) => prev + 1);
+              setNewLineCount(newLineCountRef.current);
             }
           }, 10);
         });
 
-        // Handle window resize
         const handleResize = () => fitAddon?.fit();
         window.addEventListener('resize', handleResize);
 
-        // Call onReady callback
-        onReady?.();
-
-        // Connect WebSocket AFTER terminal is fully initialized
+        stableOnReady();
         connectWebSocket();
 
         console.log('[terminal] Initialization complete');
@@ -428,10 +488,12 @@ export function XtermTerminal({
       }
     };
 
-    // Start initialization
     init();
 
+    // -----------------------------------------------------------------------
     // Cleanup
+    // -----------------------------------------------------------------------
+
     return () => {
       console.log('[terminal] Cleaning up');
       isMounted = false;
@@ -456,23 +518,14 @@ export function XtermTerminal({
       } catch {}
 
       terminal?.dispose();
-      terminalRef.current = null; // Clear ref
-      setIsConnected(false);
+      terminalRef.current = null;
     };
-  }, [wsUrl]); // Only re-run when wsUrl changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [wsUrl]);
 
-  // Handle scroll to bottom button click
-  const handleScrollToBottom = () => {
-    const terminal = terminalRef.current;
-    if (terminal) {
-      // Actually scroll the terminal to bottom
-      terminal.scrollToBottom();
-      console.log('[terminal] User clicked scroll to bottom button');
-    }
-    // Clear the indicator
-    setHasNewContent(false);
-    setNewLineCount(0);
-  };
+  // =========================================================================
+  // Render
+  // =========================================================================
 
   return (
     <div className="relative w-full h-full">
@@ -513,4 +566,4 @@ export function XtermTerminal({
       )}
     </div>
   );
-}
+}
\ No newline at end of file
diff --git a/hooks/use-projects.ts b/hooks/use-projects.ts
index ff1361d..2358753 100644
--- a/hooks/use-projects.ts
+++ b/hooks/use-projects.ts
@@ -4,18 +4,24 @@
  * Provides automatic caching, refetching, and state synchronization
  */
 
-import type { Project } from '@prisma/client';
-import { useQuery } from '@tanstack/react-query';
+import type { Project } from '@prisma/client'
+import { useQuery } from '@tanstack/react-query'
 
-import { GET } from '@/lib/fetch-client';
+import { GET } from '@/lib/fetch-client'
 
 interface UseProjectsOptions {
   /** Enable automatic refetching every 3 seconds */
-  refetchInterval?: number;
+  refetchInterval?: number
   /** Enable refetch on window focus */
-  refetchOnWindowFocus?: boolean;
-  /** Optional namespace filter (for Sealos environment) */
-  namespace?: string | null;
+  refetchOnWindowFocus?: boolean
+  /** Show all projects regardless of namespace */
+  all?: boolean
+  /** Search keyword - matches both name and description (case-insensitive partial match) */
+  keyword?: string
+  /** Filter by creation date - projects created from this date (inclusive) */
+  createdFrom?: string | Date
+  /** Filter by creation date - projects created until this date (inclusive) */
+  createdTo?: string | Date
 }
 
 /**
@@ -25,19 +31,47 @@ interface UseProjectsOptions {
  * @returns Query result with projects list
  */
 export function useProjects(options: UseProjectsOptions = {}) {
-  const { refetchInterval = 3000, refetchOnWindowFocus = false, namespace } = options;
+  const {
+    refetchInterval = 3000,
+    refetchOnWindowFocus = true,
+    all,
+    keyword,
+    createdFrom,
+    createdTo,
+  } = options
+
+  // Build query key for caching
+  const queryKey = ['projects', all, keyword, createdFrom, createdTo]
 
   return useQuery({
-    queryKey: ['projects', namespace],
+    queryKey,
     queryFn: async () => {
-      const url = namespace
-        ? `/api/projects?namespace=${encodeURIComponent(namespace)}`
-        : '/api/projects';
-      return GET<Project[]>(url);
+      const params = new URLSearchParams()
+
+      if (all) {
+        params.append('all', 'true')
+      }
+      if (keyword) {
+        params.append('keyword', keyword)
+      }
+      if (createdFrom) {
+        params.append(
+          'createdFrom',
+          createdFrom instanceof Date ? createdFrom.toISOString() : createdFrom
+        )
+      }
+      if (createdTo) {
+        params.append('createdTo', createdTo instanceof Date ? createdTo.toISOString() : createdTo)
+      }
+
+      const queryString = params.toString()
+      const url = queryString ? `/api/projects?${queryString}` : '/api/projects'
+
+      return GET<Project[]>(url)
     },
     refetchInterval,
     refetchOnWindowFocus,
     staleTime: 2000, // Consider data stale after 2 seconds
     retry: 2,
-  });
+  })
 }
diff --git a/lib/k8s/sandbox-manager.ts b/lib/k8s/sandbox-manager.ts
index b0cc5a5..e84a07a 100644
--- a/lib/k8s/sandbox-manager.ts
+++ b/lib/k8s/sandbox-manager.ts
@@ -151,6 +151,7 @@ export class SandboxManager {
       this.deleteStatefulSet(sandboxName, namespace),
       this.deleteService(sandboxName, namespace),
       this.deleteIngresses(sandboxName, namespace),
+      this.deletePVCs(sandboxName, namespace),
     ])
 
     logger.info(`Sandbox deleted: ${sandboxName}`)
@@ -619,6 +620,12 @@ export class SandboxManager {
           },
         },
         minReadySeconds: 10,
+        // Automatically delete PVCs when StatefulSet is deleted
+        // This prevents orphaned PVCs and storage costs
+        persistentVolumeClaimRetentionPolicy: {
+          whenDeleted: 'Delete', // Delete PVCs when StatefulSet is deleted
+          whenScaled: 'Retain', // Keep PVCs when scaling down (for potential scale-up)
+        },
         template: {
           metadata: {
             labels: {
@@ -1172,4 +1179,46 @@ echo "=== Init Container: Completed successfully ==="
       }
     }
   }
+
+  /**
+   * Delete PVCs associated with a StatefulSet
+   *
+   * StatefulSets create PVCs with names: {volumeClaimTemplate.name}-{statefulset.name}-{ordinal}
+   * For our case: vn-homevn-agent-{sandboxName}-0
+   *
+   * This method handles both:
+   * 1. Clusters with persistentVolumeClaimRetentionPolicy support (Kubernetes 1.23+)
+   * 2. Older clusters where PVCs need manual cleanup
+   *
+   * @param sandboxName - Sandbox name
+   * @param namespace - Kubernetes namespace
+   */
+  private async deletePVCs(sandboxName: string, namespace: string): Promise<void> {
+    try {
+      // List all PVCs in namespace that belong to this StatefulSet
+      // StatefulSet PVC naming: {volumeClaimTemplate.name}-{statefulset.name}-{ordinal}
+      const pvcName = `vn-homevn-agent-${sandboxName}-0`
+
+      try {
+        await this.k8sApi.deleteNamespacedPersistentVolumeClaim({
+          name: pvcName,
+          namespace,
+        })
+        logger.info(`Deleted PVC: ${pvcName}`)
+      } catch (error) {
+        if (isK8sNotFound(error)) {
+          logger.info(
+            `PVC not found (may have been auto-deleted by persistentVolumeClaimRetentionPolicy): ${pvcName}`
+          )
+        } else {
+          throw error
+        }
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      logger.error(`Failed to delete PVCs for sandbox: ${sandboxName} - ${errorMessage}`)
+      // Don't throw - PVC deletion failure shouldn't block sandbox cleanup
+      // The PVCs might have already been deleted by K8s retention policy
+    }
+  }
 }

From 373bc16ae0c31fe89bf51e06f85ec9f480410016 Mon Sep 17 00:00:00 2001
From: limbo <huahua1319873800@outlook.com>
Date: Wed, 12 Nov 2025 14:41:56 +0800
Subject: [PATCH 8/8] Update components/terminal/xterm-terminal.tsx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 components/terminal/xterm-terminal.tsx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/components/terminal/xterm-terminal.tsx b/components/terminal/xterm-terminal.tsx
index 7d996b0..2dd8d45 100644
--- a/components/terminal/xterm-terminal.tsx
+++ b/components/terminal/xterm-terminal.tsx
@@ -230,6 +230,8 @@ export function XtermTerminal({
       if (!socket || socket.readyState !== WebSocket.OPEN) return;
 
       if (typeof data === 'string') {
+        // Allocate buffer for UTF-8 encoding: each character may take up to 3 bytes in UTF-8.
+        // The extra byte (+1) is for the command code at the start of the buffer.
         const payload = new Uint8Array(data.length * 3 + 1);
         payload[0] = ClientCommand.INPUT.charCodeAt(0);
         const stats = textEncoder.encodeInto(data, payload.subarray(1));