vesper/README.md

# Vesper

<p align="center">
  <img src="https://img.shields.io/badge/version-1.0.0-blue" alt="Version">
  <img src="https://img.shields.io/badge/platform-Windows-blue" alt="Platform">
  <img src="https://img.shields.io/badge/framework-Tauri 2.0-black" alt="Framework">
  <img src="https://img.shields.io/badge/license-CC0-green" alt="License">
</p>

A beautiful, distraction-free markdown reader for Windows. Vesper renders your markdown files with premium editorial typography and a refined dark aesthetic, giving you the ultimate reading experience.

---

## Features

### Markdown Rendering

- Full CommonMark support via **markdown-it** with extensions:
  - Syntax highlighting for 190+ languages (highlight.js)
  - Task lists (checkboxes)
  - Superscript and subscript (`^text^`, `~text~`)
  - ==Highlighted text== via `mark`
  - Smart quotes, em-dashes, and ellipses (typographer)
  - Line break preservation
  - Auto-linking of URLs
  - HTML passthrough
- Premium dark-mode typography tuned for long-form reading:
  - Inter Variable at 17px with 1.7 line-height
  - ~65 character measure (680px max-width) for optimal readability
  - Progressive heading color cascade (H1 near-white through H6 muted)
  - Accent-colored list markers
  - Gradient-fade horizontal rules
  - Subtle persistent link underlines that intensify on hover
  - Refined blockquote, table, and code block styling
  - JetBrains Mono Variable for code at 14px with ligature support

### Tabbed Interface

- Open multiple documents in tabs
- Duplicate detection: re-opening an already-open file switches to its existing tab instead of creating a duplicate
- Animated tab enter/exit with layout transitions
- Scroll arrows appear when tabs overflow the bar, with hold-to-scroll
- Mouse wheel scrolling over the tab bar
- New tabs automatically scroll into view
- Close individual tabs with the X button or `Ctrl+W`

### Navigation

- **Table of Contents sidebar** auto-generated from document headings (H1-H6), with indentation by level
- Click any heading in the sidebar to smooth-scroll to that section
- Sidebar opens even when a document has no headings (shows "No headings" message)
- Resizable sidebar via drag handle
- **Full-text search** (`Ctrl+F`) with real-time DOM highlighting, match counter, and Enter to cycle through matches

### Reading Experience

- **Focus Mode** (`F11`) hides the title bar and menu bar for immersive reading
- **Content zoom** via `Ctrl+Scroll` (50%--200%)
- **Content width** adjustment via `Shift+Scroll` (400px--1200px)
- **UI scale** (50%--200%) with a spinner in the View menu, persisted across sessions via localStorage
- **Kinetic scrolling** on right-mouse-button drag with iOS-style rubber band overscroll and damped spring snapback
- **Custom scrollbars** via OverlayScrollbars -- thin, auto-hiding after 800ms, accent-colored on hover
- Window state (size, position, maximized) remembered between sessions via `tauri-plugin-window-state`

### File Handling

- Open files via the File menu, `Ctrl+O` dialog, or drag-and-drop from Explorer
- Supports `.md`, `.markdown`, and `.txt` files
- Native Tauri drag-and-drop integration (receives real file system paths)

### UI Details

- Custom frameless title bar with minimize, maximize/restore, and close buttons
- Draggable title area for window repositioning
- Menu bar with File, View, and Help menus
- Right-click context menu with: Copy (when text is selected), Open File, Toggle Search, Toggle Sidebar, Focus Mode, Keyboard Shortcuts, About, Exit
- Text selection preserved visually on right-click via overlay rendering
- Context menu stays within window bounds and respects UI zoom
- All panels, modals, tabs, and menus animate with Framer Motion (slide, fade, scale)
- Subtle noise texture overlay on the app background
- Keyboard shortcuts modal listing all bindings

---

## Keyboard Shortcuts

| Shortcut | Action |
|---|---|
| `Ctrl+O` | Open file |
| `Ctrl+W` | Close current tab |
| `Ctrl+Q` | Exit application |
| `Ctrl+F` | Toggle search |
| `Ctrl+Shift+S` | Toggle sidebar |
| `F11` | Toggle focus mode |
| `Escape` | Close search / sidebar |
| `Ctrl+Scroll` | Zoom content in / out |
| `Shift+Scroll` | Adjust content width |

---

## Installation

### Prerequisites

- Windows 10 or later
- WebView2 Runtime (pre-installed on Windows 10/11)

