[hunterbecton]

Why

Copilot's last review of #1 flagged the j and k step keys. They listened on the whole document, so either letter changed the step from anywhere on the page except a text field. WCAG 2.1.4, Character Key Shortcuts, requires that the reader can turn off or remap a single-letter shortcut, or that the shortcut works only while its component has focus. This PR takes the focus option, because it needs no new setting or UI.

What changes

initStepKeys in src/client/step-keys.ts now listens on the guide's main element instead of document. A keydown fires on the focused element, so the listener receives j and k only while focus is inside the guide, such as on a step's header, a Reviewed checkbox, or a link in the explanation. The guards for text fields and modifier keys stay as they were.

The scope is main rather than the steps pane because the narrow layout moves each explanation into its step. With main, the keys behave the same in both layouts.

Behavior change

Right after a guide loads, focus is on the page itself, so j does nothing until the reader tabs into the guide or clicks a step. A reader who opened #step-2 and pressed j used to reach step 3. Now they click or tab into the guide first.

Tests

The key specs in tests/e2e/step-navigation.spec.ts now focus the guide before they press a key. New specs check that the keys do nothing with focus on the page or on the breadcrumb, and that they work from a link in the explanation pane. The spec for focus outside the guide fails against the old listener. pnpm check passes, and pnpm test passes all 73 specs.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

No active review issues were identified for the change restricting the guide’s keyboard shortcuts to focus within its main element.

No open issues 🎉

What changed in this PR

This PR scopes the guide’s j and k step shortcuts to focus inside its main element, addressing WCAG 2.1.4 without adding settings or changing behavior across layouts.

Changes:

• Moves the keyboard listener from document to the guide’s main, preserving existing input and modifier guards.
• Updates keyboard tests to focus the guide explicitly and adds coverage for focus outside the guide and within the explanation pane.

File	Description
tests/​e2e/​step-navigation.spec.ts	Updates focus setup and verifies shortcut scope and focus movement.
src/​client/​step-keys.ts	Restricts shortcuts to the guide and documents the focus requirement.

_{Review effort: Balanced}