From 303755437d0f278318ec49bb17833e4c049f2d04 Mon Sep 17 00:00:00 2001
From: josedario87 <jodarioel87@gmail.com>
Date: Sat, 14 Feb 2026 12:16:34 -0600
Subject: [PATCH] refactor: Extract terminal rendering logic to
 useTerminalRenderer composable

- Create useTerminalRenderer.ts with all xterm.js logic
- Support custom theme, fontSize, fontFamily options
- Add handleReplay() for proper visibility handling
- Add getBufferContent() for copying terminal content
- Refactor FloatingTerminal.vue to use composable
- Refactor TerminalPage.vue to use composable
- Server: Add request-replay message type for on-demand replay
- Server: Remove auto-replay on connect (client requests when ready)
- Fix xterm.js rendering issues with hidden containers (v-show)
---
 frontend/src/components/FloatingTerminal.vue  | 822 ++++++------------
 .../src/composables/useTerminalRenderer.ts    | 491 +++++++++++
 frontend/src/pages/TerminalPage.vue           | 287 ++----
 server/config.ts                              |   2 +-
 server/services/terminal.ts                   |  45 +-
 5 files changed, 877 insertions(+), 770 deletions(-)
 create mode 100644 frontend/src/composables/useTerminalRenderer.ts

diff --git a/frontend/src/components/FloatingTerminal.vue b/frontend/src/components/FloatingTerminal.vue
index 1063632..c791e81 100644
--- a/frontend/src/components/FloatingTerminal.vue
+++ b/frontend/src/components/FloatingTerminal.vue
@@ -1,12 +1,9 @@
 <script setup lang="ts">
 import { ref, onMounted, onBeforeUnmount, nextTick, watch, computed } from 'vue'
-import { Terminal } from '@xterm/xterm'
-import { FitAddon } from '@xterm/addon-fit'
-import { WebLinksAddon } from '@xterm/addon-web-links'
-import '@xterm/xterm/css/xterm.css'
 import { connectWithToken, stopTokenPolling } from '../services/webmcp'
 import { useCanvasStore } from '../stores/canvas'
 import { endpoints } from '../config/endpoints'
