vesper/README.md

<div align="center">

# ✦ Vesper

**A beautiful, distraction-free markdown reader for Windows**

Built for everyone. Owned by no one. Free as in freedom.

<br>

<img src="https://img.shields.io/badge/version-1.0.0-6B8AFF?style=flat-square&labelColor=282C33" alt="Version">
<img src="https://img.shields.io/badge/platform-Windows-6B8AFF?style=flat-square&labelColor=282C33" alt="Platform">
<img src="https://img.shields.io/badge/Tauri-v2-6B8AFF?style=flat-square&labelColor=282C33" alt="Tauri">
<img src="https://img.shields.io/badge/license-CC0_Public_Domain-6B8AFF?style=flat-square&labelColor=282C33" alt="License">

</div>

<br>

## 📖 Overview

Vesper renders your markdown with carefully tuned typography and a refined dark interface, giving you the ultimate reading experience. No installation, no AppData, no registry, no telemetry, no accounts, no subscriptions - just drop the exe and go.

Knowledge should be accessible to all. Vesper exists to make reading a pleasure, not a product.

<br>

## ✨ Features

### 🔤 Markdown Rendering

Full CommonMark support via **markdown-it** with extensions:

| Extension | Description |
|:--|:--|
| 🎨 Syntax Highlighting | 190+ languages via highlight.js with a curated dark palette |
| ☑️ Task Lists | Interactive checkboxes in lists |
| ᴬᵇ Superscript / Subscript | `^text^` and `~text~` notation |
| 🖍️ Highlight | `==marked text==` rendered with accent background |
| 💬 Typographer | Smart quotes, dashes, and ellipses |
| 🔗 Linkify | Bare URLs auto-converted to clickable links |
| 📄 HTML | Inline HTML passthrough |
| ↵ Breaks | Newlines preserved as line breaks |

**Premium dark-mode typography** tuned for long-form reading:

> - **Inter Variable** at 17px with 1.7 line-height
> - ~65 character measure for optimal readability
> - Progressive heading color cascade - H1 near-white through H6 muted
> - Accent-colored list markers on both ordered and unordered lists
> - Gradient-fade horizontal rules
> - Subtle persistent link underlines that intensify on hover
> - **JetBrains Mono Variable** for code at 14px with ligature support

<br>

### 📑 Tabbed Interface

- Open **multiple documents** simultaneously in tabs
- 🔁 **Duplicate detection** - re-opening an already-open file switches to its tab
- ✨ Animated tab enter/exit with layout transitions
- ◀ ▶ **Scroll arrows** appear on overflow with hold-to-scroll
- 🖱️ **Mouse wheel** scrolling over the tab bar
- 📌 New tabs **auto-scroll** into view
- ✕ Close tabs with the button or `Ctrl+W`

<br>

### 🧭 Navigation

- 📋 **Table of Contents** sidebar auto-generated from headings (H1-H6) with indentation
- Click any heading to **smooth-scroll** to that section
- Sidebar opens even with no headings (shows "No headings" message)
- ↔️ **Resizable** sidebar via drag handle
- 🔍 **Full-text search** with real-time highlighting, match counter, and `Enter` to cycle

<br>

### 👁️ Reading Experience

| Feature | Details |
|:--|:--|
| 🖥️ Focus Mode | `F11` hides title bar and menu for immersive reading |
| 🔎 Content Zoom | `Ctrl+Scroll` - 50% to 200% |
| ↔️ Content Width | `Shift+Scroll` - 400px to 1200px |
| 🔲 UI Scale | 50%-200% via View menu spinner, persisted across sessions |
| 🏀 Kinetic Scroll | Right-mouse drag with iOS-style rubber band overscroll |
| 📜 Custom Scrollbars | Thin, auto-hiding, accent-colored on hover |
| 💾 Window Memory | Position, size, and maximized state remembered between sessions |

<br>

### 📂 File Handling

- Open via **File menu**, **`Ctrl+O`**, or **drag-and-drop** from Explorer
- Supports `.md` · `.markdown` · `.txt`
- Native Tauri drag-and-drop integration with real file system paths

<br>

### 🎨 UI Details

