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.1.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 interface, giving you the ultimate reading experience. Choose between dark and light themes, navigate entirely by keyboard, and enjoy full WCAG 2.2 AAA accessibility. 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 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 |
|:--|:--|
| 🌗 Dark / Light Theme | Toggle in View menu, persisted across sessions |
| 🖥️ Focus Mode | `F11` hides title bar and menu for immersive reading |
| 🔎 Content Zoom | `Ctrl+Scroll` or View menu spinner - 50% to 200% |
| ↔️ Content Width | `Shift+Scroll` or View menu spinner - 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`**, **drag-and-drop**, or **double-click** from Explorer
- Supports `.md` · `.markdown` · `.txt`
- **Single instance** - opening a file when Vesper is already running forwards it to the existing window
- 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>

## ♿ Accessibility

Vesper targets **WCAG 2.2 AAA** compliance across the entire interface.

| Area | Details |
|:--|:--|
| 🏗️ Semantic HTML | `<header>`, `<nav>`, `<main>`, `<article>`, `<search>` landmarks; proper ARIA roles for menus, tabs, dialogs, and status regions |
| ⌨️ Full Keyboard Navigation | Menu bar, tab bar, sidebar TOC, modals, and context menu all navigable with arrow keys, Home/End, Enter, Escape |
| 🔗 Skip Link | "Skip to content" link as first focusable element for screen reader users |
| 🎯 Focus Management | Visible `:focus-visible` outlines on all interactive elements; focus traps in modals with restore on close |
| 🌗 High Contrast Themes | Dark and light themes both meet AAA contrast ratios (7:1+ for normal text) |
| 🎞️ Reduced Motion | Respects `prefers-reduced-motion` OS setting - all animations disabled when active |
| 📋 Active Heading Tracking | Current section highlighted in sidebar TOC via IntersectionObserver |
| 🔲 Target Sizes | All interactive targets meet 24x24px minimum (WCAG 2.5.8) |
| 📢 Status Messages | Search results counter uses `aria-live="polite"` for screen reader announcements |
| 🎨 Non-Color Indicators | Active tabs marked with a bottom border accent; search highlights include underline in addition to background |
| ↔️ Resizable Sidebar | Keyboard-accessible resize handle (`role="separator"`) with arrow key support |

<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 / context menu |
| `Shift+F10` | 📋 Open context menu |
| `Delete` | ✕ Close focused tab (when tab bar is focused) |
| `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://git.lashman.live/lashman/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://git.lashman.live/lashman/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` · `single-instance`

<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 & Light** - two high-contrast themes, both WCAG AAA compliant |
| ⌨️ | **Keyboard Driven** - every feature accessible via shortcuts and arrow keys |
| ✨ | **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