ompchamber 3.2.0 → 3.3.1

package/src/shared/lib/code/editor/typography.test.ts

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor typography contract.
+ *
+ * These are the properties that make one set of constants serve two layouts at
+ * any zoom level. Each one has a silent failure mode:
+ *
+ * - A px line-height does not scale with the font size, so zooming the editor
+ *   leaves the rows at the size they were chosen for at 12px — cramped at 24,
+ *   loose at 8. A ratio cannot.
+ * - The stack must name the bundled face first: `Fira Code` is the only entry
+ *   the app ships, so anything ahead of it would either be a font nobody has or
+ *   silently change the ligatures the whole console is typeset in.
+ * - The bounds must bracket the default, or the editor opens at a size its own
+ *   zoom controls cannot return to (the first click jumps).
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  EDITOR_DEFAULT_FONT_FAMILY,
+  EDITOR_DEFAULT_FONT_SIZE,
+  EDITOR_FONT_CHOICES,
+  EDITOR_FONT_FAMILY,
+  EDITOR_LINE_HEIGHT,
+  EDITOR_MAX_FONT_SIZE,
+  EDITOR_MIN_FONT_SIZE,
+  editorFontStack,
+} from '@/shared/lib/code/editor/typography';
+
+describe('editor typography', () => {
+  test('the line box is a ratio, so it scales with the font size', () => {
+    expect(typeof EDITOR_LINE_HEIGHT).toBe('number');
+    expect(EDITOR_LINE_HEIGHT).toBeGreaterThan(1);
+    expect(EDITOR_LINE_HEIGHT).toBeLessThan(3);
+  });
+
+  test('the stack leads with the bundled face and ends in a generic', () => {
+    expect(EDITOR_FONT_FAMILY.startsWith('"Fira Code"')).toBe(true);
+    expect(EDITOR_FONT_FAMILY.trimEnd().endsWith('monospace')).toBe(true);
+  });
+
+  test('the zoom bounds bracket the size the editor opens at', () => {
+    expect(EDITOR_MIN_FONT_SIZE).toBeLessThan(EDITOR_DEFAULT_FONT_SIZE);
+    expect(EDITOR_MAX_FONT_SIZE).toBeGreaterThan(EDITOR_DEFAULT_FONT_SIZE);
+  });
+});
+
+describe('editorFontStack', () => {
+  test('the default and an empty choice both yield the shared stack', () => {
+    expect(editorFontStack(EDITOR_DEFAULT_FONT_FAMILY)).toBe(EDITOR_FONT_FAMILY);
+    expect(editorFontStack('')).toBe(EDITOR_FONT_FAMILY);
+    expect(editorFontStack(undefined)).toBe(EDITOR_FONT_FAMILY);
+    expect(editorFontStack('   ')).toBe(EDITOR_FONT_FAMILY);
+  });
+
+  test('a chosen face is preferred, with the bundled stack still behind it', () => {
+    const stack = editorFontStack('JetBrains Mono');
+    expect(stack.startsWith('"JetBrains Mono"')).toBe(true);
+    // The fallback is what keeps an uninstalled choice from breaking the editor.
+    expect(stack).toContain(EDITOR_FONT_FAMILY);
+    expect(stack.trimEnd().endsWith('monospace')).toBe(true);
+  });
+
+  test('a multi-word choice is quoted, so it stays one family name', () => {
+    expect(editorFontStack('Courier New').startsWith('"Courier New"')).toBe(true);
+  });
+
+  test('the default choice is one the picker offers', () => {
+    expect(EDITOR_FONT_CHOICES.map((choice) => choice.id)).toContain(EDITOR_DEFAULT_FONT_FAMILY);
+  });
+
+  test('exactly one offered face is the bundled one, and it is the default', () => {
+    const bundled = EDITOR_FONT_CHOICES.filter((choice) => choice.bundled);
+    expect(bundled.map((choice) => choice.id)).toEqual([EDITOR_DEFAULT_FONT_FAMILY]);
+  });
+
+  test('every choice resolves to a stack that still ends in the bundled face', () => {
+    // The picker offers faces the app does not ship, so the guarantee that makes
+    // that safe is per-choice: a device without the chosen face must land on
+    // Fira Code rather than on a system serif or a blank cell.
+    for (const choice of EDITOR_FONT_CHOICES) {
+      const stack = editorFontStack(choice.id);
+      expect(stack.startsWith(`"${choice.id}"`)).toBe(true);
+      expect(stack).toContain(EDITOR_FONT_FAMILY);
+      expect(stack.trimEnd().endsWith('monospace')).toBe(true);
+    }
+  });
+});

