=== Chat for WebIRC ===
Contributors: jtzl
Tags: irc, websocket, chat, real-time, communication
Requires at least: 6.8
Tested up to: 6.9
Stable tag: 1.0.0
Requires PHP: 8.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A framework-light WordPress plugin that embeds a WebSocket IRC client.

== Description ==

This plugin provides a shortcode that renders a lightweight IRC client written in vanilla JavaScript. It supports direct WebSocket connections to IRC servers (IRCv3-friendly) and includes an optional WebIRC gateway.

**Security-conscious defaults:**

* Server allow-list (host:port format), WSS (WebSockets over SSL/TLS) only
* Optional WebSocket subprotocols (e.g., `text.ircv3.net`)
* Optional WS path (e.g., `/webirc`)
* Optional CSP connect-src helper (off by default)
* Input sanitization and validation
* Proper escaping of output

**Features:**

* **Modern Responsive Design**: Mobile-first approach with adaptive layouts for all screen sizes
* **Enhanced Mobile Experience**: Touch-optimized interface with proper virtual keyboard support
* **Smart Responsive Behavior**: Overlay sidebar on mobile, collapsible on tablet, side-by-side on desktop
* **Editable Username**: Click-to-edit nickname with real-time validation and user persistence
* **User Persistence**: Automatic nickname saving for logged-in WordPress users
* Lightweight vanilla TypeScript/JavaScript implementation (no frameworks)
* Fully responsive design with semantic HTML
* Internationalization ready (i18n strings)
* Configurable server allow-list with strict validation
* WebSocket subprotocol support (IRCv3)
* Optional WebIRC gateway fallback
* Comprehensive IRC slash commands: 30+ commands including /join, /part, /nick, /msg, /whois, /topic, /away, /help, and more
* Automatic nickname generation and collision handling
* Debug logging and connection status indicators
* Optional Content Security Policy (CSP) header generation
* WordPress hooks and filters for extensibility
* Follows WordPress Coding Standards

== Usage ==

**Basic Usage:**
Simply add the shortcode `[chat_webirc]` to any page or post where you want the IRC chat to appear. The plugin will use secure default settings to connect to a test IRC server.

**Shortcode Examples:**
* Basic: `[chat_webirc]` - Uses default server and channel
* Custom channel: `[chat_webirc channel="#mychannel"]`
* Custom server: `[chat_webirc server="irc.example.com:7443" channel="#general"]`

**Available IRC Commands:**
Once the chat is loaded, users can use these commands:

**Basic Commands:**
* `/join #channel` - Join a channel
* `/part [#channel]` - Leave current or specified channel
* `/nick newname` - Change nickname
* `/quit [message]` - Disconnect
* `/help` - Show all available commands

**Communication:**
* `/msg <nick> <message>` - Send private message
* `/notice <target> <message>` - Send notice message
* `/me <action>` - Send action message
* `/query <nick>` - Open private chat context

**User & Channel Info:**
* `/whois <nick>` - Get detailed user information
* `/who [channel]` - List users in channel
* `/list [pattern]` - List available channels
* `/names [channel]` - List nicknames in channel
* `/topic [text]` - View/set channel topic

**Status & Utility:**
* `/away [message]` - Set away status
* `/back` - Remove away status
* `/ping <nick>` - Ping user
* `/version [nick]` - Get version info

**Advanced Commands:**
* `/ctcp <nick> <command>` - Send CTCP command
* `/motd [server]` - View message of the day
* `/stats <query> [server]` - View server statistics
* `/raw <command>` - Send raw IRC command (if enabled)

Type `/help` in the chat for the complete command reference.

**Configuration:**
Go to **Settings → Chat for WebIRC** in your WordPress admin to customize servers, channels, and security options.

== Installation ==

1. Upload the plugin files to the `/wp-content/plugins/chat-webirc/` directory, or install the plugin through the WordPress plugins screen directly.
2. Activate the plugin through the 'Plugins' screen in WordPress.

**Next Steps - Getting Started:**

After activation, you're ready to use the IRC chat! The plugin comes with secure default settings that will connect to a test IRC server.

**Quick Start:**
1. Create or edit any page/post where you want the IRC chat to appear
2. Add the shortcode: `[chat_webirc]`
3. Save and view your page - the IRC chat will be embedded and ready to use!

**Default Settings:**
* **Server**: `irc.livefreeonline.club:7443` (secure test server)
* **Channel**: `#help` (general help channel)

