Compile `ink` (React-based TUI framework) end-to-end via `perry.compilePackages`

[proggeramlug]

Tracking issue for landing ink (https://github.com/vadimdemedes/ink) as a perry.compilePackages target. Surfaced in discussion #333 (TUI/CLI support) — the consensus there was that for full-screen TUIs, building a Perry-native ncurses-style framework is a lot of surface for a niche audience. ink is the modern, actively-maintained, React-based replacement for blessed / react-blessed and is what most new TS TUIs in 2025–2026 are built on (gh-copilot, claude-code, opencommit, etc.). Wiring it as a compilePackages target gives Perry users a maintained TUI library without reinventing the wheel.

Depends on

• TUI gap: readline + tty.setRawMode + raw-mode stdin reader #347 — readline + tty.setRawMode + raw-mode stdin + tty.isatty + process.stdout.columns/rows + SIGWINCH. Ink can't render anything useful until at least Phase 1 + Phase 2 of TUI gap: readline + tty.setRawMode + raw-mode stdin reader #347 land.

Scope

End-to-end means: a user does npm install ink react, adds \"compilePackages\": [\"ink\", \"react\"] to package.json, writes a standard ink program, runs perry compile app.tsx -o app && ./app and gets an interactive TUI binary.

The unknowns split into three buckets:

1. React itself — Perry already ships perry-react (github.com/PerryTS/react) as a native-widget React (compiles JSX to AppKit / UIKit / Android widgets), which is not the same as ink's use case. Ink uses upstream react + react-reconciler + a custom renderer that emits ANSI to the terminal. Open question whether perry-react's React infra can be reused for ink's reconciler-as-consumer pattern, or whether DOM-style React needs to compile via compilePackages independently.
2. Yoga layout — ink uses yoga-layout for flexbox layout in text. Yoga is traditionally a C++ lib; current yoga-layout has both a native-binding fork and a pure-JS fork. Either path needs evaluation: link libyoga natively (cross-compile story for every Perry target) vs. compile the JS port via compilePackages.
3. ANSI utility deps — chalk, cli-cursor, cli-truncate, slice-ansi, string-width, strip-ansi, wrap-ansi, ansi-escapes, etc. Mostly thin string-manipulation wrappers; the gap (if any) is likely individual TS-subset features each one trips over, which is the standard compilePackages shake-out.

Acceptance

• A 30-line ink program (counter component with keyboard input — increment on +, decrement on -, quit on q) compiles via perry compile, produces a single-file native binary, runs interactively, and matches ink running under node --experimental-strip-types byte-for-byte (modulo terminal cursor positioning timing).
• The ink "todo list" example (https://github.com/vadimdemedes/ink#examples) compiles and runs end-to-end.
• Whatever shake-out fixes are needed in perry-codegen / perry-stdlib to make the dependency tree compile cleanly, land them under this issue's umbrella.

Out of scope (separate follow-ups)

• inquirer / prompts / other prompt-style libs — those are simpler (line-buffered only) and TUI gap: readline + tty.setRawMode + raw-mode stdin reader #347's Phase 1 unblocks them directly without ink.
• blessed / react-blessed — older, flakier, not the recommended path. Documenting why we picked ink over blessed is enough.
• A Perry-native TUI framework written from scratch — would be a bigger lift than wiring ink and competes with a maintained library; skip unless ink turns out to be unworkable.

Discussion: #333. Primitives: #347.

[proggeramlug]

Scoping pass — findings (worktree issue-348-ink-compile)

Built a minimal ink sandbox (<Text>hello from ink</Text> with no input) on Perry 0.5.427, attempted perry compile index.tsx -o app with compilePackages: ["ink", "react"]. Compile got all the way to the linker (parsing, HIR, codegen, and per-module .o emission all succeeded for both ink and react) — every failure is at link time as Undefined symbols for architecture arm64. That's the good news: nothing in the compile pipeline rejects ink-shaped TS-subset code outright; the failures are about specific runtime shapes Perry isn't wired for.

Blocker #1 (the one that matters): React 18 is CommonJS

node_modules/react/index.js is the canonical CJS env-switch:

'use strict';
if (process.env.NODE_ENV === 'production') {
  module.exports = require('./cjs/react.production.min.js');
} else {
  module.exports = require('./cjs/react.development.js');
}

Perry's verbose output confirms what it does with that shape:

Warning: unknown identifier 'require' — assuming global; member access will dispatch by name at runtime, bare reads lower to 0
Warning: unknown identifier 'module' — assuming global; member access will dispatch by name at runtime, bare reads lower to 0

So react/index.js compiles to a no-op module with zero exports. Every downstream import { createContext, useContext, useEffect, useMemo, forwardRef } from "react" then resolves to _perry_fn_node_modules_react_index_js__<name> symbols that were never emitted, producing the bulk of the link errors:

"_perry_fn_node_modules_react_index_js__createContext"
"_perry_fn_node_modules_react_index_js__forwardRef"
"_perry_fn_node_modules_react_index_js__useContext"
"_perry_fn_node_modules_react_index_js__useEffect"
"_perry_fn_node_modules_react_index_js__useMemo"
... (and more from ink hooks)

CJS support exists in perry-jsruntime (the V8 fallback — crates/perry-jsruntime/src/modules.rs:473 is_commonjs, :481 wrap_cjs_as_esm, :476 heuristic on module.exports) but the native compilePackages pipeline doesn't have a CJS path. perry-hir/src/lower.rs:1710 actually documents the intended workaround for vanilla-react: alias react → perry-react via packageAliases. But perry-react is the native-widget React (compiles JSX to AppKit/UIKit), not a DOM-style React with useState/useEffect/createContext — which is what ink's reconciler depends on. So the existing aliasing path doesn't help here; ink needs vanilla React semantics.

Three paths forward, in increasing order of ambition:

1. --enable-js-runtime for ink — works today, no Perry changes needed, but adds 10–15 MB and defeats the "single-file native binary" pitch.
2. Vendor an ESM-shimmed vanilla React — hand-author or auto-generate @perry/react-vanilla that re-exports React's APIs as ESM (export const useState = ...), pre-bundled from react.production.min.js. Document packageAliases: {"react": "@perry/react-vanilla"} as the standard recipe. Medium effort. The shim has to track React releases.
3. Native CJS support in compilePackages — port the heuristic + wrapper from perry-jsruntime/src/modules.rs:481 into perry-codegen-js (or wherever ESM module-shape detection lives in the native pipeline). Large, but unblocks the entire CJS half of npm — react, react-dom, react-reconciler, scheduler, lots of older libs that haven't gone ESM-first yet. Highest leverage.

I'd lean on option 3 if there's appetite for the work — CJS interop is going to come up again and again as more users try compilePackages on real npm trees, not just hand-picked TS-source packages. Option 2 is the pragmatic interim.

Blocker #2: process import resolution from inside node_modules

Perry can't resolve import process from "node:process" (or the equivalent bare import process from "process") when it appears in a compilePackages target:

Warning: Could not resolve import 'process' from render.js
Warning: Could not resolve import 'process' from ink.js
Warning: Could not resolve import 'process' from reconciler.js
Warning: Could not resolve import 'process' from App.js
Warning: Could not resolve import 'process' from StdinContext.js
Warning: Could not resolve import 'process' from StdoutContext.js
Warning: Could not resolve import 'process' from StderrContext.js
Warning: Could not resolve import 'process' from ErrorOverview.js

process.argv / process.env work fine when accessed as the implicit global from user code. But ink's modules import process explicitly. Perry's stdlib already implements the process surface; it just needs the import path to map to it. Smaller scope than blocker #1 — should be a focused stdlib-resolver fix.

Blocker #3: Dynamic import()

Warning: Dynamic import('./devtools.js') not fully supported, returning undefined

ink does a runtime import("./devtools.js") to lazy-load its devtools panel. The cosmetic fix is wrapping the call in try/catch and treating undefined as "devtools off"; the real fix is wiring dynamic-import support in the native compiler. Not a blocker for static rendering — just means devtools won't work.

Blocker #4: Bare-identifier downstream noise

Warning: unknown identifier 'props' / 'style' / 'customId' / 'autoFocus' / 'isActive' / 'showCursor'

I'm not sure yet if these are independent issues or downstream symptoms of React not loading (React's PropTypes / hook returns being undefined → destructuring patterns silently failing). Worth re-checking once #1 is solved; might just disappear.

Out of scope from this scoping pass

• Yoga layout — didn't even reach the yoga-loading code path because compile died upstream on React. Yoga is ~3.2.1, native-binding-or-WASM, and is its own substantial chunk of work. Will surface as the next blocker once React is unblocked.
• react-reconciler — same. Couldn't observe its compile failure shape because the upstream React shape failed first.
• TUI interactivity — gated on TUI gap: readline + tty.setRawMode + raw-mode stdin reader #347, separate concern.

Recommendation for #348

Don't try to fix everything in one PR. Phase the work:

• Phase 0 (this work): scoping done.
• Phase A: decide on path 1 / 2 / 3 above for React. If path 3 (native CJS), it's its own tracking issue probably under a new umbrella since it benefits much more than just ink. If path 2 (ESM shim), file as a sub-issue and the work is contained.
• Phase B: fix process import resolution in compilePackages (blocker linux compilation and README #2).
• Phase C: dynamic import() workaround/fix (blocker Using the fetch API #3).
• Phase D: retry compile with React resolved → first look at yoga + reconciler.
• Phase E: TUI gap: readline + tty.setRawMode + raw-mode stdin reader #347 lands → first look at interactivity.

Worktree state: branch worktree-issue-348-ink-compile, sandbox at test-files/ink-sandbox/, no Perry source changes. I'll keep the worktree around for follow-up work; happy to throw it away if the maintainer prefers a clean slate per phase.