jeo-code 0.1.0 → 0.4.4

package/src/tui/components/provider-picker.ts

@@ -1,11 +1,12 @@
 /**
  * Provider picker — turns live provider readiness into a `SelectList` for the
- * TUI `/provider` and `joc setup` flows. Ready providers are listed first and
+ * TUI `/provider` and `jeo setup` flows. Ready providers are listed first and
  * the recommended choice is the first ready provider. Pure builders.
  */
 import { SelectList, renderSelectList, type SelectItem, type RenderSelectOptions } from "./select-list";
 import type { ProviderStatus } from "../../ai/provider-status";
 import type { ProviderName } from "../../ai/types";
+import { companyLabel } from "../../ai/model-catalog";
 
 /** Right-aligned hint for a provider row: credential kind + base URL + readiness. */
 export function providerHint(s: ProviderStatus, unicode = true): string {
@@ -20,7 +21,7 @@ export function buildProviderChoices(statuses: ProviderStatus[], unicode = true)
   const sorted = [...statuses].sort((a, b) => (a.ready === b.ready ? 0 : a.ready ? -1 : 1));
   return sorted.map(s => ({
     value: s.name,
-    label: s.name,
+    label: `${s.name} (${companyLabel(s.name)})`,
     group: s.ready ? "ready" : "needs setup",
     hint: providerHint(s, unicode),
   }));

package/src/tui/components/section.ts

@@ -0,0 +1,70 @@
+/**
+ * Section layout primitives — a small shadcn/ui-inspired design-token layer for the
+ * terminal TUI. shadcn's discipline is *consistent vertical rhythm* (`space-y-*`) and
+ * *card grouping* with a muted header (`CardHeader` + `text-muted-foreground`). The
+ * gjc reference TUI does the same with `├─ Output ─┤` style dividers between a tool
+ * block and its output.
+ *
+ * These helpers give the live frame one shared spacing token (`SECTION_GAP`) and a
+ * muted card-header divider (`sectionLabel`) so the in-frame stages (plan / activity /
+ * output) read as distinct, evenly-spaced cards instead of one cramped wall of lines.
+ */
+import chalk from "chalk";
+import { visibleWidth } from "./color";
+
+/** Vertical rhythm: blank lines inserted between adjacent sections (shadcn `space-y`). */
+export const SECTION_GAP = 1;
+
+export interface SectionLabelOpts {
+  color?: boolean;
+  unicode?: boolean;
+}
+
+/**
+ * A muted card-header divider spanning `width` columns: `── Plan ─────────────`.
+ * Mirrors shadcn's `CardHeader` (a muted title) and gjc's `├─ Output ─┤` separators,
+ * so each stage block is announced by a low-contrast label rather than running into
+ * the previous block.
+ */
+export function sectionLabel(title: string, width: number, opts: SectionLabelOpts = {}): string {
+  const unicode = opts.unicode !== false;
+  const dash = unicode ? "─" : "-";
+  const head = `${dash.repeat(2)} ${title.trim()} `;
+  const headW = visibleWidth(head);
+  const fill = Math.max(0, Math.trunc(width) - headW);
+  const line = head + dash.repeat(fill);
+  return opts.color !== false ? chalk.dim(line) : line;
+}
+
+export interface Section {
+  /** Optional muted card header. Omit for self-headed blocks (plan/forge already label themselves). */
+  title?: string;
+  lines: string[];
+}
+
+export interface StackOptions {
+  width: number;
+  gap?: number;
+  color?: boolean;
+  unicode?: boolean;
+}
+
+/**
+ * Stack sections with a consistent blank-line rhythm. Empty sections are dropped, a
+ * titled section is prefixed with its muted `sectionLabel`, and exactly `gap` blank
+ * lines separate adjacent (non-empty) sections. Returns a flat line array ready to
+ * drop into the frame.
+ */
+export function stackSections(sections: Section[], opts: StackOptions): string[] {
+  const gap = Math.max(0, opts.gap ?? SECTION_GAP);
+  const out: string[] = [];
+  for (const section of sections) {
+    if (!section.lines.length) continue;
+    if (out.length) for (let i = 0; i < gap; i++) out.push("");
+    if (section.title) {
+      out.push(sectionLabel(section.title, opts.width, { color: opts.color, unicode: opts.unicode }));
+    }
+    for (const line of section.lines) out.push(line);
+  }
+  return out;
+}

package/src/tui/components/select-list.ts

@@ -10,6 +10,7 @@
 import chalk from "chalk";
 import { padLineTo } from "./layout";
 import { visibleWidth } from "./color";
+import { truncate as truncateAnsi } from "../terminal";
 
 export interface SelectItem<T> {
   value: T;
@@ -20,6 +21,12 @@ export interface SelectItem<T> {
   disabled?: boolean;
   /** Optional right-aligned hint/badge (e.g. "✓ ready · 200k"). */
   hint?: string;
+  /** When true, `hint` is already styled and should not be wrapped in gray. */
+  hintRaw?: boolean;
+  /** Tree indentation depth for nested/sub-list choices. */
+  depth?: number;
+  /** Tree connector for nested rows; defaults to "mid" when depth > 0. */
+  branch?: "mid" | "last";
 }
 
 export class SelectList<T> {
@@ -145,11 +152,17 @@ export function renderSelectList<T>(list: SelectList<T>, opts: RenderSelectOptio
   const tint = (s: string, fn: (x: string) => string) => (color ? fn(s) : s);
 
   const out: string[] = [];
-  if (opts.title) out.push(tint(opts.title, chalk.bold));
+  if (opts.title) {
+    for (const rawTitle of opts.title.split("\n")) {
+      const title = rawTitle ? tint(rawTitle, chalk.bold) : "";
+      out.push(cols ? clampToCols(title, cols) : title);
+    }
+  }
 
   const items = list.visible();
   if (items.length === 0) {
-    out.push(tint("  (no matches)", chalk.gray));
+    const empty = tint("  (no matches)", chalk.gray);
+    out.push(cols ? clampToCols(empty, cols) : empty);
   } else {
     const cur = list.cursorIndex();
     // Scrolling window centered-ish on the cursor.
@@ -157,20 +170,25 @@ export function renderSelectList<T>(list: SelectList<T>, opts: RenderSelectOptio
     start = Math.min(start, Math.max(0, items.length - rows));
     const end = Math.min(items.length, start + rows);
 
-    if (start > 0) out.push(tint(`  \u2191 ${start} more`, chalk.gray));
+    if (start > 0) {
+      const more = tint(`  \u2191 ${start} more`, chalk.gray);
+      out.push(cols ? clampToCols(more, cols) : more);
+    }
     let lastGroup: string | undefined;
     for (let i = start; i < end; i++) {
       const it = items[i]!;
       if (it.group && it.group !== lastGroup) {
-        out.push(tint(`  ${it.group}`, chalk.gray));
+        const group = tint(`  ${it.group}`, chalk.gray);
+        out.push(cols ? clampToCols(group, cols) : group);
         lastGroup = it.group;
       }
       const isCur = i === cur;
       const marker = isCur ? tint(pointer, chalk.cyan) : " ";
-      let label = it.disabled ? tint(it.label, chalk.gray) : isCur ? tint(it.label, chalk.cyan.bold) : it.label;
+      const prefix = treePrefix(it, { unicode });
+      let label = it.disabled ? tint(`${prefix}${it.label}`, chalk.gray) : isCur ? tint(`${prefix}${it.label}`, chalk.cyan.bold) : `${prefix}${it.label}`;
       let line = `${marker} ${label}`;
       if (it.hint) {
-        const hint = tint(it.hint, chalk.gray);
+        const hint = it.hintRaw ? it.hint : tint(it.hint, chalk.gray);
         if (cols) {
           // right-align the hint within cols
           const used = visibleWidth(line) + visibleWidth(hint) + 1;
@@ -182,18 +200,30 @@ export function renderSelectList<T>(list: SelectList<T>, opts: RenderSelectOptio
       }
       out.push(cols ? clampToCols(line, cols) : line);
     }
-    if (end < items.length) out.push(tint(`  \u2193 ${items.length - end} more`, chalk.gray));
+    if (end < items.length) {
+      const more = tint(`  \u2193 ${items.length - end} more`, chalk.gray);
+      out.push(cols ? clampToCols(more, cols) : more);
+    }
   }
 
   const q = list.filter();
   const filterPart = q ? `filter: ${q}` : "type to filter";
   const keys = unicode ? "\u2191/\u2193 move \u00b7 enter select \u00b7 esc cancel" : "up/down move . enter select . esc cancel";
-  out.push(tint(`  ${filterPart}  \u2014  ${keys}`, chalk.gray));
+  const footer = tint(`  ${filterPart}  \u2014  ${keys}`, chalk.gray);
+  out.push(cols ? clampToCols(footer, cols) : footer);
   return out;
 }
 
-/** Fit a (possibly colored) line to cols by visible width, preserving the right hint. */
 function clampToCols(line: string, cols: number): string {
   if (visibleWidth(line) <= cols) return padLineTo(line, cols, "left");
-  return line; // caller-built hint lines are already gap-fitted; leave longer plain lines to the renderer truncate
+  const cut = truncateAnsi(line, cols);
+  return visibleWidth(cut) <= cols ? padLineTo(cut, cols, "left") : cut;
+}
+
+function treePrefix<T>(item: SelectItem<T>, opts: { unicode: boolean }): string {
+  const depth = Math.max(0, item.depth ?? 0);
+  if (depth <= 0) return "";
+  const pad = "  ".repeat(Math.max(0, depth - 1));
+  if (!opts.unicode) return `${pad}${item.branch === "last" ? "`-" : "|-"} `;
+  return `${pad}${item.branch === "last" ? "└─" : "├─"} `;
 }

package/src/tui/components/skill-picker.ts

@@ -0,0 +1,25 @@
+import type { SkillDoc } from "../../skills/catalog";
+import { skillSlashAliases } from "../../skills/catalog";
+import { SelectList, renderSelectList, type RenderSelectOptions, type SelectItem } from "./select-list";
+
+function skillHint(skill: SkillDoc): string {
+  const aliases = skillSlashAliases(skill);
+  return aliases.length ? aliases.slice(0, 3).join(" ") : skill.command;
+}
+
+export function buildSkillChoices(skills: SkillDoc[]): SelectItem<SkillDoc>[] {
+  return skills.map(skill => ({
+    value: skill,
+    label: skill.name,
+    group: "skills",
+    hint: skillHint(skill),
+  }));
+}
+
+export function skillPicker(skills: SkillDoc[]): SelectList<SkillDoc> {
+  return new SelectList(buildSkillChoices(skills));
+}
+
+export function renderSkillPicker(list: SelectList<SkillDoc>, opts: RenderSelectOptions = {}): string[] {
+  return renderSelectList(list, { title: "Select a skill", rows: 12, ...opts });
+}

package/src/tui/components/slash.ts

@@ -1,34 +1,257 @@
 /** Slash-command palette/autocomplete for the interactive REPL (TUI M3). */
+import chalk from "chalk";
 
-export const SLASH_COMMANDS = [
-  "/help",
-  "/clear",
-  "/compact",
-  "/model",
-  "/models",
-  "/provider",
-  "/agents",
-  "/config",
-  "/roles",
-  "/thinking",
-  "/view",
-  "/diff",
-  "/find",
-  "/search",
-  "/sessions",
-  "/evolve",
-  "/exit",
-  "/quit",
+/** Order-preserving subsequence test: every char of `needle` appears in `hay`
+ *  left-to-right (gjc-style fuzzy match, e.g. "expt" ⊑ "export"). */
+function subsequence(needle: string, hay: string): boolean {
+  if (needle === "") return true;
+  let i = 0;
+  for (let j = 0; j < hay.length && i < needle.length; j++) {
+    if (hay[j] === needle[i]) i++;
+  }
+  return i === needle.length;
+}
+
+export interface SlashCommandInfo {
+  command: string;
+  usage: string;
+  description: string;
+  group: "session" | "models" | "subagents" | "code" | "skills" | "system";
+}
+
+export const SLASH_COMMAND_DETAILS: readonly SlashCommandInfo[] = [
+  { command: "/help", usage: "/help", description: "Show this help message", group: "system" },
+  { command: "/clear", usage: "/clear", description: "Clear conversation history (keeps system prompt)", group: "session" },
+  { command: "/new", usage: "/new", description: "Start a new session (fresh history + new session id)", group: "session" },
+  { command: "/drop", usage: "/drop", description: "Delete the current session and start a new one", group: "session" },
+  { command: "/session", usage: "/session [info|delete]", description: "Show current session info, or delete it", group: "session" },
+  { command: "/rename", usage: "/rename <title>", description: "Rename the current session", group: "session" },
+  { command: "/resume", usage: "/resume [id]", description: "Resume a saved session in this REPL", group: "session" },
+  { command: "/retry", usage: "/retry", description: "Retry the last request", group: "session" },
+  { command: "/history", usage: "/history [n|all]", description: "Re-print the worked turn history (prompts, tool steps, replies) into scrollback", group: "session" },
+  { command: "/export", usage: "/export [path] [json]", description: "Export the session transcript to a file", group: "session" },
+  { command: "/dump", usage: "/dump", description: "Copy the session transcript to the clipboard", group: "session" },
+  { command: "/btw", usage: "/btw <question>", description: "Ask an ephemeral side question (history untouched)", group: "session" },
+  { command: "/compact", usage: "/compact", description: "Summarize older turns to free context", group: "session" },
+  { command: "/model", usage: "/model [id|#N|save|thinking <level>|subagent <role> <model|#N|thinking L>]", description: "Show/switch model; picker can apply to default or any subagent role and set thinking", group: "models" },
+  { command: "/fast", usage: "/fast [on|off|status]", description: "Toggle fast thinking mode when the active model supports it", group: "models" },
+  { command: "/provider", usage: "/provider [name] [model|#N]", description: "Credentials, switch provider, set model; `login <name>` starts OAuth", group: "models" },
+  { command: "/login", usage: "/login [provider]", description: "OAuth login (alias of /provider login)", group: "models" },
+  { command: "/logout", usage: "/logout <anthropic|openai|gemini|antigravity>", description: "Remove the stored OAuth token for a provider", group: "models" },
+  { command: "/roles", usage: "/roles [tier model]", description: "Show or set model role tiers (smol/slow/plan)", group: "models" },
+  { command: "/thinking", usage: "/thinking [level]", description: "Show or set thinking budget (minimal/low/medium/high/xhigh)", group: "models" },
+  { command: "/agents", usage: "/agents [edit|role] [model|#N|thinking L|maxSteps N|reset]", description: "List subagent roles; use /agents edit for the interactive picker or pin role model/settings", group: "subagents" },
+  { command: "/subagent", usage: "/subagent [role]", description: "Show the current subagent composition (per-role model · thinking · steps); alias of /agents", group: "subagents" },
+  { command: "/view", usage: "/view <file> [a-b]", description: "Render a file with line numbers + light highlight", group: "code" },
+  { command: "/diff", usage: "/diff [file]", description: "Render `git diff` with +/- coloring", group: "code" },
+  { command: "/find", usage: "/find <glob>", description: "List files matching a glob", group: "code" },
+  { command: "/search", usage: "/search <pat> [glob]", description: "Search the repo for a pattern", group: "code" },
+  { command: "/skill", usage: "/skill [name [intent]]", description: "List, show, or run a workflow skill", group: "skills" },
+  { command: "/skill:", usage: "/skill:<name> [intent]", description: "Run a workflow skill by GJC-style entrypoint", group: "skills" },
+  { command: "/sessions", usage: "/sessions", description: "List saved sessions", group: "session" },
+  { command: "/usage", usage: "/usage", description: "Show cumulative token usage for this session", group: "system" },
+  { command: "/context", usage: "/context", description: "Show context token usage breakdown", group: "system" },
+  { command: "/tools", usage: "/tools", description: "Show the tools currently visible to the agent", group: "system" },
+  { command: "/hotkeys", usage: "/hotkeys", description: "Show keyboard shortcuts", group: "system" },
+  { command: "/theme", usage: "/theme [name]", description: "Show or set the TUI theme (cosmic/matrix/solar/mono)", group: "system" },
+  { command: "/settings", usage: "/settings", description: "Show effective runtime configuration (alias of /config)", group: "system" },
+  { command: "/evolve", usage: "/evolve", description: "Simulate and view the agent's evolutionary gallery", group: "system" },
+  { command: "/config", usage: "/config", description: "Show the effective runtime configuration", group: "system" },
+  { command: "/exit", usage: "/exit", description: "Exit the agent", group: "system" },
+  { command: "/quit", usage: "/quit", description: "Exit the agent", group: "system" },
 ];
 
-/** Return the slash commands that prefix-match `input` (case-insensitive). Empty for non-slash input. */
+export const SLASH_COMMANDS = SLASH_COMMAND_DETAILS.map(c => c.command);
+
+export function mergeSlashCommandDetails(extra: readonly SlashCommandInfo[] = []): SlashCommandInfo[] {
+  const byCommand = new Map<string, SlashCommandInfo>();
+  for (const d of [...SLASH_COMMAND_DETAILS, ...extra]) byCommand.set(d.command, d);
+  return [...byCommand.values()];
+}
+
+/** Return the slash commands that match `input` (case-insensitive). Prefix matches
+ *  come first; a fuzzy subsequence fallback (gjc-style, e.g. `/expt` → `/export`)
+ *  follows so typos / abbreviations still surface a command. A bare `/` lists every
+ *  command. Empty for non-slash input. */
 export function matchSlash(input: string, commands: string[] = SLASH_COMMANDS): string[] {
   if (!input.startsWith("/")) return [];
   const q = input.toLowerCase();
-  return commands.filter(c => c.startsWith(q));
+  const body = q.slice(1);
+  if (body === "") return [...commands];
+  const starts = commands.filter(c => c.toLowerCase().startsWith(q));
+  const fuzzy = commands.filter(c => !starts.includes(c) && subsequence(body, c.slice(1).toLowerCase()));
+  return [...starts, ...fuzzy];
 }
 
 /** True when `input` looks like a slash command (starts with "/" and has no space). */
 export function isSlashAttempt(input: string): boolean {
   return input.startsWith("/") && !input.slice(1).includes(" ");
 }
+
+const GROUP_LABELS: Record<SlashCommandInfo["group"], string> = {
+  session: "Session",
+  models: "Models / Providers",
+  subagents: "Subagents",
+  code: "Code tools",
+  skills: "Skills",
+  system: "System",
+};
+
+const GROUP_ORDER: readonly SlashCommandInfo["group"][] = ["models", "subagents", "code", "skills", "session", "system"];
+/** Format a visible command palette for `/`, `/help`, or a partial slash prefix. */
+export function formatSlashCommandList(input = "/", extra: readonly SlashCommandInfo[] = []): string[] {
+  const details = mergeSlashCommandDetails(extra);
+  const commands = details.map(c => c.command);
+  const query = input === "/?" ? "/" : input;
+  const matches = matchSlash(query, commands);
+  if (matches.length === 0) return [`Unknown command '${input}'. Try /help.`];
+  const wanted = new Set(matches);
+  const rows = details.filter(c => wanted.has(c.command));
+  const usageWidth = Math.max(...rows.map(c => c.usage.length), 6);
+  const title = query === "/" || query === "/help"
+    ? "Slash Commands:"
+    : `Slash Commands matching '${query}':`;
+  const lines = [title];
+  for (const group of GROUP_ORDER) {
+    const groupRows = rows.filter(c => c.group === group);
+    if (groupRows.length === 0) continue;
+    lines.push(`  ${GROUP_LABELS[group]}:`);
+    for (const c of groupRows) lines.push(`    ${c.usage.padEnd(usageWidth)} - ${c.description}`);
+  }
+  lines.push("Tip: type a slash prefix like '/mod' and press Tab to autocomplete.");
+  return lines;
+}
+
+export interface SkillPreviewItem {
+  name: string;
+  summary?: string;
+}
+
+function renderPreviewRows(
+  rows: { usage: string; description: string }[],
+  max: number,
+  selected: number,
+): string[] {
+  const fmt = (r: { usage: string; description: string }, on: boolean): string => {
+    const head = on ? chalk.cyan(`▸ ${r.usage}`) : `  ${r.usage}`;
+    return `${head}  ${chalk.dim(r.description)}`;
+  };
+  const n = rows.length;
+  if (n === 0) return [];
+  // HARD row-budget contract: the returned lines NEVER exceed `max` — the caller
+  // reserves exactly that many footer rows, and one extra line shifts the input
+  // box / caret math (the "broken input box" corruption). When the list overflows,
+  // up to two slots are spent on ↑/↓ "more" markers INSIDE the budget.
+  const overflowing = n > max;
+  const slots = overflowing ? Math.max(1, max - 2) : n;
+  const sel = selected < 0 ? 0 : Math.min(selected, n - 1);
+  const start = Math.max(0, Math.min(sel - Math.floor(slots / 2), n - slots));
+  const lines: string[] = [];
+  // Position counter (1-based) of the selected row within the full match list,
+  // shown on a "more" marker so an overflowing list reads like gjc's `(3/33)`.
+  // When nothing is selected, the window starts at the top → `(1/total)`.
+  const counter = `(${sel + 1}/${n})`;
+  const below = n - (start + slots);
+  if (start > 0) lines.push(below > 0 ? `  ↑ ${start} more` : `  ↑ ${start} more   ${counter}`);
+  for (let i = start; i < start + slots && i < n; i++) lines.push(fmt(rows[i]!, i === selected));
+  if (below > 0) lines.push(`  ↓ ${below} more   ${counter}`);
+  return lines;
+}
+
+/** Skills matching a `$keyword` probe (no space yet). Prefix matches come first,
+ *  then a fuzzy subsequence fallback (gjc-style, e.g. `$dintv` → `$deep-interview`).
+ *  A bare `$` lists every skill. */
+function dollarMatches(trimmed: string, skills: readonly SkillPreviewItem[]): SkillPreviewItem[] {
+  const prefix = trimmed.slice(1).toLowerCase();
+  if (prefix === "") return [...skills];
+  const starts = skills.filter(s => s.name.toLowerCase().startsWith(prefix));
+  const fuzzy = skills.filter(s => !starts.includes(s) && subsequence(prefix, s.name.toLowerCase()));
+  return [...starts, ...fuzzy];
+}
+
+/** The `/command` or `$skill` token actively being typed, ANYWHERE in the line. */
+export interface ActiveTrigger {
+  kind: "/" | "$";
+  /** The trigger token itself (`/mo`, `$te`, bare `/`, bare `$`, …). */
+  token: string;
+  /** Index of the token's first character in `line` — for in-place replacement. */
+  start: number;
+}
+
+/**
+ * Find the trigger token the user is typing, regardless of where it sits in the
+ * line (mention-style): the LAST whitespace-delimited word, when it starts with
+ * `/` or `$` and the caret is still on it (the word ends the line — no space
+ * after it yet). `"fix the bug /mo"` → `/mo`, `"explain $te"` → `$te`,
+ * `"/model"` → `/model`. No trigger once a space follows (`"/model gpt"` →
+ * the active word is `gpt`), and never for `/`/`$` glued inside a word
+ * (`"src/cli"`, `"FOO$BAR"` — paths/vars stay popup-free).
+ */
+export function activeTriggerToken(line: string): ActiveTrigger | undefined {
+  const m = /(^|\s)([/$]\S*)$/.exec(line);
+  if (!m) return undefined;
+  const token = m[2]!;
+  return { kind: token[0] as "/" | "$", token, start: (m.index ?? 0) + m[1]!.length };
+}
+
+/**
+ * Compact live preview shown beneath the input box while a `/command` or
+ * `$skill` keyword is being typed — at any position in the line (mention-style,
+ * gjc/Codex parity): `"do X then /mo"` previews commands, `"…then $te"`
+ * previews skills. Returns matching usages + descriptions, capped, or [] when
+ * no trigger token is active (finished words stay popup-free). Match ORDER is
+ * preserved from matchSlash/dollarMatches so prefix hits sit above fuzzy hits.
+ */
+export function formatSlashPreview(
+  line: string,
+  max = 6,
+  selected = -1,
+  extra: readonly SlashCommandInfo[] = [],
+  skills: readonly SkillPreviewItem[] = [],
+): string[] {
+  const trigger = activeTriggerToken(line);
+  if (!trigger) return [];
+  if (trigger.kind === "$") {
+    const rows = dollarMatches(trigger.token, skills).map(s => ({
+      usage: `$${s.name} [intent]`,
+      description: s.summary?.trim() || "run this skill directly",
+    }));
+    return renderPreviewRows(rows, max, selected);
+  }
+  const details = mergeSlashCommandDetails(extra);
+  const byCommand = new Map(details.map(c => [c.command, c] as const));
+  const rows = matchSlash(trigger.token, details.map(c => c.command))
+    .map(cmd => byCommand.get(cmd))
+    .filter((c): c is SlashCommandInfo => Boolean(c));
+  if (rows.length === 0) return [];
+  return renderPreviewRows(rows, max, selected);
+}
+
+/** The matching command names for an active `/cmd` or `$name` trigger token
+ *  (anywhere in the line), in display order (prefix-first, then fuzzy). */
+export function slashPreviewMatches(
+  line: string,
+  extra: readonly SlashCommandInfo[] = [],
+  skills: readonly SkillPreviewItem[] = [],
+): string[] {
+  const trigger = activeTriggerToken(line);
+  if (!trigger) return [];
+  if (trigger.kind === "$") return dollarMatches(trigger.token, skills).map(s => `$${s.name}`);
+  const details = mergeSlashCommandDetails(extra);
+  return matchSlash(trigger.token, details.map(c => c.command));
+}
+
+/**
+ * Tab-completion target for the live `/`·`$` popup: the highlighted row when the
+ * user arrowed to one, else the TOP match (prefix hits sort first). Returns the
+ * completed line WITH a trailing space — arguments follow, and the space closes
+ * the keyword popup (a space means a real invocation is being typed). Pure.
+ */
+export function tabCompleteSelection(line: string, matches: readonly string[], selected: number): string | undefined {
+  if (matches.length === 0) return undefined;
+  const trigger = activeTriggerToken(line);
+  if (!trigger) return undefined;
+  const pick = matches[selected >= 0 && selected < matches.length ? selected : 0]!;
+  return line.slice(0, trigger.start) + `${pick} `;
+}
+