docs: add openspec proposal for TUI threaded rendering fix

Author: brettheap

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

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