Arrow keys and Page Up/Down don't scroll until the window is tabbed into
Nobody has claimed this yet.
- Dominant language
- Swift
- Stars
- 50
- Forks
- 4
- PR merge metrics
- No merged PRs in 30d
Description
Opening a document straight from Finder (or Nimble Commander, which is what I
use) leaves the keyboard unable to scroll it. Arrow keys, Page Up/Down and
Home/End all do nothing until I press Tab once, or reach for the mouse.
As a keyboard user this is the first thing I hit every time: open a file, start
reading, press Down, nothing happens.
Steps
- Quit Mud.
- In Finder, select a Markdown file long enough to scroll and press Cmd+↓
(or Enter in Nimble Commander). - The window opens and is frontmost. Press ↓ without clicking anything.
Expected: the document scrolls.
Actual: nothing moves.
Press Tab once and ↓ works from then on.
What I checked
Tested against 4.2.0 (21) on macOS 26.6.2, on a fresh window with no click and
no Tab. I compared screenshots of the document body before and after each key,
with a control pair first to confirm the capture was stable:
| Key | Result |
|---|---|
| ↓ | no effect |
| Page Down | no effect |
| End | no effect |
| Space | works — toggles Mark Up / Mark Down |
| Tab, then ↓ | scrolls |
Space working while the scroll keys don't is the part I found interesting.
Space is handled in Swift, so the keyboard is reaching the app fine; the keys
WebKit would handle itself are the ones going nowhere. AXFocusedUIElement on
the process comes back as missing value.
Clicking in the document didn't restore arrow scrolling for me either, though
the mouse wheel is fine, so I've been scrolling with the trackpad without
really noticing what was going on.
Guess at the cause
Offered in case it saves you a few minutes — you'll know straight away if it's
wrong.
DocumentContentView puts the focus on the SwiftUI container
(.focusable() / .focused($contentFocused), set true in .onAppear), and I
couldn't find a makeFirstResponder anywhere, so I don't think the WKWebView
itself ever becomes first responder. That would fit: .onKeyPress handlers
like Space still fire, but the keys WebKit handles natively never reach it.
Tab presumably walks the key view loop onto the web view, which is why it
helps.
If that's right, it's awkward rather than trivial, because Space is doing
double duty — it's the mode toggle via onKeyPress, but it's also WebKit's
page-down. Just handing first responder to the web view would fix scrolling and
break the mode toggle.
There's also this in DocumentContentView, which pulls focus back whenever
it's lost:
.onChange(of: contentFocused) { _, focused in
if !focused && !findState.isVisible && !state.isComposingComment {
contentFocused = true
}
}
which might be why clicking doesn't stick.
Happy to test a build if that's useful.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the Finder or Nimble Commander launch steps with a long Markdown document, then inspect DocumentContentView and its .focusable(), .focused($contentFocused), .onAppear, and focus-change handling. Check how the WKWebView receives focus and how Space is handled in Swift. Done means arrow keys, Page Up/Down, and Home/End scroll immediately after launch while the Space mode toggle still works.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- macos, swift
- Domain
- desktop
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100