CodeVetter · Repo Unpack · Extension points
microsoft/terminal
The codebase is built around explicit extension surfaces: the ALL_SHORTCUT_ACTIONS X-macro generates dispatch for every bindable action; ACTION_ARGS_STRUCT macros synthesize args classes with JSON keys; NewTabMenuEntry variants compose the new-tab menu; IDynamicProfileGenerator feeds discovered profiles; ITerminalConnection abstracts transports; IStateMachineEngine/ITermDispatch decouple the VT parser from its consumer; renderers are swappable behind the renderer/base interface; settings fragments + app extensions let third parties inject configuration; and features.xml adds staged feature flags. HwndTerminal/WpfTerminalControl expose the terminal as an embeddable control.
- Adding a new keybindable action means adding one line to ALL_SHORTCUT_ACTIONS in AllShortcutActions.h — the X-macro auto-generates the ShortcutAction enum entry, the ShortcutActionDispatch case that raises the event, and handler declarations consumed by TerminalPage/AppActionHandlers.
- Action argument types are generated by macro: ACTION_ARGS_STRUCT(MyArgs, MY_ARGS) plus a per-action args X-macro produces the class, its JSON keys, and (de)serialization hooks — documented inline in ActionArgsMagic.h including a godbolt -E tip for debugging expansion.
- The new-tab dropdown is data-driven from settings via NewTabMenuEntry variants — Profile, Folder, Separator, RemainingProfiles, MatchProfiles, Action — recursively materialized by _CreateNewTabFlyoutItems.
- New dynamic profile sources implement IDynamicProfileGenerator and are enumerated during CascadiaSettings::LoadAll -> GenerateProfiles; existing examples are WslDistroGenerator, PowershellCoreProfileGenerator, AzureCloudShellGenerator, VisualStudioGenerator, SshHostGenerator.
- Third-party settings injection: JSON 'fragments' dropped in '<LocalState>\Microsoft\Windows Terminal\Fragments' or delivered via the 'com.microsoft.windows.terminal.settings' app-extension host are merged by FindFragmentsAndMergeIntoUserSettings and surfaced as ExtensionPackages in the Settings UI.
- New connection transports implement ITerminalConnection (idl: Initialize(ValueSet), Start, WriteInput, Resize, Close; events TerminalOutput/StateChanged) — ConptyConnection, AzureConnection, EchoConnection are the built-ins, and _CreateConnectionFromSettings selects by profile.ConnectionType().
- The VT parser is engine-agnostic: StateMachine owns an IStateMachineEngine (OutputStateMachineEngine for output, InputStateMachineEngine for input), which forwards to an ITermDispatch/ITerminalApi implementation — letting conhost (AdaptDispatch) and TerminalCore share the same parser.
- Settings layering is tag-based: ParsedSettings entries carry an OriginTag (InBox, User, Generated, Dynamic, Fragment) and SettingsLoader merges them in a fixed order — new settings sources plug in as additional origins without changing the merge engine.
- New feature flags are added declaratively in src/features.xml with a name/description/stage and per-branding alwaysEnabled/alwaysDisabled tokens, then materialized as TIL_FEATURE_* macros by tools/Generate-FeatureStagingHeader.ps1 (schema: tools/FeatureStagingSchema.xsd).
- The terminal control is embeddable: HwndTerminal hosts it as a raw HWND and WpfTerminalControl wraps it for WPF apps — the intended surface for third-party embedding.
- wt subcommands extend through CLI11: _addNewTerminalArgs adds the shared option set to each subcommand and each subcommand registers a callback that pushes ActionAndArgs onto _startupActions — new subcommands follow the new-tab/split-pane pattern.
- Adding a new setting is a documented recipe (doc/AddASetting.md): model class + .idl property + JSON key in the serialization layer + defaults.json + Settings UI page — the specs folder contains design docs for past additions like marks, unfocused appearance, and quake mode.