Feature: TerminalGrid — Layout manager for tabs, splits, and state-aware styling

[holiber]

Summary

Add a TerminalGrid component (or similar high-level layout manager) that sits on top of <JabTerm> and provides:

1. Tabbed terminals — Create, close, and switch between multiple terminal sessions via a tab bar.
2. Split panes — Split any terminal horizontally or vertically to view multiple sessions side-by-side (VS Code / tmux style).
3. State-aware tab colors — Each tab automatically reflects the terminal's current state through color coding:
   • 🔵 Blue — Idle, waiting for user input
   • 🟢 Green / Lime — Process is running
   • 🟠 Orange — Errors detected in stderr
   • ⚫ Gray — Disconnected / closed

Motivation

When embedding terminals in web applications (dashboards, AI agent UIs, DevOps panels), users almost always need multiple terminals with a way to organize them visually. Currently each <JabTerm> is independent, so the consuming app has to build its own tab bar, split logic, and state detection from scratch.

A first-party layout manager would make JabTerm a drop-in replacement for a full terminal experience.

Proposed API (rough sketch)

import { TerminalGrid } from 'jabterm/react';

<TerminalGrid
  wsUrl="ws://localhost:3223"
  defaultLayout={{
    type: 'tabs',
    children: [
      { id: 'main', title: 'Main' },
      { id: 'build', title: 'Build' },
      {
        type: 'split-h',
        children: [
          { id: 'logs', title: 'Logs' },
          { id: 'tests', title: 'Tests' },
        ],
      },
    ],
  }}
  tabColors={{
    idle: '#6366f1',      // indigo/blue
    running: '#84cc16',   // lime/green
    error: '#f97316',     // orange
    disconnected: '#6b7280', // gray
  }}
  onLayoutChange={(layout) => saveToLocalStorage(layout)}
/>

State detection approach

Terminal state could be inferred by combining:

• data-jabterm-state (already exists: connecting | open | closed) → maps to disconnected
• PTY child-process activity (server-side: is the foreground process running?) → running vs idle
• stderr marker detection (opt-in, via ANSI escape or heuristic) → error

Scope

• TerminalGrid React component with tab bar
• Horizontal and vertical split support (draggable dividers)
• State-aware tab styling (color + optional icon/badge)
• Keyboard shortcuts (e.g. Cmd+T new tab, Cmd+D split, Cmd+W close)
• Persistent layout via onLayoutChange callback
• Server-side: expose process state per terminal session (new WS message or REST endpoint)

[holiber]

Additional requirement: Configurable keyboard shortcuts with tmux defaults

The TerminalGrid should ship with default tmux-style keybindings out of the box (using a configurable prefix key, e.g. Ctrl+B), and allow full customization:

Default tmux shortcuts (examples)

Shortcut	Action
Prefix + c	New tab
Prefix + %	Split horizontally
Prefix + "	Split vertically
Prefix + x	Close current pane
Prefix + o	Cycle through panes
Prefix + ←/→/↑/↓	Navigate between panes
Prefix + n / p	Next / previous tab
Prefix + z	Toggle pane zoom (fullscreen)

Customization API

Users should be able to:

1. Redefine any default shortcut
2. Add custom shortcuts that trigger arbitrary actions — run a command, open a new tab with a preset, add a split with a specific widget view, etc.

<TerminalGrid
  wsUrl="ws://localhost:3223"
  prefixKey="Ctrl+B"  // tmux-style prefix, customizable
  shortcuts={{
    // override defaults
    'Prefix + c': { action: 'new-tab', title: 'Shell' },
    'Prefix + %': { action: 'split-h' },
    
    // custom shortcuts
    'Prefix + l': { action: 'new-tab', title: 'Logs', command: 'tail -f /var/log/app.log' },
    'Prefix + t': { action: 'split-v', command: 'npm test -- --watch' },
    'Prefix + d': { action: 'new-tab', title: 'Docker', command: 'docker compose logs -f' },
    
    // disable a default shortcut
    'Prefix + z': null,
  }}
/>

This makes the component feel native to anyone coming from tmux, while staying fully extensible for custom workflows and AI agent tooling.

[holiber]

Visual concept & code example

Here's a concept mockup of how the TerminalGrid component with state-aware tabs and split panes would look:

Tab states shown: 🔵 Main (idle) · 🟢 Build (running) · 🟠 Logs (stderr errors) · ⚫ Deploy (disconnected)

Styling code example

Below is a self-contained React example showing how you might style the TerminalGrid tab bar with state-aware colors, including the split-pane layout:

import { useState } from 'react';

type TerminalState = 'idle' | 'running' | 'error' | 'disconnected';

interface TerminalTab {
  id: string;
  title: string;
  state: TerminalState;
}

