How DOM Collective works, and how to run it.

01 / Overview

What this is

DOM Collective is a WebMCP reference application for Executable Interface Contracts. A live webpage identifies specific runtime failures in one user journey, an agent drafts a narrowly scoped repair contract from primitives the page already supports, a human reviews and ratifies it, and the page applies only the whitelisted changes before verifying the same journey again.

The problem it responds to: interface failures like a fake button, a missing label, or broken dialog focus live entirely in the current browser session — focus, viewport, open dialogs, unsaved values. They are invisible to static analysis, and an agent that clicks through a broken page blindly is brittle. The alternative, giving an agent unrestricted DOM/JS/CSS access, is unrestricted mutation. This project is the middle path: bounded, named, human-approved repairs only.

Seven product principles

1. Repair the interface, don't just report on it.
2. The agent may only choose primitives the site itself already owns.
3. The human holds final authority — an agent can never approve its own plan.
4. Every capability is bound to one exact interface state and is single-use.
5. The page proves the outcome instead of asserting it.
6. Every applied change is reversible by design, with a rollback receipt.
7. The demo degrades honestly — no WebMCP, no fake discovery, just a working fallback.

02 / Setup & verify

Run it locally

1. npm install
2. npm run dev — then open / for the landing page or /demo for the interactive demo

Full verification sequence

1. npm run typecheck
2. npm run lint
3. npm test — unit and component coverage (Vitest)
4. npm run build
5. npm run test:e2e — browser coverage (Playwright), including a native WebMCP project

To run the browser suite against a deployed build instead of a local dev server:

PLAYWRIGHT_BASE_URL=https://your-deployment-url npx playwright test

03 / Architecture

How it's built

The domain logic never imports React or the DOM. It lives in lib/domain as a pure state machine plus a compile-time repair registry — a fixed allowlist of five repairs, never raw selectors, JavaScript, or CSS. Browser-only concerns (focus, viewport, live DOM reads) live in lib/browser. The WebMCP adapters in lib/webmcp are thin transport — they validate input shape and call the same domain functions the React UI calls, nothing more.

Contract phase progression

RAW → SNAPSHOTTED → DRAFTED → AWAITING_RATIFICATION → RATIFIED → APPLIED → VERIFIED

Any contract can also end at DENIED, STALE, EXPIRED, or ROLLED_BACK — every phase transition re-validates state version, DOM hash, and receipt status before it does anything.

Apply and verify

Applying a contract consumes a one-use capability receipt, updates a single declarative repairPolicy object, and issues a mutation receipt holding both the previous and new policy. Verification re-runs five deterministic checks against the actually-rendered DOM plus four protected invariants — it never trusts what the contract claims, only what the page currently shows.

04 / WebMCP tool reference

The seven tools

Every tool call and response shares one envelope: ok, the current stateVersion and phase, either a result or an error, and allowedNextTools — the page always tells the caller what it's permitted to do next, rather than letting it guess.

05 / Security model

What this proves, and what it doesn't

The thesis is cooperative least privilege, not a hardened security boundary. An agent can only ever choose from primitives the site already owns; the page only ever applies a change after a visible human click; every capability is bound to one exact snapshot, contract, and DOM hash, and can be used exactly once.

What an agent is never allowed to send

CSS selectors, XPath, raw JavaScript, HTML, arbitrary attributes, URLs, network requests, file paths, or anything resembling a submission instruction. Every operation resolves to one of five named repairs or the request fails closed.

What stays protected on every applied contract

Visible copy, current form values, validation configuration, and the submission count — checked as four digest-bound invariants on every apply and every verification, independent of what the contract itself claims.