runtime: OpenTUI dependencies fail on standard Node.js after build fix

[li-xiu-qi]

Problem

After applying the build fix from #28 (which resolves the missing createLocalTuiClientApp export), step still cannot start the TUI on a standard Node.js runtime. Two separate upstream-related errors appear depending on how the entrypoint is run.

Environment

• step-realtime-cli version: 1.0.0
• Node version: v22.14.0
• OS: Linux (Ubuntu / WSL)
• Package manager: pnpm 10.17.0
• OpenTUI packages: @opentui/core@0.1.90, @opentui/react@0.1.90

Error 1: built dist path

When dist/ is present and bin/step-cli.js resolves to dist/index.js:

$ step
step-cli error: Cannot find module 'react-reconciler/constants' imported from .../@opentui/react/chunk-tq1yd1rw.js
Did you mean to import "react-reconciler/constants.js"?

Root cause: @opentui/react (ESM package) imports from react-reconciler/constants without the .js extension. Node.js's ESM loader cannot resolve the subpath without an explicit extension because react-reconciler does not expose a conditional exports map for /constants.

Error 2: tsx source path

When dist/ is removed and bin/step-cli.js falls back to tsx src/index.ts:

$ rm -rf dist && node bin/step-cli.js
step-cli error: Only URLs with a scheme in: file, data, and node are supported by the default ESM loader. Received protocol 'bun:'

Root cause: @opentui/core@0.1.90 depends on bun-webgpu@0.1.5, which contains unconditional bun: protocol imports. On standard Node.js (not Bun) these imports cannot be resolved. The bun-webgpu package is pulled in as a transitive production dependency:

@opentui/core 0.1.90
└── bun-webgpu 0.1.5

Impact

With the current dependency versions, the interactive TUI cannot be launched on a stock Node.js installation. This blocks the default bash scripts/setup.sh → step workflow for users who are not running Bun.

Mitigation

• fix(setup): prefer Linux-native Bun on WSL and respect STEP_BUN_BIN #37 updates scripts/setup.sh to prefer a Linux-native Bun and install the Bun-compiled native binary. When that PR is merged, the default installer path on WSL will produce a working launcher as long as a Linux Bun is available.
• Until the upstream OpenTUI packages are made Node-compatible, TUI mode should be considered Bun-only.

Related

• build: bundled OpenTUI chunk is empty, step fails with createLocalTuiClientApp not exported #25 (the build-time chunk issue)
• fix(build): emit OpenTUI runtime chunk and build agent-sdk #28 (PR that fixes the build-time chunk issue and exposes these runtime issues)
• setup: WSL installer picks Windows Bun and produces a non-working binary / Node launcher #36 (installer WSL Bun detection issue)
• fix(setup): prefer Linux-native Bun on WSL and respect STEP_BUN_BIN #37 (installer WSL Bun detection PR)

[li-xiu-qi]

Update after deeper investigation:

The TUI cannot run on standard Node.js because @opentui/core / @opentui/react are Bun-built packages. They rely on Bun-only APIs such as bun:ffi and bun-webgpu, so running step under Node.js will always fail at the OpenTUI layer.

On this machine, bun is available at /mnt/c/nvm4w/nodejs/bun (a Windows-installed Bun inside WSL). Using Bun as the runtime resolves the OpenTUI loading errors.

One extra WSL-specific wrinkle: Windows-installed Bun resolves os.homedir() to C:\Users\ke, whereas Node/WSL resolves it to /home/ke. This means ~/.step-cli/config.json must also be present at C:\Users\ke\.step-cli\config.json for Bun to find it.

Current working setup

1. Apply the build fix from fix(build): emit OpenTUI runtime chunk and build agent-sdk #28 (or rebuild from the PR branch).
2. Use the launcher script that invokes bun and mirrors the config to the Windows home path.
3. Run step normally.

Long-term options

• Document that the TUI requires Bun (currently the README only mentions Bun for Windows native compilation).
• Wait for / help upstream OpenTUI become Node.js-compatible.
• Consider an alternative TUI renderer for Node.js users.

[li-xiu-qi]

Another WSL + Windows Bun issue when launching TUI:

step-cli error: Failed to initialize OpenTUI render library: Failed to open library "\\wsl.localhost\Ubuntu-22.04\home\ke\projects\Step-Realtime-CLI\node_modules\@opentui\core-win32-x64\opentui.dll": error code 126

Context