package/src/shared/lib/code/editor/typography.ts

@@ -0,0 +1,86 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor's typography, in one place.
+ *
+ * The desktop editor and the phone's full-screen editor are the same surface on
+ * two layouts, so their text has to be the same text — the same face and the
+ * same line box. It was not: the stack was written out as a literal twice in
+ * the desktop editor and replaced by a bare `monospace` on the phone, which
+ * dropped Fira Code (and the ligatures the whole console is typeset in) and put
+ * the phone's line numbers in a different face from the code beside them — the
+ * gutter was already `font-mono`.
+ *
+ * `EDITOR_LINE_HEIGHT` is a ratio rather than a pixel value for the reason the
+ * desktop editor already used one: the zoom control changes the font size, and
+ * a fixed pixel line box keeps the rows at the size they were chosen for at
+ * 12px — cramped at 18px, loose at 10px. It has to be applied to the gutter as
+ * well as the editor, because with word wrap off the gutter rows carry no
+ * explicit height and take their spacing from their own line-height; a gutter
+ * pinned to a different value drifts out of register with the lines it counts.
+ *
+ * The two layouts keep their own padding and gutter width — a phone has less
+ * room, and the padding is chrome, not type. Everything that decides how a
+ * glyph is drawn lives here.
+ */
+
+/** Fira Code first (bundled — see `fira-code-fonts.css`), then faces a system may already have. */
+export const EDITOR_FONT_FAMILY = '"Fira Code", "JetBrains Mono", "SF Mono", Consolas, monospace';
+
+/**
+ * The faces the editor font picker offers, in the order it lists them.
+ *
+ * Each entry is a CSS family name. The editor puts the chosen one FIRST in its
+ * stack and keeps the rest of `EDITOR_FONT_FAMILY` behind it, so a face the
+ * device does not have falls through to the bundled Fira Code rather than
+ * rendering a blank or a system serif — which is what makes this setting safe
+ * to offer without shipping every font in the list. Only Fira Code is bundled;
+ * the others are names a system may or may not have, and the picker says so.
+ *
+ * `id` is the stored value and is deliberately the CSS name itself: a mapping
+ * table would add a second thing to keep in sync, and the name is already the
+ * only thing the renderer needs.
+ */
+export const EDITOR_FONT_CHOICES = [
+  { id: 'Fira Code', label: 'Fira Code', bundled: true },
+  { id: 'JetBrains Mono', label: 'JetBrains Mono', bundled: false },
+  { id: 'SF Mono', label: 'SF Mono', bundled: false },
+  { id: 'Menlo', label: 'Menlo', bundled: false },
+  { id: 'Consolas', label: 'Consolas', bundled: false },
+  { id: 'Monaco', label: 'Monaco', bundled: false },
+  { id: 'Courier New', label: 'Courier New', bundled: false },
+] as const;
+
+/** The stored setting's default; also the first entry the picker lists. */
+export const EDITOR_DEFAULT_FONT_FAMILY = 'Fira Code';
+
+/**
+ * The editor's font stack with `family` preferred.
+ *
+ * The chosen face is quoted (the list carries multi-word names) and placed
+ * ahead of the shared stack, so an unknown or uninstalled name degrades to the
+ * bundled Fira Code instead of replacing it. An empty or absent choice yields
+ * the shared stack unchanged, which is what a settings row that predates this
+ * option holds.
+ */
+export function editorFontStack(family?: string | null): string {
+  const chosen = (family ?? '').trim();
+  if (!chosen || chosen === EDITOR_DEFAULT_FONT_FAMILY) return EDITOR_FONT_FAMILY;
+  return `"${chosen}", ${EDITOR_FONT_FAMILY}`;
+}
+
+/** Line box as a multiple of the font size; apply to the editor AND its gutter. */
+export const EDITOR_LINE_HEIGHT = 1.5;
+
+/** Font size in px both editors open at. */
+export const EDITOR_DEFAULT_FONT_SIZE = 12;
+
+/**
+ * Zoom bounds, in px. Shared so the two layouts offer the same range — a phone
+ * clamped to a narrower one is a different editor, not a smaller one.
+ */
+export const EDITOR_MIN_FONT_SIZE = 8;
+export const EDITOR_MAX_FONT_SIZE = 24;

