perry/tui: ink-API ergonomics layer (useState, useEffect, useApp, JSX, source-compat)

[proggeramlug]

Background

`perry/tui` (#358, closed) already ships a complete native TUI engine inside `perry-runtime/src/tui/` — taffy-based flexbox, double-buffered ANSI diff with cell-level dirty tracking, ~3K LOC, zero npm deps. Widget set: `Box`/`Text`/`Spacer`/`Input`/`TextArea`/`List`/`Select`/`Spinner`/`ProgressBar`/`Table`/`Tabs`. Reactivity ships as `state(initial)` with `.get()`/`.set()` plus a global STATE_DIRTY flag that re-renders on change.

This issue covers what's left to make `perry/tui` feel like ink to authors — same hooks, same prop names, JSX-friendly — so ink's mental model and AI tools' code-generation habits transfer with minimal friction. The engine is done. This is API polish + missing hooks.

This is the recommended first-party TUI path; ink-via-`compilePackages` (#348) becomes a compiler smoke test only.

Goal

An ink program of the shape below compiles via `perry compile` with a one-line import change (`from 'ink'` → `from 'perry/tui'`) and runs natively:

```tsx
import { Box, Text, useState, useInput, useApp, render } from "perry/tui";

function App() {
const { exit } = useApp();
const [n, setN] = useState(0);
useInput((ch) => {
if (ch === "+") setN(n + 1);
if (ch === "-") setN(n - 1);
if (ch === "q") exit();
});
return count: {n};
}

render();
```

What ships today vs what's missing

Surface	Today	ink-shape target
`Box` / `Text` / `Spacer`	✅	✅
`Input` / `TextArea` / `List` / `Select` / `Spinner` / `ProgressBar` / `Table` / `Tabs`	✅	✅
flexbox props (`flexDirection`/`justifyContent`/`alignItems`/`gap`/`padding`/`flexGrow`|`Shrink`|`Basis`/pct)	✅	✅
`render(root)` / `enter` / `exit`	✅	✅
`useInput(handler)`	✅	✅
`state(initial)` builder	✅	Alias / wrap as `useState`
`useEffect(fn, deps)`	❌	Run after mount + on dep change; cleanup on unmount/dep-change
`useApp() → { exit, ... }`	❌	Imperative `exit()` from inside components
`useStdout() → { write, columns, rows }`	❌	Surface terminal dims, raw write escape hatch
`useFocus() → { isFocused }` + ``	❌	Tab navigation between focusable widgets
`useMemo(fn, deps)` / `useRef(initial)`	❌	Standard hook surface
JSX as authoring surface	⚠️ partial	``/`` lower to `Box(...)`/`Text(...)` — audit
Text styling props (`color`, `bgColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`)	partial	parity with ink
Source-compat test suite	❌	5–10 small real-world ink programs as regression tests

Phases

Phase 1 — Hook API parity (highest leverage)

• `useState(initial)` — alias to existing `state()` builder, but match React signature: returns `[value, setter]` tuple, not `{ get, set }` object. Internal slot allocation reuses `js_perry_tui_state_alloc`.
• `useEffect(fn, deps?)` — runs after first render; if `deps` change between renders, re-runs (after running prior cleanup); cleanup returned from `fn` runs on unmount. Wire to render loop's frame boundary.
• `useApp()` — returns `{ exit(code?), waitUntilExit() }`. `exit` flips a global flag the run loop checks at frame top.
• `useStdout()` — returns `{ write(str), columns, rows }`. `write` for escape-hatch raw output; columns/rows from current terminal dims.
• `useMemo(fn, deps)` / `useRef(initial)` — small additions, same slot machinery as `useState`.

Phase 2 — JSX audit + ergonomics

• Verify `<Box flexDirection="row" gap={1}>...` lowers correctly through SWC's JSX transform to `Box({ flexDirection: "row", gap: 1, children: [...] })`.
• Confirm children are passed through as an array, not spread positionally.
• Document the JSX pragma / tsconfig setup for `perry/tui` in CLAUDE.md.

Phase 3 — Focus + keyboard navigation

• `useFocus({ autoFocus?, isActive? })` — register the calling widget with a focus manager.
• `` / `useFocusManager()` — Tab/Shift-Tab cycles focused widget; focused widget gets keypress events from `useInput`.
• Required for any form-style ink program.

Phase 4 — Source-compat test suite

• Take 5–10 small ink programs from the wild (counter, todo list, file picker, multi-step prompt, log viewer). Patch `from 'ink'` → `from 'perry/tui'`. Each compiles + runs + matches expected output. Lives in `test-files/test_perry_tui_inkcompat_*.ts`.
• This is the acceptance gate — "ink-shape" is real when these compile.

Phase 5 — Text styling parity

• Audit `<Text color="red" bold italic>`, ``, ``, `` against ink behavior. Should already mostly work via existing style.rs; this is a parity audit + filling in gaps.

Out of scope (deliberately)

• React-reconciler compat — we don't ship a fiber tree, the architectural avoidance is the whole point of `perry/tui` (perry/tui: native TUI engine (zero-flicker, double-buffered, cell-level dirty tracking) #358).
• Class components — ink dropped them too.
• Devtools panel — ink's dynamic-import dependency.
• `` ink component — niche, only needed for append-only scrolling output; defer.
• Hooks-rules linting ("no hooks in conditionals") — we can reject loudly at compile time later if needed; not v1.

Acceptance

• Phase 1 ships → counter program above (one-line import change from ink) compiles + runs interactively, matches expected behavior.
• Phase 4 ships → all source-compat test programs green.

Related

• perry/tui: native TUI engine (zero-flicker, double-buffered, cell-level dirty tracking) #358 — engine umbrella (closed, this builds on top)
• TUI gap: readline + tty.setRawMode + raw-mode stdin reader #347 — TUI primitives (closed, dependency)
• Compile ink (React-based TUI framework) end-to-end via perry.compilePackages #348 — ink-via-compilePackages (open, deprioritized to smoke-test-only — sibling track, not blocked-by)
• ink-as-compilePackages — Phase B follow-ups after #348 CJS support landed #360 — closed; this is its successor for TUI investment.

[proggeramlug]

Closing summary

All 5 phases shipped. Main landing in v0.5.810 (01a524bb), follow-ups in v0.5.812 (d2a3e07e — GC roots for hook + state slot pools) and v0.5.818 (4d852de9 — runtime-array Box children + GC root completion, surfaced building a Claude-Code-style chat demo).

What shipped

• Phase 1 — Hook API parity. useState (tuple destructuring via crates/perry-hir/src/destructuring.rs::rewrite_use_state_tuple), useEffect, useMemo, useRef (+ get/set), useApp (+ exit/waitUntilExit), useStdout (+ write/columns/rows). All FFIs in crates/perry-runtime/src/tui/hooks.rs. Slot pool is call-site-indexed; tui/run.rs resets the index at every frame so re-renders read the same slot.
• Phase 2 — JSX audit. User-component dispatch (<App />) works via js_jsx recognising the closure pointer. Built-in widget intrinsics (<Box>/<Text>) deferred — see follow-up below.
• Phase 3 — Focus + keyboard navigation. useFocus, Tab/Shift-Tab cycling in tui/input.rs::drain_input calling super::hooks::js_perry_tui_focus_next/previous before forwarding bytes to the user handler.
• Phase 4 — Source-compat test suite. Seven ink-compat programs: test_perry_tui_inkcompat_{counter,useapp,useeffect,usefocus,usememo,useref,usestdout}.ts.
• Phase 5 — Text styling parity. DIM + STRIKETHROUGH added; existing color / bold / italic / underline / inverse audited.

Acceptance gate hit

The counter program from the issue's acceptance section compiles with one-line from 'ink' → from 'perry/tui' swap and runs interactively (+ / - / q).

Tests

13 unit tests in tui::hooks + 7 ink-compat programs + 3 issue-679 audit files (test_issue_679_perry_tui_{hooks,jsx_audit,text_styling}.{ts,tsx}) + 2 follow-up regression tests (test_issue_679_box_runtime_children.ts, test_issue_679_useState_gc_root.ts). All green.

Single deferred follow-up

JSX with built-in <Box>/<Text> intrinsics (Phase 2 partial). Today <Box flexDirection="row"><Text>...</Text></Box> lowers to jsx(Box, props) and falls through to TAG_UNDEFINED because js_jsx doesn't recognise the Box/Text function-pointer constants. Fix is a compile-time recogniser in crates/perry-codegen/src/lower_call/native.rs that pattern-matches Call { callee: ExternFuncRef("jsx"/"jsxs"), args: [ExternFuncRef("Box"/"Text"), props, ...] } and rewrites to a direct Box(opts, children) / Text(content, opts) call. Tracked as a discrete issue.

Workaround documented in test-files/test_issue_679_perry_tui_jsx_audit.tsx: stay on function-call form (Box({ flexDirection: "row" }, [Text("hi")])) for Box/Text intrinsics. User-component JSX (<App />) works.