After switching the launcher to Bun (to satisfy OpenTUI's Bun-only runtime requirements), the TUI now reaches the native renderer initialization stage. However, Bun (installed from Windows) tries to load @opentui/core-win32-x64/opentui.dll using a WSL UNC path (\\wsl.localhost\...).

Error 126 meaning

Windows error code 126 is ERROR_MOD_NOT_FOUND. This usually means either the DLL itself cannot be found at the given path, or (more likely) one of its runtime dependencies cannot be resolved. Native Windows DLLs loaded from WSL UNC paths can fail to resolve dependencies such as the Microsoft Visual C++ Redistributable.

Possible fixes

1. Install/ repair Microsoft Visual C++ Redistributable on Windows and retry.
2. Move the project to a native Windows path (e.g., C:\Users\ke\projects\Step-Realtime-CLI) so the DLL is loaded from a normal Windows path rather than a WSL UNC path.
3. Run the TUI directly on Windows (outside WSL) with a Windows-native Bun installation.

Note

Until this is resolved, the CLI mode still works.

[ZouR-Ma]

Thanks for opening this!

We've set up a contribution workflow. If anything is missing (repro steps, version, environment, logs), please refile using one of our templates:

https://github.com/stepfun-ai/Step-Realtime-CLI/issues/new/choose

For logs, run with LOG_LEVEL=debug.

If you'd like to fix it yourself, open a PR referencing this issue with Closes #<number>.

See:
https://github.com/stepfun-ai/Step-Realtime-CLI/blob/main/CONTRIBUTING.md

[Lion-1209]

Adding a 0.4.4 datapoint — the analysis on #29 / #78 is all based on 0.1.90, so I tested the latest @opentui/core / @opentui/react@0.4.4 on Windows native Node. The picture differs from 0.1.90 in a meaningful way.

Env: Windows 11, Node v24.13.0, no Bun installed, isolated dir with npm install @opentui/core@latest @opentui/react@latest (not in-repo, to avoid polluting the workspace).

0.4.4 vs 0.1.90:

Layer	0.1.90	0.4.4
bun:ffi / .scm / bun-webgpu (the 0.1.90 blockers)	❌ pervasive, Node dies	✅ gone (index.js grep count = 0)
Module import	❌ fails at load	✅ imports cleanly, 256 exports loaded
react-reconciler/constants (#29 Error 1)	❌ fails	❌ still there; patchable by adding an exports map to react-reconciler (verified)
FFI rendering (createCliRenderer())	❌ Bun-only	❌ still Bun-only

Root cause at the FFI layer (unchanged in 0.4.4): 0.4.4 no longer uses bun:ffi directly — it depends on bun-ffi-structs@0.2.4, whose backend logic is if ("bun" in process.versions) → bun:ffi, else import("node:ffi"). Node has no node:ffi builtin, so rendering fails with OpenTUI native FFI is not available for this runtime yet.

bun-ffi-structs's error string mentions "Node.js with node:ffi enabled (--experimental-ffi --allow-ffi)", but those flags don't exist on Node v24 (node --experimental-ffi → bad option) — the docs are stale.

These are just datapoints from my local test, may not be comprehensive. Whether a 0.4.4 upgrade resolves #29, whether it should ride with #79, or whether a different direction (swapping the renderer) makes more sense — would value the maintainers' take.

One side note: 0.4.4 imports fine on Node, but react-reconciler/constants (#29 Error 1) is still present and needs an exports map on react-reconciler to work around — that would need to be handled together if upgrading.

---

补充一份 0.4.4 实测——之前 #29 / #78 的分析都基于 0.1.90,我测了一下最新的 @opentui/core/@opentui/react@0.4.4 在 Windows 原生 Node 下的表现,情况和 0.1.90 不太一样,值得拿出来对照。

环境:Windows 11,Node v24.13.0,未装 Bun,隔离目录 npm install @opentui/core@latest @opentui/react@latest(不在仓库内,避免污染)。

0.4.4 vs 0.1.90 对比:

层	0.1.90	0.4.4
bun:ffi / .scm / bun-webgpu(0.1.90 的拦路点)	❌ 满地都是,Node 直接挂	✅ 全没了(index.js grep 计数 0)
模块 import	❌ 加载层就炸	✅ 能 import,256 个 export 全加载
react-reconciler/constants(#29 Error 1)	❌ 挂	❌ 仍在;但给 react-reconciler 补个 exports map 就能绕过(实测验证)
FFI 渲染(createCliRenderer())	❌ Bun-only	❌ 仍 Bun-only

FFI 这层的根因(0.4.4 没改):0.4.4 不再直接用 bun:ffi,而是依赖 bun-ffi-structs@0.2.4,它的加载逻辑是 if ("bun" in process.versions) → bun:ffi,否则 import("node:ffi")。问题是 Node 没有 node:ffi 这个内置模块,所以渲染时报 OpenTUI native FFI is not available for this runtime yet。

bun-ffi-structs 的报错信息提到 "Node.js with node:ffi enabled (--experimental-ffi --allow-ffi)",但这两个 flag 在 Node v24 根本不存在(node --experimental-ffi → bad option),是过时文档。

这只是我本机实测的事实,不一定全面。升级到 0.4.4 能不能解决 #29、要不要配合 #79 一起推进、或者走别的方向(换渲染后端),想听下维护者的判断。

另外提一句:0.4.4 在 Node 下 import 没问题,但 react-reconciler/constants(#29 Error 1)还在,需要 react-reconciler 补 exports map 才能绕过——这块如果升级也得一起处理。