feat: improvied TUI, commands and added more themes

Author: MrFaruk0

docs/HANDOFF.md

@@ -1,6 +1,87 @@
 # Development handoff
 
-**Last update:** 2026-08-08
+## 2026-08-09 TUI UX milestone
+
+Implemented a responsive centered shell capped at 112 columns, edge-to-edge narrow rendering,
+unique slash-command Tab completion, simplified provider forms, four additional themes, and explicit
+keyboard semantics. OpenRouter uses its built-in endpoint and `OPENROUTER_API_KEY`; the advanced
+OpenAI-compatible form uses `OPENAI_API_KEY`. Neither form exposes an environment-reference field,
+and pasted credentials remain ephemeral and masked. Ctrl+C is an application no-op, Ctrl+X cancels
+an active run, and `/exit` is the normal exit path.
+
+Tests cover 140- and 50-column layouts without overflow, completion without submission, provider
+field visibility, fixed internal credential references, theme construction, and cancellation/exit
+behavior.
+
+### Verification
+
+Focused runs first, then the full gate set, all green on Node.js `v24.14.1`:
+
+```text
+npm test --workspace @researk/cli -- tui-state.test.ts                  # passed: 32 tests
+npm test --workspace @researk/cli -- tui-app.test.tsx                   # passed: 65 tests
+npm test --workspace @researk/cli -- tui-provider-integration.test.tsx  # passed: 5 tests
+npm test --workspace @researk/cli -- tui-controller.test.ts theme.test.ts # passed: 27 tests
+npm test --workspace @researk/cli                                       # passed: 191 in 11 files
+npm run clean                                                           # passed: 7 workspace packages
+npm run build                                                           # passed: 7 workspace packages
+npm run typecheck                                                       # passed: 7 workspace packages
+npm test                                                                # passed: 323 in 19 files
+npm run lint                                                            # passed: 101 files
+npm run format-check                                                    # passed: 101 files
+git diff --check                                                        # passed: no whitespace errors
+node packages/cli/dist/bin.js help                                      # passed: exit 0
+node packages/cli/dist/bin.js version                                   # passed: exit 0
+node packages/cli/dist/bin.js doctor --json                             # passed: exit 0, telemetry false
+"" | node packages/cli/dist/bin.js                                      # passed: exit 2, non-TTY guard
+```
+
+Per-package totals behind the 323: `@researk/cli` 191 in 11 files (was 180), `@researk/latex-renderer`
+97 in 3, `@researk/provider-openai-compatible` 12, `@researk/contracts` 10, `@researk/harness` 7,
+`@researk/provider-openrouter` 4, and `@researk/research` 2. The CLI count rose by 11 because this
+milestone adds completion, layout, and key-binding coverage.
+
+The real Ink lifecycle was also driven through `startTui` with a TTY-shaped stream pair against the
+built `dist`: the alternate screen entered on mount, an idle Ctrl+C kept the app mounted without
+inserting a `c`, an idle Ctrl+X was also a no-op, `/pro`+Tab produced `/provider` and Enter opened
+the provider picker rather than submitting, `/exit` exited with code 0, the alternate screen was
+restored, and stderr stayed empty.
+
+### Files changed
+
+- `packages/cli/src/tui/commands.ts` — `completeSlashCommand` for unambiguous Tab completion
+- `packages/cli/src/tui/App.tsx` — Tab handler, Ctrl+C/Ctrl+X semantics, `terminalWidth`/`terminalHeight`
+  test seams, centered 112-column layout
+- `packages/cli/src/tui/components/Composer.tsx` — placeholder documents Ctrl+X
+- `packages/cli/src/tui/components/Footer.tsx` — persistent footer documents Ctrl+X and `/exit`
+- `packages/cli/src/tui/components/Conversation.tsx` — empty-state vertical centering
+- `packages/cli/src/tui/overlays/InfoOverlays.tsx` — help overlay key bindings
+- `packages/cli/src/tui/overlays/ProviderOverlay.tsx` — simplified forms; removed the
+  environment-reference field
+- `packages/cli/src/tui/controller.ts` — fixed internal references (`OPENROUTER_API_KEY`,
+  `OPENAI_API_KEY`) and OpenRouter default base URL
+- `packages/cli/src/tui/theme.ts` — four additional semantic themes (nord, dracula, solarized-dark,
+  gruvbox)
+- `packages/cli/src/theme.ts` — extended one-shot theme names and palettes
+- `packages/cli/src/tui.tsx` — comment and `exitOnCtrlC: false` intent
+- `packages/cli/test/tui-state.test.ts` — completion unit tests
+- `packages/cli/test/tui-app.test.tsx` — completion, layout, cancellation/exit, and provider form
+  tests
+- `packages/cli/test/tui-controller.test.ts` — connection reference tests
+- `packages/cli/test/tui-provider-integration.test.tsx` — pasted-key integration tests
+- `packages/cli/test/theme.test.ts` — extended theme construction
+- `docs/HANDOFF.md`
+
+### Intentional limitation: OpenAI-compatible URLs
+
+There is no universal default endpoint for an OpenAI-compatible provider. The normal `/provider`
+flow keeps the explicit Base URL field on the advanced OpenAI-compatible form (Provider ID + Base
+URL + masked key) because omitting it would pretend an impossible default exists. The form itself
+carries the disclosure line, and `validateProviderEndpoint` still enforces HTTPS-or-loopback and
+rejects credentials, query strings, and fragments in that URL. OpenRouter is the only choice with a
+built-in default endpoint, and its form exposes only the masked key field.
+
+**Last update:** 2026-08-09
 
 ## Current milestone: macOS TUI provider-integration timeouts fixed as a budget problem, not a hang
 

