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

package/src/__tests__/ui-intent-rendering.test.tsx

@@ -0,0 +1,291 @@
+/**
+ * CMD-004 Phase 2 Stage C (TC-04): the TUI is a pure renderer — the four UI screens open from the
+ * requester-routed `ui_intent` session event (never from legacy `result.effects` branches), the
+ * session title updates from the broadcast `session_renamed` event (never by the TUI mutating the
+ * session), and the statusline re-reads its persisted settings when a command result arrives
+ * (refresh-on-result — the HOST applies the patch; the TUI no longer writes settings).
+ *
+ * Red-first evidence: written against the pre-Stage-C hook (which still consumed legacy effects and
+ * had no session subscription) — every behavioral case below failed there.
+ */
+
+import { Text } from 'ink';
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { useSideEffects } from '../hooks/useSideEffects.js';
+import { useStatusLineSettings } from '../hooks/useStatusLineSettings.js';
+import { TuiCliAdapterProvider } from '../tui-cli-adapter-context.js';
+import { TUI_SESSION_EVENT_CLASSIFICATION } from '../tui-session-events.js';
+
+import type { IUseSideEffectsOptions, IUseSideEffectsResult } from '../hooks/side-effects-types.js';
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+
+const FRAME_DEADLINE_MS = 3000;
+
+async function waitUntil(predicate: () => boolean): Promise<void> {
+  const deadline = Date.now() + FRAME_DEADLINE_MS;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  expect(predicate()).toBe(true);
+}
+
+type TSessionListener = (payload: unknown) => void;
+
+/** Minimal InteractiveSession stand-in: a typed event emitter (`on`/`off`/`emit`). */
+class FakeSessionEmitter {
+  private readonly listeners = new Map<string, Set<TSessionListener>>();
+
+  on(event: string, handler: TSessionListener): void {
+    const set = this.listeners.get(event) ?? new Set<TSessionListener>();
+    set.add(handler);
+    this.listeners.set(event, set);
+  }
+
+  off(event: string, handler: TSessionListener): void {
+    this.listeners.get(event)?.delete(handler);
+  }
+
+  emit(event: string, payload: unknown): void {
+    for (const handler of [...(this.listeners.get(event) ?? [])]) handler(payload);
+  }
+
+  listenerCount(event: string): number {
+    return this.listeners.get(event)?.size ?? 0;
+  }
+
+  subscribedEvents(): string[] {
+    return [...this.listeners].filter(([, handlers]) => handlers.size > 0).map(([event]) => event);
+  }
+
+  setName = vi.fn();
+  getName = (): string | undefined => undefined;
+}
+
+function fakeCliAdapter(store: () => Record<string, TUniversalValue>): ITuiCliAdapter {
+  return {
+    getUserSettingsPath: () => '/tmp/fake-settings.json',
+    readSettings: () => store(),
+    reloadPluginCommandSource: vi.fn(),
+    applyActiveModelChange: vi.fn().mockReturnValue({ applied: true }),
+    getGitBranch: vi.fn().mockReturnValue(undefined),
+    getProviderDisplayName: vi.fn((type: string) => type),
+  } as unknown as ITuiCliAdapter;
+}
+
+interface IHarness {
+  session: FakeSessionEmitter;
+  result: () => IUseSideEffectsResult;
+  lastFrame: () => string | undefined;
+  unmount: () => void;
+  spies: {
+    setSessionName: ReturnType<typeof vi.fn>;
+    refreshStatusLineSettings: ReturnType<typeof vi.fn>;
+    refreshAppearanceSettings: ReturnType<typeof vi.fn>;
+    openAgentSwitcher: ReturnType<typeof vi.fn>;
+    baseHandleSubmit: ReturnType<typeof vi.fn>;
+  };
+}
+
+function mountHarness(): IHarness {
+  const session = new FakeSessionEmitter();
+  const spies = {
+    setSessionName: vi.fn(),
+    refreshStatusLineSettings: vi.fn(),
+    refreshAppearanceSettings: vi.fn(),
+    openAgentSwitcher: vi.fn(),
+    baseHandleSubmit: vi.fn(async () => {}),
+  };
+  const resultRef: { current: IUseSideEffectsResult | null } = { current: null };
+
+  // Superset options object: carries both the pre-Stage-C fields (queue, addEntry, …) and the
+  // Stage-C fields so the SAME test file compiled red (pre) and green (post).
+  const options = {
+    cwd: '/tmp',
+    uiEventPort: session,
+    commandEffectQueue: {
+      enqueueEffects: () => undefined,
+      drain: () => undefined,
+      clear: () => undefined,
+    },
+    addEntry: vi.fn(),
+    baseHandleSubmit: spies.baseHandleSubmit,
+    setSessionName: spies.setSessionName,
+    setStatusLineSettings: vi.fn(),
+    refreshStatusLineSettings: spies.refreshStatusLineSettings,
+    refreshAppearanceSettings: spies.refreshAppearanceSettings,
+    showSessionPickerOnStart: false,
+    openAgentSwitcher: spies.openAgentSwitcher,
+  } as unknown as IUseSideEffectsOptions;
+
+  function Probe(): React.ReactElement {
+    const state = useSideEffects(options);
+    resultRef.current = state;
+    return (
+      <Text>
+        {`plugin:${state.showPluginTUI ? 1 : 0} settings:${state.showTransportTUI ? 1 : 0} picker:${state.showSessionPicker ? 1 : 0}`}
+      </Text>
+    );
+  }
+
+  const instance = render(
+    <TuiCliAdapterProvider value={fakeCliAdapter(() => ({}))}>
+      <Probe />
+    </TuiCliAdapterProvider>,
+  );
+
+  return {
+    session,
+    result: () => {
+      if (!resultRef.current) throw new Error('useSideEffects result not captured');
+      return resultRef.current;
+    },
+    lastFrame: instance.lastFrame,
+    unmount: instance.unmount,
+    spies,
+  };
+}
+
+describe('ui_intent → TUI screens (requester-routed, CMD-004 Stage C)', () => {
+  it('show-settings with the owner requester opens the settings screen', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', { intent: { type: 'show-settings' }, requesterDriverId: 'owner' });
+    await waitUntil(() => (h.lastFrame() ?? '').includes('settings:1'));
+    h.unmount();
+  });
+
+  it('show-plugin-manager with the owner requester opens the plugin screen', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', {
+      intent: { type: 'show-plugin-manager' },
+      requesterDriverId: 'owner',
+    });
+    await waitUntil(() => (h.lastFrame() ?? '').includes('plugin:1'));
+    h.unmount();
+  });
+
+  it('show-session-picker with the owner requester opens the session picker', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', {
+      intent: { type: 'show-session-picker' },
+      requesterDriverId: 'owner',
+    });
+    await waitUntil(() => (h.lastFrame() ?? '').includes('picker:1'));
+    h.unmount();
+  });
+
+  it('show-agent-switcher with the owner requester invokes the switcher callback', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', {
+      intent: { type: 'show-agent-switcher' },
+      requesterDriverId: 'owner',
+    });
+    await waitUntil(() => h.spies.openAgentSwitcher.mock.calls.length === 1);
+    h.unmount();
+  });
+
+  it('an intent stamped with ANOTHER surface driver id is ignored (requester-routed)', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', {
+      intent: { type: 'show-settings' },
+      requesterDriverId: 'device-remote-1',
+    });
+    h.session.emit('ui_intent', {
+      intent: { type: 'show-agent-switcher' },
+      requesterDriverId: 'device-remote-1',
+    });
+    // Give the (wrong) render a chance to happen, then assert it did not.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(h.lastFrame()).toContain('settings:0');
+    expect(h.spies.openAgentSwitcher).not.toHaveBeenCalled();
+    h.unmount();
+  });
+
+  it('an unattributed intent (no requester id) is ignored by this surface', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', { intent: { type: 'show-settings' } });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(h.lastFrame()).toContain('settings:0');
+    h.unmount();
+  });
+
+  it('unmounting unsubscribes the ui_intent and session_renamed listeners', async () => {
+    const h = mountHarness();
+    const expected = Object.entries(TUI_SESSION_EVENT_CLASSIFICATION)
+      .filter(([, classification]) => classification === 'react-side-effect')
+      .map(([event]) => event)
+      .sort();
+    await waitUntil(() => h.session.subscribedEvents().sort().join() === expected.join());
+    h.unmount();
+    await waitUntil(() => h.session.subscribedEvents().length === 0);
+  });
+});
+
+describe('session_renamed broadcast → TUI title (CMD-004 Stage C / TC-10)', () => {
+  it('updates the session name from the broadcast without mutating the session itself', async () => {
+    const h = mountHarness();
+    h.session.emit('session_renamed', { name: 'Renamed via broadcast' });
+    await waitUntil(() => h.spies.setSessionName.mock.calls.length === 1);
+    expect(h.spies.setSessionName).toHaveBeenCalledWith('Renamed via broadcast');
+    // Pure renderer: the TUI reflects the host-executed rename; it never performs it.
+    expect(h.session.setName).not.toHaveBeenCalled();
+    h.unmount();
+  });
+});
+
+describe('statusline refresh-on-result (CMD-004 Stage C)', () => {
+  it('re-reads statusline settings after a slash-command result arrives', async () => {
+    const h = mountHarness();
+    await h.result().handleSubmit('/statusline off');
+    expect(h.spies.baseHandleSubmit).toHaveBeenCalledWith('/statusline off');
+    expect(h.spies.refreshStatusLineSettings).toHaveBeenCalledTimes(1);
+    // SCREEN-2002: the appearance is re-read on the same signal — a `/theme` result has already
+    // been written to the settings document by the host when this fires.
+    expect(h.spies.refreshAppearanceSettings).toHaveBeenCalledTimes(1);
+    h.unmount();
+  });
+
+  it('does not re-read for a plain (non-command) submit', async () => {
+    const h = mountHarness();
+    await h.result().handleSubmit('hello there');
+    expect(h.spies.refreshStatusLineSettings).not.toHaveBeenCalled();
+    expect(h.spies.refreshAppearanceSettings).not.toHaveBeenCalled();
+    h.unmount();
+  });
+});
+
+describe('useStatusLineSettings exposes a from-disk refresh', () => {
+  it('refresh() re-reads the persisted settings document', async () => {
+    let doc: Record<string, TUniversalValue> = { statusline: { enabled: true, gitBranch: true } };
+    const adapter = fakeCliAdapter(() => doc);
+    const captured: {
+      settings: { enabled: boolean; gitBranch: boolean } | null;
+      refresh: (() => void) | null;
+    } = { settings: null, refresh: null };
+
+    function Probe(): React.ReactElement {
+      const [settings, refresh] = useStatusLineSettings();
+      captured.settings = settings;
+      captured.refresh = refresh as unknown as () => void;
+      return <Text>{`enabled:${settings.enabled ? 1 : 0}`}</Text>;
+    }
+
+    const instance = render(
+      <TuiCliAdapterProvider value={adapter}>
+        <Probe />
+      </TuiCliAdapterProvider>,
+    );
+    await waitUntil(() => (instance.lastFrame() ?? '').includes('enabled:1'));
+
+    // The HOST persisted a patch (Stage B applies it via the settings adapter); the TUI refreshes.
+    doc = { statusline: { enabled: false, gitBranch: true } };
+    captured.refresh?.();
+    await waitUntil(() => (instance.lastFrame() ?? '').includes('enabled:0'));
+    expect(captured.settings?.enabled).toBe(false);
+    instance.unmount();
+  });
+});