- Custom **frameless title bar** with minimize, maximize/restore, and close
- **Right-click context menu** - Copy, 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 bounds** and respects UI zoom
- All panels, modals, tabs, and menus **animate** with Framer Motion
- Subtle **noise texture overlay** on the app background

<br>

## ⌨️ 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 |

<br>

## 📦 Installation

### Prerequisites

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

### Download

Download the latest **`vesper.exe`** from the [Releases](https://github.com/yourusername/vesper/releases) page.
No installation required - Vesper is fully portable. No gatekeepers between you and your documents.

### Build from Source

Everyone has the right to inspect, modify, and rebuild the tools they use.

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

```bash
git clone https://github.com/yourusername/vesper.git
cd vesper
npm install
```

```bash
# Development (hot-reload on localhost:1420)
npm run tauri dev

# Production build
npm run tauri build
# -> src-tauri/target/release/vesper.exe
```

<br>

## 🔧 Technology Stack

Built entirely on open-source foundations - no proprietary dependencies, no vendor lock-in.

| | 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) + plugins |
| 🌈 | Syntax | [highlight.js](https://highlightjs.org/) |
| 🎬 | Animation | [Framer Motion](https://www.framer.com/motion/) |
| 🔤 | Fonts | [Inter Variable](https://rsms.me/inter/) · [JetBrains Mono](https://www.jetbrains.com/lp/mono/) |
| 🖼️ | Icons | [Lucide React](https://lucide.dev/) |
| 📜 | Scrollbars | [OverlayScrollbars](https://kingsora.github.io/OverlayScrollbars/) |

**Tauri Plugins:** `dialog` · `fs` · `opener`

<br>

## 💼 Portable

Vesper is **fully portable** - zero installation, zero system footprint. Your tools, your data, under your control.

All data lives in a `data/` folder next to the executable:

```
vesper.exe
data/
  ├── window-state.json    <- window position, size, maximized
  └── EBWebView/           <- WebView2 data (localStorage, cache)
```

> Nothing is written to AppData, the registry, or any other system location.
> No cloud sync, no phoning home. To move Vesper, just copy the exe and optionally the `data/` folder.

<br>

## 🧠 Design Philosophy

| | Principle |
|:--|:--|
| 📖 | **Content First** - all UI chrome can be hidden; the reader is the focus |
| 🔤 | **Typography Matters** - Inter at 17px, 1.7 line-height, ~65 char measure |
| 🌙 | **Dark by Default** - deep onyx base `#282C33` reduces eye strain |
| ⌨️ | **Keyboard Driven** - every feature accessible via shortcuts |
| ✨ | **Minimalist Chrome** - the interface gets out of your way |
| 🤝 | **No Extraction** - no ads, no tracking, no data harvesting, no paywalls |

<br>

## 🎨 Color Palette

| Swatch | Name | Hex | Usage |
|:--|:--|:--|:--|
| 🟫 | Base | `#282C33` | 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 |
| 🩶 | Text Tertiary | `#6B7280` | Placeholders, hints |
| 🔵 | Accent | `#6B8AFF` | Interactive elements |
| 🔷 | Link | `#7CA9F7` | Hyperlinks |

<br>

## 🗂️ Project Structure

```
vesper/
├── src/
│   ├── App.tsx              Main application component
│   ├── main.tsx             React entry point
│   └── styles.css           Variables, UI, markdown typography
├── src-tauri/
│   ├── src/
│   │   ├── main.rs          Rust entry point
│   │   └── lib.rs           Tauri builder, portable data, window state
│   ├── capabilities/
│   │   └── default.json     Permission declarations
│   ├── tauri.conf.json      Window, bundle, and build config
│   ├── Cargo.toml           Rust dependencies
│   └── icons/               App icons (ICO, PNG, ICNS)
├── index.html
├── package.json
├── vite.config.ts
└── tsconfig.json
```

<br>

## 📜 License

Dedicated to the **public domain** under [CC0 1.0 Universal](LICENSE). No copyright, no restrictions, no permission needed. Take it, use it, change it, share it - it belongs to everyone.

<br>

## 🙏 Acknowledgments

Built with gratitude on the collective work of open-source communities worldwide:

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