Add /annotate skill with Studio inspector

[youknowriad]

Related issues

• Builds on Add visual annotation browser with Agentation #3030 (the original /annotate skill PR by @lezama). This PR rebases that work onto current trunk and replaces the third-party agentation toolbar with a self-contained Studio inspector. The first commit on this branch is the original @lezama commit, preserved for attribution; the second commit is the rewrite.

How AI was used in this PR

Heavy AI involvement — Claude Code drove the rebase, the discovery of the issues with the agentation-based approach (window sizing, dock-icon leak, sync gaps, missing confirmation step), and the rewrite into a vanilla-DOM inspector. End-to-end behaviours were verified with Playwright scripts; screenshots from each iteration are in the session transcript.

Reviewers should focus on:

• The injected page script in apps/cli/ai/inspector/page-script.ts — it runs in the host WordPress page so it needs to be defensive against any theme CSS / global handlers.
• The chromium lifecycle in apps/cli/ai/inspector/inspector-inject.ts — close-on-page-close + close-on-process-exit hooks are the bits I'd most want a second pair of eyes on.
• The mandatory "summarize and confirm" step in SKILL.md. The intent is that the agent never edits files based on annotations without an explicit yes from the user.

Proposed Changes

This PR is a Proof-of-Concept-grade rework of the annotation skill. Marking as draft + Proof of Concept label per AGENTS.md guidance for substantial AI-generated features.

Removed

• agentation npm package dependency (loaded at runtime from esm.sh in Add visual annotation browser with Agentation #3030)
• agentation-mcp dev dependency
• agentation MCP server entry in apps/cli/ai/agent.ts
• apps/cli/ai/agentation-inject.ts

Added — apps/cli/ai/inspector/

• page-script.ts — self-contained vanilla-DOM inspector mounted into a Shadow DOM root. No React, no esm.sh, no external runtime deps.
• inspector-inject.ts — Playwright launch + inject + waitForAnnotationsDone helper.

Inspector UI (vs. agentation toolbar in #3030)

• Two-button toolbar: Annotate and Done, plus a count badge. Layout-mode, settings page, theme picker, colour palette all gone.
• Annotate is sticky — after Save, picking mode stays on so the user can chain annotations.
• Done ships the batch to the CLI via window.__studioAnnotateDone, clears local state, plays a live 10-second countdown toast, then the CLI auto-closes the chromium window.
• Picked elements get a blue outline; saved annotations get numbered markers; clicking a marker reopens the popup for edit/delete.
• Esc cancels picking / closes the popup.

CLI lifecycle hardening

• 1280×800 window + viewport: null so the bottom-right toolbar is always inside the visible region regardless of host screen size.
• bringToFront() so the macOS window doesn't open behind the terminal.
• page.on('close') and browser.on('disconnected') tear down the whole chromium process tree.
• process.once('exit'|'SIGINT'|'SIGTERM'|'SIGHUP') hooks so quitting studio ai doesn't orphan a dock icon.
• 10-second deferred close after Done so the user has time to register the confirmation before the window vanishes.

Skill flow (SKILL.md)

• After wait_for_annotations returns, the agent must print a numbered summary in plain language and call AskUserQuestion to confirm before making any edits.
• Each summary item identifies the element by tag + nearbyText (not selector), restates the intent in the agent's own words, and quotes the user's verbatim comment.
• For another annotation round, the user re-runs /annotate rather than reusing the (now-closed) window.

Testing Instructions

1. npm install && npm run cli:build
2. node apps/cli/dist/cli/main.mjs ai
3. In the chat, run /annotate against any local Studio site.
4. Verify the bottom-right Annotate / Done toolbar appears in the headed chromium window. Click Annotate, click any element on the page, type feedback, click Save. Picking mode should stay on — click another element and repeat without re-clicking Annotate.
5. Click Done. Confirm:
   • A toast counts down 10s … 1s … closing now….
   • The chromium window closes automatically.
   • The CLI prints a numbered summary (in plain language, with the verbatim comment in parens) and asks for confirmation before making any edits.
6. Confirm the changes get applied. Try /annotate again — a fresh window should open with no leftover annotations from the previous session.
7. Close the chromium window manually mid-session — the dock icon should disappear cleanly (no force-quit needed).
8. Quit studio ai (Ctrl-C) while the inspector window is open — the chromium process should exit too.

Pre-merge Checklist

• No TypeScript / lint errors (npm run typecheck --workspace apps/cli, npx eslint --fix on the modified files).
• CLI builds (npm run cli:build).
• Unit/E2E tests — none added in this PR. The interaction surface lives entirely inside an injected vanilla-DOM script in a headed chromium window; reviewers may want to push for Playwright coverage before landing.
• Cross-platform (Windows/Linux) verification — only manually tested on macOS.
• PolyForm-Shield licence concerns from the agentation package are gone, but reviewers should confirm there are no other lingering references.

[youknowriad]

If this one becomes more complex we could consider extracting it to its own "react app" in the apps folder.

[youknowriad]

Good shout — agreed. Right now the inspector is ~330 lines of vanilla DOM in a Shadow root, which is light enough to live as an injected string. If we start adding things like keyboard navigation, an annotations panel, or theme variants, hoisting it to a proper apps/inspector React app (built and shipped as a static bundle the CLI loads as a string) would be the natural next step.

[wpmobilebot]

📊 Performance Test Results

Comparing 99d7d56 vs trunk

app-size

Metric	trunk	99d7d56	Diff	Change
App Size (Mac)	1451.96 MB	1907.46 MB	+455.49 MB	🔴 31.4%

site-editor

Metric	trunk	99d7d56	Diff	Change
load	1795 ms	1786 ms	9 ms	⚪ 0.0%

site-startup

Metric	trunk	99d7d56	Diff	Change
siteCreation	8086 ms	8083 ms	3 ms	⚪ 0.0%
siteStartup	4939 ms	4949 ms	+10 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[borkweb]

A couple of small changes