What Is AdaptDispatch in Windows Terminal? Understanding the VT Sequence Adapter

AdaptDispatch is the adapter layer that translates Virtual Terminal (VT) control sequences into concrete actions on the Windows Console rendering engine.

In the microsoft/terminal repository, AdaptDispatch serves as the critical bridge between the terminal's VT parser and its underlying console implementation. This class implements the ITermDispatch interface to convert parsed escape sequences—such as cursor movements, color changes, and screen erasures—into direct manipulations of the terminal state.

The Architectural Role of AdaptDispatch

AdaptDispatch sits at the intersection of parsing and rendering, ensuring that the VT parser remains decoupled from the console's internal mechanics. By implementing the ITermDispatch interface defined in src/terminal/parser/termDispatch.hpp, it provides a concrete execution layer for the abstract commands generated by the parser.

This separation allows the same VT parser to be reused across different contexts, including unit tests, the ConHost backend, and alternative rendering pipelines. The adapter pattern employed here ensures that changes to the console's rendering engine do not require modifications to the parser logic.

Core Dependencies and Internal State

The AdaptDispatch class maintains references to the essential subsystems it controls. As defined in src/terminal/adapter/adaptDispatch.hpp (lines 108–124), the private members include:

ITerminalApi& _api;          // Low-level console API for writing and mode setting
Renderer* _renderer;         // Rendering back-end for visual output
RenderSettings& _renderSettings;
TerminalInput& _terminalInput;
PageManager _pages;          // Manages active page (main/alt buffer)

These references enable AdaptDispatch to execute VT commands by delegating to the appropriate subsystem. The class also tracks terminal mode flags—such as INSERT/REPLACE, ORIGIN, and RECTANGULAR-CHANGE-EXTENT—through an internal enum class Mode, exposing state management via SetMode, ResetMode, and RequestMode methods.

Translating VT Sequences to Console Actions

Cursor Movement and Positioning

When the parser receives a Cursor Up (CUU) sequence like \x1b[5A, AdaptDispatch::CursorUp processes the request. The implementation in src/terminal/adapter/adaptDispatch.cpp (lines 1008–1010) forwards to _CursorMovePosition, which handles margin constraints, origin mode compliance, and coordinate clamping:

// Direct call equivalent to receiving CSI "\x1b[5A"
adapter->CursorUp(5);   // Moves cursor 5 rows up, respecting scroll margins

Graphics Rendition (SGR)

The Select Graphic Rendition command updates text attributes through SetGraphicsRendition. Located in src/terminal/adapter/adaptDispatch.cpp (lines 722–748), this method parses VT parameters and applies them via _ApplyGraphicsOptions:

VTParameters sgr = { 1, 34 };   // Bold + blue foreground
adapter->SetGraphicsRendition(sgr);

Display Erasure Operations

For erasing display regions, EraseInDisplay handles the ED sequences. The implementation (lines 3030–3078) resets the delayed-wrap flag, determines the erase region based on the EraseType parameter, and fills the area with spaces using the current erase attributes:

adapter->EraseInDisplay(DispatchTypes::EraseType::ToEnd);

Instantiation and Integration

In production code, AdaptDispatch is instantiated during terminal initialization and wired to the VT parser:

// Pattern used in terminal startup
auto dispatch = std::make_unique<AdaptDispatch>(
    api,           // ITerminalApi implementation
    renderer,      // Renderer instance
    renderSettings,// Render settings reference
    terminalInput  // Terminal input handler
);

parser.SetDispatch(dispatch.get());   // Parser now routes to AdaptDispatch

This wiring allows the parser to remain agnostic of the specific console implementation while AdaptDispatch handles the translation to Windows-specific APIs.

Unit Testing and Isolation

The adapter architecture enables comprehensive unit testing without requiring a full UI context. The test harness in src/terminal/adapter/ut_adapter/adapterTest.cpp (lines 417–447) creates AdaptDispatch instances with mock implementations of the dependency interfaces:

// From adapterTest.cpp
auto adapter = std::make_unique<AdaptDispatch>(
    *_testGetSet,    // Mock ITerminalApi
    &renderer,       // Test renderer
    renderSettings,  // Test settings
    _terminalInput   // Test input handler
);

This approach allows developers to verify individual VT command behaviors—such as verifying that CursorUp respects scroll margins or that SetGraphicsRendition correctly updates color attributes—in isolation from the rendering pipeline.

Summary

• AdaptDispatch implements the ITermDispatch interface to bridge the VT parser and console implementation in microsoft/terminal.
• The class translates escape sequences into concrete operations on cursor position, text attributes, and screen buffers.
• It maintains state for terminal modes (INSERT, ORIGIN, etc.) and delegates rendering to the Renderer and ITerminalApi subsystems.
• Located in src/terminal/adapter/adaptDispatch.hpp and src/terminal/adapter/adaptDispatch.cpp, it encapsulates all VT-specific logic separately from the parser.
• The adapter pattern enables extensive unit testing through mock dependencies in src/terminal/adapter/ut_adapter/adapterTest.cpp.

Frequently Asked Questions

What interface does AdaptDispatch implement?

AdaptDispatch implements the ITermDispatch interface defined in src/terminal/parser/termDispatch.hpp. This interface defines the contract that the VT parser uses to report terminal actions, allowing AdaptDispatch to provide the concrete Windows Console implementation for each virtual terminal command.

How does AdaptDispatch handle cursor movement?

The class processes cursor movement through methods like CursorUp and CursorDown, which internally call _CursorMovePosition to apply margin constraints and origin mode settings. According to the source in src/terminal/adapter/adaptDispatch.cpp (lines 1008–1010), these methods ensure that cursor coordinates remain within valid screen boundaries while respecting the terminal's current mode flags.

Why is AdaptDispatch essential for testing?

AdaptDispatch enables unit testing by accepting mock implementations of its dependencies (ITerminalApi, Renderer, etc.). As demonstrated in src/terminal/adapter/ut_adapter/adapterTest.cpp (lines 417–447), developers can instantiate the adapter with test doubles to verify VT command behavior without launching the full terminal UI or rendering pipeline.

Where is AdaptDispatch instantiated in the Windows Terminal codebase?

The class is instantiated during terminal initialization, typically within the terminal creation logic. The standard pattern involves creating a std::unique_ptr<AdaptDispatch> with references to the live ITerminalApi, Renderer, RenderSettings, and TerminalInput instances, then registering it with the VT parser via SetDispatch() to begin processing escape sequences.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}