cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/host/launcher.py

@@ -0,0 +1,395 @@
+"""
+CAT Browser Launcher - creates CAT's own browser window.
+
+Entry point for CAT's embedded browser subsystem.
+Creates a QWebEngineView-based browser window (same process).
+
+Usage:
+  from calc_terminal.host.launcher import launch_cat_host, can_launch_host
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import pathlib
+
+def _has_module(name: str) -> bool:
+    try:
+        __import__(name)
+        return True
+    except ImportError:
+        return False
+
+
+def can_launch_host() -> bool:
+    return _has_module("PySide6") or _has_module("PyQt6")
+
+
+def get_host_status() -> dict:
+    engines = []
+    if _has_module("PySide6"):
+        engines.append("PySide6 (Qt WebEngine)")
+    if _has_module("PyQt6"):
+        engines.append("PyQt6 (Qt WebEngine)")
+    return {
+        "available": bool(engines),
+        "engines": engines,
+        "preferred": engines[0] if engines else None,
+        "reason": "ready" if engines else "no browser engine - install: pip install PySide6",
+        "webview2_runtime": _webview2_runtime_version(),
+    }
+
+
+def _webview2_runtime_version() -> str:
+    if sys.platform != "win32":
+        return ""
+    try:
+        import winreg
+        for path in [
+            r"SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}",
+            r"SOFTWARE\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}",
+        ]:
+            try:
+                k = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, path)
+                pv, _ = winreg.QueryValueEx(k, "pv")
+                winreg.CloseKey(k)
+                return str(pv)
+            except FileNotFoundError:
+                continue
+    except Exception:
+        pass
+    return ""
+
+
+_PENDING_VERIFICATION_PATH = pathlib.Path.home() / ".cat_pending_verification.json"
+
+def _store_pending_verification(url: str):
+    try:
+        import json, time
+        payload = json.dumps({"url": url, "ts": time.time()})
+        tmp_p = pathlib.Path.home() / ".cat_pending_verification.tmp"
+        tmp_p.write_text(payload, encoding="utf-8")
+        tmp_p.replace(_PENDING_VERIFICATION_PATH)
+    except Exception:
+        try:
+            _PENDING_VERIFICATION_PATH.write_text(
+                json.dumps({"url": url, "ts": time.time()}), encoding="utf-8"
+            )
+        except Exception:
+            pass
+
+
+def _ensure_qt_app():
+    """Create or get existing QApplication. Returns (app, created_new)."""
+    # Fix Qt WebEngine cache permission errors
+    import tempfile
+    _cache_path = os.path.join(tempfile.gettempdir(), "cat_qt_cache")
+    os.makedirs(_cache_path, exist_ok=True)
+    os.environ["QTWEBENGINE_CACHE_PATH"] = _cache_path
+    # Performance: keep GPU enabled for smooth rendering, add safe flags
+    os.environ.setdefault("QTWEBENGINE_CHROMIUM_FLAGS",
+                          "--disable-dev-shm-usage --enable-gpu-rasterization "
+                          "--ignore-gpu-blocklist --enable-zero-copy "
+                          "--disable-background-networking --disable-default-apps")
+    os.environ.setdefault("QTWEBENGINE_DISABLE_SANDBOX", "1")
+
+    try:
+        from PySide6.QtWidgets import QApplication
+    except ImportError:
+        from PyQt6.QtWidgets import QApplication  # type: ignore
+    app = QApplication.instance()
+    if app is None:
+        app = QApplication(sys.argv)
+        return app, True
+    return app, False
+
+
+def _is_pid_alive(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    if sys.platform == "win32":
+        try:
+            import ctypes, ctypes.wintypes
+            h = ctypes.windll.kernel32.OpenProcess(0x1000, False, pid)
+            if h:
+                code = ctypes.wintypes.DWORD()
+                ctypes.windll.kernel32.GetExitCodeProcess(h, ctypes.byref(code))
+                ctypes.windll.kernel32.CloseHandle(h)
+                return code.value == 259
+            return False
+        except Exception:
+            return False
+    else:
+        try:
+            os.kill(pid, 0)
+            return True
+        except OSError:
+            return False
+
+
+def launch_cat_host(
+    start_browser_url: str | None = None,
+    start_mode: str = "terminal",
+    repl=None,
+    block: bool = True,
+) -> int:
+    """Launch CAT's own browser window.
+
+    block=True:  creates app + window + runs event loop (BLOCKS until closed).
+    block=False: navigates existing window to URL (no new app, returns fast).
+    """
+    if start_browser_url in ("fatty", "--fatty", "cat web"):
+        start_browser_url = "http://localhost:8765/"
+        start_mode = "browser"
+
+    if start_browser_url and "8765" in start_browser_url:
+        try:
+            from ..web.server import ensure_fatty_server
+            ensure_fatty_server(timeout=5.0, auto_start=True)
+        except Exception:
+            pass
+
+    if not block:
+        url = start_browser_url or "about:home"
+        _store_pending_verification(url)
+        # 1. Check if running in current process
+        try:
+            try:
+                from PySide6.QtWidgets import QApplication as _QApp
+            except ImportError:
+                from PyQt6.QtWidgets import QApplication as _QApp  # type: ignore
+            app = _QApp.instance()
+            if app is not None:
+                for w in app.topLevelWidgets():
+                    try:
+                        if w.__class__.__name__ == "CATDesktopWindow" and hasattr(w, "browser"):
+                            w.navigate(url)
+                            if hasattr(w, "_bring_to_front"):
+                                w._bring_to_front()
+                            else:
+                                w.show()
+                                w.raise_()
+                                w.activateWindow()
+                            return 0
+                    except Exception:
+                        continue
+        except Exception:
+            pass
+
+        # 2. Check if an external CAT Browser process is actively running (heartbeat within 3.5s)
+        try:
+            import time, json
+            hb_path = pathlib.Path.home() / ".cat_browser_heartbeat"
+            if hb_path.exists():
+                is_running = False
+                hwnd = 0
+                try:
+                    raw = hb_path.read_text(encoding="utf-8").strip()
+                    if raw:
+                        if raw.startswith("{"):
+                            data = json.loads(raw)
+                            hb_ts = float(data.get("ts", 0))
+                            pid = int(data.get("pid", 0))
+                            hwnd = int(data.get("hwnd", 0))
+                        else:
+                            hb_ts = float(raw)
+                            pid = 0
+                        if (time.time() - hb_ts) < 3.5:
+                            if pid > 0:
+                                is_running = _is_pid_alive(pid)
+                            else:
+                                is_running = True
+                except Exception:
+                    is_running = False
+
+                if is_running:
+                    # Active window will pick up _store_pending_verification within 250ms
+                    # On Windows, immediately restore & bring it to foreground over maximized terminal!
+                    if sys.platform == "win32":
+                        try:
+                            import ctypes
+                            if hwnd <= 0 and pid > 0:
+                                def _enum_cb(h, extra):
+                                    lp = ctypes.c_ulong()
+                                    ctypes.windll.user32.GetWindowThreadProcessId(h, ctypes.byref(lp))
+                                    if lp.value == pid and ctypes.windll.user32.IsWindowVisible(h):
+                                        extra.append(h)
+                                        return False
+                                    return True
+                                WNDENUMPROC = ctypes.WINFUNCTYPE(ctypes.c_bool, ctypes.c_int, ctypes.py_object)
+                                found = []
+                                ctypes.windll.user32.EnumWindows(WNDENUMPROC(_enum_cb), found)
+                                if found:
+                                    hwnd = found[0]
+
+                            if hwnd > 0:
+                                user32 = ctypes.windll.user32
+                                kernel32 = ctypes.windll.kernel32
+                                user32.ShowWindow(hwnd, 9)  # SW_RESTORE
+                                fg_hwnd = user32.GetForegroundWindow()
+                                fg_thread = user32.GetWindowThreadProcessId(fg_hwnd, None) if fg_hwnd else 0
+                                cur_thread = kernel32.GetCurrentThreadId()
+                                attached = False
+                                if fg_thread and fg_thread != cur_thread:
+                                    attached = bool(user32.AttachThreadInput(cur_thread, fg_thread, True))
+                                swp_flags = 0x0001 | 0x0002 | 0x0040  # SWP_NOSIZE | SWP_NOMOVE | SWP_SHOWWINDOW
+                                user32.SetWindowPos(hwnd, -1, 0, 0, 0, 0, swp_flags)  # HWND_TOPMOST
+                                user32.SetWindowPos(hwnd, -2, 0, 0, 0, 0, swp_flags)  # HWND_NOTOPMOST
+                                user32.BringWindowToTop(hwnd)
+                                user32.SetForegroundWindow(hwnd)
+                                if attached:
+                                    user32.AttachThreadInput(cur_thread, fg_thread, False)
+                        except Exception:
+                            pass
+                    return 0
+                else:
+                    # Stale heartbeat file from dead/crashed process -> clean it up
+                    hb_path.unlink(missing_ok=True)
+        except Exception:
+            pass
+
+        # 3. No active CAT Browser window found -> spawn in background
+        has_qt = _has_module("PySide6") or _has_module("PyQt6")
+        if has_qt:
+            import subprocess
+            exe = sys.executable
+            if sys.platform == "win32":
+                pw = exe.replace("python.exe", "pythonw.exe")
+                if os.path.exists(pw):
+                    exe = pw
+            # Source-checkout support only: a pip-installed CAT already has
+            # `calc_terminal` importable, so never force PYTHONPATH/cwd to a
+            # repo path that does not exist on the user's machine.
+            candidate_root = pathlib.Path(__file__).resolve().parent.parent.parent
+            is_source_checkout = (candidate_root / "calc_terminal").is_dir() and (
+                candidate_root / "main.py"
+            ).exists()
+            env = os.environ.copy()
+            popen_kwargs: dict = {}
+            if is_source_checkout:
+                ws_root = str(candidate_root)
+                ppath = env.get("PYTHONPATH", "")
+                env["PYTHONPATH"] = ws_root + (os.pathsep + ppath if ppath else "")
+                popen_kwargs["cwd"] = ws_root
+            cmd = [exe, "-m", "calc_terminal.host.launcher", "--url", url, "--mode", "browser"]
+            creationflags = 0
+            if sys.platform == "win32":
+                creationflags = subprocess.CREATE_NEW_PROCESS_GROUP
+            try:
+                subprocess.Popen(
+                    cmd,
+                    env=env,
+                    creationflags=creationflags,
+                    close_fds=(sys.platform != "win32"),
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    **popen_kwargs,
+                )
+                return 0
+            except Exception as e:
+                print(f"[CAT Browser] failed to spawn background browser: {e}", file=sys.stderr)
+        return 0
+
+    has_qt = _has_module("PySide6") or _has_module("PyQt6")
+    if has_qt:
+        return _launch_with_qt(start_browser_url, start_mode, repl)
+
+    print("\n[CAT Browser] No browser engine found.", file=sys.stderr)
+    print("Install PySide6 for real HTML/CSS/JS rendering:", file=sys.stderr)
+    print("  pip install PySide6", file=sys.stderr)
+    return 2
+
+
+def _launch_with_qt(start_browser_url, start_mode, repl) -> int:
+    """Create the browser window AND run the event loop. BLOCKS until closed."""
+    try:
+        os.environ.setdefault(
+            "QTWEBENGINE_CHROMIUM_FLAGS",
+            "--disable-dev-shm-usage --enable-gpu-rasterization "
+            "--ignore-gpu-blocklist --enable-zero-copy "
+            "--disable-background-networking --disable-default-apps"
+        )
+        app, created = _ensure_qt_app()
+
+        from .desktop import CATDesktopWindow
+        initial_url = start_browser_url if (start_mode == "browser" or start_browser_url) else None
+        w = CATDesktopWindow(repl=repl, start_browser_url=initial_url)
+        w.show()
+        try:
+            if hasattr(w, "_bring_to_front"):
+                w._bring_to_front()
+            else:
+                w.raise_()
+                w.activateWindow()
+        except Exception:
+            pass
+
+        if created:
+            return app.exec()  # type: ignore
+        return 0
+    except Exception as e:
+        import traceback
+        print(f"[CAT Browser] launch failed: {e}", file=sys.stderr)
+        traceback.print_exc()
+        return 1
+
+
+def create_browser_window(start_browser_url=None, start_mode="browser", repl=None):
+    """Create the browser window WITHOUT starting the event loop.
+
+    Returns (app, window, created_new).
+    Caller MUST call app.exec() after setting up other Qt objects.
+    """
+    os.environ.setdefault(
+        "QTWEBENGINE_CHROMIUM_FLAGS",
+        "--disable-dev-shm-usage --enable-gpu-rasterization "
+        "--ignore-gpu-blocklist --enable-zero-copy "
+        "--disable-background-networking --disable-default-apps"
+    )
+    app, created = _ensure_qt_app()
+
+    from .desktop import CATDesktopWindow
+    initial_url = start_browser_url if (start_mode == "browser" or start_browser_url) else None
+    w = CATDesktopWindow(repl=repl, start_browser_url=initial_url)
+    w.show()
+    try:
+        w.raise_()
+        w.activateWindow()
+    except Exception:
+        pass
+    return app, w, created
+
+
+def main():
+    import argparse
+    p = argparse.ArgumentParser(description="CAT Browser - embedded Chromium")
+    p.add_argument("url_pos", nargs="?", default=None, help="URL to open (positional)")
+    p.add_argument("--url", default=None, help="URL to open")
+    p.add_argument("--mode", choices=["terminal", "browser"], default="browser")
+    p.add_argument("--no-block", action="store_true")
+    p.add_argument("--status", action="store_true")
+    p.add_argument("--fatty", action="store_true", help="Open Fatty CAT Web interface")
+    args = p.parse_args()
+
+    if args.status:
+        import json
+        print(json.dumps(get_host_status(), indent=2))
+        return 0
+
+    start_url = args.url or args.url_pos
+    if args.fatty:
+        start_url = "http://localhost:8765/"
+        args.mode = "browser"
+    elif start_url and "localhost" in start_url and args.mode == "terminal":
+        args.mode = "browser"
+
+    sys.exit(launch_cat_host(
+        start_browser_url=start_url,
+        start_mode=args.mode,
+        block=not args.no_block,
+    ))
+
+
+if __name__ == "__main__":
+    main()

calc_terminal/host/terminal.py

@@ -0,0 +1,279 @@
+"""
+CAT Host — Terminal Embed
+
+Provides the terminal pane inside the graphical CAT Host window.
+
+The host window is a real OS window (Qt/QWebEngine on Windows). This module
+gives it a terminal surface that preserves existing CAT CLI behaviour:
+
+  PowerShell
+    ↓
+  cat  (launcher detects Windows, launches CAT Host)
+    ↓
+  CAT Host OS Window
+    ├── [Terminal]  ← this widget (CAT REPL preserved)
+    ├── [Browser]   ← real QWebEngineView (WebView2/Chromium)
+    ├── [IDE]
+    └── ...
+
+Design decisions:
+* The widget is a plain Qt widget (no external PTY, no xterm.js dependency)
+  so it works with only PySide6 installed.
+* It hosts the existing calc_terminal.app.App REPL logic — the same
+  handle()/handle_question() dispatch the Textual and fallback CLI use.
+  Input from the GUI line edit is fed to App.handle(); output (print())
+  is captured and appended to the read-only log view.
+* ANSI escape sequences from calc_terminal.theme are stripped for the
+  QPlainTextEdit (Qt handles rich text separately). The behaviour and
+  command set are 100% identical to the classic terminal.
+* If the REPL raises, the widget stays alive — the error is shown inline
+  and the prompt returns (same contract as the fallback terminal).
+
+Fomoji: the REPL instance passed in is the same one cli.bootstrap()
+created, so `cat --auth` state is shared.
+"""
+
+from __future__ import annotations
+
+import io
+import re
+import sys
+import contextlib
+import threading
+import traceback
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]|\x1b\].*?\x07|\x1b\(B")
+
+def _strip_ansi(s: str) -> str:
+    return _ANSI_RE.sub("", s)
+
+
+# ---------------------------------------------------------------------------
+# Fallback when Qt not installed — import-time safe so the host package
+# can be imported on headless CI.
+# ---------------------------------------------------------------------------
+try:
+    from PySide6.QtWidgets import (
+        QWidget, QVBoxLayout, QHBoxLayout, QPlainTextEdit,
+        QLineEdit, QLabel, QPushButton
+    )
+    from PySide6.QtCore import Qt, Signal, Slot
+    from PySide6.QtGui import QFont, QTextCursor
+    _QT_AVAILABLE = True
+except ImportError:
+    try:
+        from PyQt6.QtWidgets import (
+            QWidget, QVBoxLayout, QHBoxLayout, QPlainTextEdit,
+            QLineEdit, QLabel, QPushButton
+        )
+        from PyQt6.QtCore import Qt, pyqtSignal as Signal, pyqtSlot as Slot
+        from PyQt6.QtGui import QFont, QTextCursor
+        _QT_AVAILABLE = True
+    except ImportError:
+        _QT_AVAILABLE = False
+        QWidget = object  # type: ignore
+        Signal = lambda *a, **k: None  # type: ignore
+
+
+if _QT_AVAILABLE:
+
+    class CATTerminalWidget(QWidget):
+        """
+        Graphical terminal pane for CAT Host.
+
+        Hosts calc_terminal.app.App (the REPL/product logic) and exposes
+        it through a Qt input line + scrollback. The host window owns the
+        layout; this widget owns only the terminal chrome.
+
+        Usage:
+            repl = App()  # from calc_terminal.app
+            term = CATTerminalWidget(repl)
+            stacked.addWidget(term)
+        """
+
+        # Emitted on every command so the host can mirror to status bar
+        commandEntered = Signal(str)
+
+        def __init__(self, repl=None, parent=None):
+            super().__init__(parent)
+            self.repl = repl
+            self._history: list[str] = []
+            self._history_idx: int = -1
+            self._setup_ui()
+            self._print_boot()
+
+        def _setup_ui(self):
+            layout = QVBoxLayout(self)
+            layout.setContentsMargins(6, 6, 6, 6)
+            layout.setSpacing(6)
+
+            # Header — shows we are the real CAT terminal, not a plain shell
+            header = QLabel("CAT TERMINAL  —  type /help  ·  /browser  ·  /agent  ·  Ctrl+Shift+B → Browser")
+            header.setStyleSheet("color: #878caf; font-size: 11px; padding: 2px 4px;")
+            layout.addWidget(header)
+
+            # Scrollback — read-only, selectable
+            self.log = QPlainTextEdit()
+            self.log.setReadOnly(True)
+            self.log.setLineWrapMode(QPlainTextEdit.LineWrapMode.WidgetWidth)
+            font = QFont("Consolas" if sys.platform == "win32" else "Monospace", 10)
+            font.setStyleHint(QFont.StyleHint.Monospace)
+            self.log.setFont(font)
+            # Dark terminal palette matching CAT themes
+            self.log.setStyleSheet(
+                "QPlainTextEdit { background: #1a1b26; color: #e8ebfa; "
+                "border: 1px solid #2a2e48; border-radius: 6px; padding: 6px; "
+                "selection-background-color: #82aaff; }"
+            )
+            layout.addWidget(self.log, 1)
+
+            # Input row — glyph + line edit + send
+            row = QHBoxLayout()
+            row.setSpacing(6)
+            glyph = QLabel("❯")
+            glyph.setStyleSheet("color: #82aaff; font-weight: bold; font-size: 14px; padding-left: 4px;")
+            glyph.setFixedWidth(22)
+            row.addWidget(glyph)
+
+            self.input = QLineEdit()
+            self.input.setPlaceholderText("Type a command or question…  (/help for list)")
+            self.input.setStyleSheet(
+                "QLineEdit { background: #1e2030; color: #e8ebfa; "
+                "border: 1px solid #2a2e48; border-radius: 999px; padding: 6px 12px; "
+                "selection-background-color: #82aaff; }"
+                "QLineEdit:focus { border: 1px solid #82aaff; }"
+            )
+            self.input.returnPressed.connect(self._on_submit)
+            row.addWidget(self.input, 1)
+
+            send = QPushButton("↵")
+            send.setFixedSize(32, 28)
+            send.setToolTip("Send (Enter)")
+            send.setStyleSheet(
+                "QPushButton { background: #82aaff; color: #1a1b26; border: none; "
+                "border-radius: 14px; font-weight: bold; }"
+                "QPushButton:hover { background: #9ab8ff; }"
+            )
+            send.clicked.connect(self._on_submit)
+            row.addWidget(send)
+
+            layout.addLayout(row)
+            self.input.setFocus()
+
+        # --------------------------------------------------------------- I/O --
+
+        def _append(self, text: str):
+            """Append text to scrollback, stripping ANSI for Qt."""
+            if not text:
+                return
+            clean = _strip_ansi(text)
+            # QPlainTextEdit.appendPlainText adds a newline; for multi-line
+            # captures we insert as single block to preserve formatting.
+            self.log.appendPlainText(clean.rstrip("\n"))
+            # Autoscroll
+            cursor = self.log.textCursor()
+            cursor.movePosition(QTextCursor.MoveOperation.End)
+            self.log.setTextCursor(cursor)
+
+        def _print_boot(self):
+            if self.repl is None:
+                self._append("CAT terminal ready — no REPL attached (UI preview mode).")
+                self._append("Run `cat` from PowerShell to attach the real session.")
+                return
+            # Capture the classic boot/home output (same as fallback CLI)
+            buf = io.StringIO()
+            try:
+                with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
+                    # theme.enable_windows_ansi + load_saved_theme are already
+                    # done by cli.bootstrap(); just print home.
+                    try:
+                        self.repl.print_home()
+                    except Exception:
+                        # Fallback if print_home fails early
+                        print(f"CAT v{getattr(self.repl, 'VERSION', '?')} — ready", file=buf)
+            except Exception as e:
+                buf.write(f"[boot warning: {e}]\n")
+            out = buf.getvalue()
+            if out.strip():
+                self._append(out)
+            else:
+                self._append(f"CAT v{getattr(self.repl, 'VERSION', '0.7.9')} — ready. Type /help")
+
+        def _on_submit(self):
+            raw = self.input.text()
+            if raw is None:
+                return
+            raw = raw.strip()
+            if not raw:
+                return
+            # History
+            self._history.append(raw)
+            del self._history[:-200]
+            self._history_idx = len(self._history)
+            self.input.clear()
+            self._append(f"\n❯ {raw}")
+            self.commandEntered.emit(raw)
+
+            if self.repl is None:
+                self._append("(no REPL — echo only)")
+                return
+
+            # Special: clear
+            if raw.lower() in ("/clear", "/home", "clear", "cls"):
+                self.log.clear()
+                self._print_boot()
+                return
+
+            # Dispatch to the real REPL, capturing its print() output
+            buf = io.StringIO()
+            try:
+                with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
+                    self.repl.handle(raw)
+            except SystemExit:
+                # /exit /quit — don't kill host window, just note it
+                self._append("\n[Use the window close button or Ctrl+Q to quit CAT Host]")
+                # Still show any buffered output
+            except Exception as e:
+                buf.write(f"\n[error: {type(e).__name__}: {e}]\n")
+                traceback.print_exc(file=buf)
+            out = buf.getvalue()
+            if out:
+                self._append(out)
+
+        # --------------------------------------------------------- public API --
+
+        def focus_input(self):
+            self.input.setFocus()
+            self.input.selectAll()
+
+        def execute(self, raw: str):
+            """Programmatic entry — used by host for /browser shortcuts."""
+            self.input.setText(raw)
+            self._on_submit()
+
+        def keyPressEvent(self, event):
+            # History navigation with Up/Down when input is focused
+            try:
+                if event.key() == Qt.Key.Key_Up:
+                    if self.input.hasFocus() and self._history:
+                        self._history_idx = max(0, self._history_idx - 1)
+                        self.input.setText(self._history[self._history_idx])
+                        return
+                elif event.key() == Qt.Key.Key_Down:
+                    if self.input.hasFocus() and self._history:
+                        if self._history_idx >= len(self._history) - 1:
+                            self._history_idx = len(self._history)
+                            self.input.clear()
+                        else:
+                            self._history_idx += 1
+                            self.input.setText(self._history[self._history_idx])
+                        return
+            except Exception:
+                pass
+            super().keyPressEvent(event)
+
+else:
+    # Stub so `from .terminal import CATTerminalWidget` never crashes
+    class CATTerminalWidget:  # type: ignore
+        def __init__(self, *a, **k):
+            raise ImportError("Qt not installed — CAT Host requires PySide6 (pip install PySide6)")