fix(shortcuts): align custom bindings and mobile key defaults

[devswha]

Change

Keep app shortcuts as configurable Mod+Shift bindings and keep the mobile key bar a terminal input device, not an app-action toolbar.

• Resolve command-palette hints from the saved mapping; disabled shortcuts have no hint.
• Recognize non-Latin physical letter keys outside IME composition, sharing the terminal's physical-key convention and keeping Latin-layout letters intact.
• Mark a narrow set of known browser/OS reservations and explain the currently selected conflict without rejecting or silently changing saved bindings. The list is intentionally not exhaustive.
• Keep shortcut selects readable on narrow screens and explain global versus focus-local keys and device-local settings (English/Korean/Japanese/Chinese).
• Start fresh/restored mobile bars with Esc, Tab and Ctrl+C. Preserve explicit custom layouts, empty layouts and legacy extra-key ordering.
• Update the guide, design rules and existing CI browser regression. No HTTP/WS changes or new demo transport behavior.

This does not replace #480 (tab reordering) or #602 (split view). Their shortcut paths were reviewed separately; both currently conflict with main and lack the required CI runs. Review comments document the remaining checks/fixes rather than closing either PR as superseded.

Validation

On Linux, Bun 1.4.2 / Node 24.18.0:

• bun run check fast on the rebased branch: workflow syntax, generated types, typecheck, build and unit suite pass; 1853 pass, 6 skip, 0 fail.
• bun scripts/key-bar-customization-demo-regression.ts: PASS. Rebinding/Off/reset/persistence and palette hints, reservation warning without rewriting the setting, non-Latin shortcut with no terminal input, IME guard, Ctrl+C visibility at 320/390px, legacy/custom layouts and held modifiers.
• bun scripts/settings-pages-demo-regression.ts: PASS. All settings pages at 320/390px, Back/Forward/Escape and responsive history behavior.
• bun run check run bun scripts/terminal-input-regression.ts: PASS on an isolated herdr, including input readiness, drafts, IME and shortcut interception.
• UI evidence below uses fictional demo fixtures only. Non-Latin browser events are synthetic; physical phones, macOS and real non-Latin hardware layouts were not tested. Production build retains the existing large-chunk warning.

Shortcut settings	Default terminal keys

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: devswha/herdr-web-ui/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 1159ee29-d7b7-4bee-bfb4-325aa8502d04

📥 Commits

Reviewing files that changed from the base of the PR and between 4ece1be and 9e24327.

⛔ Files ignored due to path filters (2)

