termcast-tui-patterns

Documents termcast component APIs and PTY snapshot testing patterns for terminal UIs.

Updated Aug 2, 2026
One-click install
npx skills add https://github.com/leonardoacosta/skills --skill termcast-tui-patterns-leonardoacosta
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: termcast-tui-patterns
Source: https://github.com/leonardoacosta/skills/tree/main/runtime-kit/skills/termcast-tui-patterns
Command: npx skills add https://github.com/leonardoacosta/skills --skill termcast-tui-patterns-leonardoacosta

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Building terminal UIs with termcast (the Raycast extension API ported to the terminal via @opentui/react and Bun) involves non-obvious rules — accessory alignment laws, cache invalidation after mutations, Bun's duplicate-React crash — and testing a TUI requires driving a real pseudo-terminal, which most developers have never done. ## Core Features & Use Cases - Component API Reference: Covers List/Detail/Form/ActionPanel usage, the accessory-alignment law, useCachedPromise with revalidate(), Cache vs LocalStorage, and the Bun explicit-react-dependency gotcha. - PTY E2E Testing Guide: Explains how to write mock-data *-demo.tsx variants, launch a PTY session with tuistory's launchTerminal, drive it with press/type, and assert golden frames with toMatchInlineSnapshot. - Use Case: You are scaffolding a termcast project and your List rows render with misaligned columns. Load the component-api reference to learn that every List.Item must carry the same number of accessories in the same order, then fix the layout and lock it in with an inline snapshot test. ## Quick Start Ask the agent to load the termcast component API reference and explain why your List.Item accessories are misaligned.

Frequently Asked Questions about termcast-tui-patterns

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I test a terminal UI built with termcast?

Write a mock-data *-demo.tsx variant of your command that calls renderWithProviders at module scope, then launch it in a real pseudo-terminal with tuistory's launchTerminal. Drive the session with press and type, wait for expected text, and assert the rendered frame with toMatchInlineSnapshot.

Why are my termcast List accessories misaligned across rows?

Every List.Item in a List must carry the same number of accessories in the same order, because the renderer lays out accessory columns positionally. When an accessory is conditionally absent, render a placeholder entry instead of omitting it.

How do I refresh data after a mutation in termcast?

Call revalidate() from useCachedPromise after every mutation, since the cache does not know a write happened. Polling on an interval complements revalidate but does not replace it, because waiting for the next poll leaves the UI stale.

Why does useSyncExternalStore crash in my Bun termcast app?

The crash comes from two React copies in one process when react is resolved transitively through termcast or @opentui/react. Add react as an explicit dependency in package.json so Bun deduplicates it to a single instance.

When should I use LocalStorage instead of the cache in termcast?

Use LocalStorage for durable key-value state that must survive process restarts, such as selected team or last-used filter. Use the useCachedPromise cache only for ephemeral data derived from live fetches that can be cheaply re-fetched.