From b99c27c13e7334caa2c50e5bbd569b77a97885c0 Mon Sep 17 00:00:00 2001 From: brettheap Date: Mon, 29 Dec 2025 18:32:32 -0400 Subject: [PATCH 1/2] fix(tui): enable threaded rendering to prevent UI freezing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enable useThread option in @opentui render config which moves native FFI rendering calls to a separate thread. This prevents the 6+ second event loop blocks that were occurring during normal typing due to synchronous Bun FFI calls. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- packages/opencode/src/cli/cmd/tui/app.tsx | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/opencode/src/cli/cmd/tui/app.tsx b/packages/opencode/src/cli/cmd/tui/app.tsx index 5214b0c1a9a..b26edcec85f 100644 --- a/packages/opencode/src/cli/cmd/tui/app.tsx +++ b/packages/opencode/src/cli/cmd/tui/app.tsx @@ -149,6 +149,7 @@ export function tui(input: { url: string; args: Args; onExit?: () => Promise Date: Mon, 29 Dec 2025 18:43:10 -0400 Subject: [PATCH 2/2] docs: add openspec proposal for TUI threaded rendering fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add structured proposal documenting the root cause (Bun FFI blocking) and solution (useThread: true) for the TUI freezing issue. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .../fix-tui-threaded-rendering/proposal.md | 34 +++++++++++++++++++ .../fix-tui-threaded-rendering/tasks.md | 13 +++++++ 2 files changed, 47 insertions(+) create mode 100644 openspec/changes/fix-tui-threaded-rendering/proposal.md create mode 100644 openspec/changes/fix-tui-threaded-rendering/tasks.md diff --git a/openspec/changes/fix-tui-threaded-rendering/proposal.md b/openspec/changes/fix-tui-threaded-rendering/proposal.md new file mode 100644 index 00000000000..50ffb265d0a --- /dev/null +++ b/openspec/changes/fix-tui-threaded-rendering/proposal.md @@ -0,0 +1,34 @@ +# Change: Enable Threaded Rendering to Fix TUI Freezing + +## Why + +The TUI freezes for 6+ seconds during normal typing, making the application unusable during these periods. Users experience complete input lag where keystrokes are not registered until the freeze ends. + +**Root Cause**: The @opentui native library makes FFI (Foreign Function Interface) calls to render the terminal UI. In Bun, FFI calls are synchronous and block the JavaScript event loop. The native rendering operations were taking ~6.5 seconds and occurring every ~5 seconds, causing periodic complete freezes. + +**Diagnosis Method**: Created a heartbeat-based diagnostic that detected event loop blocks by measuring gaps between expected 100ms intervals. The diagnostic confirmed consistent ~6.5 second blocks. + +## What Changes + +- Enable `useThread: true` in the @opentui render configuration +- This moves native FFI rendering calls to a separate thread, preventing them from blocking the JS event loop + +**Code Change** (1 line): +```typescript +// packages/opencode/src/cli/cmd/tui/app.tsx +render(component, { + targetFps: 60, + gatherStats: false, + exitOnCtrlC: false, + useThread: true, // Enable threaded rendering to avoid blocking the JS event loop + useKittyKeyboard: {}, + // ... +}) +``` + +## Impact + +- **Affected specs**: None (bug fix restoring expected behavior - TUI should not freeze) +- **Affected code**: `packages/opencode/src/cli/cmd/tui/app.tsx:152` +- **Risk**: Low - the `useThread` option is a supported @opentui feature +- **Testing**: Verified with perf diagnostics showing zero `[BLOCKED]` messages after fix diff --git a/openspec/changes/fix-tui-threaded-rendering/tasks.md b/openspec/changes/fix-tui-threaded-rendering/tasks.md new file mode 100644 index 00000000000..01f1c97bc28 --- /dev/null +++ b/openspec/changes/fix-tui-threaded-rendering/tasks.md @@ -0,0 +1,13 @@ +# Tasks: Enable Threaded Rendering + +## 1. Implementation +- [x] 1.1 Add `useThread: true` to render config in `app.tsx` + +## 2. Verification +- [x] 2.1 Run typecheck to ensure no type errors +- [x] 2.2 Test TUI with normal typing - confirm no freezing +- [x] 2.3 Verify with perf diagnostics (OPENCODE_PERF_DEBUG=1) - confirm zero blocked events + +## 3. Cleanup +- [x] 3.1 Remove diagnostic instrumentation code +- [x] 3.2 Commit and push changes