joseph / joseph/mud

Arrow keys and Page Up/Down don't scroll until the window is tabbed into

Open
#23 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Quit Mud.
  2. In Finder, select a Markdown file long enough to scroll and press Cmd+↓
    (or Enter in Nimble Commander).
  3. 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.