docs: document Studio's WebMCP agent tools, proven end-to-end in a browser

[miguel-heygen]

What

The webmcp docs page, an end-to-end proof that the tool set works in a real browser, and the one bug that proof found.

Stacked on #3520. Last unit of ten.

End-to-end proof

Driven with Claude in Chrome against Studio's dev server on 127.0.0.1:5190, using a minimal GSAP fixture composition. Not a mock anywhere.

1. All twelve tools register

> const tools = await document.modelContext.getTools()
> tools.map(t => t.name).sort()

["studio_add_animation", "studio_add_keyframe", "studio_delete_animation",
 "studio_frame", "studio_inspect", "studio_look", "studio_seek",
 "studio_select", "studio_set_style", "studio_set_text",
 "studio_transform", "studio_update_animation"]

2. studio_look returns real Studio state

{ "ok": true, "project": "webmcp-proof", "playhead": 0, "duration": 4,
  "canWrite": true, "elementCount": 1,
  "elements": [{ "handle": "hf:hf-10wy", "label": "Ship it", "tag": "div",
                 "start": 0, "duration": 4, "track": 0 }],
  "selection": null }

3. Select, inspect, write

selected  { "ok": true, "label": "Headline" }
inspect   { "text": "Ship it", "canEditText": true, "fieldKey": "self:0:h1" }
wrote     { "ok": true, "text": "Shipped it", "changed": true }

Studio's own URL state moved with it, so this is Studio's real selection, not a shadow copy:

#project/webmcp-proof?...&selFile=index.html&selId=headline&selSelector=%23headline

4. The file on disk changed

md5 before  b0d086373b574f887b93b52fcd8d2066
md5 after   d37d443d880eda060792386ebf4cd195

-  <h1 id="headline" data-hf-id="headline">Ship it</h1>
+  <h1 id="headline" data-hf-id="headline">Shipped it</h1>

5. And it renders

studio_frame's URL, against the real Puppeteer renderer, before and after:

t=0.500  ->  HTTP 200  image/png  14,424 bytes  1920x1080   "Ship it"
t=1.500  ->  HTTP 200  image/png  17,680 bytes  1920x1080   "Shipped it"

Both PNGs were opened and read. The frame shows the agent's edit.

The bug the proof found

The first run failed, and failed honestly:

{ "ok": false, "kind": "failed",
  "reason": "the text was not applied: persist-failed",
  "hint": "The write did not reach the file. Check Studio." }

The file was unchanged, checksum identical. So the reporting work in #3510 and #3518 did exactly its job: before that, this would have returned success.

Intercepting fetch gave the cause:

POST .../file-mutations/patch-element  ->  400 {"error":"target and operations required"}

An element's text lives in a child field, keyed self:0:h1 here. studio_set_text passed no field key, so buildNextDomTextFields planned zero operations and the patch went out empty.

The unit tests could not have caught this, because they mock setText and never cross that boundary. This is the class of failure only a browser run finds, which is why the plan insisted on this unit.

Fixed: the tool resolves the field, using the one named or the element's single field. Several fields, it asks which. No fields, it reports blocked. A named field that does not exist is rejected with the list of ones that do. Four regression tests, including the exact failing shape. One existing assertion expected the key to be undefined, which was the bug, so it now expects the resolved key.

Two real-world behaviours, both documented

Registration is asynchronous. A caller reading getTools() the instant Studio loads sees a partial list. Observed at 10 of 12 mid-registration. The docs page says to wait for toolchange or poll.

Tools on the current selection need a render between select and edit. Firing select-then-edit back to back from one script returns "nothing is selected", because applyDomSelection schedules a React state update. A real agent gets this for free, since its calls arrive as separate messages. This is the live confirmation of the select-first design rather than a defect.

The docs page

guides/webmcp, under Developers → Agent setup.

Its first job is defusing a name collision: guides/mcp already covers HeyGen's hosted MCP connector, which builds a video from a chat. This page is an agent working inside Studio. The page says what it is not before what it is.

Also flags the two things easiest to get wrong: the API is document.modelContext not navigator.modelContext, and Studio should stay visible because some write paths report failure through a toast the human sees rather than a return value.

Test plan

• Unit tests added/updated

• Manual testing performed

• Documentation updated

• Full end-to-end run above, in Chrome, against a live Studio.

• npx mint validate and npx mint broken-links --check-redirects both pass.

• Package suite 4606 passing across 414 files.

• bunx tsc --noEmit, bunx oxlint, bunx fallow audit --fail-on-issues all clean.

Still not covered

Native Chrome behind chrome://flags/#enable-webmcp-testing uses a different code path from the polyfill, and has not been tried. Neither has a bridge extension calling from the extension context. The polyfill path is now proven end to end; those two are not.