**Customize Settings (Optional):**
Visit **Settings → Chat for WebIRC** in your WordPress admin to:
* Add your own IRC servers to the allowed servers list
* Change the default server and channel
* Configure advanced options like WebSocket paths and subprotocols
* Enable per-shortcode overrides for multiple chat instances

**Advanced Usage:**
Use shortcode parameters to override defaults: `[chat_webirc server="irc.livefreeonline.club:7443" channel="#mychannel"]`

== Frequently Asked Questions ==

= What IRC servers are supported? =

The plugin works with any IRC server that supports WebSocket connections. By default, it includes:
* `irc.livefreeonline.club:7443` - An IRC server contributed by our team for testing purposes

= Is this secure? =

Yes, the plugin implements several security measures:
* Server allow-list to prevent connections to unauthorized servers
* Input sanitization and validation
* Proper escaping of all output
* Optional Content Security Policy headers
* WSS (secure WebSocket connections) only

= Can I use my own IRC server? =

Yes, you can add your own IRC server to the allowed servers list in the plugin settings. The server must support WebSocket connections and be accessible via WSS (secure WebSockets).

= Does this work with private IRC networks? =

The current version is designed for public IRC servers. For private networks that require extra authentication, we will add support for them in future versions.

= Do I need an SSL certificate to use this plugin? =

The IRC server must have an SSL certificate for WSS (WebSockets Secure) connections to work. Your WordPress website doesn't strictly require SSL, but it's highly recommended:

* **IRC server**: SSL certificate required (mandatory for WSS connections)
* **WordPress site**: SSL recommended but not mandatory for basic functionality

For security reasons, the plugin only supports secure WSS connections and does not support unencrypted WebSocket connections.

= What shortcode parameters are available? =

