diff --git a/README.md b/README.md
index c7527928..6bcfbaab 100644
--- a/README.md
+++ b/README.md
@@ -483,8 +483,8 @@ Single-digit selection (1-9), color-coded status, token counts, auto-refresh. De
|----------|--------|
| `Ctrl/Cmd+W` | Kill active session |
| `Ctrl/Cmd+Tab` | Next session |
-| `Option+[` / `Option+]` | Previous / next session |
-| `Option+1`-`Option+9` | Switch to tab N (physical keys, so macOS Option layouts work) |
+| `Alt/Option+[` / `Alt/Option+]` | Previous / next session |
+| `Alt/Option+1`-`Alt/Option+9` | Switch to tab N (physical keys, so macOS Option layouts work) |
| `Ctrl+Shift+{` / `Ctrl+Shift+}` | Move active tab left / right |
| `Ctrl/Cmd+L` | Clear terminal |
| `Ctrl+Shift+R` | Restore terminal size |
diff --git a/src/web/public/index.html b/src/web/public/index.html
index 38194fb8..09588109 100644
--- a/src/web/public/index.html
+++ b/src/web/public/index.html
@@ -505,8 +505,8 @@
Ctrl+W
Close Session
Ctrl+Tab
Next Session
-
Option+[ / Option+]
Previous / Next Session
-
Option+1-9
Switch to Tab N
+
Alt/Option+[ / Alt/Option+]
Previous / Next Session
+
Alt/Option+1-9
Switch to Tab N
Ctrl+L
Clear Terminal
Ctrl++
Increase Font
Ctrl+-
Decrease Font
diff --git a/src/web/public/terminal-ui.js b/src/web/public/terminal-ui.js
index c6edc476..c39f91a2 100644
--- a/src/web/public/terminal-ui.js
+++ b/src/web/public/terminal-ui.js
@@ -114,8 +114,14 @@ Object.assign(CodemanApp.prototype, {
this.terminal.attachCustomKeyEventHandler((ev) => {
if (ev.isComposing || ev.keyCode === 229) return false;
- // Let Alt+digit pass through to browser (tab switching)
- if (ev.altKey && ev.key >= '0' && ev.key <= '9') return false;
+ // Let the app's Alt/Option session-nav shortcuts reach the document keydown handler
+ // (app.js switches tabs by PHYSICAL e.code) instead of xterm injecting ESC
into
+ // the PTY. Mirror app.js's gate exactly โ same physical codes + modifier guard โ so
+ // macOS Option layouts (Option+1 -> "ยก", Option+[ -> "โ") are suppressed here too and
+ // don't leak an escape sequence into the focused terminal on every tab switch.
+ if (ev.altKey && !ev.ctrlKey && !ev.shiftKey && /^(Digit[1-9]|BracketLeft|BracketRight)$/.test(ev.code || '')) {
+ return false;
+ }
// Ctrl+V / Cmd+V: intercept before xterm sends ^V to PTY.
// Route through our paste trap which handles both images and text.
diff --git a/test/keyboard-shortcuts.test.ts b/test/keyboard-shortcuts.test.ts
index b02f43d6..7b93e541 100644
--- a/test/keyboard-shortcuts.test.ts
+++ b/test/keyboard-shortcuts.test.ts
@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
import { describe, expect, it } from 'vitest';
const appSource = readFileSync('src/web/public/app.js', 'utf8');
+const terminalUiSource = readFileSync('src/web/public/terminal-ui.js', 'utf8');
const helpHtml = readFileSync('src/web/public/index.html', 'utf8');
const readme = readFileSync('README.md', 'utf8');
@@ -19,11 +20,18 @@ describe('keyboard shortcuts', () => {
expect(appSource).toContain('this.nextSession()');
});
- it('documents mac-friendly Option shortcuts in help and README', () => {
- expect(helpHtml).toContain('Option+[');
- expect(helpHtml).toContain('Option+]');
- expect(helpHtml).toContain('Option+1-9');
- expect(readme).toContain('`Option+[` / `Option+]`');
- expect(readme).toContain('`Option+1`-`Option+9`');
+ it('suppresses xterm PTY injection for the same physical Alt nav codes (no ESC leak)', () => {
+ // terminal-ui.js must gate its xterm pass-through on the SAME physical e.code set the
+ // app.js handler consumes; otherwise Alt+[ / Alt+] (and Option+digit on remapped macOS
+ // layouts) switch tabs AND inject ESC into the focused terminal. Keep in sync.
+ expect(terminalUiSource).toContain('/^(Digit[1-9]|BracketLeft|BracketRight)$/.test(ev.code');
+ });
+
+ it('documents the Alt/Option shortcuts in help and README', () => {
+ expect(helpHtml).toContain('Alt/Option+[');
+ expect(helpHtml).toContain('Alt/Option+]');
+ expect(helpHtml).toContain('Alt/Option+1-9');
+ expect(readme).toContain('`Alt/Option+[` / `Alt/Option+]`');
+ expect(readme).toContain('`Alt/Option+1`-`Alt/Option+9`');
});
});