packages/cli/src/theme.ts

@@ -1,4 +1,14 @@
-export const THEME_NAMES = ["system", "dark", "light", "high-contrast", "mono"] as const;
+export const THEME_NAMES = [
+  "system",
+  "dark",
+  "light",
+  "high-contrast",
+  "mono",
+  "nord",
+  "dracula",
+  "solarized-dark",
+  "gruvbox",
+] as const;
 
 export type ThemeName = (typeof THEME_NAMES)[number];
 
@@ -94,4 +104,36 @@ const PALETTES: Readonly<
     math: "37",
     code: "37;2",
   }),
+  nord: Object.freeze({
+    accent: "38;5;110;1",
+    muted: "38;5;109",
+    heading: "38;5;255;1",
+    error: "38;5;174;1",
+    math: "38;5;110",
+    code: "38;5;221",
+  }),
+  dracula: Object.freeze({
+    accent: "38;5;141;1",
+    muted: "38;5;61",
+    heading: "38;5;231;1",
+    error: "38;5;203;1",
+    math: "38;5;212",
+    code: "38;5;228",
+  }),
+  "solarized-dark": Object.freeze({
+    accent: "38;5;37;1",
+    muted: "38;5;244",
+    heading: "38;5;230;1",
+    error: "38;5;166;1",
+    math: "38;5;37",
+    code: "38;5;136",
+  }),
+  gruvbox: Object.freeze({
+    accent: "38;5;108;1",
+    muted: "38;5;245",
+    heading: "38;5;223;1",
+    error: "38;5;167;1",
+    math: "38;5;142",
+    code: "38;5;214",
+  }),
 });

packages/cli/src/tui.tsx

@@ -14,7 +14,7 @@ import { createInitialState, type ProviderConnection } from "./tui/state.js";
  * Mounts the full-screen TUI in the terminal's alternate screen buffer.
  *
  * Ink owns entering and leaving the alternate screen, cursor visibility, and raw mode. Restoration
