Add an AI writing assistant to the Drafts widget

[Alexismlg]

Summary

Adds an opt-in AI writing assistant to the Drafts widget. When an AI provider is configured (Settings → Connectors), each draft row gets a 💡 button that suggests a title, excerpt, tags and categories for the draft plus a short readiness check, and lets you apply the chosen suggestion straight onto the draft — without opening the editor.

Builds on the Drafts widget (#423).

What it does

• Hover a draft → 💡 → a panel appears with:
  • Readiness — a one-line, evidence-based take on how close the draft is (and, only when genuinely present, what it still needs).
  • Title ideas / Excerpt / Tags / Categories — tap any suggestion to apply it to the draft (title/excerpt written, tags/categories appended). The row's title updates live; a toast confirms.
• Categories are classified into the site's existing categories (passed to the model), not invented from scratch.

Graceful degradation (no provider configured)

The 💡 button is only rendered when desktopModeConfig.aiAssistant.providerConfigured is true, so a site without AI sees the widget exactly as before — no button, no empty state, no error. The server route mirrors this (returns 503 when no provider), as defence in depth.

Implementation

• desktop-mode/v1/draft-suggestions (read-only): reads the draft, calls wp_ai_client_prompt() with a JSON-schema response, returns { titles, excerpt, tags, categories, readiness }. Gated on edit_post and a configured provider.
• desktop-mode/v1/draft-apply: writes the accepted title / excerpt / tag / category onto the post. New categories are only created for users who can manage_categories (mirrors Core — Authors may assign but not create); unknown categories are skipped. Gated on edit_post.
• UI lives in the existing src/plugins/drafts-widget/. Auto-refresh pauses while the panel is open so the AI round-trip isn't wiped by a poll.
• Content is truncated with mb_substr to avoid splitting multibyte characters; the readiness prompt is strict/evidence-based to avoid the model inventing issues.

Testing

• npm run typecheck, npm run lint, npm run test:js (drafts widget: 12 tests) all pass.
• New phpunit coverage for draft-apply (tests/phpunit/tests/widgetDrafts.php, now 8 tests / 22 assertions): title+excerpt write-back, tag append, and the category-creation capability gate (editor creates; author can assign an existing category but cannot create a new one; subscriber is forbidden).
• Verified end-to-end in wp-env with a real provider: suggestions + apply + readiness + category classification all work; with no provider the button is absent and the endpoint 503s.
• CI never needs an API key — the deterministic parts are what's tested; the LLM call itself is exercised locally only.

[AllTerrainDeveloper]

Thanks! That's a good feature, and the read-only/write route split is the right call. Two things blocked it as-is, and I've pushed the fixes to this branch (987acd9) rather than sending it back — details below so nothing lands silently.

1. wpd-* components (blocking)

Every control in the feature was a bare <button>. Per AGENTS.md → Use wpd-* components, not raw HTML controls, these carry the framework's keyboard-nav, focus-management, theming-token and a11y plumbing for free; raw HTML doesn't.

Converted:

Was	Now
<button class="dm-drafts__spark">	<wpd-button variant="ghost">
<button class="dm-drafts__suggest-item"> (titles, excerpt)	<wpd-button> tuned to a list row
<button class="dm-drafts__suggest-tag"> (tags, categories)	<wpd-button> tuned to a pill
panel.textContent = 'Thinking…'	<wpd-spinner> + label
.dm-drafts__readiness div	<wpd-notice>, tone-coded success / warning off missing
error text	<wpd-notice tone="error">

Styling goes through the documented --wpd-button-* custom properties and the button shadow part, not a reimplementation. The apply buttons now use the component's busy state while the write is in flight and disabled after — an impatient double-click can't apply the same suggestion twice, which the old code allowed.

I also converted the pre-existing Trash button in the same row. Leaving one bare <button> beside a <wpd-button> would have shipped two different focus rings and two different disabled looks in the same 26px gutter. Shout if you'd rather I split that out.

A11y — the Suggest button is now a real disclosure (aria-expanded / aria-controls), the panel a labelled role="group", the load region aria-live="polite".

Theming — #7c3aed / #a78bfa / #22c55e were hardcoded. Now --wpd-accent / --wpd-success-fg with fallbacks, matching how the Trash button already read --wpd-danger.

2. Tests (blocking)

The phpunit coverage for draft-apply was solid — the category-creation capability gate in particular. But draft-suggestions had none, and there was no JS coverage at all for ~260 new lines of UI.

• vitest 12 → 25 — absent button without a provider, disclosure contract, fetch payloads, every group rendering as <wpd-button>, readiness tone flipping on missing, apply write-back + row update + toast, apply failure staying re-tryable, suggestions failure degrading to a notice, close-on-second-click, refresh suppression while the panel is open.
• phpunit 8 → 17 — the ordering fix below, the 503 path, title sanitization, empty-title no-op, the applied action's payload, prompt assembly, the content-limit filter, instruction/schema filterability, list normalization.

3. Correctness

• Permission ordering — /draft-suggestions checked for a provider before edit_post, so the 503-vs-403 split told an unauthorized caller whether the site had AI configured. Capability first now; the 403 is identical either way.
• toText() can throw — the route used generate_result() + an unguarded (string) $result->toText(). includes/ai-copilot/client.php wraps that call in a try/catch for exactly this reason. Switched to generate_text() inside a try/catch, matching the comment scorer's shape, so an SDK throw lands on the same clean 502 as a WP_Error instead of a fatal.
• List normalizer cast non-scalars; it skips them now.

4. House rules

• Removed the six @since 0.26.0 tags — AGENTS.md → No version-history annotations in docs or comments. Git history is the changelog.
• Hooks. Nothing in the feature was extensible. Added desktop_mode_drafts_ai_instructions, …_ai_schema, …_ai_content_limit, …_ai_suggestions, and the desktop_mode_drafts_suggestion_applied action, with the prompt/schema/normalizer extracted into named functions.
• Docs. Two new REST routes are public surface. Added a Drafts-widget section to hooks-reference.md (both routes + the five hooks), an architecture.md paragraph on the route split and the provider gate, and docs/examples/drafts-ai-suggestions.md, indexed in examples/README.md.

Green

npm run build, lint, typecheck clean. vitest 2461/2461 (252 files), phpunit 1659 tests / 4265 assertions OK.

[AllTerrainDeveloper]

I have tweaked a bit the new widget and adecuated it to what we are expecting, have you checked that your LLM is actually consuming the agents.md? seems It's not quite following it.

But anyway, good feature! And the good thing is that peopl who don't have a connector setup won't see it so it's not annoying

Thanks!