# AGENTS.md

Guidance for AI coding agents working on the **Big Emoji Comments** plugin.

## Directory Structure

The plugin is structured procedurally without classes or namespaces to keep it lightweight.

- **`big-emoji-comments.php`**: The main plugin bootstrap. Contains the filter callback, sizing constants, grapheme cluster counting logic, and the precompiled regex character class.
- **`regex-builder.php`**: A CLI helper utility for fetching the latest official Unicode character definitions, optimizing the intervals, and printing the formatted PHP source ranges.
- **`phpcs.xml`**: Preconfigured WordPress Coding Standards (WPCS) local ruleset.

## Key Design Patterns & Decisions

### 1. Emoji Count Precision (Graphemes vs Codepoints)
Do not count characters using `strlen` or `mb_strlen`. Modifiers (skin tones), joiners (ZWJ), regional flag indicators, and variation selectors consist of multiple Unicode codepoints. 
- Use `grapheme_strlen()` if the PHP `intl` extension is active.
- Fall back to `mb_strlen()` only if `grapheme_strlen` is unavailable.

### 2. Regex Optimization
The regex character class `all_emoji_regex` is generated by fetching the latest Unicode database properties and merging overlapping/adjacent integer intervals.
- Avoid listing every codepoint range separately in the main plugin file; use `regex-builder.php` to merge them into a compressed set of intervals.
- Maintain the PCRE UTF-8 (`/u`) modifier at the end of the regex patterns.

### 3. Extensibility
Ensure any adjustments to the sizing tiers or output formatting preserve the filters:
- `apply_filters( 'big_emoji_comments_percent', $percent, $no_markup )`
- `apply_filters( 'big_emoji_comments_output', $output, $content, $percent, $no_markup )`

### 4. Security
Always escape the output in the filter wrapper via `wp_kses_post( $content )`. Emojis can technically be sent in combination with formatted tags which we want to preserve while ensuring XSS payloads are neutralised.

---

## Tooling & Verification

### Running Linting Tests
The local ruleset requires 100% compliance with `WordPress-Extra` and `WordPress-Docs` standards. Run the linter using:
```bash
../vendor/bin/phpcs --standard=phpcs.xml
```

### Updating Regex Ranges
When a new Unicode emoji version is released:
1. Verify the URL defined in `regex-builder.php` is still correct.
2. Run the script: `php regex-builder.php`.
3. Copy the output ranges block and drop it directly into `big-emoji-comments.php`.
4. Ensure the ranges end in full stops to satisfy Squiz inline comment rules.
5. Re-run local standards checks.