Design dreb dashboard UX/UI for TUI feature parity

[aebrer]

Summary

Before building the dreb web dashboard, do a UX/UI design pass focused on TUI feature parity plus the extra capabilities a browser dashboard enables.

TUI feature parity means: anything a user can do in the dreb TUI should also be possible from the dashboard. The dashboard should also cover browser-specific features such as project/file browsing, upload/download, Tailscale-based auth, and remote/mobile use.

This should block implementation work on the dashboard issue until the feature map, workflows, layout, and security-sensitive flows are clear enough to implement against.

Related implementation issue: #307

Why

The previous implementation attempt started too far into backend/API scaffolding before the UI requirements were pinned down. We need to map the existing TUI capabilities to dashboard workflows first, then design the extra browser-only functionality around that.

This is the foundation for the dashboard, not a disposable prototype. The first implementation should establish the main structure, navigation, state model, and feature coverage that future work can build on.

React, Svelte, another Node/browser framework, or a smaller custom stack are all viable implementation options. Framework choice should be made deliberately after the design clarifies the interaction model, state complexity, accessibility needs, mobile behavior, and maintainability tradeoffs.

Design questions

• What TUI features exist today, and how is each exposed in the dashboard?
• What is the flow from opening the dashboard to selecting a project and starting or resuming a session?
• How are chat, steering, follow-up, abort, model switching, settings, slash commands, task lists, suggest-next, tool events, and subagents represented?
• How does session history/tree/fork/resume/export map to the browser UI?
• How do file browsing, upload, and download fit into the main workflow?
• How should localhost access, Tailscale remote access, and PIN pairing work from the user's perspective?
• What needs to be visible on desktop vs mobile?
• Which framework/frontend architecture best supports this feature set?

Deliverables

• TUI feature parity checklist: every TUI capability mapped to a dashboard equivalent or explicitly marked as out of scope with a reason.
• UX flow for first launch, local-only use, remote pairing, project selection, session creation/resume, chat, subagent monitoring, file transfer, settings, and session history/tree operations.
• Responsive layout plan for desktop and mobile.
• Visual design direction: typography, spacing, colors, density, status treatments, and component language.
• Interaction design for prompts, steering, follow-up, abort, live tool calls, task lists, suggest-next, and background subagents.
• Security UX copy for localhost vs Tailscale remote access, PIN pairing, and file/agent-control risks.
• Foundation scope: what the first implementation must establish, and what can be sequenced later without compromising the base.
• Frontend architecture recommendation, including whether to use React/Svelte/another framework or a smaller custom stack, with rationale.
• Acceptance criteria that a future implementation PR can be reviewed against.

Non-goals

• Do not implement the dashboard in this issue.
• Do not revive or fork Pi dashboard visuals/protocol assumptions.
• Do not treat the dashboard as a disposable MVP/prototype; this design should define the base dashboard experience.

Acceptance criteria

• A concrete dashboard UX/UI spec exists in repo docs or linked issue comments.
• The spec includes a TUI feature parity checklist.
• The spec includes desktop and mobile flows.
• The spec covers security-sensitive flows, especially remote access and PIN pairing.
• The spec defines the foundation surface area clearly enough that implementation can be scoped and reviewed.
• The spec recommends a frontend architecture/framework direction with rationale.
• The implementation issue can be treated as blocked until this design work is accepted.

[m-aebrer]

Issue Assessment

Summary

Design-only issue: produce a UX/UI spec for the dreb web dashboard (implementation issue 307) covering TUI feature parity, browser-only capabilities (files, remote access, mobile), responsive layout, security flows, and a frontend architecture recommendation. Implementation stays blocked until this spec is accepted. Triggered by closed draft PR 310, which built backend scaffolding plus a vanilla-DOM client before the product shape was defined.

Current state

The stable API seam is AgentSession, not the TUI. The TUI (packages/coding-agent/src/modes/interactive/interactive-mode.ts, ~5,600 lines) is pure presentation; all state-changing logic (fork, tree, compaction, model switching, queuing, bash) lives in core/agent-session.ts and is what any dashboard would consume.

