# Payas Reader — Documentation

> Privacy-first document viewer · PDF · EPUB · Markdown · Plain Text · No server · Open Source  
> Developer: **Saman Wijesinghe** · License: MIT

---

## Table of Contents

1. [Project Overview](#1-project-overview)
2. [Quick Start](#2-quick-start)
3. [Interface Layout](#3-interface-layout)
4. [Toolbar Reference](#4-toolbar-reference)
5. [Supported Formats](#5-supported-formats)
6. [Reading Features](#6-reading-features)
7. [Sidebar Panels](#7-sidebar-panels)
8. [Find & Search](#8-find--search)
9. [Keyboard Shortcuts](#9-keyboard-shortcuts)
10. [Settings Reference](#10-settings-reference)
11. [Storage & Data](#11-storage--data)
12. [Architecture & Code Structure](#12-architecture--code-structure)
13. [JavaScript API Reference](#13-javascript-api-reference)
14. [License](#14-license)

---

## 1. Project Overview

**Payas Reader** is a fully client-side document viewer that runs entirely in your browser — no server, no account, no build step. Open `payas-reader.html` directly and load any PDF, EPUB, Markdown, or plain-text file. All configuration is stored locally in `localStorage`.

### Key Facts

| Property | Value |
|---|---|
| Entry point | `payas-reader.html` |
| Stack | HTML5 · CSS3 · Vanilla JS (ES2022) |
| Dependencies | Bootstrap 5.3.3 · Bootstrap Icons 1.11.3 · marked.js 9.1.6 · PDF.js 3.11.174 · epub.js 0.3.93 · jszip 3.10.1 · Google Fonts |
| Storage | `localStorage` (settings + bookmarks) |
| Formats | PDF · EPUB · Markdown · Plain Text |
| Export | None (viewer only) |
| Themes | Light · Dark + 6 accent colours |
| Responsive | Yes — mobile sidebar overlay |

### Design Language

Payas Reader follows the **Payas design system** shared across all Payas web tools (Editor, Days, Player, Imager, FM, Omi). Same colour tokens, typography, and component patterns.

---

## 2. Quick Start

No build or server required. Open the file directly:

```bash
# Option 1 — open directly
xdg-open payas-reader.html          # Linux
open payas-reader.html              # macOS
start payas-reader.html             # Windows

# Option 2 — serve locally
python3 -m http.server 8080
# Then visit http://localhost:8080/payas-reader.html
```

On first launch a **welcome / drop-zone screen** is shown. Drag a file onto it or click **Open** to load a document.

---

## 3. Interface Layout

```
┌─ Title Bar ──────────────────────────────────────────────────┐
│ [Logo] [☰] [Open] [Settings] [About] [License] [🌙] [badge] │
├─ Toolbar ────────────────────────────────────────────────────┤
│ [🔍±] [Zoom−][%][Zoom+] [◀][Page n][▶] [🔍][⟳][🔖][⛶][🖨] │
├─ Find Bar (hidden) ──────────────────────────────────────────┤
│ [Search…] [n/m] [◀][▶] [✕]                                   │
├─ Body ───────────────────────────────────────────────────────┤
│  Sidebar (TOC / Bookmarks / Info)  │  Document View Area     │
├─ Status Bar ─────────────────────────────────────────────────┤
│ · Page n of m  ·  Reading progress                           │
└──────────────────────────────────────────────────────────────┘
```

### Title Bar

| Control | Action |
|---|---|
| Sidebar toggle (☰) | Show / hide the sidebar |
| Open | Open a document file |
| Settings | Open the settings panel |
| About | Version and project info |
| License | MIT licence text |
| Theme toggle (🌙) | Switch light / dark mode |
| Filename badge | Shows the name of the loaded file |

---

## 4. Toolbar Reference

| Button | Shortcut | Description |
|---|---|---|
| Zoom Out | `Ctrl+−` | Decrease zoom level |
| Zoom % display | — | Shows current zoom; click to reset |
| Zoom In | `Ctrl+=` | Increase zoom level |
| Reset Zoom | `Ctrl+0` | Return to 100% zoom |
| Previous Page | `←` | Go to previous PDF/EPUB page |
| Page input | — | Type a page number and press Enter |
| Next Page | `→` | Go to next PDF/EPUB page |
| Find | `Ctrl+F` | Open the search/find bar |
| Rotate (PDF) | — | Rotate PDF 90° clockwise |
| Add Bookmark | — | Bookmark the current page or position |
| Fullscreen | `F11` | Enter / exit browser fullscreen |
| Focus Mode | `F10` | Hide toolbar, find bar and status bar |
| Print | `Ctrl+P` | Print the document |
| Scroll to Top | `Home` | Jump to the first page / top |

---

## 5. Supported Formats

### PDF

- Rendered page-by-page with **PDF.js**
- Lazy loading via `IntersectionObserver` for performance
- Zoom, rotation, page navigation, search with highlight
- Configurable render scale (quality setting)

### EPUB

- Full rendition via **epub.js**
- Table of contents extracted automatically
- Bookmark support with page/chapter reference
- Theme colours inherited from the app

### Markdown (`.md`, `.markdown`)

- Converted to rich HTML via **marked.js**
- Full typography: headings, blockquotes, code blocks, tables, images, links
- Same styling as the Payas Editor preview pane

### Plain Text (`.txt`)

- Loaded as preformatted text
- Respects line breaks and indentation
- Same font and colour settings as Markdown view

---

## 6. Reading Features

### Zoom

| Action | Result |
|---|---|
| Zoom In / Out buttons | ±10% increments |
| Mouse wheel | Scroll-zoom on PDF/image content |
| Zoom % input | Type exact value and press Enter |
| `Ctrl+0` | Reset to 100% |

PDF zoom is configured separately in settings (0.5×–3×).

### Page Navigation (PDF / EPUB)

Use the toolbar arrow buttons, the page-number input, or the keyboard arrow keys to move between pages. PDF renders pages lazily — only visible and nearby pages are drawn.

### Bookmarks

Click the **bookmark** button in the toolbar to save the current page. Bookmarks are listed in the sidebar **Bookmarks** panel with the page number and a custom label. Click a bookmark to jump to that page. Bookmarks are persisted in `localStorage` keyed by a file hash.

### Focus Mode

Press `F10` or click the focus button to hide the toolbar, find bar, and status bar for a fully distraction-free reading experience. Any key press or mouse movement reveals the UI briefly.

### Reading Progress Bar

An optional thin progress bar at the top of the view area tracks how far through the document you are. Toggle in Settings → Reader.

### Print

`Ctrl+P` opens the browser print dialog. A print-specific stylesheet hides all UI chrome, leaving only the document content.

---

## 7. Sidebar Panels

Toggle the sidebar with `Ctrl+B` or the ☰ button. On mobile the sidebar appears as a full-height overlay.

### TOC (Table of Contents)

Available for EPUB and Markdown documents. Shows a hierarchical list of headings (levels 0–3). Click any entry to jump to that section.

### Bookmarks

Lists all bookmarks saved for the currently loaded file. Each entry shows the page reference and label. Click to navigate; use the delete button to remove.

### Info

Displays file metadata:
- File name
- File size
- Total page count (PDF) or chapter count (EPUB)
- Format/type

---

## 8. Find & Search

Open with `Ctrl+F` or the toolbar search button.

| Control | Description |
|---|---|
| Search input | Type to find; results are highlighted in the document |
| Match counter (n/m) | Shows current match and total match count |
| ◀ Previous | Jump to the previous match |
| ▶ Next | Jump to the next match |
| ✕ Close | Close the find bar (`Escape` also works) |

---

## 9. Keyboard Shortcuts

| Shortcut | Action |
|---|---|
| `Ctrl+O` | Open file |
| `Ctrl+B` | Toggle sidebar |
| `Ctrl+F` | Open find bar |
| `Ctrl+P` | Print |
| `Ctrl+=` | Zoom in |
| `Ctrl+−` | Zoom out |
| `Ctrl+0` | Reset zoom |
| `←` | Previous page |
| `→` | Next page |
| `F10` | Toggle focus mode |
| `F11` | Toggle fullscreen |
| `Home` | Scroll to top |
| `Escape` | Close find bar / close modal |

---

## 10. Settings Reference

Open via **Settings** in the title bar.

### Text Style

| Setting | Range / Options | Default |
|---|---|---|
| Font family | DM Sans · Fraunces · JetBrains Mono · Georgia | DM Sans |
| Font size | 12–28 px (slider) | 17 px |
| Line height | 1.4–2.2 (slider) | 1.8 |
| Max content width | 400–1200 px (slider) | 720 px |
| Text justification | Toggle on/off | Off |
| Hyphenation | Toggle on/off | Off |

### Appearance

| Setting | Options | Default |
|---|---|---|
| Theme | Light / Dark | Light |
| Accent colour | 6 colour swatches | Green (#2d6a4f) |

### Reader

| Setting | Options | Default |
|---|---|---|
| Reading progress bar | Toggle on/off | Off |
| PDF zoom level | 0.5×–3× (slider) | 1.5× |
| PDF render quality | 0.5–2.0 (slider) | 1.0 |

---

## 11. Storage & Data

### localStorage Keys

| Key | Contents |
|---|---|
| `payas_cfg` | JSON object of all user settings |
| `payas_bm` | JSON object mapping file hash → array of bookmark objects |

### Bookmark Object

```json
{
  "page":  12,
  "label": "Chapter 3 — Introduction",
  "ts":    "2025-06-01T10:00:00.000Z"
}
```

### Settings Object (`payas_cfg`)

```json
{
  "theme":       "light",
  "accent":      "#2d6a4f",
  "fontFamily":  "DM Sans, sans-serif",
  "fontSize":    17,
  "lineHeight":  1.8,
  "maxWidth":    720,
  "justify":     false,
  "hyphens":     false,
  "progressBar": false,
  "pdfZoom":     1.5,
  "pdfQuality":  1.0
}
```

---

## 12. Architecture & Code Structure

Payas Reader is a **single HTML file** — no bundler, no framework, no server.

```
payas-reader.html
├── <style>          CSS custom properties, layout, sidebar, viewer
├── <body>
│   ├── Title Bar    Open, settings, theme, filename badge
│   ├── Toolbar      Zoom, page nav, search, focus, fullscreen, print
│   ├── Find Bar     Search UI with match counter
│   ├── Body Row
│   │   ├── Sidebar  TOC · Bookmarks · Info panels
│   │   └── Viewer   Text view / PDF canvas pages / EPUB rendition
│   └── Status Bar   Page count · Reading progress
└── <script>         All application logic (vanilla JS)
    ├── Config & theme       loadCfg, applyCfg, saveSettings, setTheme, setAccent
    ├── File loading         loadPDF, loadEPUB, loadMD, loadTXT
    ├── PDF rendering        renderPage, renderVisiblePages (IntersectionObserver)
    ├── EPUB control         epub.js rendition, theme sync, chapter navigation
    ├── Navigation           prevPage, nextPage, goToPage
    ├── Zoom                 zoomIn, zoomOut, zoomReset
    ├── Search               toggleFind, doSearch, findNext, findPrev
    ├── Bookmarks            addBookmark, renderBookmarks, deleteBookmark
    ├── TOC                  buildTOC, renderTOC
    ├── UI                   toggleSidebar, setSidebarPanel, toggleFocus, toggleFS
    └── Utilities            formatFileSize, hashFile, scrollToTop
```

---

## 13. JavaScript API Reference

All functions are in global scope within the single HTML file.

### File Loading

```js
loadPDF(file)     // Initialize PDF.js, render pages, extract TOC
loadEPUB(file)    // Load EPUB via epub.js, setup rendition and TOC
loadMD(file)      // Parse Markdown → HTML via marked.js, render
loadTXT(file)     // Load plain text, display as preformatted block
```

### Navigation

```js
prevPage()        // Go to the previous PDF/EPUB page
nextPage()        // Go to the next PDF/EPUB page
goToPage(n)       // Jump to a specific page number
scrollToTop()     // Scroll the viewer to the top
```

### Zoom

```js
zoomIn()          // Increase zoom by one step
zoomOut()         // Decrease zoom by one step
zoomReset()       // Return to 100% zoom
```

### Search

```js
toggleFind()      // Show / hide the find bar
doSearch(term)    // Run a search and highlight matches
findNext()        // Advance to the next match
findPrev()        // Go back to the previous match
```

### Bookmarks

```js
addBookmark()               // Save a bookmark for the current position
renderBookmarks()           // Redraw the bookmarks sidebar panel
deleteBookmark(fileHash, i) // Remove a bookmark by index
```

### Settings & Theme

```js
loadCfg()         // Read settings from localStorage
applyCfg()        // Apply all settings to the UI
saveSettings()    // Write current settings to localStorage
setTheme(dark)    // true = dark, false = light
setAccent(color)  // Apply an accent hex colour
```

### UI

```js
toggleSidebar()         // Show / hide the sidebar
setSidebarPanel(name)   // Switch sidebar to 'toc' | 'bookmarks' | 'info'
toggleFocus()           // Enter / exit focus (distraction-free) mode
toggleFS()              // Enter / exit browser fullscreen
```

---

## 14. License

MIT License

Copyright © Saman Wijesinghe

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.