# 画面設計書 25-ホーム

## 概要

本ドキュメントは、OpenCode TUI（ターミナルUI）アプリケーションにおけるホーム画面の設計を定義する。CLIターミナル上で動作するインタラクティブなホーム画面であり、プロンプト入力、MCPサーバー状態表示、Tips表示などの機能を提供する。

### 本画面の処理概要

この画面は、OpenCode TUIアプリケーションの起点となるホーム画面である。ユーザーがAIに対する指示を入力するプロンプトを中心に、MCPサーバーの接続状態、ヒントTips、カレントディレクトリなどの情報を表示する。

**業務上の目的・背景**：ターミナル上でAIコーディングエージェントを利用する際、シンプルかつ直感的なインターフェースが重要である。本画面は、ユーザーが即座にAIへの指示を開始できるよう設計されており、同時にMCPサーバーの状態やシステム情報を把握できるようにしている。

**画面へのアクセス方法**：
1. `opencode`コマンドを実行してTUIを起動
2. セッション画面から戻る操作を実行

**主要な操作・処理内容**：
1. OpenCodeロゴの表示
2. プロンプト入力フィールドの提供
3. MCPサーバー接続状態の表示（接続数、エラー有無）
4. Tips（使い方ヒント）の表示
5. カレントディレクトリの表示
6. アプリケーションバージョンの表示
7. コマンドダイアログによるスキル登録・実行

**画面遷移**：
- この画面から遷移可能：セッション画面（プロンプト送信後）
- この画面に遷移してくる：TUI起動時、セッション画面からの戻り

**権限による表示制御**：なし。TUIを起動できるユーザーはすべての機能を利用可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 35 | MCPサーバー管理 | 主機能 | MCPサーバー接続状態の表示、接続数カウント |
| 50 | スキル検出・実行 | 補助機能 | コマンドダイアログによるスキル登録・実行 |
| 56 | 国際化 | 補助機能 | TUIテキストの多言語対応（Locale.pluralize） |

## 画面種別

ホーム（初期画面）

## URL/ルーティング

- ルート: `home`（TUI内部ルーティング）
- ファイル: `packages/opencode/src/cli/cmd/tui/routes/home.tsx`

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| プロンプト入力 | string | いいえ | AIへの指示テキスト |
| 添付ファイル | File[] | いいえ | プロンプトに添付するファイル |

### 初期データ（ルートデータ）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| initialPrompt | PromptInfo | 初期プロンプト（引数から渡された場合） |

## 表示項目

| セクション | 項目名 | 表示内容 | 説明 |
|-----------|--------|----------|------|
| 中央上部 | ロゴ | OpenCodeロゴ（ASCII art） | Logo コンポーネント |
| 中央 | プロンプト | 入力フィールド | Prompt コンポーネント |
| プロンプト右 | MCPヒント | "X mcp server(s)" | 接続MCPサーバー数 |
| 中央下部 | Tips | 使い方ヒント | Tips コンポーネント |
| 下部左 | ディレクトリ | カレントディレクトリパス | 作業ディレクトリ |
| 下部中央 | MCP状態 | 接続数・/status | エラー時は赤表示 |
| 下部右 | バージョン | アプリバージョン | Installation.VERSION |
| オーバーレイ | Toast | 通知メッセージ | Toast コンポーネント |

## イベント仕様

### 1-プロンプト送信

ユーザーがプロンプトを入力してEnterキーを押すと、新規セッションが作成されセッション画面に遷移する。

**処理フロー**:
1. Promptコンポーネントで入力を受け付け
2. submit時にセッション画面へナビゲート
3. 入力内容がセッション画面に引き継がれる

### 2-コマンドダイアログ表示

Ctrl+Xを押すとコマンドダイアログが表示される。

**登録されるコマンド**:
- `tips.toggle`: Tipsの表示/非表示を切り替え（keybind: tips_toggle）

### 3-Tips表示切替

コマンドダイアログからtips.toggleを選択、またはショートカットキーでTipsの表示状態を切り替え。

**処理フロー**:
1. `kv.get("tips_hidden", false)`で現在の状態を取得
2. `kv.set("tips_hidden", !tipsHidden())`で状態を反転
3. UIが自動的に再レンダリング

### 4-MCPステータス確認

`/status`コマンド入力でMCPサーバー詳細画面を表示。

## データベース更新仕様

### 操作別データベース影響一覧

データベース直接操作なし（状態はメモリ内KVストアで管理）

## メッセージ仕様

| 表示条件 | メッセージ内容 | スタイル |
|---------|---------------|---------|
| MCPエラーあり | "mcp errors ctrl+x s" | 赤色テキスト |
| MCP接続あり | "{N} mcp server(s)" | 緑色ドット |
| Tips表示時 | 各種使い方ヒント | 薄いテキスト |

## 例外処理

| 例外 | 発生条件 | 処理内容 |
|-----|----------|---------|
| sync.data.mcp取得失敗 | MCPサーバー情報が取得できない | 空オブジェクトとして扱う |

