dsh-code 1.0.2 → 1.0.4

package/src/input-split.ts

@@ -0,0 +1,191 @@
+/**
+ * Terminal input arrives as byte chunks, and one chunk can carry several
+ * keypresses: a fast space-then-enter, a bridged stdin that batches reads, a
+ * middle-click paste. Ink parses each chunk as exactly one keypress —
+ * `parseKeypress(' \r')` matches neither member, so both keys silently
+ * vanish (a multi-select question answered with an empty set). The splitter
+ * below cuts every chunk into the individual keypress units Ink's parser
+ * expects, keeping escape sequences and bracketed-paste blocks intact, and
+ * the stdin proxy feeds the split stream to the Ink mount.
+ *
+ * @module @deepseek-ai/dsh-tui/input-split
+ */
+
+import { PassThrough } from 'node:stream'
+import { PASTE_BRACKET_TIMEOUT_MS } from './keyboard.ts'
+
+/** Bracketed-paste wrapper bytes; the whole block travels as one unit. */
+const PASTE_START = '\x1b[200~'
+const PASTE_END = '\x1b[201~'
+
+/** One keypress cut from the input stream. */
+export interface KeypressSplitter {
+  /** Feed one chunk; returns every keypress unit this chunk completed. */
+  push(chunk: string): string[]
+  /** Whether an unterminated bracketed-paste block is currently held. */
+  openPaste(): boolean
+  /**
+   * Last-resort escape hatch for a paste whose end marker never arrived:
+   * drop the start marker and emit the held bytes as plain keypress units so
+   * nothing (Esc and Ctrl+C included) stays hostage. Inert when no paste is
+   * open.
+   */
+  releaseStalePaste(): string[]
+}
+
+/** Final byte of a CSI sequence (\x40-\x7e per ECMA-48). */
+const isCsiFinal = (char: string): boolean => char >= '@' && char <= '~'
+
+/**
+ * Build a stateful chunk splitter. A partial unit at the end of one chunk
+ * (a cut CSI sequence, an open paste block) waits in the buffer for the
+ * rest. A chunk-trailing lone ESC emits as the Escape key right away:
+ * terminals send Escape as its own chunk, and holding it hostage for a
+ * sequence that may never continue would break every Esc cancel.
+ */
+export function createKeypressSplitter(): KeypressSplitter {
+  let buffer = ''
+  const push = (chunk: string): string[] => {
+      buffer += chunk
+      const units: string[] = []
+      while (buffer !== '') {
+        // A bracketed paste block is display text, not keypresses: keep the
+        // whole wrapper plus its payload as the single unit the composer
+        // expects, even when the payload contains ESC-looking bytes.
+        if (buffer.startsWith(PASTE_START)) {
+          const end = buffer.indexOf(PASTE_END, PASTE_START.length)
+          if (end < 0) break
+          const stop = end + PASTE_END.length
+          units.push(buffer.slice(0, stop))
+          buffer = buffer.slice(stop)
+          continue
+        }
+        const head = buffer[0]!
+        if (head !== '\x1b') {
+          // Plain bytes key one at a time; a surrogate pair is one grapheme
+          // and must not split into two lone surrogates.
+          const pair = head >= '\uD800' && head <= '\uDBFF' && buffer[1] !== undefined
+          const take = pair ? 2 : 1
+          units.push(buffer.slice(0, take))
+          buffer = buffer.slice(take)
+          continue
+        }
+        // CSI (\x1b[…final) and SS3 (\x1bO<char): hold until complete.
+        if (buffer[1] === '[') {
+          let end = -1
+          for (let at = 2; at < buffer.length; at += 1) {
+            if (isCsiFinal(buffer[at]!)) {
+              end = at
+              break
+            }
+          }
+          if (end < 0) break
+          units.push(buffer.slice(0, end + 1))
+          buffer = buffer.slice(end + 1)
+          continue
+        }
+        if (buffer[1] === 'O') {
+          if (buffer[2] === undefined) break
+          units.push(buffer.slice(0, 3))
+          buffer = buffer.slice(3)
+          continue
+        }
+        if (buffer[1] === undefined) {
+          // Lone ESC: Escape key (see the tradeoff above).
+          units.push(buffer)
+          buffer = ''
+          continue
+        }
+        // Alt+key: ESC glued to one more byte travels as one unit.
+        units.push(buffer.slice(0, 2))
+        buffer = buffer.slice(2)
+      }
+      return units
+    }
+  return {
+    push,
+    openPaste(): boolean {
+      return buffer.startsWith(PASTE_START)
+    },
+    releaseStalePaste(): string[] {
+      if (!buffer.startsWith(PASTE_START)) return []
+      // Strip the unterminated start marker, then re-run the unit loop: the
+      // held bytes flow as ordinary keypresses under all the normal rules.
+      buffer = buffer.slice(PASTE_START.length)
+      return push('')
+    },
+  }
+}
+
+
+/** The stdin-shaped stream the Ink mount renders through. */
+export interface TuiStdin extends PassThrough {
+  /** Mirrors the real stdin so Ink's raw-mode gate passes. */
+  isTTY: boolean
+  /** Forwarded to the real stdin; Ink toggles it around focus. */
+  setRawMode(value: boolean): unknown
+  ref(): void
+  unref(): void
+}
+
+/**
+ * Wrap one real stdin in the splitting proxy: keypress units flow into a
+ * PassThrough Ink reads, while raw-mode/ref calls forward to the source.
+ * @param source - the process (or harness) input stream in raw mode.
+ * @returns the proxy stream plus a dispose that detaches the tap.
+ */
+export function createSplitStdin(source: NodeJS.ReadStream): { stdin: TuiStdin; dispose(): void } {
+  // Object mode matters: a plain stream's read() without a size drains the
+  // whole buffer as one chunk, which would re-coalesce the units this module
+  // exists to separate. In object mode every pushed unit reads back alone.
+  const stream = new PassThrough({ objectMode: true }) as TuiStdin
+  const splitter = createKeypressSplitter()
+  let stalePasteTimer: ReturnType<typeof setTimeout> | undefined
+  const disarmStalePasteTimer = (): void => {
+    if (stalePasteTimer === undefined) return
+    clearTimeout(stalePasteTimer)
+    stalePasteTimer = undefined
+  }
+  // A terminal that drops the end marker must not swallow every following
+  // keypress forever: past the shared paste window the held block is released
+  // as plain text, keeping Esc/Ctrl+C reachable. The App-level paste flag has
+  // its own reset net with the same window, but it can only see markers that
+  // reach Ink — this one guards the bytes that never do.
+  const armStalePasteTimer = (): void => {
+    if (stalePasteTimer !== undefined || !splitter.openPaste()) return
+    stalePasteTimer = setTimeout(() => {
+      stalePasteTimer = undefined
+      for (const unit of splitter.releaseStalePaste()) stream.write(unit)
+      armStalePasteTimer()
+    }, PASTE_BRACKET_TIMEOUT_MS)
+    stalePasteTimer.unref?.()
+  }
+  const onChunk = (chunk: string): void => {
+    for (const unit of splitter.push(String(chunk))) stream.write(unit)
+    if (splitter.openPaste()) armStalePasteTimer()
+    else disarmStalePasteTimer()
+  }
+  const proxy = Object.assign(stream, {
+    isTTY: source.isTTY === true,
+    setRawMode(value: boolean): TuiStdin {
+      source.setRawMode?.(value)
+      return stream
+    },
+    ref(): void {
+      source.ref?.()
+    },
+    unref(): void {
+      source.unref?.()
+    },
+  })
+  source.setEncoding('utf8')
+  source.on('data', onChunk)
+  return {
+    stdin: proxy,
+    dispose(): void {
+      disarmStalePasteTimer()
+      source.removeListener('data', onChunk)
+      source.pause()
+    },
+  }
+}

