Skip to content

Commit d448496

Browse files
jcxplorerclaude
andcommitted
fix(web): macOS Option types layout characters in the terminal
On macOS the terminal sent every Option+key as Alt, so layouts that put ASCII characters on the Option layer (German @ on Option+L, Finnish | on Option+7) could not type them. A lone Option that produces a character now types it through the textarea, like AltGr elsewhere, and Option dead keys compose there. A macOS-only "Option as Alt in terminal" setting (off, left, right, both), modelled on Ghostty's macos-option-as-alt, keeps Alt for users who rely on Option+B and similar shortcuts. Fixes #13046 Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 339179f commit d448496

7 files changed

Lines changed: 248 additions & 1 deletion

File tree

‎apps/web/src/components/ThreadTerminalDrawer.tsx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -485,6 +485,8 @@ export function TerminalViewport({
485485
}),
486486
);
487487
const terminalFontRef = useRef({ family: terminalFontFamily, size: terminalFontSize });
488+
const terminalOptionAsAlt = useClientSettings((settings) => settings.terminalOptionAsAlt);
489+
const readTerminalOptionAsAlt = useEffectEvent(() => terminalOptionAsAlt);
488490
const terminalSession = useAttachedTerminalSession({
489491
environmentId,
490492
terminal: {
@@ -606,6 +608,9 @@ export function TerminalViewport({
606608
onResize: (cols, rows) => void resizeTerminal(cols, rows),
607609
onSelectionChange: () => handleSelectionChange(),
608610
beforeKey: (event) => handleBeforeKey(event),
611+
get optionAsAlt() {
612+
return readTerminalOptionAsAlt();
613+
},
609614
onLinkActivate: (text, event) => handleLinkActivate(text, event),
610615
canActivateLink: (text) => canActivateTerminalLink(text),
611616
// The surface listens from construction, so a right-click can land

‎apps/web/src/components/settings/SettingsPanels.tsx‎

Lines changed: 96 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,14 @@ import { useScopedSettingsWriteAllowed } from "./useScopedSettings";
33
import { Spinner } from "~/components/ui/spinner";
44
import { NotificationSettings } from "./NotificationSettings";
55
import { PRIVACY_POLICY_URL } from "../../legalLinks";
6-
import { ArchiveIcon, ArchiveX, CheckIcon, ChevronRightIcon, SettingsIcon } from "lucide-react";
6+
import {
7+
ArchiveIcon,
8+
ArchiveX,
9+
CheckIcon,
10+
ChevronRightIcon,
11+
InfoIcon,
12+
SettingsIcon,
13+
} from "lucide-react";
714
import { Link, useNavigate } from "@tanstack/react-router";
815
import type { CSSProperties, ReactNode } from "react";
916
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
@@ -27,6 +34,7 @@ import {
2734
DEFAULT_UNIFIED_SETTINGS,
2835
type ChatWidth,
2936
type DiffLayout,
37+
TerminalOptionAsAlt,
3038
type EnvironmentIdentificationMode,
3139
MAX_APPEARANCE_CONTRAST,
3240
MAX_CODE_FONT_SIZE,
@@ -193,6 +201,7 @@ const SIDEBAR_PROJECT_SORT_ORDER_LABELS: Record<SidebarProjectSortOrder, string>
193201
manual: "Manual",
194202
};
195203
const isSidebarProjectSortOrder = Schema.is(SidebarProjectSortOrder);
204+
const isTerminalOptionAsAlt = Schema.is(TerminalOptionAsAlt);
196205

197206
const TIMESTAMP_FORMAT_LABELS = {
198207
locale: "System default",
@@ -211,6 +220,13 @@ const DIFF_LAYOUT_LABELS: Record<DiffLayout, string> = {
211220
split: "Split",
212221
};
213222

223+
const TERMINAL_OPTION_AS_ALT_LABELS: Record<TerminalOptionAsAlt, string> = {
224+
off: "Off",
225+
left: "Left Option",
226+
right: "Right Option",
227+
both: "Both",
228+
};
229+
214230
const QUIT_CONFIRMATION_MODE_LABELS: Record<QuitConfirmationMode, string> = {
215231
direct: "Direct",
216232
hold: "Hold",
@@ -608,6 +624,9 @@ export function useSettingsRestore(onRestored?: () => void) {
608624
? ["Diff whitespace changes"]
609625
: []),
610626
...(settings.diffLayout !== DEFAULT_UNIFIED_SETTINGS.diffLayout ? ["Diff layout"] : []),
627+
...(settings.terminalOptionAsAlt !== DEFAULT_UNIFIED_SETTINGS.terminalOptionAsAlt
628+
? ["Option as Alt in terminal"]
629+
: []),
611630
...(settings.proactivePanelsEnabled !== DEFAULT_UNIFIED_SETTINGS.proactivePanelsEnabled
612631
? ["Proactive panels"]
613632
: []),
@@ -694,6 +713,7 @@ export function useSettingsRestore(onRestored?: () => void) {
694713
settings.diffFilesCollapsed,
695714
settings.diffIgnoreWhitespace,
696715
settings.diffLayout,
716+
settings.terminalOptionAsAlt,
697717
settings.proactivePanelsEnabled,
698718
settings.environmentIdentificationMode,
699719
settings.contextWindowMeterEnabled,
@@ -805,6 +825,7 @@ export function useSettingsRestore(onRestored?: () => void) {
805825
diffFilesCollapsed: DEFAULT_UNIFIED_SETTINGS.diffFilesCollapsed,
806826
diffIgnoreWhitespace: DEFAULT_UNIFIED_SETTINGS.diffIgnoreWhitespace,
807827
diffLayout: DEFAULT_UNIFIED_SETTINGS.diffLayout,
828+
terminalOptionAsAlt: DEFAULT_UNIFIED_SETTINGS.terminalOptionAsAlt,
808829
proactivePanelsEnabled: DEFAULT_UNIFIED_SETTINGS.proactivePanelsEnabled,
809830
showSkillsInSlashMenu: DEFAULT_UNIFIED_SETTINGS.showSkillsInSlashMenu,
810831
composerCollapseOnScroll: DEFAULT_UNIFIED_SETTINGS.composerCollapseOnScroll,
@@ -1718,6 +1739,78 @@ function FontSmoothingRow() {
17181739
);
17191740
}
17201741

1742+
function TerminalOptionAsAltRow() {
1743+
const settings = useScopedSettings();
1744+
const updateSettings = useUpdateScopedSettings();
1745+
if (!isMacPlatform(navigator.platform)) return null;
1746+
const { id, title } = searchableSetting("terminal-option-as-alt");
1747+
return (
1748+
<SettingsRow
1749+
id={id}
1750+
title={
1751+
<span className="inline-flex items-center gap-1.5">
1752+
{title}
1753+
<Tooltip>
1754+
<TooltipTrigger
1755+
delay={200}
1756+
render={
1757+
<Button size="icon-micro" variant="ghost-muted" aria-label="Option as Alt details">
1758+
<InfoIcon className="size-3.5" />
1759+
</Button>
1760+
}
1761+
/>
1762+
<TooltipPopup side="top">
1763+
When off, Option types the character your keyboard layout puts on that key. For
1764+
example, Option+L types @ on a German keyboard, and Option+B types ∫ on a US keyboard.
1765+
</TooltipPopup>
1766+
</Tooltip>
1767+
</span>
1768+
}
1769+
description="Use Option for shell shortcuts like Option+B instead of typing characters."
1770+
resetAction={
1771+
settings.terminalOptionAsAlt !== DEFAULT_UNIFIED_SETTINGS.terminalOptionAsAlt ? (
1772+
<SettingResetButton
1773+
label="Option as Alt"
1774+
onClick={() =>
1775+
updateSettings({
1776+
terminalOptionAsAlt: DEFAULT_UNIFIED_SETTINGS.terminalOptionAsAlt,
1777+
})
1778+
}
1779+
/>
1780+
) : null
1781+
}
1782+
control={
1783+
<Select
1784+
value={settings.terminalOptionAsAlt}
1785+
onValueChange={(value) => {
1786+
if (isTerminalOptionAsAlt(value)) {
1787+
updateSettings({ terminalOptionAsAlt: value });
1788+
}
1789+
}}
1790+
>
1791+
<SelectTrigger size="sm" className="w-full sm:w-40" aria-label="Option as Alt">
1792+
<SelectValue>{TERMINAL_OPTION_AS_ALT_LABELS[settings.terminalOptionAsAlt]}</SelectValue>
1793+
</SelectTrigger>
1794+
<SelectPopup align="end" alignItemWithTrigger={false}>
1795+
<SelectItem hideIndicator value="off">
1796+
{TERMINAL_OPTION_AS_ALT_LABELS.off}
1797+
</SelectItem>
1798+
<SelectItem hideIndicator value="left">
1799+
{TERMINAL_OPTION_AS_ALT_LABELS.left}
1800+
</SelectItem>
1801+
<SelectItem hideIndicator value="right">
1802+
{TERMINAL_OPTION_AS_ALT_LABELS.right}
1803+
</SelectItem>
1804+
<SelectItem hideIndicator value="both">
1805+
{TERMINAL_OPTION_AS_ALT_LABELS.both}
1806+
</SelectItem>
1807+
</SelectPopup>
1808+
</Select>
1809+
}
1810+
/>
1811+
);
1812+
}
1813+
17211814
function WordWrapRow() {
17221815
const settings = useScopedSettings();
17231816
const updateSettings = useUpdateScopedSettings();
@@ -2913,6 +3006,8 @@ export function GeneralSettingsPanel() {
29133006
}
29143007
/>
29153008

3009+
<TerminalOptionAsAltRow />
3010+
29163011
<SettingsRow
29173012
serverScoped
29183013
settingKeys={["enableProviderUpdateChecks"]}

‎apps/web/src/components/settings/settingsSearch.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -465,6 +465,13 @@ export const SETTINGS_SEARCH_ITEMS = [
465465
to: "/settings/general",
466466
searchTerms: ["queue steer running turn send default behavior composer"],
467467
},
468+
{
469+
id: "terminal-option-as-alt",
470+
title: "Option as Alt in terminal",
471+
to: "/settings/general",
472+
searchTerms: ["alt key keyboard layout shell readline emacs macos international"],
473+
macOnly: true,
474+
},
468475
{
469476
id: "provider-update-checks",
470477
title: "Provider update checks",

‎apps/web/src/terminal/ghostty/surface.test.ts‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
clearPrimedTerminalCopyInput,
1010
ghosttyMouseButton,
1111
isTerminalAltGraphText,
12+
isTerminalOptionComposedText,
1213
isTerminalCompositionCommitInput,
1314
isTerminalCompositionKey,
1415
isTerminalCopyShortcut,
@@ -964,6 +965,60 @@ describe("isTerminalAltGraphText", () => {
964965
});
965966
});
966967

968+
describe("isTerminalOptionComposedText", () => {
969+
const option = (key: string, extra: { ctrlKey?: boolean; metaKey?: boolean } = {}) => ({
970+
key,
971+
altKey: true,
972+
ctrlKey: extra.ctrlKey ?? false,
973+
metaKey: extra.metaKey ?? false,
974+
});
975+
const noneHeld = { left: false, right: false };
976+
const leftHeld = { left: true, right: false };
977+
const rightHeld = { left: false, right: true };
978+
979+
it("types layout characters made with Option on macOS", () => {
980+
// German Option+L is @, and Option+Shift+7 is a backslash.
981+
expect(isTerminalOptionComposedText(option("@"), "off", leftHeld, "MacIntel")).toBe(true);
982+
expect(isTerminalOptionComposedText(option("\\"), "off", rightHeld, "MacIntel")).toBe(true);
983+
});
984+
985+
it("leaves other platforms, chords, and non-character keys to the encoder", () => {
986+
expect(isTerminalOptionComposedText(option("@"), "off", leftHeld, "Win32")).toBe(false);
987+
expect(
988+
isTerminalOptionComposedText(option("@", { ctrlKey: true }), "off", leftHeld, "MacIntel"),
989+
).toBe(false);
990+
expect(
991+
isTerminalOptionComposedText(option("@", { metaKey: true }), "off", leftHeld, "MacIntel"),
992+
).toBe(false);
993+
expect(isTerminalOptionComposedText(option("ArrowLeft"), "off", leftHeld, "MacIntel")).toBe(
994+
false,
995+
);
996+
// Option+Space is a non-breaking space, which breaks shell commands.
997+
expect(isTerminalOptionComposedText(option("\u00a0"), "off", leftHeld, "MacIntel")).toBe(false);
998+
expect(
999+
isTerminalOptionComposedText({ ...option("b"), altKey: false }, "off", noneHeld, "MacIntel"),
1000+
).toBe(false);
1001+
});
1002+
1003+
it("keeps Alt for the Option keys the setting names", () => {
1004+
expect(isTerminalOptionComposedText(option("∫"), "both", leftHeld, "MacIntel")).toBe(false);
1005+
expect(isTerminalOptionComposedText(option("∫"), "left", leftHeld, "MacIntel")).toBe(false);
1006+
expect(isTerminalOptionComposedText(option("@"), "left", rightHeld, "MacIntel")).toBe(true);
1007+
expect(isTerminalOptionComposedText(option("∫"), "right", rightHeld, "MacIntel")).toBe(false);
1008+
expect(isTerminalOptionComposedText(option("@"), "right", leftHeld, "MacIntel")).toBe(true);
1009+
});
1010+
1011+
it("lets Option dead keys compose in the textarea", () => {
1012+
// German Option+N starts `~`.
1013+
expect(isTerminalOptionComposedText(option("Dead"), "off", leftHeld, "MacIntel")).toBe(true);
1014+
expect(isTerminalOptionComposedText(option("Dead"), "both", leftHeld, "MacIntel")).toBe(false);
1015+
});
1016+
1017+
it("types the character when the held side was never seen", () => {
1018+
expect(isTerminalOptionComposedText(option("@"), "left", noneHeld, "MacIntel")).toBe(true);
1019+
});
1020+
});
1021+
9671022
describe("terminalGridCellAt", () => {
9681023
const options = {
9691024
bounds: { left: 100, top: 200 },

‎apps/web/src/terminal/ghostty/surface.ts‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { TerminalOptionAsAlt } from "@t3tools/contracts";
12
import { isMacPlatform } from "../../lib/utils";
23
import { SELECTION_MULTI_CLICK_INTERVAL_MS } from "../../lib/selectionActions";
34
import { collectWrappedTerminalLinkLine, extractTerminalLinks } from "../../terminal-links";
@@ -427,6 +428,44 @@ export function isTerminalAltGraphText(
427428
return event.getModifierState("AltGraph") && [...event.key].length === 1;
428429
}
429430

431+
/** Which Option keys are down, tracked from their own keydown and keyup. */
432+
export interface TerminalHeldOptionKeys {
433+
readonly left: boolean;
434+
readonly right: boolean;
435+
}
436+
437+
/**
438+
* A macOS Option press that should type the character the layout composed
439+
* (German Option+L is `@`) through the textarea, as Terminal.app does with
440+
* "Use Option as Meta key" off. Browsers report Option as Alt, never AltGraph,
441+
* so encoding it sends an Alt sequence and the character is lost. Option keys
442+
* set to act as Alt keep that encoding. An Option press that started before
443+
* the terminal had focus has no tracked side and types the character.
444+
* Dead keys (German Option+N for `~`) go to the textarea to compose. Option+Space
445+
* stays encoded, since a non-breaking space in a command line breaks it.
446+
* Option+arrow is not a single character, so word motion is unaffected.
447+
*/
448+
export function isTerminalOptionComposedText(
449+
event: Pick<KeyboardEvent, "altKey" | "ctrlKey" | "key" | "metaKey">,
450+
optionAsAlt: TerminalOptionAsAlt,
451+
heldOption: TerminalHeldOptionKeys,
452+
platform: string,
453+
): boolean {
454+
if (!isMacPlatform(platform) || !event.altKey || event.ctrlKey || event.metaKey) return false;
455+
if (event.key === "\u00a0") return false;
456+
if (event.key !== "Dead" && [...event.key].length !== 1) return false;
457+
switch (optionAsAlt) {
458+
case "off":
459+
return true;
460+
case "both":
461+
return false;
462+
case "left":
463+
return !heldOption.left;
464+
case "right":
465+
return !heldOption.right;
466+
}
467+
}
468+
430469
export function shouldReportTerminalMouse(
431470
tracking: boolean,
432471
event: Pick<MouseEvent, "ctrlKey" | "metaKey" | "shiftKey">,
@@ -547,6 +586,8 @@ export interface GhosttyTerminalSurfaceOptions {
547586
readonly onResize: (cols: number, rows: number) => void;
548587
readonly onSelectionChange: () => void;
549588
readonly beforeKey: (event: KeyboardEvent) => boolean;
589+
/** Read on every key press. Hosts can supply a getter for the latest value. */
590+
readonly optionAsAlt?: TerminalOptionAsAlt;
550591
readonly onLinkActivate: (text: string, event: MouseEvent) => void;
551592
readonly canActivateLink?: (text: string) => boolean;
552593
/**
@@ -622,6 +663,7 @@ export class GhosttyTerminalSurface {
622663
private selectionMoved = false;
623664
private composing = false;
624665
private focused = false;
666+
private heldOption: TerminalHeldOptionKeys = { left: false, right: false };
625667
private resizeNotified = false;
626668
private canvasConfigured = false;
627669
private theme: GhosttyTheme;
@@ -1114,6 +1156,7 @@ export class GhosttyTerminalSurface {
11141156
}
11151157

11161158
private readonly onKeyDown = (event: KeyboardEvent) => {
1159+
this.trackHeldOption(event, true);
11171160
// Presses handled outside the terminal must also swallow their release:
11181161
// beforeKey runs side effects (keybindings, navigation sends), so it cannot
11191162
// be consulted again on keyup, and Kitty report-event-types sessions would
@@ -1128,6 +1171,17 @@ export class GhosttyTerminalSurface {
11281171
this.suppressedKeyCodes.add(event.code);
11291172
return;
11301173
}
1174+
if (
1175+
isTerminalOptionComposedText(
1176+
event,
1177+
this.options.optionAsAlt ?? "off",
1178+
this.heldOption,
1179+
navigator.platform,
1180+
)
1181+
) {
1182+
this.suppressedKeyCodes.add(event.code);
1183+
return;
1184+
}
11311185
const mac = isMacPlatform(navigator.platform);
11321186
const primaryModifier = mac ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey;
11331187
const selectAllShortcut =
@@ -1259,6 +1313,7 @@ export class GhosttyTerminalSurface {
12591313
};
12601314

12611315
private readonly onKeyUp = (event: KeyboardEvent) => {
1316+
this.trackHeldOption(event, false);
12621317
if (this.suppressedKeyCodes.delete(event.code)) return;
12631318
if (isTerminalCompositionKey(event, this.composing)) {
12641319
return;
@@ -1272,6 +1327,19 @@ export class GhosttyTerminalSurface {
12721327
this.options.onData(data);
12731328
};
12741329

1330+
// Any event without Alt means no Option is down, which also clears a side
1331+
// whose release happened while focus was elsewhere.
1332+
private trackHeldOption(event: KeyboardEvent, down: boolean): void {
1333+
if (!event.altKey && event.code !== "AltLeft" && event.code !== "AltRight") {
1334+
if (this.heldOption.left || this.heldOption.right) {
1335+
this.heldOption = { left: false, right: false };
1336+
}
1337+
return;
1338+
}
1339+
if (event.code === "AltLeft") this.heldOption = { ...this.heldOption, left: down };
1340+
if (event.code === "AltRight") this.heldOption = { ...this.heldOption, right: down };
1341+
}
1342+
12751343
private readonly onFocus = () => {
12761344
this.focused = true;
12771345
this.cursorOn = true;
@@ -1280,6 +1348,7 @@ export class GhosttyTerminalSurface {
12801348

12811349
private readonly onBlur = () => {
12821350
this.focused = false;
1351+
this.heldOption = { left: false, right: false };
12831352
this.refreshHoveredLink();
12841353
// Suppressions survive blur deliberately: a shortcut that moves focus (for
12851354
// example terminal-toggle) must still swallow its own keyup if focus comes

‎docs/user/terminal.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,8 @@ To copy all retained output, choose Select all in the terminal's context menu,
1616
then copy. Cmd+A on macOS and Ctrl+Shift+A elsewhere select the same output.
1717
Ctrl+A still moves to the beginning of shell input on Windows and Linux.
1818
Jump to latest in the context menu returns to the current output.
19+
20+
On macOS, Option types the characters your keyboard layout puts on it, such as
21+
@ with Option+L on a German keyboard. To use Option as Alt for shell shortcuts
22+
like Option+B, choose which Option keys act as Alt in Settings > General >
23+
Option as Alt in terminal.

0 commit comments

Comments
 (0)