Speed Reader (Offline Local Site)

A lightweight, high-performance, and entirely offline application designed for speed reading using Rapid Serial Visual Presentation (RSVP). This document outlines the comprehensive specifications, architectural patterns, tech stack details, and developmental milestones for building the application.

---

📖 Table of Contents

1. Overview
2. Product Requirements
3. Technology Stack
4. System Architecture
5. Milestones & Roadmap
6. Offline Verification Guide

---

⚡ Overview

Traditional reading involves moving eyes screen-wide from left to right, which is inherently throttled by physical eye muscles. Rapid Serial Visual Presentation (RSVP) circumvents this visual sweep limit by flashing individual words sequentially in a fixed focal position on the screen.

This application allows users to paste raw text, adjust their reading velocity (in Words Per Minute), and read content efficiently with zero internet connection dependencies.

---

🎯 Product Requirements

1. Offline Execution

• 100% Client-Side Reliance: The core reading visualizers must run entirely without external CDNs, third-party APIs, or standard cloud handshakes.
• Asset Bundling: All visual styling, fonts, and scripts must be hosted and served locally.

2. Rich Text Input

• Input Canvas: A clean, spacious, high-contrast <textarea> accepting diverse copy-pasted document formats.
• Input Handlers: Dynamic character cleanups, line-break sanitizations, and whitespace trimming.

3. Core RSVP Engine (Reading Display)

• Visual Focus Center: A large, prominent focal display frame positioned in the physical center of the interface.
• Optimal Recognition Point (ORP): The engine should center each word slightly to the left of its physical middle (specifically near the 35-40% mark of the word) and highlight this focal character in red to maximize peripheral character recognition.
• Dynamic Interval Sliching: Support for adjusting focal dwell times on longer words or punctuation to keep reading flow organic.

4. Interactive Feedback & Playback Controls

• Interactive Control Ribbons: Dedicated visual triggers for Play, Pause, and Reset/Stop.
• Progress Scrubber: Visual indicators tracking the reading progress (e.g., word count tracker, remaining time estimator, progress bar).

5. Precision Speed Slider

• Words Per Minute (WPM) Controls: Adjustable slider ranging from 100 WPM to 1000 WPM with precise, real-time speed calculation adjustments.

6. Modular Codebase Separation

• Clean Boundaries: The logic must be cleanly divided into dedicated modules (e.g., text parser, interval timers, state controllers, UI layout handlers) rather than a monolithic script block.

---

💻 Technology Stack

                     ┌────────────────────────┐
                     │    Express.js Server   │ (Local serving and support
                     │      (node_modules)     │  for future local loaders)
                     └───────────┬────────────┘
                                 │ Serve Static Files
                                 ▼
                     ┌────────────────────────┐
                     │   HTML5 / CSS3/ JS     │ (Static Client Assets)
                     └───────────┬────────────┘
                                 │ ESM Imports
                     ┌───────────┴────────────┐
                     │  Modular ES6 Engines   │ (Parser, RSVP, Timer Modules)
                     └────────────────────────┘

The stack is kept highly clean to guarantee instantaneous local execution:

• Backend Environment: Node.js coupled with a minimal, zero-dependency Express server serving assets purely on port 3000. This provides an extensible foundation if local file loaders (e.g., parsing local .pdf, .epub, or .txt binary inputs) are integrated later.
• Frontend Delivery: Semantic HTML5, high-contrast CSS3 focusing on eye straining reduction, and vanilla JavaScript (ES6 Modules) to implement dynamic speed control interfaces cleanly.

---

🏗️ System Architecture

📁 Directory Layout

The proposed modular workspace ensures separation of concerns:

/
├── server.js                 # Minimal Express server to host static local directory
├── public/
│   ├── index.html            # Core structural shell of the Speed Reader
│   ├── styles.css            # Clean, dark-mode display sheets with focus styling
│   └── js/
│       ├── main.js           # UI binder and initialization entry-point
│       ├── parser.js         # Tokenizes text strings and sanitizes punctuations
│       └── engine.js         # Precise RSVP interval tracker and state engine
└── package.json              # Minimal Node metadata configuration

---

📅 Milestones & Roadmap

  ┌────────────────────────────────────────────────────────────────────────┐
  │  MILESTONE 1: Local Server Setup & Semantic HTML Interface             │
  └───────────────────────────────────┬───────────────────────────────────┘
                                      ▼
  ┌────────────────────────────────────────────────────────────────────────┐
  │  MILESTONE 2: ES6 Parsing Module & Text Sanitization Logic             │
  └───────────────────────────────────┬───────────────────────────────────┘
                                      ▼
  ┌────────────────────────────────────────────────────────────────────────┐
  │  MILESTONE 3: High-Frequency RSVP Core State Engine & Timers            │
  └───────────────────────────────────┬───────────────────────────────────┘
                                      ▼
  ┌────────────────────────────────────────────────────────────────────────┐
  │  MILESTONE 4: Interactive Control Loops & Real-time WPM Calibration    │
  └───────────────────────────────────┬───────────────────────────────────┘
                                      ▼
  ┌────────────────────────────────────────────────────────────────────────┐
  │  MILESTONE 5: UX Refinement, Dark-Mode Pairing & Local Testing         │
  └────────────────────────────────────────────────────────────────────────┘

Milestone 1: Client Shell & Local Serving Host

• Set up a minimal local server routing using express serving static root streams.
• Construct index markup representing two core screens:
  1. Preparation Pane: Input area, speed preferences, document statistics.
  2. Reader Pane: Visual focal canvas (massive typography) and media-player style sliders.

Milestone 2: Text Parsing Engine

• Create /js/parser.js specializing in string ingestion.
• Implement support for:
  • Splitting text securely on regular spaces and line breaks.
  • Tracking punctuation delimiters to inject conversational pausing delays (e.g., matching ., ,, !, ? to temporarily insert delay modifiers).
  • Removing rogue hidden control characters.

Milestone 3: Core Visualizer (RSVP Engine)

• Create /js/engine.js implementing a deterministic state machine:
  • States: IDLE, PLAYING, PAUSED, FINISHED.
• Leverage high-precision timers (setInterval or customized requestAnimationFrame ticks) to schedule RSVP text renders without layout shifts.
• Auto-adjust presentation timing per-word based on length to maintain a natural comprehension flow.

Milestone 4: Control Inputs & WPM Calibration

• Wire physical buttons to engine bindings (play(), pause(), stop()).
• Implement interactive range sliders translating immediate user range offsets (e.g., 350 WPM $\approx$ 171ms per word focal cycle) into live speed interval updates.
• Track active reading index position to support dynamic pausing and resumes.

Milestone 5: Refinement & Complete Offline Validation

• Ensure all styling assets are local copies (no external Font Awesome, Google Font links, or CDN scripts).
• Refine the typography choices and layout dimensions for optimal readability.
• Perform comprehensive memory leak analysis to guarantee that lengthy reading tasks do not degrade thread performance.

---

🔒 Offline Verification Guide

To test full offline capabilities during development and deploy the server locally:

1. Clean Installation: Ensure all primary static assets are fully contained inside the directory tree.
2. Offline Simulation: Start the local service, disconnect the development machine from the local networking router, and confirm that all media states, parser triggers, speed settings, and UI styling remain fully interactive and pixel-perfect.