manhvann Preview
Universal viewer + visual generator. View existing content OR generate new visual explanations.
Default (No Arguments)
If invoked without arguments, ask the user to choose available preview operations:
| Operation | Description |
|---|---|
(view) |
View a file or directory |
--explain |
Generate visual explanation |
--slides |
Generate presentation slides |
--diagram |
Generate architecture diagram |
--ascii |
Terminal-friendly diagram |
--stop |
Stop preview server |
Present options with header "Preview Operation", question "What would you like to do?".
Usage
View Mode
$preview <file.md>- View markdown file in novel-reader UI$preview <directory/>- Browse directory contents$preview --stop- Stop running server
Generation Mode
$preview --explain <topic>- Generate visual explanation (ASCII + Mermaid + prose)$preview --slides <topic>- Generate presentation slides (one concept per slide)$preview --diagram <topic>- Generate focused diagram (ASCII + Mermaid)$preview --ascii <topic>- Generate ASCII-only diagram (terminal-friendly)
Argument Resolution
When processing arguments, follow this priority order:
--stop→ Stop server (exit)- Generation flags (
--explain,--slides,--diagram,--ascii) → Generation mode. Loadreferences/generation-modes.md - Resolve path from argument:
- If argument is an explicit path → use directly
- If argument is a contextual reference → resolve from recent conversation context
- Resolved path exists on filesystem → View mode. Load
references/view-mode.md - Path doesn't exist or can't resolve → Ask user to clarify
Topic-to-slug conversion:
- Lowercase the topic
- Replace spaces/special chars with hyphens
- Remove non-alphanumeric except hyphens
- Collapse multiple hyphens → single hyphen
- Trim leading/trailing hyphens
- Max 80 chars - truncate at word boundary if longer
Multiple flags: If multiple generation flags provided, use first one; remaining treated as topic.
Placeholder {topic}: Replaced with original user input in title case (not the slug).
Error Handling
| Error | Action |
|---|---|
| Invalid topic (empty) | Ask user to provide a topic |
| Flag without topic | Ask user: "Please provide a topic: $preview --explain <topic>" |
| Topic becomes empty after sanitization | Ask for topic with alphanumeric characters |
| File write failure | Report error, suggest checking permissions |
| Server startup failure | Check if port in use, try $preview --stop first |
| No generation flag + unresolvable reference | Ask user to clarify which file they meant |
| Existing file at output path | Overwrite with new content (no prompt) |
| Server already running | Reuse existing server instance, just open new URL |
Parent plans/ dir missing |
Create directories recursively before write |