package/src/internals.ts

@@ -18,6 +18,7 @@ import {
   isVsCodeTerminalEnv,
   shouldEnableKeyboardEnhancement,
 } from './keyboard.ts'
+import { createSplitStdin } from './input-split.ts'
 
 /** A mounted terminal app instance; the runner owns unmount ordering. */
 export interface TuiMount {
@@ -52,19 +53,36 @@ export const internals: {
     // draft, quit). Ink's default `exitOnCtrlC: true` would intercept the
     // normalized control byte first, unmount only its renderer, and leave the
     // Harness runner plus the pushed keyboard protocol alive.
-    const instance = render(element, { exitOnCtrlC: false })
+    // stdin travels through the keypress splitter: Ink parses one chunk as
+    // one keypress, so a coalesced space-then-enter would drop both keys.
+    const tuiStdin = createSplitStdin(process.stdin)
+    // Ink only touches isTTY/setRawMode/ref/read on stdin; the object-mode
+    // proxy satisfies that contract without the full ReadStream surface.
+    const instance = render(element, {
+      exitOnCtrlC: false,
+      stdin: tuiStdin.stdin as unknown as NodeJS.ReadStream,
+      stdout: process.stdout,
+    })
     return {
       rerender(element: ReactElement): void {
         instance.rerender(element)
       },
       unmount(): void {
-        instance.unmount()
-        // Pop only a stack this mount pushed, then disable bracketed paste.
-        process.stdout.write(
-          (keyboardEnhanced ? KEYBOARD_ENHANCE_DISABLE : '')
-          + BRACKETED_PASTE_DISABLE
-          + (focusReporting ? TERMINAL_FOCUS_REPORT_DISABLE : ''),
-        )
+        // The cleanup below must run even when Ink's unmount throws (a
+        // render-teardown failure): a stdin tap or pushed terminal-protocol
+        // stack outliving the app wedges the terminal for whatever runs
+        // next, and a stray exception here must not skip the exit sequence.
+        try {
+          instance.unmount()
+        } finally {
+          tuiStdin.dispose()
+          // Pop only a stack this mount pushed, then disable bracketed paste.
+          process.stdout.write(
+            (keyboardEnhanced ? KEYBOARD_ENHANCE_DISABLE : '')
+            + BRACKETED_PASTE_DISABLE
+            + (focusReporting ? TERMINAL_FOCUS_REPORT_DISABLE : ''),
+          )
+        }
       },
     }
   },

package/src/kernel-panels.ts

@@ -47,9 +47,19 @@ function searchLine(searching: boolean | undefined, query: string): string {
 function ListFrame(props: ListFrameProps): ReactElement {
   const stdout = useStdout().stdout
   const viewport = panelViewport(stdout?.columns ?? 80, stdout?.rows ?? 30)
-  if (viewport.maxHeight === 0) return createElement(Box, { display: 'none' })
-  if (viewport.compact) {
-    return createElement(Text, { wrap: 'truncate-end' }, truncateColumns(singleLineText(`${props.title} · esc close`), viewport.contentColumns))
+  if (viewport.maxHeight === 0 || viewport.compact) {
+    // One visible row instead of a hidden panel: the current selection (or
+    // load state) is shown so Enter/arrows are never blind keys acting on
+    // invisible state. The selection leads and `esc close` follows it, so a
+    // narrow terminal truncates the panel title — never the actionable facts.
+    const body = props.loading
+      ? `${props.title} · loading…`
+      : props.error !== undefined
+        ? `${props.title} · load failed`
+        : props.rows.length === 0
+          ? `${props.title} · no matching entries`
+          : `❯ ${singleLineText(props.rows[props.cursor]?.text ?? '')}`
+    return createElement(Text, { wrap: 'truncate-end' }, truncateColumns(singleLineText(`${body} · esc close`), viewport.contentColumns))
   }
   const stateRows = props.loading
     ? [{ key: 'loading', text: '  loading…' }]
@@ -117,7 +127,10 @@ export function ModePanel({ current, load, select, close }: {
     if (input === 'r' && query === '') return refresh()
     if (key.upArrow) return setCursor(value => visible.length === 0 ? 0 : (value + visible.length - 1) % visible.length)
     if (key.downArrow) return setCursor(value => visible.length === 0 ? 0 : (value + 1) % visible.length)
-    if (key.return && visible[cursor]?.broken === undefined) return select(visible[cursor]!.id)
+    // Empty/loading/filtered-out lists have no row at the cursor: a bare
+    // `?.broken === undefined` check passes on undefined and crashes the
+    // process on the `!.id` access (PermissionPanel guards this correctly).
+    if (key.return && visible[cursor] !== undefined && visible[cursor]!.broken === undefined) return select(visible[cursor]!.id)
     const next = editQuery(query, input, key)
     if (next !== undefined) { setQuery(next); setCursor(0) }
   })
@@ -494,10 +507,10 @@ export function HistoryPanel({ entries, fill, close }: {
   })
   const stdout = useStdout().stdout
   const viewport = panelViewport(stdout?.columns ?? 80, stdout?.rows ?? 30)
-  if (viewport.compact) {
-    return createElement(Text, { wrap: 'truncate-end' }, truncateColumns('/history · esc close', viewport.contentColumns))
+  if (viewport.maxHeight === 0 || viewport.compact) {
+    const picked = matches[cursor]
+    return createElement(Text, { wrap: 'truncate-end' }, truncateColumns('/history · ' + (picked === undefined ? 'no matching prompts' : singleLineText(picked)) + ' · esc close', viewport.contentColumns))
   }
-  if (viewport.maxHeight === 0) return createElement(Box, { display: 'none' })
   const bodyRows = Math.max(1, viewport.bodyRows - 1)
   const offset = revealRow(0, cursor, matches.length, bodyRows)
   const visible = matches.slice(offset, offset + bodyRows)
@@ -586,10 +599,9 @@ export function StatuslinePanel({ enabled, change, close }: {
   })
   const stdout = useStdout().stdout
   const viewport = panelViewport(stdout?.columns ?? 80, stdout?.rows ?? 30)
-  if (viewport.compact) {
+  if (viewport.maxHeight === 0 || viewport.compact) {
     return createElement(Text, { wrap: 'truncate-end' }, truncateColumns('/statusline · esc close', viewport.contentColumns))
   }
-  if (viewport.maxHeight === 0) return createElement(Box, { display: 'none' })
   const bodyRows = Math.max(1, viewport.bodyRows - 1)
   const offset = revealRow(0, cursor, order.length, bodyRows)
   const visible = order.slice(offset, offset + bodyRows)
@@ -630,7 +642,7 @@ export function StatuslinePanel({ enabled, change, close }: {
  * instead of a bare failure notice. Enter applies one level; Esc returns to
  * the model list without applying.
  */
-export function EffortPanel({ row, current, select, back }: {
+export function EffortPanel({ row, current, select, back, onExit }: {
   /** The model row whose advertised levels this stage lists. */
   row: ModelRow
   /** Effective effort currently in force ('' when none), for the ● mark. */
@@ -639,6 +651,8 @@ export function EffortPanel({ row, current, select, back }: {
   select(effortId: string): void
   /** Return to the model list without applying. */
   back(): void
+  /** Leave the whole /model flow (Ctrl+C). */
+  onExit(): void
 }): ReactElement {
   const advertised = row.reasoning?.efforts ?? []
   const empty = row.reasoning === undefined || advertised.length === 0
@@ -666,6 +680,7 @@ export function EffortPanel({ row, current, select, back }: {
   }, [rows.length, cursor])
   useInput((input, key) => {
     if (key.escape || input === 'q') return back()
+    if (key.ctrl && input === 'c') return onExit()
     if (empty) return
     if (input === 'g') {
       setCursor(0)
@@ -894,6 +909,7 @@ export function SubagentPanel({ current, load, pick, inherit, close }: {
       current: current === '' ? undefined : current.split('@')[1],
       select: effortId => pick(effortFor, effortId),
       back: () => setEffortFor(undefined),
+      onExit: close,
     })
   }
   return createElement(ListFrame, {

package/src/keyboard.ts

@@ -1,25 +1,25 @@
-/**
- * Keyboard enhancement protocol (Codex `keyboard_modes` parity) and the
- * kitty CSI-u normalization layer.
- *
+/**
+ * Keyboard enhancement protocol (Codex `keyboard_modes` parity) and the
+ * kitty CSI-u normalization layer.
+ *
  * The TUI pushes the kitty keyboard protocol with DISAMBIGUATE_ESCAPE_CODES
  * and REPORT_ALTERNATE_KEYS (flags 1|4 = `\x1b[>5u`). Event types are
  * deliberately NOT requested: Ink 5's parser cannot decode the
  * `:event-type` suffix, and repeat/release reporting buys this surface
  * nothing.
- *
- * Ink 5 also cannot parse most CSI-u forms at all — they fall through its
- * regex as unnamed sequences and get INSERTED AS DRAFT TEXT. The composer's
- * stdin read patch therefore rewrites every CSI-u form it can decode back
- * to the legacy byte or canonical sequence the existing key handling
+ *
+ * Ink 5 also cannot parse most CSI-u forms at all — they fall through its
+ * regex as unnamed sequences and get INSERTED AS DRAFT TEXT. The composer's
+ * stdin read patch therefore rewrites every CSI-u form it can decode back
+ * to the legacy byte or canonical sequence the existing key handling
  * already understands, before Ink ever parses the chunk.
  * @module @deepseek-ai/dsh-code/keyboard
  */
 
 /** Push keyboard enhancement (modifyOtherKeys off, kitty flags 1|4). */
 export const KEYBOARD_ENHANCE_ENABLE = '\x1b[>4;0m\x1b[>5u'
-
-/** Pop the enhancement stack and reset modifyOtherKeys (exit path). */
+
+/** Pop the enhancement stack and reset modifyOtherKeys (exit path). */
 export const KEYBOARD_ENHANCE_DISABLE = '\x1b[<u\x1b[>4;0m'
 
 /** Explicit environment overrides for terminal keyboard enhancement. */
@@ -47,7 +47,7 @@ export function shouldEnableKeyboardEnhancement(env: NodeJS.ProcessEnv = process
   if (explicitEnable !== undefined) return explicitEnable
   return !isVsCodeTerminalEnv(env)
 }
-
+
 /** Enable bracketed paste reporting. */
 export const BRACKETED_PASTE_ENABLE = '\x1b[?2004h'
 
@@ -70,16 +70,25 @@ export function stripTerminalFocusEvents(chunk: string, onFocus: (focused: boole
     return ''
   })
 }
-
-/** Bracketed paste markers as Ink delivers them (it strips the leading ESC). */
-export const PASTE_START_MARKER = '[200~'
-export const PASTE_END_MARKER = '[201~'
-
-/**
- * Remove bracketed paste markers from one input chunk. Panel drafts accept raw
- * `input` text, where an unhandled paste would otherwise persist the literal
- * "[200~"/"[201~" markers Ink leaves after stripping the ESC byte.
- */
+
+/** Bracketed paste markers as Ink delivers them (it strips the leading ESC). */
+export const PASTE_START_MARKER = '[200~'
+export const PASTE_END_MARKER = '[201~'
+
+/**
+ * How long an unterminated bracketed-paste block may hold buffered bytes
+ * before the input splitter strips its start marker and releases them: a
+ * terminal that loses the end marker must never take the whole keyboard
+ * hostage (Esc/Ctrl+C included). Shared by the splitter and the composer's
+ * lost-paste safety net so both use one window.
+ */
+export const PASTE_BRACKET_TIMEOUT_MS = 1_000
+
+/**
+ * Remove bracketed paste markers from one input chunk. Panel drafts accept raw
+ * `input` text, where an unhandled paste would otherwise persist the literal
+ * "[200~"/"[201~" markers Ink leaves after stripping the ESC byte.
+ */
 export function stripPasteMarkers(text: string): string {
   return text
     .replaceAll(`\x1b${PASTE_START_MARKER}`, '')
@@ -87,22 +96,37 @@ export function stripPasteMarkers(text: string): string {
     .replaceAll(PASTE_START_MARKER, '')
     .replaceAll(PASTE_END_MARKER, '')
 }
-
-/** One decoded CSI-u keypress: key code, 1-based modifier param, alternate code. */
-interface CsiUKey {
-  code: number
-  modifiers: number
-  alternate?: number
-}
-
-/** Match one CSI-u sequence (code, optional ;modifiers, then :event or ;alternate). */
-const CSI_U_SOURCE = '\x1b\\[(\\d+)(?:;(\\d+))?(?:[:;](\\d+))?u'
+
+/** One decoded CSI-u keypress: key code, 1-based modifier param, alternate code. */
+interface CsiUKey {
+  code: number
+  modifiers: number
+  alternate?: number
+}
+
+/** Match one CSI-u sequence (code, optional ;modifiers, then :event or ;alternate). */
+const CSI_U_SOURCE = '\x1b\\[(\\d+)(?:;(\\d+))?(?:(:|;)(\\d+))?u'
+
+/** Kitty private-use keycodes for the numeric keypad and keypad Enter. */
+const KITTY_KEYPAD_CODES: Readonly<Record<number, string>> = {
+  57399: '0',
+  57400: '1',
+  57401: '2',
+  57402: '3',
+  57403: '4',
+  57404: '5',
+  57405: '6',
+  57406: '7',
+  57407: '8',
+  57408: '9',
+  57414: '\r',
+}
 
 /** Legacy equivalent for one decoded CSI-u key, or undefined to pass through. */
 function legacyForKey(key: CsiUKey): string | undefined {
-  const bits = Math.max(0, key.modifiers - 1)
-  const shift = (bits & 1) !== 0
-  const alt = (bits & 2) !== 0
+  const bits = Math.max(0, key.modifiers - 1)
+  const shift = (bits & 1) !== 0
+  const alt = (bits & 2) !== 0
   const ctrl = (bits & 4) !== 0
   if (key.code === 13) {
     // Modified Enter has no dedicated composer behavior. Preserve the legacy
@@ -110,62 +134,73 @@ function legacyForKey(key: CsiUKey): string | undefined {
     if (ctrl) return '\n'
     if (alt) return '\x1b\r'
     return '\r'
-  }
-  if (key.code === 27) return '\x1b'
-  if (key.code === 9) return shift ? '\x1b[Z' : '\t'
-  if (key.code === 127) return alt || ctrl ? '\x1b\x7f' : '\x7f'
-  // Kitty disambiguate mode reports the six legacy functional keys as CSI u
-  // codes 1-6 (Home, Insert, Delete, End, PageUp, PageDown). Ink 5 cannot
-  // parse these forms and would insert literal "[3u" text into the draft, so
-  // rewrite them to the legacy sequences the input layer already annotates.
-  // The modifier parameter passes through: kitty and xterm share the same
-  // 1+bit-field encoding (shift 2, alt 3, ctrl 5, ...). Lock-key bits are
-  // dropped because the legacy sequences cannot express them.
-  if (key.code >= 1 && key.code <= 6) {
-    const mask = (shift ? 1 : 0) + (alt ? 2 : 0) + (ctrl ? 4 : 0)
-    const mods = mask === 0 ? '' : `;${mask + 1}`
-    if (key.code === 1) return mods === '' ? '\x1b[H' : `\x1b[1${mods}H`
-    if (key.code === 4) return mods === '' ? '\x1b[F' : `\x1b[1${mods}F`
-    return `\x1b[${key.code}${mods}~`
-  }
-  if (key.code >= 97 && key.code <= 122) {
-    const letter = String.fromCodePoint(key.code)
-    if (ctrl) return String.fromCodePoint(key.code - 96)
-    if (alt) return '\x1b' + letter
-    if (shift) return String.fromCodePoint(key.alternate ?? key.code - 32)
-    return letter
-  }
-  if (key.code >= 65 && key.code <= 90) {
-    if (ctrl) return String.fromCodePoint(key.code + 32 - 96)
-    if (alt) return '\x1b' + String.fromCodePoint(key.code + 32)
-    return String.fromCodePoint(key.code)
-  }
-  if (key.code >= 32 && key.code <= 126 && key.alternate !== undefined) {
-    const base = key.alternate >= 97 && key.alternate <= 122 ? key.alternate : key.code
-    if (ctrl && base - 96 >= 1 && base - 96 <= 26) return String.fromCodePoint(base - 96)
-    if (alt) return '\x1b' + String.fromCodePoint(key.alternate)
-    return String.fromCodePoint(key.alternate)
-  }
-  return undefined
-}
-
-/**
- * Rewrite every decodable kitty CSI-u sequence in one stdin chunk to the
- * legacy form the input layer already handles. Undecodable or non-key
- * sequences pass through untouched, so terminals without the protocol are
- * unaffected.
- */
+  }
+  if (key.code === 27) return '\x1b'
+  if (key.code === 9) return shift ? '\x1b[Z' : '\t'
+  if (key.code === 127) return alt || ctrl ? '\x1b\x7f' : '\x7f'
+  const keypad = KITTY_KEYPAD_CODES[key.code]
+  if (keypad !== undefined) {
+    if (alt) return '\x1b' + keypad
+    return keypad
+  }
+  // Kitty disambiguate mode reports the six legacy functional keys as CSI u
+  // codes 1-6 (Home, Insert, Delete, End, PageUp, PageDown). Ink 5 cannot
+  // parse these forms and would insert literal "[3u" text into the draft, so
+  // rewrite them to the legacy sequences the input layer already annotates.
+  // The modifier parameter passes through: kitty and xterm share the same
+  // 1+bit-field encoding (shift 2, alt 3, ctrl 5, ...). Lock-key bits are
+  // dropped because the legacy sequences cannot express them.
+  if (key.code >= 1 && key.code <= 6) {
+    const mask = (shift ? 1 : 0) + (alt ? 2 : 0) + (ctrl ? 4 : 0)
+    const mods = mask === 0 ? '' : `;${mask + 1}`
+    if (key.code === 1) return mods === '' ? '\x1b[H' : `\x1b[1${mods}H`
+    if (key.code === 4) return mods === '' ? '\x1b[F' : `\x1b[1${mods}F`
+    return `\x1b[${key.code}${mods}~`
+  }
+  if (key.code >= 97 && key.code <= 122) {
+    const letter = String.fromCodePoint(key.code)
+    if (ctrl) return String.fromCodePoint(key.code - 96)
+    if (alt) return '\x1b' + letter
+    if (shift) return String.fromCodePoint(key.alternate ?? key.code - 32)
+    return letter
+  }
+  if (key.code >= 65 && key.code <= 90) {
+    if (ctrl) return String.fromCodePoint(key.code + 32 - 96)
+    if (alt) return '\x1b' + String.fromCodePoint(key.code + 32)
+    return String.fromCodePoint(key.code)
+  }
+  if (key.code >= 32 && key.code <= 126) {
+    // Kitty reports ordinary printable keys as CSI-u with no alternate code
+    // (for example space is `ESC[32u` and `1` is `ESC[49u`). Keep the
+    // alternate form when present, but never leave a plain printable key as
+    // an unknown escape sequence for Ink to swallow.
+    const base = key.alternate ?? key.code
+    if (ctrl && base - 96 >= 1 && base - 96 <= 26) return String.fromCodePoint(base - 96)
+    if (alt) return '\x1b' + String.fromCodePoint(base)
+    return String.fromCodePoint(base)
+  }
+  return undefined
+}
+
+/**
+ * Rewrite every decodable kitty CSI-u sequence in one stdin chunk to the
+ * legacy form the input layer already handles. Undecodable or non-key
+ * sequences pass through untouched, so terminals without the protocol are
+ * unaffected.
+ */
 export function normalizeKeyboardChunk(chunk: string): string {
   if (!chunk.includes('\x1b[') || !chunk.includes('u')) return chunk
   const pattern = new RegExp(CSI_U_SOURCE, 'g')
-  return chunk.replace(pattern, (whole, code: string, mods?: string, third?: string) => {
-    const legacy = legacyForKey({
-      code: Number.parseInt(code, 10),
-      modifiers: mods === undefined || mods === '' ? 1 : Math.max(1, Number.parseInt(mods, 10)),
-      alternate: third !== undefined && third !== '' ? Number.parseInt(third, 10) : undefined,
-    })
-    return legacy ?? whole
-  })
+  return chunk.replace(pattern, (whole, code: string, mods?: string, separator?: ':' | ';', third?: string) => {
+    const legacy = legacyForKey({
+      code: Number.parseInt(code, 10),
+      modifiers: mods === undefined || mods === '' ? 1 : Math.max(1, Number.parseInt(mods, 10)),
+      // A colon introduces Kitty's optional event type (`:1` = press), not
+      // an alternate key code. Semicolon introduces the alternate code.
+      alternate: separator === ';' && third !== undefined && third !== '' ? Number.parseInt(third, 10) : undefined,
+    })
+    return legacy ?? whole
+  })
 }
 
 /** Editor actions Ink cannot distinguish reliably when terminal bytes batch. */