• docs/screenshots/shortcuts/key-bar-phone.png is excluded by !**/*.png, !docs/screenshots/**
• docs/screenshots/shortcuts/settings-phone.png is excluded by !**/*.png, !docs/screenshots/**

📒 Files selected for processing (4)

• CHANGELOG.md
• docs/guide.md
• src/lib/shortcuts.test.ts
• src/lib/shortcuts.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• CHANGELOG.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• New Features
  • Shortcut settings show platform-aware bindings and flag keys that may be intercepted by the browser or operating system.
  • Command palette hints reflect customized shortcuts and are hidden when a shortcut is disabled.
• Bug Fixes
  • App shortcuts now recognize physical letter keys on non-Latin layouts, except during IME composition.
  • The default mobile terminal key bar places Escape, Tab, and Ctrl+C before modifiers and arrow keys; saved custom layouts retain their order.
• Documentation
  • Updated shortcut guidance to clarify browser-local settings and distinguish app shortcuts from terminal and interface controls.

Walkthrough

This PR changes the default mobile key-bar order and settings fallback. It updates shortcut matching for non-Latin keyboard layouts, makes palette hints reflect shortcut overrides, and adds reservation indicators and warnings in shortcut settings.

Changes

Mobile Key Bar

Layer / File(s)	Summary
Default order and settings fallback src/lib/keyBar.ts, src/lib/settings.ts, src/lib/keyBar.test.ts, src/lib/settings.test.ts	The default key bar now places Escape, Tab, and Ctrl+C before modifiers and navigation keys. Missing key-bar data uses the new default, while legacy extras are still migrated.
Key-bar display checks and guidance scripts/key-bar-customization-demo-regression.ts, DESIGN.md, docs/guide.md, docs/terminal-input.md, CHANGELOG.md	Regression checks verify the restored order and Ctrl+C visibility at narrow widths. Documentation describes the revised default and states that saved custom layouts retain their order.

App Shortcuts

Layer / File(s)	Summary
Shortcut matching and display-key resolution src/lib/shortcuts.ts, src/lib/shortcuts.test.ts, scripts/key-bar-customization-demo-regression.ts, CHANGELOG.md	Letter shortcuts can match physical key positions for non-Latin layouts. Display-key resolution accounts for overrides and disabled shortcuts. Tests cover matching, display keys, and IME guards.
Settings warnings and command-palette hints src/lib/shortcutBindings.ts, src/components/SettingsDialog.tsx, src/components/SettingsDialog.css, src/components/CommandPalette.tsx, src/lib/i18n.*.ts, scripts/key-bar-customization-demo-regression.ts, DESIGN.md, docs/guide.md, docs/terminal-input.md, src/AGENTS.md	Shortcut settings mark known reserved keys and warn when a selected key may be intercepted. Palette hints use current overrides and disappear for disabled shortcuts. Regression checks, translations, and documentation cover the updated behavior.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Suggested reviewers: nahwan-kim

Merge Risk: ⚪ Minimal · up to 9e243

No actionable issue remains identified; the change is ready for normal merge checks.

Architecture Summary

Architecture risk: 🔵 Low · up to 9e243

The change affects 5 systems.

Changed systems: src, docs, CHANGELOG.md, DESIGN.md, scripts

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — src (service) was modified; 14 changed files map to changed impact.
• observed — docs (service) was modified; 2 changed files map to changed impact.
• observed — CHANGELOG.md (service) was modified; 1 changed file maps to changed impact.
• observed — DESIGN.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in DESIGN.md: The palette’s .kbd hints now follow this browser’s shortcut settings and are omitted for disabled bindings, replacing the global-shortcut-exists condition.
• observed — Modified behavior in DESIGN.md: The Shortcuts page is described as listing platform-resolved global bindings, replacing the description that it lists the complete platform-resolved list.
• observed — Modified behavior in DESIGN.md: The documented default mobile key bar order now puts ^C immediately after Esc and Tab, before sticky Ctrl/Alt/Shift; previously ^C followed the modifiers, Enter, and arrows.
• observed — Modified behavior in DESIGN.md: The accessibility constraints replace the settings table as the discoverable source of shortcut mappings with rules for editable, browser-local bindings, duplicate blocking, and browser/OS reservation warnings. They also specify that text selection and IME composition retain their keys, local navigation and reordering must not intercept terminal input, handled global shortcuts must not reach the PTY, and touch actions stay in buttons and menus while the key bar remains for terminal input.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 13 files. (2 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main changes: custom shortcut bindings and mobile key-bar defaults.
Description check	✅ Passed	The description follows the required Change and Validation sections. It explains the behavior, lists validation results, identifies test limitations, and includes UI evidence.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 26.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 13 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[devswha]

Merge-lane review of this PR at 9e24327 (main 90b01f8 merged in).

Fixed here

• 9e24327: the physical-key fallback matched any Unicode letter, so an accented Latin letter fired the binding of the key position it sits on (BÉPO É on KeyW with a binding on W; Turkish F Ç on KeyB, the default sidebar key) and never reached the terminal. Only letters outside the Latin script use the position now; a test covers it and fails without the fix. Found by the Codex pass, confirmed with a probe against main (which returned no action).

Checked, no change needed

• Saved settings: records written by the v0.3.52, v0.4.0 and v0.4.1 code (untouched but saved, legacy extras emptied / customised / with an unknown id, key-bar items emptied / customised / with unknown ids, items missing with legacy extras, shortcut overrides rebound / off / with an unknown id) load with the same bar and bindings as before, and stay the same after a re-save.
• Hangul, Cyrillic and kana letters with Mod+Shift fire by key position; nothing fires during composition (isComposing, keyCode 229, Process); Ctrl+letter without Shift, Ctrl+Shift+Alt and unbound letters stay with the terminal. Palette hints match what fires for every binding in default, rebound and off states.
• scripts/key-bar-customization-demo-regression.ts and scripts/settings-pages-demo-regression.ts pass through bun run check run; the two guide screenshots are reproduced by the regression's own captures on the demo fixtures.

Notes (not changed)

• A record saved by v0.3.50 or earlier has no key-bar field at all, so it gets the new default order (Ctrl+C third). That bar could not be customised, so this follows the PR's rule, but it is a visible reorder for those installs. Codex rated it Medium; left as is.
• A user on v0.3.51 or later who never touched the bar but saved any other setting keeps the old order (Ctrl+C last), because the saved record already holds the old default. Only installs with no saved record see the new order.
• On Windows and Linux three default bindings (J, B, O) are on the reservation list, so Settings → Shortcuts shows three warnings before anything is changed. Chrome lets a page handle these three, and the comment at src/lib/shortcuts.ts:12 says O was chosen because it works in a tab.
• The first non-Latin test title still says "non-ASCII" although the rule is now "non-Latin".

[devswha]

Independent review of 9e24327 (lead session; lane rev-607 merged main 90b01f8 and wrote 9e24327 after a Codex gpt-6-astra adversarial pass).

Verdict: merge.

What I ran, in a scratch copy of 9e24327:

Check	Result
bun test on src/lib/shortcuts.test.ts, keyBar.test.ts, settings.test.ts, i18n.test.ts	81 pass, 0 fail
the same with src/lib/shortcuts.ts from b2910d0 (before the lane's fix)	1 fail: an accented Latin letter (BÉPO's É on KeyW, Turkish F's Ç on KeyB) fired the binding of the key position it sits on instead of reaching the terminal

Read:

• 9e24327 limits the physical-key fallback to letters outside the Latin script, so Hangul, Cyrillic and kana still fire Mod+Shift bindings by key position, and a Latin layout's own letters stay as typed.
• The lane loaded records written by the v0.3.52, v0.4.0 and v0.4.1 code in every stored shape (customised, emptied, legacy extras, unknown ids): the bar and the bindings come through unchanged. Only an install with no saved record, or one from v0.3.50 or earlier (where the bar could not be customised), gets the new Esc, Tab, Ctrl+C order.
• Nothing fires during IME composition, and Ctrl+letter without Shift stays with the pty.

Notes for later, not blockers: on Windows and Linux the default J, B and O bindings are on the reservation list, so Settings shows three warnings before anything is changed; and one test title still says "non-ASCII". I did not run the browser regressions myself: CI's "Integration and browser" is green on 9e24327. Both required checks and CodeRabbit are green, no threads are open, and the branch contains main.