package/src/shared/lib/fonts/NOTICE.md

@@ -0,0 +1,44 @@
+# Bundled font: Symbols Nerd Font Mono
+
+`symbols-nerd-font-mono.woff2` is a subset of **SymbolsNerdFontMono-Regular.ttf**
+from [Nerd Fonts](https://github.com/ryanoasis/nerd-fonts) **v3.5.1**, built by
+`scripts/nerd-symbols-font.mjs`. It is the fallback face for the terminal's
+private-use glyphs (powerline separators, devicons, Font Awesome, Material
+Design icons); see `nerd-symbols.css` for why it is needed and how it is scoped.
+
+Subset coverage — the private-use areas plus the handful of Nerd-specific
+codepoints outside them:
+
+    U+E000-F8FF      BMP private use
+    U+F0000-FFFFD    Supplementary private use area-A (Material Design Icons)
+    U+23FB-23FE, U+2630, U+2665, U+26A1, U+276C-2771, U+2B58
+
+## Licences
+
+The font is a patched build combining several upstream icon sets. Each is
+redistributed here under its own licence, unchanged in substance (the subset
+keeps the glyph outlines verbatim; only `layout-features` and hinting are
+dropped, which are not licence terms).
+
+| Icon set                 | Upstream                                              | Licence     |
+|--------------------------|-------------------------------------------------------|-------------|
+| Codicons                 | https://github.com/microsoft/vscode-codicons          | CC BY 4.0   |
+| Devicons                 | https://github.com/devicons/devicon                   | MIT         |
+| extraglyphs              | https://github.com/source-foundry/Hack                | MIT         |
+| Font Awesome             | https://github.com/FortAwesome/Font-Awesome           | CC BY 4.0   |
+| Font Awesome Extension   | https://github.com/AndreLZGava/font-awesome-extension | MIT         |
+| Font Logos               | https://github.com/lukas-w/font-logos                 | unlicensed  |
+| Material Design Icons    | https://github.com/Templarian/MaterialDesign-Font     | Apache 2.0  |
+| Octicons                 | https://github.com/primer/octicons                    | MIT         |
+| Seti and original        | https://github.com/jesseweed/seti-ui                  | MIT         |
+| Pomicons                 | https://github.com/gabrielelana/pomicons              | OFL 1.1 RFN |
+| Powerline Extra Symbols  | https://github.com/ryanoasis/powerline-extra-symbols  | MIT         |
+| Powerline Symbols        | https://github.com/powerline/powerline                | MIT         |
+
+The Nerd Fonts project itself (the patching, the font metadata and the
+non-icon glyphs) is MIT, Copyright (c) 2014 Ryan L McIntyre. Its licence text
+accompanies the upstream release at
+https://github.com/ryanoasis/nerd-fonts/blob/master/LICENSE.
+
+"Font Logos" is marked unlicensed upstream; it ships inside the Nerd Fonts
+release that this subset is taken from, and is redistributed on that basis.

package/src/shared/lib/fonts/nerd-symbols.css

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * The bundled Nerd Font symbols face.
+ *
+ * A shell prompt is drawn with private-use symbols — powerline separators,
+ * devicons, Font Awesome, Material Design icons — that no coding webfont
+ * contains. `@fontsource/fira-code`'s latin subset maps 226 codepoints and not
+ * one of them is above U+FFFF, so the terminal's stack can only reach them
+ * through a Nerd Font. Until now the stack named installed families only
+ * (`XTERM_GLYPH_FALLBACKS`), which means the glyphs appeared on the machine
+ * that had one installed and were hollow tofu boxes on every other device — a
+ * phone, a second laptop, a colleague's browser.
+ *
+ * This face closes that gap without taking the choice away: it is declared LAST
+ * in the stack, after every installed Nerd Font family, so a machine that
+ * already has one renders from it and never fetches these bytes.
+ *
+ * `unicode-range` is what makes "never fetches" true rather than aspirational.
+ * A face whose range no laid-out glyph falls in is never downloaded, so a page
+ * that renders only Latin text (or a desktop where an installed family wins)
+ * issues no request at all. Verified: a latin-only document with this
+ * stylesheet loaded fetched only `fira-code-latin-400-normal.woff2` and left
+ * this face `unloaded`; a document laying out U+E0B0 with an installed family
+ * ahead of it fetched nothing.
+ *
+ * `font-display: block` rather than `swap`, unlike the text faces beside it: a
+ * swapped symbol paints a tofu box first and repaints, and in a terminal that
+ * box is exactly the artifact this face exists to remove. `mount.ts` awaits the
+ * face before opening xterm for the same reason — see `ensureNerdGlyphs`.
+ *
+ * Generated by `bun run scripts/nerd-symbols-font.mjs` from
+ * `SymbolsNerdFontMono-Regular.ttf` (Nerd Fonts v3.5.1). See NOTICE.md in this
+ * directory for the icon-set licences.
+ */
+
+@font-face {
+  font-family: 'OMPChamber Nerd Symbols';
+  font-style: normal;
+  font-weight: 400;
+  font-display: block;
+  unicode-range:
+    U+E000-F8FF,
+    U+F0000-FFFFD,
+    U+23FB-23FE,
+    U+2630,
+    U+2665,
+    U+26A1,
+    U+276C-2771,
+    U+2B58;
+  src: url('./symbols-nerd-font-mono.woff2') format('woff2');
+}

package/src/shared/lib/fonts/nerd-symbols.test.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The terminal's Nerd Font coverage is one contract split across three files,
+ * and every way it can break is silent at runtime:
+ *
+ * - The bundled face's family name is written twice — in the stack
+ *   (`XTERM_FONT_FAMILY`) and in the `@font-face` (`nerd-symbols.css`). If they
+ *   drift, the face loads and nothing uses it: prompts render as tofu boxes
+ *   with no error anywhere.
+ * - The face must stay LAST in the stack. Moved ahead of the installed families
+ *   it would win on every machine, which both changes the glyph shapes a user
+ *   with a Nerd Font already sees AND makes every desktop download 1.1 MB it
+ *   never needed. That is a bandwidth regression with no visible symptom on the
+ *   developer's own laptop.
+ * - The font file and its `unicode-range` must agree. A range that names
+ *   codepoints the subset dropped leaves those glyphs as tofu even though the
+ *   face is loaded and "working".
+ *
+ * These assertions are cheap and each one pins a failure this change was made
+ * to prevent, so they are permanent rather than throwaway.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  NERD_SYMBOLS_FAMILY,
+  XTERM_FONT_FAMILY,
+  XTERM_GLYPH_FALLBACKS,
+} from '@/client/data/theme/terminal';
+
+const FONT_DIR = import.meta.dir;
+const CSS = readFileSync(join(FONT_DIR, 'nerd-symbols.css'), 'utf8');
+const WOFF2 = join(FONT_DIR, 'symbols-nerd-font-mono.woff2');
+
+/** Parse `unicode-range: a, b, c;` into codepoint intervals. */
+function declaredRanges(css: string): Array<[number, number]> {
+  const block = css.match(/unicode-range:\s*([^;]+);/);
+  if (!block) throw new Error('nerd-symbols.css declares no unicode-range');
+  return block[1]
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const [start, end] = entry.split('-');
+      const lo = Number.parseInt(start.replace(/^U\+/i, ''), 16);
+      const hi = end ? Number.parseInt(end.replace(/^U\+/i, ''), 16) : lo;
+      return [lo, hi] as [number, number];
+    });
+}
+
+describe('bundled Nerd Font symbols face', () => {
+  test('the stylesheet declares the family the terminal stack names', () => {
+    const declared = CSS.match(/font-family:\s*'([^']+)'/)?.[1];
+    expect(declared).toBe(NERD_SYMBOLS_FAMILY);
+  });
+
+  test('the face is LAST in the stack, after every installed family', () => {
+    // A local Nerd Font must win, so the bundled face is only reached on a
+    // machine that has none — which is also what keeps the desktop from
+    // downloading it (its unicode-range is PUA-only, so it is never fetched
+    // when another family supplies the glyph).
+    expect(XTERM_FONT_FAMILY.indexOf(NERD_SYMBOLS_FAMILY)).toBeGreaterThan(
+      XTERM_FONT_FAMILY.indexOf('PowerlineSymbols'),
+    );
+    // Only the generic fallbacks may follow it.
+    const after = XTERM_FONT_FAMILY.slice(XTERM_FONT_FAMILY.indexOf(NERD_SYMBOLS_FAMILY));
+    expect(after).not.toMatch(/Nerd Font Mono'/);
+  });
+
+  test('every installed family is still offered before the bundled one', () => {
+    for (const family of ['FiraCode Nerd Font Mono', 'JetBrainsMono Nerd Font', 'Symbols Nerd Font Mono']) {
+      expect(XTERM_GLYPH_FALLBACKS).toContain(family);
+      expect(XTERM_FONT_FAMILY.indexOf(family)).toBeLessThan(
+        XTERM_FONT_FAMILY.indexOf(NERD_SYMBOLS_FAMILY),
+      );
+    }
+  });
+
+  test('the subset actually covers the ranges the stylesheet claims', () => {
+    // Reading the cmap needs fonttools, which is not a project dependency. The
+    // absence is a legitimate skip; a *failure* of the probe is not, so the two
+    // are told apart rather than both being swallowed as "no fonttools".
+    const available = Bun.spawnSync([
+      'python3',
+      '-c',
+      'import fontTools, brotli',
+    ]);
+    if (available.exitCode !== 0) {
+      console.warn('skipping font coverage check: python3 fonttools/brotli unavailable');
+      return;
+    }
+
+    const probe = Bun.spawnSync([
+      'python3',
+      '-c',
+      `
+import json
+from fontTools.ttLib import TTFont
+
+cmap = set(TTFont(${JSON.stringify(WOFF2)}).getBestCmap())
+ranges = ${JSON.stringify(declaredRanges(CSS))}
+uncovered = [r for r in ranges if not any(cp in cmap for cp in range(r[0], r[1] + 1))]
+# The prompt glyphs this face exists for.
+required = [0xE0B0, 0xE0B4, 0xE0B6, 0xE606, 0xE7A8, 0xE718, 0xF015, 0xF03E, 0xF121B, 0xF0001]
+print(json.dumps({ "codepoints": len(cmap), "uncovered": uncovered, "missing": [c for c in required if c not in cmap] }))
+`,
+    ]);
+
+    // fonttools is known to be importable here, so a non-zero exit is a real
+    // failure (a corrupt subset, a bad path) and must not read as a skip.
+    expect(probe.stderr.toString()).toBe('');
+
+    const result = JSON.parse(probe.stdout.toString()) as {
+      codepoints: number;
+      uncovered: Array<[number, number]>;
+      missing: number[];
+    };
+    expect(result.uncovered).toEqual([]);
+    expect(result.missing).toEqual([]);
+    expect(result.codepoints).toBeGreaterThan(10_000);
+  });
+
+  test('the face file is present and non-trivial', async () => {
+    const file = Bun.file(WOFF2);
+    expect(await file.exists()).toBe(true);
+    expect(file.size).toBeGreaterThan(100_000);
+  });
+});

