=== Breadbugger ===
Contributors: abiagio
Tags: debug, bug-tracker, qa, pre-launch, feedback
Requires at least: 5.6
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.0.10
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

On-page bug tracker for pre-launch QA. Pin reports directly on the page, manage them in a clean admin list, integrate with external clients via REST.

== Description ==

**Breadbugger** is a bug tracking tool built for the pre-launch phase of a WordPress site — the moment when designers, QA, developers and clients walk through the site looking for issues before go-live.

Three complementary surfaces:

1. **On-page floating widget** — open the widget with a configurable keyboard shortcut, "pin" reports directly to the HTML element they refer to, attach screenshots captured on-the-fly from the browser.
2. **Clean admin list** — manage every report from a compact full-screen view: filter by status, priority, author; sort manually with drag & drop; reply with inline notes.
3. **REST API for external clients** — app-password gated endpoints to integrate your bug tracker with CLIs, AI coding assistants, or custom scripts.

= Key features =

* **Stable pin selectors** — element selector built via a cascade: `data-breadbugger-name` (opt-in dev), then stable `id`, then semantic class, then positional CSS. Pins survive refactors.
* **Configurable hotkey** — press the keys to set your preferred combo, with browser/OS collision validation.
* **Reporter / manager role model** — assign who can open reports (reporter) and who can manage them all (manager) via custom capabilities on any WordPress role.
* **Author filter + configurable visibility** — managers can see and filter by author; reporters can optionally see only their own bugs.
* **In-browser screenshots** — automatic capture via `getDisplayMedia` (HTML2Canvas-Pro as a fallback for modern CSS like `oklch` / `color-mix`).
* **Internationalized** — Italian source, .po / .mo translations, .pot template ready for any language.
* **Built-in feedback channel** — settings form to send bug reports / feature requests / questions to the author via `wp_mail`.
* **Branded email notifications** — HTML emails for @mentions in notes and (optional) for new bugs and resolved bugs, with per-recipient frequency: all events, accorpate (timeout-based), daily digest, weekly digest, or none.

= Use case =

Client site pre-go-live: 5-10 people testing in parallel. Each one loads the site, opens the widget with a shortcut, pins the issue directly on the affected element. The PM / dev watches the admin list, sorts by priority, assigns fixes, marks resolved.

Standalone. No external SaaS required. No data sent to third-party servers. Your bugs stay in your database.

== Installation ==

1. Upload the `breadbugger` folder to `/wp-content/plugins/`, or install from WP Admin → Plugins → Add New → Upload Plugin.
2. Activate the plugin via WP Admin → Plugins.
3. Open **Breadbugger → Settings**.
4. Enable "Widget frontend" to make the floating widget visible.
5. Configure reporter / manager roles if you want to separate who can open vs. who can manage reports.
6. (Optional) Customize the keyboard shortcut.
7. Visit a public page of the site → press the shortcut (default `⌘+E` / `Ctrl+E`) → create your first report.

== Frequently Asked Questions ==

= Does the plugin send data to external servers? =

No. All data stays in your WordPress database. The only optional exception: the "Feedback" form in settings, when submitted, sends an email to the author through your site's mail system (`wp_mail`).

= Can I use it in production, not just pre-launch? =

Yes, but it is designed for pre-launch. For end-user support tickets there are better solutions (Zendesk, Freshdesk, etc.).

= Do I have to add `data-breadbugger-name` everywhere? =

No, it is opt-in. Without it the plugin cascades to id, class, positional CSS. It is useful only on 5-10 cornerstone blocks of the site to get extremely stable pins.

= How do I integrate Breadbugger with my AI coding assistant? =

Settings → "REST API for external clients" → generate an app-password → use the header `Authorization: Basic <user:app-password>` in REST calls. Base endpoint: `/wp-json/breadbugger/v1/bugs`.

= Can I restrict reporters to see only their own bugs? =

Yes, Settings → Visibility → "Reporters see only their own reports". Managers always see everything.

= Will uninstalling delete my data? =

`uninstall.php` removes everything (bugs, settings, capabilities, attachments owned by the plugin, app-passwords containing "Breadbugger" in the name). If you want to keep your data, **deactivate** instead of uninstalling.

== Screenshots ==

1. On-page floating widget for creating bugs directly on the page
2. Admin list with filters by status, priority, author
3. Keyboard shortcut configuration with free-form capture
4. Settings: reporter / manager roles, feedback, REST integration
5. Pin selector cascade documentation

== Changelog ==

