14 KiB
pi-workflow popup prototypes
Status: Direction C accepted
These static terminal frames compare popup directions for /workflow. They are prototype evidence, not production screenshots or manual validation of the implemented extension. All variants use Pi theme tokens, keyboard-visible focus, one border at most, and no animation.
Representative run: pi-workflow-usability-resume, waiting at Plan Approval after Discover and Design.
A. Centered compact modal
A small modal preserves the surrounding conversation and keeps one decision in focus.
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ ╭─ pi-workflow ──────────────────────────────╮ │
│ │ pi-workflow-usability-resume │ │
│ │ WAITING · Plan Approval · revision 12 │ │
│ │ │ │
│ │ ✓ Discover ✓ Design · Prototype │ │
│ │ · Implement · Verify · Review │ │
│ │ │ │
│ │ > Review plan │ │
│ │ Approve plan │ │
│ │ Request revision │ │
│ │ Close │ │
│ │ │ │
│ │ ↑↓ navigate enter select esc close │ │
│ ╰─────────────────────────────────────────────╯ │
│ │
└──────────────────────────────────────────────────────────────────────┘
Strengths:
- Minimal visual interruption.
- Familiar one-step prompt behavior.
- Low chrome and clear focus.
Weaknesses:
- Long plans and detailed run state require repeated modal replacement.
- Context disappears quickly as the interaction deepens.
- Poor fit for browsing artifacts or transcripts.
A at 60 columns
╭─ pi-workflow ───────────────────────╮
│ usability-resume · WAITING │
│ Plan Approval · r12 │
│ │
│ > Review plan │
│ Approve plan │
│ Request revision │
│ Close │
│ │
│ ↑↓ enter esc │
╰─────────────────────────────────────╯
B. Near-full-screen workspace
A stable workspace keeps the run list, selected run, progress, and actions visible together.
╭─ pi-workflow ────────────────────────────────────────────────────────────────╮
│ Runs │ pi-workflow-usability-resume WAITING │
│ │ feature/pi-workflow-usability-resume · r12 │
│ > usability-resume │ │
│ auth-cleanup │ Progress │
│ cache-audit │ ✓ Discover ✓ Design · Prototype · Implement │
│ │ · Verify · Review │
│ │ │
│ │ Open Gate │
│ │ Plan Approval │
│ │ Review the implementation plan before work begins. │
│ │ │
│ │ > Review plan │
│ │ Approve plan │
│ │ Request revision │
│ │ Browse artifacts │
│ │ Close │
│ │ │
│ ↑↓ run tab focus │ ↑↓ action enter select esc back │
╰──────────────────────────────────────────────────────────────────────────────╯
Strengths:
- High information density with stable spatial context.
- Fast comparison between several active runs.
- Actions and state remain visible together.
Weaknesses:
- The permanent left pane spends space on uncommon multi-run comparison.
- Focus management and responsive collapse are more complex.
- At 80 columns the content pane becomes cramped; below 80 it must become a different UI.
B at 80x24
╭─ pi-workflow ────────────────────────────────────────────────────────────────╮
│ Runs │ usability-resume · WAITING · r12 │
│ > usability │ ✓ Discover ✓ Design · Prototype │
│ auth-cleanup │ · Implement · Verify · Review │
│ cache-audit │ │
│ │ Plan Approval │
│ │ > Review plan │
│ │ Approve plan │
│ │ Request revision │
│ │ Browse artifacts │
│ │ │
│ tab focus │ ↑↓ action enter select esc back │
╰──────────────────────────────────────────────────────────────────────────────╯
B at 60 columns
The workspace must collapse to a single run-detail pane. The run list becomes a prior drill-down view, effectively converging on direction C.
C. Drill-down overlays with dedicated readers
Direction C uses shallow browser-style navigation. Each overlay does one job. Escape always returns one level.
C1. Run list popup
╭─ pi-workflow ─────────────────────────────╮
│ > usability-resume WAITING Plan Approval│
│ auth-cleanup RUNNING Implement │
│ cache-audit DONE report ready │
│ │
│ ↑↓ navigate enter open esc close │
╰────────────────────────────────────────────╯
C2. Run detail popup
╭─ usability-resume ───────────────────────────────────╮
│ WAITING · Plan Approval · revision 12 │
│ │
│ ✓ Discover ✓ Design · Prototype · Implement │
│ · Verify · Review │
│ │
│ > Review plan │
│ Record Gate Decision │
│ Browse prototype evidence │
│ Browse Assignment transcripts │
│ Show worktree path │
│ │
│ ↑↓ navigate enter select esc runs │
╰──────────────────────────────────────────────────────╯
C3. Plan reader at wide width
The reader uses the whole overlay. The terminal edge is the outer frame, so there is no decorative full-screen border. The left outline tracks the heading containing the top visible document line.
pi-workflow plan · usability-resume line 42/216
Outline Plan
───────────────────────────── ─────────────────────────────────────────────
pi-workflow usability update # pi-workflow usability update plan
Locked decisions
> Implementation phases ## Implementation phases
Prototype overlays
Session lifecycle ### 2. Session lifecycle and recovery
Worktree safety
Popup TUI - Route the dashboard's fresh-session action
Progress widget through the existing continuation path.
Design regression
Acceptance criteria - Atomically rotate lease and context owners
during absent/dead adoption.
Primary files: dashboard.ts,
context-transition.ts, continuation.ts,
engine.ts, and focused tests.
↑↓ scroll pgup/pgdn page home/end document esc back
C3 at 80x24
pi-workflow plan · usability-resume row 42/216
Outline Plan
────────────────────── ─────────────────────────────────────────────
Locked decisions ## Implementation phases
> Implementation
Prototype overlays ### 2. Session lifecycle and recovery
Session lifecycle - Route the dashboard's fresh-session action
Worktree safety through the existing continuation path.
Popup TUI
Progress widget - Atomically rotate lease and context owners
Acceptance criteria during absent/dead adoption.
↑↓ scroll pgup/pgdn page home/end document esc back
C3 at 60 columns
The outline hides and the document becomes the only pane. The current heading remains visible in the header.
pi-workflow plan · Implementation phases · row 42/216
## Implementation phases
### 2. Session lifecycle and recovery
- Route the dashboard's fresh-session action through the
existing continuation path.
- Atomically rotate lease and context owners during
absent/dead adoption.
↑↓ scroll pgup/pgdn page home/end document esc back
C3 at 47x11
terminal too small
pi-workflow plan needs 48x12
current terminal is 47x11
resize the terminal or press esc
Strengths:
- Each screen has one dominant task and a complete local keymap.
- Best responsive behavior because narrow layouts remain single-pane.
- Long plans and transcripts get dedicated virtualized readers.
- The shallow stack preserves context without permanent side-panel cost.
Weaknesses:
- Comparing several runs takes more navigation than direction B.
- Back-stack state and overlay focus/disposal require careful implementation.
Persistent progress widget
The widget is independent of the selected popup direction and stays above Pi's editor while the newest attached run is active.
Standard:
workflow usability-resume DESIGN 2/6 Gate: Plan Approval
Narrow:
workflow usability-resume DESIGN 2/6
Terminal runs disappear rather than leaving a stale receipt above the editor.
Recommendation
Use direction C. It has one border only on bounded popup cards, no redundant frame around the full-screen reader, keyboard-visible selection, and the most truthful 80-column and 60-column degradation. Direction B spends too much space on multi-run comparison, while direction A does not provide enough stable space for plans and evidence.
Production mapping
The accepted direction maps to extensions/pi-workflow/tui.ts and dashboard.ts. The implementation uses popup overlays for bounded selections and text entry, then switches to the full-screen reader for verified plans and retained evidence. progress.ts owns the separate one-line widget. Pure renderer tests cover the wide, 80-column, 60-column, and below-48x12 contracts; interactive Pi validation remains a separate manual step.
Interaction contract
- Arrow keys navigate every selection surface; Enter selects; Escape cancels or returns one level.
- Page Up/Page Down and Home/End apply only to long-document readers.
- Text inputs use Pi's
InputorEditorcomponents and propagate focus for IME positioning. - The current selection uses position plus selected background or reverse video, never color alone.
- TUI overlays are never opened in RPC, print, or JSON mode.
- Every rendered line is truncated or wrapped by terminal cell width rather than JavaScript string length.
- No continuously repainting animation is used.