@robota-sdk/agent-ui-terminal 3.0.0-beta.100

package/src/keybindings/node-keybindings-source.ts

@@ -0,0 +1,189 @@
+import { watch, type FSWatcher } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname } from 'node:path';
+
+import {
+  parseKeybindingsDocument,
+  type IKeybindingDiagnostic,
+  type IKeybindingSnapshot,
+} from './keybinding-registry.js';
+
+const RELOAD_DEBOUNCE_MS = 10;
+
+export interface IKeybindingsFilePort {
+  ensureFile(): Promise<string>;
+}
+
+export interface IKeybindingsSource extends IKeybindingsFilePort {
+  readonly filePath: string;
+  start(): Promise<void>;
+  isStarted(): boolean;
+  getSnapshot(): IKeybindingSnapshot;
+  subscribe(listener: (snapshot: IKeybindingSnapshot) => void): () => void;
+  dispose(): void;
+}
+
+export interface INodeKeybindingsSourceOptions {
+  readonly filePath: string;
+  readonly schemaUrl?: string;
+  readonly onDiagnostic?: (diagnostic: IKeybindingDiagnostic) => void;
+}
+
+function defaultDocument(schemaUrl: string | undefined) {
+  return { ...(schemaUrl === undefined ? {} : { $schema: schemaUrl }), version: 1 as const, bindings: {} };
+}
+
+function defaultSnapshot(filePath: string, schemaUrl: string | undefined): IKeybindingSnapshot {
+  const parsed = parseKeybindingsDocument(JSON.stringify(defaultDocument(schemaUrl)), filePath);
+  if (!parsed.ok) throw new Error(parsed.diagnostic.message);
+  return parsed.snapshot;
+}
+
+class NodeKeybindingsSource implements IKeybindingsSource {
+  readonly filePath: string;
+  readonly #schemaUrl: string | undefined;
+  readonly #onDiagnostic: ((diagnostic: IKeybindingDiagnostic) => void) | undefined;
+  readonly #listeners = new Set<(snapshot: IKeybindingSnapshot) => void>();
+  #snapshot: IKeybindingSnapshot;
+  #watcher: FSWatcher | undefined;
+  #reloadTimer: ReturnType<typeof setTimeout> | undefined;
+  #startPromise: Promise<void> | undefined;
+  #disposed = false;
+
+  constructor(options: INodeKeybindingsSourceOptions) {
+    if (options.filePath.trim() === '') throw new Error('Keybindings file path must not be empty.');
+    if (options.schemaUrl?.trim() === '') throw new Error('Keybindings schema URL must not be empty.');
+    this.filePath = options.filePath;
+    this.#schemaUrl = options.schemaUrl;
+    this.#onDiagnostic = options.onDiagnostic;
+    this.#snapshot = defaultSnapshot(this.filePath, this.#schemaUrl);
+  }
+
+  start(): Promise<void> {
+    if (this.#disposed) return Promise.reject(new Error('Keybindings source is disposed.'));
+    if (this.#startPromise !== undefined) return this.#startPromise;
+    this.#startPromise = this.#start().catch((cause) => {
+      this.#watcher?.close();
+      this.#watcher = undefined;
+      this.#startPromise = undefined;
+      throw cause;
+    });
+    return this.#startPromise;
+  }
+
+  async #start(): Promise<void> {
+    const directory = dirname(this.filePath);
+    await mkdir(directory, { recursive: true });
+    await this.#load();
+    if (this.#disposed) throw new Error('Keybindings source is disposed.');
+    this.#watcher = watch(directory, { persistent: false }, (_event, filename) => {
+      if (filename !== null && filename.toString() !== basename(this.filePath)) return;
+      this.#scheduleReload();
+    });
+  }
+
+  isStarted(): boolean {
+    return this.#watcher !== undefined && !this.#disposed;
+  }
+
+  getSnapshot(): IKeybindingSnapshot {
+    return this.#snapshot;
+  }
+
+  subscribe(listener: (snapshot: IKeybindingSnapshot) => void): () => void {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  async ensureFile(): Promise<string> {
+    await mkdir(dirname(this.filePath), { recursive: true });
+    try {
+      await writeFile(this.filePath, `${JSON.stringify(defaultDocument(this.#schemaUrl), null, 2)}\n`, {
+        encoding: 'utf8',
+        flag: 'wx',
+        mode: 0o600,
+      });
+    } catch (cause) {
+      if (!isAlreadyExists(cause as object)) throw cause;
+    }
+    return this.filePath;
+  }
+
+  dispose(): void {
+    this.#disposed = true;
+    if (this.#reloadTimer !== undefined) clearTimeout(this.#reloadTimer);
+    this.#reloadTimer = undefined;
+    this.#watcher?.close();
+    this.#watcher = undefined;
+    this.#listeners.clear();
+  }
+
+  #scheduleReload(): void {
+    if (this.#disposed) return;
+    if (this.#reloadTimer !== undefined) clearTimeout(this.#reloadTimer);
+    this.#reloadTimer = setTimeout(() => {
+      this.#reloadTimer = undefined;
+      void this.#load();
+    }, RELOAD_DEBOUNCE_MS);
+  }
+
+  async #load(): Promise<void> {
+    let text: string;
+    try {
+      text = await readFile(this.filePath, 'utf8');
+    } catch (cause) {
+      if (isNotFound(cause as object)) return;
+      this.#publishInvalid({
+        file: this.filePath,
+        path: '$',
+        message: errorMessage(cause as object),
+      });
+      return;
+    }
+    const parsed = parseKeybindingsDocument(text, this.filePath);
+    if (!parsed.ok) {
+      this.#publishInvalid(parsed.diagnostic);
+      return;
+    }
+    this.#publish(Object.freeze({ ...parsed.snapshot, generation: this.#snapshot.generation + 1 }));
+  }
+
+  #publishInvalid(diagnostic: IKeybindingDiagnostic): void {
+    this.#onDiagnostic?.(diagnostic);
+    this.#publish(
+      Object.freeze({
+        ...this.#snapshot,
+        generation: this.#snapshot.generation + 1,
+        diagnostic,
+      }),
+    );
+  }
+
+  #publish(snapshot: IKeybindingSnapshot): void {
+    if (this.#disposed) return;
+    this.#snapshot = snapshot;
+    for (const listener of this.#listeners) listener(snapshot);
+  }
+}
+
+function isNotFound(cause: object): boolean {
+  return isNodeError(cause) && cause.code === 'ENOENT';
+}
+
+function isAlreadyExists(cause: object): boolean {
+  return isNodeError(cause) && cause.code === 'EEXIST';
+}
+
+function isNodeError(cause: object): cause is NodeJS.ErrnoException {
+  return cause instanceof Error && 'code' in cause;
+}
+
+function errorMessage(cause: object): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+export function createNodeKeybindingsSource(
+  options: INodeKeybindingsSourceOptions,
+): IKeybindingsSource {
+  return new NodeKeybindingsSource(options);
+}

