Skip to content

Commit 096d631

Browse files
shmuelhizmishmuel hizmiclaude
authored
Add wmux-client-terminal: TUI client for wmux (#25)
* Add wmux-client-terminal: TUI client for wmux using OpenTUI New `@playfast/wmux-client-terminal` package that renders wmux in the terminal via OpenTUI's React reconciler, connecting to the same wmux server as the browser client through echoform's WebSocket transport. Features: - Sidebar with categories, tabs, and status indicators - VT100 terminal buffer with ANSI color/cursor/erase support - File viewer with line numbers - Tmux-style Ctrl+B prefix for TUI commands, all other keys pass to PTY - Auto-scroll to bottom on terminal output - Web client link in header bar - Proper lifecycle cleanup via onDestroy and error handlers Also exposes `token` and `wsUrl` on WmuxHandle so consumers can pass credentials to `renderWmuxTUI()`, and adds a TUI demo entry point. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add done promise to WmuxTUIHandle for consumer cleanup The `done` promise resolves when the TUI is closed (user quit via Ctrl+B q, or programmatic destroy()). This lets consumers await it and shut down the dev server cleanly. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * tui skill * Fix typecheck: use per-file jsxImportSource pragma Move jsxImportSource from tsconfig.json to per-file `@jsxImportSource` pragmas so tsgo doesn't apply it to echoform's tsx files resolved through workspace dependencies. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add wmux/preset/tui: one-call TUI preset with web URL and awaitStop New export `@playfast/wmux/preset/tui` that starts the wmux server, prints the web URL, opens the TUI client, and returns a handle with `url`, `stop()`, and `done` promise. Server auto-stops when TUI closes. Uses dynamic import for @playfast/wmux-client-terminal (devDependency for types only) — no circular deps. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Move wmux-client-terminal to regular dependency It's used at runtime via dynamic import in the preset, not just for types. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: shmuel hizmi <shmuel@tov.dev> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 19a5af5 commit 096d631

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

50 files changed

+11684
-2
lines changed

‎.agents/skills/opentui/SKILL.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
---
2+
name: opentui
3+
description: Comprehensive OpenTUI skill for building terminal user interfaces. Covers the core imperative API, React reconciler, and Solid reconciler. Use for any TUI development task including components, layout, keyboard handling, animations, and testing.
4+
metadata:
5+
references: core, react, solid
6+
---
7+
8+
# OpenTUI Platform Skill
9+
10+
Consolidated skill for building terminal user interfaces with OpenTUI. Use decision trees below to find the right framework and components, then load detailed references.
11+
12+
## Critical Rules
13+
14+
**Follow these rules in all OpenTUI code:**
15+
16+
1. **Use `create-tui` for new projects.** See framework `REFERENCE.md` quick starts.
17+
2. **`create-tui` options must come before arguments.** `bunx create-tui -t react my-app` works, `bunx create-tui my-app -t react` does NOT.
18+
3. **Never call `process.exit()` directly.** Use `renderer.destroy()` (see `core/gotchas.md`).
19+
4. **Text styling requires nested tags in React/Solid.** Use modifier elements, not props (see `components/text-display.md`).
20+
21+
## How to Use This Skill
22+
23+
### Reference File Structure
24+
25+
Framework references follow a 5-file pattern. Cross-cutting concepts are single-file guides.
26+
27+
Each framework in `./references/<framework>/` contains:
28+
29+
| File | Purpose | When to Read |
30+
|------|---------|--------------|
31+
| `REFERENCE.md` | Overview, when to use, quick start | **Always read first** |
32+
| `api.md` | Runtime API, components, hooks | Writing code |
33+
| `configuration.md` | Setup, tsconfig, bundling | Configuring a project |
34+
| `patterns.md` | Common patterns, best practices | Implementation guidance |
35+
| `gotchas.md` | Pitfalls, limitations, debugging | Troubleshooting |
36+
37+
Cross-cutting concepts in `./references/<concept>/` have `REFERENCE.md` as the entry point.
38+
39+
### Reading Order
40+
41+
1. Start with `REFERENCE.md` for your chosen framework
42+
2. Then read additional files relevant to your task:
43+
- Building components -> `api.md` + `components/<category>.md`
44+
- Setting up project -> `configuration.md`
45+
- Layout/positioning -> `layout/REFERENCE.md`
46+
- Keyboard/input handling -> `keyboard/REFERENCE.md`
47+
- Animations -> `animation/REFERENCE.md`
48+
- Troubleshooting -> `gotchas.md` + `testing/REFERENCE.md`
49+
50+
### Example Paths
51+
52+
```
53+
./references/react/REFERENCE.md # Start here for React
54+
./references/react/api.md # React components and hooks
55+
./references/solid/configuration.md # Solid project setup
56+
./references/components/inputs.md # Input, Textarea, Select docs
57+
./references/core/gotchas.md # Core debugging tips
58+
```
59+
60+
### Runtime Notes
61+
62+
OpenTUI runs on Bun and uses Zig for native builds. Read `./references/core/gotchas.md` for runtime requirements and build guidance.
63+
64+
## Quick Decision Trees
65+
66+
### "Which framework should I use?"
67+
68+
```
69+
Which framework?
70+
├─ I want full control, maximum performance, no framework overhead
71+
│ └─ core/ (imperative API)
72+
├─ I know React, want familiar component patterns
73+
│ └─ react/ (React reconciler)
74+
├─ I want fine-grained reactivity, optimal re-renders
75+
│ └─ solid/ (Solid reconciler)
76+
└─ I'm building a library/framework on top of OpenTUI
77+
└─ core/ (imperative API)
78+
```
79+
80+
### "I need to display content"
81+
82+
```
83+
Display content?
84+
├─ Plain or styled text -> components/text-display.md
85+
├─ Container with borders/background -> components/containers.md
86+
├─ Scrollable content area -> components/containers.md (scrollbox)
87+
├─ ASCII art banner/title -> components/text-display.md (ascii-font)
88+
├─ Code with syntax highlighting -> components/code-diff.md
89+
├─ Diff viewer (unified/split) -> components/code-diff.md
90+
├─ Line numbers with diagnostics -> components/code-diff.md
91+
└─ Markdown content (streaming) -> components/code-diff.md (markdown)
92+
```
93+
94+
### "I need user input"
95+
96+
```
97+
User input?
98+
├─ Single-line text field -> components/inputs.md (input)
99+
├─ Multi-line text editor -> components/inputs.md (textarea)
100+
├─ Select from a list (vertical) -> components/inputs.md (select)
101+
├─ Tab-based selection (horizontal) -> components/inputs.md (tab-select)
102+
└─ Custom keyboard shortcuts -> keyboard/REFERENCE.md
103+
```
104+
105+
### "I need layout/positioning"
106+
107+
```
108+
Layout?
109+
├─ Flexbox-style layouts (row, column, wrap) -> layout/REFERENCE.md
110+
├─ Absolute positioning -> layout/patterns.md
111+
├─ Responsive to terminal size -> layout/patterns.md
112+
├─ Centering content -> layout/patterns.md
113+
└─ Complex nested layouts -> layout/patterns.md
114+
```
115+
116+
### "I need animations"
117+
118+
```
119+
Animations?
120+
├─ Timeline-based animations -> animation/REFERENCE.md
121+
├─ Easing functions -> animation/REFERENCE.md
122+
├─ Property transitions -> animation/REFERENCE.md
123+
└─ Looping animations -> animation/REFERENCE.md
124+
```
125+
126+
### "I need to handle input"
127+
128+
```
129+
Input handling?
130+
├─ Keyboard events (keypress, release) -> keyboard/REFERENCE.md
131+
├─ Focus management -> keyboard/REFERENCE.md
132+
├─ Paste events -> keyboard/REFERENCE.md
133+
├─ Mouse events -> components/containers.md
134+
└─ Text selection -> components/text-display.md
135+
```
136+
137+
### "I need to test my TUI"
138+
139+
```
140+
Testing?
141+
├─ Snapshot testing -> testing/REFERENCE.md
142+
├─ Interaction testing -> testing/REFERENCE.md
143+
├─ Test renderer setup -> testing/REFERENCE.md
144+
└─ Debugging tests -> testing/REFERENCE.md
145+
```
146+
147+
### "I need to debug/troubleshoot"
148+
149+
```
150+
Troubleshooting?
151+
├─ Runtime errors, crashes -> <framework>/gotchas.md
152+
├─ Layout issues -> layout/REFERENCE.md + layout/patterns.md
153+
├─ Input/focus issues -> keyboard/REFERENCE.md
154+
└─ Repro + regression tests -> testing/REFERENCE.md
155+
```
156+
157+
### Troubleshooting Index
158+
159+
- Terminal cleanup, crashes -> `core/gotchas.md`
160+
- Text styling not applying -> `components/text-display.md`
161+
- Input focus/shortcuts -> `keyboard/REFERENCE.md`
162+
- Layout misalignment -> `layout/REFERENCE.md`
163+
- Flaky snapshots -> `testing/REFERENCE.md`
164+
165+
For component naming differences and text modifiers, see `components/REFERENCE.md`.
166+
167+
## Product Index
168+
169+
### Frameworks
170+
| Framework | Entry File | Description |
171+
|-----------|------------|-------------|
172+
| Core | `./references/core/REFERENCE.md` | Imperative API, all primitives |
173+
| React | `./references/react/REFERENCE.md` | React reconciler for declarative TUI |
174+
| Solid | `./references/solid/REFERENCE.md` | SolidJS reconciler for declarative TUI |
175+
176+
### Cross-Cutting Concepts
177+
| Concept | Entry File | Description |
178+
|---------|------------|-------------|
179+
| Layout | `./references/layout/REFERENCE.md` | Yoga/Flexbox layout system |
180+
| Components | `./references/components/REFERENCE.md` | Component reference by category |
181+
| Keyboard | `./references/keyboard/REFERENCE.md` | Keyboard input handling |
182+
| Animation | `./references/animation/REFERENCE.md` | Timeline-based animations |
183+
| Testing | `./references/testing/REFERENCE.md` | Test renderer and snapshots |
184+
185+
### Component Categories
186+
| Category | Entry File | Components |
187+
|----------|------------|------------|
188+
| Text & Display | `./references/components/text-display.md` | text, ascii-font, styled text |
189+
| Containers | `./references/components/containers.md` | box, scrollbox, borders |
190+
| Inputs | `./references/components/inputs.md` | input, textarea, select, tab-select |
191+
| Code & Diff | `./references/components/code-diff.md` | code, line-number, diff, markdown |
192+
193+
## Resources
194+
195+
**Repository**: https://github.com/anomalyco/opentui
196+
**Core Docs**: https://github.com/anomalyco/opentui/tree/main/packages/core/docs
197+
**Examples**: https://github.com/anomalyco/opentui/tree/main/packages/core/src/examples
198+
**Awesome List**: https://github.com/msmps/awesome-opentui

0 commit comments

Comments
 (0)