Troubleshooting

"Device not configured" (os error 6)

Cause: stdin is not attached to a real TTY.

Common failure cases:

./app > output.log
printf '' | ./app

Run in an interactive terminal session instead.

Terminal Left in Raw Mode After Crash

If the process dies hard (kill -9, OOM, host crash), cleanup hooks do not run.

Recovery in the same terminal:

reset
# or
stty sane

Blank Screen / No Visible Output

Check these first:

1. Root component renders visible content (not null)
2. App is in a real TTY
3. Terminal emulator supports alternate screen mode

Input Not Responding

Checklist:

• process.stdin.isTTY === true
• In React mode, use render() (it starts input parser + app lifecycle)
• In raw-buffer mode, create a TerminalGuard before your loop

Mouse Events Not Firing

• React mode enables mouse tracking by default
• Raw-buffer mode needs new TerminalGuard(true)
• Confirm your terminal supports SGR mouse tracking (1006)

Paste Not Routed to usePaste

Routing behavior is intentional:

• If one or more active usePaste listeners exist, paste goes to usePaste
• Otherwise, paste falls back to useInput

In raw-buffer mode, bracketed paste requires new TerminalGuard(true).

Scrolling Content Moves Sibling UI Unexpectedly

If you use negative margins to "scroll" a child, Yoga shifts layout instead of clipping.

Use data slicing instead:

const visible = items.slice(scroll.offset, scroll.offset + viewportHeight);

Text Wraps Unexpectedly

Text currently wraps to available layout width. There is no Text wrap="..." API in @visulima/tui.

If output looks wrong, check parent width constraints (Box width, padding, border, etc.).

Wide Unicode/Emoji Alignment Issues

@visulima/tui uses width-aware rendering for full-width characters (CJK and many emoji) and marks continuation cells explicitly in the buffer/diff pipeline.

If alignment still looks off, it's usually due to terminal-specific grapheme behavior (some ZWJ emoji clusters). For strict layout-sensitive UIs, prefer single-codepoint glyphs over complex emoji sequences.

renderToString Output Surprises

renderToString is synchronous and returns a plain string snapshot.

• useLayoutEffect updates can affect output
• useEffect async follow-up updates do not affect returned output