package/src/numbered-list.tsx

@@ -0,0 +1,113 @@
+/**
+ * CLI-2004 — the numbered-list menu (SSOT for its grammar).
+ *
+ * Every arrow-key menu becomes this in screen-reader mode: `N. <option>` lines followed by one
+ * prompt naming the valid range. Arrow navigation and the `> ` cursor are position cues a reader
+ * cannot follow — a spoken "3" is unambiguous, and the range in the prompt is the affordance.
+ *
+ * The prompt LITERAL is authored here, not copied from any reference: the surveyed documentation
+ * publishes the prompt's NAME and the cancel suffix, never the composed string. This module is the
+ * one place it exists, so the menus cannot drift into per-component dialects — the same reason
+ * `key-hint-footer.tsx` owns the footer grammar.
+ *
+ * No colour props: the mode drops colour rather than substituting values, so the palette floor stays
+ * green and nothing here depends on a cue a reader cannot hear.
+ */
+
+import { Box } from 'ink';
+import React from 'react';
+
+import { Text } from './SafeText.js';
+
+/** Appended to the prompt when Escape actually cancels the menu. */
+export const NUMBERED_LIST_CANCEL_SUFFIX = ' or Escape to cancel';
+
+/** The prompt literal. `Enter selection (1-3)`, plus the cancel suffix where it applies. */
+export function formatNumberedSelectionPrompt(itemCount: number, cancellable: boolean): string {
+  const base = `Enter selection (1-${itemCount})`;
+  return cancellable ? `${base}${NUMBERED_LIST_CANCEL_SUFFIX}` : base;
+}
+
+/** One row's number prefix: `1. `, `2. `, … */
+export function numberedRowPrefix(index: number): string {
+  return `${index + 1}. `;
+}
+
+export interface INumberedSelectionPromptProps {
+  /** How many rows the prompt names. Zero ⇒ nothing is rendered: `(1-0)` names no answer. */
+  itemCount: number;
+  cancellable?: boolean;
+  /** Digits typed so far, echoed after the prompt. */
+  buffer?: string;
+  /** The last entry was out of range ⇒ the same literal is re-printed. */
+  invalid?: boolean;
+}
+
+/**
+ * The prompt line, separated from `NumberedList` so a menu that renders its own rows — the
+ * checklist, whose rows carry a checkbox — asks its question in the same words rather than
+ * inventing a dialect.
+ */
+export function NumberedSelectionPrompt({
+  itemCount,
+  cancellable = false,
+  buffer = '',
+  invalid = false,
+}: INumberedSelectionPromptProps): React.ReactElement | null {
+  if (itemCount === 0) return null;
+  const prompt = formatNumberedSelectionPrompt(itemCount, cancellable);
+  return (
+    <>
+      <Text>
+        {prompt}
+        {buffer.length > 0 ? ` ${buffer}` : ''}
+      </Text>
+      {/* An out-of-range answer re-prints the SAME literal: the range is the correction. */}
+      {invalid && <Text>{prompt}</Text>}
+    </>
+  );
+}
+
+export interface INumberedListProps {
+  /** Heading line, e.g. the menu title or the permission question. */
+  title?: string;
+  /** Extra context line under the title. */
+  description?: string;
+  /** The selectable options, in order. */
+  options: readonly string[];
+  /** Escape cancels ⇒ the prompt says so. */
+  cancellable?: boolean;
+  /** Digits typed so far, echoed after the prompt. */
+  buffer?: string;
+  /** The last entry was out of range ⇒ the same literal is re-printed. */
+  invalid?: boolean;
+}
+
+/** Render the numbered list and its prompt. */
+export function NumberedList({
+  title,
+  description,
+  options,
+  cancellable = false,
+  buffer = '',
+  invalid = false,
+}: INumberedListProps): React.ReactElement {
+  return (
+    <Box flexDirection="column">
+      {title !== undefined && title.length > 0 && <Text>{title}</Text>}
+      {description !== undefined && description.length > 0 && <Text>{description}</Text>}
+      {options.map((option, index) => (
+        <Text key={`${index}-${option}`}>
+          {numberedRowPrefix(index)}
+          {option}
+        </Text>
+      ))}
+      <NumberedSelectionPrompt
+        itemCount={options.length}
+        cancellable={cancellable}
+        buffer={buffer}
+        invalid={invalid}
+      />
+    </Box>
+  );
+}

