cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/editor/commands.py

@@ -0,0 +1,160 @@
+"""CAT Code Editor — Command Registry (calc_terminal/editor/commands.py).
+
+Centralized registration and execution of all editor, preview, and workbench commands.
+UI components, buttons, menus, and shortcuts invoke commands through this registry.
+"""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+
+@dataclass
+class CATCommand:
+    """Definition of an executable command inside CAT IDE."""
+    id: str
+    title: str
+    category: str = "General"
+    handler: Optional[Callable[[Optional[dict]], Any]] = None
+    can_execute: Optional[Callable[[Optional[dict]], bool]] = None
+    default_keybinding: Optional[str] = None
+    description: str = ""
+
+
+class CommandRegistry:
+    """Central registry of all CAT IDE commands."""
+
+    def __init__(self) -> None:
+        self._commands: Dict[str, CATCommand] = {}
+        self._register_defaults()
+
+    def register(self, command: CATCommand) -> None:
+        """Register or override a command."""
+        self._commands[command.id] = command
+
+    def unregister(self, command_id: str) -> bool:
+        """Unregister a command by ID."""
+        if command_id in self._commands:
+            del self._commands[command_id]
+            return True
+        return False
+
+    def get(self, command_id: str) -> Optional[CATCommand]:
+        """Look up a command by its ID."""
+        return self._commands.get(command_id)
+
+    def can_execute(self, command_id: str, context: Optional[dict] = None) -> bool:
+        """Check if a command can currently execute."""
+        cmd = self.get(command_id)
+        if not cmd:
+            return False
+        if cmd.can_execute is not None:
+            try:
+                return bool(cmd.can_execute(context))
+            except Exception:
+                return False
+        return cmd.handler is not None
+
+    def execute(self, command_id: str, context: Optional[dict] = None) -> Any:
+        """Execute a registered command by its ID."""
+        cmd = self.get(command_id)
+        if not cmd:
+            raise KeyError(f"Command '{command_id}' is not registered.")
+        if not self.can_execute(command_id, context):
+            return None
+        if cmd.handler is None:
+            return None
+        try:
+            sig = inspect.signature(cmd.handler)
+            if len(sig.parameters) == 0:
+                return cmd.handler()
+            return cmd.handler(context)
+        except TypeError:
+            try:
+                return cmd.handler(context)
+            except Exception:
+                return cmd.handler()
+
+    def list_commands(self, category: Optional[str] = None) -> List[CATCommand]:
+        """Return a sorted list of registered commands, optionally filtered by category."""
+        cmds = list(self._commands.values())
+        if category:
+            cmds = [c for c in cmds if c.category.lower() == category.lower()]
+        cmds.sort(key=lambda c: (c.category, c.title))
+        return cmds
+
+    def _register_defaults(self) -> None:
+        """Register default editor, preview, and workbench commands."""
+        defaults = [
+            # Editor File Actions
+            CATCommand("editor.save", "File: Save", "File", default_keybinding="ctrl+s", description="Save the active file to disk"),
+            CATCommand("editor.saveAs", "File: Save As...", "File", default_keybinding="ctrl+shift+s", description="Save active file with a new name"),
+            CATCommand("editor.closeTab", "View: Close Current Tab", "View", default_keybinding="ctrl+w", description="Close active editor or viewer tab"),
+            CATCommand("editor.reopenClosedTab", "View: Reopen Closed Tab", "View", default_keybinding="ctrl+shift+t", description="Reopen recently closed tab"),
+            CATCommand("editor.quickOpen", "Go to File... (Quick Open)", "Go", default_keybinding="ctrl+p", description="Quickly open a file from workspace"),
+            CATCommand("editor.commandPalette", "View: Command Palette", "View", default_keybinding="ctrl+shift+p", description="Open CAT Command Palette"),
+            
+            # Editor Navigation & Search
+            CATCommand("editor.find", "Edit: Find", "Edit", default_keybinding="ctrl+f", description="Find text in active editor"),
+            CATCommand("editor.replace", "Edit: Replace", "Edit", default_keybinding="ctrl+h", description="Find and replace text in active editor"),
+            CATCommand("workspace.search", "Search: Find in Files", "Search", default_keybinding="ctrl+shift+f", description="Search text across workspace"),
+            CATCommand("editor.goToDefinition", "Go: Go to Definition", "Go", default_keybinding="f12", description="Jump to symbol definition"),
+            CATCommand("editor.findReferences", "Go: Find References", "Go", default_keybinding="shift+f12", description="Find all references of symbol"),
+            CATCommand("editor.rename", "Edit: Rename Symbol", "Edit", default_keybinding="f2", description="Rename symbol across file"),
+
+            # Line & Text Manipulation
+            CATCommand("editor.toggleComment", "Edit: Toggle Line Comment", "Edit", default_keybinding="ctrl+/", description="Comment or uncomment current line"),
+            CATCommand("editor.selectNextOccurrence", "Selection: Add Next Occurrence", "Selection", default_keybinding="ctrl+d", description="Select next matching text occurrence"),
+            CATCommand("editor.deleteLine", "Edit: Delete Line", "Edit", default_keybinding="ctrl+shift+k", description="Delete entire current line"),
+            CATCommand("editor.moveLineUp", "Edit: Move Line Up", "Edit", default_keybinding="alt+up", description="Move active line or selection up"),
+            CATCommand("editor.moveLineDown", "Edit: Move Line Down", "Edit", default_keybinding="alt+down", description="Move active line or selection down"),
+            CATCommand("editor.copyLineUp", "Edit: Copy Line Up", "Edit", default_keybinding="shift+alt+up", description="Duplicate active line upwards"),
+            CATCommand("editor.copyLineDown", "Edit: Copy Line Down", "Edit", default_keybinding="shift+alt+down", description="Duplicate active line downwards"),
+            CATCommand("editor.insertLineBelow", "Edit: Insert Line Below", "Edit", default_keybinding="ctrl+enter", description="Insert line below and move cursor"),
+            CATCommand("editor.insertLineAbove", "Edit: Insert Line Above", "Edit", default_keybinding="ctrl+shift+enter", description="Insert line above and move cursor"),
+            CATCommand("editor.triggerCompletion", "Edit: Trigger Suggestion", "Edit", default_keybinding="ctrl+space", description="Trigger code completion / suggestions"),
+            CATCommand("editor.formatDocument", "Edit: Format Document", "Edit", default_keybinding="shift+alt+f", description="Format source code"),
+
+            # Live Preview Commands
+            CATCommand("preview.open", "Preview: Run / Open Live Preview", "Preview", default_keybinding="shift+enter", description="Start or reuse local development server and open live preview"),
+            CATCommand("preview.reload", "Preview: Reload Live Preview", "Preview", default_keybinding="ctrl+r", description="Reload active live preview"),
+            CATCommand("preview.stop", "Preview: Stop Development Server", "Preview", description="Stop the running local development server"),
+            CATCommand("preview.restart", "Preview: Restart Development Server", "Preview", description="Restart the local development server"),
+            CATCommand("preview.toggleSplit", "View: Toggle Split Editor / Preview", "View", default_keybinding="ctrl+shift+s", description="Toggle side-by-side split between editor and preview"),
+
+            # Workbench & Sidebar
+            CATCommand("workbench.action.toggleSidebar", "View: Toggle Primary Sidebar", "View", default_keybinding="ctrl+b", description="Show or hide primary sidebar / explorer"),
+            CATCommand("workbench.action.terminal.toggle", "View: Toggle Terminal", "View", default_keybinding="ctrl+`", description="Toggle integrated terminal"),
+            CATCommand("workbench.view.explorer", "View: Show Explorer", "View", default_keybinding="ctrl+shift+e", description="Focus workspace file explorer"),
+            CATCommand("workbench.view.scm", "View: Show Source Control", "View", default_keybinding="ctrl+shift+g", description="Open source control / git panel"),
+            CATCommand("workbench.action.closeOverlays", "View: Close Active Overlays", "View", default_keybinding="escape", description="Dismiss active find bar, popups, or dialogs"),
+
+            # Viewer Controls
+            CATCommand("viewer.zoomIn", "Viewer: Zoom In", "Viewer", default_keybinding="ctrl+=", description="Zoom in active viewer"),
+            CATCommand("viewer.zoomOut", "Viewer: Zoom Out", "Viewer", default_keybinding="ctrl+-", description="Zoom out active viewer"),
+            CATCommand("viewer.fitPage", "Viewer: Fit to Screen", "Viewer", description="Fit document or image to screen"),
+            CATCommand("viewer.fitWidth", "Viewer: Fit to Width", "Viewer", description="Fit document or image to width"),
+            CATCommand("viewer.fullscreen", "Viewer: Toggle Fullscreen", "Viewer", default_keybinding="f11", description="Toggle fullscreen right pane"),
+
+            # AI Code Actions
+            CATCommand("ai.explainSelection", "CAT AI: Explain Selection", "AI", description="Ask CAT AI to explain the selected code"),
+            CATCommand("ai.fixSelection", "CAT AI: Fix Selection", "AI", description="Ask CAT AI to fix bugs or errors in selection"),
+            CATCommand("ai.refactorSelection", "CAT AI: Refactor Selection", "AI", description="Refactor selected code with AI diff"),
+            CATCommand("ai.generateTests", "CAT AI: Generate Unit Tests", "AI", description="Generate unit tests for selected code"),
+        ]
+        for cmd in defaults:
+            self.register(cmd)
+
+
+# Global singleton registry
+_GLOBAL_REGISTRY: Optional[CommandRegistry] = None
+
+
+def get_command_registry() -> CommandRegistry:
+    """Return the global CommandRegistry singleton."""
+    global _GLOBAL_REGISTRY
+    if _GLOBAL_REGISTRY is None:
+        _GLOBAL_REGISTRY = CommandRegistry()
+    return _GLOBAL_REGISTRY