= 2.0.10 =
* New: reporters can now open the admin **Lista** page (menu visible with the `breadbugger_report` capability), where they see only their own reports when "reporters see own only" is enabled. The Settings page remains manager-only.
* New: for reporter-only users the list renders as a clean read-only view — management controls (status, priority, notes, reorder, delete, attachments) are hidden in the UI and remain enforced server-side. Creating new reports is still available.

= 2.0.9 =
* Security: GET /bugs/{id} now enforces the same per-author visibility as the list endpoint. A reporter restricted to "see own only" can no longer read another author's bug by requesting its ID directly (broken access control / IDOR fix). The frontend pin query applies the same restriction.

= 2.0.8 =
* Security: escape the `categoria` value before rendering it in the admin list (prevents stored attribute-injection in the device chip).
* Updated: bundled SortableJS from 1.15.2 to 1.15.7 (latest stable).
* Updated Contributors metadata.

= 2.0.7 =
* Changed: AI notes (created via REST API) are now ALWAYS hidden by default. The per-user preference no longer makes them appear inline.
* New: when the per-user preference is enabled, a small "AI" pill is rendered in the bottom-right corner of the notes box, showing the AI-note count. Clicking it reveals/hides those notes for that bug only (session-scoped, not persisted).
* Settings label updated to "Abilita pulsante note AI" with refreshed description.
* Removed legacy inline "N nota nascosta" stub (replaced by the new AI pill).

= 2.0.6 =
* New: distinct rendering for notes created via REST API (AI tools, agents) — green badge with AI icon instead of user initial, light tint, left border.
* New: per-user preference "Show AI notes" in Settings → Manutenzione (off by default). When off, API-sourced notes are replaced by a compact stub "N nota nascosta" so the count is still visible.
* REST: added `/me/preferences` (GET + POST) backed by `user_meta` for per-user UI preferences.

= 2.0.5 =
* WP.org submission gate — passes Plugin Check.
* Header: Plugin Name simplified to "Breadbugger" (matches readme); tagline "a PaneStudio tool" moved to description.
* readme.txt: Description, Installation, FAQ and Screenshots rewritten in English (WP.org requires standard English).
* Bumped "Tested up to" to 7.0.
* Removed `load_plugin_textdomain` call — WordPress.org auto-loads translations since WP 4.6.
* Build script: added `.distignore` itself to its own exclude list (no longer leaks as a hidden file in the ZIP).
* Added targeted `phpcs:ignore` comments with rationale on legitimate direct DB queries (uninstall cleanup, migration UPDATEs, sequential bug numbering, queue dispatch enumeration) and on the file-scope variables in admin views (which are method-scoped via include, not global).

= 2.0.4 =
* New: flusso email notifiche completo. Settings card "Email & Notifiche" (ridotta a 6 colonne, bottom-right accanto a Feedback) con:
  - Sottoscrittori per evento (Nuovo bug + Risolto) per ogni utente con cap breadbugger_*
  - Frequenza per utente: Tutte le mail / Accorpate (timeout) / Recap giornaliero / Recap settimanale / Nessuna
  - Toggle "Notifica reporter su risoluzione" (default on)
  - Input "Finestra accorpate (min)" — invia digest dopo X minuti di inattività
  - Sezioni "Mittente" e "Sottoscrizioni" collapsibili per compattezza
* New: nuovo `Breadbugger_Notifications` con queue per-utente in user_meta + cron `breadbugger_5min` per dispatch batched. Daily a 8:00 UTC, weekly lunedì 8:00 UTC.
* New: nuovi metodi `Breadbugger_Mailer::event_email()` (nuovo bug / risolto) + `digest_email()` (recap con elenco eventi cliccabili, etichette colorate, ordinati per timestamp).
* New: hook automatici su `create_bug` → dispatch 'new_bug' e su `update_bug` quando lo status passa a done/done_by_ai/closed → dispatch 'resolution'.
* Changed: snippet CLAUDE-DEBUG.md ora istruisce gli agent AI ad usare `done_by_ai` invece di `done` — il developer promuoverà manualmente a `done` dopo review.

= 2.0.3 =
* New: deep-link `#bug-{id}` in URL (es. dal link nelle email) — il bug viene scrollato in vista e segnato con un accento cream a sinistra che pulsa 3 volte. Funziona anche su hashchange (clic su un altro link senza ricaricare).
* New: email HTML brandizzate Breadbugger. Nuovo `Breadbugger_Mailer` con template dark theme: pane logo + wordmark, blockquote nota su cream accent, CTA "Vai al bug →", footer co-branded "a PaneStudio tool".
* New: settings card "Email & Notifiche" — toggle "Email su @menzione" + campi "Mittente (From)" + "Nome mittente" con autosave (debounce 400ms su input).
* Changed: Subject email ora include il nome del sito → `[Breadbugger · NomeSito] Autore ti ha menzionato su "Bug"`. Stesso pattern su feedback form.

