Skip to content

fix(shortcuts): keep Open settings off Ctrl+, on Windows/Linux, show Alt+, (#9824) - #11738

Merged
bolichen97 merged 2 commits into
mainfrom
fix/open-settings-alt-comma-9824
Sep 18, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/open-settings-alt-comma-9824

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

On Windows and Linux, Ctrl+, is how a Chinese or Japanese IME types a comma.
Base 2960ec6a binds Open settings to that chord on every platform, on two
surfaces:

  • website/electron/app-menu.js registers accelerator: "CmdOrCtrl+,"
    unconditionally
  • website/src/lib/shortcutRegistry.ts resolves open-settings to
    { key: ',', mod: true } for all platforms

Off macOS a registered menu accelerator takes the keystroke before the IME sees
it, so a CJK user cannot type a comma at all. The chord also fires ahead of the
global shortcut enable/disable gate, so turning shortcuts off does not work
around it.

Why it matters

A Chinese or Japanese user of the desktop app loses a character in ordinary
prose, everywhere in the product, with no in-product workaround. That is not a
degraded shortcut. Users who do not type with an IME are unaffected, which is
why the defect is easy to review past.

What changed (motivation -> approach -> change)

Symptom: comma input is dead on Windows and Linux. Cause: a chord that is a
comma keystroke for an IME is registered as a global accelerator on those
platforms. Change: stop registering it, on both surfaces that could claim it.

shortcutRegistry.ts now resolves Alt+, off macOS and keeps Cmd+, on macOS,
where a comma is not a Ctrl chord. Alt+, was already an accepted alias, so it
is promoted from alias to primary rather than invented.

app-menu.js needed a second decision, because simply dropping the accelerator
left the fix undiscoverable: a user whose Ctrl+, stopped working would see a
menu item with no shortcut at all and had to find Alt+, in the shortcuts
modal. The item now carries accelerator: "Alt+," together with
registerAccelerator: false, which Electron documents as a Linux and Windows
option that displays a chord without registering it with the system. So the
caption appears on File > Settings... while the menu claims no key: Ctrl+,
stays free for the IME, and Alt+, continues to be handled in the renderer with
its focus and enable/disable gates intact. isMac is the single predicate shared
by both surfaces.

The alternative was accelerator: "Alt+," registered normally. Rejected: a
registered menu accelerator fires regardless of focus, which would take Alt+,
away from the in-page handler and bypass the gates that handler applies.
Displaying without registering keeps one owner for the chord.

Backwards compatibility

Breaking, deliberately: Ctrl+, stops opening Settings on Windows and
Linux. That removal is the fix.

Writer sweep on kirocrew/main @ 2960ec6a: two surfaces claim this chord and
both are handled - the Electron menu (app-menu.js, now an unregistered Alt+,
caption off macOS) and the in-page registry (shortcutRegistry.ts, now Alt+,
as the primary off macOS). Alt+, already resolved as an alias at this base, so
a user who was already pressing Alt+, is unaffected; a user who pressed
Ctrl+, is pointed at the new chord by the caption this PR adds. macOS is
untouched: Cmd+, stays the primary and Option+, stays an alias.

Tests

Measured against base 2960ec6a, where app-menu.test.js asserted
settings.accelerator === "CmdOrCtrl+," with no platform split at all.

  • website/electron/test/app-menu.test.js - 29 pass. The #9824 pin is now a
    pair of platform-split assertions. Off macOS the caption must carry no
    Ctrl-class modifier in any spelling, checked by rule rather than by listing
    spellings, and any caption present must have registerAccelerator === false.
    On macOS the caption must remain CmdOrCtrl+, with registerAccelerator
    unset, so the platform convention stays a real binding rather than a caption.
    Mutation-verified, each caught by exactly one assertion: dropping
    registerAccelerator: false; using Ctrl+,; and Control+,, a spelling no
    enumeration listed.
  • website/src/test/WindowsTitlebarMenu.test.tsx - 24 pass, including a new
    assertion that the Settings row renders Alt+, and never Ctrl+,. This is the
    caption a Windows user actually reads (see Screenshots below). Its fixture
    carried CmdOrCtrl+,, a value the main process can no longer send off macOS.
    Mutation-verified: restoring CmdOrCtrl+, fails that test alone.
  • website/src/test/shortcutRegistry.test.ts,
    website/src/test/settingsShortcut.test.tsx,
    website/src/test/useKeyboardShortcuts.test.tsx - 204 pass across the touched
    suites, covering that Ctrl+, matches nothing off macOS and Alt+, resolves
    to open-settings.
  • eslint and tsc -p tsconfig.app.json clean.

Comment sweep. At this base, shortcutRegistry.ts said "the desktop shell's menu
owns Ctrl+, there" and that was true: the menu registered it. Taking the
accelerator away is what falsifies the claim, so the claim is corrected in the
same change, along with four sibling copies that carried it - the
isSettingsChord docblock, the open-settings dispatch comment, the non-Mac
jsdom preamble in useKeyboardShortcuts.test.tsx, and the in-page regression
pin's comment. One of those was load-bearing: the dispatch comment justified its
position ahead of the Alt gate with "the primary chord carries no Alt", which
inverts once Alt+, is the primary, so a later reader could have moved the
branch under the gate and silently killed the chord. No behaviour changed there;
the branch already returns before the gate.

Manual verification

The menu template is built by a pure function and asserted directly, so the
accelerator string and the registerAccelerator flag are covered without
launching the app. What no automated coverage in this repository can reach is the
native menu frame - see below.

Screenshots / video

Both changed captions are shown below. Only the native Linux and macOS menu frame
is unrenderable here, and that gap is tracked separately.

Windows File > Settings..., the caption a Windows user reads. This is a DOM
surface, not a native frame: WindowsTitlebarMenu.tsx draws the submenu itself
rather than calling Menu.popup(), because a native popup captures window input
on Windows. The row reads Settings... with Alt+, right-aligned.

Windows titlebar File menu open, showing the Settings row with an Alt and comma accelerator caption

Produced by scripts/capture-settings-accelerator-caption.mjs, added in this
change. It does not hand-write the menu rows: it builds them with the real
buildMenuTemplate from electron/app-menu.js and refuses to take any picture
unless that template's Settings item is exactly Alt+, with
registerAccelerator: false. A screenshot of a string the harness chose would
prove nothing, so the harness is not allowed to choose one.

Shortcuts modal, Windows/Linux desktop host. Open settings reads Alt ,
and nothing else. Every other row still shows its Ctrl chord, which is what makes
this a platform-host difference rather than a global sweep: only Settings moved.

Shortcuts modal on the Windows/Linux desktop host: Open settings shows Alt and comma, with no Ctrl chord and no alias

Shortcuts modal, macOS host, for the contrast the split depends on. There
Open settings reads Cmd+, or Option+, - the platform convention stays
primary and the Option chord stays an accepted alias.

Shortcuts modal on the macOS host: Open settings shows Cmd comma or Option comma

The two modal shots come from the existing
scripts/capture-shortcuts-registry.mjs, run against a build of this branch.

The one remaining gap: the native menu on Linux and macOS. No harness here can
screenshot it. website/scripts/ holds roughly 200 capture-*.mjs scripts and
every one drives the web app in Chromium, so none launches Electron. Building one
needs Playwright's _electron driver plus Xvfb, which is new test infrastructure
rather than a screenshot - filed separately as #11737. The caption itself is
asserted for that path by app-menu.test.js, so what is missing is a rendering
confirmation of the frame, not coverage of the change.

Related Issues

Refs #9824
Supersedes #10796 - same change, raised from a branch in this repository.
Rendering-evidence harness for the native menu: #11737

Pattern harvest

Rule candidate: review-prompt

Pattern: a regression pin asserts a proxy property (a field is absent)
instead of the property it stands for (the field is never registered with the
OS). The proxy holds while nothing else is possible, then blocks a safe
improvement and has to be restated. Worth asking of any pin whose assertion is an
absence: is absence the invariant, or is it standing in for one?

Second, demonstrated on this PR rather than theorised: when a change falsifies a
claim that a sibling module owns, the claim has usually been copied. This one
had four copies beyond the original, and an earlier revision of this description
asserted the sweep was complete while three of them were still live. Grep the
claim, not the file.

Checklist

  • At most two commits, with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) - the comments on every touched
    surface now describe the built template; no user-facing doc names this chord
  • No secrets, credentials, or internal references in the diff

