DEV Community

Trung Thanh Tran
Trung Thanh Tran

Posted on

Building a Faster Playwright MCP Server: Compact DOM Deltas, 1-Turn Form Filling, and Submit Guards

While using a browser automation agent over Model Context Protocol (MCP) to prefill job applications and publishing forms, four bottlenecks showed up in the execution logs before any site rate limit did:

  1. Full accessibility snapshots kept piling up in the conversation context until single turns carried 90,000+ tokens.
  2. Filling a form step-by-step (click, fill, click, fill) spent 10 to 15 MCP turns per page, and typing keystrokes into <select> elements caused multi-second stalls.
  3. Passing file uploads as inline Base64 strings through LLM tool arguments forced the model to emit ~20,000 output tokens and stalled tool calls for over three minutes.
  4. One wrong click on a button labeled Submit or Publish sent half-checked data live before a human could inspect the page.

I built turbo-browser-mcp (v0.4.0, MIT, playwright-core with no other runtime dependencies) to group those patterns into 10 consolidated MCP tools:

https://github.com/Tthanh2k6/turbo-browser-mcp

Here are the four design choices in the codebase, along with where the approach still has limits.

1. Bounded data-tbm-ref snapshots and onlyChanged deltas

inspect_compact walks the main document, nested accessible frames, and open Shadow DOM roots (el.shadowRoot), stamps deterministic f<frameIdx>:e<N> IDs onto data-tbm-ref, and caps output at maxChars (4000 by default).

Instead of dumping a full accessibility tree after every action, the server hashes each line's signature per tab (frameIdx, tag, label, value/checked state) and supports onlyChanged: true to return only added or modified controls. Calling act_fast, batch_actions, or smart_fill_form with returnSnapshot: true folds the updated view into the same tool response so the agent does not spend a separate read turn.

2. One-turn smart_fill_form for React inputs, rich text, and disk uploads

Standard .value = "..." writes often vanish on React forms on blur or submit because React tracks internal input state via _valueTracker. In src/dom-engine.mjs, smart_fill_form updates inputs through the native HTMLInputElement.prototype or HTMLTextAreaElement.prototype value setter after calling _valueTracker.setValue(''), then dispatches input, change, and blur.

In the same single MCP call, fields can target:

  • React/plain <input> and <textarea> elements, single/multi <select> (values), <input type="range"> sliders, radios, checkboxes, and ARIA [role="combobox"] widgets
  • contenteditable editors (ProseMirror, Quill, compose boxes) via execCommand('insertText') with InputEvent fallback
  • Nested iframes (frameIdx) and open Shadow DOM fields
  • Local files via file or files, which Playwright attaches straight from disk through setInputFiles or filechooser (never through inline Base64 strings)

3. A default allowSubmit=false guard that checks coordinates too

By default, resolveAllowSubmit evaluates to false unless allowSubmit: true is passed per call or TURBO_BROWSER_ALLOW_SUBMIT=true / --allow-submit is enabled on launch.

In src/dom-engine.mjs, SUBMIT_LABEL_RE blocks clicks, Enter key presses, and type submit: true actions matching submit, publish, post, send, apply, confirm and pay, pay, checkout, delete, and Vietnamese equivalents (gửi, đăng bài, nộp đơn, thanh toán), plus <input type="submit"> elements outside an explicit safe list (next, continue, search, filter, save draft). Raw viewport { x, y } mouse clicks resolve the element at that screen coordinate first so a coordinate click cannot bypass the label guard.

4. Local benchmark numbers (npm run benchmark)

Measured locally on Windows (Node v24.15.0, Chromium headless) against the self-contained HTTP fixture in benchmarks/benchmark.mjs:

