Archived notes from the C#/Avalonia reimplementation. Current product docs start at README.md and parity-status.md.
This was the plan for turning the prototype into Devolutions Terminal, a behavior- and settings-compatible Windows Terminal host on .NET 10, NativeAOT, and Avalonia instead of C++/WinRT/WinUI.
It is not a line-for-line transcription of CppWinRT, MIDL, or XAML Islands. Those types do not exist in this stack. The bar is:
- A user can point the app at a real
settings.jsonand get the same profiles, schemes, keybindings, and startup behavior for the supported subset. - Modern shells, editors, and TUIs (
pwsh,cmd, WSL, neovim, lazygit) work. - NativeAOT publish of a single
Devolutions.Terminal.exestays green.
The original C++ Windows Terminal tree is the compatibility oracle.
| Project | What it covers today |
|---|---|
Devolutions.Terminal.Core |
Circular scrollback/reflow, grapheme-aware cells, shell marks/search/export, complete daily-driver VT plus bounded DCS/Sixel/DRCS/macros/VT52/rectangular operations |
Devolutions.Terminal.Render |
Immutable plans, HarfBuzz shaping, fallback fonts, bounded Skia text-blob and image caching, dirty-row contracts |
Devolutions.Terminal.Connection |
Restartable NativeAOT-safe ConPTY, Linux PTY, and Azure Cloud Shell HTTP/WebSocket connections |
Devolutions.Terminal.Settings |
Complete MTSM projection, tri-state inheritance, migrations, fragments, profile generators, state persistence, plus the 92-action inventory, typed action arguments, normalized key chords, current/legacy binding parsing, and source-generated NativeAOT-safe JSON |
Devolutions.Terminal.Control |
Avalonia TermControl: Skia rendering, search, shell-region selection, clipboard/paste policy, mouse/touch/IME, accessibility, and event-driven output draining |
Devolutions.Terminal.App |
Persistent tabs/panes, all-action dispatch, action/command-line/history/tab palettes, settings UI, Azure auth UI, scratchpad, and notifications |
Devolutions.Terminal |
NativeAOT executable, authenticated single-instance broker, multi-window routing, and notification-area integration |
The baseline also includes dedicated settings, connection, control, app, compatibility, and UI test projects; x64/ARM64 NativeAOT CI; architecture decisions; and a generated compatibility inventory covering 120 settings keys, 92 actions, 123 VT dispatch methods, 14 CLI commands, and 25 settings pages.
The practical daily-driver surface is implemented. Inventory actions that need an upstream shell-completion/Quick Fix provider or a Windows-only native integration return an explicit unavailable result or notification rather than silently doing the wrong thing.
Leave these in the C++ tree. Do not port them as part of this app:
conhost.exe/ console driver / server IOCTL protocol- The inbox console property sheet (
propsheet,propslib) - WinUI, XAML Islands, CppWinRT, MIDL
- Store submission / OneBranch / PGO of the C++ build
- Pixel-identical AtlasEngine D3D shaders (match visually, not the HLSL)
Platform boundaries that remain intentionally external to the C# application:
- Cross-process visual tab tear-off has versioned broker contracts but cannot transfer a live ConPTY/HPCON through the public API.
- The Windows 11 Explorer verb requires an architecture-matched native
IExplorerCommandCOM DLL loaded by the shell. - Default-terminal delegation requires Windows console registration and handoff contracts that are not exposed as a managed app-only API.
- System toast activation and jump lists require a WinRT/Windows App SDK projection. In-app accessible notifications and notification-area behavior remain available without those dependencies.
settings.jsonkeys used by WT defaults + common user files (profiles,profiles.defaults,schemes,actions/keybindings,theme, launch/window settings). Unknown keys are preserved on round-trip.- Profile GUIDs for PowerShell, cmd, Windows PowerShell.
- Default keybindings from
defaults.json. wtsubcommands that map to actions:nt,sp,ft,mf,focus-tab.- OSC 0/2 title, OSC 7 cwd, OSC 8 hyperlinks, OSC 9;9 notifications, CSI SGR, CUP/ED/EL/IL/DL, DECSET 1/7/25/47/1049/2004/1000/1006, win32-input-mode where ConPTY emits it.
- WinUI chrome, TabView, Mica/acrylic material (Avalonia equivalents)
- AtlasEngine D3D glyph cache internals
- UIA peer class names
ms-appx:///icon URIs (map toavares://or file paths)- Elevation / packaged identity until MSIX exists
C++ / WinUI .NET / Avalonia
───────────────────────────────── ──────────────────────────────────
buffer/out + TerminalCore Devolutions.Terminal.Core (buffer, engine)
terminal/parser + adapter + input Devolutions.Terminal.Core.Vt (parser, dispatch, input)
renderer/atlas + base Devolutions.Terminal.Render (Skia atlas)
cascadia/TerminalConnection Devolutions.Terminal.Connection
cascadia/TerminalSettingsModel Devolutions.Terminal.Settings
cascadia/TerminalControl Devolutions.Terminal.Control (TermControl + search)
cascadia/TerminalApp Devolutions.Terminal.App (tabs, panes, actions)
cascadia/Devolutions.Terminal Devolutions.Terminal (windowing host)
cascadia/TerminalSettingsEditor Devolutions.Terminal.Settings.Editor (Avalonia pages)
Layer rules:
- Core has no Avalonia, no Win32 UI. Parser and buffer must be testable
on any
net10.0RID. - Connection selects an OS transport. Windows uses ConPTY; Linux uses the
bundled
forkptyrelay. Keep each implementation behind its corresponding supported-platform annotation. - Control talks to Core + Connection. It owns rendering, input, selection, search box, scrollbar.
- App owns ActionMap, panes, tabs, command palette, CLI.
- NativeAOT:
LibraryImportnotDllImport; source-generated JSON; no runtime XAML loading; no reflection DI;IsAotCompatible=trueon production projects. - Windows shell: the managed host keeps
BuiltInComInteropSupport=false. Architecture-matched native package helpers own Explorer COM, jump lists, toasts, and the explicit unavailable OpenConsole handoff boundary.
Linux uses the same Avalonia/Skia UI and built-in or Ghostty terminal engines as
Windows. Local processes are hosted by dt-pty-host, a small bundled forkpty
relay that preserves interactive shell, resize, signal, and process-group
semantics. Dynamic profiles discover $SHELL, bash, zsh, fish, PowerShell, and
sh; settings and state follow XDG directory conventions.
Build the deterministic NativeAOT package set on Linux:
dotnet/scripts/Build-LinuxPackage.sh linux-x64 0.1.0 artifacts/packages all
dotnet/scripts/Build-LinuxPackage.sh linux-arm64 0.1.0 artifacts/packages allARM64 cross-publish from x64 requires the GNU AArch64 linker/binutils packages.
The resulting tar, DEB, RPM, and AppImage preserve executable permissions for
Devolutions.Terminal, wt, and dt-pty-host. All four consume one canonical
install root containing validated freedesktop metadata, hicolor icons,
architecture-correct native libraries, licenses, deterministic inventory/SPDX
SBOM, and a DESTDIR-aware install/uninstall helper.
Linux opens and notifications use bounded, argument-list-only subprocesses:
the freedesktop portal is preferred, with xdg-open and notify-send
fallbacks. Protocol and default-terminal selection are separate explicit,
reversible helper actions; installation never overwrites those user choices.
Do not take a C++/CLI or C++/WinRT interop dependency on Devolutions.Terminal.*
DLLs. That reintroduces the runtime we are leaving.
AtlasEngine (src/renderer/atlas) is a DWrite + D2D/D3D glyph atlas. Avalonia
already uses Skia. Porting Atlas 1:1 would mean a second graphics stack and
break NativeAOT simplicity.
Decision: C# Skia glyph atlas inside Devolutions.Terminal.Control / Devolutions.Terminal.Render.
Match Atlas behavior:
- Cell grid with wide glyphs, zero-width marks, and built-in row rendition
- Dirty-row invalidation, not full-frame redraw
- Font fallback (Cascadia Mono → Consolas → bundled Noto Color Emoji → Segoe UI Emoji)
- Bold/italic as real faces when present, synthetic otherwise
- Cursor styles: bar, vintage, underscore, filled/empty box
- Reverse video, underline, strikethrough
- Selection overlay and hyperlink underline
- Background images and platform-appropriate acrylic/Mica approximations
P1 now uses a retained Skia custom draw operation, HarfBuzz-shaped cell clusters, bounded text-blob/typeface caches, dirty-row contracts, and image overlays. Stable image ownership across reflow and built-in double-width/double-height line rendition are implemented.
Reimplement TerminalSettingsModel in C#, not WinRT projections.
Implemented load order:
- Embedded
defaults.json(checked in, generated from the C++ copy) - Deterministic dynamic profiles (PowerShell, inbox shells, WSL, SSH, VS)
- Fragment files (
%LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\,%PROGRAMDATA%\...) - User
settings.json
Fragment updates are applied after profile identity is known, including to
user-created profiles. Ordinary null clears an override and resumes
inheritance; nullable color/tab settings preserve an explicit null. User profile
order is retained before unmatched inbox/fragment profiles. Models expose
User, InBox, Fragment, Generated, and ProfilesDefaults origins.
state.json is a separate, source-generated model for settings hashes,
generated profiles, recent commands, dismissed UI, persisted windows, and named
workspaces. It is loaded independently (no settings layering), rejects malformed
payloads as a whole, and is written atomically.
Required types:
- Global/window settings from
MTSMSettings.h - Profiles with
profiles.defaults, font, focused/unfocused appearance, and compatibility aliases - Color schemes, theme pairs and nested themes, media resources, and new-tab menu
- Warnings for invalid defaults, profile/scheme/theme references, environment names, and menu structure
Actions and keybindings retain their lossless raw JSON and also project into
ActionMap/ActionAndArgs for typed lookup and dispatch.
Typed JSON is source-generated (System.Text.Json + JsonSerializerContext).
Settings layering and unknown-property preservation operate on JsonNode, so
NativeAOT round-trips comments-stripped WT JSON without reflection.
Default actions live in a C# copy of the actions block from
src/cascadia/TerminalSettingsModel/defaults.json. Keep the JSON in sync;
do not hand-code key chords in the window.
ITermDispatch is ~160 methods. The port implements the daily-driver and
advanced bounded subsets; engine-specific limits are recorded in
parity-status.md.
| Bucket | Sequences / features | Phase |
|---|---|---|
| A. Editing | ICH/DCH/IL/DL/ECH, DECSTBM, SU/SD, DECSC/DECRC | P0 slice complete |
| B. Modes | DECCKM, DECAWM, DECTCEM, alt buffer, bracketed paste, mouse SGR | P0 slice complete |
| C. Reports | DA1/DA2, DSR CPR, DECRQM | P0 slice complete |
| D. Color | SGR 38/48 2/5, OSC 4/10/11/12, indexed/RGB | P0 slice complete |
| E. Unicode | UTF-8, wcwidth, emoji ZWJ, reflow on resize | Wide/combining/ZWJ behavior is substantial; complete UAX #29 coverage remains |
| F. Shell integration | OSC 7, OSC 133 marks, OSC 8 hyperlinks | Implemented |
| G. Input | Application keypad, win32-input-mode, Kitty protocol | Implemented in the built-in engine; pinned Ghostty ABI limitations are explicit |
| H. Images | Sixel, OSC 1337, ConEmu | Built-in bounded decode/render, DECSDM behavior, and stable ownership complete; pinned Ghostty image projection is explicitly unavailable |
| I. Rare VT | Rectangular ops, DECDLD, macros, DECRQSS, VT52 | Built-in core, DRCS rendering, and VT52 input implemented |
The .NET buffer now uses bounded circular scrollback, keeps independent
main/alternate state (cursor, margins, attributes, tab stops), reflows logical
wrapped lines on resize, repairs wide-cell boundaries, retains combining marks
and hyperlink metadata, and exposes detached read-only snapshots. Existing
GetRow, cursor, selection, and scroll-offset APIs remain compatible with
Devolutions.Terminal.Control.
Buffer work beyond the current parity slice:
- Complete UAX #29 grapheme and emoji ZWJ coverage
- Ghostty image projection if a future pinned C ABI exposes image resources
Bounded image payloads, stable image ownership, row rendition, DCS payload dispatch, rectangular operations, downloadable resources and rendering, macros, VT52 output/input, extended keyboard input, Sixel, DECRQSS/XTGETTCAP, and OSC 52/133/1337 core behavior are implemented.
Port tests from src/terminal/parser/ut_parser and
src/cascadia/UnitTests_TerminalCore as xUnit facts. That is the correctness
oracle — not visual screenshots.
P0:
- ConPTY: create, resize, write UTF-8, wait, close
- Env inheritance + profile
environmentmap startingDirectory,commandlineexpansioncloseOnExit(always / graceful / never / automatic)- Resize must call
ResizePseudoConsoleandTerminalEngine.Resize - Restart an active connection without replacing its pane/control
P1:
- WSL path translation
elevatevia a small helper (not the C++ shim at first)- Inbound ConPTY listener / default-terminal handoff
- Working directory from OSC 7
P2:
- Azure Cloud Shell (
AzureConnection) - Process handoff from
wt/OpenConsole
Reimplement TerminalApp + Devolutions.Terminal EXE as Avalonia, following the
same object graph:
App
└─ Window (per IslandWindow / AppHost)
├─ Titlebar + TabRow
├─ Pane tree (binary split: horizontal / vertical)
│ └─ TermControl
├─ Command palette / Suggestions
├─ Search box (in-control)
└─ Settings page (optional pane content)
AllShortcutActions.h is the action checklist (92 actions). P0 implements
the ones users hit every day; the rest still parse and return explicit
unsupported dispatch results.
CopyText, PasteText, NewTab, CloseTab, CloseWindow, NextTab,
PrevTab, SwitchToTab, DuplicateTab, SplitPane, ClosePane,
MoveFocus, ResizePane, TogglePaneZoom, AdjustFontSize,
ResetFontSize, ScrollUp/Down/Page/ToTop/ToBottom, Find,
OpenSettings, ToggleCommandPalette, NewWindow, Quit, SelectAll,
ClearBuffer, SendInput, MovePane, CloseOtherPanes,
ToggleSplitOrientation, RestartConnection, FindMatch,
ToggleAlwaysOnTop, ToggleFullscreen, ToggleFocusMode, and
MultipleActions.
Tab color/rename, mark mode, full-scrollback search, export buffer,
quake/global summon, broadcast input, suggestions, color selection,
restore last closed, and wt commandline.
Quick Fix, workspaces, scratchpad, markdown pane, identify windows, shader effects, opacity.
Windowing (WindowEmperor, remoting):
- P0: one process, many windows (
Ctrl+Shift+N) is enough - P1: single-instance +
wt -wtargeting (named pipe / localhost socket, not WinRT remoting) - P2: tab tear-off, quake, tray icon, virtual desktop
src/cascadia/TerminalSettingsEditor is ~150 XAML/IDL/cpp files. Do not
clone that page-for-page on day one.
P0: “Open settings file” (already there) + JSON schema validation errors in a toast.
P1: Avalonia settings window with the pages people actually use:
- Startup / Launch
- Interaction
- Appearance (global)
- Color schemes
- Profiles (base + appearance)
- Actions (list + key chord capture)
Rendering, compatibility, extensions, new-tab-menu, and advanced profile pages are now implemented in the compiled-XAML editor.
Port AppCommandlineArgs onto System.CommandLine (AOT-friendly).
P0: nt / new-tab, --profile, --startingDirectory, --, sp /
split-pane, --focus-tab.
P1: window name (-w), move-focus, move-pane, save, startup actions
from settings.
PublishAot=trueonDevolutions.Terminalonly; tests stay JITLibraryImport+partialfor all kernel32/user32- Source-generated JSON and regex
- Cascadia fonts as
AvaloniaResource - Trimmer roots:
Devolutions.Terminal,Avalonia.Themes.Fluent, settings context - COM (shell extension, WSL query, VS setup) isolated behind feature
switches; prefer subprocess/
vswhereover in-proc COM in P1 - MSIX / sparse package identity is P2 (notifications, default terminal)
| Layer | Tests | Source of truth |
|---|---|---|
| Parser | xUnit, byte-level | ut_parser cases |
| Buffer | xUnit, reflow/scroll | UnitTests_TerminalCore |
| Settings | xUnit, JSON round-trip | UnitTests_SettingsModel + real defaults.json |
| Actions | xUnit, key chord → action | defaults.json actions |
| Control | headless Avalonia/Skia tests | golden grids and interaction contracts |
| ConPTY | optional Windows-only test | spawn cmd /c echo |
The dedicated workflow builds/tests the .NET solution, publishes Windows and Linux x64/ARM64 NativeAOT, validates MSIX plus tar/DEB/RPM/AppImage artifacts, and runs native Linux ARM64 non-UI gates.
Goal: replace Windows Terminal for local pwsh/cmd/wsl work.
- Settings. Load WT
defaults.json+ user file; inheritance; ActionMap; unknown-key preservation. Implemented. - Actions + default keybindings. Complete catalog dispatch is wired to the window or an explicit platform capability.
- Panes. Binary split tree, focus movement, zoom, close. Implemented.
- Search. Find in the visible buffer, next/prev. Implemented; full scrollback Unicode search controller is ready for overlay integration.
- Command palette. Action search, fuzzy ranking, and dispatch. Implemented.
- Dynamic profiles. Installed PowerShell, WSL, cmd, Windows PowerShell, SSH hosts, and Visual Studio developer shells. Implemented.
- Buffer/VT bucket A–D completed and tested.
- Scrollbar, copy HTML/RTF optional, confirm close.
wt nt/wt spCLI.
Exit criteria: open the app, split a pane, bind a custom action in
settings.json, search scrollback, WSL profile appears, NativeAOT still
publishes.
Goal: settings UI and rendering that do not feel like a prototype.
- Skia glyph atlas, ligatures optional, CJK widths, dirty-row paint
- Hyperlinks, OSC 7, shell-integration marks
- Settings editor (launch, profiles, schemes, actions)
- Multi-window + single-instance
wt -w - Selection mark mode, find match, export buffer
- Themes, acrylic/Mica approximation, tab color
- win32-input-mode / application keypad
- Restart connection, elevate, WSL path translation
- Accessibility: basic UIA via Avalonia AutomationPeer
Exit criteria: a typical settings.json from a WT Preview user works
without hand edits; neovim and lazygit look correct.
- Sixel, OSC 1337, and bounded ConEmu image decoding/rendering complete
- Azure Cloud Shell
- Extension fragment discovery/merge complete; extension UI remains
- Notification-area behavior and Windows global summon/quake hotkeys complete; Linux manual/broker summon is available with explicit portal limitations.
- Broadcast input and command-history suggestions complete; provider-backed shell completion and Quick Fix report unavailable when the shell supplies no data.
- Scratchpad window complete; markdown pane content remains outside the terminal-pane persistence contract.
- Default-terminal handoff is a documented OS/native boundary.
- x64/ARM64 MSIX and bundle include jump-list, toast, and Explorer helpers.
- Versioned workspaces and bounded Skia retro effects are implemented.
dotnet/
Devolutions.Terminal.slnx
src/
Devolutions.Terminal.Core/ # buffer, VT, input encoding
Devolutions.Terminal.Render/ # HarfBuzz shaping, Skia text-blob cache, render plans
Devolutions.Terminal.Connection/ # ConPTY, Linux PTY, Azure Cloud Shell
Devolutions.Terminal.Settings/ # CascadiaSettings, ActionMap, generators
Devolutions.Terminal.Control/ # TermControl, search, scrollbar
Devolutions.Terminal/ # app host, tabs, panes, palette, CLI
Devolutions.Terminal.Settings.Editor/ # P1 settings pages
tests/
Devolutions.Terminal.Core.Tests/
Devolutions.Terminal.Settings.Tests/
Devolutions.Terminal.Control.Tests/
PORTING.md
README.md
The settings model, ActionMap, panes/tabs, search/palette, VT/buffer, dynamic-profile, CLI/broker, Skia renderer, accessibility, Azure, and MSIX layers are integrated on the consolidated branch. Future changes must keep the full Release suite, x64/ARM64 NativeAOT publish, broker smoke, and package validation green.
- VT completeness is the long pole. Under-implementing dispatch is how TUIs break. Gate on parser tests, not screenshots.
- Reflow and wide glyphs. Easy to get wrong; steal cases from
ReflowTests.cpp. - COM + NativeAOT. VS/WSL detection must not use runtime-callable
wrappers. Prefer CLI (
wsl.exe -l -q,vswhere). - settings.json comments. WT allows comments; STJ needs
ReadCommentHandling.Skipon a serializer that still AOT-compiles. - Default terminal / handoff. Requires packaged identity. Do not block P0/P1 on it.
- Performance. The Skia/HarfBuzz cache and dirty-row contracts are in place. Output draining is event-driven rather than a 125 Hz idle poll. Full-history search and viewport snapshot reuse remain the next profiling-led optimization opportunities.
- Organization:
doc/ORGANIZATION.md - Settings schema:
doc/cascadia/SettingsSchema.md,src/cascadia/TerminalSettingsModel/defaults.json - Actions:
src/cascadia/TerminalSettingsModel/AllShortcutActions.h - VT surface:
src/terminal/adapter/ITermDispatch.hpp - Atlas:
src/renderer/atlas/README.md - Process model:
doc/specs/#5000 - Process Model 2.0/ - ConPTY sample we followed:
samples/ConPTY/MiniTerm