opentui

OpenTUI プラットフォームスキル

OpenTUI でターミナルユーザーインターフェイスを構築するための統合スキルです。以下の判断ツリーで適切なフレームワークとコンポーネントを見つけてから、詳細なリファレンスを読み込んでください。

重要なルール

OpenTUI のコードでは、常に以下のルールに従ってください。

1. 新しいプロジェクトには create-tui を使用してください。 フレームワークの REFERENCE.md にあるクイックスタートを参照してください。
2. create-tui のオプションは引数より前に指定してください。 bunx create-tui -t react my-app は動作しますが、bunx create-tui my-app -t react は動作しません。
3. process.exit() を直接呼び出さないでください。 renderer.destroy() を使用してください（core/gotchas.md を参照）。
4. React／Solid でテキストをスタイリングするには、ネストしたタグが必要です。 props ではなく修飾要素を使用してください（components/text-display.md を参照）。

このスキルの使用方法

リファレンスファイルの構成

フレームワークのリファレンスは、5 ファイルのパターンに従います。複数の領域にまたがる概念は、1 ファイルのガイドで説明します。

./references/<framework>/ 内の各フレームワークには、以下が含まれます。

ファイル	目的	読むタイミング
REFERENCE.md	概要、使用する場面、クイックスタート	必ず最初に読む
api.md	ランタイム API、コンポーネント、フック	コードを書くとき
configuration.md	セットアップ、tsconfig、バンドル	プロジェクトを設定するとき
patterns.md	よく使うパターン、ベストプラクティス	実装の指針を確認するとき
gotchas.md	落とし穴、制限、デバッグ	トラブルシューティング時

./references/<concept>/ 内にある複数の領域にまたがる概念では、REFERENCE.md が入口です。

読む順序

1. 使用するフレームワークの REFERENCE.md から始めます
2. 次に、タスクに関連するファイルを読みます。
   • コンポーネントの構築 -> api.md + components/<category>.md
   • プロジェクトのセットアップ -> configuration.md
   • レイアウト／配置 -> layout/REFERENCE.md
   • キーボード／入力処理 -> keyboard/REFERENCE.md
   • レイヤー化されたキー割り当て／コマンド -> keymap/REFERENCE.md
   • アニメーション -> animation/REFERENCE.md
   • トラブルシューティング -> gotchas.md + testing/REFERENCE.md

パスの例

./references/react/REFERENCE.md           # Start here for React
./references/react/api.md              # React components and hooks
./references/solid/configuration.md    # Solid project setup
./references/components/inputs.md      # Input, Textarea, Select docs
./references/core/gotchas.md           # Core debugging tips

ランタイムに関する注意

OpenTUI は Bun 上で動作し、ネイティブビルドには Zig を使用します。ランタイム要件とビルドのガイダンスについては、./references/core/gotchas.md をお読みください。

クイック判断ツリー

「どのフレームワークを使えばよいですか？」

Which framework?
├─ I want full control, maximum performance, no framework overhead
│  └─ core/ (imperative API)
├─ I know React, want familiar component patterns
│  └─ react/ (React reconciler)
├─ I want fine-grained reactivity, optimal re-renders
│  └─ solid/ (Solid reconciler)
└─ I'm building a library/framework on top of OpenTUI
   └─ core/ (imperative API)

「コンテンツを表示したい」

Display content?
├─ Plain or styled text -> components/text-display.md
├─ Container with borders/background -> components/containers.md
├─ Scrollable content area -> components/containers.md (scrollbox)
├─ Standalone scrollbar -> components/containers.md (scrollbar)
├─ ASCII art banner/title -> components/text-display.md (ascii-font)
├─ PNG/JPEG/WebP/GIF image -> components/text-display.md (image)
├─ First-draw diagnostic -> components/text-display.md (time-to-first-draw)
├─ QR code -> components/text-display.md (qr-code, @opentui/qrcode)
├─ Embedded child terminal/VT output -> components/containers.md (Core only)
├─ Data table with borders/wrapping -> components/code-diff.md (TextTable)
├─ Code with syntax highlighting -> components/code-diff.md
├─ Diff viewer (unified/split, hunk nav) -> components/code-diff.md
├─ Line numbers with diagnostics -> components/code-diff.md
└─ Markdown content (streaming) -> components/code-diff.md (markdown)

「ユーザー入力を受け付けたい」

User input?
├─ Single-line text field -> components/inputs.md (input)
├─ Multi-line text editor -> components/inputs.md (textarea)
├─ Select from a list (vertical) -> components/inputs.md (select)
├─ Tab-based selection (horizontal) -> components/inputs.md (tab-select)
├─ Value slider -> components/inputs.md (slider)
├─ Declarative/layered keybindings -> keymap/REFERENCE.md (@opentui/keymap)
└─ Custom keyboard shortcuts -> keyboard/REFERENCE.md

「レイアウト／配置を行いたい」

Layout?
├─ Flexbox-style layouts (row, column, wrap) -> layout/REFERENCE.md
├─ Absolute positioning -> layout/patterns.md
├─ Responsive to terminal size -> layout/patterns.md
├─ Centering content -> layout/patterns.md
└─ Complex nested layouts -> layout/patterns.md

「アニメーションを使いたい」