Scenario Baseline turbo-browser-mcp Measured change (o200k_base)
Dense 140-button SaaS DOM snapshot 18,654 tok raw HTML / 3,568 tok full ARIA 1,135 tok compact (28 ms) / 56 tok delta (18 ms) 93.9% vs HTML, 68.2% vs ARIA, 98.4% on delta
10-field form fill + snapshot 11 MCP turns (574 ms, 12,197 dir / 72,614 cum tok) 1 MCP turn (82 ms, 811 tok, filled=10) 11 -> 1 turns, 7x faster, 93.4% dir / 98.9% cum saved
48 KiB PDF file upload (49,152 bytes) 44,728 tok inline Base64 tool arg 85 tok disk path (68 ms) 99.8% tokens saved, no Base64 encode
Open 6 tabs (60 ms simulated TTFB) 6 turns (998 ms sequential) 1 turn (420 ms parallel open_many) 6 -> 1 turns, 2.38x faster
Heavy media load (turbo vs clean) 252 ms (304 KiB, 9 asset hits) 165 ms (0 KiB, 0 asset hits) 1.53x faster, 100% media bandwidth cut
Article Markdown + Diagnostics errors 3,595 tok HTML / 3,460 tok all logs 156 tok Markdown / 601 tok errors-only 95.7% and 82.6% tokens saved

