11 KiB
11 KiB
Feature Landscape
Domain: Retro BBS-style terminal markdown vault reader (SSH login shell) Researched: 2026-02-28 Confidence: MEDIUM — external search tools unavailable; analysis based on domain knowledge of TUI apps (glow, mdcat, obsidian, lynx, classic BBS systems like PCBoard/TBBS), ratatui ecosystem, and stated project context.
Table Stakes
Features users expect. Missing = product feels incomplete or broken.
| Feature | Why Expected | Complexity | Notes |
|---|---|---|---|
| Render markdown headers (H1-H6) with visual hierarchy | Every markdown viewer does this; wall of unstyled text is unusable | Low | H1 = bold+large/colored, H2 = bold, H3+ = indented bold |
| Render bold, italic, inline code | Absolute minimum markdown styling; without it docs look broken | Low | crossterm supports SGR attributes |
| Render fenced code blocks with monospace styling | Code blocks unformatted = content is unreadable for technical vaults | Medium | Needs distinct background/border treatment |
| Render unordered and ordered lists | Core markdown construct; expected in any viewer | Low | Unicode bullets (•, ◦, ▸) fit retro aesthetic |
| Render blockquotes with visual distinction | Common in docs and notes; must be visually distinct | Low | Left-border char (│ or ▎) in a muted color |
| Scrollable content (up/down) | Documents longer than terminal height; non-scrollable is immediately broken | Medium | Ratatui ScrollView widget or manual offset state |
Follow [[wiki-links]] to target .md files |
Core product feature; stated requirement; Obsidian-style vaults rely on this | Medium | Must resolve vault-relative paths, strip [[]], add .md |
Follow standard [text](path.md) links |
Standard markdown; viewers that ignore links are just text dumpers | Medium | Must handle relative paths and URL-style paths |
| Back navigation (previous page) | Web-like browsing is core product value; no back = broken UX | Low | History stack, pop on back |
| Landing at index.md on launch | Defined entry point; without it the app has no starting state | Low | Read vault root for index.md, fallback to error page |
| Graceful exit (q or Ctrl+C) | Login shell replacement; if user can't exit they are stuck in the SSH session | Low | Must restore terminal state on exit |
| Keyboard navigation hints visible | Users don't know keybindings in a custom shell; must be discoverable | Low | Status bar / footer with active key hints |
| Handle missing files gracefully | Broken links are inevitable; crash is unacceptable in a login shell | Low | "Not found" page with link back to index |
| Terminal resize handling | SSH terminals resize constantly; content must reflow | Medium | Listen for SIGWINCH or crossterm resize events |
| [IMAGE: alt text] placeholder rendering | Stated requirement; images can't render in standard terminals | Low | Render as styled placeholder box with alt text |
Differentiators
Features that set this product apart. Not universally expected, but high value.
| Feature | Value Proposition | Complexity | Notes |
|---|---|---|---|
| Retro BBS ANSI art header / splash screen | Creates the "BBS you SSH into" atmosphere immediately on connect; memorable first impression | Medium | Static ANSI escape sequence loaded from a file or embedded; shown on index.md |
| Box-drawing borders on all panels | Distinguishes from generic TUI apps; reinforces retro aesthetic consistently | Low | Ratatui Block widget uses box-drawing chars natively |
| Color theme inspired by classic BBS palettes | Cyan/magenta/bright-green on dark = instant retro feel; no other markdown viewer does this | Low | CGA-era 16-color palette or amber/green phosphor options |
| Forward navigation (forward after back) | Goes beyond simple back; makes browsing feel genuinely web-like | Low | Forward stack that clears on new navigation |
| Full page navigation history | Users can see where they've been; useful in deep vaults | Medium | History list UI overlay (e.g., a popup list widget) |
| Filesystem watching for live content updates | Content updates without restarting any session; feels like a live publication | Medium | notify crate; re-parse changed file, update display if currently viewed |
| Vault-wide index / directory listing | Users can discover documents beyond what links expose | Medium | Scan vault dir, list .md files in a browsable list widget |
| "Last updated" timestamp on pages | Shows freshness of content without requiring git; adds BBS bulletin feel | Low | File mtime from std::fs::metadata |
| Table rendering | Tables in markdown are common; most TUI renderers skip them | High | Column width calculation, wrapping; high complexity for correct rendering |
| Inline link highlighting / cursor | Shows which links are interactive; keyboard-navigable link cycling | Medium | Track link positions during render, highlight focused link |
| Link cycling with Tab/arrow keys | Keyboard-first navigation between links on a page without needing a mouse | Medium | Depends on link position tracking during render pass |
| "You are here" breadcrumb | Shows current file path relative to vault root; orientation in deep vaults | Low | Status bar element: vault/subfolder/page.md |
| Page title in terminal title bar / status | Sets terminal window title via OSC escape sequence; useful when multiple tabs | Low | OSC 0 escape: \x1b]0;{title}\x07 |
Anti-Features
Features to explicitly NOT build.
| Anti-Feature | Why Avoid | What to Do Instead |
|---|---|---|
| Write / edit capabilities | Adds auth complexity, file locking, conflict resolution; stated as out of scope; login shell editing is a support nightmare | Stay strictly read-only; make this a hard guarantee |
| Embedded SSH/telnet server | OS SSH daemon handles this already; reimplementing is security risk and massive scope; stated out of scope | Document how to configure /etc/passwd or sshd_config to use binary as shell |
| User identity / sessions / per-user state | Auth is SSH daemon's job; tracking user state adds storage, privacy concerns, race conditions between processes | Each process is stateless per session; no session files written |
| Search across vault | High complexity (full-text index), not BBS-like, and adds significant scope for unclear benefit in read-only context | Good vault organization and index.md solve discovery |
| Syntax highlighting for code blocks | Requires a syntax highlighter crate (syntect adds 5MB+ to binary), high complexity, marginal value in a retro aesthetic context | Use distinct monospace block styling with a single muted color instead |
| Mermaid / PlantUML diagram rendering | Requires external process execution or complex parser; terminal rendering of diagrams is poor anyway | Treat diagram fences as code blocks (show source) |
| Mouse click navigation | SSH sessions vary wildly in mouse support; mouse events add complexity for marginal gain | Keyboard-only navigation is more universal and fits BBS aesthetic |
| Sixel / Kitty graphics protocol | Terminal support is inconsistent; stated out of scope; adds significant complexity | [IMAGE: alt text] placeholders are the stated solution |
| Configuration file / user preferences | Single-instance deployment; content owner controls the experience; user prefs add scope and storage needs | Hard-code the aesthetic; let the vault author configure via content |
| External link handling (http://) | Cannot open a browser from a login shell context meaningfully; confusing for users | Show external links as visually distinct but non-interactive; display the URL text |
| Animations beyond the initial splash | Distracting in a document reader; increases render complexity; SSH latency makes animations jank | Static retro aesthetic is more authentic and reliable |
| Plugin system | Massive scope; no clear use case for a single-purpose vault reader | Keep it a focused, well-built single-purpose tool |
Feature Dependencies
index.md landing page → graceful missing file handling (both needed before launch)
[[wiki-links]] parsing → vault-relative path resolution → graceful missing file handling
standard [text](link) parsing → vault-relative path resolution
back navigation → navigation history stack
forward navigation → navigation history stack (forward stack on top of back stack)
history overlay UI → navigation history stack
link highlighting / cursor → link position tracking during render
Tab/arrow link cycling → link highlighting / cursor
filesystem watching → markdown parser (must re-parse on change)
filesystem watching → currently-viewed-page check (only re-render if watching current file)
vault-wide index / directory listing → vault path scan (filesystem access layer)
"last updated" timestamp → filesystem metadata access (same layer as vault scan)
table rendering → markdown parser (must handle GFM table extension)
all markdown rendering → markdown parser (single parse pass feeds all render features)
ANSI art splash → retro theme (splash should match overall palette)
box-drawing borders → retro theme (same palette/style decisions)
terminal resize → scroll state (offset must be recalculated on resize)
scrollable content → terminal resize (dependent on terminal dimensions)
MVP Recommendation
Prioritize for first working session:
- Markdown render: headers, bold, italic, inline code, lists, blockquotes, code blocks
- index.md landing page with graceful missing-file error
- Scrollable content with keyboard scroll (j/k, arrow keys, PgUp/PgDn)
- wiki-link following + standard markdown link following
- Back navigation (history stack)
- Graceful exit (q, Ctrl+C) with terminal restoration
- Keyboard hints in status bar
- Retro box-drawing border aesthetic (Ratatui Block widgets, color theme)
- [IMAGE: alt text] placeholder rendering
- Terminal resize handling
Defer to later phases:
- Filesystem watching: Technically impressive but not needed for initial usable product; adds async complexity
- Forward navigation: Nice to have after back works; low complexity, natural second step
- Vault-wide index: Useful discovery feature; needs filesystem scan layer first
- Table rendering: High complexity, skip until core render pipeline is solid
- ANSI art splash screen: Pure aesthetic polish; implement after functional MVP
- Link highlighting / Tab cycling: Usability improvement; implement after basic link-following works
- History overlay UI: Convenience feature; implement after core navigation works
Sources
- Project context:
/Users/ruohki/shared/bbs-md/.planning/PROJECT.md(HIGH confidence — stated requirements) - Domain expertise: Classic BBS systems (PCBoard, TBBS, Telegard), TUI markdown viewers (glow, mdcat, tdf), Obsidian wiki-link conventions, ratatui widget inventory — MEDIUM confidence (training knowledge, external verification unavailable)
- Note: WebSearch, WebFetch, and Bash tools were unavailable during this research session. All competitive analysis is from training knowledge. Findings should be cross-checked against current ratatui docs and existing TUI markdown viewer feature lists before roadmap is finalized.