package/src/plugin-tui-handlers.ts

@@ -0,0 +1,163 @@
+/**
+ * Screen-specific selection handlers for PluginTUI.
+ * Extracted to keep PluginTUI.tsx under 300 lines.
+ */
+
+import type { IMenuSelectItem } from './MenuSelect.js';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+
+interface IConfirmState {
+  message: string;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+
+interface IMenuContext {
+  marketplace?: string;
+  pluginId?: string;
+}
+
+interface INavActions {
+  push: (state: { screen: string; context?: IMenuContext }) => void;
+  pop: () => void;
+  popN: (n: number) => void;
+  notify: (content: string) => void;
+  setConfirm: (state: IConfirmState | undefined) => void;
+  refresh: () => void;
+}
+
+export function handleMainSelect(value: string, nav: Pick<INavActions, 'push'>): void {
+  if (value === 'marketplace') {
+    nav.push({ screen: 'marketplace-list' });
+  } else if (value === 'installed') {
+    nav.push({ screen: 'installed-list' });
+  }
+}
+
+export function handleMarketplaceListSelect(value: string, nav: Pick<INavActions, 'push'>): void {
+  if (value === '__add__') {
+    nav.push({ screen: 'marketplace-add' });
+  } else {
+    nav.push({ screen: 'marketplace-action', context: { marketplace: value } });
+  }
+}
+
+export function handleMarketplaceActionSelect(
+  value: string,
+  marketplace: string,
+  callbacks: ICommandPluginAdapter,
+  nav: Pick<INavActions, 'push' | 'pop' | 'popN' | 'notify' | 'setConfirm'>,
+): void {
+  if (value === 'browse') {
+    nav.push({ screen: 'marketplace-browse', context: { marketplace } });
+  } else if (value === 'update') {
+    callbacks
+      .marketplaceUpdate(marketplace)
+      .then(() => {
+        nav.notify(`Updated marketplace "${marketplace}".`);
+        nav.pop();
+      })
+      .catch((err) => {
+        nav.notify(`Error: ${err instanceof Error ? err.message : String(err)}`);
+      });
+  } else if (value === 'remove') {
+    nav.setConfirm({
+      message: `Remove marketplace "${marketplace}" and all its plugins?`,
+      onConfirm: () => {
+        nav.setConfirm(undefined);
+        callbacks
+          .marketplaceRemove(marketplace)
+          .then(() => {
+            nav.notify(`Removed marketplace "${marketplace}".`);
+            nav.popN(2);
+          })
+          .catch((err) => {
+            nav.notify(`Error: ${err instanceof Error ? err.message : String(err)}`);
+          });
+      },
+      onCancel: () => nav.setConfirm(undefined),
+    });
+  }
+}
+
+export function handleMarketplaceBrowseSelect(
+  value: string,
+  marketplace: string,
+  items: IMenuSelectItem[],
+  nav: Pick<INavActions, 'push'>,
+): void {
+  const fullId = `${value}@${marketplace}`;
+  const item = items.find((i) => i.value === value);
+  if (item?.hint === 'installed') {
+    nav.push({ screen: 'installed-action', context: { pluginId: fullId } });
+  } else {
+    nav.push({ screen: 'marketplace-install-scope', context: { marketplace, pluginId: fullId } });
+  }
+}
+
+export function handleInstallScopeSelect(
+  value: string,
+  pluginId: string,
+  callbacks: ICommandPluginAdapter,
+  nav: Pick<INavActions, 'popN' | 'notify'>,
+): void {
+  const scope = value as 'user' | 'project';
+  callbacks
+    .install(pluginId, scope)
+    .then(() => {
+      nav.notify(`Installed plugin "${pluginId}" (${scope} scope).`);
+      nav.popN(2);
+    })
+    .catch((err) => {
+      nav.notify(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    });
+}
+
+export function handleInstalledListSelect(
+  value: string,
+  callbacks: ICommandPluginAdapter,
+  nav: Pick<INavActions, 'notify' | 'setConfirm' | 'refresh'>,
+): void {
+  nav.setConfirm({
+    message: `Uninstall plugin "${value}"?`,
+    onConfirm: () => {
+      nav.setConfirm(undefined);
+      callbacks
+        .uninstall(value)
+        .then(() => {
+          nav.notify(`Uninstalled plugin "${value}".`);
+          nav.refresh();
+        })
+        .catch((err) => {
+          nav.notify(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    },
+    onCancel: () => nav.setConfirm(undefined),
+  });
+}
+
+export function handleInstalledActionSelect(
+  value: string,
+  pluginId: string,
+  callbacks: ICommandPluginAdapter,
+  nav: Pick<INavActions, 'popN' | 'notify' | 'setConfirm'>,
+): void {
+  if (value === 'uninstall') {
+    nav.setConfirm({
+      message: `Uninstall plugin "${pluginId}"?`,
+      onConfirm: () => {
+        nav.setConfirm(undefined);
+        callbacks
+          .uninstall(pluginId)
+          .then(() => {
+            nav.notify(`Uninstalled plugin "${pluginId}".`);
+            nav.popN(2);
+          })
+          .catch((err) => {
+            nav.notify(`Error: ${err instanceof Error ? err.message : String(err)}`);
+          });
+      },
+      onCancel: () => nav.setConfirm(undefined),
+    });
+  }
+}

package/src/product-display-name-context.tsx

@@ -0,0 +1,30 @@
+import React, { createContext, useContext } from 'react';
+
+const ProductDisplayNameContext = createContext('Assistant');
+const ModelCommandToolPrefixContext = createContext<string | undefined>(undefined);
+
+export function ProductDisplayNameProvider({
+  name,
+  modelCommandToolPrefix,
+  children,
+}: {
+  name?: string;
+  modelCommandToolPrefix?: string;
+  children: React.ReactNode;
+}): React.ReactElement {
+  return (
+    <ProductDisplayNameContext.Provider value={name?.trim() || 'Assistant'}>
+      <ModelCommandToolPrefixContext.Provider value={modelCommandToolPrefix}>
+        {children}
+      </ModelCommandToolPrefixContext.Provider>
+    </ProductDisplayNameContext.Provider>
+  );
+}
+
+export function useProductDisplayName(): string {
+  return useContext(ProductDisplayNameContext);
+}
+
+export function useModelCommandToolPrefix(): string | undefined {
+  return useContext(ModelCommandToolPrefixContext);
+}

package/src/render-markdown.ts

@@ -0,0 +1,209 @@
+import { marked } from 'marked';
+// @ts-expect-error — marked-terminal has no type declarations
+import TerminalRenderer from 'marked-terminal';
+
+import { sanitizeTerminalText } from './sanitize-terminal-text.js';
+import { isInteractiveColorTerminal } from './terminal-capabilities.js';
+import {
+  diffRowStyles,
+  markdownRendererOptions,
+  resolveTheme,
+  syntaxHighlightTheme,
+} from './theme/index.js';
+
+import type { IDiffRowStyles, ITuiTheme } from './theme/index.js';
+import type { Renderer } from 'marked';
+
+const CODE_BLOCK_INDENT = '    ';
+
+export interface IRenderMarkdownOptions {
+  color?: boolean;
+  codeBlockWidth?: number;
+  /**
+   * SCREEN-2002: the resolved theme. Absent ⇒ the `dark` built-in, which is byte-identical to what
+   * this renderer produced before themes existed.
+   */
+  theme?: ITuiTheme;
+  /** SCREEN-2002: `false` renders code blocks as plain indented text, with no highlight SGR. */
+  syntaxHighlighting?: boolean;
+  /**
+   * CLI-2004: flatten tables to `Header: value` sentences. A box-drawn grid is unreadable aloud —
+   * a reader announces the rules, not the relationship between a heading and its cell.
+   */
+  screenReader?: boolean;
+}
+
+interface IHighlightOptions {
+  ignoreIllegals?: boolean;
+  /** The cli-highlight theme marked-terminal forwards; absent ⇒ its red/green defaults. */
+  theme?: Record<string, (text: string) => string>;
+}
+
+type TTerminalRendererConstructor = new (
+  /** `marked-terminal`'s style options: one chalk instance per token it colours. */
+  options?: Record<string, (text: string) => string>,
+  highlightOptions?: IHighlightOptions,
+) => Renderer;
+
+const TerminalRendererConstructor = TerminalRenderer as TTerminalRendererConstructor;
+
+function shouldUseColor(option: boolean | undefined): boolean {
+  if (option !== undefined) {
+    return option;
+  }
+  return isInteractiveColorTerminal();
+}
+
+function isDiffLanguage(language: string | undefined): boolean {
+  return language?.trim().toLowerCase() === 'diff';
+}
+
+function styleAddedOrRemovedDiffRow(
+  line: string,
+  rowWidth: number,
+  color: boolean,
+  styles: IDiffRowStyles,
+): string {
+  const row = `${CODE_BLOCK_INDENT}${line}`.padEnd(rowWidth);
+  if (!color) {
+    return row.trimEnd();
+  }
+  if (line.startsWith('+')) return styles.added(row);
+  if (line.startsWith('-')) return styles.removed(row);
+  return row.trimEnd();
+}
+
+function colorizeDiffLine(
+  line: string,
+  color: boolean,
+  rowWidth: number,
+  styles: IDiffRowStyles,
+): string {
+  if (line.startsWith('+') || line.startsWith('-')) {
+    return styleAddedOrRemovedDiffRow(line, rowWidth, color, styles);
+  }
+  const row = `${CODE_BLOCK_INDENT}${line}`;
+  if (!color) {
+    return row;
+  }
+  if (line.startsWith('@@')) return styles.hunk(row);
+  if (line.startsWith('diff ') || line.startsWith('index ')) return styles.meta(row);
+  return row;
+}
+
+function resolveDiffRowWidth(lines: readonly string[], requestedWidth: number | undefined): number {
+  const minimumWidth = lines.reduce(
+    (maxWidth, line) => Math.max(maxWidth, CODE_BLOCK_INDENT.length + line.length),
+    0,
+  );
+  if (requestedWidth === undefined) {
+    return minimumWidth;
+  }
+  return Math.max(minimumWidth, requestedWidth);
+}
+
+function renderDiffCodeBlock(
+  code: string,
+  color: boolean,
+  codeBlockWidth: number | undefined,
+  styles: IDiffRowStyles,
+): string {
+  const lines = code.split('\n');
+  const rowWidth = resolveDiffRowWidth(lines, codeBlockWidth);
+  const body = lines.map((line) => colorizeDiffLine(line, color, rowWidth, styles)).join('\n');
+  return `${body}\n\n`;
+}
+
+/**
+ * CLI-2004 — flatten a table to `Header: value` lines.
+ *
+ * The cell and row hooks tag their output with separators marked's own renderers never emit, so the
+ * table hook can recover the grid it was given. Reconstructing it from the RENDERED strings is the
+ * alternative, and those already carry the SGR the inline renderers added.
+ */
+const CELL_MARK = '\u0000';
+const ROW_MARK = '\u0001';
+
+function splitTableCells(row: string): string[] {
+  const cells = row.split(ROW_MARK).join('').split(CELL_MARK);
+  // The trailing separator leaves one empty tail entry; the cells themselves may legitimately be ''.
+  return cells.slice(0, -1);
+}
+
+function installTableFlattening(renderer: Renderer): void {
+  renderer.tablecell = (content: string): string => `${content}${CELL_MARK}`;
+  renderer.tablerow = (content: string): string => `${content}${ROW_MARK}`;
+  renderer.table = (header: string, body: string): string => {
+    const headers = splitTableCells(header);
+    const rows = body
+      .split(ROW_MARK)
+      .filter((row) => row.length > 0)
+      .map((row) => splitTableCells(`${row}${ROW_MARK}`));
+    if (headers.length === 0 || rows.length === 0) return '';
+    const blocks = rows.map((cells) =>
+      headers.map((head, index) => `${head}: ${cells[index] ?? ''}`).join('\n'),
+    );
+    // A blank line between rows: the row boundary is the only structure left to hear.
+    return `${blocks.join('\n\n')}\n\n`;
+  };
+}
+
+function createTerminalRenderer(
+  color: boolean,
+  codeBlockWidth: number | undefined,
+  screenReader: boolean,
+  theme: ITuiTheme,
+  syntaxHighlighting: boolean,
+): Renderer {
+  // SCREEN-2002: both dependencies are told what to colour with. Left to their own defaults, a
+  // daltonized theme would still get green/red code blocks from cli-highlight's own theme.
+  const renderer = new TerminalRendererConstructor(markdownRendererOptions(theme.markdown), {
+    ignoreIllegals: true,
+    theme: syntaxHighlightTheme(theme.syntax),
+  });
+  const renderCode = renderer.code.bind(renderer);
+  const styles = diffRowStyles(theme);
+
+  renderer.code = (code: string, language: string | undefined, escaped: boolean): string => {
+    if (isDiffLanguage(language)) {
+      return renderDiffCodeBlock(code, color, codeBlockWidth, styles);
+    }
+    // Highlighting off: the block renders as plain indented text, the shape the diff path uses.
+    if (!syntaxHighlighting) {
+      return `${code
+        .split('\n')
+        .map((line) => `${CODE_BLOCK_INDENT}${line}`)
+        .join('\n')}\n\n`;
+    }
+    return renderCode(code, language, escaped);
+  };
+
+  if (screenReader) installTableFlattening(renderer);
+
+  return renderer;
+}
+
+/**
+ * Render markdown to a terminal-formatted string with colors, bold, etc.
+ * Returns the rendered string (may include ANSI escape codes).
+ */
+export function renderMarkdown(md: string, options: IRenderMarkdownOptions = {}): string {
+  // SEC-019 (issue #2022): the untrusted string is sanitized BEFORE parsing, never after. The
+  // renderer ADDS ANSI — colours, bold, code-block framing — so filtering its output would strip the
+  // repository's own presentation along with the attacker's. Filtering its input removes what
+  // arrived from outside and leaves what is generated after.
+  //
+  // This is the choke point every render path shares (MessageList, StreamingIndicator,
+  // ToolDiffBlock), which is why it is here rather than at each of the three.
+  const safe = sanitizeTerminalText(md);
+  const result = marked.parse(safe, {
+    renderer: createTerminalRenderer(
+      shouldUseColor(options.color),
+      options.codeBlockWidth,
+      options.screenReader === true,
+      resolveTheme(options.theme),
+      options.syntaxHighlighting !== false,
+    ),
+  });
+  return typeof result === 'string' ? result.trimEnd() : safe;
+}