ModApi: UI Interactions & Dialogs

Feature Description

Disclaimer: This message was synthesized by an AI from a long, unstructured Markdown file of notes accumulated while building real mods. Use cases have been kept intentionally simple and generic. If anything seems off or incoherent, feel free to ask for clarification.

1. cmd.ui.spinner() — native spinners

Problem: There's no way to show a loading indicator during async work. Packages like ora don't work inside the harness sandbox.

Use case: A mod that does any async operation at startup (network call, file scan, etc.) has no way to tell the user it's working. A native spinner is the most basic UX expectation.

const spinner = cmd.ui.spinner("Loading...");
await task();
spinner.success("Done!");

---

2. cmd.ui.progress() — progress bar for long operations

Problem: There's no way to show progress during a multi-step or time-consuming operation. The user has no feedback while the mod is working.

Use case: Any mod that processes multiple items sequentially should be able to show a progress bar rather than leaving the user wondering if it's stuck.

const bar = cmd.ui.progress({ total: 100, label: 'Processing...' });
bar.update(45);
bar.complete('Done!');

---

3. cmd.ui.menu() — interactive select with groups and search

Problem: cmd.ui.select() is basic — no groups, no filtering, no advanced keyboard navigation.

Use case: Any mod presenting a long list of options would benefit from a searchable, keyboard-navigable menu rather than a flat list the user has to scroll through.

---

4. cmd.ui.confirm() with custom button labels

Problem: cmd.ui.confirm() always shows "OK" and "Cancel". There's no way to customize the button labels.

Use case: Any confirmation that involves a specific action ("Delete", "Overwrite", "Enable") should label its buttons accordingly rather than relying on the generic "OK".

cmd.ui.confirm({
  title: 'Overwrite this file?',
  labels: { confirm: 'Overwrite', cancel: 'Keep existing' },
});

---

5. ANSI / color support in dialogs (confirm, select, notify)

Problem: Dialog text in cmd.ui.confirm(), cmd.ui.select(), and cmd.ui.notify() is rendered as plain text — ANSI escape codes are not parsed.

Use case: A confirmation dialog that visually distinguishes a dangerous action (red/bold title, colored options) is much clearer than a plain-text prompt. Color in dialogs is a basic UX expectation.

---

6. cmd.ui.push() — more prominent push notification

Problem: cmd.ui.notify() adds a message to the feed, which gets lost in the scroll. There's no way to attract the user's attention more visibly.

Use case: A mod that needs to alert the user about something important should have a way to show a more prominent notification that doesn't get buried in feed history.

cmd.ui.push({ title: 'Threshold reached', body: 'The limit has been exceeded', level: 'warning' });

---

PART 2

5. Animations — Smooth visual transitions

Problem: The only visual feedback during async operations is a text spinner. There are no transitions, no gradients, no animated indicators. The terminal feels static and lifeless compared to modern TUI applications.

Use case: A mod that tracks live data (prices, counters, status) should be able to animate value changes — smooth color transitions, pulse effects on threshold alerts, or animated progress indicators. A mod that displays a loading state should show a smooth spinner, not a static ... text.

cmd.ui.animate({
  target: statusBadge,
  from: { color: 'yellow' },
  to: { color: 'green' },
  duration: 300,
});

References: ChromaCat (12 pattern types — plasma, aurora, fire, wave, spiral, ripple — 40+ built-in themes — cyberpunk, nebula, neon, retrowave — 60fps animations with interactive controls), terminui (animated spinners, progress transitions with easing), Ink (animated components via React state — smooth re-renders), SilkCircuit (design language with neon, soft, glow, vibrant styles — 20+ tools). The TUI Renaissance article (2026): "Smooth animations breathe life into your terminal with fluid color transitions."

6. Tooltips / Popovers — Contextual information

Problem: There is no way to show contextual information on hover or focus. If a mod wants to explain what a status badge means or show details about a metric, it must dump the info into the feed, polluting the conversation history.

Use case: A mod that displays a cost summary badge in the footer should show detailed breakdown (input tokens, output tokens, cache savings) when the user hovers over it, without printing anything in the feed.

cmd.ui.tooltip({
  target: costBadge,
  content: ['Input: 12,400 tokens', 'Output: 3,200 tokens', 'Cache saved: $0.42'],
});

References: OpenTUI (console overlay for contextual info — built into the framework), Ink UI (interactive components with focus states and hover), terminui (popover-like widgets with positioning), Ratatui (popup/modal overlays). Modern TUIs treat contextual info as a first-class concern, not an afterthought.

Use Case

No response

Additional Context

No response

How important is this to you?

None

該 issue 沒有指定檔案、測試或實作入口。首先，將所要求的 spinner、進度、選單、確認、通知、動畫和 tooltip 工作拆分為範圍明確的提案，然後在實作之前，為每個提案定義受支援的終端行為和測試。