Editor Command Protocol

What is ECP?

The Editor Command Protocol (ECP) is Ultra's internal architecture that separates the editor into distinct services and clients communicating via JSON-RPC 2.0. This design enables multiple UI implementations (terminal, future GUI, headless testing) to interact with shared backend services through a unified API.

Three-Layer Architecture

The system comprises three distinct layers:

Method Routing

ECP methods follow a namespace/action format, enabling organized routing:

document/*  → DocumentServiceAdapter
file/*      → FileServiceAdapter
git/*       → GitServiceAdapter
lsp/*       → LSPServiceAdapter
terminal/*  → TerminalServiceAdapter
database/*  → DatabaseServiceAdapter

Data Flow

Every user interaction flows through a consistent pipeline:

1. Input Capture — Terminal captures keystroke
2. TUI Processing — Client determines action from keybinding
3. ECP Request — JSON-RPC request sent to service
4. Service Execution — Service modifies state, emits events
5. UI Update — Render scheduler batches and displays changes

Service Implementation Pattern

Each service follows a standardized three-layer architecture that ensures consistency, testability, and clean separation of concerns:

src/services/[name]/
├── interface.ts      # Contract definition
├── types.ts          # Type definitions
├── [name]Service.ts  # Local implementation
├── adapter.ts        # ECP request mapping
└── index.ts          # Public exports

Pattern Benefits

This design enables switching between local and remote implementations, testing services in isolation, and adding new services without modifying existing code. Services operate as singletons with both named and default exports for flexible access throughout the application.

Event System

Services emit events through callback registration. Components subscribe to changes and receive unsubscribe functions for proper cleanup:

const unsubscribe = documentService.onChange((event) => {
  // Handle document changes
  scheduleRender('editor', renderEditor);
});

// Later: cleanup
unsubscribe();

UI Component System

Ultra's terminal UI is built on a component-based architecture with intelligent rendering that minimizes redraws and terminal I/O.

Component Hierarchy

App
├── Navbar
├── Sidebar
│   ├── FileTree
│   └── GitPanel
├── EditorPane
│   ├── TabBar
│   ├── Editor
│   │   ├── LineNumbers
│   │   ├── TextBuffer
│   │   └── Minimap
│   └── Scrollbar
├── Panel
│   ├── Terminal
│   ├── Problems
│   └── AIChat
└── StatusBar

Render Lifecycle

Components follow a simple lifecycle:

1. State Change — Component data updates
2. Schedule Render — Component queued with priority
3. Layout — Calculate bounds based on parent
4. Paint — Write cells to screen buffer
5. Flush — Only dirty cells sent to terminal

Input Handling

Keyboard and mouse input flows through a focus-based system:

// Input is routed to the focused component
inputManager.onKeyPress((key) => {
  const focused = focusManager.current;

  // Check keybindings first
  if (keybindings.handle(key, focused.context)) {
    return;
  }

  // Otherwise let the component handle it
  focused.onKeyPress(key);
});