…Alt+, (#9824)

On Windows and Linux, Ctrl+, is how a Chinese or Japanese IME types a comma.
Binding Open settings to Ctrl+, there swallows the keystroke before the IME
sees it, so a CJK user cannot type a comma at all. The chord also fires ahead
of the global enable/disable gate, so turning shortcuts off could not even
work around it.

Two surfaces could claim the chord, so both are fixed. The in-page binding in
src/lib/shortcutRegistry.ts resolves to Alt+, off macOS. The Electron menu in
website/electron/app-menu.js no longer registers CmdOrCtrl+, on those
platforms: it carries accelerator "Alt+," together with registerAccelerator
false, which Electron documents as a Linux/Windows option that displays a
chord without registering it with the system. The caption therefore appears on
File > Settings while the menu claims no key, so Ctrl+, stays free for the IME
and Alt+, keeps being handled in the renderer with its focus and
enable/disable gates intact. macOS is untouched and keeps a real Cmd+,
binding, since a mac comma is not a Ctrl chord.

Displaying the chord matters on its own: without it a habituated user whose
Ctrl+, stopped working had no in-product pointer to Alt+,, and could only
rediscover it through the shortcuts modal.

The #9824 regression pin is rewritten rather than loosened. Asserting
accelerator === undefined off macOS was a proxy for "nothing is registered",
so it could not express that a caption claiming nothing is safe. It now
asserts the two properties directly: the caption carries no Ctrl-class
modifier in any spelling, checked by rule instead of by listing the two
spellings that happened to exist, and any caption present must have
registerAccelerator false. The macOS test additionally pins that
registerAccelerator stays unset there, so the platform convention remains a
real binding rather than a caption.

Two comments claimed the desktop shell owns or reserves Ctrl+, off macOS.
Nothing did, and the claim had already propagated from the module into a test
comment, so both now describe the unregistered caption the code actually
builds.

Refs #9824
@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 98815ec9f3e1366cbc7637b936d201f6a44a154a and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 98815ec

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 98815ec9f3e1366cbc7637b936d201f6a44a154a: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 98815ec9f3e1366cbc7637b936d201f6a44a154a — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 98815ec

Verdict parsed from the review's SHA-scoped output markers for commit 98815ec9f3e1366cbc7637b936d201f6a44a154a.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 98815ec9f3e1366cbc7637b936d201f6a44a154a: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 98815ec9f3e1366cbc7637b936d201f6a44a154a — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Confirm on a real Windows/Linux Electron build that the Alt+, caption is truly display-only — the native frame no harness here renders (the gap the author filed as #11737).

Not justified as shipped

  • Item 5 — rides along: declared; the display-only Alt+, caption is an addition beyond the strict fix, carried as the pointer for users who reached for Ctrl+,; no premise risk.
  • Item 6 — rides along: declared dev tooling ("scripts/capture-settings-accelerator-caption.mjs, added in this change"); 532 sibling capture-*.mjs scripts exist (globbed website/scripts/capture-*.mjs) and none touches the Windows titlebar menu (grepped win-titlebar|WindowsTitlebar|file-menu: 1 hit, this script); no user surface.

What this change ships

Inventory (7 items) — 5 justified

Intent: stop the Settings shortcut from eating the CJK-IME comma keystroke on Windows/Linux — a FIX (linked issue #9824; the new pins fail on base).

  1. Ctrl+, no longer opens Settings on Windows/Linux; the comma reaches the IME — justified
  2. The desktop File menu off macOS registers no Settings key with the system — justified
  3. Alt+, promoted from alias to primary Open-settings chord off macOS — justified
  4. Shortcuts modal off macOS shows only Alt+, for Open settings, no alias — justified
  5. File > Settings… off macOS displays an Alt+, caption without binding it — rides along (see above)
  6. New screenshot harness capture-settings-accelerator-caption.mjs — rides along (see above)
  7. The old Ctrl+, pins replaced by platform-split regression pins — justified

Pin-reversal evidence (lens 8): the deleted pin "accepts Ctrl+, (the VS Code convention…)" is quoted, declared "Breaking, deliberately", and grounded in #9824/#783 — framing matches the diff. Sibling sweep: Ctrl\+,|CmdOrCtrl\+, hits 9 files; 8 are in this diff, the ninth (windows-menu-model.test.js) is an arbitrary fixture string in a serializer pass-through test, not a claim on the chord. macOS untouched.

[FIRST-PRINCIPLES-REVIEWED] 98815ec

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 98815ec9f3e1366cbc7637b936d201f6a44a154a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify on a real Windows/Linux Electron build that registerAccelerator: false truly leaves Ctrl+, and Alt+, unclaimed — the native-frame gap deferred to #11737.

[DESIGN-REVIEWED] 98815ec

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of 98815ec9f3e1366cbc7637b936d201f6a44a154a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Verify the Alt+, caption renders on the native Linux menu frame — the one surface no supplied screenshot shows (tracked in #11737).

Suggestions

  • In the new capture-settings-accelerator-caption.mjs, spoof the navigator platform alongside window.kirocrew.platform: 'win32': shot-01 shows a "⌘K" search hint on the Windows frame, and the blind reader "can't tell which kind of computer this screen thinks I'm on".

[UX-REVIEWED] 98815ec

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 18, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 18, 2026
…u caption

Review found the sweep this change claimed to have completed was incomplete, in
exactly the way its own pattern harvest predicted: correcting a claim in one
place leaves the copies behind. Four comment sites still named Ctrl+, as the
Windows/Linux settings chord.

- useKeyboardShortcuts.ts, isSettingsChord docblock: said the chord is Ctrl+,
  off macOS and that "in the desktop shell the menu accelerator fires first
  there". Neither holds. The chord is Alt+,, and off macOS the menu registers
  nothing, so no accelerator fires ahead of this handler.
- useKeyboardShortcuts.ts, the open-settings dispatch: justified its position
  ahead of the Alt gate with "the primary chord carries no Alt". Off macOS the
  primary now DOES carry Alt, which makes that position load-bearing rather
  than incidental; the comment said the opposite, so a later reader could have
  moved the branch under the gate and silently killed Alt+,. No behaviour
  changed here - the branch already returns before the gate.
- useKeyboardShortcuts.test.tsx: listed "Ctrl+, settings" among the chords the
  non-Mac jsdom resolves.

Also pins the caption on the surface that actually renders it for Windows
users. WindowsTitlebarMenu draws the application menu itself rather than
calling Menu.popup(), because a native popup captures window input on Windows.
So the Settings row in that component IS the caption a Windows user reads, and
it is a DOM surface. Its fixture still carried CmdOrCtrl+, - a state the main
process can no longer send off macOS - and nothing asserted the rendered text.
The fixture now carries Alt+, and a new test asserts the row shows Alt+, and
never Ctrl+,. Mutation-verified: restoring CmdOrCtrl+, to the fixture fails
that test alone.

That also narrows the rendered-evidence gap. Only the native menu path
(Linux, macOS) is uncapturable; the Windows caption is asserted here.

Tests: WindowsTitlebarMenu, useKeyboardShortcuts, shortcutRegistry and
settingsShortcut suites, 204 pass. eslint and tsc clean.
@chenmingwei23
chenmingwei23 force-pushed the fix/open-settings-alt-comma-9824 branch from 5337675 to 98815ec Compare September 18, 2026 09:10
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 18, 2026
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 18, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the full production diff on 98815ec. Windows/Linux用Alt+,打开设置,释放输入法使用的Ctrl+,。

生产快捷键、Electron菜单及相关脚本相对共同基线在固定main上未改变。macOS保持Cmd+,;其他平台菜单只展示Alt+,而不注册系统加速键,由现有页面处理器执行。 写前逐文件对照证明本项生产文件及文档自阶段A没有变化。

Fresh REST checks: current-head PR Readiness success; no effective change request or unresolved review hold; CODEOWNERS/UX eligibility and the distinct last pusher verified. Optional baseline failures, if present, remain recorded and are not claimed green. This approval does not bypass branch protection.

@bolichen97
bolichen97 merged commit f752c3a into main Sep 18, 2026
81 of 87 checks passed
@bolichen97
bolichen97 deleted the fix/open-settings-alt-comma-9824 branch September 18, 2026 11:18
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 18, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…Alt+, (kirodotdev#9824) (kirodotdev#11738)

* fix(shortcuts): keep Open settings off Ctrl+, on Windows/Linux, show Alt+, (kirodotdev#9824)

On Windows and Linux, Ctrl+, is how a Chinese or Japanese IME types a comma.
Binding Open settings to Ctrl+, there swallows the keystroke before the IME
sees it, so a CJK user cannot type a comma at all. The chord also fires ahead
of the global enable/disable gate, so turning shortcuts off could not even
work around it.

Two surfaces could claim the chord, so both are fixed. The in-page binding in
src/lib/shortcutRegistry.ts resolves to Alt+, off macOS. The Electron menu in
website/electron/app-menu.js no longer registers CmdOrCtrl+, on those
platforms: it carries accelerator "Alt+," together with registerAccelerator
false, which Electron documents as a Linux/Windows option that displays a
chord without registering it with the system. The caption therefore appears on
File > Settings while the menu claims no key, so Ctrl+, stays free for the IME
and Alt+, keeps being handled in the renderer with its focus and
enable/disable gates intact. macOS is untouched and keeps a real Cmd+,
binding, since a mac comma is not a Ctrl chord.

Displaying the chord matters on its own: without it a habituated user whose
Ctrl+, stopped working had no in-product pointer to Alt+,, and could only
rediscover it through the shortcuts modal.

The kirodotdev#9824 regression pin is rewritten rather than loosened. Asserting
accelerator === undefined off macOS was a proxy for "nothing is registered",
so it could not express that a caption claiming nothing is safe. It now
asserts the two properties directly: the caption carries no Ctrl-class
modifier in any spelling, checked by rule instead of by listing the two
spellings that happened to exist, and any caption present must have
registerAccelerator false. The macOS test additionally pins that
registerAccelerator stays unset there, so the platform convention remains a
real binding rather than a caption.

Two comments claimed the desktop shell owns or reserves Ctrl+, off macOS.
Nothing did, and the claim had already propagated from the module into a test
comment, so both now describe the unregistered caption the code actually
builds.

Refs kirodotdev#9824

* fix(shortcuts): finish the stale Ctrl+, sweep and pin the Windows menu caption

Review found the sweep this change claimed to have completed was incomplete, in
exactly the way its own pattern harvest predicted: correcting a claim in one
place leaves the copies behind. Four comment sites still named Ctrl+, as the
Windows/Linux settings chord.

- useKeyboardShortcuts.ts, isSettingsChord docblock: said the chord is Ctrl+,
  off macOS and that "in the desktop shell the menu accelerator fires first
  there". Neither holds. The chord is Alt+,, and off macOS the menu registers
  nothing, so no accelerator fires ahead of this handler.
- useKeyboardShortcuts.ts, the open-settings dispatch: justified its position
  ahead of the Alt gate with "the primary chord carries no Alt". Off macOS the
  primary now DOES carry Alt, which makes that position load-bearing rather
  than incidental; the comment said the opposite, so a later reader could have
  moved the branch under the gate and silently killed Alt+,. No behaviour
  changed here - the branch already returns before the gate.
- useKeyboardShortcuts.test.tsx: listed "Ctrl+, settings" among the chords the
  non-Mac jsdom resolves.

Also pins the caption on the surface that actually renders it for Windows
users. WindowsTitlebarMenu draws the application menu itself rather than
calling Menu.popup(), because a native popup captures window input on Windows.
So the Settings row in that component IS the caption a Windows user reads, and
it is a DOM surface. Its fixture still carried CmdOrCtrl+, - a state the main
process can no longer send off macOS - and nothing asserted the rendered text.
The fixture now carries Alt+, and a new test asserts the row shows Alt+, and
never Ctrl+,. Mutation-verified: restoring CmdOrCtrl+, to the fixture fails
that test alone.

That also narrows the rendered-evidence gap. Only the native menu path
(Linux, macOS) is uncapturable; the Windows caption is asserted here.

Tests: WindowsTitlebarMenu, useKeyboardShortcuts, shortcutRegistry and
settingsShortcut suites, 204 pass. eslint and tsc clean.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants