From 69f67d2fd3d5fe4bec455b42d7ad0741d63086f3 Mon Sep 17 00:00:00 2001
From: jester <admin@zerolaghub.com>
Date: Tue, 10 Mar 2026 20:04:30 +0000
Subject: [PATCH] Add TerminalView component doc with reconnect behavior

---
 Frontend/TerminalView_Component.md | 46 ++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 Frontend/TerminalView_Component.md

diff --git a/Frontend/TerminalView_Component.md b/Frontend/TerminalView_Component.md
new file mode 100644
index 0000000..c6ad515
--- /dev/null
+++ b/Frontend/TerminalView_Component.md
@@ -0,0 +1,46 @@
+# TerminalView Component
+
+> Status: ✅ Operational
+
+---
+
+## Overview
+
+The terminal console is implemented using:
+
+- **xterm.js** — frontend terminal renderer
+- **WebSocket transport** — connects portal to agent
+- **PTY session** — managed by the agent via `creack/pty`
+
+`TerminalView` owns the WebSocket lifecycle. `ServerConsole` owns policy and session gating.
+
+The file panel does not interrupt the console lifecycle.
+
+---
+
+## Reconnect Behavior
+
+The terminal automatically reconnects when the WebSocket closes unexpectedly.
+
+Behavior:
+
+- Reconnect delay: 1–5 seconds
+- Backoff capped at 5 seconds
+- Console session recreated automatically
+
+The user no longer needs to refresh the page to regain console access after navigating away from the console tab or after a transient disconnect.
+
+---
+
+## Agent Side
+
+- One PTY read loop per `{vmid, container_type}`
+- PTY-backed WebSocket served at `/console/ws`
+- Commands sent via `GET /console/command?cmd=<cmd>` to server stdin
+
+---
+
+## Constraints
+
+- Portal never calls the agent directly — all traffic through API
+- Console does not enforce real policy — agent enforces