feat(cli): OpenTUI migration foundation batch — theme, a11y, clipboard, keys, dialogs scaffolding

packages/cli/src/ui/opentui/a11y-plain-text.test.ts

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * Copyright 2026 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { markdownToPlainText, stripAnsi } from './a11y-plain-text.js';
+
+describe('stripAnsi', () => {
+  it('removes SGR color and attribute sequences', () => {
+    expect(stripAnsi('\x1b[31mred\x1b[0m')).toBe('red');
+    expect(stripAnsi('\x1b[1;33mbold yellow\x1b[0m')).toBe('bold yellow');
+    expect(stripAnsi('\x1b[38:5:208mext\x1b[0m')).toBe('ext');
+  });
+
+  it('removes cursor movement and erase sequences', () => {
+    expect(stripAnsi('\x1b[2K\x1b[1Atext\x1b[2J')).toBe('text');
+    expect(stripAnsi('\x1b[?25lhidden cursor\x1b[?25h')).toBe('hidden cursor');
+  });
+
+  it('removes OSC sequences with BEL or ST terminators', () => {
+    expect(stripAnsi('\x1b]8;;https://example.com\x07link\x1b]8;;\x07')).toBe(
+      'link',
+    );
+    expect(stripAnsi('\x1b]0;window title\x1b\\body')).toBe('body');
+  });
+
+  it('leaves plain text untouched', () => {
+    expect(stripAnsi('hello world')).toBe('hello world');
+    expect(stripAnsi('')).toBe('');
+  });
+
+  it('removes device escape sequences (R2-10)', () => {
+    // SGR mouse reports and DEC save/restore cursor leaked past the old
+    // hand-rolled pattern.
+    expect(stripAnsi('\x1b[<0;5;1Mclick')).toBe('click');
+    expect(stripAnsi('\x1b7x\x1b8')).toBe('x');
+  });
+});
+
+describe('markdownToPlainText', () => {
+  it('strips heading markers', () => {
+    expect(markdownToPlainText('# Title')).toBe('Title');
+    expect(markdownToPlainText('### Deep heading')).toBe('Deep heading');
+  });
+
+  it('strips emphasis and inline code markers', () => {
+    expect(markdownToPlainText('**bold** and *em* and _u_')).toBe(
+      'bold and em and u',
+    );
+    expect(markdownToPlainText('run `npm test` now')).toBe('run npm test now');
+    expect(markdownToPlainText('__strong__ ~~gone~~')).toBe('strong gone');
+  });
+
+  it('reduces links and images to their text', () => {
+    expect(markdownToPlainText('see [docs](https://x.dev) now')).toBe(
+      'see docs now',
+    );
+    expect(markdownToPlainText('logo ![alt text](img.png) end')).toBe(
+      'logo alt text end',
+    );
+  });
+
+  it('keeps fenced code bodies, dropping the fences', () => {
+    const md = ['```ts', 'const a = 1;', '```'].join('\n');
+    expect(markdownToPlainText(md)).toBe('const a = 1;');
+  });
+
+  it('drops blockquote prefixes and horizontal rules', () => {
+    expect(markdownToPlainText('> quoted line')).toBe('quoted line');
+    expect(markdownToPlainText('a\n---\nb')).toBe('a\n\nb');
+  });
+
+  it('keeps bullet markers and plain lines', () => {
+    expect(markdownToPlainText('- first\n- second')).toBe('- first\n- second');
+    expect(markdownToPlainText('just text')).toBe('just text');
+  });
+
+  it('leaves dunders and snake_case identifiers untouched', () => {
+    expect(markdownToPlainText('def __init__(self):')).toBe(
+      'def __init__(self):',
+    );
+    expect(markdownToPlainText('use snake_case_name here')).toBe(
+      'use snake_case_name here',
+    );
+    // Boundary-guarded underscore emphasis still works.
+    expect(markdownToPlainText('really _important_ now')).toBe(
+      'really important now',
+    );
+  });
+
+  it('keeps fence-like lines inside a block opened by the other character (R1-47/48)', () => {
+    // CommonMark: a fence only closes on the same character.
+    expect(markdownToPlainText('~~~\n```\nbody\n~~~\nafter')).toBe(
+      '```\nbody\nafter',
+    );
+    expect(markdownToPlainText('```\n~~~\nbody\n```\nafter')).toBe(
+      '~~~\nbody\nafter',
+    );
+  });
+
+  it('recognizes headings inside blockquotes (R1-1)', () => {
+    expect(markdownToPlainText('> # Title')).toBe('Title');
+  });
+
+  it('keeps code-span contents literal — no link/emphasis consumption (R1-1)', () => {
+    expect(markdownToPlainText('`[a](b)`')).toBe('[a](b)');
+    expect(markdownToPlainText('`**not bold**`')).toBe('**not bold**');
+  });
+
+  it('tracks fence length — a shorter run does not close a longer fence (R2-10)', () => {
+    expect(
+      markdownToPlainText('````\ncode\n```\nstill code\n````\nafter'),
+    ).toBe('code\n```\nstill code\nafter');
+  });
+
+  it('keeps fence-like quoted lines inside a fence literal (R2-10)', () => {
+    // A de-quoted ``` inside a fenced body must not flip fence state.
+    expect(markdownToPlainText('```\n> ```\n```\nafter **bold**')).toBe(
+      '> ```\nafter bold',
+    );
+  });
+
+  it('keeps inner backticks in multi-backtick code spans (R2-10)', () => {
+    expect(markdownToPlainText('a ``b ` c`` d')).toBe('a b ` c d');
+  });
+
+  it('a fence line with info text does not close an open fence (R3-3)', () => {
+    // CommonMark: a closing fence cannot carry info text, so ```js inside
+    // an open block is literal body — not an early close that drops the
+    // block and inverts parse state for the rest of the document.
+    expect(markdownToPlainText('```\n```js\nbody\n```\nafter **x**')).toBe(
+      '```js\nbody\nafter x',
+    );
+  });
+});