= 2.0.2 =
* Fix: @mention con display_name multi-word (es. "Nome Cognome") ora vengono pillati visualmente per intero e notificati via email. Server-side cerca prima i display_name con spazi via get_users + capability__in, poi fallback al lookup per user_login.
* Improved: user pool caricato eagerly al page load (insieme a /bugs) — primo render già con pill multi-word funzionanti.
* Internals: regenerated .pot template per le stringhe aggiunte nel 2.0.1 (mentions, copy bug-context, autosave indicator).

= 2.0.1 =
* New: pagina Impostazioni completamente ridisegnata — dark theme branded PaneStudio, autosave on change, grid 12 colonne.
* New: status intermedio "Done by AI" tra in_progress e done.
* New: toggle "Lista fullscreen" per disabilitare la modalità full-bleed e mantenere la sidebar WP.
* New: editing inline delle note (doppio click → contenteditable). Empty content + blur = elimina nota.
* New: @mention utenti nelle note con autocomplete + notifica via wp_mail. Pesca da utenti con capability breadbugger_report o breadbugger_manage.
* New: pulsante "Copia contesto AI" per ogni bug — copia in clipboard titolo, status, priority, device, URL, pin selector, note (con autore) e screenshot URL in formato markdown.
* New: titolo bug truncato con "..." in lettura, scroll on hover, click per copiare titolo in clipboard.
* New: barra ricerca dopo "Autore" che cerca in titolo+note. Digitando sulla pagina senza click parte direttamente in modalità ricerca.
* New: filter chip device passa a click+dropdown (pattern coerente con priority/status).
* New: tagline "a PaneStudio tool" sotto al wordmark BREADBUGGER (link discreto a panestudio.com).
* New: card pop-menu auto-flip verso il basso quando spazio sopra è insufficiente o spazio sotto è maggiore.
* Security: API request (HTTP Basic / app-password) distingue ora da sessione UI. API può solo aggiungere note, modificare note create via API, e cambiare status. Update di altri campi e delete bug bloccati con 403.
* Security: notes ora taggate con source ("ui" o "api") nello shape.
* Fix: caratteri accentati (è/à/ò/ù) nelle note non più corrotti in `\u00XX` (mancava wp_slash + JSON_UNESCAPED_UNICODE in set_array_meta).
* Fix: cache-bust filemtime su settings.css/.js (era cappato a BREADBUGGER_VERSION).
* Fix: MENU_SLUG e SETTINGS_SLUG rinominati da 'panestudio-debug*' a 'breadbugger*' (rimasti dietro dal rebrand M2).
* Fix: hook detection in enqueue_assets ora cattura il return value di add_menu_page invece di costruire stringhe.
* Fix: classi CSS body via admin_body_class filter — body.breadbugger-list-page e body.breadbugger-settings-page (stabili a prescindere dal menu title).
* Fix: WP admin notice/update-nag/screen-meta nascoste nella modalità fullscreen della list.
* Fix: row con pop aperto sale a z-index:100 — il pop non viene più coperto dalla card successiva.
* Fix: WP shell hide regole gate-ate su --fullscreen modifier.
* Fix: menu icon dashboard ora SVG dedicato 20×20 (era pane.png 2:1 distorto).

= 2.0.0 =
* Public release. Rebrand da "PaneStudio Debug" a "Breadbugger — a PaneStudio tool".
* New: hotkey configurabile (capture libero)
* New: modello ruoli reporter/manager via capability custom
* New: filtro autore + opzione "reporter vedono solo i propri"
* New: feedback form integrato (wp_mail)
* New: pin selector cascade (data-breadbugger-name → id → class → finder → nth-of-type)
* New: i18n ready (text-domain breadbugger, IT/EN)
* Changed: license GPLv2+
* Changed: tutti gli identifier rinominati da psdebug_* a breadbugger_*
* Changed: REST namespace da panestudio-debug/v1 a breadbugger/v1
* Migration: data esistente (bug, settings) migrata automaticamente all'attivazione

= 1.1.0 =
* Internal release — sviluppo M1 features.

= 1.0.0 =
* Initial private release as PaneStudio Debug.

== Upgrade Notice ==

= 2.0.0 =
First public release. Per chi viene da PaneStudio Debug v1.x: migration data automatica all'attivazione. Tutti i bug esistenti restano accessibili.