## 備考

- OpenTUIフレームワークを使用したリアクティブターミナルUI
- SolidJSのリアクティブプリミティブ（createMemo, createSignal等）を使用
- テーマはuseTheme()フックで管理
- 初回ユーザー（セッション数0）にはTipsを非表示
- 引数からの初期プロンプト（`-p`オプション）に対応

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sync.ts | `packages/opencode/src/cli/cmd/tui/context/sync.ts` | sync.dataの構造（mcp, session等） |
| 1-2 | kv.tsx | `packages/opencode/src/cli/cmd/tui/context/kv.tsx` | KVストアによる状態管理 |

**読解のコツ**: TUIのグローバル状態はsyncコンテキストで管理され、永続化が必要な設定はkvコンテキストで管理される。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | home.tsx | `packages/opencode/src/cli/cmd/tui/routes/home.tsx` | ホーム画面コンポーネント全体 |

**主要処理フロー**:
1. **22行目**: useSync()でグローバル状態取得
2. **23行目**: useKV()で永続化設定取得
3. **24行目**: useTheme()でテーマ設定取得
4. **28-35行目**: MCP接続状態の計算（createMemo）
5. **37-43行目**: Tips表示条件の計算
6. **45-56行目**: コマンドダイアログへのコマンド登録
7. **79-89行目**: 引数からの初期プロンプト処理
8. **94-143行目**: UIレンダリング

#### Step 3: 子コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | prompt/index.tsx | `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx` | プロンプト入力コンポーネント |
| 3-2 | logo.tsx | `packages/opencode/src/cli/cmd/tui/component/logo.tsx` | ロゴ表示コンポーネント |
| 3-3 | tips.tsx | `packages/opencode/src/cli/cmd/tui/component/tips.tsx` | Tips表示コンポーネント |

#### Step 4: ユーティリティを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | locale.ts | `packages/opencode/src/util/locale.ts` | Locale.pluralize等のヘルパー関数 |

**主要処理フロー**:
- **77-80行目**: pluralize関数による複数形処理

### プログラム呼び出し階層図

```
home.tsx (Home)
    │
    ├─ useSync()
    │      └─ sync/index.ts → グローバル状態管理
    │
    ├─ useKV()
    │      └─ kv.tsx → 永続化設定管理
    │
    ├─ useTheme()
    │      └─ theme.tsx → テーマ設定
    │
    ├─ useRouteData("home")
    │      └─ route.tsx → ルートデータ取得
    │
    ├─ usePromptRef()
    │      └─ prompt.tsx → プロンプト参照管理
    │
    ├─ useCommandDialog()
    │      └─ dialog-command.tsx → コマンドダイアログ管理
    │
    ├─ useArgs()
    │      └─ args.tsx → CLI引数管理
    │
    ├─ useDirectory()
    │      └─ directory.tsx → ディレクトリ管理
    │
    └─ UI Components
           ├─ <Logo />
           ├─ <Prompt ref={...} hint={Hint} />
           ├─ <Tips />
           └─ <Toast />
```

### データフロー図

```
[入力]                    [処理]                         [出力]

CLI引数（-p）
    │
    ▼
useArgs() ─────▶ args.prompt ─────▶ 初期プロンプト設定
                      │
                      ▼
               prompt.set() ─────▶ Promptコンポーネント表示

sync.data.mcp
    │
    ▼
createMemo() ───▶ connectedMcpCount() ───▶ MCP状態表示
    │                    │
    └────────────────────┴───▶ mcpError() ───▶ エラー表示

kv.get("tips_hidden")
    │
    ▼
createMemo() ───▶ showTips() ───▶ Tips表示/非表示

プロンプト入力
    │
    ▼
Prompt.submit() ───▶ セッション画面へ遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| home.tsx | `packages/opencode/src/cli/cmd/tui/routes/home.tsx` | ソース | ホーム画面コンポーネント |
| prompt/index.tsx | `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx` | ソース | プロンプト入力コンポーネント |
| logo.tsx | `packages/opencode/src/cli/cmd/tui/component/logo.tsx` | ソース | ロゴ表示コンポーネント |
| tips.tsx | `packages/opencode/src/cli/cmd/tui/component/tips.tsx` | ソース | Tips表示コンポーネント |
| toast.tsx | `packages/opencode/src/cli/cmd/tui/ui/toast.tsx` | ソース | Toast通知コンポーネント |
| sync.ts | `packages/opencode/src/cli/cmd/tui/context/sync.ts` | ソース | 同期状態コンテキスト |
| kv.tsx | `packages/opencode/src/cli/cmd/tui/context/kv.tsx` | ソース | KVストアコンテキスト |
| theme.tsx | `packages/opencode/src/cli/cmd/tui/context/theme.tsx` | ソース | テーマコンテキスト |
| locale.ts | `packages/opencode/src/util/locale.ts` | ソース | ローカライズユーティリティ |
| installation.ts | `packages/opencode/src/installation.ts` | ソース | バージョン情報 |
