The Explorer stops fighting the reader

[jbachorik]

Eleven usability defects in the Session Explorer, found by driving the real app rather than reading the code, then fixed, reviewed and re-verified in the app.

The report that started this was "it is more chaotic than before: sections collapse and expand seemingly randomly, the scrolling is totally weird, and there are no mnemonics". Each of those turned out to be a real defect with a specific cause.

What was wrong, and what it is now

Symptom	Cause	Fix
"Sections collapse at random"	The rail's expand caret was an 11px dim glyph that did not read as a control, so the only collapse target was invisible and every other pixel opened the file	A caret you can see and hit, on a plate, at full text colour
…and re-expand on their own	rebuild() recreated every row expanded, and it runs on every keystroke, file open and findings refresh	Collapse state and scroll position survive a rebuild
"Scrolling is totally weird"	Flowless's VirtualFlow consumes every wheel event, even when a body sized to its content has nothing to scroll	The wheel reaches the skim scroller; a non-overflowing body stays inert
Files opened in the middle	setSkim anchored on a CodeArea that had not been laid out — it asked for line 42 of a 68-line file	The open path places the view itself and computes no bogus anchor
Clicking a search result did nothing	revealLine silently no-op'd for any line no member covers — imports, blank lines, class headers	Lines resolve forward to the next member; "go to line N" always lands
…and when it did, it did not stick	ScrollPaneSkin re-derives vvalue on the next layout to preserve the old absolute offset, overwriting the scroll	The reveal is re-applied until it holds
The rail lost the file you were reading	The query filter ran before the open-file exemption	The open file keeps its row under any scope and query, without inflating match counts
Nothing worked at 1000px	No responsive behaviour at all: …, …, e… where the controls should be	Rail auto-collapses, breadcrumb elides from the left, controls keep a floor
"No mnemonics"	/, d and s were bound and advertised nowhere — an AGENTS.md rule violation	Advertised, behind a parity test that fails in both directions
A toast covered the peek's actions	Bottom-centre toast over a bottom-anchored action row	The toast moves while a peek is open
Signature shown twice per open member	The body started at the member's own start line	It starts after it

Plus: skim-by-default is now a setting (~/.drydock/config.json, Settings → Explorer) rather than something the Explorer does to you.

Notes for review

• UserConfig.updateAsync — the read-modify-write was two executor tasks, so two overlapping preference edits could each read before either wrote. It is one task on the thread that already serialises writes.
• A false "read" signal. The bogus open anchor did not merely scroll wrong: revealLine expands what it lands on and reports it through onMemberRead, so every changed file opened with a member nobody chose unfolded and permanently marked read — a minimap tick and a dwell signal for code no one had looked at.
• Three tests were found passing for the wrong reason and tightened: two asserted only vvalue > 0, which the very overwrite they were meant to catch satisfies, and one could not fail at all.

Verification

1269 tests, 0 failures. Every fix was verified RED-then-GREEN by reverting it.

The scroll tests wait for the outcome rather than counting FX pulses — fixed pulse counts were behind three separate order-dependent failures in this class.

Screenshots of the running app before and after, at 1600×1000 and 1000×760, in both themes.

Two behaviours are deliberately untested, and say so in the code: the pixel-vs-fraction scroll restore (a test restored reliably alone and timed out in the full suite), and topLine()'s exact-edge boundary (rows carry 1px spacing, so two edges never coincide — a test could only pass by construction).

Two need a human, because no harness can drive them: the mouse wheel over open code, and a click on a search match that lands inside an untouched private helper.

🤖 Generated with Claude Code