package/src/shared/lib/settings/diff.test.ts

@@ -4,7 +4,7 @@ import { diffSettings } from '@/shared/lib/settings/diff';
 
 describe('diffSettings', () => {
   test('an object patch persists only the keys it actually changed', () => {
-    const prev = { theme: 'paper', soundAlerts: true, binaryPath: '/bin/omp' };
+    const prev = { theme: 'paper', soundAlerts: true, editorFont: 'Fira Code' };
     const next = { ...prev, theme: 'nord-dark' };
     expect(diffSettings(prev, next, { theme: 'nord-dark' })).toEqual({ theme: 'nord-dark' });
   });

package/src/shared/lib/workspace/terminal/keys.test.ts

@@ -0,0 +1,189 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The bytes the terminal key bar sends.
+ *
+ * Every expectation here is copied from xterm's own `evaluateKeyboardEvent`
+ * (`@xterm/xterm/src/common/input/Keyboard.ts`), because the shell cannot tell a
+ * bar button from a physical key: a sequence that merely looks plausible works
+ * in bash and breaks in vim. Three of those rules are the ones this file exists
+ * to pin — a modifier is a CSI PARAMETER and not an ESC prefix, application
+ * cursor mode swaps in the SS3 spelling, and Ctrl on a literal key is a latch
+ * for typed text rather than a byte to fold.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  NO_MODIFIERS,
+  TERMINAL_KEYS,
+  TERMINAL_SYMBOLS,
+  applyModifiers,
+  ctrlCharacter,
+  resolveKeySequence,
+  type TerminalModifiers,
+} from '@/shared/lib/workspace/terminal/keys';
+
+const CTRL: TerminalModifiers = { ctrl: true, alt: false };
+const ALT: TerminalModifiers = { ctrl: false, alt: true };
+
+describe('resolveKeySequence — cursor keys', () => {
+  test('unmodified arrows use CSI', () => {
+    expect(resolveKeySequence('up')).toBe('\x1b[A');
+    expect(resolveKeySequence('down')).toBe('\x1b[B');
+    expect(resolveKeySequence('right')).toBe('\x1b[C');
+    expect(resolveKeySequence('left')).toBe('\x1b[D');
+  });
+
+  test('application cursor mode swaps in the SS3 spelling', () => {
+    const options = { applicationCursorKeys: true };
+    expect(resolveKeySequence('up', options)).toBe('\x1bOA');
+    expect(resolveKeySequence('left', options)).toBe('\x1bOD');
+  });
+
+  test('Home and End always use the terminfo spelling, DECCKM or not', () => {
+    // `TERM=xterm-256color` declares khome/kend as SS3, so the CSI form is a
+    // sequence the shell does not bind: zsh rings the bell and ignores it.
+    expect(resolveKeySequence('home')).toBe('\x1bOH');
+    expect(resolveKeySequence('end')).toBe('\x1bOF');
+    expect(resolveKeySequence('home', { applicationCursorKeys: true })).toBe('\x1bOH');
+    expect(resolveKeySequence('end', { applicationCursorKeys: true })).toBe('\x1bOF');
+  });
+
+  test('a modifier beats application cursor mode, as xterm does', () => {
+    const options = { applicationCursorKeys: true, modifiers: CTRL };
+    expect(resolveKeySequence('up', options)).toBe('\x1b[1;5A');
+  });
+
+  test('a modifier is a CSI parameter, never an ESC prefix', () => {
+    expect(resolveKeySequence('up', { modifiers: CTRL })).toBe('\x1b[1;5A');
+    expect(resolveKeySequence('up', { modifiers: ALT })).toBe('\x1b[1;3A');
+    expect(resolveKeySequence('up', { modifiers: { ctrl: true, alt: true } })).toBe('\x1b[1;7A');
+  });
+});
+
+describe('resolveKeySequence — keys with a fixed spelling', () => {
+  test('an unmodified page/delete key drops its leading 1', () => {
+    expect(resolveKeySequence('delete')).toBe('\x1b[3~');
+    expect(resolveKeySequence('pageUp')).toBe('\x1b[5~');
+    expect(resolveKeySequence('pageDown')).toBe('\x1b[6~');
+  });
+
+  test('page keys carry their prefix once modified', () => {
+    expect(resolveKeySequence('pageUp', { modifiers: CTRL })).toBe('\x1b[5;5~');
+    expect(resolveKeySequence('delete', { modifiers: ALT })).toBe('\x1b[3;3~');
+  });
+
+  test('a page key has no SS3 form, so DECCKM does not touch it', () => {
+    expect(resolveKeySequence('pageUp', { applicationCursorKeys: true })).toBe('\x1b[5~');
+  });
+
+  test('escape, tab and shift-tab are literal', () => {
+    expect(resolveKeySequence('escape')).toBe('\x1b');
+    expect(resolveKeySequence('tab')).toBe('\t');
+    expect(resolveKeySequence('shiftTab')).toBe('\x1b[Z');
+  });
+});
+
+describe('resolveKeySequence — modifiers on a literal key', () => {
+  test('Ctrl does NOT fold a literal key into a control byte', () => {
+    // The `^C` button is the only Ctrl+C. A tapped `|` stays a pipe: folding it
+    // would send FS (0x1c), which is not a pipe and not a signal.
+    expect(resolveKeySequence('pipe', { modifiers: CTRL })).toBe('|');
+    expect(resolveKeySequence('underscore', { modifiers: CTRL })).toBe('_');
+  });
+
+  test('Alt on a literal key is the ESC prefix', () => {
+    expect(resolveKeySequence('pipe', { modifiers: ALT })).toBe('\x1b|');
+    expect(resolveKeySequence('escape', { modifiers: ALT })).toBe('\x1b\x1b');
+  });
+
+  test('the dedicated control keys are already the folded byte', () => {
+    expect(resolveKeySequence('interrupt')).toBe('\x03');
+    expect(resolveKeySequence('eof')).toBe('\x04');
+    expect(resolveKeySequence('clear')).toBe('\x0c');
+  });
+});
+
+describe('resolveKeySequence — defaults and coverage', () => {
+  test('no options means no modifier and no application mode', () => {
+    // `pageUp` is the plain CSI default; Home/End carry a terminfo spelling.
+    expect(resolveKeySequence('pageUp')).toBe('\x1b[5~');
+    expect(NO_MODIFIERS).toEqual({ ctrl: false, alt: false });
+  });
+
+  test('every control key resolves to bytes', () => {
+    for (const def of TERMINAL_KEYS) {
+      expect(resolveKeySequence(def.id).length, def.id).toBeGreaterThan(0);
+    }
+  });
+
+  test('every symbol resolves to its own literal', () => {
+    for (const def of TERMINAL_SYMBOLS) {
+      expect(resolveKeySequence(def.id), def.id).toBe(def.sequence);
+    }
+  });
+
+  test('the symbol layer covers the characters a phone buries', () => {
+    const labels = new Set(TERMINAL_SYMBOLS.map((def) => def.label));
+    for (const required of ['|', '~', '\\', '$', '*', '?', '&', '<', '>', '`', '{', '}', '[', ']', '"', "'"]) {
+      expect(labels.has(required), required).toBe(true);
+    }
+  });
+
+  test('a symbol under a latched Alt is an ESC prefix, like any literal', () => {
+    expect(resolveKeySequence('dollar', { modifiers: ALT })).toBe('\x1b$');
+  });
+
+  test('an unknown id sends nothing rather than a guess', () => {
+    expect(resolveKeySequence('nope' as never)).toBe('');
+  });
+});
+
+describe('ctrlCharacter', () => {
+  test('letters fold case-insensitively onto C0', () => {
+    expect(ctrlCharacter('c')).toBe('\x03');
+    expect(ctrlCharacter('C')).toBe('\x03');
+    expect(ctrlCharacter('a')).toBe('\x01');
+    expect(ctrlCharacter('z')).toBe('\x1a');
+  });
+
+  test('the symbol set matches the terminal, not the ASCII table', () => {
+    expect(ctrlCharacter('@')).toBe('\x00');
+    expect(ctrlCharacter(' ')).toBe('\x00');
+    expect(ctrlCharacter('[')).toBe('\x1b');
+    expect(ctrlCharacter('_')).toBe('\x1f');
+    expect(ctrlCharacter('?')).toBe('\x7f');
+    expect(ctrlCharacter('!')).toBeNull();
+    expect(ctrlCharacter('ab')).toBeNull();
+  });
+});
+
+describe('applyModifiers', () => {
+  test('a latched Ctrl folds a typed letter', () => {
+    expect(applyModifiers('c', CTRL)).toBe('\x03');
+    expect(applyModifiers('r', CTRL)).toBe('\x12');
+  });
+
+  test('a latched Alt prefixes ESC', () => {
+    expect(applyModifiers('b', ALT)).toBe('\x1bb');
+    expect(applyModifiers('f', { ctrl: true, alt: true })).toBe('\x1b\x06');
+  });
+
+  test('no modifier is the identity', () => {
+    expect(applyModifiers('c', NO_MODIFIERS)).toBe('c');
+  });
+
+  test('a paste is left intact — the latch does not corrupt it', () => {
+    const pasted = 'bun run build\n';
+    expect(applyModifiers(pasted, CTRL)).toBe(pasted);
+    expect(applyModifiers(pasted, ALT)).toBe(pasted);
+  });
+
+  test('a character with no control code passes through', () => {
+    expect(applyModifiers('!', CTRL)).toBe('!');
+  });
+});