Epic: OpenTUI Example Migration

[yaohaowei0914]

Source file: docs/issues/2026-04-22-opentui-example-migration-epic.md

Labels: ui, frontend, opentui, planning
Priority: P1
Scope: ui/

Goal

Turn the relocated sample tree under ui/examples/upstream-patterns/ into a controlled migration source for the maintained OpenTUI frontend under ui/src/.

This epic does not restore the old upstream runtime.
It defines a staged path for reusing patterns, components, and interaction ideas while keeping:

• ui/src/main.tsx
• ui/src/components/App.tsx

as the only active frontend entry chain.

Ground Rules

1. ui/examples/upstream-patterns/ is a reference corpus, not a runnable source of truth.
2. No direct imports from the sample tree into the active frontend without first adapting state, protocol, and rendering primitives.
3. screens/REPL.tsx, dialogLaunchers.tsx, and interactiveHelpers.tsx remain sample-runtime references only.
4. Every migration slice must end with bun run build in ui/.
5. Behavior should move in small vertical slices, not via wholesale file transplant.

Source Of Truth

• Main migration note:
  docs/issues/2026-04-21-frontend-refactor-notes.md
• Sample tree:
  ui/examples/upstream-patterns/

Execution Order

1. Issue 01: adapter foundation
2. Issue 02: render primitives
3. Issue 03: message presentation slice
4. Issue 04: permission and tool-result UX
5. Issue 05: operational panels (MCP/LSP/team/shell)
6. Issue 06: composer and prompt input
7. Issue 07: status line, docs, and cleanup

Dependency Rules

• Issue 01 blocks every later issue.
• Issue 02 should land before Issue 03.
• Issue 03 should land before Issue 04 and Issue 06.
• Issue 04 and Issue 05 can run in parallel after Issue 03.
• Issue 07 only starts after at least one slice from Issues 04-06 is merged.

Definition Of Done

The epic is complete when:

• the active OpenTUI frontend uses a meaningful subset of the sample-tree patterns
• no migration slice depends on direct runtime imports from the sample tree
• at least message rendering, prompt/composer behavior, and permission UX have dedicated Lite-native implementations
• docs no longer describe the sample tree as a candidate alternate frontend

Related Issues

• Issue 01: Adapter Foundation For Sample Migration #90 Issue 01: Adapter Foundation For Sample Migration
• Issue 02: Render Primitives From The Sample Tree #91 Issue 02: Render Primitives From The Sample Tree
• Issue 03: Message Presentation Slice #92 Issue 03: Message Presentation Slice
• Issue 04: Permission And Tooling UX Slice #93 Issue 04: Permission And Tooling UX Slice
• Issue 05: Operational Panels For MCP, LSP, Team, And Shell #94 Issue 05: Operational Panels For MCP, LSP, Team, And Shell
• Issue 06: Composer And Prompt Input Migration #95 Issue 06: Composer And Prompt Input Migration
• Issue 07: Status Line, Docs, And Migration Cleanup #96 Issue 07: Status Line, Docs, And Migration Cleanup