calc_terminal/editor/shortcuts.py

@@ -0,0 +1,226 @@
+"""CAT Code Editor — Shortcut & Keybinding Manager (calc_terminal/editor/shortcuts.py).
+
+Centralized keybinding registration, normalization, conflict detection, and resolution.
+Enforces VS Code keyboard compatibility with customizable bindings.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from typing import Dict, List, Optional
+
+
+@dataclass
+class Keybinding:
+    """Represents a key combination mapped to a command ID."""
+    command_id: str
+    key: str
+    when: Optional[str] = None  # e.g., "editor", "preview", "global"
+    priority: int = 0
+    enabled: bool = True
+
+
+def normalize_key(key: str) -> str:
+    """Normalize key combinations into canonical lowercase format: [ctrl+][alt+][shift+]key."""
+    if not key:
+        return ""
+    parts = [p.strip().lower() for p in key.replace("-", "+").split("+")]
+    modifiers = set()
+    base_key = ""
+    for p in parts:
+        if p in ("ctrl", "control"):
+            modifiers.add("ctrl")
+        elif p in ("alt", "option"):
+            modifiers.add("alt")
+        elif p in ("shift",):
+            modifiers.add("shift")
+        elif p:
+            base_key = p
+    ordered = []
+    if "ctrl" in modifiers:
+        ordered.append("ctrl")
+    if "alt" in modifiers:
+        ordered.append("alt")
+    if "shift" in modifiers:
+        ordered.append("shift")
+    if base_key:
+        ordered.append(base_key)
+    return "+".join(ordered)
+
+
+class ShortcutManager:
+    """Manages all keyboard shortcuts across CAT IDE."""
+
+    CONFIG_PATH = os.path.join(os.path.expanduser("~"), ".cat_keybindings.json")
+
+    def __init__(self) -> None:
+        self._bindings: List[Keybinding] = []
+        self._register_default_bindings()
+        self.load_user_bindings()
+
+    def _register_default_bindings(self) -> None:
+        """Register default VS Code-compatible keybindings."""
+        defaults = [
+            # File Operations
+            Keybinding("editor.save", "ctrl+s", when="editor", priority=10),
+            Keybinding("editor.save", "ctrl+s", when="global", priority=5),
+            Keybinding("editor.saveAs", "ctrl+shift+s", when="editor", priority=10),
+            Keybinding("editor.closeTab", "ctrl+w", when="editor", priority=10),
+            Keybinding("editor.reopenClosedTab", "ctrl+shift+t", when="global", priority=5),
+            Keybinding("editor.quickOpen", "ctrl+p", when="global", priority=10),
+            Keybinding("editor.commandPalette", "ctrl+shift+p", when="global", priority=10),
+
+            # Search & Navigation
+            Keybinding("editor.find", "ctrl+f", when="editor", priority=10),
+            Keybinding("editor.replace", "ctrl+h", when="editor", priority=10),
+            Keybinding("workspace.search", "ctrl+shift+f", when="global", priority=5),
+            Keybinding("editor.goToDefinition", "f12", when="editor", priority=10),
+            Keybinding("editor.findReferences", "shift+f12", when="editor", priority=10),
+            Keybinding("editor.rename", "f2", when="editor", priority=10),
+
+            # Code Editing
+            Keybinding("editor.toggleComment", "ctrl+/", when="editor", priority=10),
+            Keybinding("editor.selectNextOccurrence", "ctrl+d", when="editor", priority=10),
+            Keybinding("editor.deleteLine", "ctrl+shift+k", when="editor", priority=10),
+            Keybinding("editor.moveLineUp", "alt+up", when="editor", priority=10),
+            Keybinding("editor.moveLineDown", "alt+down", when="editor", priority=10),
+            Keybinding("editor.copyLineUp", "shift+alt+up", when="editor", priority=10),
+            Keybinding("editor.copyLineDown", "shift+alt+down", when="editor", priority=10),
+            Keybinding("editor.insertLineBelow", "alt+enter", when="editor", priority=10),
+            Keybinding("editor.insertLineAbove", "alt+shift+enter", when="editor", priority=10),
+            Keybinding("editor.triggerCompletion", "ctrl+space", when="editor", priority=10),
+
+            # Live Preview
+            Keybinding("preview.open", "shift+enter", when="editor", priority=20),
+            Keybinding("preview.open", "ctrl+shift+enter", when="editor", priority=20),
+            Keybinding("preview.open", "cmd+shift+enter", when="editor", priority=20),
+            Keybinding("preview.open", "super+shift+enter", when="editor", priority=20),
+            Keybinding("preview.open", "ctrl+enter", when="editor", priority=20),
+            Keybinding("preview.open", "shift+enter", when="global", priority=5),
+            Keybinding("preview.open", "ctrl+shift+enter", when="global", priority=5),
+            Keybinding("preview.reload", "ctrl+r", when="preview", priority=10),
+            Keybinding("preview.toggleSplit", "ctrl+shift+s", when="preview", priority=10),
+
+            # Workbench & Shell
+            Keybinding("workbench.action.toggleSidebar", "ctrl+b", when="global", priority=10),
+            Keybinding("workbench.action.terminal.toggle", "ctrl+`", when="global", priority=10),
+            Keybinding("workbench.view.explorer", "ctrl+shift+e", when="global", priority=10),
+            Keybinding("workbench.view.scm", "ctrl+shift+g", when="global", priority=10),
+            Keybinding("workbench.action.closeOverlays", "escape", when="global", priority=10),
+
+            # Viewer
+            Keybinding("viewer.fullscreen", "f11", when="global", priority=10),
+            Keybinding("viewer.zoomIn", "ctrl+=", when="viewer", priority=10),
+            Keybinding("viewer.zoomOut", "ctrl+-", when="viewer", priority=10),
+        ]
+        for kb in defaults:
+            self.register(kb)
+
+    def register(self, binding: Keybinding) -> None:
+        """Register a keybinding with normalized key representation."""
+        binding.key = normalize_key(binding.key)
+        self._bindings.append(binding)
+
+    def unregister(self, command_id: str, key: Optional[str] = None) -> None:
+        """Remove a keybinding by command ID and optionally key string."""
+        norm_key = normalize_key(key) if key else None
+        self._bindings = [
+            b for b in self._bindings
+            if not (b.command_id == command_id and (norm_key is None or b.key == norm_key))
+        ]
+
+    def detect_conflicts(self, key: str, when: Optional[str] = None) -> List[Keybinding]:
+        """Detect any existing enabled keybindings that share the same key and compatible context."""
+        norm_key = normalize_key(key)
+        conflicts = []
+        for b in self._bindings:
+            if not b.enabled:
+                continue
+            if b.key == norm_key:
+                if when is None or b.when is None or b.when == "global" or when == "global" or b.when == when:
+                    conflicts.append(b)
+        return conflicts
+
+    def resolve(self, raw_key: str, context: Optional[str] = None) -> Optional[str]:
+        return self._resolve_impl(raw_key, context)
+
+    match = resolve
+
+    def _resolve_impl(self, raw_key: str, context: Optional[str] = None) -> Optional[str]:
+        """Resolve a raw keyboard input event into the winning command ID."""
+        norm_key = normalize_key(raw_key)
+        matching = []
+        for b in self._bindings:
+            if not b.enabled or b.key != norm_key:
+                continue
+            # Context match: exact context wins, or global matches if no specific binding
+            if context and b.when == context:
+                matching.append((b.priority + 20, b.command_id))
+            elif b.when in (None, "global"):
+                matching.append((b.priority, b.command_id))
+            elif not context:
+                matching.append((b.priority, b.command_id))
+        if not matching:
+            return None
+        # Highest score wins
+        matching.sort(key=lambda item: item[0], reverse=True)
+        return matching[0][1]
+
+    def get_keybindings_for_command(self, command_id: str) -> List[str]:
+        """Return all active key combination strings for a command ID."""
+        keys = []
+        for b in self._bindings:
+            if b.command_id == command_id and b.enabled and b.key not in keys:
+                keys.append(b.key)
+        return keys
+
+    def list_bindings(self) -> List[Keybinding]:
+        """Return all registered keybindings."""
+        return list(self._bindings)
+
+    def load_user_bindings(self) -> None:
+        """Load user-configured keybinding overrides from ~/.cat_keybindings.json."""
+        if not os.path.exists(self.CONFIG_PATH):
+            return
+        try:
+            with open(self.CONFIG_PATH, "r", encoding="utf-8") as f:
+                items = json.load(f)
+                if isinstance(items, list):
+                    for item in items:
+                        cmd = item.get("command_id")
+                        key = item.get("key")
+                        if cmd and key:
+                            # Higher priority for user customizations
+                            self.register(Keybinding(
+                                command_id=cmd,
+                                key=key,
+                                when=item.get("when"),
+                                priority=item.get("priority", 50),
+                                enabled=item.get("enabled", True),
+                            ))
+        except Exception:
+            pass
+
+    def save_user_bindings(self) -> bool:
+        """Persist user custom keybindings to disk."""
+        try:
+            user_bindings = [asdict(b) for b in self._bindings if b.priority >= 50]
+            with open(self.CONFIG_PATH, "w", encoding="utf-8") as f:
+                json.dump(user_bindings, f, indent=2)
+            return True
+        except Exception:
+            return False
+
+
+# Global singleton manager
+_GLOBAL_SHORTCUT_MANAGER: Optional[ShortcutManager] = None
+
+
+def get_shortcut_manager() -> ShortcutManager:
+    """Return the global ShortcutManager singleton."""
+    global _GLOBAL_SHORTCUT_MANAGER
+    if _GLOBAL_SHORTCUT_MANAGER is None:
+        _GLOBAL_SHORTCUT_MANAGER = ShortcutManager()
+    return _GLOBAL_SHORTCUT_MANAGER

calc_terminal/engine.py

@@ -0,0 +1,259 @@
+import shutil
+import sys
+import textwrap
+import time
+
+from . import theme
+from .mathtext import compose, mathify
+
+
+def term_width(min_w=60, max_w=100, margin=1, fallback=78):
+    """The real, current terminal width, clamped to a sane range.
+
+    Every box/panel in CCT is drawn at a fixed width — if that width is
+    wider than the actual terminal, the border characters wrap onto the
+    next line and the box looks broken (this was reported as a "border
+    problem": the right-hand `│` shows up in a different, wrong column
+    on every row, because every long line wraps at a different point).
+    Sizing to the real terminal at startup fixes that in the vast
+    majority of cases without needing a live-resize architecture.
+    """
+    try:
+        cols = shutil.get_terminal_size(fallback=(fallback, 24)).columns
+    except Exception:
+        cols = fallback
+    return max(min_w, min(max_w, cols - margin))
+
+
+WIDTH = term_width()
+
+ENGINE_STEPS = [
+    "Initializing Chemistry Engine...",
+    "Loading Formula Library...",
+    "Searching Database...",
+    "Checking Units...",
+    "Generating Notebook...",
+    "Rendering Output...",
+]
+
+DERIVE_STEPS = [
+    "Setting up the differential rate law...",
+    "Separating variables...",
+    "Integrating both sides...",
+    "Simplifying the result...",
+    "Typesetting derivation...",
+]
+
+IMAGE_STEPS = [
+    "Reading Image...",
+    "Recognizing Formula...",
+    "Extracting Text...",
+    "Preparing Solution...",
+]
+
+SPINNER = "\u280b\u2819\u2839\u2838\u283c\u2834\u2826\u2827\u2807\u280f"
+
+
+def run_steps(steps, step_time=0.35):
+    """Print a sequential fake-AI processing log with a spinner + checkmark."""
+    for step in steps:
+        frames = max(3, int(step_time / 0.05))
+        for i in range(frames):
+            frame = SPINNER[i % len(SPINNER)]
+            sys.stdout.write(f"\r  {theme.cyan(frame)} {theme.dim(step)}" + " " * 10)
+            sys.stdout.flush()
+            time.sleep(0.05)
+        sys.stdout.write(f"\r  {theme.green(chr(0x2713))} {theme.dim(step)}" + " " * 10 + "\n")
+        sys.stdout.flush()
+    print(f"  {theme.green(chr(0x2713) + ' Completed', bold=True)}")
+    time.sleep(0.15)
+
+
+def _wrap(s, width=WIDTH - 10):
+    return textwrap.wrap(s, width=width) or [""]
+
+
+# ---------------------------------------------------------------- reveal --
+# Animation is on by default; app.py can flip this off (e.g. non-tty runs
+# or a user "fast mode" setting) without touching call sites.
+ANIMATE = True
+
+
+def set_animation(on):
+    global ANIMATE
+    ANIMATE = bool(on)
+
+
+def _border(width, top=True, color=theme.CYAN):
+    ch = theme.TL + theme.H * (width - 2) + theme.TR if top else theme.BL + theme.H * (width - 2) + theme.BR
+    return theme.fg(ch, color)
+
+
+def _row(text_line, width, color=theme.CYAN):
+    inner = width - 2
+    pad = max(0, inner - theme.vlen(text_line) - 2)
+    return theme.fg(theme.V, color) + " " + text_line + " " * pad + theme.fg(theme.V, color)
+
+
+def _title_row(title, width, color):
+    inner = width - 2
+    tag = f" {title} "
+    left = 3
+    right = max(0, inner - left - theme.vlen(tag))
+    return theme.fg(theme.TL + theme.H * left, color) + theme.fg(tag, color, bold=True) + theme.fg(theme.H * right + theme.TR, color)
+
+
+def animate_panel(lines, title=None, color=theme.CYAN, width=WIDTH, stage_pause=0.10, line_pause=0.014):
+    """Reveal a panel progressively: border draws in, then each line
+    fades in top-to-bottom, with a slightly longer pause on section
+    headers (lines containing the bullet marker) so every response
+    feels like it's being worked out live rather than dumped instantly.
+    Falls back to an instant static panel when ANIMATE is off."""
+    if not ANIMATE:
+        print(theme.panel(lines, title=title, color=color, width=width))
+        return
+    try:
+        print(_title_row(title, width, color) if title else _border(width, top=True, color=color))
+        for line in lines:
+            print(_row(line, width, color))
+            time.sleep(stage_pause if "\u25cf" in line else line_pause)
+        print(_border(width, top=False, color=color))
+    except Exception:
+        # any terminal-width edge case -> never break the actual output
+        print(theme.panel(lines, title=title, color=color, width=width))
+
+
+def render_notebook(nb):
+    """Print a full step-by-step notebook panel for a generated numerical,
+    revealed one stage at a time (animated)."""
+    lines = []
+    lines.append(theme.purple(nb["topic"].upper(), bold=True))
+    for w in _wrap(nb["question"]):
+        lines.append(theme.text(w, bold=True))
+    lines.append("")
+
+    def stage(label, body_lines, final=False):
+        color = theme.GREEN if final else theme.CYAN
+        lines.append(theme.fg("\u25cf " + label, color, bold=True))
+        for bl in body_lines:
+            lines.append("  " + bl)
+        lines.append("")
+
+    stage("GIVEN DATA", [theme.dim("\u2022 ") + theme.text(g) for g in nb["given"]])
+    stage("FIND", [theme.text(nb["find"])])
+    stage("FORMULA", [theme.text(l) for l in compose(nb["formula"]).split("\n")])
+    stage("SUBSTITUTION", [theme.text(l) for l in compose(nb["substitution"]).split("\n")])
+    stage("CALCULATION", [theme.dim(f"{i+1}. ") + theme.text(mathify(c)) for i, c in enumerate(nb["calculation"])])
+
+    unit_lines = []
+    for w in _wrap(mathify(nb["unit"])):
+        unit_lines.append(theme.dim(w))
+    stage("UNITS", unit_lines)
+
+    ver_lines = []
+    for w in _wrap(mathify(nb["verification"])):
+        ver_lines.append(theme.dim(w))
+    stage("VERIFICATION", ver_lines)
+
+    stage("FINAL ANSWER", [theme.green(nb["final_answer"], bold=True)], final=True)
+
+    animate_panel(lines, title="notebook", color=theme.CYAN, width=WIDTH)
+
+
+import re as _re
+
+# A header line is either a short markdown-ish "## SOME HEADER" line, or a
+# short, mostly-uppercase line (with or without a trailing colon) — the
+# style CCT Agent's system prompt asks the model to write in (GIVEN DATA,
+# FORMULA, FINAL ANSWER...). Kept permissive since it's parsing free-form
+# LLM text, not a fixed schema.
+_AGENT_HEADER_RE = _re.compile(
+    r"^\s*(?:#{1,4}\s*|\*\*)?([A-Z][A-Z0-9 /&()\-]{2,40}?)(?:\*\*)?\s*:?\s*$"
+)
+
+
+def _is_agent_header(line):
+    s = line.strip()
+    if not s or len(s) > 48:
+        return None
+    m = _AGENT_HEADER_RE.match(s)
+    if not m:
+        return None
+    label = m.group(1).strip()
+    letters = [c for c in label if c.isalpha()]
+    if len(letters) < 3:
+        return None
+    # Require it to actually look shouted (mostly uppercase), not just any
+    # short capitalized sentence fragment.
+    upper = sum(1 for c in letters if c.isupper())
+    if upper / len(letters) < 0.8:
+        return None
+    return label
+
+
+def render_agent_answer(text, tag="CAT Agent", color=theme.PURPLE):
+    """Render CAT Agent's free-form "final" text as a notebook-style
+    panel — detecting the ALL-CAPS section headers (GIVEN DATA, FORMULA,
+    FINAL ANSWER, OVERVIEW, EXPLANATION...) the agent's system prompt asks
+    for, and falling back to a single plain ANSWER section for any text
+    that doesn't use them (e.g. a short aside or an older-style reply), so
+    /agent always reads like a worked notebook page rather than a wall of
+    unstructured prose."""
+    if not text or not text.strip():
+        return
+    raw_lines = text.strip().split("\n")
+    sections = []          # [(header, [body_lines])]
+    current_body = []
+    for line in raw_lines:
+        header = _is_agent_header(line)
+        if header:
+            sections.append([header, []])
+            current_body = sections[-1][1]
+        else:
+            if not sections:
+                sections.append(["ANSWER", []])
+                current_body = sections[-1][1]
+            if line.strip():
+                current_body.append(line.strip())
+
+    lines = [theme.badge(tag, theme.BG_AI, fgcolor=(225, 210, 255)), ""]
+    for header, body in sections:
+        is_final = "FINAL" in header
+        hcolor = theme.GREEN if is_final else theme.CYAN
+        lines.append(theme.fg("\u25cf " + header, hcolor, bold=True))
+        if not body:
+            body = [""]
+        for b in body:
+            for w in _wrap(b):
+                lines.append("  " + (theme.green(w, bold=True) if is_final else theme.text(w)))
+        lines.append("")
+
+    animate_panel(lines, title="agent notebook", color=color, width=WIDTH, stage_pause=0.10)
+
+
+def render_derivation(dv):
+    """Print a full step-by-step DERIVATION panel (real calculus, not a
+    numeric example) for the given derivation dict from derivations.py,
+    revealed step-by-step so the logic visibly builds instead of
+    appearing all at once."""
+    lines = []
+    lines.append(theme.purple(dv["topic"].upper(), bold=True))
+    for w in _wrap(dv["goal"]):
+        lines.append(theme.text(w, bold=True))
+    lines.append("")
+
+    for i, (label, parts) in enumerate(dv["steps"], 1):
+        lines.append(theme.fg(f"\u25cf Step {i} \u2014 {label}", theme.CYAN, bold=True))
+        for l in compose(parts).split("\n"):
+            lines.append("  " + theme.text(l))
+        lines.append("")
+
+    lines.append(theme.fg("\u25cf RESULT", theme.GREEN, bold=True))
+    lines.append("  " + theme.green(dv["result"], bold=True))
+    lines.append("")
+
+    lines.append(theme.fg("\u25cf WHAT IT MEANS", theme.ORANGE, bold=True))
+    for w in _wrap(dv["note"]):
+        lines.append("  " + theme.dim(w))
+
+    animate_panel(lines, title="derivation", color=theme.PURPLE, width=WIDTH, stage_pause=0.16)