Make GateFlow TUI responsive (#10)

Fix the OpenClaw-style terminal dashboard so narrow local terminals render as a stacked status view instead of overlapping columns.

- add responsive layout helpers and text/path truncation
- update release metadata to v2.5.2
- cover narrow dashboard rendering with unit tests

Author: codejunkie99

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "gateflow",
       "description": "AI-powered hardware development platform \u2014 design, verify, synthesize, release, and deploy working RTL with natural language. 20 agents, 27 skills, 8 IP blocks.",
-      "version": "2.5.1",
+      "version": "2.5.2",
       "author": {
         "name": "codejunkie99",
         "github": "https://github.com/codejunkie99"

README.md

@@ -590,6 +590,7 @@ For detailed release notes, see [`releases.md`](releases.md).
 
 | Version | Date | What Changed |
 |---------|------|-------------|
+| **2.5.2** | 2026-05-21 | Responsive TUI layout for narrow terminal windows |
 | **2.5.1** | 2026-05-21 | TUI terminal compatibility fixes for cursor and colorless PTYs |
 | **2.5.0** | 2026-05-21 | OpenClaw-style CLI/TUI, release readiness workflow, deterministic validators, synced marketplace/docs/index/mirrors |
 | **2.4.0** | 2026-04-11 | Deep skill enrichment across verification, synthesis, orchestration, architecture, learning, IP, and planning |

plugins/gateflow/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gateflow",
-  "version": "2.5.1",
+  "version": "2.5.2",
   "description": "AI-powered hardware development platform \u2014 design, verify, synthesize, release, and deploy working RTL with natural language. 20 agents, 27 skills, 8 IP blocks.",
   "author": {
     "name": "codejunkie99",

releases.md

@@ -1,5 +1,17 @@
 # Releases
 
+## 2.5.2 (2026-05-21) — Responsive TUI Layout
+
+Patch release for narrow terminal windows.
+
+### Fixes
+- Added a stacked interactive layout for terminals below 100 columns so the
+  actions list no longer overlaps workspace, inventory, or health panels.
+- Clamped action descriptions and other terminal text to their available
+  column width.
+- Added regression coverage for narrow terminal layout selection and text
+  ellipsizing.
+
 ## 2.5.1 (2026-05-21) — TUI Terminal Compatibility
 
 Patch release for the GateFlow terminal console.

tests/test_gateflow_tui.py

@@ -36,7 +36,7 @@ def test_json_mode_returns_machine_readable_inventory(self):
         payload = tui.build_payload(ROOT)
 
         self.assertEqual("gateflow", payload["plugin"]["name"])
-        self.assertEqual("2.5.1", payload["plugin"]["version"])
+        self.assertEqual("2.5.2", payload["plugin"]["version"])
         self.assertEqual(20, payload["inventory"]["agents"])
         self.assertEqual(27, payload["inventory"]["skills"])
         self.assertEqual(21, payload["inventory"]["commands"])
@@ -95,6 +95,52 @@ def color_pair(_pair):
         self.assertEqual(FakeCurses.A_DIM, styles["muted"])
         self.assertEqual(0, styles["footer"])
 
+    def test_narrow_terminals_use_stacked_layout(self):
+        tui = load_tui()
+
+        self.assertEqual("stacked", tui._layout_mode(80))
+        self.assertEqual("columns", tui._layout_mode(120))
+
+    def test_text_is_ellipsized_to_fit_column(self):
+        tui = load_tui()
+
+        value = tui._fit_text("Validate plugin release readiness", 18)
+
+        self.assertEqual("Validate plugin...", value)
+        self.assertLessEqual(len(value), 18)
+
+    def test_narrow_draw_stacks_panels_below_actions(self):
+        tui = load_tui()
+        payload = tui.build_payload(ROOT)
+
+        class FakeScreen:
+            def __init__(self):
+                self.rows = [" " * 80 for _ in range(32)]
+
+            def erase(self):
+                pass
+
+            def getmaxyx(self):
+                return (32, 80)
+
+            def addnstr(self, y, x, text, max_width, _attr=0):
+                line = self.rows[y]
+                clipped = text[:max_width]
+                self.rows[y] = line[:x] + clipped + line[x + len(clipped) :]
+
+            def refresh(self):
+                pass
+
+        screen = FakeScreen()
+
+        tui._draw(screen, payload, selected=6, message="")
+
+        action_row = next(row for row in screen.rows if "/gf-release" in row)
+        workspace_row = next(index for index, row in enumerate(screen.rows) if "Workspace" in row)
+
+        self.assertNotIn("Workspace", action_row)
+        self.assertGreater(workspace_row, 11)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_validate_gateflow.py

@@ -35,13 +35,13 @@ def test_inventory_matches_release_target(self):
     def test_repository_passes_release_checks(self):
         validator = load_validator()
 
-        result = validator.run_checks(ROOT, expected_version="2.5.1")
+        result = validator.run_checks(ROOT, expected_version="2.5.2")
 
         self.assertEqual([], result.errors)
 
     def test_cli_reports_success(self):
         completed = subprocess.run(
-            [sys.executable, str(VALIDATOR), "--version", "2.5.1"],
+            [sys.executable, str(VALIDATOR), "--version", "2.5.2"],
             cwd=ROOT,
             text=True,
             capture_output=True,

tools/gateflow_tui.py

@@ -138,6 +138,66 @@ def _terminal_styles(curses_module=curses) -> dict[str, int]:
     return styles
 
 
+def _layout_mode(width: int) -> str:
+    return "stacked" if width < 100 else "columns"
+
+
+def _fit_text(text: str, max_width: int) -> str:
+    if max_width <= 0:
+        return ""
+    if len(text) <= max_width:
+        return text
+    if max_width <= 3:
+        return "." * max_width
+    return text[: max_width - 3].rstrip() + "..."
+
+
+def _short_path(path: str, max_width: int) -> str:
+    if len(path) <= max_width:
+        return path
+    name = Path(path).name
+    parent = Path(path).parent.name
+    compact = f".../{parent}/{name}" if parent else f".../{name}"
+    return _fit_text(compact, max_width)
+
+
+def _dashboard_rows(payload: dict, width: int, selected: int, message: str) -> list[tuple[str, str]]:
+    max_width = max(20, width - 1)
+    inv = payload["inventory"]
+    health = payload["health"]
+    rows: list[tuple[str, str]] = []
+
+    def row(text: str = "", style: str = "normal") -> None:
+        rows.append((_fit_text(text, max_width), style))
+
+    row(f"GateFlow Terminal  {payload['plugin']['name']} {payload['plugin']['version']}", "accent")
+    row(payload["mode"], "muted")
+    row("─" * max_width, "muted")
+    row()
+    row("Actions", "heading")
+    for index, action in enumerate(payload["actions"], start=1):
+        marker = ">" if index - 1 == selected else " "
+        style = "selected" if index - 1 == selected else "normal"
+        row(f"{marker} {index}. {action['command']:<11} {action['description']}", style)
+    row()
+    row("Workspace", "heading")
+    row(f"  path    {_short_path(payload['workspace'], max_width - 10)}")
+    row(f"  plugin  {payload['plugin']['name']} {payload['plugin']['version']}", "accent")
+    row()
+    row("Inventory", "heading")
+    row(f"  {inv['agents']} agents   {inv['skills']} skills   {inv['commands']} commands")
+    row(f"  {inv['ip_blocks']} IP blocks   {inv['boards']} boards")
+    row()
+    row("Health", "heading")
+    row(f"  doctor    {health['doctor']:<10} release  {health['release']}")
+    row(f"  map       {health['map']['status']:<10} verilator {health['verilator']}")
+    row(f"  yosys     {health['yosys']:<10} sby       {health['sby']}")
+    row()
+    row("─" * max_width, "muted")
+    row(message or "↑/↓ select   Enter show command   r refresh   q quit", "footer")
+    return rows
+
+
 def render_snapshot(root: Path, plain: bool = False) -> str:
     payload = build_payload(root)
     inv = payload["inventory"]
@@ -182,11 +242,12 @@ def _draw(stdscr, payload: dict, selected: int, message: str) -> None:
     actions = payload["actions"]
     inv = payload["inventory"]
     health = payload["health"]
-    left_width = min(34, max(24, width // 3))
+    mode = _layout_mode(width)
 
     def add(y: int, x: int, text: str, attr=0) -> None:
         if 0 <= y < height:
-            stdscr.addnstr(y, x, text, max(0, width - x - 1), attr)
+            max_width = max(0, width - x - 1)
+            stdscr.addnstr(y, x, _fit_text(text, max_width), max_width, attr)
 
     styles = _terminal_styles()
     accent = styles["accent"]
@@ -198,22 +259,47 @@ def add(y: int, x: int, text: str, attr=0) -> None:
     add(0, 20, payload["mode"], muted)
     add(1, 0, "─" * (width - 1), muted)
 
+    if mode == "stacked":
+        style_attrs = {
+            "accent": accent,
+            "footer": styles["footer"],
+            "heading": curses.A_BOLD,
+            "muted": muted,
+            "normal": 0,
+            "selected": curses.A_REVERSE,
+        }
+        for y, (text, style) in enumerate(_dashboard_rows(payload, width, selected, message)):
+            add(y, 0, text, style_attrs.get(style, 0))
+        stdscr.refresh()
+        return
+
     add(3, 2, "Actions", curses.A_BOLD)
+    right_x = 52 if mode == "columns" else 2
+    action_desc_width = (right_x - 18) if mode == "columns" else (width - 18)
     for idx, action in enumerate(actions):
         attr = curses.A_REVERSE if idx == selected else 0
-        add(5 + idx, 2, f"{idx + 1}. {action['command']}", attr)
-        add(5 + idx, 16, action["description"], attr)
-
-    x = left_width + 2
-    add(3, x, "Workspace", curses.A_BOLD)
-    add(5, x, payload["workspace"])
-    add(6, x, f"{payload['plugin']['name']} {payload['plugin']['version']}", accent)
-
-    add(8, x, "Inventory", curses.A_BOLD)
-    add(10, x, f"{inv['agents']} agents   {inv['skills']} skills   {inv['commands']} commands")
-    add(11, x, f"{inv['ip_blocks']} IP blocks   {inv['boards']} boards")
-
-    add(13, x, "Health", curses.A_BOLD)
+        y = 5 + idx
+        add(y, 2, f"{idx + 1}. {action['command']}", attr)
+        add(y, 16, _fit_text(action["description"], action_desc_width), attr)
+
+    if mode == "columns":
+        workspace_y = 3
+        inventory_y = 8
+        health_y = 13
+    else:
+        workspace_y = 6 + len(actions)
+        inventory_y = workspace_y + 5
+        health_y = inventory_y + 5
+
+    add(workspace_y, right_x, "Workspace", curses.A_BOLD)
+    add(workspace_y + 2, right_x, payload["workspace"])
+    add(workspace_y + 3, right_x, f"{payload['plugin']['name']} {payload['plugin']['version']}", accent)
+
+    add(inventory_y, right_x, "Inventory", curses.A_BOLD)
+    add(inventory_y + 2, right_x, f"{inv['agents']} agents   {inv['skills']} skills   {inv['commands']} commands")
+    add(inventory_y + 3, right_x, f"{inv['ip_blocks']} IP blocks   {inv['boards']} boards")
+
+    add(health_y, right_x, "Health", curses.A_BOLD)
     rows = [
         ("doctor", health["doctor"]),
         ("release", health["release"]),
@@ -224,7 +310,7 @@ def add(y: int, x: int, text: str, attr=0) -> None:
     ]
     for offset, (name, value) in enumerate(rows):
         attr = ok if value in {"ready", "installed"} else warn
-        add(15 + offset, x, f"{name:<10} {value}", attr)
+        add(health_y + 2 + offset, right_x, f"{name:<10} {value}", attr)
 
     footer = message or "↑/↓ select   Enter show command   r refresh   q quit"
     add(height - 2, 0, "─" * (width - 1), muted)

tools/validate_gateflow.py

@@ -132,7 +132,7 @@ def _check_symlink(path: Path, expected_target: str, errors: list[str]) -> None:
         errors.append(f"{path} points to {target}, expected {expected_target}")
 
 
-def run_checks(root: Path, expected_version: str = "2.5.1") -> ValidationResult:
+def run_checks(root: Path, expected_version: str = "2.5.2") -> ValidationResult:
     root = root.resolve()
     inventory = discover_inventory(root)
     errors: list[str] = []
@@ -148,7 +148,7 @@ def run_checks(root: Path, expected_version: str = "2.5.1") -> ValidationResult:
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--root", type=Path, default=Path.cwd(), help="Repository root")
-    parser.add_argument("--version", default="2.5.1", help="Expected release version")
+    parser.add_argument("--version", default="2.5.2", help="Expected release version")
     args = parser.parse_args(argv)
 
     result = run_checks(args.root, expected_version=args.version)