xonecas.io
60255
Zn

Zoea-Nova / commit 8280f8d

refactor: move project-specific skills to local config

Move Zoea Nova specific skills from global OpenCode config to local project:
- bubbletea (TUI framework for Zoea Nova)
- build-tui-view (Hatchet CLI TUI views)
- go-skills (Go best practices for LlamaFarm CLI)

This reduces global config bloat and prevents cross-project confusion.

Global config changes (outside this repo):
- Removed ~/.config/opencode/skills/ directory
- Removed ~/.agents/ directory
- Removed generic skills: commit-work, crafting-effective-readmes, find-skills, writing-plans
- Updated AGENTS.md with core development principles:
  - Systematic Debugging
  - Verification Before Completion
  - Writing Clearly and Concisely
  - Mermaid Diagrams

Local config now contains only Zoea Nova specific skills.

xonecas2026-02-07 8280f8de07aa745b30bbd324336320c962e39425 parent fa42f84

12 files changed

This diff is too big to show in full. The first 1000 lines are below, and every file is listed with its counts.

.opencode/skills/bubbletea/SKILL.md+277−0
@@ -0,0 +1,277 @@
1+---
2+name: bubbletea
3+description: Build terminal user interfaces with Go and Bubbletea framework. Use for creating TUI apps with the Elm architecture, dual-pane layouts, accordion modes, mouse/keyboard handling, Lipgloss styling, and reusable components. Includes production-ready templates, effects library, and battle-tested layout patterns from real projects.
4+license: MIT
5+---
6+
7+# Bubbletea TUI Development
8+
9+Production-ready skill for building beautiful terminal user interfaces with Go, Bubbletea, and Lipgloss.
10+
11+## When to Use This Skill
12+
13+Use this skill when:
14+- Creating new TUI applications with Go
15+- Adding Bubbletea components to existing apps
16+- Fixing layout/rendering issues (borders, alignment, overflow)
17+- Implementing mouse/keyboard interactions
18+- Building dual-pane or multi-panel layouts
19+- Adding visual effects (metaballs, waves, rainbow text)
20+- Troubleshooting TUI rendering problems
21+
22+## Core Principles
23+
24+**CRITICAL**: Before implementing ANY layout, consult `references/golden-rules.md` for the 4 Golden Rules. These rules prevent the most common and frustrating TUI layout bugs.
25+
26+### The 4 Golden Rules (Summary)
27+
28+1. **Always Account for Borders** - Subtract 2 from height calculations BEFORE rendering panels
29+2. **Never Auto-Wrap in Bordered Panels** - Always truncate text explicitly
30+3. **Match Mouse Detection to Layout** - Use X coords for horizontal, Y coords for vertical
31+4. **Use Weights, Not Pixels** - Proportional layouts scale perfectly
32+
33+Full details and examples in `references/golden-rules.md`.
34+
35+## Creating New Projects
36+
37+This project includes a production-ready template system. When this skill is bundled with a new project (via `new_project.sh`), use the existing template structure as the starting point.
38+
39+### Project Structure
40+
41+All new projects follow this architecture:
42+```
43+your-app/
44+├── main.go # Entry point (minimal, ~21 lines)
45+├── types.go # Type definitions, structs, enums
46+├── model.go # Model initialization & layout calculation
47+├── update.go # Message dispatcher
48+├── update_keyboard.go # Keyboard handling
49+├── update_mouse.go # Mouse handling
50+├── view.go # View rendering & layouts
51+├── styles.go # Lipgloss style definitions
52+├── config.go # Configuration management
53+└── .claude/skills/bubbletea/ # This skill (bundled)
54+```
55+
56+### Architecture Guidelines
57+
58+- Keep `main.go` minimal (entry point only, ~21 lines)
59+- All types in `types.go` (structs, enums, constants)
60+- Separate keyboard and mouse handling into dedicated files
61+- One file, one responsibility
62+- Maximum file size: 800 lines (ideally <500)
63+- Configuration via YAML with hot-reload support
64+
65+## Available Components
66+
67+See `references/components.md` for the complete catalog of reusable components:
68+
69+- **Panel System**: Single, dual-pane, multi-panel, tabbed layouts
70+- **Lists**: Simple list, filtered list, tree view
71+- **Input**: Text input, multiline, forms, autocomplete
72+- **Dialogs**: Confirm, input, progress, modal
73+- **Menus**: Context menu, command palette, menu bar
74+- **Status**: Status bar, title bar, breadcrumbs
75+- **Preview**: Text, markdown, syntax highlighting, images, hex
76+- **Tables**: Simple and interactive tables
77+
78+## Effects Library
79+
80+Beautiful physics-based animations available in the template:
81+
82+- 🔮 **Metaballs** - Lava lamp-style floating blobs
83+- 🌊 **Wave Effects** - Sine wave distortions
84+- 🌈 **Rainbow Cycling** - Animated color gradients
85+- 🎭 **Layer Compositor** - ANSI-aware multi-layer rendering
86+
87+See `references/effects.md` for usage examples and integration patterns.
88+
89+## Layout Implementation Pattern
90+
91+When implementing layouts, follow this sequence:
92+
93+### 1. Calculate Available Space
94+```go
95+func (m model) calculateLayout() (int, int) {
96+ contentWidth := m.width
97+ contentHeight := m.height
98+
99+ // Subtract UI elements
100+ if m.config.UI.ShowTitle {
101+ contentHeight -= 3 // title bar (3 lines)
102+ }
103+ if m.config.UI.ShowStatus {
104+ contentHeight -= 1 // status bar
105+ }
106+
107+ // CRITICAL: Account for panel borders
108+ contentHeight -= 2 // top + bottom borders
109+
110+ return contentWidth, contentHeight
111+}
112+```
113+
114+### 2. Use Weight-Based Panel Sizing
115+```go
116+// Calculate weights based on focus/accordion mode
117+leftWeight, rightWeight := 1, 1
118+if m.accordionMode && m.focusedPanel == "left" {
119+ leftWeight = 2 // Focused panel gets 2x weight
120+}
121+
122+// Calculate actual widths from weights
123+totalWeight := leftWeight + rightWeight
124+leftWidth := (availableWidth * leftWeight) / totalWeight
125+rightWidth := availableWidth - leftWidth
126+```
127+
128+### 3. Truncate Text to Prevent Wrapping
129+```go
130+// Calculate max text width to prevent wrapping
131+maxTextWidth := panelWidth - 4 // -2 borders, -2 padding
132+
133+// Truncate ALL text before rendering
134+title = truncateString(title, maxTextWidth)
135+subtitle = truncateString(subtitle, maxTextWidth)
136+
137+func truncateString(s string, maxLen int) string {
138+ if len(s) <= maxLen {
139+ return s
140+ }
141+ return s[:maxLen-1] + "…"
142+}
143+```
144+
145+## Mouse Interaction Pattern
146+
147+Always check layout mode before processing mouse events:
148+
149+```go
150+func (m model) handleLeftClick(msg tea.MouseMsg) (tea.Model, tea.Cmd) {
151+ if m.shouldUseVerticalStack() {
152+ // Vertical stack mode: use Y coordinates
153+ topHeight, _ := m.calculateVerticalStackLayout()
154+ relY := msg.Y - contentStartY
155+
156+ if relY < topHeight {
157+ m.focusedPanel = "left" // Top panel
158+ } else {
159+ m.focusedPanel = "right" // Bottom panel
160+ }
161+ } else {
162+ // Side-by-side mode: use X coordinates
163+ leftWidth, _ := m.calculateDualPaneLayout()
164+
165+ if msg.X < leftWidth {
166+ m.focusedPanel = "left"
167+ } else {
168+ m.focusedPanel = "right"
169+ }
170+ }
171+
172+ return m, nil
173+}
174+```
175+
176+## Common Pitfalls to Avoid
177+
178+See `references/troubleshooting.md` for detailed solutions to common issues:
179+
180+### ❌ DON'T: Set explicit Height() on bordered panels
181+```go
182+// BAD: Can cause misalignment
183+panelStyle := lipgloss.NewStyle().
184+ Border(border).
185+ Height(height) // Don't do this!
186+```
187+
188+### ✅ DO: Fill content to exact height
189+```go
190+// GOOD: Fill content lines to exact height
191+for len(lines) < innerHeight {
192+ lines = append(lines, "")
193+}
194+panelStyle := lipgloss.NewStyle().Border(border)
195+```
196+
197+## Testing and Debugging
198+
199+When panels don't align or render incorrectly:
200+
201+1. **Check height accounting** - Verify contentHeight calculation subtracts all UI elements + borders
202+2. **Check text wrapping** - Ensure all strings are truncated to maxTextWidth
203+3. **Check mouse detection** - Verify X/Y coordinate usage matches layout orientation
204+4. **Check border consistency** - Use same border style for all panels
205+
206+See `references/troubleshooting.md` for the complete debugging decision tree.
207+
208+## Configuration System
209+
210+All projects support YAML configuration with hot-reload:
211+
212+```yaml
213+theme: "dark"
214+keybindings: "default"
215+
216+layout:
217+ type: "dual_pane"
218+ split_ratio: 0.5
219+ accordion_mode: true
220+
221+ui:
222+ show_title: true
223+ show_status: true
224+ mouse_enabled: true
225+ show_icons: true
226+```
227+
228+Configuration files are loaded from:
229+1. `~/.config/your-app/config.yaml` (user config)
230+2. `./config.yaml` (local override)
231+
232+## Dependencies
233+
234+**Required:**
235+```
236+github.com/charmbracelet/bubbletea
237+github.com/charmbracelet/lipgloss
238+github.com/charmbracelet/bubbles
239+gopkg.in/yaml.v3
240+```
241+
242+**Optional** (uncomment in go.mod as needed):
243+```
244+github.com/charmbracelet/glamour # Markdown rendering
245+github.com/charmbracelet/huh # Forms
246+github.com/alecthomas/chroma/v2 # Syntax highlighting
247+github.com/evertras/bubble-table # Interactive tables
248+github.com/koki-develop/go-fzf # Fuzzy finder
249+```
250+
251+## Reference Documentation
252+
253+All reference files are loaded progressively as needed:
254+
255+- **golden-rules.md** - Critical layout patterns and anti-patterns
256+- **components.md** - Complete catalog of reusable components
257+- **troubleshooting.md** - Common issues and debugging decision tree
258+- **emoji-width-fix.md** - Battle-tested solution for emoji alignment across terminals (xterm, WezTerm, Termux, Windows Terminal)
259+
260+## External Resources
261+
262+- [Bubbletea Documentation](https://github.com/charmbracelet/bubbletea)
263+- [Lipgloss Documentation](https://github.com/charmbracelet/lipgloss)
264+- [Bubbles Components](https://github.com/charmbracelet/bubbles)
265+- [Charm Ecosystem](https://charm.sh/)
266+
267+## Best Practices Summary
268+
269+1. **Always** consult golden-rules.md before implementing layouts
270+2. **Always** use weight-based sizing for flexible layouts
271+3. **Always** truncate text explicitly (never rely on auto-wrap)
272+4. **Always** match mouse detection to layout orientation
273+5. **Always** account for borders in height calculations
274+6. **Never** set explicit Height() on bordered Lipgloss styles
275+7. **Never** assume layout orientation in mouse handlers
276+
277+Follow these patterns and you'll avoid 90% of TUI layout bugs.
.opencode/skills/bubbletea/references/components.md+647−0
@@ -0,0 +1,647 @@
1+# Bubbletea Components Catalog
2+
3+Reusable components for building TUI applications. All components follow the Elm architecture pattern (Init, Update, View).
4+
5+## Panel System
6+
7+Pre-built panel layouts for different UI arrangements.
8+
9+### Single Panel
10+
11+Full-screen single view with optional title and status bars.
12+
13+**Use for:**
14+- Simple focused interfaces
15+- Full-screen text editors
16+- Single-purpose tools
17+
18+**Implementation:**
19+```go
20+func (m model) renderSinglePanel() string {
21+ contentWidth, contentHeight := m.calculateLayout()
22+
23+ // Create panel with full available space
24+ panel := m.styles.Panel.
25+ Width(contentWidth).
26+ Render(content)
27+
28+ return panel
29+}
30+```
31+
32+### Dual Pane
33+
34+Side-by-side panels with configurable split ratio and accordion mode.
35+
36+**Use for:**
37+- File browsers with preview
38+- Split editors
39+- Source/destination views
40+
41+**Features:**
42+- Dynamic split ratio (50/50, 66/33, 75/25)
43+- Accordion mode (focused panel expands)
44+- Responsive (stacks vertically on narrow terminals)
45+- Weight-based sizing for smooth resizing
46+
47+**Implementation:**
48+```go
49+func (m model) renderDualPane() string {
50+ contentWidth, contentHeight := m.calculateLayout()
51+
52+ // Calculate weights based on focus/accordion
53+ leftWeight, rightWeight := 1, 1
54+ if m.accordionMode && m.focusedPanel == "left" {
55+ leftWeight = 2
56+ }
57+
58+ // Calculate actual widths from weights
59+ totalWeight := leftWeight + rightWeight
60+ leftWidth := (contentWidth * leftWeight) / totalWeight
61+ rightWidth := contentWidth - leftWidth
62+
63+ // Render panels
64+ leftPanel := m.renderPanel("left", leftWidth, contentHeight)
65+ rightPanel := m.renderPanel("right", rightWidth, contentHeight)
66+
67+ return lipgloss.JoinHorizontal(lipgloss.Top, leftPanel, rightPanel)
68+}
69+```
70+
71+**Keyboard shortcuts:**
72+- `Tab` - Switch focus between panels
73+- `a` - Toggle accordion mode
74+- Arrow keys - Focus panel in direction
75+
76+**Mouse support:**
77+- Click panel to focus
78+- Works in both horizontal and vertical stack modes
79+
80+### Multi-Panel
81+
82+3+ panels with configurable sizes and arrangements.
83+
84+**Use for:**
85+- IDEs (file tree, editor, terminal, output)
86+- Dashboard views
87+- Complex workflows
88+
89+**Common layouts:**
90+- Three-column (25/50/25)
91+- Three-row
92+- Grid (2x2, 3x3)
93+- Sidebar + main + inspector
94+
95+**Implementation:**
96+```go
97+// Three-column example
98+mainWeight, leftWeight, rightWeight := 2, 1, 1 // 50/25/25
99+totalWeight := mainWeight + leftWeight + rightWeight
100+
101+leftWidth := (contentWidth * leftWeight) / totalWeight
102+mainWidth := (contentWidth * mainWeight) / totalWeight
103+rightWidth := contentWidth - leftWidth - mainWidth
104+```
105+
106+### Tabbed
107+
108+Multiple views with tab switching.
109+
110+**Use for:**
111+- Multiple documents
112+- Settings pages
113+- Different data views
114+
115+**Features:**
116+- Tab bar with active indicator
117+- Keyboard shortcuts (`1-9`, `Ctrl+Tab`)
118+- Mouse click to switch tabs
119+- Close tab support
120+
121+## Lists
122+
123+### Simple List
124+
125+Basic scrollable list of items.
126+
127+**Use for:**
128+- File listings
129+- Menu options
130+- Search results
131+
132+**Features:**
133+- Keyboard navigation (Up/Down, Home/End, PgUp/PgDn)
134+- Mouse scrolling and selection
135+- Visual selection indicator
136+- Viewport scrolling (only visible items rendered)
137+
138+**Integration:**
139+```go
140+import "github.com/charmbracelet/bubbles/list"
141+
142+type model struct {
143+ list list.Model
144+}
145+
146+func (m model) Init() tea.Cmd {
147+ items := []list.Item{
148+ item{title: "Item 1", desc: "Description 1"},
149+ item{title: "Item 2", desc: "Description 2"},
150+ }
151+ m.list = list.New(items, list.NewDefaultDelegate(), 0, 0)
152+ return nil
153+}
154+```
155+
156+### Filtered List
157+
158+List with fuzzy search/filter.
159+
160+**Use for:**
161+- Quick file finder
162+- Command palette
163+- Searchable settings
164+
165+**Features:**
166+- Real-time filtering as you type
167+- Fuzzy matching
168+- Highlighted matches
169+
170+**Dependencies:**
171+```go
172+github.com/koki-develop/go-fzf
173+```
174+
175+### Tree View
176+
177+Hierarchical list with expand/collapse.
178+
179+**Use for:**
180+- Directory trees
181+- Nested data structures
182+- Outline views
183+
184+**Features:**
185+- Expand/collapse nodes
186+- Indentation levels
187+- Parent/child relationships
188+- Recursive rendering
189+
190+## Input Components
191+
192+### Text Input
193+
194+Single-line text field.
195+
196+**Use for:**
197+- Forms
198+- Search boxes
199+- Prompts
200+
201+**Integration:**
202+```go
203+import "github.com/charmbracelet/bubbles/textinput"
204+
205+type model struct {
206+ input textinput.Model
207+}
208+
209+func (m model) Init() tea.Cmd {
210+ m.input = textinput.New()
211+ m.input.Placeholder = "Enter text..."
212+ m.input.Focus()
213+ return textinput.Blink
214+}
215+```
216+
217+### Multiline Input
218+
219+Text area for longer content.
220+
221+**Use for:**
222+- Commit messages
223+- Notes
224+- Configuration editing
225+
226+**Integration:**
227+```go
228+import "github.com/charmbracelet/bubbles/textarea"
229+
230+type model struct {
231+ textarea textarea.Model
232+}
233+```
234+
235+### Forms
236+
237+Structured input with multiple fields.
238+
239+**Use for:**
240+- Settings dialogs
241+- User registration
242+- Multi-field input
243+
244+**Integration:**
245+```go
246+import "github.com/charmbracelet/huh"
247+
248+form := huh.NewForm(
249+ huh.NewGroup(
250+ huh.NewInput().
251+ Title("Name").
252+ Value(&name),
253+ huh.NewInput().
254+ Title("Email").
255+ Value(&email),
256+ ),
257+)
258+```
259+
260+### Autocomplete
261+
262+Text input with suggestions.
263+
264+**Use for:**
265+- Command entry
266+- File paths
267+- Tag selection
268+
269+**Features:**
270+- Real-time suggestions
271+- Keyboard navigation of suggestions
272+- Tab completion
273+
274+## Dialogs
275+
276+### Confirm Dialog
277+
278+Yes/No confirmation.
279+
280+**Use for:**
281+- Delete confirmations
282+- Save prompts
283+- Destructive actions
284+
285+**Example:**
286+```
287+┌─────────────────────────────┐
288+│ Delete this file? │
289+│ │
290+│ [Yes] [No] │
291+└─────────────────────────────┘
292+```
293+
294+### Input Dialog
295+
296+Prompt for single value.
297+
298+**Use for:**
299+- Quick input
300+- Rename operations
301+- New file creation
302+
303+### Progress Dialog
304+
305+Show long-running operations.
306+
307+**Use for:**
308+- File uploads
309+- Build processes
310+- Data processing
311+
312+**Integration:**
313+```go
314+import "github.com/charmbracelet/bubbles/progress"
315+
316+type model struct {
317+ progress progress.Model
318+}
319+```
320+
321+### Modal
322+
323+Full overlay dialog.
324+
325+**Use for:**
326+- Settings
327+- Help screens
328+- Complex forms
329+
330+## Menus
331+
332+### Context Menu
333+
334+Right-click or keyboard-triggered menu.
335+
336+**Use for:**
337+- File operations
338+- Quick actions
339+- Tool integration
340+
341+**Example:**
342+```
343+┌─────────────┐
344+│ Open │
345+│ Copy │
346+│ Delete │
347+│ Properties │
348+└─────────────┘
349+```
350+
351+### Command Palette
352+
353+Fuzzy searchable command list.
354+
355+**Use for:**
356+- Command discovery
357+- Keyboard-first workflows
358+- Power user features
359+
360+**Keyboard:**
361+- `Ctrl+P` or `Ctrl+Shift+P` to open
362+- Type to filter
363+- Enter to execute
364+
365+### Menu Bar
366+
367+Top-level menu system.
368+
369+**Use for:**
370+- Traditional application menus
371+- Organized commands
372+- Discoverability
373+
374+**Example:**
375+```
376+File Edit View Help
377+```
378+
379+## Status Components
380+
381+### Status Bar
382+
383+Bottom bar showing state and help.
384+
385+**Use for:**
386+- Current mode/state
387+- Keyboard hints
388+- File info
389+
390+**Example:**
391+```
392+┌────────────────────────────────────┐
393+│ │
394+│ Content area │
395+│ │
396+├────────────────────────────────────┤
397+│ Normal | file.txt | Line 10/100 │
398+└────────────────────────────────────┘
399+```
400+
401+**Pattern:**
402+```go
403+func (m model) renderStatusBar() string {
404+ left := fmt.Sprintf("%s | %s", m.mode, m.filename)
405+ right := fmt.Sprintf("Line %d/%d", m.cursor, m.lineCount)
406+
407+ width := m.width
408+ gap := width - lipgloss.Width(left) - lipgloss.Width(right)
409+
410+ return left + strings.Repeat(" ", gap) + right
411+}
412+```
413+
414+### Title Bar
415+
416+Top bar with app title and context.
417+
418+**Use for:**
419+- Application name
420+- Current path/document
421+- Action buttons
422+
423+### Breadcrumbs
424+
425+Path navigation component.
426+
427+**Use for:**
428+- Directory navigation
429+- Nested views
430+- History trail
431+
432+**Example:**
433+```
434+Home > Projects > TUITemplate > components
435+```
436+
437+## Preview Components
438+
439+### Text Preview
440+
441+Rendered text with syntax highlighting.
442+
443+**Use for:**
444+- File preview
445+- Code display
446+- Log viewing
447+
448+**Integration:**
449+```go
450+import "github.com/alecthomas/chroma/v2/quick"
451+
452+func renderCode(code, language string) string {
453+ var buf bytes.Buffer
454+ quick.Highlight(&buf, code, language, "terminal256", "monokai")
455+ return buf.String()
456+}
457+```
458+
459+### Markdown Preview
460+
461+Rendered markdown.
462+
463+**Integration:**
464+```go
465+import "github.com/charmbracelet/glamour"
466+
467+func renderMarkdown(md string) (string, error) {
468+ renderer, _ := glamour.NewTermRenderer(
469+ glamour.WithAutoStyle(),
470+ glamour.WithWordWrap(80),
471+ )
472+ return renderer.Render(md)
473+}
474+```
475+
476+### Image Preview
477+
478+ASCII/Unicode art from images.
479+
480+**Use for:**
481+- Image thumbnails
482+- Visual file preview
483+- Logos/artwork
484+
485+**External tools:**
486+- `catimg` - Convert images to 256-color ASCII
487+- `viu` - View images in terminal with full color
488+
489+### Hex Preview
490+
491+Binary file viewer.
492+
493+**Use for:**
494+- Binary file inspection
495+- Debugging
496+- Data analysis
497+
498+**Example:**
499+```
500+00000000: 7f45 4c46 0201 0100 0000 0000 0000 0000 .ELF............
501+00000010: 0200 3e00 0100 0000 6009 4000 0000 0000 ..>.....`.@.....
502+```
503+
504+## Tables
505+
506+### Simple Table
507+
508+Static data display.
509+
510+**Use for:**
511+- Data display
512+- Reports
513+- Comparison views
514+
515+### Interactive Table
516+
517+Navigable table with selection.
518+
519+**Use for:**
520+- Database browsers
521+- CSV viewers
522+- Process lists
523+
524+**Integration:**
525+```go
526+import "github.com/evertras/bubble-table/table"
527+
528+type model struct {
529+ table table.Model
530+}
531+
532+func (m model) Init() tea.Cmd {
533+ m.table = table.New([]table.Column{
534+ table.NewColumn("id", "ID", 10),
535+ table.NewColumn("name", "Name", 20),
536+ })
537+ return nil
538+}
539+```
540+
541+**Features:**
542+- Sort by column
543+- Row selection
544+- Keyboard navigation
545+- Column resize
546+
547+## Component Integration Patterns
548+
549+### Composing Components
550+
551+```go
552+type model struct {
553+ // Multiple components in one view
554+ list list.Model
555+ preview string
556+ input textinput.Model
557+ focused string // which component has focus
558+}
559+
560+func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
561+ switch msg := msg.(type) {
562+ case tea.KeyMsg:
563+ // Route to focused component
564+ switch m.focused {
565+ case "list":
566+ var cmd tea.Cmd
567+ m.list, cmd = m.list.Update(msg)
568+ return m, cmd
569+ case "input":
570+ var cmd tea.Cmd
571+ m.input, cmd = m.input.Update(msg)
572+ return m, cmd
573+ }
574+ }
575+ return m, nil
576+}
577+```
578+
579+### Lazy Loading Components
580+
581+Only initialize components when needed:
582+
583+```go
584+type model struct {
585+ preview *PreviewComponent // nil until needed
586+ previewPath string
587+}
588+
589+func (m *model) showPreview(path string) {
590+ if m.preview == nil {
591+ m.preview = NewPreviewComponent()
592+ }
593+ m.preview.Load(path)
594+}
595+```
596+
597+### Component Communication
598+
599+Use Bubbletea commands to communicate between components:
600+
601+```go
602+type fileSelectedMsg struct {
603+ path string
604+}
605+
606+// In list component Update
607+case tea.KeyMsg:
608+ if key.Matches(msg, m.keymap.Enter) {
609+ selectedFile := m.list.SelectedItem()
610+ return m, func() tea.Msg {
611+ return fileSelectedMsg{path: selectedFile.Path()}
612+ }
613+ }
614+
615+// In main model Update
616+case fileSelectedMsg:
617+ m.preview.Load(msg.path)
618+ return m, nil
619+```
620+
621+## Best Practices
622+
623+1. **Keep components focused** - Each component should have one responsibility
624+2. **Use bubbles package** - Don't reinvent standard components
625+3. **Lazy initialization** - Create components when needed, not upfront
626+4. **Proper sizing** - Always pass explicit width/height to components
627+5. **Clean interfaces** - Components should expose minimal, clear APIs
628+
629+## External Dependencies
630+
631+**Core Charm libraries:**
632+```
633+github.com/charmbracelet/bubbletea # Framework
634+github.com/charmbracelet/lipgloss # Styling
635+github.com/charmbracelet/bubbles # Standard components
636+```
637+
638+**Extended functionality:**
639+```
640+github.com/charmbracelet/glamour # Markdown rendering
641+github.com/charmbracelet/huh # Forms
642+github.com/alecthomas/chroma/v2 # Syntax highlighting
643+github.com/evertras/bubble-table # Interactive tables
644+github.com/koki-develop/go-fzf # Fuzzy finder
645+```
646+
647+See `go.mod` in template for complete list of optional dependencies.
.opencode/skills/bubbletea/references/emoji-width-fix.md+295−0
@@ -0,0 +1,295 @@
1+# Emoji Width Alignment Fix for Terminal UIs
2+
3+**Date:** 2025-10-27
4+**Source:** TFE project debugging session
5+**Issue:** Emoji alignment breaks in WezTerm/Termux but works in Windows Terminal
6+
7+---
8+
9+## The Problem
10+
11+Some emojis with variation selectors (U+FE0F) render inconsistently across terminals:
12+
13+| Emoji | Windows Terminal | WezTerm/Termux | Result |
14+|-------|------------------|----------------|--------|
15+| ⬆️ (U+2B06 + U+FE0F) | 2 cells | 1 cell | Misalignment |
16+| ⚙️ (U+2699 + U+FE0F) | 2 cells | 1 cell | Misalignment |
17+| 🗜️ (U+1F5DC + U+FE0F) | 2 cells | 1 cell | Misalignment |
18+| 📦 (U+1F4E6) | 2 cells | 2 cells | ✅ Aligned |
19+
20+**Symptom:** File names with narrow emojis shift left by 1 space, breaking column alignment.
21+
22+---
23+
24+## Root Causes
25+
26+### 0. XTerm Terminals Require unicode11
27+
28+**For xterm-based terminals:** Must configure go-runewidth properly:
29+
30+```go
31+import "github.com/mattn/go-runewidth"
32+
33+// Required initialization for xterm terminals
34+// Without this, xterm won't handle emoji widths correctly
35+```
36+
37+### 1. go-runewidth Bug #76 (Open since Feb 2024)
38+
39+**Issue:** Variation Selectors incorrectly report width = 1 instead of 0
40+
41+```go
42+// WRONG: go-runewidth bug
43+runewidth.StringWidth("⬆️") // Returns 2 (base=1 + VS=1)
44+// Should return 1 (base=1 + VS=0)
45+```
46+
47+This causes padding calculations to fail:
48+- Code thinks "⬆️" is already 2 cells wide
49+- No padding added
50+- Terminal renders as 1 cell
51+- Result: 1 space misalignment
52+
53+### 2. Terminal Rendering Differences
54+
55+Different terminals handle emoji + variation selector differently:
56+- **Windows Terminal:** Honors VS-16 → renders as 2 cells (colorful, wide) - slightly different handling
57+- **WezTerm/Termux:** Ignores VS-16 for width → renders as 1 cell - **need identical fixes**
58+- **xterm:** Requires unicode11 configuration (see above)
59+- **Kitty:** Actively adjusts width based on VS
60+
61+**No standard exists** - Unicode only defines width at codepoint level, not grapheme level.
62+
63+---
64+
65+## The Fix
66+
67+**Strategy:** Strip variation selectors before width calculation AND before display in affected terminals.
68+
69+### Implementation
70+
71+```go
72+// In your width calculation function (strips ANSI codes first)
73+func visualWidth(s string) int {
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/bubbletea/references/golden-rules.md+393−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/bubbletea/references/troubleshooting.md+698−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/build-tui-view/SKILL.md+1968−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/SKILL.md+113−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/concurrency.md+328−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/error-handling.md+337−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/patterns.md+264−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/security.md+398−0
Cut short: this commit's diff is over 1000 lines.
.opencode/skills/go-skills/testing.md+357−0
Cut short: this commit's diff is over 1000 lines.