docs: correct and complete CLAUDE.md for the v0.7.0 release - #114
Merged
Conversation
Release review of the 20 commits since v0.6.0. Three documentation defects, one of them actively wrong. WRONG: the active-terminal highlight section claimed the ring's accent "is stashed on Border.Tag at build time so the highlight method doesn't need to look up the VM". The code does the opposite and its own comment says so — RepoRoot is populated asynchronously by GitService and AccentColor changes when it lands, so a cached Tag goes stale and stops matching the sidebar. The Tag is only a fallback. MISSING: three services added this cycle were undocumented — DbGate (#102), PwshLocator (#104), ClaudeConfigGate (now shutdown-only after #111). MISSING: nothing described what actually makes a session active, which is now the most subtle thing in the codebase and was got wrong twice. Added a section covering all three routes and, more importantly, why two of them must come from the page: - WebView2 is an HwndHost, so mouse input on hosted native content raises no WPF routed events at all — a Preview handler on the host Border only ever sees the ring around the terminal (#108). - xterm's onData is not "the user typed": it also carries device-attribute replies, cursor-position reports, OSC colour replies and focus in/out, none of which are distinguishable from typing by inspecting the bytes (#106). Also recorded why the font-load re-fit exists (#113) and why the ClaudeLaunch stagger must stay a flat delay — including that a plain Task.Delay(2000) still logged gate=36339ms after the revert, which is what finally showed the gate was measuring an app-wide stall rather than causing one. Written as a "do not try this again" note with the measurements, since the adaptive version looks obviously better on paper and was attempted three times. Verified while here: every service on disk is now documented, and all nine keybindings in MainWindow match the documented table. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NDsEfog5kVkT5NmX1Ya5be
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation half of the release review over the 20 commits since v0.6.0. Three defects, one of them actively wrong.
Wrong
The active-terminal highlight section claimed the ring's accent "is stashed on
Border.Tagat build time so the highlight method doesn't need to look up the VM."The code does the opposite, and its own comment explains why:
RepoRootis populated asynchronously byGitServiceandAccentColorchanges when it lands, so a cached Tag goes stale and stops matching the sidebar ring. The Tag survives only as a fallback.That's the worst kind of doc error — it would have sent someone optimising in exactly the wrong direction.
Missing — three services
DbGate(#102),PwshLocator(#104), andClaudeConfigGate(now shutdown-only after #111) were all added this cycle with no entry in the services table.Missing — what makes a session "active"
Nothing described this, and it's now the subtlest thing in the codebase. I got it wrong twice.
The new section covers all three routes (sidebar click, typing, pane click) and, more usefully, why two of them must come from the page:
HwndHost. Mouse input on hosted native content raises no WPF routed events, tunnellingPreview*included — a handler on the host Border only ever sees the thin ring around the terminal (fix(terminal): make clicking a pane activate it, from the page side #108).onDatais not "the user typed". It also carries device-attribute replies, cursor-position reports, OSC colour replies and focus in/out. None are distinguishable from typing by inspecting the bytes; xterm knows internally but doesn't expose it.onKeyis the only honest source (fix(terminal): promote on real key events, not on anything xterm sends #106).Both are non-obvious enough that the next person hits the same walls without this written down.
A "do not try this again" note
The Claude launch stagger now documents why it must stay a flat delay, with the measurements: gates of 12574ms, 22953ms and 31378ms against a 2000ms cap, and — after the revert — a plain
Task.Delay(2000)still logginggate=36339ms. That last number is what finally showed the gate was measuring an app-wide stall rather than causing one.Written explicitly as a warning because the adaptive version looks obviously better on paper. It was attempted three times.
Also records why the font-load re-fit exists (#113).
Verified while here
MainWindowmatch the documented table🤖 Generated with Claude Code
https://claude.ai/code/session_01NDsEfog5kVkT5NmX1Ya5be