The shortcode supports:
* `server`: IRC server (host:port, must be in allowed servers list)
* `channel`: Channel name (with # prefix)

Example: `[chat_webirc server="irc.livefreeonline.club:7443" channel="#help"]`

= What IRC commands are supported? =

The client supports 30+ comprehensive IRC slash commands organized by category:

**Basic Commands:**
* `/join #channel` - Join a channel
* `/part [#channel]` or `/leave [#channel]` - Leave current/specified channel
* `/nick newname` - Change nickname
* `/quit [message]` - Disconnect from server

**Communication:**
* `/msg <nick> <message>` or `/privmsg <nick> <message>` - Send private message
* `/notice <target> <message>` - Send notice message (less intrusive)
* `/me <action>` - Send action message
* `/query <nick>` - Open private chat context

**User Information:**
* `/whois <nick>` - Get detailed user information
* `/who [channel]` - List users in channel
* `/userhost <nick> [nick2]...` - Get user host information
* `/ison <nick> [nick2]...` - Check if users are online
* `/finger <nick>` - Send FINGER request

**Channel Information:**
* `/list [pattern]` - List available channels
* `/names [channel]` - List nicknames in channel
* `/topic [text]` - View or set channel topic

**Server Information:**
* `/motd [server]` - View message of the day
* `/admin [server]` - View server admin info
* `/info [server]` - View server information
* `/stats <query> [server]` - View server statistics
* `/links [mask]` - List server links
* `/lusers [mask]` - List user statistics
* `/time [server]` - Get server time
* `/version [nick]` - Get version info

**Status & Utility:**
* `/away [message]` - Set away status
* `/back` - Remove away status
* `/ping <nick>` - Ping user

**Advanced:**
* `/ctcp <nick> <command>` - Send CTCP command (VERSION, TIME, PING, FINGER)
* `/raw <IRC command>` - Send raw IRC command (if enabled by admin)

**Help:**
* `/help` - Show complete command reference with usage examples

All commands include proper error handling and usage instructions when used incorrectly.

= Does this work well on mobile devices? =

Yes! Version 0.5.0 includes a complete mobile overhaul with:
* **Responsive Design**: Adapts perfectly to phones, tablets, and desktops
* **Touch-Optimized**: Proper touch targets and gesture support
* **Mobile-First Layout**: Optimized for small screens with smart sidebar behavior
* **Orientation Support**: Works great in both portrait and landscape modes

= Can users change their nickname? =

Yes! Version 0.6.0 introduces an editable username feature:
* **Click-to-Edit**: Simply click on your nickname in the chat header to edit it
* **Real-time Validation**: Instant feedback on nickname validity according to IRC standards
* **User Persistence**: Logged-in WordPress users have their nicknames automatically saved and restored
* **Keyboard Shortcuts**: Press Enter to save or Escape to cancel
* **Guest Support**: Non-logged-in users can still change nicknames, but they won't be saved between sessions

= What are the admin settings? =

The settings page includes:
* **Allowed servers**: One per line (host:port format)
* **Default server**: Selected from allowed servers list
* **Default channel**: e.g., #general
* **WebSocket path**: e.g., /webirc (optional)
* **Subprotocols**: Comma-separated, e.g., text.ircv3.net
* **Gateway URL**: Optional WSS fallback
* **Allow per-shortcode overrides**: Restricted to allowed servers list
* **Add CSP header**: For connect-src (advanced)
* **Enable debug logs**: Show debug messages in chat

== Screenshots ==

1. Plugin settings page
2. IRC chat interface embedded in a page
3. Connection status and message display

== Changelog ==

= 1.0.0 =
* **Removed**: User avatar upload feature. Messages now display as `[HH:MM] username ▸ text` with no avatar bubble. The `chat_webirc_upload_avatar` / `chat_webirc_get_avatar` / `chat_webirc_get_user_avatars` AJAX endpoints, the `chat-webirc-avatar` user meta, and the `chat-webirc-avatars/` and `chat-webirc-temp/avatars/` directories are no longer used.
* **Cleanup note**: Sites can safely delete `wp-content/uploads/chat-webirc-avatars/` and `wp-content/uploads/chat-webirc-temp/`. Avatar user meta and the `chat_webirc_temp_avatars` option are removed on plugin uninstall.

= 0.9.0 =
* **Removed**: In-chat image sharing (upload, display, and preview). The `chat_webirc_upload_image` AJAX endpoint, the `image_expiration` setting, and the `chat-webirc-temp` storage directory are gone.
* **Retained**: User avatar upload remains unchanged.
* **Cleanup note**: Sites that previously used image sharing can delete files directly inside `wp-content/uploads/chat-webirc-temp/`, but **do not delete the `avatars/` subdirectory** — it is still used as a staging area for guest user avatars.

= 0.7.0 =
* **Custom Avatars**: User avatar upload with cropping, preview, and persistent storage
* **WordPress Integration**: Full integration with WordPress media library and user meta
* **Error Handling**: Graceful error handling with user-friendly feedback messages

= 0.6.0 =
* **Editable Username Interface**: Click-to-edit nickname functionality with inline editing
* **User Persistence**: Automatic nickname saving for logged-in WordPress users
* **Real-time Validation**: Client-side IRC nickname validation with helpful error messages
* **Smart Nickname Loading**: Automatic loading of saved nicknames for returning users
* **Improved UX**: Loading states, success feedback, and error handling for nickname changes
* **WordPress Integration**: New AJAX endpoints for saving and retrieving user nicknames
* **Guest User Support**: Graceful fallback for non-logged-in users with session-based nicknames
* **Mobile-Optimized Editing**: Touch-friendly edit interface that works seamlessly on all devices

= 0.5.0 =
* **Major UI Overhaul**: Complete redesign of the chat interface with modern, responsive layout
* **Mobile-First Design**: Fully responsive chat window that adapts to all screen sizes
* **Enhanced Mobile Experience**: Optimized touch interactions, proper virtual keyboard handling, and improved readability on mobile devices
* **Responsive Sidebar**: Smart sidebar behavior - overlay on mobile, collapsible on tablet, side-by-side on desktop
* **Improved Message Display**: Better message grouping, optimized spacing, and responsive typography
* **Touch-Friendly Interface**: Minimum 44px touch targets for mobile users
* **Orientation Support**: Smooth transitions and optimized layouts for both portrait and landscape modes
* **New Admin Settings**: Enhanced configuration options for responsive behavior and UI customization
* **Performance Optimizations**: Reduced layout thrashing and improved rendering performance

= 0.2.0 =
* Add comprehensive IRC slash commands support (30+ commands)
* Enhanced command categories: Basic, Communication, User Info, Channel Info, Server Info, Status, Advanced
* Improved command help system with detailed usage examples
* Added support for CTCP commands, server queries, user lookups, and more
* Better error handling and user feedback for all commands

= 0.1.0 =
* Initial release with full shortcode functionality
* WebSocket IRC client with IRCv3 support
* Comprehensive admin settings (server allow-list, defaults, security options)
* Comprehensive slash command support (30+ IRC commands)
* Automatic nickname handling and collision resolution
* Debug logging and connection status display
* Security: WSS-only, input sanitization, optional CSP headers
* TypeScript source with proper documentation

== Notes ==

* Some public IRC networks may restrict WebSocket connections to certain origins. The included test server permits connections for testing purposes.
* Do not send sensitive information. This client is intentionally minimal and does not yet support SASL authentication.
