🌬️ Wisp Wiki

Welcome to the Wisp documentation! This wiki contains comprehensive guides for using, developing, and contributing to Wisp.

📚 Quick Navigation

🎯 What is Wisp?

Wisp is a context-aware, zero-dependency UI engine that analyzes your HTML structure and automatically generates optimized CSS. Unlike traditional frameworks that require you to add classes or configure themes, Wisp examines your content and adapts the styling accordingly.

Key Features

• Zero Configuration: Works out of the box with semantic HTML
• Context-Aware: Automatically detects content type (narrative, dashboard, form, minimal)
• Lightweight: <5KB total payload (2KB CSS + 2KB JS)
• Zero Dependencies: No build tools, no npm, no bundlers required
• Accessibility First: Auto-generates skip links and respects user preferences

🚀 Quick Start

# Clone and setup
git clone https://github.com/rotsl/wisp.git
cd wisp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Analyze a webpage
./wisp-fetch https://en.wikipedia.org/wiki/Wiki --open

📊 Live Dashboards

• GitHub Pages: https://rotsl.github.io/wisp/
• GitLab Pages: https://wisp-d69513.gitlab.io/

🤝 Contributing

We welcome contributions! See Contributing for guidelines.

📄 License

MIT License - see LICENSE file.

---

### **Installation.md** (GitHub Wiki)

```markdown
# Installation Guide

This guide covers installing Wisp on different operating systems.

## 📋 Prerequisites

- Python 3.8 or higher
- Git
- (Optional) Node.js if you want to modify the JavaScript runtime

## 🍎 macOS Installation

### Step 1: Clone Repository
```bash
git clone https://github.com/rotsl/wisp.git
cd wisp

Step 2: Create Virtual Environment

python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Verify Installation

python scripts/build.py
python tests/test_scanner.py

Step 5: (Optional) Install CLI Globally

sudo ln -s $(pwd)/wisp-fetch /usr/local/bin/wisp-fetch

🐧 Linux Installation

Ubuntu/Debian

# Install Python and pip
sudo apt update
sudo apt install python3 python3-pip python3-venv git

# Clone and setup
git clone https://github.com/rotsl/wisp.git
cd wisp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Fedora/RHEL

sudo dnf install python3 python3-pip git
# Follow same steps as Ubuntu

🪟 Windows Installation

Using Command Prompt

git clone https://github.com/rotsl/wisp.git
cd wisp
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

Using PowerShell

git clone https://github.com/rotsl/wisp.git
cd wisp
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

🧪 Testing Installation

Run the test suite to ensure everything works:

python tests/test_scanner.py

Expected output:

Running Wisp Scanner tests...
✓ Narrative detection
✓ Dashboard detection
✓ Form detection
✓ CSS generation
✓ Density calculation

✅ All tests passed!

🔄 Updating Wisp

To update to the latest version:

cd ~/wisp
git pull origin main
source venv/bin/activate
pip install -r requirements.txt --upgrade

🗑️ Uninstallation

Simply delete the directory:

rm -rf ~/wisp
# If you created a symlink:
sudo rm /usr/local/bin/wisp-fetch

🐛 Troubleshooting

Issue: python: command not found

Solution: Use python3 instead of python on macOS/Linux

Issue: pip install fails with permissions

Solution: Ensure virtual environment is activated (you should see (venv) in prompt)

Issue: wisp-fetch: command not found

Solution: Use ./wisp-fetch from the wisp directory, or use the full path

📦 Dependencies

Core dependencies (automatically installed):

• beautifulsoup4>=4.12.0
• lxml>=4.9.0
• requests>=2.31.0

Optional (for minification):

• jsmin>=3.0.0
• rcssmin>=1.1.0