dev-guide-gotchas

Gotchas and Known Pitfalls

Nested lingtai-dev-guide reference. Read this after the top-level router sends you here. Collective wisdom from production incidents — each entry has caused at least one regression.

Bubble Tea v2: paste delivery

Bubble Tea v2 splits keys (tea.KeyPressMsg) from clipboard pastes (tea.PasteMsg). Any Update dispatcher handling case tea.KeyPressMsg: must also forward tea.PasteMsg to whichever text widget is focused, or paste silently drops.

For embedded sub-models (e.g. PresetEditorModel inside FirstRunModel), the host's outer default: branch must forward paste msgs into the sub-model. If the host's dispatcher enumerates focused widgets per-step but misses the step hosting an embedded model, paste dies before reaching it — and a fall-through inside the sub-model's own Update is useless because the msg never arrives.

Symptom: typing into an input works, pasting does nothing.

Fix: trace top-down (tea.Program → host's outer switch → sub-model's outer switch → widget) and ensure every layer handles or forwards tea.PasteMsg.

textarea vs textinput

textinput is single-line and drops characters on multi-byte / clipboard pastes; textarea handles paste cleanly. For any paste-friendly field (API keys, base URLs, anything pasted from a browser), use textarea even when the content is conceptually one line:

ta := textarea.New()
ta.CharLimit = 512
ta.SetWidth(50)
ta.SetHeight(1)
ta.ShowLineNumbers = false
ta.Prompt = ""
ta.KeyMap.InsertNewline.SetKeys() // single-line: no newline insertion
ta.SetStyles(themedTextareaStyles())

themedTextareaStyles() is in the tui package — always apply it. A bare textarea.New() ships dark default cursor/focus colors that render as a black smear against the warm LingTai theme.

Dev-mode rebuild gotcha (retired)

Project migrations are retired: production TUI/Portal no longer read, write, advance, or gate on .lingtai/meta.json, so a stale dev binary against a newer project no longer trips a data version N is newer than this binary supports gate. No meta.json version preflight is needed before replacing a local dev binary, and you never "fix" a project by editing meta.json downward — the file is inert. Rebuilding a fresh binary after ordinary code changes is still the right way to make main behaviour live; the only live migration surface left is the TUI's per-machine ~/.lingtai-tui/ registry (tui/internal/globalmigrate/), which runs at TUI startup and needs no paired portal bump.