=== Init Chat Engine – Real-Time, Community, Extensible ===
Contributors: brokensmile.2103
Tags: chat, community, realtime, shortcode, lightweight
Requires at least: 5.5
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.3.4.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A lightweight, real-time community chat system built with REST API and Vanilla JS. No jQuery, no reload. Full admin panel with moderation tools.

== Description ==

Init Chat Engine is a clean and minimal frontend chatbox plugin, designed for homepage or site-wide communication with comprehensive administrative controls.

This plugin is the core user system behind the [Init Plugin Suite](https://en.inithtml.com/init-plugin-suite-minimalist-powerful-and-free-wordpress-plugins/) – optimized for frontend-first interaction, extensibility, and real-time gamification.

GitHub repository: [https://github.com/brokensmile2103/init-chat-engine](https://github.com/brokensmile2103/init-chat-engine)

**Key Features:**

**Frontend Experience:**
- Built with 100% REST API and Vanilla JS
- No jQuery, no bloat – blazing fast
- Fully embeddable via `[init_chatbox]` shortcode
- Guest messaging support (optional)
- Smart polling system (adaptive 3.5–10s based on activity)
- Browser notifications when new messages arrive
- Scroll-up to load history, scroll-down to auto-scroll
- Optimistic sending & "new message" jump button
- Clean UI with customizable themes
- Template override supported (`chatbox.php`)

**Administrative Control:**
- **Complete Settings Panel** - Basic, Security, and Advanced configurations
- **Message Management** - Search, view, delete messages with pagination
- **User Moderation** - Ban/unban users by IP or user ID with expiration
- **Rate Limiting** - Prevent spam with configurable message limits
- **Word Filtering** - Block messages containing prohibited words
- **Statistics Dashboard** - View chat activity, user engagement, and trends
- **Cleanup Tools** - Automatic and manual cleanup of old messages
- **Custom CSS Support** - Full styling customization options

**Security & Moderation:**
- IP-based and user-based banning system
- Configurable rate limiting (messages per minute)
- Word filtering with custom blocked word lists
- Message moderation queue (optional)
- Automatic cleanup of old messages and expired bans
- Admin override capabilities

**Multilingual Ready:**
- Translation-ready with full `.pot` file included
- Vietnamese translation included
- Easy to translate to any language

Perfect for community-based sites, forums, fanpages, manga readers, SaaS dashboards, customer support, or any interactive chat widget.

== Installation ==

1. Upload the plugin to the `/wp-content/plugins/` directory.
2. Activate the plugin through the 'Plugins' menu in WordPress.
3. Configure settings under `Settings → Chat Engine`.
4. Add the `[init_chatbox]` shortcode anywhere you want the chatbox to appear.
5. Optional: Visit `Chat Engine → Management` to moderate messages and users.

== Shortcode Attributes ==

Shortcode `[init_chatbox]` supports the following attributes:

- `height` - Set chat height (e.g., `height="400px"`)
- `width` - Set chat width (e.g., `width="100%"`)
- `theme` - Apply custom theme (e.g., `theme="dark"`)
- `show_avatars` - Override avatar setting (`true`/`false`)
- `show_timestamps` - Override timestamp setting (`true`/`false`)
- `title` - Add custom chat title
- `class` - Add custom CSS classes
- `id` - Set custom container ID

Example: `[init_chatbox height="500px" title="Community Chat" theme="modern"]`

== Filters for Developers ==

This plugin provides filters and actions to allow developers to extend word filtering, message processing, and chat behavior without modifying core files.

**`init_plugin_suite_chat_engine_word_filter_strategy`**  
Modify word filtering strategy (`substring`, `word`, `regex`).  
**Applies to:** Message validation  
**Params:** `string $strategy`, `array $settings`, `string $message`

**`init_plugin_suite_chat_engine_blocked_words`**  
Modify the blocked-words list before validation.  
**Applies to:** Message validation  
**Params:** `array $blocked_words`, `array $settings`, `string $message`

**`init_plugin_suite_chat_engine_bypass_filter`**  
Bypass filtering under custom conditions (VIP, internal users, etc.).  
**Applies to:** Message validation  
**Params:** `bool $bypass`, `string $message`, `WP_User|null $user`, `array $settings`

**`init_plugin_suite_chat_engine_word_block_hit`** *(action)*  
Triggered when a word filter rule blocks a message.  
**Applies to:** Message validation  
**Params:** `string $blocked_word`, `string $message`, `string $strategy`

**`init_plugin_suite_chat_engine_enrich_message_row`**  
Extend chat message data (add flags, metadata, user info, etc.).  
**Applies to:** Backend DB → JSON output  
**Params:** `array $message_row`, `WP_User|null $user`

== Screenshots ==

1. Admin settings panel - Basic configuration
2. Admin settings panel - Security and moderation
3. Admin settings panel - Advanced options and maintenance
4. Frontend chatbox interface with guest and user messages

== Frequently Asked Questions ==

= Can guests send messages? =  
Yes, if enabled in the plugin settings under Basic Settings. Guests will be asked to enter a display name before sending messages.

= How do I moderate messages and users? =  
Go to `Chat Engine → Management` to view recent messages, ban/unban users, and see chat statistics. You can search messages, delete inappropriate content, and ban users by IP or user account.

= Does it support real-time messaging? =  
This plugin uses REST API with smart polling (3.5-10 second intervals) for broad compatibility. No WebSocket setup required, works on any hosting.

= How many messages are stored? =  
Configurable in settings (default: 1000 messages). Old messages are automatically deleted when the limit is reached. You can also set up automatic cleanup based on age.

= Can I customize the chat appearance? =  
Yes, multiple ways:
- Use the Custom CSS field in Advanced Settings
- Override the template by placing `chatbox.php` in your theme's `init-chat-engine/` folder
- Use shortcode attributes for basic styling
- Disable plugin CSS entirely and use your own

= How does the ban system work? =  
Administrators can ban users by IP address or user account from the Management panel. Bans can be temporary (with expiration date) or permanent. Banned users see a clear message explaining their restriction.

= Can I limit message frequency? =  
Yes, use the Rate Limiting setting to control how many messages users can send per minute (1-100 messages). This helps prevent spam and abuse.

= Is it translation-ready? =  
Yes, the plugin is fully translation-ready with Vietnamese translation included. All text strings use proper WordPress internationalization functions.

= How do I backup chat data? =  
Chat messages are stored in your WordPress database in the `wp_init_chatbox_msgs` table. Use any WordPress backup plugin or database backup tool.

== Changelog ==

= 1.3.4 – April 7, 2026 =
- Fixed bulk delete and single message delete not working due to stale object cache
- Added `init_plugin_suite_chat_engine_clear_message_cache()` to properly invalidate message list, total count, and stats cache after every delete action
- Fixed nonce variable conflict between single action handler and cleanup handler that could cause cleanup verification to fail silently
- Added Screen Options support for configurable messages per page (default: 20, range: 5–200)
- Per-page preference is saved per user via user meta — does not affect other admins
- Replaced WordPress screen option API with direct POST handler for reliable save behavior
- No changes to database schema, REST API, or existing chat flow

= 1.3.3 – March 30, 2026 =
- Added expand/collapse support for pinned message content in banner
- Allows viewing full pinned message without jumping to original message
- Stores full message content via `dataset` to avoid additional queries or requests
- Updated pinned banner to use absolute positioning to eliminate layout shift (CLS)
- Ensures stable layout when banner appears or updates
- Refined animation and interaction for smoother realtime UX
- No changes to API, database, or existing chat flow

= 1.3.2 – March 30, 2026 =
- Introduced Pin Message feature for chat moderation (admin only)
- Allows pinning a single message to the top of the chat box (auto-replaces previous pin)
- Added hover-based Pin/Unpin button on messages for admins with dynamic state handling
- Implemented pinned message banner with jump-to-message and highlight animation
- Added REST endpoints: POST /pin and DELETE /pin (nonce-verified, admin only)
- `GET /messages` now includes `pinned_message` for real-time sync across clients
- Pin state cached (5 minutes) with immediate invalidation on update
- Uses existing database (`init_chatbox_stats`) — no schema changes required
- Fully translation-ready via `InitChatEngineData.i18n`
- Fully backwards-compatible and does not affect existing chat flow

= 1.3.1 – March 26, 2026 =
- Performance optimization: added object caching for frequently called checks
- `init_plugin_suite_chat_engine_has_messages()` now cached (24 hours) to reduce redundant DB queries during render
- `init_plugin_suite_chat_engine_check_user_banned()` now uses 10-minute cache with multi-key strategy (user ID + IP)
- Implemented proper cache invalidation on ban/unban actions to ensure real-time accuracy
- Added negative caching to eliminate repeated queries for non-banned users
- Internal optimization only — no UI or database changes
- Improves scalability and reduces database load under high traffic chat environments

= 1.3.0 – March 2, 2026 =
- Introduced new **Minimum Account Age Requirement** (Security setting)
- Administrators can now require users to have an account older than **X days** before participating in chat
- Rule only applies when **guest chatting is disabled** (login required mode)
- Fully integrated across backend and frontend:
  - REST `/send` endpoint now enforces account age validation via centralized security check
  - Shared reusable function `init_plugin_suite_chat_engine_check_account_age_requirement()` ensures single source of truth
- Frontend UI enhancement:
  - Chat input is automatically disabled (`pointer-events: none; opacity: 0.6`) when account is too new
  - Context-aware warning message displayed directly under the input area
- No impact on guest mode — public chats remain unaffected when guests are allowed
- Backwards-compatible with existing settings and database schema
- Security-focused enhancement to mitigate spam, clone accounts, and coordinated war activity

= 1.2.9 – February 13, 2026 =
- Overhauled **User Ban System** with timezone-aware logic and optimized detection flow
- Fixed **timezone inconsistency** across ban creation, validation, and display layers
  - `init_plugin_suite_chat_engine_ban_user()`: now uses `DateTime` with WordPress timezone for precise `expires_at` calculation
  - `init_plugin_suite_chat_engine_check_user_banned()`: replaced `NOW()` (GMT) with `current_time('mysql')` for accurate expiration checks
  - `init_plugin_suite_chat_engine_render_banned_message()`: switched to `date_i18n()` to prevent double timezone conversion
- Improved **ban detection priority** — user accounts are now checked first, IP fallback only when user is not banned
  - Prevents trivial IP-based bypass when logged-in users are banned
  - Guest users (no `user_id`) continue to rely on IP-only detection
- Eliminated redundant dual-condition SQL queries (`user_id OR ip_address`) in favor of sequential checks
- Ban expiration timestamps now remain consistent across creation → validation → display (e.g., 48-hour ban created at 8:57 AM expires exactly at 8:57 AM, not 3:56 PM)
- Enhanced WP_DEBUG logging with detailed timestamp comparisons for admin troubleshooting
- Fully backwards-compatible with existing ban records and database schema
- Internal security hardening only; no UI or frontend behavioral changes

= 1.2.8 – November 11, 2025 =
- Hotfix: fixed **Load More (history pagination)** message order becoming inconsistent
  - **API (`before_id`)**: changed `ORDER BY id` from **ASC → DESC**
  - **Frontend (Load More)**: removed `.reverse()`, now directly `prepend()` using API DESC order
  - **Frontend (Initial load)**: unchanged — reverse initial batch then `append()` (old → new)
  - **Frontend (Realtime / after_id)**: unchanged — API returns ASC, frontend `append()`
- Result: timeline in the DOM remains strictly **old → new**
- Minimal change — **no DB schema changes, no UI changes**

= 1.2.7 – November 10, 2025 =
- Fixed **Load More / Pagination** logic returning messages in reversed order
- API now consistently outputs messages in **chronological ASC** order across:
  - Initial load
  - History pagination (`before_id`)
  - Realtime polling (`after_id`)
- No frontend sorting required — FE only append/prepend based on mode
- Ensures smooth timeline continuity when fetching older batches
- Internal change only; does **not affect DB schema or UI behavior**

= 1.2.6 – October 20, 2025 =
- Overhauled **Word Filter Engine** with hardened validation lifecycle
- Default strategy is now **aggressive substring detection** (catches `https://`, domains, encoded text, spam links, etc.)
- Fully respects existing Security settings:
  - `Enable Word Filtering` toggle
  - `Blocked Words` textarea (one per line, supports Unicode)
  - `Word Filter Exceptions` (role-based whitelist: Administrators always bypass)
- Introduced new developer extension hooks (no new UI options):
  - `init_plugin_suite_chat_engine_word_filter_strategy` — switch filter logic (`substring`, `word`, `regex`)
  - `init_plugin_suite_chat_engine_blocked_words` — modify blocked word list programmatically
  - `init_plugin_suite_chat_engine_bypass_filter` — bypass filtering based on custom logic (VIP, IP ranges, etc.)
  - `init_plugin_suite_chat_engine_word_block_hit` — event fired when a blocked word triggers
- Improved unicode normalization and internal cleanup of blocked-word lists (removes empty lines and `#comments`)
- Fully backwards-compatible — no disruption to existing settings or workflows
- Strengthened message security layer; prevents all major spam patterns (URL, Discord invite, Telegram link, obfuscated characters)

= 1.2.5 – October 18, 2025 =  
- Added new **“Delete All Messages”** button under **Quick Actions** in the management panel  
- Feature permanently removes all chat messages from the database with a single click  
- Protected by full security stack: admin-only capability, nonce verification, and SQL transaction safety  
- Resets all chat statistics (`total_messages`, `messages_today`, `active_users_today`, etc.) post-deletion  
- Includes detailed WP_DEBUG logging for admin audit trail (`who`, `when`)  
- UX-consistent with existing “Run Cleanup Now” button — executes instantly without JS dependency  
- Designed as a “nuclear cleanup” option for administrators managing public chat environments  
- No other functional or visual changes; this update focuses solely on administrative maintenance tools  

= 1.2.4 – October 18, 2025 =  
- Rebuilt **FX Keyword Engine** for per-message precision and zero-DOM overhead  
- Replaced global `TreeWalker` scanning with on-demand inline FX application during message render  
- Introduced new internal helpers: `getCompiledFXRules()` and `applyFXInMessageContainer()`  
- Rules are now compiled once and reused, ensuring stable performance even with large message histories  
- Removed redundant functions `initChatboxReplaceFXKeywords()`, `safeReplaceFXKeywordsInDOM()`, and `runFXIfHasMessages()`  
- Eliminated repeated DOM traversals after message batch rendering (initial load, polling, or history fetch)  
- Maintained full compatibility with external `runEffect()` logic and `FX_KEYWORDS` data structure  
- Improved keyword detection accuracy using unified regex alternation with named groups  
- Achieved significant runtime gains — messages now apply FX instantly upon creation  
- Internal optimization only; no visual or behavioral changes for end users  

= 1.2.3 – October 14, 2025 =
- Added safe integration hook for cross-plugin Init FX Engine keyword replacement  
- Chat engine now auto-invokes external DOM keyword highlighter (`replaceFXKeywordsInDOM`) **only when new messages are loaded**  
- Added conditional wrapper with `typeof` check to prevent errors if the external plugin is not active  
- Introduced new internal helper: `safeRunFX()` for async idle execution (avoids blocking UI on message bursts)  
- Implemented new scoped function `initChatboxReplaceFXKeywords()` — optimized DOM scanning limited to `.init-chatbox-text` only  
- Rewrote FX keyword parser with `TreeWalker` for deep text traversal and regex stability  
- Eliminated duplicate link generation and ensured idempotent behavior (no double replacements)  
- Performance improved significantly when many messages are rendered or refreshed in batch  
- Internal enhancement only — no UI changes; improves plugin compatibility and runtime stability

= 1.2.2 – October 7, 2025 =
- **Hotfix Release:** removed redundant ban check inside `[init_chatbox]` shortcode  
- Eliminated secondary `init_plugin_suite_chat_engine_check_user_banned()` call (already handled by shortcode controller)  
- Prevented duplicate banned-message rendering and minor timezone mismatches  
- Simplified shortcode logic for better maintainability and consistency with ban middleware  
- No user-facing behavior change — internal backend cleanup only  

= 1.2.1 – October 7, 2025 =
- Added role-based word filter exceptions in Security settings  
- New UI option: **“Word Filter Exceptions”** allows selecting user roles that can bypass blocked-word restrictions  
- Default exempt role: **Administrator** (others can be toggled via checkboxes)  
- Enhanced backend sanitization with strict role validation against existing WordPress roles  
- Updated message validation logic: users in exempt roles can send blocked words without triggering filter  
- Preserves security for guests and non-exempt roles (still subject to normal word filtering)  
- Improved localization: added Vietnamese translations for all new settings strings  

= 1.2.0 – October 2, 2025 =
- Introduced new filter `init_plugin_suite_chat_engine_enrich_message_row` for extending message rows with custom user metadata  
- Enables themes/plugins to attach extra flags (roles, VIP status, moderation rights, etc.) without touching core logic  
- Improves flexibility and forward-compatibility of the chat engine API, allowing richer integrations and UI features downstream  

= 1.1.9 – October 1, 2025 =
- Added optional support for user profile links in chat messages
- Introduced `profile_url` field in API responses for registered users
- Provided frontend hook (`initChatEngineMessageElementHook`) to linkify display names if desired
- Feature is opt-in only; by default, names remain plain text for backward compatibility

= 1.1.8 – September 13, 2025 =
- Hardened `/send` security for logged-in users: strictly validate `X-WP-Nonce` and block cross-site POST attempts
- Sanitized inputs on the server before storage: apply `wp_strip_all_tags()` to both `message` and `display_name` (logged-in and guest paths)
- Rejected empty or non-visible messages: now fails fast on whitespace-/zero-width-/control-character–only content
- Enforced length limits server-side (pre-insert) to prevent oversized payloads; behavior matches UI constraints
- Kept output defense-in-depth: responses continue to use `wp_kses_post()` for message rendering
- Tightened server-side anti-abuse: permission callback rate-limit check remains authoritative (in addition to any client throttling)

= 1.1.7 – September 13, 2025 =
- Updated URL auto-linking logic to only apply when the link matches the current site domain
- Prevented external or mismatched-domain links from being auto-converted into `<a>` tags
- Reduced risk of spammy or malicious links being injected into formatted content
- Maintained full support for existing markdown-style text formatting features
- Improved overall content safety and formatting reliability

= 1.1.6 – September 1, 2025 =
- Updated codebase to fully comply with WordPress Coding Standards (WPCS)
- Refactored inline documentation and formatting for better readability and maintainability
- Improved code consistency to align with official WordPress best practices
- Minor internal cleanups to enhance long-term stability

= 1.1.5 – August 4, 2025 =
- Enhanced text formatting logic with smarter boundary detection for markdown-style syntax
- Improved formatting rules to require whitespace boundaries OR string start/end positions
- Fixed formatting conflicts in code identifiers (e.g., `init_live_search` no longer formats "live")
- Resolved mathematical expression formatting issues (e.g., `1*2*3 = 6` no longer bolds "2")
- Updated regex patterns to use OR logic: format when either start OR end has whitespace boundary
- Enhanced support for edge cases like `*start* and *end*` now properly formats both words
- Maintained strict content validation: no spaces immediately after opening or before closing markers
- Added comprehensive capture group handling for multiple regex patterns
- Improved formatting accuracy while preserving backward compatibility
- Enhanced user experience with more intuitive and predictable text formatting behavior

= 1.1.4 – August 3, 2025 =
- Added extensible hook system for enhanced message formatting and customization
- Introduced `window.initChatEngineFormatHook` for custom text formatting (supports sticker display and theme extensions)
- Added `window.initChatEngineMessageElementHook` for post-processing message elements after creation
- Enhanced message rendering pipeline to support external plugins and theme customizations
- Improved integration capabilities with Init Manga sticker system and other theme features
- Maintained backward compatibility while providing flexible extension points for developers
- Optimized hook execution with proper error handling to prevent chat interruptions

= 1.1.3 – August 01, 2025 =
- Advanced request management system with AbortController to prevent duplicate API calls
- Real-time timestamp updates: message timestamps now refresh automatically (e.g., "5 minutes" → "6 minutes")
- Enhanced network error handling with exponential backoff and smart retry mechanism
- Improved connection stability for slow/unstable networks with intelligent polling intervals
- Request deduplication system prevents message loading conflicts and UI inconsistencies
- Network status monitoring with automatic reconnection when connection is restored
- Better error recovery with consecutive error tracking and adaptive polling frequency
- Performance optimizations: reduced unnecessary API calls and improved memory management
- Enhanced user experience with clearer loading states and connection status indicators
- Robust offline/online detection with proper fallback handling for network interruptions

= 1.1.2 – July 30, 2025 =
- Complete dark mode system overhaul with comprehensive theme support
- Enhanced CSS variables system with dedicated light/dark theme variable sets
- Full component coverage: dark mode now applies to all elements (messages, inputs, buttons, scrollbars, modals)
- Smart theme detection: auto-detect system dark mode preference with `@media (prefers-color-scheme: dark)`
- Improved color contrast and accessibility with proper contrast ratios for dark theme
- Smooth theme transitions with 0.3s transition animations when switching between themes

= 1.1.1 – July 29, 2025 =
- Resolved infinite scroll loop bug causing chat interface crashes
- Fixed load more button toggle conflicts in middle scroll positions (50-200px from top)
- Implemented debounced scroll handling with 100ms stabilization timer
- Added scroll direction tracking to prevent unnecessary auto-load triggers
- Improved scroll zone boundaries: auto-load (<30px), manual button (30-200px), hide (>300px)
- Enhanced state management to prevent redundant UI updates and layout thrashing
- Added proper timer cleanup on page unload to prevent memory leaks
- Optimized scroll performance with passive event listeners and reduced DOM queries
- Fixed scroll button visibility logic to prevent flickering during rapid scrolling
- Strengthened error handling for edge cases in scroll position calculations
- Added support for utility classes (uk-hidden, hidden, .ice-hidden)
- Automatic CSS framework detection and appropriate hide/show class usage
- Fixed character counter not working for guest users due to duplicate ID names
- Improved "Load more" button display logic to be more generous but still safe (expanded zone to 400px)
- Faster UI response time: reduced debounce to 80ms, auto-load delay to 150ms

= 1.1.0 – July 29, 2025 =
- Major admin panel upgrade with tabbed interface (Basic, Security, Advanced)
- Added full message management system with search and pagination
- Introduced user ban/unban system with support for IP and user restrictions
- Built statistics dashboard with activity charts and engagement metrics
- Implemented rate limiting control (messages per minute) to prevent spam
- Added word filter system with custom blocked word list
- Included auto/manual cleanup tools for old messages
- Redesigned admin UI with professional styling and responsive support
- Added connection status indicators and improved error handling
- Introduced REST API endpoints for admin moderation actions
- Implemented caching and nonce verification for all admin operations
- Added full settings validation and sanitization
- Full i18n support with .pot file and Vietnamese translation included

= 1.0.3 – July 20, 2025 =
- Added support for inline message formatting: `*bold*`, `_highlight_`, `~strike~`, `^mark^`, and `italic`
- Reused highlight style `.init-fx-highlight-text` from Init FX Engine (no duplicated CSS)
- Improved message rendering with safe HTML output
- Removed redundant `escapeHTML()` call to enable formatting
- Minor refactor of formatting logic

= 1.0.2 – July 19, 2025 =
- Added user avatar rendering with fallback support
- Introduced blinking document title when new messages arrive
- Added anti-spam cooldown and click-lock on send button
- Refined guest name workflow and improved avatar integration
- Enhanced message HTML structure and cleaned up code

= 1.0.1 – July 19, 2025 =
- Implemented smart polling system with adaptive intervals
- Added browser notification API support for new messages
- Improved scroll behavior and scroll-to-bottom logic
- Enhanced typing state detection and guest name handling
- Fixed message prepending offset issue and made UI tweaks

= 1.0.0 – July 18, 2025 =
- Initial release
- Core chat functionality using REST API (no WebSocket)
- Guest messaging support with basic identity system
- Admin settings for message limits and guest permissions
- Shortcode support with template override
- Scrollable history with smooth auto-scroll
- Optimistic message sending with fallback retry

== License ==

This plugin is licensed under the GPLv2 or later.  
You are free to use, modify, and distribute it under the same license.