const STATE_COLORS: Record<TerminalState, { dot: string; bg: string; border: string; text: string }> = {
  idle:         { dot: '#6366f1', bg: 'rgba(99,102,241,0.08)',  border: 'rgba(99,102,241,0.3)',  text: '#a5b4fc' },
  running:      { dot: '#84cc16', bg: 'rgba(132,204,22,0.08)',  border: 'rgba(132,204,22,0.3)',  text: '#bef264' },
  error:        { dot: '#f97316', bg: 'rgba(249,115,22,0.08)',  border: 'rgba(249,115,22,0.3)',  text: '#fdba74' },
  disconnected: { dot: '#6b7280', bg: 'rgba(107,114,128,0.08)', border: 'rgba(107,114,128,0.3)', text: '#9ca3af' },
};

function TerminalGridDemo() {
  const [activeTab, setActiveTab] = useState('main');
  const tabs: TerminalTab[] = [
    { id: 'main',   title: 'Main',   state: 'idle' },
    { id: 'build',  title: 'Build',  state: 'running' },
    { id: 'logs',   title: 'Logs',   state: 'error' },
    { id: 'deploy', title: 'Deploy', state: 'disconnected' },
  ];

  return (
    <div style={{
      background: '#0d1117',
      borderRadius: 16,
      border: '1px solid #21262d',
      overflow: 'hidden',
      fontFamily: "'Outfit', system-ui, sans-serif",
      width: '100%',
      maxWidth: 900,
    }}>

      {/* ─── Tab Bar ─── */}
      <div style={{
        display: 'flex',
        gap: 4,
        padding: '8px 8px 0',
        background: '#010409',
        borderBottom: '1px solid #21262d',
      }}>
        {tabs.map(tab => {
          const colors = STATE_COLORS[tab.state];
          const isActive = tab.id === activeTab;
          return (
            <button
              key={tab.id}
              onClick={() => setActiveTab(tab.id)}
              style={{
                display: 'flex',
                alignItems: 'center',
                gap: 8,
                padding: '8px 16px',
                borderRadius: '8px 8px 0 0',
                border: 'none',
                cursor: 'pointer',
                fontSize: 13,
                fontWeight: 500,
                fontFamily: 'inherit',
                transition: 'all 0.2s',
                background: isActive ? '#0d1117' : 'transparent',
                color: isActive ? colors.text : '#484f58',
                borderTop: isActive ? `2px solid ${colors.dot}` : '2px solid transparent',
              }}
            >
              {/* State dot indicator */}
              <span style={{
                width: 8,
                height: 8,
                borderRadius: '50%',
                background: colors.dot,
                boxShadow: isActive ? `0 0 8px ${colors.dot}` : 'none',
                opacity: tab.state === 'disconnected' ? 0.5 : 1,
              }} />
              {tab.title}
            </button>
          );
        })}
      </div>

      {/* ─── Split Pane Area ─── */}
      <div style={{
        display: 'grid',
        gridTemplateColumns: '1fr 1px 1fr',
        height: 320,
      }}>
        {/* Left pane */}
        <div style={{ padding: 16, fontFamily: 'monospace', fontSize: 13, color: '#7ee787', overflow: 'auto' }}>
          <div style={{ color: '#58a6ff' }}>agent@flowthink:~$</div>
          <div>npm run build</div>
          <div style={{ color: '#8b949e', marginTop: 8 }}>✓ Compiled successfully in 2.4s</div>
          <div style={{ color: '#8b949e' }}>✓ 47 modules transformed</div>
          <div style={{ color: '#7ee787' }}>● Watching for changes...</div>
        </div>

        {/* Divider (draggable in real implementation) */}
        <div style={{ background: '#21262d', cursor: 'col-resize' }} />

        {/* Right pane */}
        <div style={{ padding: 16, fontFamily: 'monospace', fontSize: 13, color: '#ffa657', overflow: 'auto' }}>
          <div style={{ color: '#f97316' }}>stderr: Connection refused at 127.0.0.1:5432</div>
          <div style={{ color: '#f97316', marginTop: 4 }}>stderr: CRITICAL: Unable to start service</div>
          <div style={{ color: '#8b949e', marginTop: 8 }}>Retry attempt 2 of 3...</div>
        </div>
      </div>

    </div>
  );
}

Key design decisions

Decision	Rationale
Colored dot + top border on active tab	Subtle but clear state indication without being too flashy
Glow effect (box-shadow) on active dot	Draws the eye to the focused terminal
Reduced opacity for disconnected state	Visually de-emphasizes inactive terminals
Draggable divider between panes	Matches tmux/VS Code muscle memory
Dark glassmorphic tab bar	Fits modern dev-tool aesthetics

[holiber]

@cursoragent please handle this

[cursor]

Yep — I’ll take this on.

• Default tmux-style keybindings: I’ll add a prefixKey prop (default Ctrl+B) and ship a built-in default mapping for the tmux actions you listed (c, %, ", x, o, arrows, n/p, z).
• Full customization: I’ll implement a shortcuts prop that can override defaults, add new bindings (including “run command / open tab with preset / split with preset”), and disable any default by setting it to null (exactly like your example).
• Deliverables: wiring to TerminalGrid actions (new tab, split H/V, close pane, focus navigation, tab navigation, zoom), plus basic docs/examples so consumers can copy-paste the API.