- * runs on normal exit, on Ctrl+C, and on an error, because `unmount` and `cleanup` are invoked from
+ * runs on normal exit and on an error, because `unmount` and `cleanup` are invoked from
  * a `finally` block that cannot be skipped.
  */
 export async function startTui(
@@ -57,7 +57,7 @@ export async function startTui(
     stdout: io.stdout as NodeJS.WriteStream,
     stdin: io.stdin as NodeJS.ReadStream,
     stderr: io.stderr as NodeJS.WriteStream,
-    // The application handles Ctrl+C itself so it can cancel a run without exiting.
+    // The application consumes Ctrl+C as a no-op and uses Ctrl+X for active-run cancellation.
     exitOnCtrlC: false,
     alternateScreen: true,
     patchConsole: true,

packages/cli/src/tui/App.tsx

@@ -4,7 +4,7 @@ import { type ReactNode, useCallback, useEffect, useMemo, useReducer, useRef } f
 import { VERSION } from "../help.js";
 import { redactSecrets, safeErrorMessage, safeTerminalText } from "../safety.js";
 import { isThemeName, type ThemeName } from "../theme.js";
-import { parseSlashCommand, SLASH_COMMANDS } from "./commands.js";
+import { completeSlashCommand, parseSlashCommand, SLASH_COMMANDS } from "./commands.js";
 import { Composer } from "./components/Composer.js";
 import { Conversation } from "./components/Conversation.js";
 import { Footer } from "./components/Footer.js";
@@ -47,6 +47,9 @@ export interface AppProps {
   readonly now?: () => number;
   /** Overrides Ink's own exit so the exit path can be observed in tests. */
   readonly onExit?: () => void;
+  /** Deterministic terminal dimensions for render tests. */
+  readonly terminalWidth?: number;
+  readonly terminalHeight?: number;
 }
 
 let noticeCounter = 0;
@@ -68,11 +71,12 @@ export function App(props: AppProps): ReactNode {
     [state.themeName, state.colorEnabled],
   );
 
-  const width = Math.max(40, stdout.columns ?? 80);
-  const height = Math.max(10, stdout.rows ?? 24);
+  const terminalWidth = Math.max(1, props.terminalWidth ?? stdout.columns ?? 80);
+  const width = Math.min(112, terminalWidth);
+  const height = Math.max(10, props.terminalHeight ?? stdout.rows ?? 24);
   // The conversation and any overlay share one fixed region. Both the key handler and the renderer
   // need this height, so it is derived once here rather than recomputed at each use.
-  const conversationHeight = Math.max(3, height - 12);
+  const conversationHeight = Math.max(3, height - 10);
 
   const notify = useCallback(
     (level: "info" | "warning" | "error" | "success", message: string): void => {
@@ -437,7 +441,7 @@ export function App(props: AppProps): ReactNode {
     // start a second Harness run and overwrite that slot, orphaning the first run beyond the reach
     // of Ctrl+C. Slash commands stay available because they never start a run.
     if (current.runStatus !== "idle" && !trimmed.startsWith("/")) {
-      notify("warning", "A response is still streaming. Press Ctrl+C to cancel it first.");
+      notify("warning", "A response is still streaming. Press Ctrl+X to cancel it first.");
       return;
     }
     dispatch({ type: "composer/submit" });
@@ -453,14 +457,15 @@ export function App(props: AppProps): ReactNode {
   useInput((input, key) => {
     const current = stateRef.current;
 
-    // Ctrl+C cancels an active run and keeps the app mounted; when idle it exits.
-    if (key.ctrl && input === "c") {
+    // Ctrl+C belongs to the terminal and is deliberately a no-op in the app. Ctrl+X is the
+    // explicit in-app cancellation binding; /exit is the only normal exit command.
+    if (key.ctrl && input === "c") return;
+    if (key.ctrl && input === "x") {
       if (activeRun.current !== undefined) {
         activeRun.current.abort();
         dispatch({ type: "run/status", status: "cancelling" });
         return;
       }
-      dispatch({ type: "exit" });
       return;
     }
 
@@ -492,6 +497,13 @@ export function App(props: AppProps): ReactNode {
       insertText("\n");
       return;
     }
+    if (key.tab) {
+      const completed = completeSlashCommand(current.composer.value, current.composer.cursor);
+      if (completed.value !== current.composer.value) {
+        dispatch({ type: "composer/set", value: completed.value, cursor: completed.cursor });
+      }
+      return;
+    }
     if (key.return) {
       submitComposer();
       return;
@@ -776,43 +788,45 @@ export function App(props: AppProps): ReactNode {
   const overlayNode = renderOverlay();
 
   return (
-    <Box flexDirection="column" width={width} height={height}>
-      <Header theme={theme} state={state} version={VERSION} width={width} />
-      {overlayNode === undefined ? (
-        <Conversation
+    <Box flexDirection="column" width={terminalWidth} height={height} alignItems="center">
+      <Box flexDirection="column" width={width} height={height}>
+        <Header theme={theme} state={state} version={VERSION} width={width} />
+        {overlayNode === undefined ? (
+          <Conversation
+            theme={theme}
+            entries={state.conversation}
+            height={conversationHeight}
+            scrollOffset={state.scrollOffset}
+            emptyHint={
+              state.connection === undefined
+                ? "No provider is connected. Use /provider to connect OpenRouter or an OpenAI-compatible endpoint."
+                : state.model === undefined
+                  ? "Connected. Use /model to select a model from the live catalog."
+                  : "Ready. Type a prompt, or / for commands."
+            }
+          />
+        ) : (
+          <Box
+            flexDirection="column"
+            flexGrow={1}
+            flexShrink={1}
+            minHeight={0}
+            height={conversationHeight}
+            paddingX={1}
+            overflow="hidden"
+          >
+            {overlayNode}
+          </Box>
+        )}
+        <Notices theme={theme} notices={state.notices} width={width} />
+        <Composer
           theme={theme}
-          entries={state.conversation}
-          height={conversationHeight}
-          scrollOffset={state.scrollOffset}
-          emptyHint={
-            state.connection === undefined
-              ? "No provider is connected. Use /provider to connect OpenRouter or an OpenAI-compatible endpoint."
-              : state.model === undefined
-                ? "Connected. Use /model to select a model from the live catalog."
-                : "Ready. Type a prompt, or / for commands."
-          }
+          composer={state.composer}
+          disabled={state.runStatus !== "idle"}
+          width={width}
         />
-      ) : (
-        <Box
-          flexDirection="column"
-          flexGrow={1}
-          flexShrink={1}
-          minHeight={0}
-          height={conversationHeight}
-          paddingX={1}
-          overflow="hidden"
-        >
-          {overlayNode}
-        </Box>
-      )}
-      <Notices theme={theme} notices={state.notices} width={width} />
-      <Composer
-        theme={theme}
-        composer={state.composer}
-        disabled={state.runStatus !== "idle"}
-        width={width}
-      />
-      <Footer theme={theme} state={state} width={width} />
+        <Footer theme={theme} state={state} width={width} />
+      </Box>
     </Box>
   );
 
@@ -883,12 +897,10 @@ export function App(props: AppProps): ReactNode {
 
 /** Describes the exact external endpoint the form will contact, so network use is never implicit. */
 export function providerDisclosure(form: ProviderFormState): string {
-  const raw =
-    form.baseUrl.trim().length > 0
-      ? form.baseUrl.trim()
-      : form.kind === "openrouter"
-        ? OPENROUTER_DEFAULT_BASE_URL
-        : "";
+  if (form.kind === "openrouter") {
+    return `connecting will contact ${OPENROUTER_DEFAULT_BASE_URL} using the built-in OPENROUTER_API_KEY reference`;
+  }
+  const raw = form.baseUrl.trim().length > 0 ? form.baseUrl.trim() : "";
   if (raw.length === 0) return "a base URL is required before any request is made";
   try {
     const url = new URL(raw);

packages/cli/src/tui/commands.ts

@@ -76,6 +76,31 @@ export function discoverSlashCommands(input: string): readonly SlashCommand[] {
   return SLASH_COMMANDS.filter((command) => command.name.startsWith(lowered));
 }
 
+/**
+ * Completes only an unambiguous command prefix; Tab never submits the composer.
+ *
+ * The result reports the matched command so the caller (and tests) can confirm exactly which command
+ * a completion expanded to. When zero or multiple commands match the prefix, the input is returned
+ * unchanged and no `command` is reported, so Tab is a no-op and the discovery list stays the only
+ * guidance.
+ */
+export function completeSlashCommand(
+  input: string,
+  cursor: number,
+): Readonly<{ value: string; cursor: number; command?: SlashCommand }> {
+  const safeCursor = Math.min(Math.max(cursor, 0), input.length);
+  const beforeCursor = input.slice(0, safeCursor);
+  if (!beforeCursor.startsWith("/") || /\s/u.test(beforeCursor)) {
+    return { value: input, cursor: safeCursor };
+  }
+  const matches = discoverSlashCommands(beforeCursor);
+  if (matches.length !== 1) return { value: input, cursor: safeCursor };
+  const command = matches[0];
+  if (command === undefined) return { value: input, cursor: safeCursor };
+  const value = command.name + input.slice(safeCursor);
+  return { value, cursor: command.name.length, command };
+}
+
 export interface ParsedSlashCommand {
   readonly name: string;
   readonly argument: string;

packages/cli/src/tui/components/Composer.tsx

@@ -43,7 +43,7 @@ export function Composer(props: {
           {props.composer.value.length === 0 ? (
             <Text {...(muted === undefined ? {} : { color: muted })}>
               {props.disabled
-                ? "Streaming\u2026 Ctrl+C cancels"
+                ? "Streaming\u2026 Ctrl+X cancels"
                 : "Ask a question, or type / for commands"}
             </Text>
           ) : (

packages/cli/src/tui/components/Conversation.tsx

@@ -218,7 +218,7 @@ export function Conversation(props: {
   const muted = themeColor(props.theme, "muted");
   if (props.entries.length === 0) {
     return (
-      <Box flexDirection="column" flexGrow={1} paddingX={1}>
+      <Box flexDirection="column" flexGrow={1} justifyContent="center" paddingX={1}>
         <Text {...(muted === undefined ? {} : { color: muted })}>{props.emptyHint}</Text>
       </Box>
     );

packages/cli/src/tui/components/Footer.tsx

@@ -62,7 +62,7 @@ export function Footer(props: {
       </Box>
       <Box>
         <Text {...(muted === undefined ? {} : { color: muted })}>
-          {`workspace ${state.workspaceRoot}`}
+          {`workspace ${state.workspaceRoot}  \u00b7  Ctrl+X cancel  \u00b7  /exit quit`}
         </Text>
       </Box>
     </Box>