WCI (Web Context Interface) is a three-layer open standard that augments standard HTML with structured semantic metadata, compresses it into agent-optimised context, and provides a typed action protocol — shipped as compact modular layers (~2–12 KB minified each).
| 🏷️ | Semantic HTML annotations (data-wci-*) |
| ⚗️ | Token-efficient distillation for LLM context |
| ⚡ | Typed browser actions via WciBridge |
| 🛡️ | Site-wide agent policy (wci.txt / wci.json / wci.md) |
| 🧪 | 50-scenario grounding benchmark (see below) + Zenodo dataset |
Additionally, three site root files give agents site-wide grounding before they touch a single page — analogous to robots.txt:
| File | Purpose |
|---|---|
/wci.txt |
Directive file — allow/deny scopes, rate limits, auth |
/wci.json |
Structured manifest — task flows, scope descriptors |
/wci.md |
Narrative context — injected into LLM system prompt |
Live (Vercel): webcontextinterface.vercel.app · Demo
Live (GitHub Pages): amirrezaalasti.github.io/webcontextinterface · Demo
Static site (VitePress) with guides, API reference, and the interactive demo.
npm run docs:dev # docs only → http://localhost:5174
npm run website:build # docs + demo → docs/.vitepress/dist
npm run website:preview # preview the full site locallyDeploy: push to main — Vercel rebuilds automatically (vercel.json). For GitHub Pages, enable Settings → Pages → Source: GitHub Actions, then the deploy workflow runs on each push.
Full concept & implementation reference: agent.md — vision, agentic interface/AX, spec, APIs, and codebase map.
NotebookLM (shareable overview): WCI notebook — audio summaries, Q&A, and briefings grounded in the paper, specification, and benchmark materials (Google sign-in required).
Markdown sources live in docs/. Quick links:
| Guide | Topic |
|---|---|
| 🚀 Getting started | Install, annotate, distil, dispatch |
| 🏗️ Architecture | Layers and data flow |
| 📋 Specification | data-wci-* and site files |
| ⚗️ Distillation | WciDistiller |
| ⚡ Action protocol | WciBridge / ActionResult |
| 🛡️ Site policy | wci.txt and policy engine |
| 🤖 LLM integration | Closed-loop agent patterns |
Monorepo (development):
npm install
npm run buildnpm packages (v1.2.0):
npm install @webcontextinterface/core@^1.2.0Or install layers individually: @webcontextinterface/spec, @webcontextinterface/distiller, @webcontextinterface/bridge, @webcontextinterface/context.
| Package | Version | Description |
|---|---|---|
@webcontextinterface/spec |
1.2.0 | TypeScript types, role enum, readWciNodeSpec() |
@webcontextinterface/distiller |
1.2.0 | Pruner, JSON/Markdown serializers, WciDistiller |
@webcontextinterface/bridge |
1.2.0 | WciBridge, policy enforcement, ActionResult |
@webcontextinterface/context |
1.2.0 | WciContextLoader, PolicyEngine, wci.txt parser |
@webcontextinterface/core |
1.2.0 | All-in-one SDK — re-exports every package |
<section
data-wci-role="landmark"
data-wci-id="registration-form"
data-wci-desc="New user registration — capture email, password, accept terms">
<input
data-wci-id="email-input"
data-wci-role="form"
data-wci-desc="User's email address — must be unique"
data-wci-action="fill"
data-wci-required="true"
data-wci-state='{"value":"","valid":null}'
data-wci-scope="registration-form"
data-wci-priority="1"
/>
<button
data-wci-id="submit-btn"
data-wci-role="action"
data-wci-desc="Submit registration — creates the account"
data-wci-action="click"
data-wci-precondition="All required fields must be valid"
data-wci-scope="registration-form"
data-wci-priority="1"
>Create Account</button>
</section>import { WciDistiller } from '@webcontextinterface/distiller';
const distiller = new WciDistiller({ format: 'json', scope: 'registration-form' });
const view = distiller.distilJSON(document);import { WciBridge } from '@webcontextinterface/bridge';
import { WciContextLoader } from '@webcontextinterface/context';
const ctx = await WciContextLoader.load('https://your-site.com');
const bridge = new WciBridge();
bridge.setPolicy(ctx.policy);
const result = await bridge.fill('email-input', 'user@example.com');
await bridge.click('submit-btn');const ctx = await WciContextLoader.load('https://your-site.com');
// Policy is enforced on bridge.dispatch when set via bridge.setPolicy(ctx.policy).
// assertScopeAllowed is optional for pre-flight checks on planned scopes:
ctx.policy.assertScopeAllowed('checkout');| Attribute | Type | Description |
|---|---|---|
data-wci-id |
string | Stable unique ID |
data-wci-role |
enum | action · form · display · nav · status · landmark |
data-wci-desc |
string | LLM-optimised description |
data-wci-action |
enum | click · fill · select · check · upload · submit · navigate |
data-wci-state |
JSON | Current observable state snapshot |
data-wci-precondition |
string | Natural language guard condition |
data-wci-required |
boolean | Must be satisfied before form submission |
data-wci-options |
JSON array | Choices for select/radio groups |
data-wci-emit |
string | Custom DOM event fired after interaction |
data-wci-scope |
string | Parent landmark scope ID |
data-wci-hidden |
boolean | Prune this node from distilled output |
data-wci-priority |
1–5 | Importance ranking (1 = primary CTA) |
See Specification for details.
npm install # install workspaces
npm run build # build all packages (tsup → dist/)
npm run lint # TypeScript check
npm run demo # interactive demo at http://localhost:5173
npm run docs:dev # documentation at http://localhost:5174
npm run website:build # full site (docs + demo) for deploymentWIA_framework/
├── docs/ # Full documentation
├── packages/
│ ├── spec/
│ ├── distiller/
│ ├── bridge/
│ ├── context/
│ └── core/ # Umbrella SDK
├── demo/
├── examples/
└── paper/ # Research paper (LaTeX)
Official evaluation dataset (Zenodo): 10.5281/zenodo.20434088 — Evaluation Dataset for WCI (CC BY 4.0). Download scenarios.zip for all 50 single-shot grounding scenarios with five representations each (raw HTML, DOM outline, interactive candidates, WCI full, WCI grounding).
The same scenario tree ships in-repo under demo/scenarios/ — 5 handmade scenarios (flight booking, banking, checkout, dashboard, social media) plus 45 synthetic layouts. The published harness scores multi-step task grounding (meta.tasks.multiStep, primary task) across those five context formats via OpenRouter.
- Methodology (public summary):
docs/benchmark.md - Commands, comparison tables, and analysis:
evals/README.md - Archived run artifacts:
demo/public/README.md(eval-results-gpt5nano.json,eval-multistep-report-gemini35flash.json, …)
npm run eval:verify
npm run eval:multistep -- --models=gpt5Nano --scenarios=flight-booking,banking
npm run eval:merge-leaderboard # update demo/public/eval-results-all.json from multistep reports
npm run demo # live leaderboard on the websiteIf you use WCI in research or publications, please cite:
Amirreza Alasti — amirrezaalasti@gmail.com
@software{Alasti_WCI_Web_Context_2026,
author = {Alasti, Amirreza and Ghandeharioun, Niloufar and Karras, Oliver},
license = {MIT},
month = may,
title = {{WCI: Web Context Interface}},
url = {https://github.com/amirrezaalasti/webcontextinterface},
version = {1.2.0},
year = {2026},
note = {Contact: amirrezaalasti@gmail.com}
}Evaluation dataset:
@dataset{wci_eval_dataset_2026,
author = {Alasti, Amirreza},
title = {Evaluation Dataset for WCI: The Web Context Interface for Agentic Web Automation},
year = {2026},
publisher = {Zenodo},
doi = {10.5281/zenodo.20434088},
url = {https://doi.org/10.5281/zenodo.20434088}
}A machine-readable citation file is also provided in CITATION.cff.
Contributions are welcome! Please read our Contributing Guidelines to learn about our branch naming conventions, development setup, and Conventional Commit principles.
MIT — Open Standard. See LICENSE.