review-html-artifacts

Review HTML Artifacts

Use the anno plugin's html_review_* MCP tools for session state and file generation. Use the host's browser capability when available; otherwise return the local review URL so the user can open it.

Start a review

1. Call html_review_start_session with the absolute source HTML path. Omit output_path unless the user names a destination. Never overwrite the source file.
2. Open the returned review_url with the available browser capability. If the host cannot open URLs, give the URL to the user without claiming it was opened.
3. Tell the user they can edit text in place, use the compact format toolbar, drag a selected element by its top handle, add an element comment from the lower-left comment button, or drag a rectangle from blank space to annotate a region. The page autosaves all of this to the MCP session.
4. Let the user click 提交给 Agent. Anno writes a clean draft containing direct text, formatting, and visual-position edits, stores that draft plus every element annotation, area annotation, and page note, and marks the session needs_agent.
5. Anno persists a generation-specific handoff before attempting host delivery. Hosts with a conversation bridge may send a follow-up automatically. In other hosts, tell the user to return to the agent and continue with the session id. Never claim that a follow-up was delivered without a handoff receipt.
6. On receiving a handoff, call html_review_claim_handoff immediately with the exact session_id and handoff_id from the message. This durable receipt is what allows Anno to show that the Agent received the request. Then reload the session and take ownership of generation, validation, registration, and user-facing delivery.

Finish a review

1. Call html_review_claim_handoff first when the follow-up contains a handoff id, then call html_review_get_session. Claiming is idempotent for the active handoff.
2. For a needs_agent session (or a legacy needs_codex session), use session.draft_html_path as the only HTML base. Preserve direct edits and format/position changes already present in the draft, then apply every unresolved element annotation, area annotation, and page note from the review payload.
3. Write a complete standalone HTML file to a temporary non-source path, preserve scripts/assets/fonts/doctype, remove Anno-only review attributes, and validate the first page plus every affected page. For ordinary pages, validate the edited viewport and responsive behavior.
4. Call html_review_register_final with the verified file. This copies it to a versioned non-overwriting destination and marks the session resolved.
5. If a legacy session is still generating, wait for it to finish instead of duplicating that old worker. If it has generation_error, report it and recover only after correcting the underlying problem.
6. Return the final absolute path and summarize applied annotations. Do not claim free-form notes were applied unless the registered output was checked.