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

package/src/__tests__/screen-reader-prepark-echo.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * SCREEN-2670 TC-10 — the echo exemption FIRES through the real render path.
+ *
+ * TC-03 arms the flag by hand, which proves the queue honours a stamp and nothing about whether
+ * anything ever sets one. This drives a keystroke through Ink's own input path into the composed
+ * tree — keybindings, the pacing context, the composer's key handler — with the proxy as Ink's
+ * stdout, and asserts BOTH halves: the keystroke's commit leaves unparked, and the next commit that
+ * is not a keystroke (a prop change from outside the composer, and Enter — whose commit appends the
+ * prompt line) is parked. A proxy that stamped everything would pass the first half and fail the
+ * second, which is why they sit in one test.
+ */
+
+import { EventEmitter } from 'node:events';
+
+import { Box, render, Text } from 'ink';
+import React, { useState } from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import CjkTextInput from '../CjkTextInput.js';
+import { KeybindingsProvider } from '../keybindings/keybindings-context.js';
+import { parseKeybindingsDocument } from '../keybindings/keybinding-registry.js';
+import { ScreenReaderPacingProvider } from '../screen-reader-pacing-context.js';
+import { createParkedStdout } from '../screen-reader-stdout.js';
+
+import type { IKeybindingsSource } from '../keybindings/node-keybindings-source.js';
+import type { IScreenReaderPacingPort } from '../screen-reader-pacing-context.js';
+import type { TParkedStdoutSource } from '../screen-reader-stdout.js';
+
+const PARK_MS = 400;
+
+class FakeTtyStdout extends EventEmitter {
+  readonly isTTY = true;
+  readonly columns = 80;
+  readonly rows = 24;
+  readonly destroyed = false;
+  readonly writable = true;
+  readonly writableEnded = false;
+  readonly writableLength = 0;
+  readonly writableNeedDrain = false;
+  readonly frames: Array<{ text: string; at: number }> = [];
+  write = (chunk: string | Uint8Array, ...rest: unknown[]): boolean => {
+    const callback = rest.find((argument) => typeof argument === 'function') as
+      ((error?: Error | null) => void) | undefined;
+    this.frames.push({ text: String(chunk), at: Date.now() });
+    callback?.(null);
+    return true;
+  };
+  asSource(): TParkedStdoutSource {
+    return this as unknown as TParkedStdoutSource;
+  }
+  textSince(index: number): string {
+    return this.frames
+      .slice(index)
+      .map((frame) => frame.text)
+      .join('');
+  }
+}
+
+class FakeStdin extends EventEmitter {
+  readonly isTTY = true;
+  private pending: string | null = null;
+  setEncoding(): void {}
+  setRawMode(): void {}
+  resume(): void {}
+  pause(): void {}
+  ref(): void {}
+  unref(): void {}
+  read(): string | null {
+    const data = this.pending;
+    this.pending = null;
+    return data;
+  }
+  send(data: string): void {
+    this.pending = data;
+    this.emit('readable');
+    this.emit('data', data);
+  }
+}
+
+function source(): IKeybindingsSource {
+  const parsed = parseKeybindingsDocument(
+    JSON.stringify({ version: 1, bindings: {} }),
+    '/tmp/keybindings.json',
+  );
+  if (!parsed.ok) throw new Error(parsed.diagnostic.message);
+  return {
+    filePath: '/tmp/keybindings.json',
+    start: async () => undefined,
+    isStarted: () => true,
+    ensureFile: async () => '/tmp/keybindings.json',
+    getSnapshot: () => parsed.snapshot,
+    subscribe: () => () => undefined,
+    dispose: () => undefined,
+  };
+}
+
+function Harness({
+  banner,
+  onSubmit,
+}: {
+  banner: string;
+  onSubmit: (value: string) => void;
+}): React.ReactElement {
+  const [value, setValue] = useState('');
+  return (
+    <Box flexDirection="column">
+      <Text>{banner}</Text>
+      <Box>
+        <Text>{'> '}</Text>
+        <CjkTextInput
+          value={value}
+          onChange={setValue}
+          onSubmit={(submitted) => {
+            // Like the real composer: submitting clears the line, so the commit repaints.
+            setValue('');
+            onSubmit(submitted);
+          }}
+          keybindingContext="chat-input"
+        />
+      </Box>
+    </Box>
+  );
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** In screen-reader mode Ink linearises each Text node; compare visible characters only. */
+const visible = (text: string): string =>
+  // eslint-disable-next-line no-control-regex -- stripping the escapes IS the point here
+  text.replace(/\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07/g, '').replace(/\s+/g, ' ');
+
+let unmount: (() => void) | undefined;
+
+afterEach(() => {
+  unmount?.();
+  unmount = undefined;
+});
+
+describe('TC-10: a keystroke through the composed tree is released unparked; a non-composer commit is parked', () => {
+  it('echo leaves at once, a banner change and Enter each wait out the interval', async () => {
+    const stdout = new FakeTtyStdout();
+    const stdin = new FakeStdin();
+    const parked = createParkedStdout({ stdout: stdout.asSource(), preparkMs: PARK_MS });
+    const port: IScreenReaderPacingPort = {
+      armEchoRelease: () => parked.armEchoRelease(),
+      write: (text) => {
+        parked.write(text);
+      },
+    };
+    const submitted: string[] = [];
+    const tree = (banner: string): React.ReactElement => (
+      <KeybindingsProvider source={source()}>
+        <ScreenReaderPacingProvider port={port}>
+          <Harness banner={banner} onSubmit={(value) => submitted.push(value)} />
+        </ScreenReaderPacingProvider>
+      </KeybindingsProvider>
+    );
+    const instance = render(tree('banner 1'), {
+      stdout: parked.asInkStdout(),
+      stdin: stdin as unknown as NodeJS.ReadStream,
+      isScreenReaderEnabled: true,
+      // Ink treats a CI environment as non-interactive and defers every frame to unmount; the
+      // park only exists for interactive terminals, so say so explicitly (as the real-cursor
+      // suite does) rather than let the runner's CI variable decide what is under test.
+      interactive: true,
+      exitOnCtrlC: false,
+      patchConsole: false,
+    });
+    unmount = instance.unmount;
+
+    // First frames: the first batch is never parked; let the mount settle past one interval.
+    await sleep(PARK_MS + 100);
+    expect(stdout.textSince(0)).toContain('banner 1');
+
+    // A keystroke: its echo must be on the underlying stream well inside the interval.
+    const beforeKey = stdout.frames.length;
+    stdin.send('hey');
+    await sleep(80);
+    expect(visible(stdout.textSince(beforeKey))).toContain('hey');
+
+    // A commit that is not a keystroke, arriving inside the interval after the echo: parked until
+    // the interval since that last printable release has elapsed, then released.
+    const beforeBanner = stdout.frames.length;
+    instance.rerender(tree('banner 2'));
+    await sleep(80);
+    expect(visible(stdout.textSince(beforeBanner))).not.toContain('banner 2');
+    await sleep(PARK_MS);
+    expect(visible(stdout.textSince(beforeBanner))).toContain('banner 2');
+
+    // Enter runs through the same key handler and must NOT arm: arriving right after the banner's
+    // release, the submit commit is parked like any other transcript commit.
+    const beforeEnter = stdout.frames.length;
+    stdin.send('\r');
+    await sleep(80);
+    expect(submitted).toEqual(['hey']);
+    expect(stdout.frames.length).toBe(beforeEnter);
+    await sleep(PARK_MS);
+    expect(stdout.frames.length).toBeGreaterThan(beforeEnter);
+  }, 10_000);
+});

package/src/__tests__/screen-reader-render-options.test.ts

@@ -0,0 +1,262 @@
+/**
+ * CLI-2004 TC-02 / TC-03 / TC-17 / TC-18 — the mode's entry point.
+ *
+ * TC-02 asserts BOTH halves of the threading, because they fail independently: Ink's own
+ * `isScreenReaderEnabled` option, and the hand-maintained `toChannelOptions` projection that
+ * ARCH-110 records as able to drop an option silently.
+ * TC-03/TC-18 assert the first line the process prints — the confirmation, the advisory, and the
+ * two cases where nothing at all is printed.
+ * TC-17 asserts the banner suppression, which TC-11's box-drawing sweep cannot see because the
+ * banner is ASCII art, not box-drawing characters.
+ */
+
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { BANNER_GLYPHS, BANNER_ART } from '../app-banner.js';
+import { buildStaticItems } from '../app-static-items.js';
+import {
+  screenReaderAnnouncement,
+  writeScreenReaderAnnouncement,
+} from '../screen-reader-announcement.js';
+import { toChannelOptions } from '../render.js';
+
+import type { IRenderOptions } from '../render.js';
+import type { IKeybindingsSource } from '../keybindings/node-keybindings-source.js';
+import type { IHistoryEntry, IAIProvider } from '@robota-sdk/agent-core';
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+
+const inkRender = vi.hoisted(() =>
+  vi.fn(
+    (
+      _node: unknown,
+      _options?: { isScreenReaderEnabled?: boolean; stdout?: NodeJS.WriteStream },
+    ) => ({
+      waitUntilExit: async (): Promise<void> => {},
+    }),
+  ),
+);
+
+vi.mock('ink', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('ink')>();
+  return { ...actual, render: inkRender };
+});
+
+// The App boots a channel and starts I/O; the mode's threading is what is under test, not the App.
+vi.mock('../App.js', () => ({
+  default: (): React.ReactElement => React.createElement('robota-app'),
+}));
+
+function baseOptions(): IRenderOptions {
+  return {
+    cwd: '/tmp/project',
+    provider: {} as IAIProvider,
+    cliAdapter: {} as ITuiCliAdapter,
+  };
+}
+
+describe('TC-02: the mode reaches Ink AND the channel projection', () => {
+  beforeEach(() => {
+    inkRender.mockClear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('renderApp passes isScreenReaderEnabled: true to Ink render when the mode is on', async () => {
+    const { renderApp } = await import('../render.js');
+    await renderApp({ ...baseOptions(), screenReader: true });
+
+    expect(inkRender).toHaveBeenCalledTimes(1);
+    expect(inkRender.mock.calls[0]?.[1]?.isScreenReaderEnabled).toBe(true);
+  });
+
+  it('renderApp passes isScreenReaderEnabled: false when no mode input is present (default-off)', async () => {
+    const { renderApp } = await import('../render.js');
+    await renderApp(baseOptions());
+
+    expect(inkRender.mock.calls[0]?.[1]?.isScreenReaderEnabled).toBe(false);
+  });
+
+  it('toChannelOptions projects screenReader — the ARCH-110 drop hazard', () => {
+    expect(toChannelOptions({ ...baseOptions(), screenReader: true }).screenReader).toBe(true);
+    expect(toChannelOptions({ ...baseOptions(), screenReader: false }).screenReader).toBe(false);
+  });
+
+  it('toChannelOptions leaves screenReader undefined when the option is absent', () => {
+    expect(toChannelOptions(baseOptions()).screenReader).toBeUndefined();
+  });
+});
+
+describe('BEHAVIOR-2003: keybinding source lifecycle', () => {
+  it('disposes the source when initialization fails before Ink starts', async () => {
+    const startupFailure = new Error('watcher startup failed');
+    const dispose = vi.fn();
+    const source = {
+      start: vi.fn().mockRejectedValue(startupFailure),
+      dispose,
+    } as unknown as IKeybindingsSource;
+    inkRender.mockClear();
+
+    const { renderApp } = await import('../render.js');
+    await expect(renderApp({ ...baseOptions(), keybindingsSource: source })).rejects.toBe(
+      startupFailure,
+    );
+
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(inkRender).not.toHaveBeenCalled();
+  });
+});
+
+describe('TC-03: the confirmation line names the channel', () => {
+  it('prints the channel that actually turned the mode on', () => {
+    expect(screenReaderAnnouncement({ enabled: true, channel: 'flag' })).toBe(
+      '[Screen reader mode: on via flag]',
+    );
+    expect(screenReaderAnnouncement({ enabled: true, channel: 'env' })).toBe(
+      '[Screen reader mode: on via env]',
+    );
+    expect(screenReaderAnnouncement({ enabled: true, channel: 'settings' })).toBe(
+      '[Screen reader mode: on via settings]',
+    );
+  });
+
+  it('prints nothing when the mode is off and no reader hint is present', () => {
+    expect(screenReaderAnnouncement({ enabled: false })).toBeUndefined();
+    const written: string[] = [];
+    writeScreenReaderAnnouncement({ enabled: false }, (text) => written.push(text));
+    expect(written).toEqual([]);
+  });
+
+  it('renderApp writes the confirmation line to stdout before Ink is called', async () => {
+    const written: string[] = [];
+    const spy = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation((chunk: string | Uint8Array): boolean => {
+        written.push(String(chunk));
+        return true;
+      });
+    inkRender.mockClear();
+    inkRender.mockImplementation(() => {
+      // Ink is reached only after the line is already on stdout.
+      expect(written.join('')).toContain('[Screen reader mode: on via flag]');
+      return { waitUntilExit: async (): Promise<void> => {} };
+    });
+    try {
+      const { renderApp } = await import('../render.js');
+      await renderApp({ ...baseOptions(), screenReader: true, screenReaderChannel: 'flag' });
+    } finally {
+      spy.mockRestore();
+      inkRender.mockImplementation(() => ({ waitUntilExit: async (): Promise<void> => {} }));
+    }
+    expect(written.join('')).toContain('[Screen reader mode: on via flag]\n');
+    expect(inkRender).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('TC-18: the advisory line, and its two negatives', () => {
+  it('is the first line when the mode is off and a reader-shaped hint is present', () => {
+    const written: string[] = [];
+    writeScreenReaderAnnouncement({ enabled: false, hint: true }, (text) => written.push(text));
+    expect(written.join('').split('\n')[0]).toBe(
+      '[Screen reader mode: off — run with --screen-reader]',
+    );
+  });
+
+  it('is absent when the mode is off and there is no hint', () => {
+    expect(screenReaderAnnouncement({ enabled: false, hint: false })).toBeUndefined();
+  });
+
+  it('is replaced by the confirmation line when the mode is on, never printed alongside it', () => {
+    const written: string[] = [];
+    writeScreenReaderAnnouncement({ enabled: true, channel: 'env', hint: true }, (text) =>
+      written.push(text),
+    );
+    const output = written.join('');
+    expect(output).toBe('[Screen reader mode: on via env]\n');
+    expect(output).not.toContain('run with --screen-reader');
+  });
+});
+
+describe('TC-17: the ASCII banner is not committed in the mode', () => {
+  const history = [{ id: 'h1' } as unknown as IHistoryEntry];
+
+  it('omits the banner item entirely when the mode is on', () => {
+    const items = buildStaticItems({ history, version: '1.2.3', screenReader: true });
+    expect(items.some((item) => item.kind === 'banner')).toBe(false);
+    expect(items).toEqual([{ kind: 'entry', entry: history[0] }]);
+  });
+
+  it('keeps the banner item when the mode is off', () => {
+    const items = buildStaticItems({ history, version: '1.2.3', screenReader: false });
+    expect(items[0]).toEqual({ kind: 'banner', version: '1.2.3' });
+  });
+
+  it('the suppressed art is what carries the glyphs a box-drawing sweep would miss', () => {
+    for (const glyph of BANNER_GLYPHS) {
+      expect(BANNER_ART).toContain(glyph);
+    }
+    // None of them is a box-drawing character — hence the separate criterion.
+    expect(BANNER_ART).not.toMatch(/[│─┌┐└┘├┤┬┴┼╭╮╰╯]/u);
+  });
+});
+
+describe('SCREEN-2670 TC-05: with the mode off, render() is called with no stdout key at all', () => {
+  beforeEach(() => {
+    inkRender.mockClear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('passes no stdout when the mode is off — Ink defaults to process.stdout and keys its map by it', async () => {
+    const { renderApp } = await import('../render.js');
+    await renderApp(baseOptions());
+    const options = inkRender.mock.calls[0]?.[1] ?? {};
+    expect(Object.keys(options)).not.toContain('stdout');
+  });
+
+  it('passes no stdout when the mode is on but the park is disabled with 0', async () => {
+    const { renderApp } = await import('../render.js');
+    await renderApp({
+      ...baseOptions(),
+      screenReader: true,
+      screenReaderPacing: {
+        startupQuiet: { raw: '0', label: 'ACME_STARTUP_QUIET_MS' },
+        prepark: { raw: '0', label: 'ACME_PREPARK_MS' },
+      },
+    });
+    expect(Object.keys(inkRender.mock.calls[0]?.[1] ?? {})).not.toContain('stdout');
+  });
+
+  it('ignores an ambient Robota park override when the host supplies no park choice', async () => {
+    vi.stubEnv('ROBOTA_SCREEN_READER_PREPARK_MS', '0');
+    const { renderApp } = await import('../render.js');
+    await renderApp({
+      ...baseOptions(),
+      screenReader: true,
+      screenReaderPacing: {
+        startupQuiet: { raw: '0', label: 'ACME_STARTUP_QUIET_MS' },
+      },
+    });
+    expect(inkRender.mock.calls[0]?.[1]?.stdout).toBeDefined();
+  });
+
+  it('hands Ink the owned stdout when the mode is on and the park is enabled', async () => {
+    const { renderApp } = await import('../render.js');
+    await renderApp({
+      ...baseOptions(),
+      screenReader: true,
+      screenReaderPacing: {
+        startupQuiet: { raw: '0', label: 'ACME_STARTUP_QUIET_MS' },
+        prepark: { raw: '50', label: 'ACME_PREPARK_MS' },
+      },
+    });
+    const stdout = inkRender.mock.calls[0]?.[1]?.stdout;
+    expect(stdout).toBeDefined();
+    expect(stdout).not.toBe(process.stdout);
+    expect(typeof stdout?.write).toBe('function');
+  });
+});