+import { useTerminalRenderer } from '../composables/useTerminalRenderer'
 
 const props = defineProps<{
   modelValue: boolean
@@ -23,12 +20,17 @@ const isOpen = computed({
 
 const canvasStore = useCanvasStore()
 
+// ============================================================================
+// REFS
+// ============================================================================
+
 const terminalContainer = ref<HTMLElement | null>(null)
 const terminalRef = ref<HTMLElement | null>(null)
 const connected = ref(false)
 const connecting = ref(false)
 const sessionId = ref<string | null>(null)
 
+// Drag state
 const isDragging = ref(false)
 const position = ref({ x: 0, y: 0 })
 const hasCustomPosition = ref(false)
@@ -40,44 +42,90 @@ const size = ref({ w: 580, h: 360 })
 
 // Mobile bottom sheet state
 const isMobile = ref(false)
-const sheetHeight = ref(55) // percentage of viewport
+const sheetHeight = ref(55)
 const isDraggingSheet = ref(false)
 const sheetDragStart = ref({ y: 0, height: 0 })
 const keyboardHeight = ref(0)
-const snapPoints = [20, 55, 85] // collapsed, half, full (percentages)
+const snapPoints = [20, 55, 85]
 
-let terminal: Terminal | null = null
-let fitAddon: FitAddon | null = null
+// WebSocket
 let socket: WebSocket | null = null
-let resizeObserver: ResizeObserver | null = null
 let reconnectTimeout: number | null = null
 let reconnectAttempts = 0
 const MAX_RECONNECT_ATTEMPTS = 10
 const RECONNECT_DELAY_MS = 2000
 
-// Buffer for detecting WebMCP token
+// Token detection
 let tokenBuffer = ''
 let tokenTimeout: number | null = null
 const waitingForToken = ref(false)
 
 const WS_URL = endpoints.terminal
 
-// Mouse position tracking for Ctrl+E
+// Mouse tracking for Ctrl+E
 const mousePos = ref({ x: 0, y: 0 })
 let lastToggle = 0
 
-function trackMouse(e: MouseEvent) {
-  mousePos.value = { x: e.clientX, y: e.clientY }
-}
+// ============================================================================
+// TERMINAL RENDERER (composable)
+// ============================================================================
+
+const renderer = useTerminalRenderer({
+  container: terminalContainer,
+  onData: (data) => {
+    // Send user input to server
+    if (socket && socket.readyState === WebSocket.OPEN) {
+      socket.send(JSON.stringify({ type: 'input', data }))
+    }
+  },
+  onResize: (cols, rows) => {
+    // Notify server of resize
+    if (socket && socket.readyState === WebSocket.OPEN) {
+      socket.send(JSON.stringify({ type: 'resize', cols, rows }))
+    }
+  },
+  onKeyEvent: (e) => {
+    // Ctrl+E: Toggle terminal
+    if (e.ctrlKey && e.key === 'e') {
+      e.preventDefault()
+      toggleTerminal()
+      return false
+    }
+
+    // Ctrl+V: Paste from clipboard
+    if (e.ctrlKey && e.key === 'v' && e.type === 'keydown') {
+      e.preventDefault()
+      navigator.clipboard.readText().then((text) => {
+        if (text && socket && socket.readyState === WebSocket.OPEN) {
+          socket.send(JSON.stringify({ type: 'input', data: text }))
+        }
+      }).catch(console.error)
+      return false
+    }
+
+    // Ctrl+C: Copy selection (if any)
+    if (e.ctrlKey && e.key === 'c' && e.type === 'keydown') {
+      const selection = renderer.getSelection()
+      if (selection) {
+        navigator.clipboard.writeText(selection).catch(console.error)
+        return false
+      }
+    }
+
+    return true
+  }
+})
+
+// ============================================================================
+// MOBILE DETECTION
+// ============================================================================
 
-// Mobile/tablet detection - show virtual keys on touch devices
 function checkMobile() {
   const isTouchDevice = 'ontouchstart' in window || navigator.maxTouchPoints > 0
   const isSmallScreen = window.innerWidth <= 1024
   isMobile.value = isTouchDevice && isSmallScreen
 }
 
-// Virtual keyboard detection using visualViewport API
 function setupKeyboardDetection() {
   if (window.visualViewport) {
     window.visualViewport.addEventListener('resize', handleViewportResize)
@@ -91,10 +139,8 @@ function handleViewportResize() {
   const windowHeight = window.innerHeight
   const diff = windowHeight - viewportHeight
 
-  // If difference > 100px, keyboard is probably open
   if (diff > 100) {
     keyboardHeight.value = diff
-    // Auto-expand sheet when keyboard opens if it's too small
     if (sheetHeight.value < 55 && isOpen.value) {
       sheetHeight.value = 55
     }
@@ -103,58 +149,56 @@ function handleViewportResize() {
   }
 }
 
-// Find nearest snap point
 function findNearestSnap(height: number): number {
   return snapPoints.reduce((prev, curr) =>
     Math.abs(curr - height) < Math.abs(prev - height) ? curr : prev
   )
 }
 
-// Mobile sheet touch handlers
+// ============================================================================
+// MOBILE SHEET DRAG
+// ============================================================================
+
 function startSheetDrag(e: TouchEvent) {
   if (!isMobile.value) return
-
   const touch = e.touches[0]
   if (!touch) return
 
   isDraggingSheet.value = true
-  sheetDragStart.value = {
-    y: touch.clientY,
-    height: sheetHeight.value
-  }
+  sheetDragStart.value = { y: touch.clientY, height: sheetHeight.value }
 }
 
 function onSheetDrag(e: TouchEvent) {
   if (!isDraggingSheet.value || !isMobile.value) return
-
   const touch = e.touches[0]
   if (!touch) return
 
   const deltaY = sheetDragStart.value.y - touch.clientY
   const deltaPercent = (deltaY / window.innerHeight) * 100
-  const newHeight = sheetDragStart.value.height + deltaPercent
-
-  // Clamp between 15% and 90%
-  sheetHeight.value = Math.max(15, Math.min(90, newHeight))
+  sheetHeight.value = Math.max(15, Math.min(90, sheetDragStart.value.height + deltaPercent))
 }
 
 function stopSheetDrag() {
   if (!isDraggingSheet.value) return
-
   isDraggingSheet.value = false
-  // Snap to nearest point
   sheetHeight.value = findNearestSnap(sheetHeight.value)
+  nextTick(() => renderer.fit())
+}
 
-  nextTick(() => fitAddon?.fit())
+// ============================================================================
+// WINDOW DRAG
+// ============================================================================
+
+function trackMouse(e: MouseEvent) {
+  mousePos.value = { x: e.clientX, y: e.clientY }
 }
 
 function toggleTerminal() {
   const now = Date.now()
-  if (now - lastToggle < 150) return // Debounce 150ms
+  if (now - lastToggle < 150) return
   lastToggle = now
 
   if (!isOpen.value) {
-    // Open at mouse position (allow 75% occlusion)
     const w = size.value.w
     const h = size.value.h
     const minX = -w * 0.75
@@ -182,11 +226,8 @@ function handleKeydown(e: KeyboardEvent) {
 function startDrag(e: MouseEvent | TouchEvent) {
   if ((e.target as HTMLElement).closest('.window-controls')) return
 
-  // On mobile, use sheet drag instead
   if (isMobile.value) {
-    if (e instanceof TouchEvent) {
-      startSheetDrag(e)
-    }
+    if (e instanceof TouchEvent) startSheetDrag(e)
     return
   }
 
@@ -197,14 +238,10 @@ function startDrag(e: MouseEvent | TouchEvent) {
   const clientY = e instanceof MouseEvent ? e.clientY : (touch?.clientY ?? 0)
 
   if (rect) {
-    // Capture actual position if using default bottom/right
     if (!hasCustomPosition.value) {
       position.value = { x: rect.left, y: rect.top }
     }
-    dragOffset.value = {
-      x: clientX - rect.left,
-      y: clientY - rect.top
-    }
+    dragOffset.value = { x: clientX - rect.left, y: clientY - rect.top }
   }
 
   document.addEventListener('mousemove', onDrag)
@@ -215,30 +252,22 @@ function startDrag(e: MouseEvent | TouchEvent) {
 
 function onDrag(e: MouseEvent | TouchEvent) {
   if (!isDragging.value) return
-
-  if (e instanceof TouchEvent) {
-    e.preventDefault()
-  }
+  if (e instanceof TouchEvent) e.preventDefault()
 
   const touch = e instanceof TouchEvent ? e.touches[0] : null
   const clientX = e instanceof MouseEvent ? e.clientX : (touch?.clientX ?? 0)
   const clientY = e instanceof MouseEvent ? e.clientY : (touch?.clientY ?? 0)
 
-  const newX = clientX - dragOffset.value.x
-  const newY = clientY - dragOffset.value.y
-
   const w = terminalRef.value?.offsetWidth || 580
   const h = terminalRef.value?.offsetHeight || 360
-
-  // Allow up to 75% occlusion per side (25% must remain visible)
   const minX = -w * 0.75
   const maxX = window.innerWidth - w * 0.25
   const minY = -h * 0.75
   const maxY = window.innerHeight - h * 0.25
 
   position.value = {
-    x: Math.max(minX, Math.min(newX, maxX)),
-    y: Math.max(minY, Math.min(newY, maxY))
+    x: Math.max(minX, Math.min(clientX - dragOffset.value.x, maxX)),
+    y: Math.max(minY, Math.min(clientY - dragOffset.value.y, maxY))
   }
 }
 
@@ -251,32 +280,26 @@ function stopDrag() {
   document.removeEventListener('touchend', stopDrag)
 }
 
-// Resize functions
+// ============================================================================
+// WINDOW RESIZE
+// ============================================================================
+
 const resizeStart = ref({ x: 0, y: 0, w: 0, h: 0 })
 
 function startResize(e: MouseEvent) {
   e.preventDefault()
   e.stopPropagation()
   isResizing.value = true
-  resizeStart.value = {
-    x: e.clientX,
-    y: e.clientY,
-    w: size.value.w,
-    h: size.value.h
-  }
+  resizeStart.value = { x: e.clientX, y: e.clientY, w: size.value.w, h: size.value.h }
   document.addEventListener('mousemove', onResize)
   document.addEventListener('mouseup', stopResize)
 }
 
 function onResize(e: MouseEvent) {
   if (!isResizing.value) return
-
-  const deltaX = e.clientX - resizeStart.value.x
-  const deltaY = e.clientY - resizeStart.value.y
-
   size.value = {
-    w: Math.max(400, Math.min(resizeStart.value.w + deltaX, window.innerWidth - 40)),
-    h: Math.max(250, Math.min(resizeStart.value.h + deltaY, window.innerHeight - 40))
+    w: Math.max(400, Math.min(resizeStart.value.w + e.clientX - resizeStart.value.x, window.innerWidth - 40)),
+    h: Math.max(250, Math.min(resizeStart.value.h + e.clientY - resizeStart.value.y, window.innerHeight - 40))
   }
 }
 
@@ -284,18 +307,17 @@ function stopResize() {
   isResizing.value = false
   document.removeEventListener('mousemove', onResize)
   document.removeEventListener('mouseup', stopResize)
-  nextTick(() => fitAddon?.fit())
+  nextTick(() => renderer.fit())
 }
 
-const terminalStyle = computed((): Record<string, string> => {
-  // Mobile: bottom sheet with dynamic height
-  if (isMobile.value) {
-    // When keyboard is open, position above it
-    const bottomOffset = keyboardHeight.value > 0 ? `${keyboardHeight.value}px` : '0'
-    const maxH = keyboardHeight.value > 0
-      ? `calc(100vh - ${keyboardHeight.value}px)`
-      : '90vh'
+// ============================================================================
+// TERMINAL STYLE
+// ============================================================================
 
+const terminalStyle = computed((): Record<string, string> => {
+  if (isMobile.value) {
+    const bottomOffset = keyboardHeight.value > 0 ? `${keyboardHeight.value}px` : '0'
+    const maxH = keyboardHeight.value > 0 ? `calc(100vh - ${keyboardHeight.value}px)` : '90vh'
     return {
       position: 'fixed',
       left: '0',
@@ -307,7 +329,6 @@ const terminalStyle = computed((): Record<string, string> => {
     }
   }
 
-  // Desktop: floating window
   if (!hasCustomPosition.value) {
     return {
       width: `${size.value.w}px`,
@@ -326,108 +347,14 @@ const terminalStyle = computed((): Record<string, string> => {
   }
 })
 
-function initTerminal() {
-  if (!terminalContainer.value || terminal) return
-
-  terminal = new Terminal({
-    cursorBlink: true,
-    cursorStyle: 'block',
-    fontSize: 12,
-    fontFamily: "'Consolas', 'Lucida Console', monospace",
-    theme: {
-      background: 'rgba(12, 12, 12, 0.95)',
-      foreground: '#ffffff',
-      cursor: '#ffffff',
-      cursorAccent: '#000000',
-      selectionBackground: 'rgba(100, 150, 255, 0.4)',
-      black: '#0c0c0c',
-      red: '#c50f1f',
-      green: '#13a10e',
-      yellow: '#c19c00',
-      blue: '#0037da',
-      magenta: '#881798',
-      cyan: '#3a96dd',
-      white: '#cccccc',
-      brightBlack: '#767676',
-      brightRed: '#e74856',
-      brightGreen: '#16c60c',
-      brightYellow: '#f9f1a5',
-      brightBlue: '#3b78ff',
-      brightMagenta: '#b4009e',
-      brightCyan: '#61d6d6',
-      brightWhite: '#f2f2f2'
-    },
-    allowProposedApi: true
-  })
-
-  fitAddon = new FitAddon()
-  terminal.loadAddon(fitAddon)
-  terminal.loadAddon(new WebLinksAddon())
-  terminal.open(terminalContainer.value)
-
-  nextTick(() => fitAddon?.fit())
-
-  resizeObserver = new ResizeObserver(() => {
-    if (fitAddon && terminal) {
-      fitAddon.fit()
-      if (socket && socket.readyState === WebSocket.OPEN) {
-        socket.send(JSON.stringify({
-          type: 'resize',
-          cols: terminal.cols,
-          rows: terminal.rows
-        }))
-      }
-    }
-  })
-  resizeObserver.observe(terminalContainer.value)
-
-  terminal.onData((data) => {
-    if (socket && socket.readyState === WebSocket.OPEN) {
-      socket.send(JSON.stringify({ type: 'input', data }))
-    }
-  })
-
-  // Capture Ctrl+E and Ctrl+V when terminal has focus
-  terminal.attachCustomKeyEventHandler((e) => {
-    // Ctrl+E: Toggle terminal
-    if (e.ctrlKey && e.key === 'e') {
-      e.preventDefault()
-      toggleTerminal()
-      return false
-    }
-
-    // Ctrl+V: Paste from clipboard
-    if (e.ctrlKey && e.key === 'v' && e.type === 'keydown') {
-      e.preventDefault()
-      navigator.clipboard.readText().then((text) => {
-        if (text && socket && socket.readyState === WebSocket.OPEN) {
-          socket.send(JSON.stringify({ type: 'input', data: text }))
-        }
-      }).catch((err) => {
-        console.error('[Terminal] Clipboard read failed:', err)
-      })
-      return false
-    }
-
-    // Ctrl+C: Copy selection (if any)
-    if (e.ctrlKey && e.key === 'c' && e.type === 'keydown') {
-      const selection = terminal?.getSelection()
-      if (selection) {
-        navigator.clipboard.writeText(selection).catch(console.error)
-        return false
-      }
-      // If no selection, let Ctrl+C pass through as SIGINT
-    }
-
-    return true // Let terminal handle other keys
-  })
-}
+// ============================================================================
+// WEBSOCKET CONNECTION
+// ============================================================================
 
 async function connect() {
   if (connecting.value || connected.value) return
   connecting.value = true
 
-  // Connection timeout - if not connected in 10s, retry
   const connectionTimeout = window.setTimeout(() => {
     if (connecting.value && !connected.value) {
       console.log('[Terminal] Connection timeout, retrying...')
@@ -442,72 +369,72 @@ async function connect() {
 
   try {
     socket = new WebSocket(WS_URL)
-
-    // Clear timeout on successful connection
     socket.addEventListener('open', () => clearTimeout(connectionTimeout), { once: true })
 
     socket.onopen = () => {
       connected.value = true
       connecting.value = false
-      reconnectAttempts = 0 // Reset on successful connection
-      terminal?.focus()
-      if (terminal) {
-        socket?.send(JSON.stringify({
-          type: 'resize',
-          cols: terminal.cols,
-          rows: terminal.rows
-        }))
+      reconnectAttempts = 0
+      renderer.focus()
+
+      // Send initial resize
+      const term = renderer.terminal.value
+      if (term) {
+        socket?.send(JSON.stringify({ type: 'resize', cols: term.cols, rows: term.rows }))
       }
     }
 
-    socket.onmessage = (event) => {
+    socket.onmessage = async (event) => {
       const msg = JSON.parse(event.data)
+
       if (msg.type === 'connected') {
         sessionId.value = msg.sessionId
-        if (!msg.isNew) {
-          terminal?.write('\x1b[36m[Reconnected]\x1b[0m\r\n')
+        console.log('[Terminal] Connected, hasHistory:', msg.hasHistory, 'bufferSize:', msg.bufferSize)
+
+        // Request replay if there's history and terminal is visible
+        if (msg.hasHistory && isOpen.value) {
+          console.log('[Terminal] Requesting replay after connect...')
+          setTimeout(() => requestReplay(), 50)
+        } else if (!msg.isNew) {
+          renderer.writeln('\x1b[36m[Session restored]\x1b[0m')
         }
       } else if (msg.type === 'replay') {
-        terminal?.write(msg.data)
+        console.log('[Terminal] Received replay, length:', msg.data?.length)
+        // USE THE COMPOSABLE'S handleReplay!
+        await renderer.handleReplay(msg.data || '')
       } else if (msg.type === 'output') {
-        // Only detect token when waiting for it
+        // Token detection
         if (waitingForToken.value) {
           tokenBuffer += msg.data
-
-          // Debounce: process buffer after output stops (300ms)
           if (tokenTimeout) clearTimeout(tokenTimeout)
           tokenTimeout = window.setTimeout(() => {
             if (tokenBuffer.includes('Token copiado')) {
-              // Clean ANSI codes and whitespace
               const clean = tokenBuffer.replace(/\x1b\[[0-9;]*m/g, '').replace(/[\r\n\s]/g, '')
               const match = clean.match(/eyJ[A-Za-z0-9_\-+/=]+/)
               if (match) {
                 try {
                   const decoded = atob(match[0])
                   JSON.parse(decoded)
-                  console.log('[Terminal] WebMCP token detected:', match[0])
+                  console.log('[Terminal] WebMCP token detected')
                   waitingForToken.value = false
                   tokenBuffer = ''
                   stopTokenPolling()
                   connectWithToken(match[0]).then(success => {
-                    if (success) {
-                      canvasStore.showNotification('WebMCP connected!', 'success')
-                    }
+                    if (success) canvasStore.showNotification('WebMCP connected!', 'success')
                   }).catch(console.error)
-                } catch {
-                  // Token incomplete, keep waiting
-                }
+                } catch { /* Token incomplete */ }
               }
             }
           }, 300)
         }
 
-        terminal?.write(msg.data)
+        // Write output using composable
+        renderer.write(msg.data)
       } else if (msg.type === 'exit') {
-        terminal?.write(msg.data)
+        renderer.write(msg.data)
         sessionId.value = null
       } else if (msg.type === 'error') {
-        terminal?.write(`\r\n\x1b[31mError: ${msg.message}\x1b[0m\r\n`)
+        renderer.writeln(`\x1b[31mError: ${msg.message}\x1b[0m`)
       }
     }
 
@@ -516,9 +443,8 @@ async function connect() {
       connecting.value = false
       socket = null
 
-      // Auto-reconnect if terminal is still open
       if (isOpen.value && reconnectAttempts < MAX_RECONNECT_ATTEMPTS) {
-        terminal?.write('\r\n\x1b[33m[Disconnected - reconnecting...]\x1b[0m\r\n')
+        renderer.writeln('\x1b[33m[Disconnected - reconnecting...]\x1b[0m')
         scheduleReconnect()
       }
     }
@@ -526,9 +452,8 @@ async function connect() {
     socket.onerror = () => {
       connecting.value = false
     }
-  } catch (e) {
+  } catch {
     connecting.value = false
-    // Try to reconnect on connection error
     if (isOpen.value && reconnectAttempts < MAX_RECONNECT_ATTEMPTS) {
       scheduleReconnect()
     }
@@ -537,9 +462,8 @@ async function connect() {
 
 function scheduleReconnect() {
   if (reconnectTimeout) clearTimeout(reconnectTimeout)
-
   reconnectAttempts++
-  const delay = RECONNECT_DELAY_MS * Math.min(reconnectAttempts, 5) // Max 10s delay
+  const delay = RECONNECT_DELAY_MS * Math.min(reconnectAttempts, 5)
 
   console.log(`[Terminal] Reconnecting in ${delay}ms (attempt ${reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS})`)
 
@@ -558,45 +482,47 @@ function cancelReconnect() {
   reconnectAttempts = 0
 }
 
+// ============================================================================
+// ACTIONS
+// ============================================================================
+
 function close() {
   isOpen.value = false
 }
 
 function runClaude() {
-  if (socket && socket.readyState === WebSocket.OPEN) {
+  if (socket?.readyState === WebSocket.OPEN) {
     socket.send(JSON.stringify({ type: 'input', data: 'claude\r' }))
   }
 }
 
 function runClaudeContinue() {
-  if (socket && socket.readyState === WebSocket.OPEN) {
+  if (socket?.readyState === WebSocket.OPEN) {
     socket.send(JSON.stringify({ type: 'input', data: 'claude --continue\r' }))
   }
 }
 
 function runClaudeResume() {
-  if (socket && socket.readyState === WebSocket.OPEN) {
+  if (socket?.readyState === WebSocket.OPEN) {
     socket.send(JSON.stringify({ type: 'input', data: 'claude --resume\r' }))
   }
 }
 
 function sendClear() {
-  if (socket && socket.readyState === WebSocket.OPEN) {
+  if (socket?.readyState === WebSocket.OPEN) {
     socket.send(JSON.stringify({ type: 'input', data: 'clear\r' }))
   }
 }
 
 function requestToken() {
-  if (socket && socket.readyState === WebSocket.OPEN) {
+  if (socket?.readyState === WebSocket.OPEN) {
     tokenBuffer = ''
     waitingForToken.value = true
-
-    // Send character by character then Enter (same as VoiceFloat)
     const text = 'genera token usando tu mcp'
     const chars = (text + '\r').split('')
     let i = 0
     const typeChar = () => {
-      if (i < chars.length && socket && socket.readyState === WebSocket.OPEN) {
+      if (i < chars.length && socket?.readyState === WebSocket.OPEN) {
         socket.send(JSON.stringify({ type: 'input', data: chars[i] }))
         i++
         setTimeout(typeChar, 15)
@@ -606,111 +532,101 @@ function requestToken() {
   }
 }
 
-// Mobile virtual keys - send special key sequences
 function sendKey(key: string) {
   if (!socket || socket.readyState !== WebSocket.OPEN) return
-
   const keyMap: Record<string, string> = {
-    'up': '\x1b[A',
-    'down': '\x1b[B',
-    'left': '\x1b[D',
-    'right': '\x1b[C',
-    'alt-m': '\x1bm',
-    'ctrl-c': '\x03',
-    'tab': '\t',
-    'esc': '\x1b'
+    'up': '\x1b[A', 'down': '\x1b[B', 'left': '\x1b[D', 'right': '\x1b[C',
+    'alt-m': '\x1bm', 'ctrl-c': '\x03', 'tab': '\t', 'esc': '\x1b'
   }
-
   const data = keyMap[key]
-  if (data) {
-    socket.send(JSON.stringify({ type: 'input', data }))
-  }
+  if (data) socket.send(JSON.stringify({ type: 'input', data }))
 }
 
-// Mobile scroll controls
 function scrollTerminal(direction: 'up' | 'down' | 'end') {
-  if (!terminal) return
+  if (direction === 'up') renderer.scrollLines(-10)
+  else if (direction === 'down') renderer.scrollLines(10)
+  else renderer.scrollToBottom()
+}
 
-  if (direction === 'up') {
-    terminal.scrollLines(-10)
-  } else if (direction === 'down') {
-    terminal.scrollLines(10)
-  } else if (direction === 'end') {
-    terminal.scrollToBottom()
+function requestReplay(tailOnly = false) {
+  if (socket?.readyState === WebSocket.OPEN) {
+    console.log('[Terminal] Requesting replay, tailOnly:', tailOnly)
+    socket.send(JSON.stringify({ type: 'request-replay', tailOnly, chunks: 500 }))
   }
 }
 
-// Refresh terminal display
-function refreshTerminal() {
-  // If disconnected, try to reconnect
+function refreshTerminal(fullReplay = false) {
   if (!connected.value && !connecting.value) {
     reconnectAttempts = 0
     connect()
     return
   }
-
-  if (!terminal || !fitAddon) return
-
-  // Clear and refit terminal
-  fitAddon.fit()
-  terminal.scrollToBottom()
-  terminal.focus()
+  requestAnimationFrame(() => {
+    renderer.fit()
+    requestReplay(!fullReplay)
+  })
 }
 
+// ============================================================================
+// WATCHERS
+// ============================================================================
+
 watch(isOpen, async (open) => {
   if (open) {
+    console.log('[Terminal] Opening terminal...')
     await nextTick()
-    initTerminal()
-    if (!connected.value && !connecting.value) connect()
-    nextTick(() => {
-      fitAddon?.fit()
-      terminal?.focus()
-    })
+
+    // Initialize terminal (only works when visible!)
+    renderer.init()
+
+    // Wait for CSS transition, then connect
+    setTimeout(async () => {
+      console.log('[Terminal] Transition done, preparing terminal...')
+
+      // Wait for terminal to be fully visible
+      await renderer.onBecameVisible()
+      console.log('[Terminal] Terminal visible, connecting...')
+
+      // Now connect (or request replay if already connected)
+      if (!connected.value && !connecting.value) {
+        connect()
+      } else if (connected.value) {
+        requestReplay()
+      }
+    }, 180)
   } else {
-    // Cleanup when closing
-    cancelReconnect() // Stop any pending reconnection
-    resizeObserver?.disconnect()
-    resizeObserver = null
-    terminal?.dispose()
-    terminal = null
-    fitAddon = null
+    renderer.blur()
     waitingForToken.value = false
     tokenBuffer = ''
     if (tokenTimeout) clearTimeout(tokenTimeout)
   }
 })
 
-// Refit terminal when mobile sheet height or keyboard changes
 watch([sheetHeight, keyboardHeight], () => {
   if (isMobile.value && isOpen.value) {
-    nextTick(() => fitAddon?.fit())
+    nextTick(() => renderer.fit())
   }
 })
 
-onMounted(async () => {
-  // Global listeners for Ctrl+E
+// ============================================================================
+// LIFECYCLE
+// ============================================================================
+
+onMounted(() => {
   document.addEventListener('mousemove', trackMouse)
   document.addEventListener('keydown', handleKeydown)
-
-  // Mobile detection
   checkMobile()
   window.addEventListener('resize', checkMobile)
-
-  // Virtual keyboard detection
   setupKeyboardDetection()
 
-  if (isOpen.value) {
-    await nextTick()
-    initTerminal()
-    connect()
-  }
+  // DON'T initialize terminal here - wait for isOpen!
+  console.log('[Terminal] Mounted, waiting for terminal to open...')
 })
 
 onBeforeUnmount(() => {
   cancelReconnect()
-  resizeObserver?.disconnect()
   socket?.close()
-  terminal?.dispose()
+  renderer.dispose()
   document.removeEventListener('mousemove', onDrag)
   document.removeEventListener('mouseup', stopDrag)
   document.removeEventListener('touchmove', onDrag)
@@ -725,7 +641,10 @@ onBeforeUnmount(() => {
   }
 })
 
-// Expose controls for MCP tools
+// ============================================================================
+// EXPOSE
+// ============================================================================
+
 defineExpose({
   open: (x?: number, y?: number) => {
     if (x !== undefined && y !== undefined) {
@@ -734,27 +653,19 @@ defineExpose({
     }
     isOpen.value = true
   },
-  close: () => {
-    isOpen.value = false
-  },
-  toggle: () => {
-    toggleTerminal()
-  },
+  close: () => { isOpen.value = false },
+  toggle: toggleTerminal,
   move: (x: number, y: number) => {
     position.value = { x, y }
     hasCustomPosition.value = true
   },
   resize: (w: number, h: number) => {
     size.value = { w: Math.max(400, w), h: Math.max(250, h) }
-    nextTick(() => fitAddon?.fit())
+    nextTick(() => renderer.fit())
   },
-  getState: () => ({
-    isOpen: isOpen.value,
-    position: position.value,
-    size: size.value
-  }),
+  getState: () => ({ isOpen: isOpen.value, position: position.value, size: size.value }),
   sendInput: (text: string) => {
-    if (socket && socket.readyState === WebSocket.OPEN) {
+    if (socket?.readyState === WebSocket.OPEN) {
       socket.send(JSON.stringify({ type: 'input', data: text + '\r' }))
       return true
     }
@@ -767,7 +678,7 @@ defineExpose({
   <Teleport to="body">
     <Transition name="win-slide">
       <div
-        v-if="isOpen"
+        v-show="isOpen"
         ref="terminalRef"
         class="aero-win"
         :class="{
@@ -798,16 +709,12 @@ defineExpose({
             @touchend="stopSheetDrag"
           >
             <div class="left">
-              <!-- Nucleo Logo -->
               <div class="nucleo-logo">
                 <svg width="16" height="16" viewBox="0 0 24 24" fill="none">
-                  <!-- Core nucleus -->
                   <circle cx="12" cy="12" r="4" fill="url(#nucleoGradient)"/>
-                  <!-- Orbital rings -->
                   <ellipse cx="12" cy="12" rx="9" ry="4" stroke="url(#orbitGradient)" stroke-width="1.2" fill="none" transform="rotate(-30 12 12)"/>
                   <ellipse cx="12" cy="12" rx="9" ry="4" stroke="url(#orbitGradient)" stroke-width="1.2" fill="none" transform="rotate(30 12 12)"/>
                   <ellipse cx="12" cy="12" rx="9" ry="4" stroke="url(#orbitGradient)" stroke-width="1.2" fill="none" transform="rotate(90 12 12)"/>
-                  <!-- Electrons -->
                   <circle cx="12" cy="3" r="1.5" fill="#a78bfa">
                     <animateTransform attributeName="transform" type="rotate" from="0 12 12" to="360 12 12" dur="3s" repeatCount="indefinite"/>
                   </circle>
@@ -817,7 +724,6 @@ defineExpose({
                   <circle cx="4" cy="14" r="1.5" fill="#c4b5fd">
                     <animateTransform attributeName="transform" type="rotate" from="240 12 12" to="600 12 12" dur="3.5s" repeatCount="indefinite"/>
                   </circle>
-                  <!-- Gradients -->
                   <defs>
                     <radialGradient id="nucleoGradient" cx="50%" cy="30%" r="60%">
                       <stop offset="0%" stop-color="#a78bfa"/>
@@ -838,13 +744,13 @@ defineExpose({
             <div class="window-controls">
               <button @click="requestToken" :class="{ waiting: waitingForToken }" title="Connect MCP"><svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg></button>
               <button @click="runClaude" title="Claude"><svg width="8" height="8" viewBox="0 0 24 24" fill="currentColor"><path d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5"/></svg></button>
+              <button @click="refreshTerminal" title="Refresh Screen"><svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-6.219-8.56"/></svg></button>
               <button class="x" @click="close" title="Close"><svg width="8" height="8" viewBox="0 0 10 10"><line x1="0" y1="0" x2="10" y2="10" stroke="currentColor" stroke-width="1.5"/><line x1="10" y1="0" x2="0" y2="10" stroke="currentColor" stroke-width="1.5"/></svg></button>
             </div>
           </div>
           <!-- Content -->
           <div class="content">
             <div ref="terminalContainer" class="term"></div>
-            <!-- Disconnected overlay -->
             <div v-if="!connected && !connecting" class="disconnect-overlay" @click="connect">
               <div class="disconnect-msg">
                 <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
@@ -855,7 +761,6 @@ defineExpose({
                 <small>Toca para reconectar</small>
               </div>
             </div>
-            <!-- Connecting overlay -->
             <div v-else-if="connecting" class="disconnect-overlay connecting">
               <div class="disconnect-msg">
                 <div class="spinner"></div>
@@ -869,19 +774,17 @@ defineExpose({
             <button @click="sendKey('tab')" class="vk">Tab</button>
             <button @click="sendKey('ctrl-c')" class="vk ctrl">^C</button>
             <button @click="sendKey('alt-m')" class="vk alt">Alt+M</button>
-            <button @click="sendClear" class="vk clear" title="Clear">Clear</button>
-            <button @click="requestToken" class="vk token" :class="{ waiting: waitingForToken }" title="Connect MCP">MCP</button>
-            <button @click="runClaude" class="vk claude" title="Claude">Claude</button>
-            <button @click="runClaudeContinue" class="vk claude-cont" title="Claude Continue">Cont</button>
-            <button @click="runClaudeResume" class="vk claude-resume" title="Claude Resume">Resume</button>
-            <button @click="refreshTerminal" class="vk refresh" title="Refrescar">↻</button>
-            <!-- Scroll controls -->
+            <button @click="sendClear" class="vk clear">Clear</button>
+            <button @click="requestToken" class="vk token" :class="{ waiting: waitingForToken }">MCP</button>
+            <button @click="runClaude" class="vk claude">Claude</button>
+            <button @click="runClaudeContinue" class="vk claude-cont">Cont</button>
+            <button @click="runClaudeResume" class="vk claude-resume">Resume</button>
+            <button @click="refreshTerminal" class="vk refresh">↻</button>
             <div class="vk-scroll">
               <button @click="scrollTerminal('up')" class="vk scroll">⬆</button>
               <button @click="scrollTerminal('end')" class="vk scroll end">⤓</button>
               <button @click="scrollTerminal('down')" class="vk scroll">⬇</button>
             </div>
-            <!-- Arrow keys for input -->
             <div class="vk-arrows">
               <button @click="sendKey('up')" class="vk arrow">▲</button>
               <div class="vk-row">
@@ -891,7 +794,6 @@ defineExpose({
               </div>
             </div>
           </div>
-          <!-- Resize handle -->
           <div class="resize-handle" @mousedown="startResize"></div>
         </div>
       </div>
@@ -918,10 +820,7 @@ defineExpose({
   -webkit-backdrop-filter: blur(24px) saturate(1.6);
   border-radius: 5px;
   border: 1px solid rgba(255,255,255,0.6);
-  box-shadow:
-    0 0 0 1px rgba(80,120,180,0.25),
-    0 6px 24px rgba(0,0,0,0.25),
-    inset 0 1px 0 rgba(255,255,255,0.6);
+  box-shadow: 0 0 0 1px rgba(80,120,180,0.25), 0 6px 24px rgba(0,0,0,0.25), inset 0 1px 0 rgba(255,255,255,0.6);
   overflow: hidden;
 }
 
@@ -963,52 +862,26 @@ defineExpose({
   letter-spacing: 0.5px;
 }
 
-.dot {
-  width: 5px; height: 5px;
-  border-radius: 50%;
-  background: #999;
-}
+.dot { width: 5px; height: 5px; border-radius: 50%; background: #999; }
 .dot.on { background: #0a0; box-shadow: 0 0 4px #0a0; }
 .dot.wait { background: #a80; animation: pulse .8s infinite; }
 
-.link {
-  margin-left: 2px;
-  color: #369;
-  font-size: 9px;
-  text-decoration: underline;
-  cursor: pointer;
-}
+.link { margin-left: 2px; color: #369; font-size: 9px; text-decoration: underline; cursor: pointer; }
 .link:hover { color: #47a; }
 
-.window-controls {
-  display: flex;
-  gap: 1px;
-}
+.window-controls { display: flex; gap: 1px; }
 .window-controls button {
-  width: 20px;
-  height: 16px;
-  display: flex;
-  align-items: center;
-  justify-content: center;
+  width: 20px; height: 16px;
+  display: flex; align-items: center; justify-content: center;
   background: rgba(255,255,255,0.3);
   border: 1px solid rgba(0,0,0,0.1);
   border-radius: 2px;
   color: #333;
   cursor: pointer;
 }
-.window-controls button:hover {
-  background: rgba(255,255,255,0.5);
-}
-.window-controls button.x:hover {
-  background: linear-gradient(180deg, #e66 0%, #c33 100%);
-  border-color: #a22;
-  color: #fff;
-}
-.window-controls button.waiting {
-  background: rgba(16, 185, 129, 0.3);
-  border-color: #10b981;
-  animation: pulse 0.8s infinite;
-}
+.window-controls button:hover { background: rgba(255,255,255,0.5); }
+.window-controls button.x:hover { background: linear-gradient(180deg, #e66 0%, #c33 100%); border-color: #a22; color: #fff; }
+.window-controls button.waiting { background: rgba(16, 185, 129, 0.3); border-color: #10b981; animation: pulse 0.8s infinite; }
 
 .content {
   flex: 1;
@@ -1019,7 +892,6 @@ defineExpose({
   position: relative;
 }
 
-/* Disconnected/Connecting overlay */
 .disconnect-overlay {
   position: absolute;
   inset: 0;
@@ -1030,10 +902,7 @@ defineExpose({
   z-index: 10;
   cursor: pointer;
 }
-
-.disconnect-overlay.connecting {
-  cursor: wait;
-}
+.disconnect-overlay.connecting { cursor: wait; }
 
 .disconnect-msg {
   display: flex;
@@ -1043,107 +912,54 @@ defineExpose({
   color: #fff;
   text-align: center;
 }
-
-.disconnect-msg svg {
-  color: #ef4444;
-  opacity: 0.8;
-}
-
-.disconnect-msg span {
-  font-size: 14px;
-  font-weight: 500;
-}
-
-.disconnect-msg small {
-  font-size: 11px;
-  color: #888;
-}
+.disconnect-msg svg { color: #ef4444; opacity: 0.8; }
+.disconnect-msg span { font-size: 14px; font-weight: 500; }
+.disconnect-msg small { font-size: 11px; color: #888; }
 
 .spinner {
-  width: 24px;
-  height: 24px;
+  width: 24px; height: 24px;
   border: 2px solid rgba(255, 255, 255, 0.2);
   border-top-color: #fff;
   border-radius: 50%;
   animation: spin 0.8s linear infinite;
 }
 
-@keyframes spin {
-  to { transform: rotate(360deg); }
-}
+@keyframes spin { to { transform: rotate(360deg); } }
 
 .resize-handle {
   position: absolute;
-  right: 0;
-  bottom: 0;
-  width: 16px;
-  height: 16px;
+  right: 0; bottom: 0;
+  width: 16px; height: 16px;
   cursor: nwse-resize;
   background: linear-gradient(135deg, transparent 50%, rgba(255,255,255,0.3) 50%, rgba(255,255,255,0.1) 100%);
   border-radius: 0 0 5px 0;
 }
-.resize-handle:hover {
-  background: linear-gradient(135deg, transparent 50%, rgba(255,255,255,0.5) 50%, rgba(255,255,255,0.2) 100%);
-}
+.resize-handle:hover { background: linear-gradient(135deg, transparent 50%, rgba(255,255,255,0.5) 50%, rgba(255,255,255,0.2) 100%); }
 
-.aero-win.resizing {
-  user-select: none;
-}
-.aero-win.resizing .term {
-  pointer-events: none;
-}
+.aero-win.resizing { user-select: none; }
+.aero-win.resizing .term { pointer-events: none; }
 
-.term {
-  width: 100%;
-  height: 100%;
-}
-.term :deep(.xterm) {
-  height: 100%;
-  padding: 2px;
-}
+.term { width: 100%; height: 100%; }
+.term :deep(.xterm) { height: 100%; padding: 2px; }
 .term :deep(.xterm-viewport) {
   overflow-y: auto !important;
-  /* Enable touch scrolling on mobile */
   -webkit-overflow-scrolling: touch;
   touch-action: pan-y;
 }
-.term :deep(.xterm-screen) {
-  /* Allow touch events to pass through for scrolling */
-  touch-action: pan-y;
-}
-.term :deep(.xterm-viewport::-webkit-scrollbar) {
-  width: 8px;
-  background: rgba(0,0,0,0.2);
-}
-.term :deep(.xterm-viewport::-webkit-scrollbar-thumb) {
-  background: rgba(255,255,255,0.15);
-  border-radius: 4px;
-}
-.term :deep(.xterm-viewport::-webkit-scrollbar-thumb:hover) {
-  background: rgba(255,255,255,0.25);
-}
+.term :deep(.xterm-screen) { touch-action: pan-y; }
+.term :deep(.xterm-viewport::-webkit-scrollbar) { width: 8px; background: rgba(0,0,0,0.2); }
+.term :deep(.xterm-viewport::-webkit-scrollbar-thumb) { background: rgba(255,255,255,0.15); border-radius: 4px; }
+.term :deep(.xterm-viewport::-webkit-scrollbar-thumb:hover) { background: rgba(255,255,255,0.25); }
 
 .win-slide-enter-active, .win-slide-leave-active { transition: all .15s ease; }
 .win-slide-enter-from, .win-slide-leave-to { opacity: 0; transform: translateY(16px) scale(0.98); }
 
 @keyframes pulse { 0%,100% { opacity:1; } 50% { opacity:.4; } }
 
-/* Mobile/tablet bottom sheet styles */
-.aero-win.mobile {
-  min-width: unset;
-  min-height: unset;
-  max-width: 100%;
-  transition: height 0.25s cubic-bezier(0.4, 0, 0.2, 1);
-}
-
-.aero-win.mobile.sheet-dragging {
-  transition: none;
-}
-
-.aero-win.mobile .glass {
-  border-radius: 16px 16px 0 0;
-  padding-bottom: env(safe-area-inset-bottom, 0);
-}
+/* Mobile */
+.aero-win.mobile { min-width: unset; min-height: unset; max-width: 100%; transition: height 0.25s cubic-bezier(0.4, 0, 0.2, 1); }
+.aero-win.mobile.sheet-dragging { transition: none; }
+.aero-win.mobile .glass { border-radius: 16px 16px 0 0; padding-bottom: env(safe-area-inset-bottom, 0); }
 
 .sheet-handle {
   display: flex;
@@ -1154,43 +970,17 @@ defineExpose({
   touch-action: none;
   background: rgba(255,255,255,0.15);
 }
+.sheet-handle:active { cursor: grabbing; }
+.handle-bar { width: 36px; height: 4px; background: rgba(0,0,0,0.3); border-radius: 2px; }
 
-.sheet-handle:active {
-  cursor: grabbing;
-}
+.aero-win.mobile .titlebar { cursor: grab; touch-action: none; }
+.aero-win.mobile .resize-handle { display: none; }
+.aero-win.mobile .content { flex: 1; min-height: 100px; touch-action: pan-y; overflow: hidden; }
 
-.handle-bar {
-  width: 36px;
-  height: 4px;
-  background: rgba(0,0,0,0.3);
-  border-radius: 2px;
-}
-
-.aero-win.mobile .titlebar {
-  cursor: grab;
-  touch-action: none;
-}
-
-.aero-win.mobile .resize-handle {
-  display: none;
-}
-
-.aero-win.mobile .content {
-  flex: 1;
-  min-height: 100px;
-  /* Allow touch scrolling in terminal area */
-  touch-action: pan-y;
-  overflow: hidden;
-}
-
-/* Mobile animations */
 .aero-win.mobile.win-slide-enter-from,
-.aero-win.mobile.win-slide-leave-to {
-  transform: translateY(100%);
-  opacity: 1;
-}
+.aero-win.mobile.win-slide-leave-to { transform: translateY(100%); opacity: 1; }
 
-/* Virtual keys for mobile */
+/* Virtual keys */
 .virtual-keys {
   display: flex;
   align-items: center;
@@ -1203,114 +993,32 @@ defineExpose({
 }
 
 .vk {
-  min-width: 48px;
-  height: 40px;
-  padding: 0 10px;
+  min-width: 48px; height: 40px; padding: 0 10px;
   background: linear-gradient(180deg, #444 0%, #333 100%);
   border: 1px solid rgba(255, 255, 255, 0.15);
   border-radius: 6px;
   color: #fff;
-  font-size: 13px;
-  font-weight: 500;
-  font-family: system-ui, sans-serif;
+  font-size: 13px; font-weight: 500; font-family: system-ui, sans-serif;
   cursor: pointer;
   touch-action: manipulation;
   transition: all 0.1s;
 }
+.vk:active { background: linear-gradient(180deg, #555 0%, #444 100%); transform: scale(0.95); }
+.vk.ctrl { background: linear-gradient(180deg, #c53030 0%, #9b2c2c 100%); border-color: rgba(255, 100, 100, 0.3); }
+.vk.alt { background: linear-gradient(180deg, #2563eb 0%, #1d4ed8 100%); border-color: rgba(100, 150, 255, 0.3); }
+.vk.refresh { background: linear-gradient(180deg, #f59e0b 0%, #d97706 100%); border-color: rgba(245, 158, 11, 0.3); font-size: 18px; }
+.vk.clear { background: linear-gradient(180deg, #6b7280 0%, #4b5563 100%); border-color: rgba(107, 114, 128, 0.3); }
+.vk.token { background: linear-gradient(180deg, #ec4899 0%, #db2777 100%); border-color: rgba(236, 72, 153, 0.3); }
+.vk.token.waiting { background: linear-gradient(180deg, #10b981 0%, #059669 100%); border-color: rgba(16, 185, 129, 0.3); animation: pulse 0.8s infinite; }
+.vk.claude { background: linear-gradient(180deg, #8b5cf6 0%, #7c3aed 100%); border-color: rgba(139, 92, 246, 0.3); }
+.vk.claude-cont { background: linear-gradient(180deg, #06b6d4 0%, #0891b2 100%); border-color: rgba(6, 182, 212, 0.3); }
+.vk.claude-resume { background: linear-gradient(180deg, #10b981 0%, #059669 100%); border-color: rgba(16, 185, 129, 0.3); }
 
-.vk:active {
-  background: linear-gradient(180deg, #555 0%, #444 100%);
-  transform: scale(0.95);
-}
+.vk-scroll { display: flex; flex-direction: column; align-items: center; gap: 2px; margin-left: auto; }
+.vk.scroll { min-width: 44px; width: 44px; height: 36px; padding: 0; font-size: 16px; background: linear-gradient(180deg, #065f46 0%, #047857 100%); border-color: rgba(16, 185, 129, 0.3); }
+.vk.scroll.end { background: linear-gradient(180deg, #7c3aed 0%, #6d28d9 100%); border-color: rgba(139, 92, 246, 0.3); font-size: 18px; }
 
-.vk.ctrl {
-  background: linear-gradient(180deg, #c53030 0%, #9b2c2c 100%);
-  border-color: rgba(255, 100, 100, 0.3);
-}
-
-.vk.alt {
-  background: linear-gradient(180deg, #2563eb 0%, #1d4ed8 100%);
-  border-color: rgba(100, 150, 255, 0.3);
-}
-
-.vk.refresh {
-  background: linear-gradient(180deg, #f59e0b 0%, #d97706 100%);
-  border-color: rgba(245, 158, 11, 0.3);
-  font-size: 18px;
-}
-
-.vk.clear {
-  background: linear-gradient(180deg, #6b7280 0%, #4b5563 100%);
-  border-color: rgba(107, 114, 128, 0.3);
-}
-
-.vk.token {
-  background: linear-gradient(180deg, #ec4899 0%, #db2777 100%);
-  border-color: rgba(236, 72, 153, 0.3);
-}
-
-.vk.token.waiting {
-  background: linear-gradient(180deg, #10b981 0%, #059669 100%);
-  border-color: rgba(16, 185, 129, 0.3);
-  animation: pulse 0.8s infinite;
-}
-
-.vk.claude {
-  background: linear-gradient(180deg, #8b5cf6 0%, #7c3aed 100%);
-  border-color: rgba(139, 92, 246, 0.3);
-}
-
-.vk.claude-cont {
-  background: linear-gradient(180deg, #06b6d4 0%, #0891b2 100%);
-  border-color: rgba(6, 182, 212, 0.3);
-}
-
-.vk.claude-resume {
-  background: linear-gradient(180deg, #10b981 0%, #059669 100%);
-  border-color: rgba(16, 185, 129, 0.3);
-}
-
-.vk-scroll {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: 2px;
-  margin-left: auto;
-}
-
-.vk.scroll {
-  min-width: 44px;
-  width: 44px;
-  height: 36px;
-  padding: 0;
-  font-size: 16px;
-  background: linear-gradient(180deg, #065f46 0%, #047857 100%);
-  border-color: rgba(16, 185, 129, 0.3);
-}
-
-.vk.scroll.end {
-  background: linear-gradient(180deg, #7c3aed 0%, #6d28d9 100%);
-  border-color: rgba(139, 92, 246, 0.3);
-  font-size: 18px;
-}
-
-.vk-arrows {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: 2px;
-}
-
-.vk-row {
-  display: flex;
-  gap: 2px;
-}
-
-.vk.arrow {
-  min-width: 38px;
-  width: 38px;
-  height: 32px;
-  padding: 0;
-  font-size: 12px;
-}
+.vk-arrows { display: flex; flex-direction: column; align-items: center; gap: 2px; }
+.vk-row { display: flex; gap: 2px; }
+.vk.arrow { min-width: 38px; width: 38px; height: 32px; padding: 0; font-size: 12px; }
 </style>
diff --git a/frontend/src/composables/useTerminalRenderer.ts b/frontend/src/composables/useTerminalRenderer.ts
new file mode 100644
index 0000000..c53d25b
--- /dev/null
+++ b/frontend/src/composables/useTerminalRenderer.ts
@@ -0,0 +1,491 @@
+/**
+ * useTerminalRenderer
+ *
+ * Composable dedicado al renderizado de xterm.js para Claude Code.
+ * TODA la lógica de renderizado del terminal debe estar aquí.
+ *
+ * Problemas conocidos de xterm.js que este composable resuelve:
+ * - xterm.js no puede calcular dimensiones cuando el contenedor está oculto
+ * - fit() no funciona correctamente con display:none
+ * - El contenido se corrompe al cambiar visibilidad
+ *
+ * Referencias:
+ * - https://github.com/xtermjs/xterm.js/issues/3029
+ * - https://github.com/xtermjs/xterm.js/issues/664
+ * - https://github.com/xtermjs/xterm.js/issues/3653
+ */
+
+import { ref, type Ref, nextTick } from 'vue'
+import { Terminal } from '@xterm/xterm'
+import { FitAddon } from '@xterm/addon-fit'
+import { WebLinksAddon } from '@xterm/addon-web-links'
+import '@xterm/xterm/css/xterm.css'
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface TerminalTheme {
+  background?: string
+  foreground?: string
+  cursor?: string
+  cursorAccent?: string
+  selectionBackground?: 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
+}
+
+export interface TerminalRendererOptions {
+  container: Ref<HTMLElement | null>
+  onData?: (data: string) => void
+  onResize?: (cols: number, rows: number) => void
+  onKeyEvent?: (e: KeyboardEvent) => boolean | void
+  theme?: TerminalTheme
+  fontSize?: number
+  fontFamily?: string
+}
+
+export interface TerminalRenderer {
+  // State
+  terminal: Ref<Terminal | null>
+  fitAddon: Ref<FitAddon | null>
+  isReady: Ref<boolean>
+
+  // Lifecycle
+  init: () => boolean
+  dispose: () => void
+
+  // Writing
+  write: (data: string) => Promise<void>
+  writeln: (data: string) => void
+
+  // Buffer management
+  clear: () => void
+  reset: () => void
+
+  // Display
+  fit: () => void
+  refresh: () => void
+  scrollToBottom: () => void
+  scrollLines: (lines: number) => void
+
+  // Focus
+  focus: () => void
+  blur: () => void
+
+  // Selection
+  getSelection: () => string
+
+  // Buffer content
+  getBufferContent: () => string
+
+  // Visibility handling - THE MAIN PROBLEM WE'RE SOLVING
+  onBecameVisible: () => Promise<void>
+
+  // Replay handling
+  handleReplay: (data: string) => Promise<void>
+}
+
+// ============================================================================
+// TERMINAL THEME
+// ============================================================================
+
+const TERMINAL_THEME = {
+  background: 'rgba(12, 12, 12, 0.95)',
+  foreground: '#ffffff',
+  cursor: '#ffffff',
+  cursorAccent: '#000000',
+  selectionBackground: 'rgba(100, 150, 255, 0.4)',
+  black: '#0c0c0c',
+  red: '#c50f1f',
+  green: '#13a10e',
+  yellow: '#c19c00',
+  blue: '#0037da',
+  magenta: '#881798',
+  cyan: '#3a96dd',
+  white: '#cccccc',
+  brightBlack: '#767676',
+  brightRed: '#e74856',
+  brightGreen: '#16c60c',
+  brightYellow: '#f9f1a5',
+  brightBlue: '#3b78ff',
+  brightMagenta: '#b4009e',
+  brightCyan: '#61d6d6',
+  brightWhite: '#f2f2f2'
+}
+
+function getTerminalConfig(options: TerminalRendererOptions) {
+  return {
+    cursorBlink: true,
+    cursorStyle: 'block' as const,
+    fontSize: options.fontSize || 12,
+    fontFamily: options.fontFamily || "'Consolas', 'Lucida Console', monospace",
+    scrollback: 10000,
+    theme: options.theme || TERMINAL_THEME,
+    allowProposedApi: true
+  }
+}
+
+// ============================================================================
+// COMPOSABLE
+// ============================================================================
+
+export function useTerminalRenderer(options: TerminalRendererOptions): TerminalRenderer {
+  const terminal = ref<Terminal | null>(null)
+  const fitAddon = ref<FitAddon | null>(null)
+  const isReady = ref(false)
+
+  let resizeObserver: ResizeObserver | null = null
+
+  // ==========================================================================
+  // LIFECYCLE
+  // ==========================================================================
+
+  /**
+   * Initialize the terminal.
+   * IMPORTANT: Only call this when the container is VISIBLE!
+   * Returns true if initialization succeeded.
+   */
+  function init(): boolean {
+    if (!options.container.value) {
+      console.warn('[TerminalRenderer] Init failed - no container')
+      return false
+    }
+
+    if (terminal.value) {
+      console.log('[TerminalRenderer] Already initialized')
+      return true
+    }
+
+    console.log('[TerminalRenderer] Initializing terminal...')
+
+    // Create terminal with options
+    terminal.value = new Terminal(getTerminalConfig(options))
+
+    // Load addons
+    fitAddon.value = new FitAddon()
+    terminal.value.loadAddon(fitAddon.value)
+    terminal.value.loadAddon(new WebLinksAddon())
+
+    // Open terminal in container
+    terminal.value.open(options.container.value)
+
+    // Initial fit (use nextTick to ensure DOM is ready)
+    nextTick(() => {
+      fit()
+      isReady.value = true
+      console.log('[TerminalRenderer] Ready, cols:', terminal.value?.cols, 'rows:', terminal.value?.rows)
+    })
+
+    // Setup resize observer
+    resizeObserver = new ResizeObserver(() => {
+      if (fitAddon.value && terminal.value) {
+        fitAddon.value.fit()
+        options.onResize?.(terminal.value.cols, terminal.value.rows)
+      }
+    })
+    resizeObserver.observe(options.container.value)
+
+    // Handle user input
+    if (options.onData) {
+      terminal.value.onData(options.onData)
+    }
+
+    // Handle custom key events
+    if (options.onKeyEvent) {
+      terminal.value.attachCustomKeyEventHandler((e) => {
+        const result = options.onKeyEvent!(e)
+        return result === undefined ? true : result
+      })
+    }
+
+    return true
+  }
+
+  /**
+   * Dispose the terminal and cleanup resources.
+   */
+  function dispose(): void {
+    console.log('[TerminalRenderer] Disposing...')
+    resizeObserver?.disconnect()
+    resizeObserver = null
+    terminal.value?.dispose()
+    terminal.value = null
+    fitAddon.value = null
+    isReady.value = false
+  }
+
+  // ==========================================================================
+  // WRITING
+  // ==========================================================================
+
+  /**
+   * Write data to terminal with Promise-based completion.
+   * The promise resolves when the data has been rendered.
+   */
+  function write(data: string): Promise<void> {
+    return new Promise((resolve) => {
+      if (!terminal.value) {
+        console.warn('[TerminalRenderer] Write failed - no terminal')
+        resolve()
+        return
+      }
+
+      terminal.value.write(data, () => {
+        resolve()
+      })
+    })
+  }
+
+  /**
+   * Write a line to the terminal (adds \r\n).
+   */
+  function writeln(data: string): void {
+    terminal.value?.writeln(data)
+  }
+
+  // ==========================================================================
+  // BUFFER MANAGEMENT
+  // ==========================================================================
+
+  /**
+   * Clear the terminal scrollback buffer.
+   */
+  function clear(): void {
+    console.log('[TerminalRenderer] Clearing buffer')
+    terminal.value?.clear()
+  }
+
+  /**
+   * Reset the terminal completely (more aggressive than clear).
+   */
+  function reset(): void {
+    console.log('[TerminalRenderer] Resetting terminal')
+    terminal.value?.reset()
+  }
+
+  // ==========================================================================
+  // DISPLAY
+  // ==========================================================================
+
+  /**
+   * Fit terminal dimensions to container size.
+   */
+  function fit(): void {
+    if (!fitAddon.value) return
+    fitAddon.value.fit()
+  }
+
+  /**
+   * Refresh all visible rows.
+   */
+  function refresh(): void {
+    if (!terminal.value) return
+    const rows = terminal.value.rows || 24
+    console.log('[TerminalRenderer] Refreshing rows 0 to', rows - 1)
+    terminal.value.refresh(0, rows - 1)
+  }
+
+  /**
+   * Scroll to the bottom of the terminal.
+   */
+  function scrollToBottom(): void {
+    terminal.value?.scrollToBottom()
+  }
+
+  /**
+   * Scroll by a number of lines (positive = down, negative = up).
+   */
+  function scrollLines(lines: number): void {
+    terminal.value?.scrollLines(lines)
+  }
+
+  // ==========================================================================
+  // FOCUS
+  // ==========================================================================
+
+  function focus(): void {
+    terminal.value?.focus()
+  }
+
+  function blur(): void {
+    terminal.value?.blur()
+  }
+
+  // ==========================================================================
+  // SELECTION
+  // ==========================================================================
+
+  function getSelection(): string {
+    return terminal.value?.getSelection() || ''
+  }
+
+  /**
+   * Get all content from the terminal buffer.
+   * Useful for copying terminal content.
+   */
+  function getBufferContent(): string {
+    if (!terminal.value) return ''
+
+    const buffer = terminal.value.buffer.active
+    let content = ''
+
+    for (let i = 0; i < buffer.length; i++) {
+      const line = buffer.getLine(i)
+      if (line) {
+        content += line.translateToString(true) + '\n'
+      }
+    }
+
+    return content.trim()
+  }
+
+  // ==========================================================================
+  // VISIBILITY HANDLING - THE MAIN PROBLEM WE'RE SOLVING
+  // ==========================================================================
+
+  /**
+   * Handle terminal becoming visible after being hidden.
+   *
+   * When terminal container goes from hidden to visible, xterm.js has issues:
+   * 1. Dimensions were calculated as 0x0 when hidden
+   * 2. Content may not render correctly
+   * 3. Scroll position may be wrong
+   *
+   * This function should be called when the terminal becomes visible.
+   * It uses multiple requestAnimationFrame to ensure browser has painted.
+   */
+  async function onBecameVisible(): Promise<void> {
+    console.log('[TerminalRenderer] onBecameVisible called')
+
+    if (!terminal.value || !fitAddon.value) {
+      console.warn('[TerminalRenderer] Terminal not initialized')
+      return
+    }
+
+    return new Promise((resolve) => {
+      // Triple RAF to ensure browser has fully painted
+      requestAnimationFrame(() => {
+        console.log('[TerminalRenderer] RAF 1: Fitting...')
+        fit()
+
+        requestAnimationFrame(() => {
+          console.log('[TerminalRenderer] RAF 2: Dimensions:', terminal.value?.cols, 'x', terminal.value?.rows)
+
+          requestAnimationFrame(() => {
+            console.log('[TerminalRenderer] RAF 3: Ready for content')
+            focus()
+            resolve()
+          })
+        })
+      })
+    })
+  }
+
+  // ==========================================================================
+  // REPLAY HANDLING
+  // ==========================================================================
+
+  /**
+   * Handle replay data from server.
+   * This is the critical function for solving the rendering issue.
+   *
+   * Steps:
+   * 1. Reset terminal to clean state
+   * 2. Fit to ensure correct dimensions
+   * 3. Write data
+   * 4. Wait for write to complete
+   * 5. Scroll to bottom using multiple RAF
+   */
+  async function handleReplay(data: string): Promise<void> {
+    console.log('[TerminalRenderer] handleReplay, bytes:', data.length)
+
+    if (!terminal.value || !fitAddon.value) {
+      console.warn('[TerminalRenderer] Cannot handle replay - terminal not ready')
+      return
+    }
+
+    // Step 1: Reset terminal completely
+    reset()
+
+    // Step 2: Fit to get correct dimensions
+    fit()
+    console.log('[TerminalRenderer] Pre-write dimensions:', terminal.value.cols, 'x', terminal.value.rows)
+
+    // Step 3 & 4: Write data and wait for completion
+    await write(data)
+    console.log('[TerminalRenderer] Write completed')
+
+    // Step 5: Scroll to bottom with multiple RAF to ensure rendering
+    return new Promise((resolve) => {
+      requestAnimationFrame(() => {
+        fit()
+
+        requestAnimationFrame(() => {
+          scrollToBottom()
+          console.log('[TerminalRenderer] Scroll completed')
+          resolve()
+        })
+      })
+    })
+  }
+
+  // ==========================================================================
+  // RETURN
+  // ==========================================================================
+
+  return {
+    // State
+    terminal,
+    fitAddon,
+    isReady,
+
+    // Lifecycle
+    init,
+    dispose,
+
+    // Writing
+    write,
+    writeln,
+
+    // Buffer management
+    clear,
+    reset,
+
+    // Display
+    fit,
+    refresh,
+    scrollToBottom,
+    scrollLines,
+
+    // Focus
+    focus,
+    blur,
+
+    // Selection
+    getSelection,
+
+    // Buffer content
+    getBufferContent,
+
+    // Visibility handling
+    onBecameVisible,
+
+    // Replay handling
+    handleReplay
+  }
+}
diff --git a/frontend/src/pages/TerminalPage.vue b/frontend/src/pages/TerminalPage.vue
index 5fe0f5f..ad832cb 100644
--- a/frontend/src/pages/TerminalPage.vue
+++ b/frontend/src/pages/TerminalPage.vue
@@ -1,10 +1,7 @@
 <script setup lang="ts">
 import { ref, onMounted, onBeforeUnmount, nextTick } from 'vue'
-import { Terminal } from '@xterm/xterm'
-import { FitAddon } from '@xterm/addon-fit'
-import { WebLinksAddon } from '@xterm/addon-web-links'
-import '@xterm/xterm/css/xterm.css'
 import { endpoints } from '../config/endpoints'
+import { useTerminalRenderer } from '../composables/useTerminalRenderer'
 
 const terminalContainer = ref<HTMLElement | null>(null)
 const connected = ref(false)
@@ -13,76 +10,52 @@ const error = ref<string | null>(null)
 const sessionId = ref<string | null>(null)
 const isResumedSession = ref(false)
 
-let terminal: Terminal | null = null
-let fitAddon: FitAddon | null = null
 let socket: WebSocket | null = null
-let resizeObserver: ResizeObserver | null = null
 
 const WS_URL = endpoints.terminal
 
-function initTerminal() {
-  if (!terminalContainer.value) return
+// Terminal theme for TerminalPage (different from FloatingTerminal)
+const TERMINAL_PAGE_THEME = {
+  background: '#0f0f14',
+  foreground: '#e4e4e7',
+  cursor: '#6366f1',
+  cursorAccent: '#0f0f14',
+  selectionBackground: 'rgba(99, 102, 241, 0.3)',
+  black: '#16161d',
+  red: '#ef4444',
+  green: '#22c55e',
+  yellow: '#eab308',
+  blue: '#3b82f6',
+  magenta: '#a855f7',
+  cyan: '#06b6d4',
+  white: '#e4e4e7',
+  brightBlack: '#52525b',
+  brightRed: '#f87171',
+  brightGreen: '#4ade80',
+  brightYellow: '#facc15',
+  brightBlue: '#60a5fa',
+  brightMagenta: '#c084fc',
+  brightCyan: '#22d3ee',
+  brightWhite: '#ffffff'
+}
 
-  terminal = new Terminal({
-    cursorBlink: true,
-    cursorStyle: 'block',
-    fontSize: 14,
-    fontFamily: "'JetBrains Mono', 'Fira Code', Consolas, monospace",
-    theme: {
-      background: '#0f0f14',
-      foreground: '#e4e4e7',
-      cursor: '#6366f1',
-      cursorAccent: '#0f0f14',
-      selectionBackground: 'rgba(99, 102, 241, 0.3)',
-      black: '#16161d',
-      red: '#ef4444',
-      green: '#22c55e',
-      yellow: '#eab308',
-      blue: '#3b82f6',
-      magenta: '#a855f7',
-      cyan: '#06b6d4',
-      white: '#e4e4e7',
-      brightBlack: '#52525b',
-      brightRed: '#f87171',
-      brightGreen: '#4ade80',
-      brightYellow: '#facc15',
-      brightBlue: '#60a5fa',
-      brightMagenta: '#c084fc',
-      brightCyan: '#22d3ee',
-      brightWhite: '#ffffff'
-    },
-    allowProposedApi: true
-  })
-
-  fitAddon = new FitAddon()
-  terminal.loadAddon(fitAddon)
-  terminal.loadAddon(new WebLinksAddon())
-
-  terminal.open(terminalContainer.value)
-  fitAddon.fit()
-
-  // Handle resize
-  resizeObserver = new ResizeObserver(() => {
-    if (fitAddon && terminal) {
-      fitAddon.fit()
-      if (socket && socket.readyState === WebSocket.OPEN) {
-        socket.send(JSON.stringify({
-          type: 'resize',
-          cols: terminal.cols,
-          rows: terminal.rows
-        }))
-      }
-    }
-  })
-  resizeObserver.observe(terminalContainer.value)
-
-  // Handle terminal input
-  terminal.onData((data) => {
+// Use the composable
+const renderer = useTerminalRenderer({
+  container: terminalContainer,
+  theme: TERMINAL_PAGE_THEME,
+  fontSize: 14,
+  fontFamily: "'JetBrains Mono', 'Fira Code', Consolas, monospace",
+  onData: (data) => {
     if (socket && socket.readyState === WebSocket.OPEN) {
       socket.send(JSON.stringify({ type: 'input', data }))
     }
-  })
-}
+  },
+  onResize: (cols, rows) => {
+    if (socket && socket.readyState === WebSocket.OPEN) {
+      socket.send(JSON.stringify({ type: 'resize', cols, rows }))
+    }
+  }
+})
 
 async function connect() {
   if (connecting.value) return
@@ -96,37 +69,37 @@ async function connect() {
     socket.onopen = () => {
       connected.value = true
       connecting.value = false
-      terminal?.focus()
+      renderer.focus()
 
-      // Send initial resize
-      if (terminal) {
-        socket?.send(JSON.stringify({
-          type: 'resize',
-          cols: terminal.cols,
-          rows: terminal.rows
-        }))
+      const term = renderer.terminal.value
+      if (term) {
+        socket?.send(JSON.stringify({ type: 'resize', cols: term.cols, rows: term.rows }))
       }
     }
 
-    socket.onmessage = (event) => {
+    socket.onmessage = async (event) => {
       const msg = JSON.parse(event.data)
+
       if (msg.type === 'connected') {
         sessionId.value = msg.sessionId
         isResumedSession.value = !msg.isNew
-        if (!msg.isNew) {
-          terminal?.write('\x1b[36m[Reconnected to existing session]\x1b[0m\r\n')
+
+        if (msg.hasHistory) {
+          // Request replay
+          socket?.send(JSON.stringify({ type: 'request-replay', tailOnly: false }))
+        } else if (!msg.isNew) {
+          renderer.writeln('\x1b[36m[Reconnected to existing session]\x1b[0m')
         }
       } else if (msg.type === 'replay') {
-        // Replay buffer from persistent session
-        terminal?.write(msg.data)
+        await renderer.handleReplay(msg.data || '')
       } else if (msg.type === 'output') {
-        terminal?.write(msg.data)
+        renderer.write(msg.data)
       } else if (msg.type === 'exit') {
-        terminal?.write(msg.data)
+        renderer.write(msg.data)
         sessionId.value = null
       } else if (msg.type === 'error') {
         error.value = msg.message
-        terminal?.write(`\r\n\x1b[31mError: ${msg.message}\x1b[0m\r\n`)
+        renderer.writeln(`\x1b[31mError: ${msg.message}\x1b[0m`)
       }
     }
 
@@ -134,9 +107,9 @@ async function connect() {
       connected.value = false
       connecting.value = false
       if (sessionId.value) {
-        terminal?.write('\r\n\x1b[33mDisconnected - session preserved on server\x1b[0m\r\n')
+        renderer.writeln('\x1b[33mDisconnected - session preserved on server\x1b[0m')
       } else {
-        terminal?.write('\r\n\x1b[33mConnection closed\x1b[0m\r\n')
+        renderer.writeln('\x1b[33mConnection closed\x1b[0m')
       }
     }
 
@@ -159,27 +132,16 @@ function disconnect() {
 }
 
 function clearTerminal() {
-  terminal?.clear()
-  terminal?.reset()
+  renderer.clear()
+  renderer.reset()
 }
 
 async function copyContent() {
-  if (!terminal) return
-
-  // Get all terminal content
-  const buffer = terminal.buffer.active
-  let content = ''
-
-  for (let i = 0; i < buffer.length; i++) {
-    const line = buffer.getLine(i)
-    if (line) {
-      content += line.translateToString(true) + '\n'
-    }
-  }
+  const content = renderer.getBufferContent()
+  if (!content) return
 
   try {
-    await navigator.clipboard.writeText(content.trim())
-    // Visual feedback
+    await navigator.clipboard.writeText(content)
     const btn = document.querySelector('.btn-copy') as HTMLButtonElement
     if (btn) {
       btn.classList.add('copied')
@@ -198,15 +160,13 @@ function runClaudeCode() {
 
 onMounted(async () => {
   await nextTick()
-  initTerminal()
-  // Auto-connect
+  renderer.init()
   connect()
 })
 
 onBeforeUnmount(() => {
-  resizeObserver?.disconnect()
   socket?.close()
-  terminal?.dispose()
+  renderer.dispose()
 })
 </script>
 
@@ -228,28 +188,14 @@ onBeforeUnmount(() => {
       </div>
 
       <div class="toolbar-actions">
-        <button
-          v-if="!connected"
-          class="btn-primary"
-          @click="connect"
-          :disabled="connecting"
-        >
+        <button v-if="!connected" class="btn-primary" @click="connect" :disabled="connecting">
           Connect
         </button>
-        <button
-          v-else
-          class="btn-secondary"
-          @click="disconnect"
-        >
+        <button v-else class="btn-secondary" @click="disconnect">
           Disconnect
         </button>
 
-        <button
-          class="btn-accent"
-          @click="runClaudeCode"
-          :disabled="!connected"
-          title="Run Claude Code"
-        >
+        <button class="btn-accent" @click="runClaudeCode" :disabled="!connected" title="Run Claude Code">
           <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
             <path d="M12 2L2 7l10 5 10-5-10-5z"/>
             <path d="M2 17l10 5 10-5"/>
@@ -258,22 +204,14 @@ onBeforeUnmount(() => {
           Claude
         </button>
 
-        <button
-          class="btn-icon btn-copy"
-          @click="copyContent"
-          title="Copy terminal content"
-        >
+        <button class="btn-icon btn-copy" @click="copyContent" title="Copy terminal content">
           <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
             <rect x="9" y="9" width="13" height="13" rx="2" ry="2"/>
             <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>
           </svg>
         </button>
 
-        <button
-          class="btn-icon"
-          @click="clearTerminal"
-          title="Clear terminal"
-        >
+        <button class="btn-icon" @click="clearTerminal" title="Clear terminal">
           <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
             <path d="M3 6h18"/>
             <path d="M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6"/>
@@ -331,20 +269,9 @@ onBeforeUnmount(() => {
   font-weight: 500;
 }
 
-.status.connected {
-  background: var(--success-bg);
-  color: var(--success);
-}
-
-.status.connecting {
-  background: var(--warning-bg);
-  color: var(--warning);
-}
-
-.status.disconnected {
-  background: var(--error-bg);
-  color: var(--error);
-}
+.status.connected { background: var(--success-bg); color: var(--success); }
+.status.connecting { background: var(--warning-bg); color: var(--warning); }
+.status.disconnected { background: var(--error-bg); color: var(--error); }
 
 .session-badge {
   margin-left: 0.5rem;
@@ -378,15 +305,8 @@ onBeforeUnmount(() => {
   cursor: pointer;
   transition: background 0.15s;
 }
-
-.btn-primary:hover:not(:disabled) {
-  background: var(--accent-hover);
-}
-
-.btn-primary:disabled {
-  opacity: 0.6;
-  cursor: not-allowed;
-}
+.btn-primary:hover:not(:disabled) { background: var(--accent-hover); }
+.btn-primary:disabled { opacity: 0.6; cursor: not-allowed; }
 
 .btn-secondary {
   padding: 0.5rem 1rem;
@@ -398,10 +318,7 @@ onBeforeUnmount(() => {
   font-weight: 500;
   cursor: pointer;
 }
-
-.btn-secondary:hover {
-  background: var(--bg-tertiary);
-}
+.btn-secondary:hover { background: var(--bg-tertiary); }
 
 .btn-accent {
   display: flex;
@@ -417,15 +334,8 @@ onBeforeUnmount(() => {
   cursor: pointer;
   transition: opacity 0.15s;
 }
-
-.btn-accent:hover:not(:disabled) {
-  opacity: 0.9;
-}
-
-.btn-accent:disabled {
-  opacity: 0.5;
-  cursor: not-allowed;
-}
+.btn-accent:hover:not(:disabled) { opacity: 0.9; }
+.btn-accent:disabled { opacity: 0.5; cursor: not-allowed; }
 
 .btn-icon {
   padding: 0.5rem;
@@ -435,16 +345,8 @@ onBeforeUnmount(() => {
   color: var(--text-secondary);
   cursor: pointer;
 }
-
-.btn-icon:hover {
-  background: var(--bg-hover);
-  color: var(--text-primary);
-}
-
-.btn-icon.btn-copy.copied {
-  color: var(--success);
-  background: var(--success-bg);
-}
+.btn-icon:hover { background: var(--bg-hover); color: var(--text-primary); }
+.btn-icon.btn-copy.copied { color: var(--success); background: var(--success-bg); }
 
 .error-banner {
   padding: 1rem;
@@ -474,29 +376,10 @@ onBeforeUnmount(() => {
 }
 
 /* xterm overrides */
-.terminal-container :deep(.xterm) {
-  height: 100%;
-  padding: 0.5rem;
-}
-
-.terminal-container :deep(.xterm-viewport) {
-  overflow-y: auto !important;
-}
-
-.terminal-container :deep(.xterm-viewport::-webkit-scrollbar) {
-  width: 10px;
-}
-
-.terminal-container :deep(.xterm-viewport::-webkit-scrollbar-track) {
-  background: #16161d;
-}
-
-.terminal-container :deep(.xterm-viewport::-webkit-scrollbar-thumb) {
-  background: #2a2a3a;
-  border-radius: 5px;
-}
-
-.terminal-container :deep(.xterm-viewport::-webkit-scrollbar-thumb:hover) {
-  background: #3a3a4a;
-}
+.terminal-container :deep(.xterm) { height: 100%; padding: 0.5rem; }
+.terminal-container :deep(.xterm-viewport) { overflow-y: auto !important; }
+.terminal-container :deep(.xterm-viewport::-webkit-scrollbar) { width: 10px; }
+.terminal-container :deep(.xterm-viewport::-webkit-scrollbar-track) { background: #16161d; }
+.terminal-container :deep(.xterm-viewport::-webkit-scrollbar-thumb) { background: #2a2a3a; border-radius: 5px; }
+.terminal-container :deep(.xterm-viewport::-webkit-scrollbar-thumb:hover) { background: #3a3a4a; }
 </style>
diff --git a/server/config.ts b/server/config.ts
index 4f69d7d..fd0626a 100644
--- a/server/config.ts
+++ b/server/config.ts
@@ -7,7 +7,7 @@ export const WORKING_DIR = process.cwd().replace(/[\\\/]server$/, '')
 export const SHELL = process.platform === 'win32' ? 'powershell.exe' : 'bash'
 export const SHELL_ARGS = process.platform === 'win32' ? ['-NoLogo', '-NoProfile'] : []
 export const DEFAULT_SESSION_ID = 'main'
-export const MAX_BUFFER_LINES = 1000
+export const MAX_BUFFER_LINES = 10000
 
 // Database
 export const DB_PATH = 'agent-ui.db'
diff --git a/server/services/terminal.ts b/server/services/terminal.ts
index 6fb9858..62890c2 100644
--- a/server/services/terminal.ts
+++ b/server/services/terminal.ts
@@ -155,21 +155,19 @@ export function startTerminalServer() {
           session.clients.add(ws)
           wsToSession.set(ws, sessionId)
 
-          // Send connection info
+          // Send connection info (include buffer size so client knows if replay is needed)
           ws.send(JSON.stringify({
             type: 'connected',
             sessionId: session.id,
-            isNew: session.outputBuffer.length === 0
+            isNew: session.outputBuffer.length === 0,
+            hasHistory: session.outputBuffer.length > 0,
+            bufferSize: session.outputBuffer.length
           }))
 
-          // Replay buffer if there's history
-          if (session.outputBuffer.length > 0) {
-            console.log(`[Terminal] Replaying ${session.outputBuffer.length} buffer entries`)
-            ws.send(JSON.stringify({
-              type: 'replay',
-              data: session.outputBuffer.join('')
-            }))
-          }
+          // DON'T auto-replay here!
+          // Client will request replay when terminal is visible and ready.
+          // This fixes xterm.js rendering issues with hidden containers.
+          console.log(`[Terminal] Client connected, buffer has ${session.outputBuffer.length} chunks (client will request replay)`)
 
           console.log(`[Terminal] Client joined session ${sessionId} (${session.clients.size} clients)`)
         } catch (e: any) {
@@ -191,6 +189,33 @@ export function startTerminalServer() {
           } else if (msg.type === 'resize' && msg.cols && msg.rows) {
             session.pty.resize(msg.cols, msg.rows)
             console.log(`[Terminal] Session ${sessionId} resized to ${msg.cols}x${msg.rows}`)
+          } else if (msg.type === 'request-replay') {
+            // Client requests fresh replay (used when terminal becomes visible)
+            console.log(`[Terminal] Replay requested, buffer has ${session.outputBuffer.length} chunks`)
+
+            if (session.outputBuffer.length > 0) {
+              // If tailOnly specified, only send last N chunks (enough for a few screens)
+              const tailOnly = msg.tailOnly === true
+              const tailChunks = msg.chunks || 500 // Default ~500 chunks for tail
+
+              let data: string
+              if (tailOnly && session.outputBuffer.length > tailChunks) {
+                // Send only the tail - more efficient for large buffers
+                data = session.outputBuffer.slice(-tailChunks).join('')
+                console.log(`[Terminal] Replaying tail (${tailChunks}/${session.outputBuffer.length} chunks), ${data.length} bytes`)
+              } else {
+                data = session.outputBuffer.join('')
+                console.log(`[Terminal] Replaying full buffer (${session.outputBuffer.length} chunks), ${data.length} bytes`)
+              }
+
+              ws.send(JSON.stringify({
+                type: 'replay',
+                data,
+                isTail: tailOnly && session.outputBuffer.length > tailChunks
+              }))
+            } else {
+              console.log('[Terminal] No buffer to replay')
+            }
           }
         } catch (e: any) {
           console.error('[Terminal] Error:', e)