From e2919eef185ae0fcf4d0ceb9bf35c76324ba206c Mon Sep 17 00:00:00 2001
From: Andrew Yim <ourdigital@Andy-MacMini-PRO.local>
Date: Fri, 20 Mar 2026 23:43:02 +0900
Subject: [PATCH] feat(tui-designer): add line input mode pattern and gotchas

New section covering read_line() for text input in raw-mode TUI,
with implementation pattern and 5 gotchas from real usage.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 custom-skills/93-tui-designer/code/SKILL.md | 40 +++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/custom-skills/93-tui-designer/code/SKILL.md b/custom-skills/93-tui-designer/code/SKILL.md
index 6d563cf..572160a 100644
--- a/custom-skills/93-tui-designer/code/SKILL.md
+++ b/custom-skills/93-tui-designer/code/SKILL.md
@@ -169,6 +169,46 @@ selector = ListSelector(
 - Sections headers group items visually
 - Callable headers re-evaluate on each render (for dynamic "Active:" display)
 
+## Line Input Mode
+
+For screens requiring text input (file paths, names, search), use `read_line()`:
+
+```python
+from myapp.tui.input import read_line
+
+# In a key_handler:
+def handle_my_key(app, key):
+    if key == "p":
+        app.console.print("Enter file path: ", end="")
+        path = read_line()
+        if path is None:  # Escape pressed
+            return True
+        # Use the path...
+        return True
+```
+
+### Implementation pattern
+
+```python
+def read_line(prompt: str = "") -> str | None:
+    """Read a full line in raw mode. Returns None on Escape/Ctrl-C."""
+    # Uses tty.setraw() same as read_key()
+    # Accumulates chars in buffer, prints each as typed
+    # Handles: Enter (return string), Escape (return None),
+    #          Ctrl-C (return None), Backspace (delete last)
+    # Escape sequences (arrow keys pressed during input) are consumed and ignored
+```
+
+### Line Input Gotchas
+
+| Gotcha | Problem | Fix |
+|--------|---------|-----|
+| Pasted paths with quotes | Users paste `'/path/to/file'` with quotes | Strip outer quotes: `path.strip("'\"")`  |
+| Tilde expansion | `~/.config/...` not expanded | Use `Path(path).expanduser()` |
+| Raw mode echo | Characters not visible while typing | Manually `sys.stdout.write(ch)` each keystroke |
+| Escape during input | Arrow keys produce garbage in buffer | Detect `0x1B`, consume rest of sequence, ignore |
+| Module-level imports for testability | `import select` inside function can't be patched | Import `select`, `termios`, `tty` at module level (in `try/except`) |
+
 ## Bilingual i18n
 
 Simple dict registry — no framework needed: