stormirc/README.md

# StormIRC

A completely accessible GUI IRC client built specifically for blind users and anyone who values keyboard-first design. Built with Python and Qt6 (PySide6).

## Features

### 🎯 Accessibility First
- **Screen Reader Support**: Fully compatible with Orca, NVDA, and other screen readers
- **Keyboard Navigation**: Complete keyboard control - mouse optional
- **Text-to-Speech**: Optional Speech Dispatcher integration for self-voicing
- **Cursor Navigation**: Arrow keys work in chat history for easy navigation

### 💬 Full IRC Protocol Support
- Multi-server support with SSL/TLS
- SASL PLAIN authentication
- Channel management (join, part, topic)
- Private messages in tabs
- User lists per channel
- Nick changes, WHOIS, CTCP ACTION (/me)
- Automatic reconnection with exponential backoff
- CAP negotiation (IRCv3)

### 🗂️ Tabbed Interface
- **Server Console** tab for server messages
- **One tab per channel** with independent chat, topic, user list, and input
- **One tab per PM** conversation (no separate windows!)
- Easy tab navigation with keyboard shortcuts

### ⚙️ Highly Configurable
- Multi-server configuration with auto-connect
- Per-channel autojoin settings
- Customizable highlight patterns (regex)
- Speech settings (rate, pitch, volume, voice selection)
- Window dimensions and UI preferences
- Export/import configuration for backup

### 🔔 Smart Notifications
- System notifications for highlights and PMs
- Customizable regex highlight patterns
- Unread message counters
- Sound notifications

### 🎹 Programmable Function Keys
- F1-F12 keys can execute:
  - Plain text messages
  - IRC commands (e.g., `/away I'm away`)
  - Shell commands (e.g., `/usr/bin/date`)
  - Shell with output to channel (e.g., `/usr/bin/fortune|`)

### 🔗 Link Management
- **Automatic URL Detection**: All http/https links are detected and tracked
- **Per-Tab History**: Each channel/PM maintains its own link history (default 25 links)
- **Page Title Fetching**: Automatically fetches page titles for better context
- **Keyboard Shortcuts**:
  - **Alt+K**: Open most recent link in current tab
  - **Alt+U**: Show URL history menu (arrow keys to navigate)
- **Configurable Browser**: Use custom browser or xdg-open
- **Deduplication**: Same URL won't appear twice in history

## Installation

### Prerequisites

**Required:**
- Python 3.8 or later
- Qt6 (via PySide6)

**Optional (for text-to-speech):**
- Speech Dispatcher

### Install Steps

1. **Clone the repository:**
   ```bash
   git clone https://git.stormux.org/storm/stormirc.git
   cd stormirc
   ```

2. **Install Python dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

3. **Optional - Install Speech Dispatcher:**
   ```bash
   # Arch/Manjaro:
   sudo pacman -S speech-dispatcher python-speechd

   # Debian/Ubuntu:
   sudo apt install python3-speechd

   # Fedora:
   sudo dnf install python3-speechd
   ```

4. **Run StormIRC:**
   ```bash
   ./stormirc
   ```

   Or with debug logging:
   ```bash
   ./stormirc -d
   ```

## Keyboard Shortcuts

### Tab Navigation
- **Ctrl+Tab**: Next tab
- **Ctrl+Shift+Tab**: Previous tab
- **Ctrl+W**: Close current tab (sends PART for channels)
- **Alt+7**, **Alt+8**, **Alt+9**: Jump to tab 7, 8, or 9

### Configuration
- **Ctrl+S**: Save settings to disk

### Within a Tab
- **F6**: Cycle focus (chat → input → user list → chat)
- **Ctrl+L**: Focus input field from anywhere
- **Enter** on user in user list: Open PM tab
- **Shift+Enter** in input: Insert newline (for multi-line messages)
- **Enter** in input: Send message

### Speech Control
- **Ctrl**: Stop speech immediately
- **Alt+1**: Decrease volume (-10)
- **Alt+2**: Increase volume (+10)
- **Alt+3**: Decrease pitch (-10)
- **Alt+4**: Increase pitch (+10)
- **Alt+5**: Decrease rate (-10)
- **Alt+6**: Increase rate (+10)

**Note:** Speech adjustments apply immediately, save to config, and announce the new value.

### Link Management
- **Alt+K**: Open last link in current tab
- **Alt+U**: Show URL history menu (arrow keys to navigate, Enter to open, Escape to cancel)

### Function Keys
- **F1-F12**: Execute programmable commands (configure in Settings)

## IRC Commands

StormIRC supports all standard IRC commands. Just prefix with `/`:

### Channel Management
- `/join #channel` - Join a channel
- `/part [#channel]` - Leave current or specified channel
- `/list` - Browse available channels (opens dialog)
- `/topic [new topic]` - View or set channel topic

### User Communication
- `/msg <nick> [message]` - Open PM tab and optionally send message
- `/query <nick>` - Open PM tab (alias for /msg)
- `/me <action>` - Send CTCP ACTION
- `/whois <nick>` - Get user information

### Configuration
- `/autojoin` - Show autojoin channels for current server
- `/autojoin add #channel1,#channel2` - Add channels to autojoin
- `/autojoin remove #channel` - Remove channel from autojoin
- `/autojoin clear` - Clear all autojoin channels
- `/autojoin list` - List autojoin channels

### Connection
- `/nick <newnick>` - Change nickname
- `/quit [message]` - Disconnect and quit application

### Any Other IRC Command
Send raw IRC commands by prefixing with `/`:
- `/mode #channel +o nick` - Give ops
- `/kick #channel nick [reason]` - Kick user
- `/away [message]` - Set away status
- etc.

## Configuration

StormIRC stores configuration in `~/.config/stormirc/config.json`.

### Settings Dialog

Access via menu or keyboard shortcut. Six tabs:

1. **General**: Window dimensions, timestamps, theme, browser path, link history limit
2. **Accessibility**: Screen reader, notifications, display options
3. **Speech**: TTS enable/disable, rate, pitch, volume, voice selection
4. **Servers**: Add, edit, remove IRC servers
5. **Highlights**: Manage regex highlight patterns
6. **Function Keys**: Configure F1-F12 programmable keys

### Server Configuration

Each server can have:
- Host, port, SSL/TLS
- Nickname, username, real name
- Optional server password
- SASL authentication (username/password)
- Auto-connect on startup
- Auto-join channels (per-channel checkbox)

### Message Logging

All messages are automatically logged to `~/.config/stormirc/logs/`:
- Per-server, per-channel log files
- Daily rotation (YYYY-MM-DD format)
- Recent history loaded when opening channels

## Accessibility Features

### Screen Reader Compatibility
- Proper ARIA roles and labels for all UI elements
- Live message announcements (when window is active)
- Logical tab order
- Context announcements when switching tabs

### Keyboard-First Design
- All functionality accessible via keyboard
- No mouse-only interactions
- Intuitive keyboard shortcuts
- F6 cycling for common navigation patterns

### Text-to-Speech (Optional)
- Speech Dispatcher integration
- Configurable voice, rate, pitch, volume
- On-the-fly adjustments with Alt+1 through Alt+6
- Per-message speech control
- Interrupt speech with Ctrl key
- Optional reading of your own messages

### Visual Accessibility
- High DPI support
- Customizable font sizes
- Clear focus indicators
- Unread message indicators

## Architecture

```
stormirc/
├── stormirc               # Main executable
├── requirements.txt       # Python dependencies
└── src/
    ├── irc/
    │   └── client.py      # IRC protocol implementation
    ├── config/
    │   └── settings.py    # Configuration management
    └── ui/
        ├── main_window.py # Main tabbed window
        ├── channel_tab.py # Reusable tab widget
        ├── accessible_tree.py # Accessible tree widget
        ├── settings_dialog.py # Settings dialog
        ├── autocomplete_textedit.py # Text input with autocomplete
        ├── link_menu_dialog.py # URL history dialog
        ├── url_utils.py   # URL detection and handling
        ├── speech.py      # Speech Dispatcher TTS
        ├── sound.py       # Sound notifications
        └── logger.py      # Message logging
```

### Threading Model
- IRC client runs in background daemon thread
- UI updates via Qt signals/slots (thread-safe)
- Speech runs in separate thread to avoid blocking

## Known Limitations

- No DCC file transfers yet
- No channel modes UI (use `/mode` command)
- No message formatting (bold/italic/colors) yet
- No custom keyboard shortcut configuration yet

## Contributing

This project prioritizes accessibility. When contributing:

1. **Never break screen reader functionality** - This is the highest priority
2. **Test with a screen reader** (Orca on Linux, NVDA on Windows)
3. **Maintain keyboard navigation** - All features must be keyboard accessible
4. **Follow code quality standards** - See `.claude/CLAUDE.md` for details

## License

[Add your license here]

## Credits

Built with Python, Qt6 (PySide6), and lots of care for the user experience.

StormIRC proves that accessibility and good UX aren't mutually exclusive.