### Download

Download the latest installer from the [Releases](https://github.com/yourusername/vesper/releases) page:

- **NSIS installer** (`.exe`) -- recommended, includes uninstaller
- **MSI installer** (`.msi`) -- alternative for enterprise/group policy deployment
- **Portable exe** -- standalone `vesper.exe` with no installation required

### Build from Source

**Prerequisites:**
- [Node.js](https://nodejs.org/) v18+
- [Rust](https://www.rust-lang.org/tools/install) (stable toolchain)
- [Tauri v2 prerequisites](https://v2.tauri.app/start/prerequisites/)

```bash
# Clone the repository
git clone https://github.com/yourusername/vesper.git
cd vesper

# Install dependencies
npm install

# Run in development mode (hot-reload on localhost:1420)
npm run tauri dev

# Build for production
npm run tauri build
```

Build outputs:
- `src-tauri/target/release/vesper.exe` -- portable executable
- `src-tauri/target/release/bundle/msi/Vesper_1.0.0_x64_en-US.msi` -- MSI installer
- `src-tauri/target/release/bundle/nsis/Vesper_1.0.0_x64-setup.exe` -- NSIS installer

---

## Technology Stack

| Layer | Technology |
|---|---|
| Runtime | [Tauri v2](https://tauri.app/) (Rust + WebView2) |
| Frontend | React 19, TypeScript, Vite 7 |
| Styling | Tailwind CSS 4, DaisyUI 5, custom CSS |
| Markdown | [markdown-it](https://github.com/markdown-it/markdown-it) with plugins (task-lists, sup, sub, mark) |
| Syntax Highlighting | [highlight.js](https://highlightjs.org/) |
| Animation | [Framer Motion](https://www.framer.com/motion/) |
| Fonts | [Inter Variable](https://rsms.me/inter/), [JetBrains Mono Variable](https://www.jetbrains.com/lp/mono/) |
| Icons | [Lucide React](https://lucide.dev/) |
| Scrollbars | [OverlayScrollbars](https://kingsora.github.io/OverlayScrollbars/) |

### Tauri Plugins

- `tauri-plugin-dialog` -- native file open dialog
- `tauri-plugin-fs` -- file system read access
- `tauri-plugin-window-state` -- persist and restore window size, position, and maximized state
- `tauri-plugin-opener` -- system default app launcher

---

## Design Philosophy

1. **Content First** -- the reader is the primary focus; all UI chrome can be hidden
2. **Typography Matters** -- Inter Variable at 17px, 1.7 line-height, ~65 character measure, generous whitespace
3. **Dark by Default** -- deep onyx base color (#282C33) reduces eye strain
4. **Keyboard Driven** -- every feature accessible via keyboard shortcuts
5. **Minimalist Chrome** -- the interface gets out of your way

---

## Color Palette

| Color | Hex | Usage |
|---|---|---|
| Base | `#282C33` | Main window background |
| Surface | `#252A31` | Title bar, sidebar |
| Elevated | `#2D333C` | Active tab, modals |
| Overlay | `#333942` | Dropdowns, context menu |
| Text Primary | `#E4E6EB` | Main content |
| Text Secondary | `#ABB0B8` | UI labels, muted text |
| Text Tertiary | `#6B7280` | Placeholders, hints |
| Accent | `#6B8AFF` | Interactive elements, highlights |
| Link | `#7CA9F7` | Hyperlinks |

---

## Project Structure

```
md-reader/
  src/
    App.tsx            # Main application component (all UI logic)
    main.tsx           # React entry point
    styles.css         # All styles -- variables, UI components, markdown typography
  src-tauri/
    src/
      main.rs          # Rust entry point
      lib.rs           # Tauri builder and plugin registration
    tauri.conf.json    # Tauri window, bundle, and build configuration
    Cargo.toml         # Rust dependencies
    icons/             # App icons (ICO, PNG, ICNS)
  index.html
  package.json
  vite.config.ts
  tsconfig.json
```

---

## License

This project is dedicated to the public domain under the CC0 1.0 Universal (CC0 1.0) Public Domain Dedication -- see the [LICENSE](LICENSE) file for details.

---

## Acknowledgments

- [iA Writer](https://ia.net/writer) for design inspiration
- [Tauri](https://tauri.app/) for the excellent desktop framework
- [markdown-it](https://github.com/markdown-it/markdown-it) for robust markdown parsing
- [highlight.js](https://highlightjs.org/) for syntax highlighting