Repository navigation
Row-change tracking (ContentVersion, CopyChangedRows) and Terminal.EncodeKey for headless hosts - #193
Conversation
JohnCampionJr
left a comment
There was a problem hiding this comment.
Pre-merge review (Codex), for the PR author
Reviewed 9c47782. Three should-fix findings, detailed inline: shifted OEM keys fall out of Win32 encoding; NumLock-off keypad navigation gets the numeric VK; tall OSC 66 changes omit the other visible rows they cover. No blocking findings or nits.
Checked cache invalidation replacements, line identity/version tracking across scroll/resize/alternate screen, independent observers, print-path work, and mode selection against the actual control. The deliberate DECKPAM difference is accounted for. Baseline: 335 focused tests passed; PR: 413 existing/new tests passed. Four additional reproductions fail as described (two cover the sized-text finding); both Win32 mismatches also fail comparisons against TerminalView's actual encoder. Current CI including the perf gate is green. No separate local benchmark was run.
9c47782 to
85f7c9b
Compare
JohnCampionJr
left a comment
There was a problem hiding this comment.
Pre-merge review follow-up (Codex), for the PR author
Rechecked 85f7c9b: all three original findings are resolved. The four unchanged core reproductions and both comparisons against the actual control now pass, as do all 434 filtered core checks. The new tests cover shifted OEM release/Win32 precedence, NumLock-off navigation and old/new tall-run coverage including anchors above the viewport. The documented non-enhanced keypad navigation flag is appropriate.
One new should-fix regression in the sized-row delta is detailed inline: first observation of a terminal constructed with Rows = 0 throws IndexOutOfRangeException. My focused test fails on this head and passes with the previous row tracker. Please initialize the watched arrays independently of the visible row count. No other new findings in the delta. Original threads left for the author/maintainer to resolve.
85f7c9b to
6aa52d4
Compare
JohnCampionJr
left a comment
There was a problem hiding this comment.
Pre-merge review follow-up (Codex), for the PR author
Rechecked 6aa52d4 (stack fix ec4bffc): the zero-row finding is resolved. My unchanged construction → ContentVersion → empty CopyChangedRows → resize-to-five reproduction passes. The new author regression also confirms GetRowVersion(0) throws ArgumentOutOfRangeException at zero rows and that all five rows are reported after resize.
All 101 filtered row-tracking/key-encoding checks pass, including the retained original reproductions. Keying initialization on the watched-array size fixes first observation without changing the normal resize behavior. No new findings in this delta. Thread resolution left to the author/maintainer.
6aa52d4 to
cecb21d
Compare
JohnCampionJr
left a comment
There was a problem hiding this comment.
Pre-merge review follow-up (Codex), for the PR author
Reviewed cecb21d (stack 7aff34e). No findings in this delta.
ContentVersion is a pure Volatile.Read of the cached counter; it neither inspects the buffer nor updates tracking state. RefreshContentVersion performs the comparison explicitly. CopyChangedRows and GetRowVersion still refresh themselves, and their docs describe that behavior. Independent observers retain their own last-seen versions without consuming each other's changes.
ResolveUnderline preserves the null foreground-fallback sentinel for default/reset, resolves indexed colors through the snapshot palette, and distinguishes RGB (including black and numerically-small values) from indices. Explicit underline color stays independent of inverse/bold; null lets the host use its final inverse/dim foreground, as documented. Out-of-range and negative direct-set indices safely fall back.
Baseline color/attribute checks: 115 passed. Current focused color/row/attribute suite, including 13 additional observer and inverse/underline checks: 166 passed. No public test or runtime limitation encountered for these cases.
3b84116 to
234e45b
Compare
Why
A headless host is any program that drives a
Terminalwithout a renderer: a test harness, a recorder, or an agent that runs a TUI and reads its screen back as data. Two things are missing for one, and today every such host writes its own copy of them:Writea host has to diff every cell of every row to find out what moved.TerminalView, so any other host has to copy that logic.The use case behind this PR is an agent driving a terminal session: it sends keys, waits for the screen to settle, and asks for just the rows that changed since its last look.
API
Row-change tracking (
Terminal.RowChanges.cs,Buffer/BufferLine.Version.cs)Buffer.X/YandCursorVisible), and screen-wide state like the palette,ReverseVideoand the title. A bare SGR or an emptyWritedoesn't move the version either.BufferLinethat already clearedCache(the invalidation the renderer depends on) now callsMarkChanged(), which clearsCacheand increments_version. So the two can't disagree, and the only cost on the print path is one increment. The comparison happens when a host asks: each call looks at the visible rows once, comparing each row's (line, version) with what the previous call saw, and gives the rows that differ a newContentVersion. Asking costs O(rows), never O(cells), and nothing allocates. The per-row versions are stored on the terminal, so any number of observers can each keep their own last-seen version.RefreshContentVersion,CopyChangedRowsandGetRowVersionfollow the same contract asWrite: call them on the thread that writes, or serialized with it.ContentVersionreads one field and writes nothing, so it's safe from any thread. What it reports is the last look, and it's 0 before the first one.CopyChangedRows(since, rows); since = ContentVersion;.CopyChangedRowslooks first, so the loop needs no separate refresh.ColorSnapshot.ResolveUnderline(Common/ColorPalette.cs)This is the underline counterpart of
ResolveBackground. SGR 58;5;n resolves through the palette, and 58;2 RGB comes through as named. Bold changes neither. It returns null when the underline should follow the text colour: SGR 59, no SGR 58, or an index past the palette. The host then draws it in the colour it used for the text, after its own inverse and dim.Terminal.EncodeKey(Terminal.KeyEncoding.cs)TerminalViewuses.Win32InputModecomes first (it's a transport, not a competing encoding), thenKittyKeyboardActivethroughGenerateKittyKeyInput, then the legacy generators, which honour DECCKM and DECKPAM.KeyEventthe Kitty path already uses.Keyis a functional-key name ("ArrowUp","F5","Shift") or the typed text.Codeis the physical key, and it's the only thing that separates the keypad from the main keys.KeyCode, when set, is taken as the Windows virtual-key code.MetaKeyis Super: Kitty encodes it (bit 8), while legacy and Win32 can't, so they drop it. That's whyKeyModifiersdoesn't need a Super member. AltGr should be reported as the composed character with Ctrl and Alt clear.ESC b, Cmd shortcuts, selection edits), Win32 lock-key state (the event doesn't carry it), and ConPTY's bare-Escape-as-a-Win32-record rule, which is a fact about that transport rather than the protocol.Code) goes throughKeypad*, so DECKPAM is honoured. With DECKPAM off the output is the same as today, the literal character. F13–F20 are covered in legacy mode as well.Performance
MarkChanged()replacesCache = nullin the same places, so the print path gains one field increment per line write and nothing else: no branch, no allocation. I measured it with the bench's ownciandcomparemodes, two runs of each side alternated on one machine (arm64 macOS, 60M chars per corpus). Allocation is unchanged, and every timing difference is inside the noise for its corpus:CI's perf gate is the real check.
Tests
RowChangeTrackingTests(22):ContentVersionis a pure read of the last look, and the usual loop works without a refresh.EncodeKeyTests(73): a table of expected bytes per mode (legacy, DECCKM, DECKPAM, Kitty disambiguate, Kitty with event types, Win32, Win32+Kitty), written as literals that match whatTerminalViewsends today, plus releases, repeats,KeyCodeand KAM. The Win32 rows include NumLock-off keypad navigation and shifted OEM keys.ColorPaletteTests:ResolveUnderlinefor every SGR 58 encoding (plus 59 and none), the live palette, and an index past it.VK_NUMPADn, or drops the OEM code or US-layout fallback; or makes the getter compare again, stops the refresh from looking, or breaks the underline's RGB, palette, default or bounds rules.XTerm.NET.Testsproject: 2642 passed, 1 skipped, 0 failed.🤖 Generated with Claude Code