cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/ui/thinking.py

@@ -0,0 +1,226 @@
+"""
+CCT UI — thinking.py: the "Advanced AI Response Animation System" (spec
+item #25). Pure logic + formatting helpers only — no Textual dependency,
+no widgets. composer.py's live status bar and conversation.py's
+completion-summary line are the only two things that render what this
+module computes; this file just decides *what* to show (stage label,
+color, spinner frame, elapsed-time text) and never *how* to paint it.
+
+Kept dependency-free on purpose: stage detection and timer formatting
+are simple enough to unit test directly, and staying importable outside
+Textual means the fallback CLI could reuse the same stage vocabulary
+later without dragging in ui/ at all.
+"""
+
+if __name__ == "__main__":
+    print("This is a library file and is not meant to be run directly.")
+    import sys
+    sys.exit(1)
+
+import re
+
+# ---------------------------------------------------------- spinner styles
+# Animation Style 1 / 2 / 3 from the spec.
+DOT_FRAMES = ["\u25cf\u25cb\u25cb\u25cb\u25cb", "\u25cf\u25cf\u25cb\u25cb\u25cb",
+              "\u25cf\u25cf\u25cf\u25cb\u25cb", "\u25cf\u25cf\u25cf\u25cf\u25cb",
+              "\u25cf\u25cf\u25cf\u25cf\u25cf"]
+BRAILLE_FRAMES = ["\u280b", "\u2819", "\u2839", "\u2838", "\u283c", "\u2834",
+                   "\u2826", "\u2827", "\u2807", "\u280f"]
+BLOCK_FRAMES = ["\u25a1\u25a1\u25a1\u25a1\u25a1\u25a1\u25a1\u25a1",
+                 "\u25a0\u25a0\u25a1\u25a1\u25a1\u25a1\u25a1\u25a1",
+                 "\u25a0\u25a0\u25a0\u25a0\u25a1\u25a1\u25a1\u25a1",
+                 "\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a1\u25a1",
+                 "\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0\u25a0"]
+
+STYLES = {"dots": DOT_FRAMES, "braille": BRAILLE_FRAMES, "blocks": BLOCK_FRAMES}
+
+
+def spinner_frame(style, tick):
+    """Loops continuously, per spec ('Loop until completion')."""
+    frames = STYLES.get(style, BRAILLE_FRAMES)
+    return frames[tick % len(frames)]
+
+
+# --------------------------------------------------------------- stages --
+# stage_key -> (display label, COLOR ROLE, spinner style).
+#
+# v0.7.9.0 LIGHT-MODE FIX: the second tuple slot used to be a hardcoded
+# Tokyo-Night hex (#7aa2f7, #9ece6a, #e0af68...). Those pastels are
+# unreadable on the light theme's white surfaces — several fall below
+# 2:1 contrast. Colors are now semantic ROLES resolved through
+# theme.role_hex() at CALL time (see stage_info), so dark keeps its
+# exact Tokyo Night values and light automatically gets its darker,
+# readable palette. `style` is just which of the three animation styles
+# best fits that stage's feel.
+STAGES = {
+    "preparing":   ("Preparing",                 "blue",    "braille"),
+    "thinking":    ("Thinking",                  "blue",    "braille"),
+    "web":         ("Searching Web",             "cyan",    "dots"),
+    "knowledge":   ("Searching Knowledge",       "cyan",    "dots"),
+    "notebook":    ("Searching Notebook",        "cyan",    "dots"),
+    "formula_db":  ("Searching Formula Database", "cyan",   "dots"),
+    "quantum_lib": ("Searching Quantum Library",  "cyan",   "dots"),
+    "analyzing":   ("Analyzing Question",        "blue",    "braille"),
+    "calc":        ("Running Calculation",       "amber",   "blocks"),
+    "simulation":  ("Running Simulation",        "purple",  "blocks"),
+    "sim3d":       ("Rendering 3D Simulation",   "purple",  "blocks"),
+    "graph":       ("Rendering Graph",           "purple",  "blocks"),
+    "html":        ("Generating HTML",           "magenta", "braille"),
+    "code":        ("Executing Code",            "magenta", "braille"),
+    "building":    ("Building Response",         "blue",    "braille"),
+    "formatting":  ("Formatting Result",         "blue",    "dots"),
+    "finalizing":  ("Finalizing",                "blue",    "dots"),
+    "debugging":   ("Debugging",                 "red",     "braille"),
+    "installing":  ("Installing Package",        "amber",   "blocks"),
+    "done":        ("Completed",                 "green",   "dots"),
+    "error":       ("Error",                     "red",     "dots"),
+}
+
+# Role -> theme.color-role used by theme.role_hex(). "magenta" maps to
+# the purple family in both palettes.
+_ROLE_MAP = {
+    "blue": "blue", "cyan": "cyan", "purple": "purple",
+    "magenta": "purple", "amber": "amber", "green": "green",
+    "red": "red", "gray": "gray",
+}
+
+DEFAULT_STAGE = "thinking"
+
+# Elapsed-time fallback used once no keyword signal fires — keeps the
+# indicator visibly alive on a plain, keyword-free question instead of
+# freezing on one word the whole time it's waiting on the model.
+_PRE_TOKEN_PROGRESSION = ["preparing", "thinking", "analyzing"]
+_POST_TOKEN_PROGRESSION = ["building", "formatting", "finalizing"]
+
+# "Smart Status Detection": prompt keywords -> stage. Order matters —
+# first match wins, most specific first.
+_KEYWORD_STAGES = [
+    (("/research", "deep research"), "web"),
+    (("/websearch", "web search", "search the web", "search online"), "web"),
+    (("/install", "/packages", "install ", "pip install", "npm install", "setup "), "installing"),
+    (("/debug", "debug this", "fix this bug", "error message", "traceback", "why is this failing"), "debugging"),
+    (("/pipeline", "build me a", "build us an", "build a full"), "building"),
+    (("/orbitals", "orbital", "quantum library", "electron cloud"), "quantum_lib"),
+    (("/atomsim", "/sim3d", "3d simulation", "atomic simulation"), "sim3d"),
+    (("/react", "reaction sim", "kinetics ode", "equilibrium ode", "simulate"), "simulation"),
+    (("/graph", "plot ", "plot a", "graph of", "draw a graph"), "graph"),
+    (("/codepad", "```", "write code", "generate code", "run python"), "code"),
+    (("render html", "generate html", "html report"), "html"),
+    (("/formulas", "formula database", "formula library"), "formula_db"),
+    (("/history", "notebook", "past numericals"), "notebook"),
+    (("/solve", "calculate", "compute", "solve for", "/calculator"), "calc"),
+]
+
+
+def detect_stage(prompt, elapsed, chunk_count=0):
+    """Best-effort stage for a moment in time. `prompt` drives an early,
+    strong keyword match (what's about to happen is real signal); once
+    tokens are already streaming (`chunk_count > 0`) with nothing more
+    specific detected, elapsed time alone walks the generic
+    building -> formatting -> finalizing tail so the status bar keeps
+    moving instead of sitting still for the rest of the response."""
+    text = (prompt or "").lower()
+    for keywords, stage in _KEYWORD_STAGES:
+        if any(k in text for k in keywords):
+            return stage
+
+    progression = _POST_TOKEN_PROGRESSION if chunk_count else _PRE_TOKEN_PROGRESSION
+    idx = min(int(elapsed // 1.4), len(progression) - 1)
+    return progression[idx]
+
+
+def stage_info(stage_key):
+    """(label, hex_color, spinner_style) for a stage key, defaulting to
+    'thinking' for anything unrecognized so callers never need a guard.
+
+    The hex is resolved from the CURRENT theme at call time (dark =
+    Tokyo Night values as before; light = its darker, readable
+    palette), so a live /theme switch recolors every spinner/status on
+    the next tick without any extra wiring."""
+    label, role, style = STAGES.get(stage_key, STAGES[DEFAULT_STAGE])
+    try:
+        from .. import theme
+        color = theme.role_hex(_ROLE_MAP.get(role, "blue"))
+    except Exception:
+        # Dependency-free fallbacks matching the DARK theme (the
+        # classic terminal may import this module before theme setup).
+        _DARK_FALLBACK = {"blue": "#7aa2f7", "cyan": "#7dcfff",
+                          "purple": "#bb9af7", "magenta": "#bb9af7",
+                          "amber": "#e0af68", "green": "#9ece6a",
+                          "red": "#f7768e"}
+        color = _DARK_FALLBACK.get(role, "#7aa2f7")
+    return label, color, style
+
+
+def format_timer(elapsed):
+    """0.1 s / 1.2 s / 5.8 s under a minute; mm:ss beyond, matching the
+    spec's live-timer examples exactly for the common case."""
+    if elapsed < 0:
+        elapsed = 0.0
+    if elapsed < 60:
+        return f"{elapsed:.1f} s"
+    minutes, seconds = divmod(int(elapsed), 60)
+    return f"{minutes}:{seconds:02d}"
+
+
+# ---------------------------------------------------- idle chemistry icons
+IDLE_ICONS = ["\u269b", "\U0001f9ea", "\U0001f9ec", "\u2601"]  # ⚛ 🧪 🧬 ☁
+
+
+def idle_icon(tick):
+    return IDLE_ICONS[tick % len(IDLE_ICONS)]
+
+
+# --------------------------------------------------------- command usage --
+_SLASH_CMD_RE = re.compile(r"(?<!\S)/[a-zA-Z][a-zA-Z\-]*")
+
+
+def commands_used(*texts):
+    """Slash commands mentioned across the given texts (prompt +
+    response), de-duplicated and sorted, for the completion summary's
+    'Commands Used' line."""
+    found = set()
+    for text in texts:
+        if not text:
+            continue
+        found.update(m.group(0) for m in _SLASH_CMD_RE.finditer(text))
+    return sorted(found)
+
+
+# ------------------------------------------------------- completion block
+def completion_summary_lines(*, provider=None, model=None, duration=None,
+                              tokens=None, commands=None, extras=None):
+    """Rich-markup lines for the 'Message Completion' block the spec
+    describes (✓ Response Complete / Provider / Model / Time / Tokens /
+    Commands Used / feature flags). Returns a list of markup strings —
+    rendering them is the caller's job (conversation.py turns each into
+    a Text.from_markup line under the finished bubble).
+
+    v0.7.9.0: the ✓ color resolves from the CURRENT theme (was a
+    hardcoded dark-palette green that washed out in light mode)."""
+    try:
+        from .. import theme
+        ok_hex = theme.role_hex("green")
+    except Exception:
+        ok_hex = "#9ece6a"
+    lines = [f"[{ok_hex}]\u2713 Response Complete[/]"]
+
+    meta = []
+    if provider:
+        meta.append(f"Provider: {provider}")
+    if model:
+        meta.append(f"Model: {model}")
+    if duration is not None:
+        meta.append(f"Time: {format_timer(duration)}")
+    if tokens:
+        meta.append(f"Tokens: {tokens}")
+    if meta:
+        lines.append("[dim]" + "  \u00b7  ".join(meta) + "[/dim]")
+
+    if commands:
+        lines.append("[dim]Commands used: " + ", ".join(commands) + "[/dim]")
+
+    if extras:
+        lines.append("[dim]" + "  \u00b7  ".join(extras) + "[/dim]")
+
+    return lines

calc_terminal/ui/timeline_panel.py

@@ -0,0 +1,102 @@
+"""
+CCT UI — timeline_panel.py: Session Timeline panel (v0.7.2 roadmap).
+Real Screen push (same family as context_menu.py/header.py's
+PermissionModeMenu — this package's standing "no floating popup
+windows" rule), showing calc_terminal/timeline.py's event log with a
+live search box and per-topic filter chips. "Jump to event" opens the
+related file in the Editor if it still exists on disk; "Restore
+previous state" is the roadmap's own named FUTURE feature and isn't
+implemented here.
+"""
+
+if __name__ == "__main__":
+    print("This is a library file and is not meant to be run directly.")
+    import sys
+    sys.exit(1)
+
+import os
+
+from .. import timeline
+from .events import FileOpenRequested
+
+TEXTUAL_AVAILABLE = True
+try:
+    from textual.containers import Vertical, Horizontal, VerticalScroll
+    from textual.screen import Screen
+    from textual.widgets import Static, Input, Button
+except Exception:
+    TEXTUAL_AVAILABLE = False
+
+
+if TEXTUAL_AVAILABLE:
+
+    class _TimelineRow(Static):
+        def __init__(self, event):
+            super().__init__(event.line(), classes="cct-timeline-row")
+            self._event = event
+
+        def on_click(self, ev):
+            if self._event.related_file and os.path.isfile(self._event.related_file):
+                self.post_message(FileOpenRequested(self._event.related_file))
+
+    class TimelinePanel(Screen):
+        """Full event log. `_filter_topic`, when set, narrows to one
+        eventbus topic; the search box narrows further by substring
+        (timeline.search) on top of that. Both apply together, list
+        re-rendered via _render_rows() rather than a full recompose."""
+
+        CSS = """
+        TimelinePanel { align: center middle; background: $app-background 60%; }
+        #cct-timeline-box {
+            width: 84%; height: 80%; background: $surface;
+            border: round $border; padding: 1 2;
+        }
+        #cct-timeline-header { height: 1; }
+        #cct-timeline-search { margin-bottom: 1; }
+        #cct-timeline-list { height: 1fr; }
+        .cct-timeline-row { height: 1; color: $text; padding: 0 1; }
+        .cct-timeline-row:hover { color: $accent; }
+        #cct-timeline-empty { color: $text-faint; padding: 1; }
+        """
+
+        def __init__(self):
+            super().__init__()
+            self._query = ""
+
+        def compose(self):
+            with Vertical(id="cct-timeline-box"):
+                with Horizontal(id="cct-timeline-header"):
+                    yield Static("[b]Session Timeline[/b]")
+                    yield Button("Close", id="cct-timeline-close")
+                yield Input(placeholder="Search timeline\u2026", id="cct-timeline-search")
+                yield VerticalScroll(id="cct-timeline-list")
+
+        def on_mount(self):
+            self._render_rows()
+
+        def _render_rows(self):
+            box = self.query_one("#cct-timeline-list", VerticalScroll)
+            for child in list(box.children):
+                child.remove()
+            evs = timeline.search(self._query)
+            if not evs:
+                box.mount(Static("No matching activity yet.", id="cct-timeline-empty"))
+                return
+            for ev in evs[:200]:
+                box.mount(_TimelineRow(ev))
+
+        def on_input_changed(self, event):
+            if event.input.id == "cct-timeline-search":
+                self._query = event.value
+                self._render_rows()
+
+        def on_button_pressed(self, event):
+            if event.button.id == "cct-timeline-close":
+                self.dismiss(None)
+
+        def on_key(self, event):
+            if event.key == "escape":
+                self.dismiss(None)
+
+else:
+    TimelinePanel = None

calc_terminal/ui/todo_panel.py

@@ -0,0 +1,193 @@
+"""
+CCT UI — todo_panel.py: AI Todo Manager panel (v0.7.2 roadmap). Real
+Screen push over calc_terminal/todos.py's per-workspace JSON store —
+add, complete/reopen, delete, search, and filter by status, plus a
+live progress bar. Priority is settable at creation (cycles low/
+normal/high via a click on the priority badge); due dates and full
+in-place text editing are accepted from todos.update_todo() but this
+pass's UI only exposes add/toggle/delete/priority-cycle/search/filter
+— see the module docstring in todos.py for what's genuinely
+implemented vs. deferred.
+
+The roadmap's own mockup nests this under a "Main Menu" (Workspace /
+Recent Projects / AI Todo / Settings / Extensions / Documentation)
+that doesn't exist anywhere in this codebase yet — header.py's
+hamburger glyph is a plain sidebar-visibility toggle, and Settings/
+Extensions/Documentation aren't panels here either. Building a whole
+new main-menu hierarchy just to host this one panel would be scope
+creep well beyond "add a Todo Manager", so this is exposed the same
+way TimelinePanel is: a dedicated `/todo` command, following this
+codebase's existing pattern for every other panel (/permissions,
+/workspace, /model, etc.) rather than a menu system that has no other
+reason to exist yet.
+"""
+
+if __name__ == "__main__":
+    print("This is a library file and is not meant to be run directly.")
+    import sys
+    sys.exit(1)
+
+from .. import todos
+
+TEXTUAL_AVAILABLE = True
+try:
+    from textual.containers import Vertical, Horizontal, VerticalScroll
+    from textual.screen import Screen
+    from textual.widgets import Static, Input, Button, ProgressBar
+except Exception:
+    TEXTUAL_AVAILABLE = False
+
+_PRIORITY_GLYPH = {"low": "\u25bd", "normal": "\u25cb", "high": "\u25b3"}
+
+
+if TEXTUAL_AVAILABLE:
+
+    class _TodoRow(Horizontal):
+        def __init__(self, todo):
+            super().__init__(classes="cct-todo-row")
+            self.todo = todo
+
+        def compose(self):
+            box = "\u2611" if self.todo["status"] == "done" else "\u2610"
+            style = "strike dim" if self.todo["status"] == "done" else ""
+            source = " [dim](AI)[/]" if self.todo.get("source") == "ai" else ""
+            yield Static(box, classes="cct-todo-check", id=f"cct-todo-check-{self.todo['id']}")
+            yield Static(_PRIORITY_GLYPH.get(self.todo["priority"], "\u25cb"),
+                         classes="cct-todo-priority", id=f"cct-todo-pri-{self.todo['id']}")
+            label = f"[{style}]{self.todo['text']}[/]" if style else self.todo["text"]
+            yield Static(label + source, classes="cct-todo-text")
+            yield Button("\u2715", classes="cct-todo-delete", id=f"cct-todo-del-{self.todo['id']}")
+
+    class TodoPanel(Screen):
+        """AI Todo Manager. `workspace` scopes the list to the currently
+        open project (or None for the global/no-folder list) — see
+        todos.py's module docstring on why todos are per-workspace."""
+
+        CSS = """
+        TodoPanel { align: center middle; background: $app-background 60%; }
+        #cct-todo-box {
+            width: 84%; height: 80%; background: $surface;
+            border: round $border; padding: 1 2;
+        }
+        #cct-todo-header { height: 1; }
+        #cct-todo-progress-row { height: 1; padding: 0 0 1 0; }
+        #cct-todo-add-row { height: 3; padding-bottom: 1; }
+        #cct-todo-add-row Input { width: 1fr; }
+        #cct-todo-filters { height: 1; padding-bottom: 1; }
+        #cct-todo-filters Button { margin-right: 1; min-width: 10; }
+        #cct-todo-search { margin-bottom: 1; }
+        #cct-todo-list { height: 1fr; }
+        .cct-todo-row { height: 1; padding: 0 1; }
+        .cct-todo-row:hover { color: $accent; }
+        .cct-todo-check { width: 3; }
+        .cct-todo-priority { width: 3; color: $warning; }
+        .cct-todo-text { width: 1fr; }
+        .cct-todo-delete { min-width: 3; height: 1; border: none; color: $error; }
+        #cct-todo-empty { color: $text-faint; padding: 1; }
+        """
+
+        def __init__(self, workspace=None):
+            super().__init__()
+            self._workspace = workspace
+            self._query = ""
+            self._filter = "all"  # all | pending | done
+
+        def compose(self):
+            with Vertical(id="cct-todo-box"):
+                with Horizontal(id="cct-todo-header"):
+                    yield Static("[b]AI Todo[/b]")
+                    yield Button("Close", id="cct-todo-close")
+                with Horizontal(id="cct-todo-progress-row"):
+                    yield Static("", id="cct-todo-progress-label")
+                    yield ProgressBar(id="cct-todo-progress", show_eta=False)
+                with Horizontal(id="cct-todo-add-row"):
+                    yield Input(placeholder="Add a task and press Enter\u2026", id="cct-todo-add")
+                with Horizontal(id="cct-todo-filters"):
+                    yield Button("All", id="cct-todo-filter-all", variant="primary")
+                    yield Button("Pending", id="cct-todo-filter-pending")
+                    yield Button("Done", id="cct-todo-filter-done")
+                yield Input(placeholder="Search\u2026", id="cct-todo-search")
+                yield VerticalScroll(id="cct-todo-list")
+
+        def on_mount(self):
+            self._render()
+
+        def _render(self):
+            frac, done, total = todos.progress(self._workspace)
+            self.query_one("#cct-todo-progress-label", Static).update(
+                f"{done}/{total} complete" if total else "No tasks yet")
+            try:
+                self.query_one("#cct-todo-progress", ProgressBar).update(total=1.0, progress=frac)
+            except Exception:
+                pass
+            items = todos.list_todos(self._workspace)
+            if self._filter == "pending":
+                items = [t for t in items if t["status"] != "done"]
+            elif self._filter == "done":
+                items = [t for t in items if t["status"] == "done"]
+            if self._query:
+                q = self._query.lower()
+                items = [t for t in items if q in t["text"].lower()]
+            box = self.query_one("#cct-todo-list", VerticalScroll)
+            for child in list(box.children):
+                child.remove()
+            if not items:
+                box.mount(Static("Nothing here.", id="cct-todo-empty"))
+                return
+            for t in items:
+                box.mount(_TodoRow(t))
+
+        def on_input_submitted(self, event):
+            if event.input.id == "cct-todo-add":
+                todos.add_todo(event.value, workspace=self._workspace, source="manual")
+                event.input.value = ""
+                self._render()
+
+        def on_input_changed(self, event):
+            if event.input.id == "cct-todo-search":
+                self._query = event.value
+                self._render()
+
+        def on_button_pressed(self, event):
+            bid = event.button.id or ""
+            if bid == "cct-todo-close":
+                self.dismiss(None)
+                return
+            if bid.startswith("cct-todo-filter-"):
+                self._filter = bid.rsplit("-", 1)[1]
+                for b in self.query("#cct-todo-filters Button"):
+                    b.variant = "primary" if b.id == bid else "default"
+                self._render()
+                return
+            if bid.startswith("cct-todo-del-"):
+                todo_id = int(bid.rsplit("-", 1)[1])
+                todos.delete_todo(todo_id, workspace=self._workspace)
+                self._render()
+                return
+
+        def on_click(self, event):
+            widget = getattr(event, "widget", None)
+            wid = getattr(widget, "id", "") or ""
+            if wid.startswith("cct-todo-check-"):
+                todo_id = int(wid.rsplit("-", 1)[1])
+                current = next((t for t in todos.list_todos(self._workspace) if t["id"] == todo_id), None)
+                if current:
+                    new_status = "pending" if current["status"] == "done" else "done"
+                    todos.set_status(todo_id, new_status, workspace=self._workspace)
+                    self._render()
+            elif wid.startswith("cct-todo-pri-"):
+                todo_id = int(wid.rsplit("-", 1)[1])
+                current = next((t for t in todos.list_todos(self._workspace) if t["id"] == todo_id), None)
+                if current:
+                    order = ("low", "normal", "high")
+                    nxt = order[(order.index(current["priority"]) + 1) % len(order)] \
+                        if current["priority"] in order else "normal"
+                    todos.update_todo(todo_id, workspace=self._workspace, priority=nxt)
+                    self._render()
+
+        def on_key(self, event):
+            if event.key == "escape":
+                self.dismiss(None)
+
+else:
+    TodoPanel = None

calc_terminal/ui/viewport.py

@@ -0,0 +1,136 @@
+"""
+CAT CLI — CATRootViewport: Shared Responsive Viewport Engine.
+
+Provides unified terminal dimension measuring, responsive breakpoints,
+and full-screen layout constraints (100% width/height) to eliminate
+the top-left corner shrinkage glitch across Provider, User, and Settings screens.
+"""
+
+from typing import Optional, Callable
+import shutil
+
+try:
+    from textual.screen import Screen
+    from textual.containers import Container
+    from textual.reactive import reactive
+    from textual.events import Resize
+    TEXTUAL_OK = True
+except ImportError:
+    Screen = object  # type: ignore
+    Container = object  # type: ignore
+    TEXTUAL_OK = False
+
+
+# Breakpoint definitions
+BP_LARGE = 100
+BP_MEDIUM = 80
+BP_SMALL = 60
+
+
+def get_terminal_size_class(width: Optional[int] = None) -> str:
+    """Return responsive size class ('large', 'medium', 'small', 'very_small')
+    based on current terminal or specified width."""
+    if width is None:
+        try:
+            cols, _ = shutil.get_terminal_size((80, 24))
+            width = cols
+        except Exception:
+            width = 80
+
+    if width >= BP_LARGE:
+        return "large"
+    elif width >= BP_MEDIUM:
+        return "medium"
+    elif width >= BP_SMALL:
+        return "small"
+    return "very_small"
+
+
+if TEXTUAL_OK:
+    class CATRootViewport(Container):
+        """Root container that guarantees 100% width and height and adapts
+
+        its child layout to the terminal viewport dimensions.
+        """
+        DEFAULT_CSS = """
+        CATRootViewport {
+            width: 100%;
+            height: 100%;
+            min-width: 100%;
+            min-height: 100%;
+            layout: vertical;
+            padding: 0;
+            margin: 0;
+            overflow: hidden;
+        }
+        """
+
+        size_class = reactive("large")
+
+        def __init__(self, *children, on_size_change: Optional[Callable[[str], None]] = None, **kwargs):
+            super().__init__(*children, **kwargs)
+            self._on_size_change = on_size_change
+
+        def on_mount(self) -> None:
+            self._update_size_class()
+
+        def on_resize(self, event: Resize) -> None:
+            self._update_size_class(event.size.width)
+
+        def _update_size_class(self, width: Optional[int] = None) -> None:
+            w = width if width is not None else (self.size.width or 80)
+            new_cls = get_terminal_size_class(w)
+            if new_cls != self.size_class:
+                self.size_class = new_cls
+                # Update CSS classes for styling hooks (.viewport-large, etc.)
+                for cls_name in ("viewport-large", "viewport-medium", "viewport-small", "viewport-very-small"):
+                    self.remove_class(cls_name)
+                self.add_class(f"viewport-{new_cls.replace('_', '-')}")
+                if self._on_size_change:
+                    try:
+                        self._on_size_change(new_cls)
+                    except Exception:
+                        pass
+
+
+    class CATViewportScreenMixin:
+        """Mixin for Textual Screen subclasses ensuring full terminal viewport
+
+        inheritance, proper resize dispatch, and lifecycle cleanup.
+        """
+        DEFAULT_CSS = """
+        Screen {
+            width: 100%;
+            height: 100%;
+            min-width: 100%;
+            min-height: 100%;
+            padding: 0;
+            margin: 0;
+        }
+        """
+
+        def get_current_size_class(self) -> str:
+            w = getattr(self.size, "width", 0) or getattr(getattr(self, "app", None), "size", None)
+            if hasattr(w, "width"):
+                width_val = w.width
+            elif isinstance(w, int) and w > 0:
+                width_val = w
+            else:
+                cols, _ = shutil.get_terminal_size((80, 24))
+                width_val = cols
+            return get_terminal_size_class(width_val)
+
+        def on_resize(self, event: Resize) -> None:
+            size_class = get_terminal_size_class(event.size.width)
+            if hasattr(self, "on_viewport_resized"):
+                try:
+                    self.on_viewport_resized(size_class, event.size.width, event.size.height)
+                except Exception:
+                    pass
+
+else:
+    class CATRootViewport:  # type: ignore
+        pass
+
+    class CATViewportScreenMixin:  # type: ignore
+        pass