DOM Collective

The UI files a grievance. You ratify the fix.

Comment

Inspiration

Picture someone reaching the last step of a scholarship application with only a keyboard and the browser zoomed to 200 percent. The form looks official and complete, but Continue is a clickable div, the income field has no real label, the error message is not announced, the dialog loses focus, and the sticky bar can hide the next action. Nothing has crashed. The page has simply become hard to use at the exact moment it matters.

An AI agent can call APIs or try to click through a page, but these failures live inside the current browser session: focus, dialog lifecycle, conditional content, unsaved values, zoom, viewport, and overlay geometry. The same broken controls that block a person also make click-based agent automation brittle.

We asked a different question: what if the webpage could describe not only what is wrong, but also the exact safe ways it permits an agent to repair the live experience—and require the human to ratify those changes first?

What it does

DOM Collective turns that question into a small, visible negotiation between three parties: a person, an agent, and the live page.

The person says what they are trying to do—review the application with a keyboard at 200 percent zoom—and sets the boundaries: do not change form copy, values, or validation rules, and never submit the application. The agent asks the page to inspect the real interface, traces the blocked keyboard journey, and drafts a contract from repairs the site already owns. The page then shows the exact contract to the person. Nothing changes until they approve it.

After approval, the page issues one state-bound, one-use capability. It applies the named repairs atomically through React state, re-runs the same journey on the rendered page, and produces a rollback receipt. The demo begins with five real failures and ends with five passing checks while the protected application data stays untouched.

What it does

The reference application is a fictional scholarship portal with a deliberately broken keyboard journey at a simulated 200% zoom. Through WebMCP, the page exposes structured evidence about five supported issues:

  • a fake button;
  • a missing programmatic label;
  • a visual-only validation error;
  • broken dialog focus behavior; and
  • a sticky action bar that obscures Continue.

The agent inspects the exact live state and drafts an Executable Interface Contract using only repair primitives owned by the site. The human reviews the operations and protected invariants in a visible ratification dialog. Approval creates a one-use receipt bound to the contract, current state version, DOM hash, expiration, and exact operation digest.

After validation, the page applies the repair through declarative React state, re-runs the same journey, reports before-and-after evidence, confirms protected business behavior remained unchanged, and issues a rollback receipt.

The memorable visual layer portrays broken DOM elements as workers filing grievances. The satire targets div soup, inaccessible implementation, and fragile CSS—not disabled users or real workers.

How we used WebMCP

Canonical tools:

inspect_live_interface
trace_access_path
draft_access_contract
request_ratification
apply_ratified_contract
verify_contract
rollback_contract

WebMCP is a strong fit because the relevant evidence and state live in the current document. The page owns the repair registry and runs the same domain services for both human UI and agent tools. This avoids giving the agent an arbitrary browser mutation interface. Rather than saying “go fix the form,” the agent receives a small vocabulary of actions that the page can validate against the exact state it inspected.

The canonical tools are statically registered for reliability. A temporary one-use execution tool may be demonstrated as a progressive enhancement only if it is proven reliable in the target browser.

What humans and agents do together

Human Agent Live page
States the need and protected intent. Combines structured evidence into a coherent plan. Knows the current DOM, focus, viewport, branch, and allowed repairs.
Reviews, revises, approves, or denies. Calls only the page's registered tools. Validates authority and applies changes.
Repeats the journey and judges usability. Requests deterministic verification. Produces evidence and rollback.

No party can complete the intended flow alone.

That separation is the point. The person supplies intent and consent. The agent helps turn evidence into a plan. The page keeps authority over its own DOM, business rules, and allowed changes. A useful repair only happens when all three line up.

How it creates a better experience

Without this flow, a person has to work around a broken form, file a support ticket, or trust an agent that may be guessing at the page. With DOM Collective, the page can explain the actual failure in plain, structured evidence, and the person can see exactly what will change before it happens.

The agent is useful without becoming all-powerful. It does not need to inspect dozens of nodes by hand or invent a selector. It can combine the page's known repair primitives into one reviewable plan. The page does not infer the user's needs or hand over unrestricted write access. The contract and its protected invariants make the collaboration visible, bounded, and reversible.

How it was built

Implemented stack:

  • Next.js App Router, React, strict TypeScript, Tailwind CSS, and Zustand;
  • a central domain store shared by UI and WebMCP handlers;
  • a compile-time allowlist of five repair primitives;
  • state-bound, single-use capability receipts;
  • declarative React repair policy;
  • deterministic keyboard, focus, relationship, geometry, and invariant checks;
  • Vitest and Playwright;
  • one HTTPS deployment on Vercel, with a server-renderable landing route and a client-owned WebMCP demo.

The implementation is deliberately split in two. Pure domain code decides whether a contract, receipt, or repair is valid. Browser-side ports inspect the mounted DOM and verify the actual rendered result. React receives only a declarative repair policy, so the interface changes through a normal re-render instead of transient injected markup. The WebMCP bridge registers tools after hydration, detects unsupported browsers, and protects registration from Strict Mode replay, HMR, and route remounts.

Challenges we ran into

The easy version of this project would have been a visual before-and-after demo. That would not prove much. We needed the real DOM to change, the keyboard path to become usable, and the original application data to stay exactly as it was.

The main challenge was lifecycle ownership. document.modelContext only exists in the browser after hydration, while React can replay effects in Strict Mode, hot-reload code during development, and remount the route. The bridge therefore tracks one active owner, aborts prior registrations, and keeps tool execution separate from route teardown.

The other hard part was making human approval meaningful. A generic “yes, fix it” could be reused after the page changed. DOM Collective binds approval to the contract ID, snapshot ID, state version, DOM hash, operation digest, invariant digest, expiry, and one-use receipt. Stale, expired, replayed, forbidden, or unratified requests fail closed instead of quietly changing the form.

Accomplishments

  • [x] Complete human–agent–page contract journey.
  • [x] Real semantic React re-render, not a visual overlay.
  • [x] Deterministic rejection of stale, expired, replayed, and forbidden actions.
  • [x] Before/after journey evidence with business invariants.
  • [x] Reliable production demo and reset.

What we learned

  • A page-owned repair vocabulary is safer and easier to explain than arbitrary browser mutation. “Use a native button” is a product decision; arbitrary CSS or selectors are not.
  • Consent must bind exact state, not a vague intention. If the page changes, the agreement should stop being valid.
  • Static tools are the reliable baseline. Dynamic tool registration is useful polish, but the core journey still needs to work when it is unavailable.
  • Short, structured tool results make it easier for an agent to take the next safe action without pretending it understands the whole page.
  • A scoped verification report is more honest than claiming universal accessibility compliance. We can prove this journey, these five repairs, and these protected invariants.

What's next

Potential future work, explicitly outside the MVP:

  • reusable contract and repair-registry SDK;
  • server-backed capability signatures and audit receipts;
  • author-defined repair registries for additional journeys;
  • independent research with accessibility practitioners and users;
  • integration with existing design systems and test suites.

Important limitations

  • This is a synthetic reference application, not a production service.
  • It does not repair arbitrary third-party websites.
  • It does not provide complete WCAG certification.
  • It does not defend against a compromised origin or independently privileged browser automation layer.
  • Verification covers one defined journey and five supported issue classes.

Built With

Share this project:

Updates

Submission history