# Wordpress coding rules

- Escape every rendered variable.
- Never trust request data.
- Validate first, sanitize second.
- Use nonces + capability checks for state changes.
- Use WordPress APIs before custom code.
- Use `$wpdb->prepare()` for dynamic SQL.
- Prefix all identifiers.
- Wrap user-facing strings in i18n functions.
- Keep templates dumb.
- Prefer readable, hook-friendly code.
- Trap all possible errors for on-screen display.  Do not allow Wordpress Cricital Errors to occur.
- Interact with third-party software via well-known interfaces,  not custom DOM probing.
- Don't embed magic numbers in the code - such as known memory limits for a particular operation.
- All production configuration is via admin setup page (or user's profile page for per-user setup)

# Project Rules

Provide user error feedback on the pane/modal that was enabling user-interaction.
Prevent exiting the page with an error that causes loss of data already entered,  instead
require that the user fix the error or "Quit" the page.

Obey rules in requirements/environment.md

# Generated JS/PHP Quoting Safety Rules

1. Never hand-escape JS strings inside PHP string literals when avoidable.
2. When emitting JS from PHP, pass dynamic string values via `json_encode(..., JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)` and assign them to JS variables.
3. Prefer PHP `nowdoc`/`heredoc` blocks for inline JS/HTML over long concatenated quoted strings.
4. Do not use JS regex literals inside PHP-quoted JS when a non-regex alternative exists (`split/join`, `replaceAll`, explicit loops).
5. If regex is required, construct with `new RegExp(...)` from safely encoded string parts, not literal `/.../` in PHP-quoted code.
6. Avoid nested quote composition (`"\'` or `\\"` chains). Build tokens with template variables + encoded parts.
7. For Twig token generation, standardize one helper function and reuse it everywhere; do not duplicate escaping logic.
8. After any change to embedded JS in PHP, run:
   - `php -l <changed php file>`
   - project-wide PHP lint for plugin files before finishing.
9. If a change touches emitted JS, include a runtime sanity check step: open affected admin page and confirm browser console has no syntax errors.
10. In fixes for syntax/runtime issues, prefer minimal reversible changes first, then refactor for cleanliness only after recovery.