Animations?
├─ Timeline-based animations -> animation/REFERENCE.md
├─ Easing functions -> animation/REFERENCE.md
├─ Property transitions -> animation/REFERENCE.md
└─ Looping animations -> animation/REFERENCE.md

「入力を処理したい」

Input handling?
├─ Keyboard events (keypress, release) -> keyboard/REFERENCE.md
├─ Layered bindings, commands, leader keys -> keymap/REFERENCE.md
├─ Focus management -> keyboard/REFERENCE.md
├─ Paste events -> keyboard/REFERENCE.md
├─ Mouse events -> components/containers.md
├─ Text selection & copy-on-select -> keyboard/REFERENCE.md (selection)
└─ Host/terminal clipboard service or OSC 52 -> keyboard/REFERENCE.md (clipboard)

「TUI をテストしたい」

Testing?
├─ Snapshot testing -> testing/REFERENCE.md
├─ Interaction testing -> testing/REFERENCE.md
├─ Test renderer setup -> testing/REFERENCE.md
└─ Debugging tests -> testing/REFERENCE.md

「プラットフォーム機能（オーディオ、画像、クリップボード、通知、SSH）が必要」

Platform capability?
├─ Play loaded sound or MP3/FLAC stream -> core/api.md (Audio)
├─ Capture microphone PCM / record WAV -> core/api.md (Audio)
├─ Decode, transform, or display images -> components/text-display.md (image)
├─ Read/write host or terminal clipboard -> keyboard/REFERENCE.md (clipboard)
├─ Desktop notifications (OSC 9/777/99) -> core/api.md (triggerNotification)
├─ Custom stdin/stdout (PTY, xterm.js) -> core/api.md (createCliRenderer)
└─ Serve a TUI over SSH -> core/REFERENCE.md (@opentui/ssh)

「デバッグ／トラブルシューティングをしたい」

Troubleshooting?
├─ Runtime errors, crashes -> <framework>/gotchas.md
├─ Layout issues -> layout/REFERENCE.md + layout/patterns.md
├─ Input/focus issues -> keyboard/REFERENCE.md
└─ Repro + regression tests -> testing/REFERENCE.md

トラブルシューティング索引

• ターミナルのクリーンアップ、クラッシュ -> core/gotchas.md
• テキストのスタイリングが適用されない -> components/text-display.md
• 入力フォーカス／ショートカット -> keyboard/REFERENCE.md
• レイアウトのずれ -> layout/REFERENCE.md
• 不安定なスナップショット -> testing/REFERENCE.md

コンポーネント名の違いとテキスト修飾子については、components/REFERENCE.md を参照してください。

製品索引

フレームワーク

フレームワーク	エントリーファイル	説明
Core	./references/core/REFERENCE.md	命令型 API、すべてのプリミティブ
React	./references/react/REFERENCE.md	宣言型 TUI 用 React リコンシラー
Solid	./references/solid/REFERENCE.md	宣言型 TUI 用 SolidJS リコンシラー

複数の領域にまたがる概念

概念	エントリーファイル	説明
レイアウト	./references/layout/REFERENCE.md	Yoga／Flexbox レイアウトシステム
コンポーネント	./references/components/REFERENCE.md	カテゴリー別のコンポーネントリファレンス
キーボード	./references/keyboard/REFERENCE.md	低レベルのキーボード入力処理
キーマップ	./references/keymap/REFERENCE.md	宣言型のレイヤー化されたキー割り当て（@opentui/keymap）
アニメーション	./references/animation/REFERENCE.md	タイムラインベースのアニメーション
テスト	./references/testing/REFERENCE.md	テスト用レンダラーとスナップショット

コンポーネントのカテゴリ

カテゴリ	エントリーファイル	コンポーネント
テキストと表示	./references/components/text-display.md	テキスト、ASCII フォント、画像、初回描画までの時間、スタイル付きテキスト、QR コード
コンテナー	./references/components/containers.md	ボックス、スクロールボックス、スクロールバー、埋め込みターミナル、枠線
入力	./references/components/inputs.md	入力、テキストエリア、選択、タブ選択、スライダー
コードと差分	./references/components/code-diff.md	コード、行番号、差分、Markdown、テキストテーブル

追加パッケージ

パッケージ	説明	ドキュメント
@opentui/keymap	レイヤー化されたキーバインド／コマンドエンジン（Bun または Node、FFI 不要）	./references/keymap/REFERENCE.md
@opentui/qrcode	QR コードコンポーネント	./references/components/text-display.md
@opentui/ssh	SSH 経由で TUI を提供	./references/core/REFERENCE.md
@opentui/three	Three.js WebGPU レンダラー（以前は core/src/3d）	上流の packages/three
@opentui/examples	実行可能なサンプル（以前は core/src/examples）	上流の packages/examples

Core には、読み込み済み／ストリーミング／キャプチャ済みのオーディオ、ネイティブの画像、ホストおよびターミナルのクリップボードサービス、OSC デスクトップ通知も含まれています。

リソース

リポジトリ：https://github.com/anomalyco/opentui コアドキュメント：https://github.com/anomalyco/opentui/tree/main/packages/core/docs サンプル：https://github.com/anomalyco/opentui/tree/main/packages/examples/src Awesome リスト：https://github.com/msmps/awesome-opentui