packages/cli/src/ui/opentui/a11y-plain-text.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * Copyright 2026 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Plain-text conversions for screen-reader parity. Ink's screen-reader path
+ * renders squashed text only (no styles, borders or backgrounds), so the
+ * OpenTUI equivalent needs ANSI-stripped, markdown-reduced text for anything
+ * it would otherwise draw with colors or structure.
+ *
+ * The reduction stays line-based on purpose: ink's InlineMarkdownRenderer
+ * guards underscore emphasis at word boundaries so identifiers like
+ * `__init__` survive, and a CommonMark parser (markdown-it) emphasizes them.
+ * Fences, code spans and quote prefixes below follow the CommonMark rules
+ * ink's renderer applies.
+ */
+
+import stripAnsiLib from 'strip-ansi';
+
+// strip-ansi 7.x does not strip CSI sequences with intermediate bytes
+// (0x20-0x2F) or private parameter markers (e.g. SGR mouse \x1b[<0;5;1M);
+// remove the full CSI production first: parameter bytes 0x30-0x3F,
+// intermediate bytes 0x20-0x2F, final byte 0x40-0x7E — one regex
+// covers both private and non-private CSI.
+/* eslint-disable no-control-regex */
+const CSI_SEQUENCE = /\x1b\[[0-9;:<=>?]*[\x20-\x2F]*[@-~]/g;
+/* eslint-enable no-control-regex */
+
+// strip-ansi also leaves DCS/SOS/PM/APC sequences (only the 2-byte
+// introducer of a DCS is consumed) and unterminated OSC bodies in place;
+// consume them through ST/BEL/end-of-input so SIXEL payloads or tmux
+// passthroughs never reach the screen reader as announced garbage.
+/* eslint-disable no-control-regex */
+const OTHER_ESCAPE_SEQUENCE =
+  /\x1b[PX^_][\s\S]*?(?:\x1b\\|\x07|$)|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\|$)/g;
+/* eslint-enable no-control-regex */
+
+/** Strips all ANSI escape sequences, leaving the readable text. */
+export function stripAnsi(text: string): string {
+  return stripAnsiLib(
+    text.replace(CSI_SEQUENCE, '').replace(OTHER_ESCAPE_SEQUENCE, ''),
+  );
+}
+
+/**
+ * Reduces markdown to the plain text a screen reader should announce:
+ * headings lose their hashes, fenced code keeps its body, emphasis markers
+ * disappear, links and images reduce to their text/alt, blockquote prefixes
+ * and horizontal rules are dropped. Bullet markers stay — they are readable
+ * content in the ink parity path too.
+ */
+export function markdownToPlainText(markdown: string): string {
+  const result: string[] = [];
+  // The character AND length of the fence that opened the current code
+  // block, or null outside one. CommonMark: a fence only closes on the
+  // same character with at least the opening length.
+  let fenceChar: '`' | '~' | null = null;
+  let fenceLength = 0;
+
+  // CommonMark line endings: \r\n, \n, and lone \r all terminate a line;
+  // splitting on \n alone leaves \r on the line, which `.` excludes and
+  // `$` cannot see past, deadening fence detection for CRLF markdown.
+  for (const rawLine of markdown.split(/\r\n|\n|\r/)) {
+    // CommonMark fence: 3+ backticks/tildes, optionally indented up to 3
+    // spaces. An OPENING fence may carry info text (```js); a CLOSING
+    // fence cannot — a fence-like line with trailing content inside a
+    // block is literal body, not a close.
+    const fenceMatch = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(rawLine);
+    if (fenceMatch) {
+      const run = fenceMatch[1]!;
+      const trailing = fenceMatch[2] ?? '';
+      const char = run.charAt(0) as '`' | '~';
+      if (fenceChar === null) {
+        fenceChar = char;
+        fenceLength = run.length;
+      } else if (
+        fenceChar === char &&
+        run.length >= fenceLength &&
+        trailing.trim() === ''
+      ) {
+        fenceChar = null;
+        fenceLength = 0;
+      } else {
+        result.push(rawLine);
+      }
+      continue;
+    }
+    if (fenceChar !== null) {
+      result.push(rawLine);
+      continue;
+    }
+
+    // Block-level passes run on the de-quoted view so headings inside
+    // blockquotes are recognized; the prefix is not content. (Only outside
+    // fences — a `>` line inside a fenced body is literal text.)
+    let text = rawLine.replace(/^(?:\s*>\s?)+/, '');
+    // Headings: "# Title" -> "Title".
+    text = text.replace(/^ {0,3}#{1,6}\s+/, '');
+    // Horizontal rules vanish in screen-reader output.
+    if (/^ {0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/.test(text)) {
+      result.push('');
+      continue;
+    }
+    // Extract code spans before the other inline passes: their contents are
+    // literal text and must not be consumed as links/emphasis markup.
+    // Mirrors ink's INLINE_CODE_SPAN_PATTERN_SOURCE: non-empty content, and
+    // the closing run is neither preceded nor followed by another backtick,
+    // so `` and stray runs stay literal instead of being consumed reordered.
+    const codeSpans: string[] = [];
+    text = text.replace(
+      /(?<!`)(`+)(?!`)([\s\S]+?)(?<!`)\1(?!`)/g,
+      (_, _ticks, span) => {
+        codeSpans.push(span);
+        return `\u0000${codeSpans.length - 1}\u0000`;
+      },
+    );
+    // Images -> alt text, links -> link text.
+    text = text.replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1');
+    text = text.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
+    // Bold before italic so "**x**" is not eaten twice.
+    text = text.replace(/\*\*(?=\S)([\s\S]*?\S)\*\*/g, '$1');
+    // Underscore emphasis only applies at word boundaries (CommonMark), so
+    // "__init__" and snake_case identifiers survive untouched.
+    text = text.replace(/(^|\s)__(?=\S)([\s\S]*?\S)__(?=\s|$)/g, '$1$2');
+    text = text.replace(/~~(?=\S)([\s\S]*?\S)~~/g, '$1');
+    text = text.replace(/\*(?=\S)([\s\S]*?\S)\*/g, '$1');
+    text = text.replace(/(^|\s)_(?=\S)([\s\S]*?\S)_(?=\s|$)/g, '$1$2');
+    // Restore the code-span contents last.
+    text = text.replace(
+      // eslint-disable-next-line no-control-regex -- NUL marks extracted code spans
+      /\u0000(\d+)\u0000/g,
+      (_, index: string) => codeSpans[Number(index)] ?? '',
+    );
+
+    result.push(text);
+  }
+
+  return result.join('\n');
+}