package/src/__tests__/wave-text.test.tsx

@@ -0,0 +1,133 @@
+/**
+ * SCREEN-006 WaveText token-sourcing tests.
+ *
+ * WaveText's color ramp comes from the resolved theme's motion tokens (its cadence is its own) in
+ * `src/theme/built-in-themes.ts` (not component-private literals), and the gated/static
+ * frame must use the canonical muted token. Reduced-motion behavior is
+ * re-asserted against the token source: when `isInteractiveColorTerminal()` is
+ * false there is no interval and no color churn.
+ */
+import chalk from 'chalk';
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import WaveText from '../WaveText.js';
+import { ScreenReaderProvider } from '../screen-reader-context.js';
+import { DARK_THEME } from '../theme/built-in-themes.js';
+import { foreground } from '../theme/index.js';
+
+/** Cadence is not themed; the component owns it (SCREEN-2002). */
+const WAVE_INTERVAL_MS = 400;
+
+const gateMock = vi.hoisted(() => ({ value: true }));
+
+vi.mock('../terminal-capabilities.js', () => ({
+  isInteractiveColorTerminal: (): boolean => gateMock.value,
+}));
+
+/** Extract every SGR open-sequence used in a frame (e.g. "38;2;85;85;85"). */
+function sgrCodes(frame: string): string[] {
+  // eslint-disable-next-line no-control-regex -- asserting on raw SGR escape bytes by design
+  return [...frame.matchAll(/\x1b\[([0-9;]+)m/g)].map((m) => m[1]);
+}
+
+/** The SGR open code chalk emits for a color, at the level ink uses in this env. */
+function chalkOpenCodes(colorize: (s: string) => string): string[] {
+  return sgrCodes(colorize('x'));
+}
+
+const ORIGINAL_CHALK_LEVEL = chalk.level;
+
+beforeAll(() => {
+  // Pin color bytes regardless of the test process's TTY detection (cjk-fallback precedent).
+  chalk.level = 3;
+});
+
+afterAll(() => {
+  chalk.level = ORIGINAL_CHALK_LEVEL;
+});
+
+afterEach(() => {
+  gateMock.value = true;
+  vi.useRealTimers();
+});
+
+describe('WaveText motion tokens (SCREEN-006)', () => {
+  it('animated frames draw only from the theme’s wave ramp', () => {
+    gateMock.value = true;
+    const allowed = new Set<string>(['39', '0']);
+    for (const stop of DARK_THEME.motion.wave) {
+      for (const code of chalkOpenCodes((s) => chalk.hex(stop)(s))) {
+        allowed.add(code);
+      }
+    }
+
+    const { lastFrame, unmount } = render(<WaveText text="Thinking" />);
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    const used = sgrCodes(frame);
+    expect(used.length).toBeGreaterThan(0);
+    const outside = used.filter((code) => !allowed.has(code));
+    expect(outside).toEqual([]);
+  });
+
+  it('gated/static frame renders with the theme’s muted token and no color churn', () => {
+    gateMock.value = false;
+    vi.useFakeTimers();
+
+    const { lastFrame, unmount } = render(<WaveText text="Thinking" />);
+    const first = lastFrame() ?? '';
+
+    // The muted token (not a wave hex stop) styles the static frame.
+    const mutedCodes = chalkOpenCodes((s) => foreground(DARK_THEME.colors.text.muted)(s));
+    for (const code of mutedCodes) {
+      expect(first).toContain(`\u001b[${code}m`);
+    }
+
+    // No interval ⇒ no motion: advancing time produces the identical frame.
+    vi.advanceTimersByTime(WAVE_INTERVAL_MS * 5);
+    const later = lastFrame() ?? '';
+    unmount();
+    expect(later).toBe(first);
+  });
+});
+
+/**
+ * CLI-2004 TC-19 — a spinner is a repaint per frame, and a repaint is an announcement. In the mode
+ * the text is written once and no interval is ever scheduled.
+ */
+describe('CLI-2004 TC-19: WaveText in screen-reader mode', () => {
+  it('renders its text once and schedules no interval', () => {
+    gateMock.value = true; // the colour gate is OPEN — the mode alone must stop the animation
+    vi.useFakeTimers();
+
+    const { lastFrame, unmount } = render(
+      <ScreenReaderProvider enabled={true}>
+        <WaveText text="Thinking" />
+      </ScreenReaderProvider>,
+    );
+    const first = lastFrame() ?? '';
+
+    // No pending timer at all — not merely a frame that happens to look the same.
+    expect(vi.getTimerCount()).toBe(0);
+
+    vi.advanceTimersByTime(WAVE_INTERVAL_MS * 5);
+    const later = lastFrame() ?? '';
+    unmount();
+
+    expect(first).toContain('Thinking');
+    expect(later).toBe(first);
+    expect(sgrCodes(first).filter((code) => code !== '0' && code !== '39')).toEqual([]);
+  });
+
+  it('leaves the 400 ms ramp exactly as it is outside the mode', () => {
+    gateMock.value = true;
+    vi.useFakeTimers();
+
+    const { unmount } = render(<WaveText text="Thinking" />);
+    expect(vi.getTimerCount()).toBeGreaterThan(0);
+    unmount();
+  });
+});