TUI capability inventory (raw material for the parity checklist):

• 26 built-in slash commands, plus extension commands, skills, and prompt templates
• ~35 keybound interactive behaviors (steer, follow-up queue/dequeue, abort, model/thinking cycling, tool-output and thinking toggles, session rename/delete, image paste, external editor)
• 9 message-stream component types (user, assistant with thinking blocks, tool execution, bash execution, compaction summary, branch summary, skill invocation, custom/extension, plus inline status loaders)
• 9 session-level event types beyond the core agent events (auto-compaction, auto-retry, background agent lifecycle, parent-pause, tasks_update, suggest_next)
• ~15 TUI-only affordances needing explicit out-of-scope-or-equivalent decisions (buddy, shell passthrough, external editor, clipboard paste, Ctrl+Z suspend, terminal images, hardware cursor, tmux detection, two-zone scrollback, etc.)

RPC surface vs TUI capability — the gap list matters most for this design. RPC (modes/rpc/rpc-types.ts) covers: prompt/steer/follow_up/abort, new_session, get_state/get_messages, model set/cycle/resolve/list, thinking level, steering/follow-up modes, compact + auto-compaction, auto-retry, bash, stats, export_html, switch_session, fork, session naming, project-scoped list_sessions, and extension UI requests (select/confirm/input/editor — the dashboard must render these as modals). Not exposed over RPC today: tree navigation (internal-only via extension actions), cross-project session listing (SessionManager.listAll exists in core but has no RPC command), session delete, settings read/write (themes, scoped models, autocompaction config), OAuth login/logout, import, JSONL export, reload, dream. PR 310 worked around some gaps by importing SessionManager directly in the dashboard server — a hybrid boundary the spec should either endorse or reject explicitly.

Salvageable prior art (both unmentioned in the issue body):

• PR 310's server side was solid and tested: fail-closed auth (loopback bypass, Tailscale identity allowlist, 5-min PIN, pairing cookies), path-escape-guarded file APIs, per-project RPC runtime pool, SSE streaming, 16 endpoints. The client was the failure: vanilla-DOM full-re-render SPA, plaintext <pre> chat (no markdown), and sidebar panels referenced in JS but never added to the HTML — it would throw at init. Screens that existed: PIN pairing card, 4 tabs (Chat/Files/Sessions/Runtime).
• core/export-html/ contains ~1,690 lines of battle-tested chat rendering: renderEntry() covers every entry type (thinking blocks, collapsible tool calls, bash, compaction/branch summaries), plus ANSI→HTML conversion, vendored marked.js + highlight.js, and TUI-theme-derived CSS variables. This is effectively a proven chat-parity renderer and should be the reference (or extraction source) for the dashboard chat pane.

Gaps

1. The issue's deliverables are prose-first (checklist, flows, copy, criteria) with no mockup/prototype deliverable. UI design evaluated only as markdown has the same failure mode as PR 310, inverted.
2. No deliverable pins where the spec lives (body says "repo docs or linked issue comments" — these age very differently).
3. The parity checklist has no source inventory in the issue; without one it will be reinvented ad hoc (the inventory above closes this).
4. RPC gaps are not acknowledged; several "parity" flows (tree navigation, cross-project sessions, settings, session delete) have no backend command to design against, so the spec must mark them as requiring RPC extensions or a hybrid server boundary.

Ambiguities

