feat(terminal): configurable normal and bold font weight (#403)

Bold text on the theme's default foreground carries exactly ONE cue, the
weight step. Claude Code marks its markdown bold with a bare ESC[1m and
changes no colour, and xterm substitutes a bright colour for bold only
when the foreground is a palette index 0-7, so the substitution never
fires for default-foreground text. A family shipping only a regular and
a bold face keeps that step small (measured on Consolas: glyph ink rises
from 14.25% to 16.57%), and picking a different family does not help,
because 400 stays 400 whatever the family. Lowering the NORMAL weight is
the only way to widen the gap.

Two per-device settings beside "Terminal font" in the Font group, each
defaulting to xterm's own value for its slot, so an untouched install
renders exactly as it did before. Both thread into the main terminal and
the Agent Teams panes, and apply on save without a reload.

The bundled face had to be unclamped in the same change or the settings
would look broken on a stock install. fonts/jetbrains-mono-variable.woff2
carries a wght axis of 100 to 800, but styles.css declared the face
`400 700`, and the descriptor is what the browser synthesizes from: at
that range 100, 200 and 300 rendered identically to 400 and 800
identically to 700 (measured in headless Chromium, both directions).
The two families ahead of it in the default stack, Fira Code and Cascadia
Code, exist only if the user installed them, so for most installs
"normal = 300" would have been a no-op. Declared `100 800`, every step is
distinct: 61%, 77% and 90% of the ink at 400, and 800 adds ~14% over 700.
Nothing in the stylesheets asks for a monospace weight outside 400-700,
so widening it changes nothing that rendered before.

Details that are easy to get wrong and are pinned by tests:

- Each slot falls back to its OWN xterm default, so an unset bold weight
  can never inherit `normal` and become a visible change.
- A live save refreshes both echo overlays. They cache
  terminal.options.fontWeight and paint it into their spans, so without
  it the characters being typed keep the old weight while the rest of the
  screen changes. Most visible on a phone, where local echo is on by
  default.
- A live save reaches open Agent Teams panes, which read their options at
  construction, exactly as applyTerminalSkin() propagates its own.
- A stored weight the picker does not list (a hand-set 350) is added to
  the select rather than dropped, so merely opening App Settings cannot
  reset it.
- _awaitTerminalFont() is untouched. CharSizeService measures through the
  CSS `font` shorthand, which resets the weight, so the measured face is
  always the 400 one and a weighted descriptor would request nothing new.

Verified end to end in a headless browser against a live server: the save
reaches the running terminal with no reload, the settings PUT stays 200
(both keys are display keys and are stripped before it, since
SettingsUpdateSchema is strict), the value survives a reload, and the
painted terminal really changes weight with the bundled font (lit-pixel
ink 0.83 / 0.95 / 1.00 / 1.13 / 1.21 at 100 / 300 / default / 700 / 800).

Proposed and analysed by @irisitymichaelgrundberg in discussion #403.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Codeman maintainer
2026-09-14 14:09:13 +02:00
parent d2ff1814ed
commit edeaa15986
10 changed files with 491 additions and 4 deletions
+50
View File
@@ -709,6 +709,54 @@ function resolveTerminalFontFamily(custom) {
return `${families.join(', ')}, ${TERMINAL_FONT_DEFAULT_STACK}`;
}
/**
* xterm's own defaults for the two weight slots, one per slot.
*
* They are deliberately kept apart rather than collapsed into a single
* fallback: handing the bold slot `normal` (or the normal slot `bold`) would
* turn an unset setting into a visible change, which is exactly the thing this
* feature exists to make controllable.
*/
const TERMINAL_FONT_WEIGHT_DEFAULTS = { fontWeight: 'normal', fontWeightBold: 'bold' };
/**
* Resolve ONE weight slot against xterm's validation rules.
*
* xterm accepts a number in 1..1000, or one of its own keyword/numeric-string
* options, and silently falls back to the slot default for anything else
* (`OptionsService._sanitizeAndValidateOption`). Resolving here instead means a
* stored value the picker does not list (a hand-set 350) still reaches the
* terminal, while junk in localStorage never does.
*/
function resolveTerminalFontWeightSlot(value, fallback) {
if (value === 'normal' || value === 'bold') return value;
const numeric = typeof value === 'number' ? value : typeof value === 'string' ? Number(value.trim()) : NaN;
if (!Number.isFinite(numeric) || numeric < 1 || numeric > 1000) return fallback;
return Math.round(numeric);
}
/**
* Resolve both xterm weight slots from the per-device settings blob.
*
* Bold text on the theme's default foreground carries exactly ONE cue, the
* weight step: Claude Code marks its markdown bold with a bare `ESC[1m` and no
* colour, and xterm's bold-to-bright substitution only fires for palette
* indices 0-7, so it never applies to default-foreground text. A family that
* ships only a regular and a bold face keeps that step small, and 400 stays
* 400 whatever family is chosen — lowering the NORMAL weight is the only way
* to widen the gap.
*/
function resolveTerminalFontWeights(settings) {
const s = settings && typeof settings === 'object' ? settings : {};
return {
fontWeight: resolveTerminalFontWeightSlot(s.terminalFontWeight, TERMINAL_FONT_WEIGHT_DEFAULTS.fontWeight),
fontWeightBold: resolveTerminalFontWeightSlot(
s.terminalFontWeightBold,
TERMINAL_FONT_WEIGHT_DEFAULTS.fontWeightBold
),
};
}
// ---------------------------------------------------------------------------
// Auto Copy (copy-on-select). Pure decision, so every guard below is testable
// without a terminal, a clipboard, or a browser.
@@ -809,6 +857,8 @@ if (typeof window !== 'undefined') {
window.CodemanTerminalFont = {
DEFAULT_STACK: TERMINAL_FONT_DEFAULT_STACK,
resolve: resolveTerminalFontFamily,
WEIGHT_DEFAULTS: TERMINAL_FONT_WEIGHT_DEFAULTS,
resolveWeights: resolveTerminalFontWeights,
};
}