feat: add customizable key bindings editor

[harumiWeb]

Summary

• add a context-aware keymap runtime plus config.toml [keymap] support
• add a Key Bindings Editor from the home settings overlay with immediate runtime/help refresh
• fix follow-up review issues around settings draft persistence, help escape safety, and assigning Esc from recording mode

Details

• introduce internal/keymap as the source of truth for contexts, actions, defaults, validation, and save canonicalization
• update app input handling, help, and inline key guides to resolve bindings dynamically per context
• add keymap editor UX improvements: terminal-height-aware scrolling, scrollbar, aligned columns, and mouse-wheel scrolling
• persist settings-overlay draft changes when saving from the keymap editor
• reject configs that unbind both help.back and help.quit
• switch recording cancel from Esc to Ctrl+G so Esc itself can be assigned
• document the feature in README and docs/specs/keymap-settings.md

Verification

• go test ./...

Closes #34

---

Summary by CodeRabbit

• New Features

  • Key Bindings Editor in home settings — record, edit, clear, reset, and save shortcuts; changes apply immediately at runtime and update help/key guides.
  • Per-context keymap overrides persisted to config with validation and conflict handling; Esc and cancel behaviors supported in record mode.

• Documentation

  • Expanded docs and localized strings describing the editor, keymap schema/example, behaviors, and theme/key GIFs.

[coderabbitai]

Warning

Rate limit exceeded

@harumiWeb has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 8 minutes and 53 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 8 minutes and 53 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3fd39506-eb53-4b06-9f6c-0f3b98ffc1df

📥 Commits

Reviewing files that changed from the base of the PR and between 09ccb44 and b800e38.

📒 Files selected for processing (3)

• internal/app/update.go
• internal/app/update_test.go
• tasks/lessons.md

📝 Walkthrough

Walkthrough

Adds a context/action keymap subsystem with persistent [keymap] config, a Key Bindings Editor reachable from Home settings, runtime application of saved keymap changes, validation rules (versioning, context/action checks, printable-key constraints for quiz.write, help escape constraints), and UI/help text rendering driven by the resolved keymap.

Changes

Cohort / File(s)	Summary
Keymap Module Core internal/keymap/keymap.go, internal/keymap/keymap_test.go	New package providing Context/Action enums, Config↔State resolution, normalization/validation (version, unknown context/action, same-context conflicts, quiz.write printable-key rule, help escape constraints), mutation APIs, conflict reporting, formatting helpers, and tests for resolution/mutation/round-trip.
Application Model & Update internal/app/model.go, internal/app/update.go, internal/app/cmds.go, internal/app/update_test.go	Introduced ScreenKeymap, keymap editor state/messages, saveKeymapCmd, applySettings, open/close editor helpers, centralized apply flow for settings/keymap saves, per-screen routing for ScreenKeymap, replacement of hardcoded key checks with m.keymap.Match(...), full editor state machine (recording/conflicts/scroll/save) and tests covering editor flows and save interactions.
View & Tests internal/app/view.go, internal/app/view_test.go	Added renderKeymapEditor and helpers (rows, viewport, scrollbar), dynamic inline key guides via renderInlineGuides/binding, help rendering updated to use keymap bindings, and tests for editor rendering/scrolling and help key rendering.
Configuration internal/config/config.go, internal/config/config_test.go	Added Settings.Keymap (toml:"keymap"), load/save canonicalization and omission of empty overrides, validation via keymap.Resolve, Settings.IsZero() helper, and tests for load/save/round-trip and omission when empty.
Localization assets/locale/en.toml, assets/locale/ja.toml, internal/i18n/keys.go, internal/i18n/i18n_test.go	New i18n keys for settings/keymap UI, recording/conflict/status messages, help screen entry; English/Japanese locale strings added and test coverage extended.
TUI Helpers internal/tui/align.go, internal/tui/align_test.go	Reworked label alignment: new AlignText using runewidth.StringWidth, AlignLabel delegates to it, and added test for Unicode-aware alignment.
Docs & README README.en.md, README.md, docs/specs/keymap-settings.md	Documented Key Bindings Editor behavior, config schema example ([keymap]), validation rules (including quiz.write restrictions and help escape constraints), editor UX details, and added illustrative media.
Tasks & Specs tasks/feature_spec.md, tasks/lessons.md, tasks/todo.md	Updated feature spec, implementation lessons (draft persistence, atomic replace rules, validation), and completed checklist for the keymap feature.
Other assets/locale/*, various tests and small scaffolding files	Numerous tests updated/added to assert new keymap behavior, i18n presence, and editor interactions; locale additions and small wiring changes across internal packages.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant HomeSettings as "Home Settings Overlay"
    participant Editor as "KeymapEditor (ScreenKeymap)"
    participant Config as "Config Storage (config.toml)"
    participant Resolver as "Keymap Resolver"
    participant App as "App State (m.keymap)"

    User->>HomeSettings: Select "Key Bindings"
    HomeSettings->>Editor: Open editor
    Editor->>User: Show contexts/actions/current & default keys

    User->>Editor: Record key(s)
    Editor->>Editor: Collect token(s)
    Editor->>Resolver: Validate token(s)
    alt Conflict or Validation Error
        Resolver-->>Editor: Conflict/Error
        Editor->>User: Show conflict dialog / prompt
    else Validation OK
        Resolver-->>Editor: OK
        Editor->>Editor: Update draft
    end

    User->>Editor: Save
    Editor->>Config: Persist keymap + settings draft
    Config->>Resolver: Resolve & canonicalize
    Resolver-->>Config: Normalized overrides
    Config->>App: Apply settings & resolved keymap
    App->>User: Render updated help/key guides (no restart)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat: add write answer mode #12 — Touches the same input/keybinding layers; earlier PR adds hard-coded write-mode bindings while this change replaces static checks with a configurable keymap system that supersedes or intersects with those edits.

Poem

🐰
Keys hop, rearranged with care,
A burrowed editor lives there.
Record, resolve, save with cheer,
Guides update — no restart near.
Config hums, and rabbits cheer!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add customizable key bindings editor' accurately summarizes the main change: adding a configurable key bindings feature with a dedicated editor interface.
Linked Issues check	✅ Passed	All primary objectives from issue #34 are met: config.toml [keymap] persistence, context-aware management, printable-key validation for quiz.write, TUI editor with recording/conflict/reset/save, key normalization via tea.KeyPressMsg, and immediate runtime reflection without restart.
Out of Scope Changes check	✅ Passed	All changes align with issue #34 objectives: keymap configuration system, editor UI, validation rules, help/guide updates, and test coverage. No unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/keybind-custom

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 441 complexity · 14 duplication

Metric	Results
Complexity	441
Duplication	14

View in Codacy

_{TIP This summary will be updated as you push new changes. Give us feedback}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 24 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.