The 405 tests across 85 suites (25 test files under test/*.test.mjs: core integration, DOM/form and session/stdio stress suites, multi-round adversarial simulations, and 10 independent audit suites) run via npm test and pass on GitHub Actions CI for Node 20 and Node 22.

Trade-offs and open gaps

  1. Pre-existing closed Shadow DOM and sandboxed frames: An init script hooks Element.prototype.attachShadow so closed shadow roots created after page initialization stay inspectable and guarded, while closed roots that already existed on an attached CDP tab or live inside strict sandboxed frames fall back to Playwright frame handles, coordinate clicks, and keyboard input.
  2. Real network latency still dominates navigation: batching collapses DOM round-trips, while remote page load times still depend on the target server (blocking images, fonts, and media via network_session preset "turbo" trims asset overhead on heavy sites).
  3. Long-lived MCP child processes: if your client already has an older MCP stdio process running when you pull updates, you need to reload the MCP client so added schemas (like open_many, onlyChanged, capture_page, or network_session) register.

Looking for community feedback

If you use Playwright MCP or browser agents in daily workflows, what breaks most often in practice for you? I am especially curious about custom virtualized dropdowns, tricky iframe embed patterns, diagnostics you miss from Chrome DevTools, or places where SUBMIT_LABEL_RE would misclassify a safe navigation button.

Issues, PRs, and edge-case reports are welcome on GitHub:
https://github.com/Tthanh2k6/turbo-browser-mcp

Top comments (35)

Collapse
 
dafili profile image
Renhua Wei •

onlyChanged is where I'd expect the first bug: a per-line signature diff reports a deleted row as nothing changed, and a re-sorted list as a batch of new controls, so the agent still clicks f0:e12 that now points at a different button. Test it with two snapshots of the same 140-button page where one li is removed and the rest are reordered - if the second delta comes back empty, the ref map is lying about what is on screen.

Collapse
 
tthanh2k6 profile image
Trung Thanh Tran •

You were right about deletions. The delta listed only new or changed lines, so a removed row looked like "nothing changed". It now ends with a Removed: f0:e12, … line. Reordering was already fine: refs live as an attribute on the element, not by position, so a re-sorted list keeps its refs and adds nothing to the delta. Your exact case is now a test: 140 buttons, one removed, the rest reordered; the delta lists only the removed ref, and clicking a surviving ref still hits the same button. It's on main, not released yet.

Collapse
 
dafili profile image
Renhua Wei •

Good that a removed row now says so — the piece I would still pin down is ref reuse. If a later snapshot ever hands f0:e12 to a different element, an agent holding the stale ref clicks the wrong button and the delta looks clean, so a monotonic ref counter that never recycles plus a test asserting a stale ref comes back "gone" rather than resolving to a fresh element is what makes that Removed line trustworthy.

Thread Thread
 
tthanh2k6 profile image
Trung Thanh Tran •

You were right to push on this. Full snapshots used to renumber from e1, so a stale ref could land on a new element. Now refs never recycle within a document: survivors keep theirs, new elements get numbers above a per-page high-water mark, and a removed element's ref fails as not found. Your 140-button case is a test. On main, not released yet.

Thread Thread
 
dafili profile image
Renhua Wei •

Per-page high-water is the right move, and the case I would still test is navigation: a new document resets the ref namespace, so an agent holding a pre-navigation ref has to come back not-found rather than land on the same-numbered element in the new page. A counter scoped to the session instead of the document gets you that for free.

Thread Thread
 
tthanh2k6 profile image
Trung Thanh Tran •

That's a real gap. The counter is per document, so after a navigation a pre-navigation ref only fails when the new page has fewer elements than its number. On a bigger page it would resolve to whatever got that number. I'm moving the counter to the tab so it carries across navigations.

Thread Thread
 
dafili profile image
Renhua Wei •

Tab-scoped counter kills the collision, but make the rejection explicit instead of implied: stamp each ref with the document's loaderId from Page.frameNavigated and reject any ref whose stamp differs from the current one. That fails on the first cross-document navigation whatever the page size, and it still accepts a bfcache restore, because a restored document keeps its loaderId.
Cheaper test than counting elements: navigate 140 buttons -> 300 buttons and assert the old f0:e12 comes back not-found while f0:e300 on the new page resolves.

Thread Thread
 
tthanh2k6 profile image
Trung Thanh Tran •

That's a cleaner rule than mine. The counter fix is in main now: ref numbers keep counting per tab across navigations, so a stale ref fails with "not found (page navigated or re-rendered since this ref was issued)" instead of landing on a new element. A loaderId stamp would make the cross-document case explicit at almost no cost, so I'll add it next to the counter. The counter still has to cover SPA re-renders, where loaderId stays the same.

Thread Thread
 
dafili profile image
Renhua Wei •

The SPA case is where the attribute-on-element design already does half the work: a re-rendered subtree drops the ref attribute, so a stale ref fails on its own. What it does not catch is node recycling — react-window and friends keep the same DOM node and swap its content, so the ref survives and now points at a different row.
Stamp the element at issue time with [loaderId, first 128 chars of the node's textContent] and fail when either moves; test it by scrolling a 10k-row list one viewport and asserting the off-screen refs come back stale instead of resolving to the row that took their slot.

Thread Thread
 
tthanh2k6 profile image
Trung Thanh Tran •

Both are in. The loaderId stamp shipped in 5bc0575, so a ref from a previous document fails before any DOM lookup and a bfcache restore still works. For recycled nodes, each ref now keeps the first 128 chars of its text from the last snapshot, and a mismatch fails as "now shows different content". Your 10k-row list is the test (30 reused rows, scroll one viewport). Inputs and contenteditable are exempt, their value is the point.

Thread Thread
 
dafili profile image
Renhua Wei •

Exempting the value is right; exempting the identity is not. Stamp inputs with name + type + aria-label, so a recycled node whose label flipped from email to phone fails instead of getting filled — with the value exempt you have nothing left to compare.

Thread Thread
 
tthanh2k6 profile image
Trung Thanh Tran •

You're right, with the value exempt there was nothing left to compare. Fields now keep an identity instead: tag, type, name, id, aria-label, placeholder, role and label text. An input recycled from email to phone fails with "now points to a different field" before anything is typed. Digits in the label text are ignored, so a live "12/160" counter doesn't trip it. It's on main (36fb9e2).

Thread Thread
 
dafili profile image
Renhua Wei •

Those attributes still collide when two fields are clones: repeated address lines, a start/end date pair, two "Phone" inputs in different sections - same tag, type, name, aria-label, so a swap between them passes silently. Add the position inside their common parent as the last tiebreaker (input[name^=address]:nth-of-type(2)) and assert a straight swap of those two fails exactly like the email-to-phone case. Same trap as your digit rule, one level up: aria-label counters like "(3 of 7)" need the number stripped or every re-render looks like a new field.

Thread Thread
 
tthanh2k6 profile image
Trung Thanh Tran •

Fair point, the clone case was a real gap. When two fields share every identity attribute, their position among those clones inside the nearest common container is now the last part of the fingerprint, so swapping two "Phone" inputs fails the same way email-to-phone does. Digits are masked in aria-label, placeholder and title too, so "(3 of 7)" becoming "(4 of 7)" doesn't trip it. On main in fa17fd1.

Thread Thread
 
dafili profile image
Renhua Wei •

Position holds until a clone disappears: delete the first of three "Phone" rows and every survivor shifts index, so untouched fields start reporting "now points to a different field" - false positives, which is the failure mode that kills trust in the check fastest. Cheap guard: when the rest of the fingerprint matches a sibling and only the index moved, score that as a layout shift rather than an identity change - compare the clone group as a multiset, not by position. Fixture worth adding: three identical rows, delete row 1, assert zero mismatches and one "group changed size" event.

Thread Thread
 
tthanh2k6 profile image
Trung Thanh Tran •

Good catch, that was a real false positive. The clone suffix now carries the group size (index/size). If the size changed, the old ref still works and the result gets a note like "clone group for e12 changed size (3 -> 2)". Same size with a different index is still refused as a swap. Your fixture is in the tests: three rows, delete row 1, zero mismatches. On main in ba47c55.

Thread Thread
 
dafili profile image
Renhua Wei •

size+index still leans on the nearest common container: reorder two sections and the whole group lands under a different parent, so every index resets against it and untouched fields read as swaps again. Pin the container's own identity too (tag + name, or a data-section marker) and key the group as (container, index/size). Fixture: two identical three-row groups, swap the sections wholesale, assert zero mismatches and no "changed size" notes.

Thread Thread
 
tthanh2k6 profile image
Trung Thanh Tran •

I wrote that fixture before changing anything: two fieldsets, three identical Phone rows each, then insertBefore to swap the sections. All six old refs filled their own fields with zero notes, and smart_fill_form agreed. The clone group is the nearest ancestor that holds another clone, which here is each fieldset, so moving a fieldset keeps index/size. It's in the suite now as a regression test (20c4e23). If a framework re-creates the sections instead of moving them, the old refs are gone and fail as stale, which is what I want.

Thread Thread
 
dafili profile image
Renhua Wei •

Your fixture pins the group to the fieldset by construction: three identical rows inside each fieldset means the nearest clone-holding ancestor can only be the fieldset, so index/size survives any move you can make with insertBefore. Flip the distribution — one Phone row per fieldset, three fieldsets — and the nearest holder becomes the form, so the same swap makes the moved row's index depend on its siblings and a ref that filled correctly in your layout should fail as stale in mine. Same DOM operation, opposite verdict; worth a second fixture that asserts stale rather than the fill, otherwise the reorder case stays green because of where the fixture happens to put the clones.

Thread Thread
 
tthanh2k6 profile image
Trung Thanh Tran •

Added that flipped-distribution fixture right next to the first one in 3446e79: three unlabelled fieldsets with one identical Phone input each, so the nearest clone-holding ancestor falls back to the form. Swapping the first two fieldsets with insertBefore flips their indices inside the form (0/3 <-> 1/3) and both old refs throw the stale-ref error while the third fieldset at 2/3 keeps working.

Thread Thread
 
dafili profile image
Renhua Wei •

Your fixture catches the moves that renumber; the ones that don't are the dangerous half. Pull the Phone input out of fieldset A and append an equivalent one to fieldset B in the same tick and the count and the per-parent size never change, so an (index, size) stale check stays green while the fill lands in the wrong row. Stamp data-owner on each fieldset and assert the filled node's owner instead of its position, then your 0/3 to 1/3 swap and the remove-plus-append case are the same assertion.

Thread Thread
 
tthanh2k6 profile image
Trung Thanh Tran •

That remove-plus-append case exposed two holes at once: moving an input from fieldset A into fieldset B kept 0/3 unchanged when total and per-parent counts matched, and appending a second Phone input into fieldset B dropped B's nearest clone container from the form (1/3) to fieldset B (0/2), which looked like a 3 -> 2 row deletion. Fixed in 954edaa by stamping WeakMap owner IDs for both the enclosing group (fieldset/tr/role=group) and the clone container (#owner:groupId:containerId), with both cases added to test/night-19-11-clone-shift.test.mjs.

Thread Thread
 
dafili profile image
Renhua Wei •

WeakMap stamps die with the node, so if any code path replaces a fieldset or resets a container's innerHTML the new nodes have no owner and your two cases collapse back to 0/0 with the suite still green. Add a canary before the delta: assert ownerMap.size equals enclosing groups + clone containers, so a missing stamp fails loud instead of silently dropping the row. On the append case, that canary is what would have caught it in production rather than only in the fixture.

Thread Thread
 
tthanh2k6 profile image
Trung Thanh Tran •

Resetting a container's innerHTML destroys the child inputs and their data-tbm-ref attributes too, so those refs fail immediately as not found. If a code path keeps the existing input node and wraps it in a newly created fieldset, ownerOf(newFieldset) assigns the next monotonic integer from ++window.__tbmOwnerSeq (for example #owner:1:4 becomes #owner:5:4), so the fingerprint check still rejects the ref without needing WeakMap.size (which JS WeakMaps do not expose).

Thread Thread
 
dafili profile image
Renhua Wei •

You are right that WeakMap.size does not exist and you can not enumerate it either, so my canary was nonsense, my mistake. If you want the owner check to be assertable at all, mirror the id into a data attribute at stamping time and query for the unstamped set instead: document.querySelectorAll('[data-tbm-ref]:not([data-tbm-owner])').length must be 0 after every mutation batch. That catches the wrap-in-a-new-fieldset case as a failed assertion rather than as a silently missing ref, and the monotonic seq you described still lives in the attribute value.

Collapse
 
amintacccp profile image
tamina •

The allowSubmit=false default is the part I'd steal first — one wrong click sending half-checked data live is exactly the failure mode that makes people distrust browser agents. And the React _valueTracker detail is the kind of thing you only learn by watching a fill vanish on blur. Curious about your open question: did SUBMIT_LABEL_RE ever misclassify a safe button in your testing, like a 'Save draft' or 'Continue' that also triggers a submit? Nice write-up, the local benchmark numbers make the trade-offs easy to follow.

Collapse
 
tthanh2k6 profile image
Trung Thanh Tran •

Yes, that exact case bit me early on. Multi-step wizards (like Workable and Greenhouse forms) often render "Continue", "Next", or "Save draft" as <button type="submit"> inside a <form>, so blocking every submit-type button broke pagination and draft saving.

I ended up splitting the check into three regexes in src/dom-engine.mjs: SUBMIT_LABEL_RE (publish, submit, send, pay, delete), SAFE_SUBMIT_TYPE_RE (next, continue, back, search, filter, save draft, preview, cancel), and COMPOUND_DANGER_RE. If a <button type="submit"> matches SAFE_SUBMIT_TYPE_RE, the form guard temporarily marks form.__tbmAllowedSubmit = true for that click unless the label also contains a final-action phrase like "Continue to payment" or "Save and submit".

Collapse
 
amintacccp profile image
tamina •

That three-way split is a neat fix — I hadn't thought about the wizard case where 'Continue' is technically a submit button but semantically just pagination. The COMPOUND_DANGER_RE escape hatch for 'Continue to payment' is the part I'd steal back, honestly. Thanks for walking through the actual regexes, that makes the trade-off a lot clearer than the usual 'just block submits' advice.

Collapse
 
alexcodebytes profile image
Oleksandr •

the react _valuetracker hack is so painfully real. i've spent hours trying to figure out why .value = '...' wasn't sticking on react forms until i realized i had to bypass the prototype. but to answer your question: custom virtualized dropdowns (like react-select) are the absolute worst for agents. they literally don't exist in the dom until you click them, so standard snapshots miss them completely. how are you handling those?

Collapse
 
tthanh2k6 profile image
Trung Thanh Tran •

react-select and Radix/Headless UI portals are definitely the trickiest ones because the <div role="option"> nodes only mount after focus or pointerdown.

Right now smart_fill_form handles the standard [role="combobox"] / [aria-haspopup="listbox"] pattern in two steps inside the same call: it clicks the combobox trigger first, waits briefly for the portal/listbox to mount in the document, and then matches the visible [role="option"] text. Where that still breaks is heavy windowing (like react-window inside a 5,000-row select) where the target option isn't mounted until you type into the inner search input or scroll the list container. For those, I currently fall back to batch_actions (click trigger -> type filter text -> click option).

Collapse
 
alexcodebytes profile image
Oleksandr •

oh man, react-window inside a select is the absolute final boss of browser automation. if it's not in the dom, you literally can't click it, so the batch_actions fallback (click -> type -> click) is actually the smartest way to handle it. it mimics what a real human would do anyway. trying to manually scroll a virtualized list via script is a special kind of hell lmao.

Collapse
 
johnnylemonny profile image
𝗝𝗼𝗵𝗻 •

Resolving raw { x, y } coordinates against SUBMIT_LABEL_RE before firing a mouse click is such a smart detail. A label-based submit guard that an agent can accidentally bypass with a coordinate click is just security theater, so keeping allowSubmit=false by default and checking the underlying element at the target coordinates gives real human-in-the-loop safety before anything irreversible goes live.

Resetting React's _valueTracker alongside native prototype setters in smart_fill_form also fixes one of the most annoying silent failure modes in browser automation, where .value = "..." looks completely fine in the DOM until blur or submit wipes the controlled state clean.

To answer your question on what breaks most often in daily workflows: portaled dropdowns and virtualized comboboxes (like Radix or Headless UI menus that mount their listbox options at document.body instead of inside the form container). When the trigger is inside a nested frame or card and the options render at the root, or only mount while focused—scoped snapshots and onlyChanged deltas can easily miss the newly mounted option nodes.

Collapse
 
paullovelace profile image
Paul Lovelace •

The 48 KiB PDF number is the one that made me wince — 44,728 tokens just to hand a file to the model, versus 85 for a disk path. That's not an optimisation, that's a whole failure mode hiding in plain sight. Haven't run turbo-browser-mcp myself, but the upload fix alone would've saved me a few very long afternoons.

Collapse
 
tthanh2k6 profile image
Trung Thanh Tran •

Thanks. That one surprised me too when I measured it. The server only passes the file path to Playwright's setInputFiles, so the bytes never go through the model at all.

Collapse
 
eye_java_420f1faa10ae8b86 profile image
Nan •

On the open question about SUBMIT_LABEL_RE misclassifying buttons: I moved that check to the request layer a while ago and never looked back. Continue in a Workable wizard and Submit on the last step both sit on a submit button, but only one ends in a URL change or a mutating fetch. If you record the URL and in-flight requests for about a second after the click, draft and save buttons give themselves away: they fire an XHR and stay on the same page. Labels lie in every language, so classifying by aftermath sidesteps the naming problem entirely.

For the portal dropdowns, keyboard events saved me more than pointer ones. Focus the combobox and send ArrowDown then Enter. react-select and Radix open their menu on focus anyway, so you never have to wait for the option list to mount, and react-window stays somebody else's problem.

Collapse
 
tthanh2k6 profile image
Trung Thanh Tran •

Took most of this. Since today a click that starts a POST, PUT, PATCH or DELETE within 800 ms comes back with possibleSubmit plus the method and host. It reports and doesn't block, and the label check stays as the first gate. The first false positive was an ad beacon firing on dev.to's own Publish button, so analytics hosts are excluded now.

Some comments may only be visible to logged-in visitors. Sign in to view all comments.