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 — all in < 8 KB per layer.

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

---

Documentation website

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 locally

Deploy: 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

---

Install

Monorepo (development):

npm install
npm run build

npm packages (v1.1.0):

npm install @webcontextinterface/core@^1.1.0

Or install layers individually: @webcontextinterface/spec, @webcontextinterface/distiller, @webcontextinterface/bridge, @webcontextinterface/context.

---

Packages

Package	Version	Description
@webcontextinterface/spec	1.1.0	TypeScript types, role enum, readWciNodeSpec()
@webcontextinterface/distiller	1.1.0	Pruner, JSON/Markdown serializers, WciDistiller
@webcontextinterface/bridge	1.1.0	WciBridge, policy enforcement, ActionResult
@webcontextinterface/context	1.1.0	WciContextLoader, PolicyEngine, wci.txt parser
@webcontextinterface/core	1.1.0	All-in-one SDK — re-exports every package

---

Quick start

1. Annotate your HTML

<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>

2. Distil

import { WciDistiller } from '@webcontextinterface/distiller';

const distiller = new WciDistiller({ format: 'json', scope: 'registration-form' });
const view = distiller.distilJSON(document);

3. Dispatch actions

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');

4. Site context

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');

---

data-wci-* attribute reference

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.

---

Development

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 deployment

Repository layout

WIA_framework/
├── docs/                 # Full documentation
├── packages/
│   ├── spec/
│   ├── distiller/
│   ├── bridge/
│   ├── context/
│   └── core/             # Umbrella SDK
├── demo/
├── examples/
└── paper/                # Research paper (LaTeX)

---

Benchmark

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, commands, and comparison tables: 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 website

---

Citation

If 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.1.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.

---

License

MIT — Open Standard. See LICENSE.