1. Information architecture — the biggest open question. Issue 307's motivation is fleet-centric ("control multiple sessions and projects from one place", live subagent fan-out), but the TUI — and PR 310's UI — are single-session-centric. Whether the dashboard's home screen is a multi-session overview with drill-in, or a session view with a picker, changes every other flow. The issue never decides this.
2. Degree of parity. "Anything a user can do in the TUI should also be possible" taken literally includes /dream, /login OAuth flows, buddy, scoped models, keybinding config. The checklist format allows out-of-scope-with-reason, but no guidance is given on where the line sits.
3. Framework timing. The issue defers framework choice until after design, but the PR 310 client failed on architecture (no components, no reactivity, full-DOM re-render), not on visual design. These decisions are weakly coupled to the design and strongly coupled to iteration speed.
4. Mobile scope. "Responsive" vs a deliberately reduced mobile control surface (e.g. read-and-steer only) is undecided; the TUI's keyboard-modal interaction model has no mobile equivalent, so mobile needs its own affordance design, not just layout reflow.
5. Remote capability tiers. Should a paired remote/mobile device get full control (bash, file upload, settings) or a reduced tier? Security section of issue 307 implies the question but the design issue doesn't ask it.

Scope

Medium, and mostly design synthesis rather than research — the codebase analysis (TUI inventory, RPC gaps, reusable rendering) is done as of this assessment. Remaining work: decide the IA question, produce screen mockups for the core flows (overview/session list, chat, subagent monitor, files, pairing, settings, mobile chat), distill the parity checklist from the inventory with explicit out-of-scope calls, write the security UX copy, and make the framework recommendation. No production code.

Risks

1. Waterfall spec risk. A giant prose spec that nobody can visually evaluate repeats the PR 310 mistake. Mitigation: static HTML/CSS mockups (or equivalent) as first-class deliverables, iterated before the checklist/criteria are written.
2. Parity-as-driver risk. Designing the dashboard as "the TUI in a browser" produces terminal cosplay and buries the dashboard's real value (multi-session overview, mobile, subagent visibility, file transfer). Parity should be a coverage audit at the end, not the design driver.
3. Designing flows RPC can't serve. Tree navigation, cross-project listing, settings, and session delete need new RPC commands or a sanctioned hybrid boundary; if the spec ignores this, the implementation PR will either stall or silently shrink scope.
4. Framework re-litigation. Leaving the stack open invites another hand-rolled client. The spec should commit to a small component framework with reactivity and dev-server iteration (e.g. Vite + Svelte or Preact), consistent with issue 307's "small enough to reason about security" constraint.
5. Spec rot. If the spec lands only in issue comments it will drift from implementation; it should live in the repo (e.g. a design doc plus mockup files) and be updated by the implementation PR.

Recommended execution order

1. Decide information architecture (fleet-centric overview vs session-centric) — this is the fulcrum decision.
2. Pick the frontend stack early and build mockups in it (or as plain HTML/CSS) — 4-6 screens: session overview, desktop chat, mobile chat, subagent monitor, PIN pairing, files.
3. Iterate mockups until approved; only then distill the parity checklist (from the inventory in this assessment), flows, security copy, and acceptance criteria.
4. Include an explicit "RPC extensions required" appendix (tree navigation, listAll, settings, delete) as input to the implementation plan for issue 307.
5. Carry forward PR 310's auth/file-API/runtime-pool server design and the export-html rendering approach as reference implementations; the spec should design their UX, not redesign their mechanics.

---

Automated assessment by mach6

[m-aebrer]

Design decision: fleet-centric information architecture

Resolving ambiguity 1 from the assessment above: the dashboard home screen is fleet-centric — a multi-session/multi-project overview showing all sessions and live subagent activity — with drill-in to any individual session for one-on-one chat interaction (which must retain full chat parity per the deliverables).

Implications for the design work:

• The overview screen is the primary new design surface; the session drill-in view can lean on existing chat-rendering prior art (export-html renderer).
• Navigation model: overview ⇄ session view, not tabs-around-one-session (what the closed draft PR had).
• Mobile design should prioritize the overview + read-and-steer flows in the session view.
• MVP fleet boundary: "live" sessions are runtimes the dashboard server manages. Sessions from disk are browsable/resumable inventory; externally running TUI processes are out of scope for liveness detection (no such mechanism exists in dreb today). The design should treat this boundary explicitly.

Prerequisite RPC functionality gaps identified in the assessment (cross-project listing, session delete, tree navigation, settings) are being split into sub-issues of the implementation issue so they can run through the pipeline independently of this design work.