# Every page, agent‑operable. (https://affordances.vercel.app/)

Your UI already knows what it can do. Affordances lets you declare it once. Humans, browser agents, headless agents and MCP clients all use the same definition.

[Get started](https://affordances.vercel.app/docs/quickstart) [How it works](https://affordances.vercel.app/#how)

**One URL, two readers.** A product page, a team settings page, and a booking page, each shown as a person sees it (`text/html`) and as the graph an agent reads (`application/vnd.affordances+json`) at the same URL: its entities, its action with input, guard, and availability, and its nav. Calling the action returns a delta with only what changed.

The shift

## Every page has two readers now.

Human · text/html

Reads pixels.

Scrolls, hovers, decides. Your UI was built for this reader, and it shows.

Agent · application/vnd.affordances+json

Reads structure.

Needs names, inputs and preconditions. Today it gets a screenshot and a guess.

Before

## Serving agents today means describing every page five more times.

A markdown twin. An OpenAPI spec. MCP routes. Tool handlers. WebMCP glue. Each one a hand-written copy of what the UI already knows. Change a price in `page.tsx` and five files still say the old one: nothing fails, agents just get it wrong. Meanwhile a screenshot agent takes twenty-five screenshots, and overruns its context window, to add one pair of shoes to a cart.

After, with Affordances

## Three files per route. One definition.

`page.tsx` renders. `state.ts` says what's on the page. `actions.ts` says what can be done. Every agent surface (server action, WebMCP, HTTP graph, MCP, Markdown) is derived from those, so one edit reaches all of them. The agent finishes in five calls: read the graph, add to cart, read the checkout, then place the order, once to get the confirmation summary and once with `confirm: true`.

How it works

## Declare it next to the page.

An action is a server action with a schema, an exposure level and a list of what it changes. Pick a surface to see what the same definition becomes.

```ts
'use server'

export const addToCart = defineAction({
  name: 'addToCart',
  description: 'Add a variant of this product to the cart',
  input: z.object({
    sku: z.string(),
    quantity: z.coerce.number().int().min(1).default(1),
  }),
  state: product,
  expose: 'public',
  requires: 'The variant is in stock',
  guard: ({ input, state }) =>
    !input || inStock(state, input.sku) || 'Sold out',
  effects: ['cart'],
  run: (input, ctx) => cart.add(ctx, input),
})
```

One `defineAction`, five surfaces:

- **Server action** (Humans): A plain server action. The form’s fields are validated against `input` before `run` sees them.
- **WebMCP tool** (Browser agents): `<AffordancesProvider>` registers it in the tab while the guard passes. Calls go through the same handler as any agent.
- **HTTP** (Headless agents): The page’s own URL answers with a graph. A call returns a delta with only the entities in `effects`.
- **MCP** (Claude, Cursor): Two tools for the whole site. The model finds `addToCart` in the graph `affordances_open` returns, then calls it by name.
- **Markdown** (Readers and LLMs): Not from the action: the page itself, as text. Buttons drop out, so what it can do lives only in the graph.

Approvals

## Agents act. Humans approve.

Mark an action `expose: 'confirm'` and an agent can prepare it but never finish it. The call waits for a person.

```ts
export const placeOrder = defineAction({
  name: 'placeOrder',
  expose: 'confirm',
  run: (input, ctx) => orders.place(ctx.session.id),
})
```

An agent's first call answers `409 confirm_required` with a summary ("Place order · $244.00"). Nothing runs until the person approves. Then the agent sends the call again with `confirm: true` and gets the delta back: the emptied cart and a redirect to the orders page. If the person declines, nothing is charged and the agent doesn't call again.

Discovery

## Agents find it on their own.

A browser agent that has never heard of Affordances, asked to add a tee to a cart. Its browser supports WebMCP, and its prompt says only that pages can register tools. On the product page, the page offers `addToCart`, and it calls it.

One recorded run on Claude Opus 5.5, the task "Add a Heavyweight Tee in size M to my cart.", two browser agents on one clock. Both start with the same built-in tools: `goto`, `click`, `fill` and `press`; the WebMCP browser adds `page_tool`, which calls whatever tools the current page registered, listed under each result.

- **With WebMCP** (its prompt says only that pages can register tools): `goto("/")`, where the home page registered `search`. It went to the Heavyweight Tee's page, which registered `addToCart`, and `search` went away. It called `addToCart({ sku: "TEE-BLK-M", quantity: 1 })` and answered. 10.6s, 4 turns.
- **Plain browser**: `goto("/")`, then the product page, clicked size M, clicked Add to cart, then went to `/cart` to check and answered. 20.8s, 6 turns.

Both added the tee to the cart. The [React and WebMCP guide](/docs/guides/react) shows how a page registers its actions.

Proof

## Measured, not claimed.

The same shopping tasks on the same model, against two baselines: a browser agent reading accessibility snapshots and a screenshot agent clicking on pixels. The Affordances agent reads the graph. From the latest committed runs; the [bench page](https://affordances.vercel.app/docs/benchmarks) has every row.

**Claude Opus 5.5**, 5 runs per task. Median per task: 47,681 tokens for the browser agent, 34,551 tokens for the screenshot agent, 4,093 tokens for the Affordances agent; 17.1s for the browser agent, 20.3s for the screenshot agent, 8.9s for the Affordances agent; 6 steps for the browser agent, 5 steps for the screenshot agent, 3 steps for the Affordances agent; $0.10 for the browser agent, $0.097 for the screenshot agent, $0.019 for the Affordances agent per successful task. Tasks completed: 100% for the browser agent, 100% for the screenshot agent, 100% for the Affordances agent. The Affordances agent against the stronger baseline on each measure: 8.4× fewer tokens than the screenshot agent (11.6× fewer than the browser agent); 1.9× faster than the browser agent (2.3× faster than the screenshot agent); 5.1× cheaper per success than the screenshot agent (5.3× cheaper than the browser agent).

| Task | Browser tokens | Screenshot tokens | Affordances tokens | Browser time | Screenshot time | Affordances time | Browser passed | Screenshot passed | Affordances passed |
| --- | --: | --: | --: | --: | --: | --: | --: | --: | --: |
| Add to cart | 47,681 | 45,515 | 4,093 | 15.9s | 21.7s | 9.2s | 5/5 | 5/5 | 5/5 |
| Change quantity | 40,189 | 16,086 | 4,347 | 16.8s | 10.6s | 8.8s | 5/5 | 5/5 | 5/5 |
| Checkout | 48,555 | 34,038 | 4,005 | 20.3s | 17.4s | 8.9s | 5/5 | 5/5 | 5/5 |
| Search | 10,825 | 34,551 | 2,724 | 6.9s | 20.0s | 7.9s | 5/5 | 5/5 | 5/5 |
| Order status | 9,145 | 15,982 | 2,189 | 10.2s | 7.3s | 4.0s | 5/5 | 5/5 | 5/5 |
| Two items checkout | 177,717 | 106,845 | 19,208 | 21.2s | 37.6s | 15.6s | 5/5 | 5/5 | 5/5 |
| Edit cart | 219,337 | 107,192 | 16,013 | 24.6s | 47.3s | 15.5s | 5/5 | 5/5 | 5/5 |

**Claude Haiku 5.5**, 5 runs per task. Median per task: 47,356 tokens for the browser agent, 40,270 tokens for the screenshot agent, 5,138 tokens for the Affordances agent; 8.8s for the browser agent, 16.5s for the screenshot agent, 3.5s for the Affordances agent; 6 steps for the browser agent, 5 steps for the screenshot agent, 3 steps for the Affordances agent; $0.0031 for the browser agent, $0.0026 for the screenshot agent, $0.00053 for the Affordances agent per successful task. Tasks completed: 100% for the browser agent, 97% for the screenshot agent, 100% for the Affordances agent. The Affordances agent against the stronger baseline on each measure: 7.8× fewer tokens than the screenshot agent (9.2× fewer than the browser agent); 2.5× faster than the browser agent (4.7× faster than the screenshot agent); 4.9× cheaper per success than the screenshot agent (5.8× cheaper than the browser agent).

| Task | Browser tokens | Screenshot tokens | Affordances tokens | Browser time | Screenshot time | Affordances time | Browser passed | Screenshot passed | Affordances passed |
| --- | --: | --: | --: | --: | --: | --: | --: | --: | --: |
| Add to cart | 38,333 | 40,270 | 4,142 | 8.9s | 15.8s | 3.2s | 5/5 | 5/5 | 5/5 |
| Change quantity | 31,358 | 28,927 | 4,354 | 7.4s | 10.6s | 3.4s | 5/5 | 5/5 | 5/5 |
| Checkout | 49,211 | 40,155 | 5,366 | 8.8s | 11.8s | 2.8s | 5/5 | 5/5 | 5/5 |
| Search | 11,015 | 59,318 | 5,138 | 4.1s | 58.0s | 3.6s | 5/5 | 5/5 | 5/5 |
| Order status | 9,225 | 17,515 | 2,194 | 4.3s | 6.1s | 1.5s | 5/5 | 4/5 | 5/5 |
| Two items checkout | 239,475 | 141,793 | 21,501 | 22.7s | 40.4s | 6.5s | 5/5 | 5/5 | 5/5 |
| Edit cart | 268,359 | 143,932 | 17,094 | 22.0s | 43.0s | 5.8s | 5/5 | 5/5 | 5/5 |

Principles

## Three rules it doesn’t bend.

1. ### Signal, not pixels.

   An agent reads names, inputs and preconditions from the graph. No screenshots, no guessing which button does what.

   ```json
   "guard": "The variant is in stock",
   "available": true
   ```

2. ### One source, no drift.

   Every surface reads the same definition, so one edit reaches all of them. There is no second copy to forget.

   ```text
   actions.ts | 2 +-
   → form, WebMCP, HTTP, MCP
   ```

3. ### Agents act, humans approve.

   Actions without expose stay invisible to agents. Mark one confirm, and an agent can prepare it but only a person can finish it.

   ```ts
   expose: 'confirm'
   // ← 409 confirm_required
   ```

**Reading this as an agent?** Skip the pixels: every page here is also Markdown and a graph. Start at [/llms.txt](https://affordances.vercel.app/llms.txt), read this page at [/index.md](https://affordances.vercel.app/index.md), or see [/agents](https://affordances.vercel.app/agents).

```bash
curl -H 'Accept: application/vnd.affordances+json' https://affordances.vercel.app
```

# Start here, agents (https://affordances.vercel.app/agents)

Everything on this site is readable without a browser. Start from llms.txt, read any page as Markdown, or ask the docs for their graph. To make an app agent-operable, hand your agent the prompt below.

[Read llms.txt](https://affordances.vercel.app/llms.txt) [Quickstart](https://affordances.vercel.app/docs/quickstart)

## Set up your agent

Every page on this site is also available as Markdown, and `/llms.txt` indexes them all. Paste this prompt into your agent to point it at the docs:

```text
Help me make this Next.js app agent-operable with Affordances. Start by reading https://affordances.vercel.app/llms.txt, which lists every page of the Affordances docs. Any page is available as Markdown by adding .md to its URL (for example https://affordances.vercel.app/docs/quickstart.md), and https://affordances.vercel.app/llms-full.txt has the whole site in one file.

1. Follow https://affordances.vercel.app/docs/guides/nextjs/getting-started.md: install @affordances/next, @affordances/react, and zod, then run `vlx @affordances/cli init`. It writes the route handler, wraps next.config.ts with withAffordances, and generates the manifest.
2. Next to each page an agent should operate, add a state.ts (what the page shows) and an actions.ts with defineAction. Set `expose` on every action an agent may call, and use 'confirm' for anything that spends money or can't be undone.
3. Check your work with curl -H 'Accept: application/vnd.affordances+json' on the page's URL, and read https://affordances.vercel.app/docs/guides/nextjs/sessions.md and https://affordances.vercel.app/docs/guides/security.md before exposing anything that needs a session.

Only use APIs that appear in the docs.
```

- [llms.txt](/llms.txt): An index of every page on this site, for agents to read before anything else.
- [Markdown pages](/llms-full.txt): Add .md to any page's URL for a plain Markdown copy, or read the whole site in one file.
- [This site’s graph](/docs/quickstart#read-the-graph): These docs run on Affordances: ask / for application/vnd.affordances+json, and search and read pages as actions.
- [MCP](/docs/guides/mcp): Serve any Affordances site to Claude, Cursor, and other MCP clients as two tools.

## Guides

Walkthroughs for the things teams set out to do first.

- [Make a page agent-operable](/docs/quickstart): Init, a state file, an action, and curl.
- [Share your session with agents](/docs/guides/nextjs/sessions): One auth resolver for the UI and the agent path.
- [Ask before an order goes through](/docs/concepts/expose): Confirm actions run only after the person approves.
- [Give browser agents tools](/docs/guides/react): WebMCP tools from the page’s own graph.
- [Connect Claude to your site](/docs/guides/mcp): Two MCP tools over any Affordances site.
- [Guard what agents can do](/docs/concepts/guards): Preconditions agents see before they call.
- [Answer with what changed](/docs/concepts/deltas): Deltas: changed entities, output, and next steps.
- [Catch unmarked controls](/docs/guides/lint): Lint rules for Affordance and action names.

## Concepts

- [Actions](/docs/concepts/actions): One defineAction call describes something a person or an agent can do on a page, and returns the server action that does it.
- [State](/docs/concepts/state): A route's state.ts says what the page shows, as entities. It's loaded for the graph and again after every action.
- [Expose](/docs/concepts/expose): Nothing reaches agents until an action says who may call it: public, session, or confirm.
- [Guards and confirm](/docs/concepts/guards): The precondition an action checks before it runs. Agents see it before they call, and get its reason when it fails.
- [Deltas](/docs/concepts/deltas): Calling an action returns what changed on the page, so the agent doesn't have to read it again.

## Reference

- [Protocol](/docs/reference/protocol): The normative Affordances protocol, version 0: discovery, graphs, calls, deltas, and error codes.
- [Security](/docs/guides/security): Default deny, explicit confirmation, Origin checks for cookies, and a fixed order of checks on every call.
- [Options](/docs/reference/options): Every option of defineAction, createHandler, and withAffordances, in one place.
- [API reference](/docs/reference/api-reference): Every export of every package, with its types, generated from the source.
- [Benchmarks](/docs/benchmarks): A browser agent and an Affordances agent on the same tasks, with committed results.

# Why Affordances (https://affordances.vercel.app/docs)

Agents operate websites by reading pixels and guessing at forms. Affordances gives them the page's state and its actions directly, at the same URL, with the same session.

An agent that wants to add a shirt to a cart today has two options. It can drive a browser: take a screenshot, find the size picker, click it, find the button, click that, and take another screenshot to see whether anything happened. Or it can use an API, if the site has one, which usually means a second set of endpoints with their own auth, their own validation, and their own drift from what the page actually does.

Affordances takes a third path. Every page that opts in answers in two formats at the same URL: HTML for browsers, and a small JSON document for agents. The JSON says what the page shows (entities), what can be done there (actions, each with an input schema and whether it's available right now), and where to go next. Calling an action returns a delta: just the parts of the page that changed.

## One definition

The action a person triggers by clicking a button is the same action an agent calls. You write it once with `defineAction`, next to the page, and it becomes:

- a server action your components call, the same as any other;
- an HTTP endpoint at the page's own URL, for headless agents;
- a WebMCP tool, registered in the browser while the page is open;
- an MCP tool, through `@affordances/mcp`, for Claude, Cursor, and other MCP clients.

There's no second API to keep in sync. If the button changes, the agent sees the change.

## Same URL, same session

Agents don't get a parallel world. A graph is built for whoever asked, with their cookies or their bearer token, so it never contains anything the HTML page wouldn't show the same user. A cart an agent fills is the cart the person sees when they open the page.

## Safe by default

Nothing is reachable by agents until you say so. An action without `expose` stays a plain server action. Actions that spend money or can't be undone use `expose: 'confirm'`, which refuses to run until the caller resends with `confirm: true`, after showing the person a summary. Every agent call is validated, then guarded, then run, in that order. See [Security](https://affordances.vercel.app/docs/guides/security).

## What Affordances is not

- It isn't a browser automation tool. Agents that can't speak Affordances still see your HTML, and `<Affordance>` marks the controls for them.
- It isn't a replacement for your API. It describes pages, so it's shaped like your UI.
- It isn't tied to Next.js. The [protocol](https://affordances.vercel.app/docs/reference/protocol) is plain HTTP and JSON, and `@affordances/core` is framework-agnostic. Next.js is the first adapter.

# Quickstart (https://affordances.vercel.app/docs/quickstart)

Give one page of a Next.js 16 app a graph and an action, then read and call it with curl.

You need a Next.js 16 app using the App Router, and zod 4 (or any schema library that implements Standard Schema and Standard JSON Schema).

## Install and initialize

```bash
vlt install @affordances/next @affordances/react zod
vlx @affordances/cli init
```

`init` does four things, and skips any that are already done:

- writes the route handler at `app/api/affordances/graph/[[...path]]/route.ts` (or under `src/app`);
- wraps the default export of `next.config.ts` with `withAffordances`;
- adds `.affordances` to `.gitignore`;
- generates `.affordances/manifest.ts` from your `actions.ts` and `state.ts` files.

The route handler it writes is one line:

```ts title="app/api/affordances/graph/[[...path]]/route.ts"
export { GET, POST } from '@affordances/next/route'
```

## Wrap the config

If your config's default export isn't a plain identifier, `init` asks you to wrap it yourself:

```ts title="next.config.ts"
import type { NextConfig } from 'next'
import { withAffordances } from '@affordances/next/config'

const nextConfig: NextConfig = {}

export default withAffordances(nextConfig)
```

`withAffordances` regenerates the manifest when Next loads the config, and again in `next dev` whenever an `actions` or `state` file changes. It also adds the rewrites that send agent requests for a page to the route handler. Your pages and their HTML are untouched.

## Describe the page

Affordances reads two files next to a page. `state.ts` returns what the page shows:

```ts title="app/guestbook/state.ts"
import { defineState } from '@affordances/next'
import { entries } from '@/lib/db'

export default defineState(async () => ({
  entries: await entries.list(),
}))
```

`actions.ts` is a regular server actions file. Each `defineAction` export is a server action your components can call, and, because it sets `expose`, an action agents can call too:

```ts title="app/guestbook/actions.ts"
'use server'

import { refresh } from 'next/cache'
import { z } from 'zod'
import { defineAction } from '@affordances/next'
import { entries } from '@/lib/db'
import guestbook from './state'

export const sign = defineAction({
  name: 'sign',
  description: 'Add a message to the guestbook',
  input: z.object({ name: z.string().min(1), message: z.string().max(280) }),
  state: guestbook,
  expose: 'public',
  effects: ['entries'],
  run: async (input, ctx) => {
    await entries.add(input)
    // a form submit re-renders the page; agents get a delta instead
    if (ctx.via === 'ui') refresh()
  },
  message: ({ input }) => `Signed as ${input.name}`,
})
```

Use it in the page like any server action. Wrapping the form in `<Affordance>` marks it for agents that read the DOM:

```tsx title="app/guestbook/page.tsx"
import { Affordance } from '@affordances/react'
import { sign } from './actions'

export default function Page() {
  return (
    <Affordance action={sign}>
      <form action={sign}>
        <input name="name" />
        <textarea name="message" />
        <button>Sign</button>
      </form>
    </Affordance>
  )
}
```

## Add the provider

`<AffordancesProvider>` loads the current page's graph in the browser and registers each available action as a WebMCP tool. Give it the current path, and refresh the server-rendered UI after an agent changes something:

```tsx title="app/agents.tsx"
'use client'

import { usePathname, useRouter } from 'next/navigation'
import { AffordancesProvider } from '@affordances/react'

export const Agents = ({ children }: { children: React.ReactNode }) => {
  const pathname = usePathname()
  const router = useRouter()
  return (
    <AffordancesProvider path={pathname} onDelta={() => router.refresh()}>
      {children}
    </AffordancesProvider>
  )
}
```

Render `<Agents>` around `{children}` in your root layout.

## Read the graph

Start the dev server and ask for the page as an agent would:

```bash
curl -H 'Accept: application/vnd.affordances+json' localhost:3000/guestbook
```

```json
{
  "v": "0",
  "page": "/guestbook",
  "route": "/guestbook",
  "entities": { "entries": [] },
  "actions": [
    {
      "name": "sign",
      "description": "Add a message to the guestbook",
      "input": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "name": { "type": "string", "minLength": 1 },
          "message": { "type": "string", "maxLength": 280 }
        },
        "required": ["name", "message"]
      },
      "expose": "public",
      "available": true,
      "effects": ["entries"]
    }
  ]
}
```

## Call the action

```bash
curl localhost:3000/guestbook \
  -H 'Content-Type: application/vnd.affordances+json' \
  -d '{ "action": "sign", "input": { "name": "Ada", "message": "Hello" } }'
```

```json
{
  "ok": true,
  "changed": { "entries": [{ "name": "Ada", "message": "Hello" }] },
  "message": "Signed as Ada"
}
```

The response is a [delta](https://affordances.vercel.app/docs/concepts/deltas): the new value of each entity the action declared in `effects`, and the message to repeat to the user. `/.well-known/affordances.json` now lists `/guestbook` and its `sign` action.

## Next

- [Actions](https://affordances.vercel.app/docs/concepts/actions) covers every `defineAction` option.
- [Expose](https://affordances.vercel.app/docs/concepts/expose) explains `session` and `confirm`, and [Sessions](https://affordances.vercel.app/docs/guides/nextjs/sessions) shows how to share a session resolver with `createAffordances`.
- [MCP](https://affordances.vercel.app/docs/guides/mcp) connects Claude or Cursor to the site.

# Benchmarks (https://affordances.vercel.app/docs/benchmarks)

How the benchmark compares a browser agent, a screenshot agent and an Affordances agent on the same tasks, and where its results are published.

The bench runs the same tasks against the example store, Acme Store, with three agents, using the same model for all three:

1. a **browser agent** driving Chromium through Playwright, reading each page as an accessibility snapshot (`goto`, `click`, `fill`, `press`). It selects radios and checkboxes with `check()`, as clicking their label would;
2. a **screenshot agent** on Claude's computer use toolset, the way most browser agents work today: a 1280×800 Chromium screen, seen only as screenshots, and acted on by coordinates and keystrokes. Its actions answer OK, and it takes a screenshot when it wants to see. It has the same `goto` and the same session as the browser agent;
3. an **Affordances agent**, headless, whose only tools are `affordances_open` and `affordances_call`, given the site index (every route and action) up front, as an MCP client gets it from `@affordances/mcp`.

Neither baseline ever sees the store's demo-only Agent view toggle. Acme Store is built to read like a real shop: category menus, breadcrumbs, a product gallery, reviews, related products and a footer, rendered accessibly and never padded. Making it read that way changed none of its pages' graphs.

The tasks are the ones a shopper does: find a product and add it to the cart, change a quantity, check out (including the confirm step), search, look up an order, and two longer ones: buy two named items and check out, and make three edits to a cart (swap a variant, change a quantity, add an item). Each run records turns, tool calls, tokens (input, cache reads, cache writes, output), dollar cost, wall time, time to first action, a trace of every tool call, and whether the task succeeded, checked against the store rather than the agent's word. Results are committed as JSON in `apps/bench/results`, one file per model, with the commit they ran against.

## What the numbers say

As of the October 29, 2026 runs, five per task on Claude Opus 5.5 and Claude Haiku 5.5:

- **Nearly every run finishes.** On Opus, all three agents complete every task. On Haiku, the screenshot agent failed one of its five order-status runs; the other two agents completed everything. What Affordances changes here is mostly the cost of finishing.
- **Against the stronger baseline, the Affordances agent uses about eight times fewer tokens.** The headline figures always compare with whichever baseline did better on that measure. Median per task on Opus: 4,093 tokens against the screenshot agent's 34,551 (8.4×) and the browser agent's 47,681 (11.6×); 8.9s against the browser agent's 17.1s (1.9×); $0.019 per successful task against the screenshot agent's $0.097 (5.1×). On Haiku: 7.8× fewer tokens than the screenshot agent, 2.5× faster than the browser agent, and 4.9× cheaper than the screenshot agent.
- **The longer the task, the wider the gap.** Buying two items or editing a cart takes the browser agent 178,000 to 219,000 tokens on Opus, because it re-reads a large snapshot every turn; the screenshot agent about 107,000; the Affordances agent 16,000 to 19,000, in 5 to 7 turns against 10 to 13.
- **The baselines trade places.** The screenshot agent reads fewer tokens than the browser agent on most tasks, but it's the slowest: a median 20.3s on Opus and up to 47s on editing a cart, one screenshot and one coordinate at a time.
- **Search is the browser agent's win on time.** On Opus it answers in 6.9s against the Affordances agent's 7.9s, a results page being cheap to read; it still uses four times the tokens (10,825 against 2,724).

These are five runs per task on one store. Read the per-task medians as a direction, not a precise ratio.

## Results

The newest full run of each model.

### Claude Opus 5.5

Medians of 5 runs per task, run on 2026-10-29 at commit `ff7ddb4`. Cost is per successful run.

Median per run: 47,681 tokens for the browser agent, 34,551 tokens for the screenshot agent, 4,093 tokens for the Affordances agent; 17.1s for the browser agent, 20.3s for the screenshot agent, 8.9s for the Affordances agent; 6 turns for the browser agent, 5 turns for the screenshot agent, 3 turns for the Affordances agent. Cost per successful task: $0.10 for the browser agent, $0.097 for the screenshot agent, $0.019 for the Affordances agent. Tasks completed: 100% for the browser agent, 100% for the screenshot agent, 100% for the Affordances agent. Against the stronger baseline on each measure: 8.4× fewer tokens than the screenshot agent (11.6× fewer than the browser agent); 1.9× faster than the browser agent (2.3× faster than the screenshot agent); 5.1× cheaper per success than the screenshot agent (5.3× cheaper than the browser agent).

| Task               | Agent       | Turns | Tokens  | Time  | Cost    | Passed |
| ------------------ | ----------- | ----- | ------- | ----- | ------- | ------ |
| Add to cart        | Browser     | 6     | 47,681  | 15.9s | $0.087  | 5/5    |
|                    | Screenshot  | 6     | 45,515  | 21.7s | $0.091  | 5/5    |
|                    | Affordances | 3     | 4,093   | 9.2s  | $0.014  | 5/5    |
| Change quantity    | Browser     | 6     | 40,189  | 16.8s | $0.078  | 5/5    |
|                    | Screenshot  | 3     | 16,086  | 10.6s | $0.059  | 5/5    |
|                    | Affordances | 3     | 4,347   | 8.8s  | $0.013  | 5/5    |
| Checkout           | Browser     | 7     | 48,555  | 20.3s | $0.075  | 5/5    |
|                    | Screenshot  | 5     | 34,038  | 17.4s | $0.079  | 5/5    |
|                    | Affordances | 3     | 4,005   | 8.9s  | $0.012  | 5/5    |
| Search             | Browser     | 3     | 10,825  | 6.9s  | $0.037  | 5/5    |
|                    | Screenshot  | 5     | 34,551  | 20.0s | $0.095  | 5/5    |
|                    | Affordances | 2     | 2,724   | 7.9s  | $0.011  | 5/5    |
| Order status       | Browser     | 3     | 9,145   | 10.2s | $0.028  | 5/5    |
|                    | Screenshot  | 3     | 15,982  | 7.3s  | $0.058  | 5/5    |
|                    | Affordances | 2     | 2,189   | 4.0s  | $0.0079 | 5/5    |
| Two items checkout | Browser     | 11    | 177,717 | 21.2s | $0.18   | 5/5    |
|                    | Screenshot  | 10    | 106,845 | 37.6s | $0.15   | 5/5    |
|                    | Affordances | 7     | 19,208  | 15.6s | $0.035  | 5/5    |
| Edit cart          | Browser     | 13    | 219,337 | 24.6s | $0.22   | 5/5    |
|                    | Screenshot  | 10    | 107,192 | 47.3s | $0.15   | 5/5    |
|                    | Affordances | 5     | 16,013  | 15.5s | $0.040  | 5/5    |

Where the tokens go, median per run. Every turn re-reads the conversation so far from the cache, so cache reads grow with each step an agent takes.

| Agent       | Input | Cache read | Cache write | Output |
| ----------- | ----- | ---------- | ----------- | ------ |
| Browser     | 14    | 32,786     | 13,254      | 431    |
| Screenshot  | 12    | 20,169     | 13,714      | 496    |
| Affordances | 8     | 2,287      | 1,641       | 211    |

### Claude Haiku 5.5

Medians of 5 runs per task, run on 2026-10-29 at commit `ff7ddb4`. Cost is per successful run.

Median per run: 47,356 tokens for the browser agent, 40,270 tokens for the screenshot agent, 5,138 tokens for the Affordances agent; 8.8s for the browser agent, 16.5s for the screenshot agent, 3.5s for the Affordances agent; 6 turns for the browser agent, 5 turns for the screenshot agent, 3 turns for the Affordances agent. Cost per successful task: $0.0031 for the browser agent, $0.0026 for the screenshot agent, $0.00053 for the Affordances agent. Tasks completed: 100% for the browser agent, 97% for the screenshot agent, 100% for the Affordances agent. Against the stronger baseline on each measure: 7.8× fewer tokens than the screenshot agent (9.2× fewer than the browser agent); 2.5× faster than the browser agent (4.7× faster than the screenshot agent); 4.9× cheaper per success than the screenshot agent (5.8× cheaper than the browser agent).

| Task               | Agent       | Turns | Tokens  | Time  | Cost     | Passed |
| ------------------ | ----------- | ----- | ------- | ----- | -------- | ------ |
| Add to cart        | Browser     | 5     | 38,333  | 8.9s  | $0.0022  | 5/5    |
|                    | Screenshot  | 5     | 40,270  | 15.8s | $0.0018  | 5/5    |
|                    | Affordances | 3     | 4,142   | 3.2s  | $0.00031 | 5/5    |
| Change quantity    | Browser     | 5     | 31,358  | 7.4s  | $0.0017  | 5/5    |
|                    | Screenshot  | 4     | 28,927  | 10.6s | $0.0017  | 5/5    |
|                    | Affordances | 3     | 4,354   | 3.4s  | $0.00023 | 5/5    |
| Checkout           | Browser     | 7     | 49,211  | 8.8s  | $0.0018  | 5/5    |
|                    | Screenshot  | 5     | 40,155  | 11.8s | $0.0016  | 5/5    |
|                    | Affordances | 3     | 5,366   | 2.8s  | $0.00041 | 5/5    |
| Search             | Browser     | 3     | 11,015  | 4.1s  | $0.00076 | 5/5    |
|                    | Screenshot  | 7     | 59,318  | 58.0s | $0.0023  | 5/5    |
|                    | Affordances | 3     | 5,138   | 3.6s  | $0.00032 | 5/5    |
| Order status       | Browser     | 3     | 9,225   | 4.3s  | $0.00051 | 5/5    |
|                    | Screenshot  | 3     | 17,515  | 6.1s  | $0.0015  | 4/5    |
|                    | Affordances | 2     | 2,194   | 1.5s  | $0.00014 | 5/5    |
| Two items checkout | Browser     | 12    | 239,475 | 22.7s | $0.0066  | 5/5    |
|                    | Screenshot  | 11    | 141,793 | 40.4s | $0.0044  | 5/5    |
|                    | Affordances | 7     | 21,501  | 6.5s  | $0.0011  | 5/5    |
| Edit cart          | Browser     | 13    | 268,359 | 22.0s | $0.0079  | 5/5    |
|                    | Screenshot  | 11    | 143,932 | 43.0s | $0.0045  | 5/5    |
|                    | Affordances | 5     | 17,094  | 5.8s  | $0.0012  | 5/5    |

Where the tokens go, median per run. Every turn re-reads the conversation so far from the cache, so cache reads grow with each step an agent takes.

| Agent       | Input | Cache read | Cache write | Output |
| ----------- | ----- | ---------- | ----------- | ------ |
| Browser     | 14    | 31,722     | 11,021      | 571    |
| Screenshot  | 12    | 36,541     | 12,650      | 555    |
| Affordances | 8     | 3,752      | 1,529       | 316    |

## Run history

Every committed results file, newest first, with each agent's median tokens per run; a dash means the run didn't have that agent. A partial run re-ran some of the tasks (`--tasks`) and isn't used above.

| Finished                                                                                                                                                                             | Model     | Tasks × runs      | Commit  | Browser | Screenshot | Affordances |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ----------------- | ------- | ------- | ---------- | ----------- |
| [10-29 23:43](https://github.com/vltpkg/affordances/blob/main/apps/bench/results/2026-10-29T2343-claude-haiku-5-5.json)                                                              | Haiku 5.5 | All 7 × 5         | ff7ddb4 | 47,356  | 40,270     | 5,138       |
| [10-29 23:16](https://github.com/vltpkg/affordances/blob/main/apps/bench/results/2026-10-29T2316-claude-opus-5-5.json)                                                               | Opus 5.5  | All 7 × 5         | ff7ddb4 | 47,681  | 34,551     | 4,093       |
| Earlier runs used the simpler store and five tasks, without the screenshot agent; see [changes to the method](https://affordances.vercel.app/docs/benchmarks#changes-to-the-method). |           |                   |         |         |            |             |
| [10-29 21:22](https://github.com/vltpkg/affordances/blob/main/apps/bench/results/2026-10-29T2122-claude-haiku-5-5.json)                                                              | Haiku 5.5 | All 5 × 5         | e9bd8bd | 11,977  | –          | 5,077       |
| [10-29 21:18](https://github.com/vltpkg/affordances/blob/main/apps/bench/results/2026-10-29T2118-claude-opus-5-5.json)                                                               | Opus 5.5  | All 5 × 5         | e9bd8bd | 15,600  | –          | 4,006       |
| Earlier runs measured the browser agent before its fixes; see [changes to the method](https://affordances.vercel.app/docs/benchmarks#changes-to-the-method).                         |           |                   |         |         |            |             |
| [10-29 18:16](https://github.com/vltpkg/affordances/blob/main/apps/bench/results/2026-10-29T1816-claude-opus-5-5.json)                                                               | Opus 5.5  | All 5 × 5         | 1543f36 | 17,992  | –          | 3,985       |
| [10-29 18:13](https://github.com/vltpkg/affordances/blob/main/apps/bench/results/2026-10-29T1813-claude-haiku-5-5.json)                                                              | Haiku 5.5 | All 5 × 5         | 1543f36 | 16,834  | –          | 5,096       |
| [10-29 18:04](https://github.com/vltpkg/affordances/blob/main/apps/bench/results/2026-10-29-claude-opus-5-5-search.json)                                                             | Opus 5.5  | Search × 5partial | 787f51c | 4,982   | –          | 2,690       |
| [10-29 17:40](https://github.com/vltpkg/affordances/blob/main/apps/bench/results/2026-10-29-claude-opus-5-5.json)                                                                    | Opus 5.5  | All 5 × 5         | 6626064 | 14,979  | –          | 5,072       |
| [10-29 17:39](https://github.com/vltpkg/affordances/blob/main/apps/bench/results/2026-10-29-claude-haiku-5-5.json)                                                                   | Haiku 5.5 | All 5 × 5         | 6626064 | 16,811  | –          | 5,723       |
| [10-29](https://github.com/vltpkg/affordances/blob/main/apps/bench/results/2026-10-29.json)                                                                                          | Opus 5.5  | All 5 × 5         | –       | 14,931  | –          | 5,487       |

## Changes to the method

**October 29, 2026, later that day: a realistic store, longer tasks, and a screenshot agent.** The store was unusually minimal, which flattered the browser agent. It now has what typical stores have (category menus, breadcrumbs, a gallery, reviews, related products, a footer), and its accessibility snapshots grew 2.9 to 6.4 times: a product page went from 1,151 to 7,313 characters, still lighter than most real stores. No page's graph changed with it; every one is byte-identical. Two longer tasks joined the five, and the screenshot agent joined as a second baseline. One change helps the Affordances agent: `search` now returns each result's variants with their SKUs, so adding to the cart is a search and an `addToCart`, three turns instead of four. Runs before this are marked in the history above; compare them only with each other.

**October 29, 2026: a fairer browser agent.** The store's size options are styled radios: a visually hidden input under its label, which takes the pointer. Every click the browser agent made on one waited 5 seconds and failed, which made up most of the add-to-cart gap and was why it failed add-to-cart on Haiku. It also kept clicking the store's Agent view toggle, a demo control no real store has, which put the page's graph in its snapshot. It now selects radios and checkboxes with `check()`, as clicking their label would, and the toggle is hidden from it. Runs before this change are marked in the history above; compare them only with each other.

# Concepts (https://affordances.vercel.app/docs/concepts)

The few ideas Affordances is built on. A page says what it shows and what can be done there, once, for people and agents alike.

An Affordances page has two files next to it. `state.ts` says what the page shows, and `actions.ts` says what can be done there. Everything an agent sees is derived from those two files.

- [**Actions**](https://affordances.vercel.app/docs/concepts/actions): one `defineAction` call describes something a person or an agent can do on a page, and returns the server action that does it.
- [**State**](https://affordances.vercel.app/docs/concepts/state): a route's `state.ts` says what the page shows, as entities. It's loaded for the graph and again after every action.
- [**Expose**](https://affordances.vercel.app/docs/concepts/expose): nothing reaches agents until an action says who may call it. `expose` is `public`, `session`, or `confirm`.
- [**Guards and confirm**](https://affordances.vercel.app/docs/concepts/guards): a guard is the precondition an action checks before it runs. Agents see it before they call, and get its reason when it fails.
- [**Deltas**](https://affordances.vercel.app/docs/concepts/deltas): calling an action returns what changed on the page, so the agent doesn't have to read it again.
- [**Plugins**](https://affordances.vercel.app/docs/concepts/plugins): a plugin serves the same pages in another form, such as Markdown, at the same URLs and from the same render. The [Plugins](https://affordances.vercel.app/docs/plugins) section lists each one.

# Actions (https://affordances.vercel.app/docs/concepts/actions)

One defineAction call describes something a person or an agent can do on a page, and returns the server action that does it.

An action is a named operation on a page, with a typed input. You define it in the route's `actions.ts`, which must start with `'use server'`:

```ts title="app/products/[slug]/actions.ts"
'use server'

import { z } from 'zod'
import { defineAction } from '@/lib/affordances'
import * as cart from '@/lib/cart'
import product from './state'

export const addToCart = defineAction({
  name: 'addToCart',
  description: 'Add a product variant to the cart',
  input: z.object({ sku: z.string(), quantity: z.number().int().min(1).default(1) }),
  state: product,
  expose: 'session',
  requires: 'The variant is in stock',
  guard: ({ input, state }) =>
    !input ||
    state.product.variants.some((v) => v.sku === input.sku && v.stock > 0) ||
    'That variant is sold out',
  effects: ['cart'],
  run: (input, ctx) => cart.add(ctx.session!.id, input),
  message: ({ input }) => `Added ${input.sku} to your cart`,
})
```

`defineAction` returns an async function: a valid server action. Pass it to `<form action>`, call it from a client component, or use it with `useActionState`. It accepts a plain object, a `FormData`, or `(previousState, FormData)`, and validates the input against the schema before `run` sees it.

The same export carries the action's metadata. Codegen finds it by its `name`, which must be a string literal, and the route handler uses it to describe and run the action for agents.

## What agents see

Each exposed action appears in the page's graph as a descriptor:

```json
{
  "name": "addToCart",
  "description": "Add a product variant to the cart",
  "input": { "type": "object", "properties": { "sku": { "type": "string" } } },
  "expose": "session",
  "guard": "The variant is in stock",
  "available": true,
  "effects": ["cart"]
}
```

- `input` is the JSON Schema of `input`, produced through Standard JSON Schema. Zod 4 implements it. For a library that doesn't, pass `jsonSchema`.
- `guard` is your `requires` text. `available` is the result of running `guard` for this request, and `reason` explains a `false`.
- `output` appears when you pass an `output` schema, and `readOnly` when you set `readOnly: true`.

## Context

`run` and `guard` receive a context:

| Property  | Type              | Description                                                                       |
| --------- | ----------------- | --------------------------------------------------------------------------------- |
| `session` | `Session \| null` | What your `auth` resolver returned. Assignable, so an action can start a session. |
| `request` | `Request`         | The incoming request, when there is one                                           |
| `via`     | `'ui' \| 'agent'` | `'ui'` when a component called the server action, `'agent'` when the handler did  |

An action that starts a session, such as an anonymous cart, assigns `ctx.session`. The handler reloads the page's state with the same context after `run`, so the new session's data shows up in the delta:

```ts
run: async ({ sku, quantity }, ctx) => {
  ctx.session ??= { id: await startSession() }
  cart.add(ctx.session.id, sku, quantity)
},
```

## Redirects

Throw `redirect(path)` from `@affordances/next` to send the caller somewhere when the action finishes. A person's browser navigates there; an agent gets it as the delta's `redirect`. Next's own `redirect()` from `next/navigation` works too.

## Errors

Throw an `AffordancesError` to answer with a specific protocol error:

```ts
import { AffordancesError } from '@affordances/next'

throw new AffordancesError('unavailable', 'The sale has ended')
```

Any other error becomes `internal`, with a generic message, so stack traces and secrets don't reach agents.

## Options

The full list is in [Options](https://affordances.vercel.app/docs/reference/options#defineaction), and every signature in the [API reference](https://affordances.vercel.app/docs/reference/api-reference/core).

# State (https://affordances.vercel.app/docs/concepts/state)

A route's state.ts says what the page shows, as entities. It's loaded for the graph and again after every action.

`state.ts` sits next to a page and default-exports `defineState(loader)`. The loader returns the page's entities: plain, JSON-serializable data, keyed by name.

```ts title="app/products/[slug]/state.ts"
import { defineState } from '@/lib/affordances'
import { getProduct } from '@/lib/catalog'
import { getCart } from '@/lib/cart'

export default defineState(
  async ({ params, ctx }) => ({
    product: await getProduct(params.slug as string),
    cart: await getCart(ctx.session),
  }),
  { nav: ({ cart }) => (cart.count > 0 ? [{ to: '/checkout', label: 'Checkout' }] : []) },
)
```

The loader receives:

| Argument       | Type                                 | Description                                                                                           |
| -------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `params`       | `Record<string, string \| string[]>` | The route's dynamic segments, as Next names them                                                      |
| `searchParams` | `URLSearchParams`                    | The page's query string, without `affordances`                                                        |
| `ctx`          | `Ctx`                                | The caller's session and request; see [Actions](https://affordances.vercel.app/docs/concepts/actions) |

The optional `nav` function turns the loaded state into links an agent can follow. A link's `when` is a human-readable condition, like `"cart.count > 0"`.

## When it runs

The handler loads state for three things:

1. Building the graph for a `GET`.
2. Evaluating the guard before an action runs.
3. Reloading after the action ran, to compute the delta.

So the loader should be cheap, and it must use the context it's given. A loader that reads the session from somewhere else won't see a session an action just started.

## Keep it small

Entities are what the page shows the same user, not everything you know. Agents read the graph as tokens, so about 2,000 tokens is a good ceiling. Summarize long lists (a count and the first page, say) rather than sending them whole.

## Typing actions against state

Pass the state to an action's `state` option. Its `guard` and `summary` then receive the loaded entities with their types, and `effects` only accepts entity names that exist:

```ts
import product from './state'

defineAction({
  // …
  state: product,
  effects: ['cart'], // 'cart' must be a key of the state
})
```

# Expose (https://affordances.vercel.app/docs/concepts/expose)

Nothing reaches agents until an action says who may call it. expose is public, session, or confirm.

`expose` decides whether an action is part of the protocol and who may call it. Without it, an action is an ordinary server action: it doesn't appear in graphs, the handler answers `not_found` for it, and `defineAction` warns in development.

| `expose`  | Who may call it                                                                     |
| --------- | ----------------------------------------------------------------------------------- |
| `public`  | Anyone                                                                              |
| `session` | A caller with a session, by cookie or bearer token                                  |
| `confirm` | A caller with a session, and only with `confirm: true` after the person approved it |

## Sessions

A session is whatever your `auth` resolver returns for a request. Define it once with `createAffordances`, and both the UI path and the agent path use it:

```ts title="lib/affordances.ts"
import { createAffordances } from '@affordances/next'
import { sessionFrom } from '@/lib/auth'

export const { defineAction, defineState } = createAffordances({
  auth: (request) => sessionFrom(request),
})
```

The resolver gets a `Request`. For agent calls, it's the real request, with its cookies and `Authorization` header. For server actions called from your UI, `@affordances/next` builds one from `headers()`.

Actions that need a session are still listed for callers without one, as `available: false` with the reason `Requires a session`. Calling one answers `unauthorized`.

## Confirm

Use `confirm` for anything a person should approve: placing an order, sending a message, deleting data. The first call doesn't run anything. It answers `confirm_required` with a summary:

```json
{
  "ok": false,
  "error": {
    "code": "confirm_required",
    "message": "Order 2 items for $96.00. Resend with confirm: true once the user approves."
  }
}
```

The summary comes from the action's `summary` option, and the agent should show it to the person before resending the same call with `"confirm": true`. `@affordances/react` does this for WebMCP tools, with `window.confirm` unless you pass your own `confirm`. `@affordances/mcp` tells the model to do the same.

```ts
export const placeOrder = defineAction({
  name: 'placeOrder',
  description: 'Place the order for everything in the cart',
  input: z.object({}),
  state: checkout,
  expose: 'confirm',
  guard: ({ state }) => state.cart.count > 0 || 'Your cart is empty',
  summary: ({ state }) => `Order ${state.cart.count} items for ${format(state.cart.total)}`,
  run: (_, ctx) => orders.place(ctx.session!.id),
})
```

`confirm` is a protocol rule, not a promise about the agent. A client can send `confirm: true` without asking anyone. It stops agents from running consequential actions by accident; it doesn't replace authorization.

# Guards and confirm (https://affordances.vercel.app/docs/concepts/guards)

A guard is the precondition an action checks before it runs. Agents see it before they call, and get its reason when it fails.

A guard is a function that returns `true` when the action may run, or a string saying why it can't:

```ts
defineAction({
  name: 'addToCart',
  // …
  requires: 'The variant is in stock',
  guard: ({ input, state }) => {
    if (!input) return state.product.variants.some((v) => v.stock > 0) || 'Sold out'
    const variant = state.product.variants.find((v) => v.sku === input.sku)
    return (variant && variant.stock > 0) || `${input.sku} is out of stock`
  },
})
```

`requires` is the human-readable version, shown in the graph as the descriptor's `guard`. The function is what's enforced.

## Two calls

The handler calls the guard twice in an action's life:

- **Building the graph**, with `input` undefined. The result becomes `available` and `reason`, so an agent knows what it can do before it tries. Return `true` here unless the action is unavailable whatever the input.
- **Handling a call**, with the validated input and freshly loaded state. A failure answers `unavailable`, with the guard's string as the message.

A guard may also return `false`, which fails without a reason. Prefer a sentence the agent can pass on.

## Order

Every agent call goes through the same steps, and stops at the first failure:

1. Find the action on the page's route: `not_found`.
2. Check the Origin of cookie-authenticated calls, and `expose`: `unauthorized`.
3. Apply the rate limit: `rate_limited`.
4. Validate the input: `invalid_input`, with the schema's issues.
5. Run the guard: `unavailable`.
6. For `confirm` actions without `confirm: true`: `confirm_required`, with the summary.
7. Run the action, reload state, and answer with a delta.

Input is always valid by the time the guard sees it, and the action never runs before the guard passes.

## The UI path

When your own components call the server action, it validates the input and runs. It doesn't evaluate `guard` or check `expose`: those protect the agent path, and your UI already decides what to render. If a check must hold for people too, such as stock at the moment of purchase, enforce it inside `run` as well.

# Deltas (https://affordances.vercel.app/docs/concepts/deltas)

Calling an action returns what changed on the page, so the agent doesn't have to read it again.

After an action runs, the handler reloads the page's state and compares it with the state from before. The response is a delta:

```json
{
  "ok": true,
  "changed": { "cart": { "count": 2, "subtotal": { "amount": 6000, "currency": "USD" } } },
  "message": "Added Heavyweight Tee (M) to your cart"
}
```

| Field            | Present when                                                                                                      |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `changed`        | Some entity changed. With `effects`, it holds those keys; without, the diff                                       |
| `output`         | `run` returned something other than `undefined`                                                                   |
| `actionsAdded`   | An action appeared, or its descriptor changed (for example, `available` flipped)                                  |
| `actionsRemoved` | An action is no longer listed                                                                                     |
| `redirect`       | The action redirected; the agent should request this path next                                                    |
| `message`        | The action has a `message` option                                                                                 |
| `error`          | `ok` is `false`; see the [protocol](https://affordances.vercel.app/docs/reference/protocol#error-codes) for codes |

## Effects

`effects` lists the entities an action changes. When it's set, `changed` holds the new value of exactly those entities, whether or not they differ. When it's omitted, the handler compares every top-level entity and includes the ones whose JSON changed.

Declaring effects is cheaper to reason about and tells agents in advance what an action touches, since `effects` is part of the descriptor.

## Availability

Deltas carry action changes too. Adding the first item to a cart can make `checkout` available; placing the order makes it unavailable again. The descriptor in `actionsAdded` is the new one, with its `available` and `reason`, so the agent's picture of the page stays current without another `GET`.

## Messages

`message` is a short sentence an agent can repeat to the person:

```ts
message: ({ input, output }) => `Added ${input.quantity} × ${output.name} to the cart`,
```

# Plugins (https://affordances.vercel.app/docs/concepts/plugins)

A plugin serves an Affordances app's pages in another form for agents, at the same URLs, from the same render. What they are and how they fit together.

The graph is one way for an agent to read a page: its entities and actions, as JSON. Not every agent speaks it. Some read Markdown, some want the whole site in one file. A plugin adds one of those forms to the app, without a second copy of your content.

## What a plugin is

A plugin is two pieces:

- **A config wrapper.** It takes your Next config and returns it with its own rewrites and headers added. You pass it to `withAffordances` in `plugins`.
- **A route handler** under `/api/affordances/<name>`. The rewrites send the requests the plugin is for to it.

The Markdown plugin is `md()` in the config and one line at `app/api/affordances/md/[[...path]]/route.ts`.

## Same URLs, different requests

Every form of a page lives at the page's own URL. Which one a client gets depends on what it asks for:

| Request                                    | Answered by          |
| ------------------------------------------ | -------------------- |
| A browser asking for HTML                  | Your page, unchanged |
| `Accept: application/vnd.affordances+json` | The graph            |
| `Accept: text/markdown`, or `/page.md`     | The Markdown plugin  |

Each plugin matches only its own requests, so plugins and the graph never answer for each other, and a person's request never reaches any of them.

## One source of truth

A plugin derives what it serves from what the app already has. The Markdown plugin requests the page's HTML from your own app, the way a browser would, and converts it. So the Markdown says whatever the page renders, including server data and streamed content, and there's nothing to keep in sync.

## Order and independence

- Plugins apply in the order you list them, after the graph's rewrites.
- A plugin doesn't need the graph. `@affordances/md` also works on its own, with `withMd(nextConfig)` instead of `withAffordances`.

## Next

- [Plugins](https://affordances.vercel.app/docs/plugins) lists each plugin and how to add it.
- [Plugins in the Next.js guide](https://affordances.vercel.app/docs/guides/nextjs/plugins) covers the config in detail, and writing your own.

# Guides (https://affordances.vercel.app/docs/guides)

How to wire Affordances into a Next.js app, a React tree, an MCP client, and your lint setup, and how to keep them secure.

Each guide covers one package or one surface. New to Affordances? Start with [Getting started](https://affordances.vercel.app/docs/guides/nextjs/getting-started).

- [**Next.js**](https://affordances.vercel.app/docs/guides/nextjs): set up an existing app with an agent or by hand, then how files, routing, route handlers, plugins, and sessions work.
- [**React and WebMCP**](https://affordances.vercel.app/docs/guides/react): `AffordancesProvider` turns the current page's actions into WebMCP tools for browser agents. `Affordance` marks the controls in the DOM.
- [**MCP**](https://affordances.vercel.app/docs/guides/mcp): `@affordances/mcp` turns any Affordances site into two MCP tools, for Claude, Cursor, and other MCP clients.
- [**Lint**](https://affordances.vercel.app/docs/guides/lint): two rules that keep the manifest buildable and every server-action control visible to agents.
- [**Security**](https://affordances.vercel.app/docs/guides/security): default deny, explicit confirmation, Origin checks for cookies, and a fixed order of checks on every agent call.

# Next.js (https://affordances.vercel.app/docs/guides/nextjs)

@affordances/next makes a Next.js App Router app agent-operable: it finds your actions, routes agent requests to them, and shares your session.

`@affordances/next` connects Affordances to the App Router. You write a `state.ts` and an `actions.ts` next to a page. The package then does three things:

- **Finds them.** Codegen reads those files at build time and writes a manifest of every route's state and actions.
- **Routes agents to them.** `withAffordances` adds rewrites, so an agent asking for a page's graph, or calling one of its actions, reaches the Affordances route handler at the same URL a person visits.
- **Shares your session.** `createAffordances({ auth })` resolves the same session for a form submit and an agent's call.

## Entry points

| Import                     | What it's for                                                                                                        |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `@affordances/next`        | `defineAction`, `defineState`, `createAffordances`, `redirect`, `AffordancesError`                                   |
| `@affordances/next/config` | `withAffordances`, for `next.config.ts`                                                                              |
| `@affordances/next/route`  | `createRouteHandler`, for the route handler                                                                          |
| `@affordances/cli`         | `affordances init` and `build`, plus `open` and `call`; see [CLI](https://affordances.vercel.app/docs/reference/cli) |

## In this guide

- [Getting started](https://affordances.vercel.app/docs/guides/nextjs/getting-started): set up an existing app, with an agent or by hand.
- [Files and conventions](https://affordances.vercel.app/docs/guides/nextjs/conventions): where `state.ts` and `actions.ts` go, and what codegen checks.
- [Routing](https://affordances.vercel.app/docs/guides/nextjs/routing): how one URL answers people and agents, and what's cached.
- [Route handlers](https://affordances.vercel.app/docs/guides/nextjs/route-handlers): the graph handler, its options, and the routes plugins add.
- [Plugins](https://affordances.vercel.app/docs/guides/nextjs/plugins): more capabilities on the same config, and how to write one.
- [Sessions](https://affordances.vercel.app/docs/guides/nextjs/sessions): one session resolver for the UI and for agents.

# Getting started (https://affordances.vercel.app/docs/guides/nextjs/getting-started)

Add Affordances to an existing Next.js app, either by handing your coding agent a prompt or by following the steps yourself.

You need a Next.js 16 app using the App Router, and zod 4 (or any schema library that implements Standard Schema and Standard JSON Schema). There are two ways to set it up.

## With an agent

Paste this prompt into Claude Code, Cursor, or any coding agent. It points the agent at these docs as Markdown and tells it what to build:

```text
Help me make this Next.js app agent-operable with Affordances. Start by reading https://affordances.vercel.app/llms.txt, which lists every page of the Affordances docs. Any page is available as Markdown by adding .md to its URL (for example https://affordances.vercel.app/docs/quickstart.md), and https://affordances.vercel.app/llms-full.txt has the whole site in one file.

1. Follow https://affordances.vercel.app/docs/guides/nextjs/getting-started.md: install @affordances/next, @affordances/react, and zod, then run `vlx @affordances/cli init`. It writes the route handler, wraps next.config.ts with withAffordances, and generates the manifest.
2. Next to each page an agent should operate, add a state.ts (what the page shows) and an actions.ts with defineAction. Set `expose` on every action an agent may call, and use 'confirm' for anything that spends money or can't be undone.
3. Check your work with curl -H 'Accept: application/vnd.affordances+json' on the page's URL, and read https://affordances.vercel.app/docs/guides/nextjs/sessions.md and https://affordances.vercel.app/docs/guides/security.md before exposing anything that needs a session.

Only use APIs that appear in the docs.
```

When it's done, check its work the same way you would your own: [read a graph with curl](https://affordances.vercel.app/docs/guides/nextjs/getting-started#7-check-it).

## By hand

The steps below set up one page. `init` does steps 2 to 4 for you; they're spelled out so you know what it changed.

### 1. Install

```bash
vlt install @affordances/next @affordances/react zod
```

### 2. Wrap the config

`withAffordances` generates the manifest and adds the rewrites that send agent requests to the route handler. Your pages and their HTML are untouched.

```ts title="next.config.ts"
import type { NextConfig } from 'next'
import { withAffordances } from '@affordances/next/config'

const nextConfig: NextConfig = {}

export default withAffordances(nextConfig, { name: 'My app' })
```

`name` is what agents see in `/.well-known/affordances.json`.

### 3. Add the route handler

Every agent request ends up here. It's one line, in `app/` or `src/app/`:

```ts title="app/api/affordances/graph/[[...path]]/route.ts"
export { GET, POST } from '@affordances/next/route'
```

The handler finds the generated manifest on its own: `withAffordances` points it there.

[Route handlers](https://affordances.vercel.app/docs/guides/nextjs/route-handlers) covers its options.

### 4. Ignore the manifest

`withAffordances` writes `.affordances/manifest.ts` every time Next loads the config, and again in `next dev` when an `actions` or `state` file changes. It's generated, so leave it out of git:

```text title=".gitignore"
.affordances
```

Or skip steps 2 to 4 and let `init` do them:

```bash
vlx @affordances/cli init
```

### 5. Describe a page

Next to a page, `state.ts` returns what the page shows, and `actions.ts` defines what can be done on it:

```ts title="app/guestbook/state.ts"
import { defineState } from '@affordances/next'
import { entries } from '@/lib/db'

export default defineState(async () => ({ entries: await entries.list() }))
```

```ts title="app/guestbook/actions.ts"
'use server'

import { z } from 'zod'
import { defineAction } from '@affordances/next'
import { entries } from '@/lib/db'
import guestbook from './state'

export const sign = defineAction({
  name: 'sign',
  description: 'Add a message to the guestbook',
  input: z.object({ name: z.string().min(1), message: z.string().max(280) }),
  state: guestbook,
  expose: 'public',
  effects: ['entries'],
  run: (input) => entries.add(input),
})
```

`sign` is still a server action, so the page uses it like any other.

### 6. Mark the controls

Wrap the control a person uses for an action in `<Affordance>`, so agents that read the DOM, and the devtools, know which button does what:

```tsx title="app/guestbook/page.tsx"
import { Affordance } from '@affordances/react'
import { sign } from './actions'

export default function Page() {
  return (
    <form>
      <input name="name" />
      <textarea name="message" />
      <Affordance action={sign}>
        <button formAction={sign}>Sign</button>
      </Affordance>
    </form>
  )
}
```

`<Affordance>` renders no box of its own (`display: contents`) and changes nothing about the button. It adds `data-affordances-action="sign"` around it. The button carries the action with `formAction`, so what's marked is exactly what submits.

When the whole form is the control, wrap the form instead. Pass `input` for values the control already fixes, such as the product a button adds:

```tsx
<Affordance action={addToCart} input={{ sku: variant.sku }}>
  <form action={addToCart}>
    <button>Add to cart</button>
  </form>
</Affordance>
```

In a client component, pass `name="sign"` instead of `action`: there, a server action arrives without the metadata `<Affordance>` reads its name from. The [`require-affordance`](https://affordances.vercel.app/docs/guides/lint#require-affordance) lint rule warns about any control that calls a server action outside an `<Affordance>`, and [React and WebMCP](https://affordances.vercel.app/docs/guides/react) adds the provider that turns these actions into browser tools.

### 7. Check it

Start the dev server and ask for the page as an agent would:

```bash
curl -H 'Accept: application/vnd.affordances+json' localhost:3000/guestbook
```

The response is the page's [graph](https://affordances.vercel.app/docs/concepts/state): its entities and the `sign` action with its input schema. Call the action at the same URL:

```bash
curl localhost:3000/guestbook \
  -H 'Content-Type: application/vnd.affordances+json' \
  -d '{ "action": "sign", "input": { "name": "Ada", "message": "Hello" } }'
```

The response is a [delta](https://affordances.vercel.app/docs/concepts/deltas) with the new `entries`.

The [CLI](https://affordances.vercel.app/docs/reference/cli) does both with a readable summary, including roughly how many tokens the page costs an agent:

```bash
vlx @affordances/cli open localhost:3000/guestbook
vlx @affordances/cli call localhost:3000/guestbook sign --input '{"name":"Ada","message":"Hello"}'
```

## Next

- [Sessions](https://affordances.vercel.app/docs/guides/nextjs/sessions): let agents act as the signed-in user.
- [Expose](https://affordances.vercel.app/docs/concepts/expose): choose who may call each action, and which need a person's approval.
- [MCP](https://affordances.vercel.app/docs/guides/mcp): connect Claude or Cursor to the app.

# Files and conventions (https://affordances.vercel.app/docs/guides/nextjs/conventions)

Where state.ts and actions.ts go, how they map to routes, and what codegen checks before it writes the manifest.

Put `state.ts` and `actions.ts` next to the `page.tsx` they describe:

```text
app/
  page.tsx
  state.ts            → /
  actions.ts          → /
  (shop)/products/[slug]/
    page.tsx
    state.ts          → /products/[slug]
    actions.ts        → /products/[slug]
  api/affordances/graph/[[...path]]/
    route.ts          (the route handler)
```

- Route groups like `(shop)` and parallel slots like `@modal` don't appear in the route.
- Folders starting with `_` are skipped.
- A route can have state without actions, or actions without state.
- Dynamic segments work as they do in Next: `[slug]`, `[...slug]`, and `[[...slug]]`.

## The manifest

Codegen reads these files statically, without running them, and writes `.affordances/manifest.ts`. It imports each route's state and actions, and the route handler reads it.

It's regenerated:

- whenever Next loads the config (`withAffordances` runs it);
- in `next dev`, whenever an `actions` or `state` file changes;
- when you run `affordances build`, for scripts and CI.

Commit it or not, as you like. `affordances init` adds `.affordances` to `.gitignore`.

## What fails the build

Codegen stops with an error when:

- an `actions` file doesn't start with `'use server'`;
- a `defineAction` call's `name` isn't a string literal;
- two actions on one route share a name;
- a `state` file has no default export.

The [lint rules](https://affordances.vercel.app/docs/guides/lint) catch the first two in your editor.

# Routing (https://affordances.vercel.app/docs/guides/nextjs/routing)

How the same URL answers people with HTML and agents with a graph, how agents discover it, and why graphs are never cached.

The same URL answers people and agents. `withAffordances` adds rewrites that run before Next's filesystem routes, and send a request to the route handler when it has any of:

- `Accept: application/vnd.affordances+json` (reading a graph);
- `Content-Type: application/vnd.affordances+json` (calling an action);
- the query parameter `affordances=1`, for clients that can't set headers.

`/.well-known/affordances.json`, the [site index](https://affordances.vercel.app/docs/reference/protocol), is rewritten to the handler too.

## What's left alone

- Every browser request for HTML reaches your pages as before.
- Requests to `/api/` routes, the handler's own included, and to `/_next` are never rewritten.
- Your own rewrites are kept. `withAffordances` puts its rules first in `beforeFiles` and leaves the rest where they were.

## Discovery

For each route in the manifest, `withAffordances` adds a header to the HTML response, so a client that loaded the page can find its graph:

```http
Link: <?affordances=1>; rel="affordances"
```

## Caching

Graphs and deltas are sent with `Cache-Control: private, no-store` and `Vary: Accept`. HTML responses keep whatever caching they had.

Agent requests are rewritten to the handler before the filesystem and before any cached page. So a cached HTML page is never served to an agent, and a graph is never cached at all.

# Route handlers (https://affordances.vercel.app/docs/guides/nextjs/route-handlers)

The graph route handler that answers every agent request, its options, and the routes plugins add under /api/affordances.

Affordances answers agents from route handlers under `/api/affordances/`. The graph's is at `/api/affordances/graph`, and each [plugin](https://affordances.vercel.app/docs/guides/nextjs/plugins) owns its own `/api/affordances/<name>`. Rewrites send agent requests there, so agents never see these paths.

## The graph handler

One line answers both reading a graph (`GET`) and calling an action (`POST`):

```ts title="app/api/affordances/graph/[[...path]]/route.ts"
export { GET, POST } from '@affordances/next/route'
```

It must live at that path, in `app/` or `src/app/`, because the rewrites point there. The catch-all `[[...path]]` receives the page path the agent asked for.

The handler reads the manifest from `@affordances/next/manifest`. `withAffordances` aliases that import to your app's `.affordances/manifest.ts`, so there's no relative path to keep right. If the config isn't wrapped, the first agent request fails with an error that says so.

## Options

To pass options, call `createRouteHandler` and export the handler as both methods. It takes the [handler options](https://affordances.vercel.app/docs/reference/options#createhandler), except `basePath`, which it sets:

```ts title="app/api/affordances/graph/[[...path]]/route.ts"
import { createRouteHandler } from '@affordances/next/route'

const handler = createRouteHandler({
  // true allows the call; a number of seconds answers rate_limited with Retry-After
  rateLimit: ({ action, session }) => limiter.check(`${action}:${session ?? 'anon'}`),
  // origins besides the app's own that may make cookie-authenticated calls
  allowedOrigins: ['https://admin.example.com'],
})

export { handler as GET, handler as POST }
```

| Option           | What it's for                                                                                                                                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rateLimit`      | Limit calls per action, per session, or per IP. Runs on every action call, after the session check and before validation.                                                                                      |
| `allowedOrigins` | Let these origins make cookie-authenticated calls too. A cookie call from any other origin is refused; bearer-token calls aren't checked. See [Security](https://affordances.vercel.app/docs/guides/security). |
| `auth`           | Resolve the session here instead. Defaults to the `auth` your actions were defined with; see [Sessions](https://affordances.vercel.app/docs/guides/nextjs/sessions).                                           |
| `manifest`       | Use this manifest instead of the generated one, such as in tests.                                                                                                                                              |

## Redirects

An action can call Next's `redirect()`, as a server action would. On the UI path, Next handles it as usual. On the agent path, the handler catches it and returns the destination in the delta's `redirect`, so the agent knows where to go next:

```json
{ "ok": true, "changed": { "cart": { "count": 0 } }, "redirect": "/account/orders" }
```

## Plugin routes

Each plugin's route handler sits next to the graph's. The Markdown plugin's is one line:

```ts title="app/api/affordances/md/[[...path]]/route.ts"
export { GET } from '@affordances/md/next'
```

```text
app/api/affordances/
  graph/[[...path]]/route.ts   the graph and actions
  md/[[...path]]/route.ts      Markdown, from @affordances/md
```

# Plugins (https://affordances.vercel.app/docs/guides/nextjs/plugins)

Add more capabilities to the same Next.js config through withAffordances's plugins, and write your own.

A plugin adds a capability to an Affordances app, such as serving every page as Markdown, without another config wrapper to order by hand. [Plugins](https://affordances.vercel.app/docs/concepts/plugins) in Concepts explains what they are, and the [Plugins](https://affordances.vercel.app/docs/plugins) section lists each one. Pass plugins to `withAffordances`:

```ts title="next.config.ts"
import { withAffordances } from '@affordances/next/config'
import { md } from '@affordances/md/next'

export default withAffordances(nextConfig, { name: 'Store', plugins: [md()] })
```

Then add each plugin's route handler. For `md()`:

```bash
vlx @affordances/md init
```

This site runs with `md()`: add `.md` to any page's URL. See [Markdown](https://affordances.vercel.app/docs/plugins/md).

## How they combine

- Plugins run in order, after the graph's own rewrites and headers.
- Each plugin owns a route handler under `/api/affordances/<name>`.
- Each one matches its own requests, such as `Accept: text/markdown` for `md()`, so plugins and the graph never answer for each other.

## Write a plugin

A plugin is a config wrapper: it takes the Next config and returns it, the same shape as `createMDX()`. Call the config's own `rewrites` and `headers` so you keep what came before:

```ts title="lib/well-known.ts"
import type { AffordancesPlugin } from '@affordances/next/config'

// serves /.well-known/agents.json from a route handler at /api/affordances/agents
export const agents = (): AffordancesPlugin => (config) => ({
  ...config,
  rewrites: async () => {
    const before = await config.rewrites?.()
    const rule = { source: '/.well-known/agents.json', destination: '/api/affordances/agents' }
    return Array.isArray(before)
      ? [rule, ...before]
      : { ...before, beforeFiles: [rule, ...(before?.beforeFiles ?? [])] }
  },
})
```

```ts title="next.config.ts"
export default withAffordances(nextConfig, { plugins: [md(), agents()] })
```

Keep its route under `/api/affordances/<name>`, and match only the requests it's for: `withAffordances` already claims the Affordances media type and `?affordances=1`.

# Sessions (https://affordances.vercel.app/docs/guides/nextjs/sessions)

One session resolver for the UI and for agents, with createAffordances, so actions run as the signed-in user either way.

Actions exposed as `session` or `confirm` need to know who's calling. `createAffordances({ auth })` returns a `defineAction` and `defineState` bound to one session resolver:

```ts title="lib/affordances.ts"
import { createAffordances } from '@affordances/next'
import { sessionFromCookie, sessionFromToken } from '@/lib/auth'

type Session = { userId: string }

export const { defineAction, defineState } = createAffordances<Session>({
  auth: async (request) => {
    const token = request.headers.get('authorization')?.replace(/^Bearer /, '')
    return token ? sessionFromToken(token) : sessionFromCookie(request.headers.get('cookie'))
  },
})
```

Import these instead of the defaults from `@affordances/next`:

```ts title="app/cart/actions.ts"
'use server'

import { AffordancesError } from '@affordances/next'
import { defineAction } from '@/lib/affordances'
```

## Where it runs

`auth` receives a standard `Request` and returns your session object, or `null` for no session.

- **Agent path:** the route handler calls `auth` with the agent's request.
- **UI path:** the server action calls it with a `Request` built from `headers()`.

So a session cookie works in both, and a browser agent acting in the person's tab is the person. Headless agents usually send a bearer token instead.

The resolver is where Auth.js, Better Auth, Clerk, or your own sessions plug in: read the cookie or token from the request, and return what your actions need.

## Using the session

The session is on `ctx.session` in `run`, `guard`, and the state loader:

```ts title="app/cart/actions.ts"
export const addToCart = defineAction({
  name: 'addToCart',
  description: 'Add a product to the cart',
  input: z.object({ slug: z.string() }),
  expose: 'session',
  run: (input, ctx) => {
    if (!ctx.session) throw new AffordancesError('unauthorized', 'Sign in to add to your cart')
    return carts.add(ctx.session.userId, input.slug)
  },
})
```

When an agent calls an action exposed as `session` or `confirm` without a session, the handler refuses it before `run`. A form submit runs the server action as usual, so check `ctx.session` yourself, as above, wherever a signed-out person can reach the form. See [Expose](https://affordances.vercel.app/docs/concepts/expose) for what each level allows.

# React and WebMCP (https://affordances.vercel.app/docs/guides/react)

AffordancesProvider turns the current page's actions into WebMCP tools for browser agents. Affordance marks the controls in the DOM.

`@affordances/react` serves agents that run inside the browser, next to the person.

## AffordancesProvider

```tsx
<AffordancesProvider path={pathname} onDelta={() => router.refresh()}>
  {children}
</AffordancesProvider>
```

On mount, and whenever `path` changes, the provider fetches the page's graph from its own URL. When the browser supports WebMCP, it registers each available action as a tool:

| Tool field                      | From the descriptor    |
| ------------------------------- | ---------------------- |
| `name`                          | `name`                 |
| `description`                   | `description`          |
| `inputSchema`                   | `input`                |
| `annotations.readOnlyHint`      | `readOnly`             |
| `annotations.consequentialHint` | `expose === 'confirm'` |

A tool's `execute` doesn't call the server action directly. It POSTs to the page's Affordances endpoint, the same way a headless agent would, so browser agents get the same `expose`, Origin, guard, and confirm checks as everyone else. The browser sends the person's cookies and the page's Origin, so session actions work.

After each call, the provider calls `onDelta`, reloads the graph, and registers the tools again, so tools that became available appear and ones that didn't go away. Unmounting unregisters everything.

WebMCP is read from `document.modelContext`, falling back to the earlier `navigator.modelContext`. Without either, the provider still loads the graph and does nothing else.

### Props

| Prop      | Type                                               | Description                                                                        |
| --------- | -------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `path`    | `string`                                           | The current page's path and query. Change it on navigation.                        |
| `onDelta` | `(delta: Delta) => void`                           | Called after every call. In Next, `router.refresh()` re-renders server components. |
| `confirm` | `(message: string) => boolean \| Promise<boolean>` | Asked before a `confirm` action runs. Defaults to `window.confirm`.                |

### useAffordances

Inside the provider, `useAffordances()` returns `{ graph, call, lastDelta }`. `graph` is the page's graph, or `null` while it loads or when the page has none. `call(action, input)` calls an action the way a tool would, including the confirm step, and resolves to the delta. `lastDelta` is the most recent delta from any call, or `null`.

```tsx
'use client'

import { useAffordances } from '@affordances/react'

export const AgentStatus = () => {
  const { graph } = useAffordances()
  if (!graph) return null
  const available = graph.actions.filter((action) => action.available)
  return <p>{available.length} actions available to agents on this page</p>
}
```

## Affordance

`<Affordance>` marks the element a person would use for an action, for agents that read the DOM:

```tsx
<Affordance action={addToCart} input={{ sku: variant.sku }}>
  <button formAction={addToCart}>Add to cart</button>
</Affordance>
```

It renders a `display: contents` wrapper with `data-affordances-action="addToCart"` and, when you pass `input`, `data-affordances-input` with the input as JSON. It doesn't register anything or change behavior.

In a server component, `action` is the real function from `defineAction`, and `<Affordance>` reads the name from it. In a client component, a server action arrives as a bare reference without its metadata, so pass the name instead:

```tsx
<Affordance name="addToCart">…</Affordance>
```

## Devtools

`<AffordancesDevtools />` from `@affordances/react/dev` shows what agents see, on top of the page. Render it inside the provider, in development only:

```tsx
import { AffordancesDevtools } from '@affordances/react/dev'

{
  process.env.NODE_ENV === 'development' && <AffordancesDevtools />
}
```

Press ⌥A (Alt+A) to toggle it. It outlines every `[data-affordances-action]` control with its action's name: solid when the action is available, dashed with the reason when it isn't. It also shows the last delta.

[`@affordances/lint`](https://affordances.vercel.app/docs/guides/lint) warns when a control calls a server action outside an `<Affordance>`.

# MCP (https://affordances.vercel.app/docs/guides/mcp)

@affordances/mcp turns any Affordances site into two MCP tools, for Claude, Cursor, and other MCP clients.

`@affordances/mcp` is a stdio MCP server that speaks Affordances to one site:

```bash
vlx @affordances/mcp https://store.example.com
```

It doesn't flatten the site into one tool per action. It gives the model two generic tools and lets it move through pages like a person would.

| Tool               | Input                                  | Returns                                                             |
| ------------------ | -------------------------------------- | ------------------------------------------------------------------- |
| `affordances_open` | `path`                                 | The page's graph: entities, actions with input schemas, and nav     |
| `affordances_call` | `path`, `action`, `input?`, `confirm?` | The delta: changed entities, output, action changes, and a redirect |

`affordances_open` is marked read-only. `affordances_call`'s description tells the model that `confirm` actions answer `confirm_required` first, and to resend with `confirm: true` only after the user approves the summary.

## Connect a client

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "store": {
      "command": "vlx",
      "args": ["@affordances/mcp", "https://store.example.com"]
    }
  }
}
```

Cursor and other clients take the same command and arguments.

## Authentication

Pass a bearer token with `--token`, or set `AFFORDANCES_TOKEN`:

```bash
vlx @affordances/mcp https://store.example.com --token "$STORE_TOKEN"
```

The token is sent as `Authorization: Bearer` on every request, and your `auth` resolver decides what session it maps to. The bridge never handles passwords.

Without a token, it keeps the cookies the site sets, like a browser would, and sends the site's own Origin with them. That's enough for flows where an action starts a session, such as an anonymous cart.

The bridge only requests paths on the site it was started with. A path that resolves to another origin is refused.

## As a library

```ts
import { createClient, createServer } from '@affordances/mcp'

const store = createClient('https://store.example.com', { token })
const graph = await store.open('/products/heavyweight-tee')
const delta = await store.call('/products/heavyweight-tee', 'addToCart', { sku: 'TEE-BLK-M' })
```

`createClient` returns `index()`, `open(path)`, and `call(path, action, input, confirm)`, each validated against the protocol's schemas. `createServer(site, options)` returns the `McpServer` the CLI connects to stdio, for embedding in your own transport.

# Lint (https://affordances.vercel.app/docs/guides/lint)

Two rules that keep the manifest buildable and every server-action control visible to agents.

`@affordances/lint` is an ESLint plugin, written against the ESLint rule API so oxlint's JS plugin support can load it too.

```bash
vlt install -D @affordances/lint
```

## ESLint

```js title="eslint.config.js"
import affordances from '@affordances/lint'

export default [affordances.configs.recommended]
```

## oxlint

```json title=".oxlintrc.json"
{
  "jsPlugins": ["@affordances/lint"],
  "rules": {
    "affordances/require-affordance": "warn",
    "affordances/static-action-name": "error"
  }
}
```

## Rules

| Rule                             | Recommended | What it checks                                               |
| -------------------------------- | ----------- | ------------------------------------------------------------ |
| `affordances/require-affordance` | `warn`      | Controls that call a server action are inside `<Affordance>` |
| `affordances/static-action-name` | `error`     | `defineAction` has a `name`, and it's a string literal       |

### require-affordance

The rule tracks identifiers imported from an actions module (`./actions`, `../cart/actions`, `@/app/cart/actions`). It reports a JSX `action`, `formAction`, `onClick`, or `onSubmit` attribute that uses one, unless an `<Affordance>` element encloses it:

```tsx
import { addToCart } from './actions'

// reported: addToCart is a server action, but this control isn't inside <Affordance>
<button formAction={addToCart}>Add</button>

// fine
<Affordance action={addToCart}>
  <button formAction={addToCart}>Add</button>
</Affordance>
```

It follows the forms people write: `action={x}`, `formAction={x.bind(null, id)}`, `onClick={() => x(input)}`, and `onClick={async () => { await x(input) }}`.

### static-action-name

Codegen reads action names without running your code, so they have to be literals:

```ts
defineAction({ name: 'addToCart' }) // fine
defineAction({ name: `add${kind}` }) // reported
defineAction({ description: '…' }) // reported: no name
```

# Security (https://affordances.vercel.app/docs/guides/security)

Default deny, explicit confirmation, Origin checks for cookies, and a fixed order of checks on every agent call.

Affordances adds an entry point to your app, so its defaults are conservative. This page lists what the handler enforces and what stays your job.

## Default deny

An action without `expose` isn't part of the protocol. It's missing from graphs and from `/.well-known/affordances.json`, and calling it answers `not_found`, the same as an action that doesn't exist. `defineAction` warns in development when `expose` is missing, so the omission is a decision rather than an accident.

## Confirm

`expose: 'confirm'` actions never run on the first call. The handler answers `confirm_required` with the action's `summary`, and runs only when the same call comes back with `confirm: true`. Clients acting for a person should show the summary and ask first. `@affordances/react` and `@affordances/mcp` both do. See [Expose](https://affordances.vercel.app/docs/concepts/expose#confirm).

## Origin and CSRF

Next's server actions protect themselves with an Origin check, but Affordances calls arrive at a route handler, so the handler does its own:

- A call that carries cookies and no bearer token must send an `Origin` header that matches the site, or one of `allowedOrigins`. Otherwise it answers `unauthorized`.
- A call with `Authorization: Bearer` is exempt, because a browser can't attach a bearer token to a cross-site request on its own.
- A call with neither carries no ambient credentials, so there's nothing to forge.

## Order of checks

Every agent call follows the same sequence and stops at the first failure: resolve the action, check Origin and `expose`, rate-limit, validate the input, run the guard, require confirmation, then run. Input is validated before the guard sees it, and the guard passes before `run` is called. See [Guards and confirm](https://affordances.vercel.app/docs/concepts/guards#order).

## Errors

An error thrown from `run` that isn't an `AffordancesError` is logged on the server and answered as `internal` with the message `Something went wrong`. Stack traces, SQL, and secrets in error messages don't reach the caller.

## Rate limits

`rateLimit`, passed to `createRouteHandler({ rateLimit })`, runs on every call, after authorization and before validation, with the request, the action's name, and the session. Return `true` to allow it, or a number of seconds to answer `rate_limited` with `Retry-After`.

## What stays yours

- **Authorization inside actions.** `session` says who is calling, not what they may touch. Check ownership in `run` as you would in any server action.
- **What entities contain.** A graph must not include anything the HTML page wouldn't show the same user. The loader runs with the caller's session; use it.
- **URLs.** Don't put personal data in paths or query strings. Graph URLs are page URLs, and they end up in logs.
- **The UI path.** A server action called from your components validates input but doesn't evaluate the guard or `expose`. Enforce invariants that matter for people in `run`.
- **Bots.** Verified-agent and bot-protection checks, such as Vercel BotID, belong in `auth` or `rateLimit`. Affordances doesn't require one.

# Plugins (https://affordances.vercel.app/docs/plugins)

Plugins add more ways for agents to read an Affordances app, on the same pages and the same URLs. Here's each one and how to add it.

The graph gives agents a page's state and actions. Plugins give them more, from the same app: each serves the same pages in another form, at the same URLs, without a second source of truth. [Plugins](https://affordances.vercel.app/docs/concepts/plugins) in Concepts explains how they work.

| Plugin                                                     | Package           | What agents get                                                                                           |
| ---------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------- |
| [Markdown](https://affordances.vercel.app/docs/plugins/md) | `@affordances/md` | Every page as Markdown, at `/page.md` and to `Accept: text/markdown`, plus `llms.txt` and `llms-full.txt` |

## Add a plugin

Install its package, pass it to `withAffordances`, and add its route handler. For Markdown:

```bash
vlt install @affordances/md
vlx @affordances/md init
```

```ts title="next.config.ts"
import { withAffordances } from '@affordances/next/config'
import { md } from '@affordances/md/next'

export default withAffordances(nextConfig, { name: 'Store', plugins: [md()] })
```

Each plugin's page covers its setup in full. To write your own, see [Plugins](https://affordances.vercel.app/docs/guides/nextjs/plugins) in the Next.js guide.

# Markdown for every page (https://affordances.vercel.app/docs/plugins/md)

@affordances/md serves every page of a Next.js app as Markdown, at /page.md and to Accept: text/markdown, from the page's own render.

Agents that don't speak the Affordances protocol still read pages, and most of a page's HTML is chrome they have to wade through. `@affordances/md` gives every page a Markdown twin: its content, without navigation, scripts, or controls.

There's no second source of truth. When an agent asks for Markdown, a route handler requests the page's HTML from your own app, the way a browser would, and converts it. Whatever the page renders, including data fetched on the server and content streamed into `<Suspense>` boundaries, is what the Markdown says.

```bash
curl https://store.example.com/products/tee.md
curl -H 'Accept: text/markdown' https://store.example.com/products/tee
```

This site runs on it: add `.md` to any page's URL.

- [Setup](https://affordances.vercel.app/docs/plugins/md/setup): the config plugin and the route handler.
- [Markers](https://affordances.vercel.app/docs/plugins/md/markers): say exactly what to keep and what to leave out.
- [What gets converted](https://affordances.vercel.app/docs/plugins/md/conversion): content, streamed boundaries, forms, code, and links.
- [Caching and privacy](https://affordances.vercel.app/docs/plugins/md/caching): what's private and what's cached.
- [llms.txt and llms-full](https://affordances.vercel.app/docs/plugins/md/llms): an index of every page for agents, and the whole site in one file, each from one line.
- [htmlToMarkdown](https://affordances.vercel.app/docs/plugins/md/converter): the converter on its own.

# Setup (https://affordances.vercel.app/docs/plugins/md/setup)

Add the md plugin to your Next.js config, then the route handler that renders and converts pages.

With the Affordances graph, add `md()` to `withAffordances`'s plugins:

```ts title="next.config.ts"
import { withAffordances } from '@affordances/next/config'
import { md } from '@affordances/md/next'

export default withAffordances(nextConfig, { name: 'Store', plugins: [md()] })
```

On its own, wrap the config with `withMd`:

```ts title="next.config.ts"
import { withMd } from '@affordances/md/next'

export default withMd(nextConfig)
```

Then add the route handler. `init` writes it:

```bash
vlx @affordances/md init
```

It's one line:

```ts title="app/api/affordances/md/[[...path]]/route.ts"
export { GET } from '@affordances/md/next'
```

## Routing

The config only adds rewrites, so nothing runs per request until an agent asks:

- A page requested with `Accept: text/markdown` is rewritten to the handler. API routes, `/_next`, and URLs with a file extension are left alone.
- `/blog/post.md` and `/index.md` (for `/`) are rewritten after Next's own files, so a real `.md` file in `public/` still wins.
- The handler's own request for the page carries an `x-affordances-md-render` header, which the rewrites skip, so it can't loop.

Next matches `Accept` as a pattern, so a header that lists `text/markdown` with a low q-value still gets Markdown. Browsers never send it, so in practice only agents do.

## Advertise it

`mdAlternate(path)` returns metadata alternates for a page's Markdown twin:

```ts title="app/blog/[slug]/page.tsx"
import { mdAlternate } from '@affordances/md/next'

export const generateMetadata = async ({ params }) => {
  const { slug } = await params
  return { alternates: { canonical: `/blog/${slug}`, ...mdAlternate(`/blog/${slug}`) } }
}
```

That renders `<link rel="alternate" type="text/markdown" href="/blog/post.md">`. For `/`, it points at `/index.md`.

# Markers (https://affordances.vercel.app/docs/plugins/md/markers)

Four components that say what a page's Markdown keeps, drops, and says instead.

The converter finds a page's content on its own. Markers from `@affordances/md/react` make it exact. They're server components that render an `<affordances-md>` element with `display: contents`, so they don't change layout and ship no JavaScript.

| Marker                  | Effect on the Markdown                                                       |
| ----------------------- | ---------------------------------------------------------------------------- |
| `<AgentMain>`           | When any are present, only these subtrees become the Markdown, in page order |
| `<AgentSkip>`           | Leaves its children out                                                      |
| `<AgentOnly>`           | Includes its children, hidden from people                                    |
| `<AgentText md block?>` | Replaces its children with `md`, verbatim; `block` makes it its own block    |

```tsx title="app/products/[slug]/page.tsx"
import { AgentMain, AgentSkip, AgentText } from '@affordances/md/react'

;<AgentMain>
  <h1>{product.name}</h1>
  <AgentSkip>
    <ShareMenu />
  </AgentSkip>
  <AgentText md={product.variants.map((v) => v.sku).join(', ')}>
    <VariantSwatches variants={product.variants} />
  </AgentText>
</AgentMain>
```

- A `skip` inside a `main` is respected, and a `main` inside another `main` is part of the outer one.
- `data-affordances-md="skip"` on any element works like `<AgentSkip>`, for components you can't wrap.
- `<AgentOnly>` must say what the page already shows people, in a form an agent can read. It's not for content people can't see.

This site wraps each docs article in `<AgentMain>`, and skips the page actions menu, the table of contents, and the previous and next links inside it.

# What gets converted (https://affordances.vercel.app/docs/plugins/md/conversion)

What the converter keeps from a page, what it drops, and how it reads streamed content, forms, code, and links.

## Which content

Without [markers](https://affordances.vercel.app/docs/plugins/md/markers), the converter takes the page's `<main>` (or `[role=main]`). Without one, it takes the body minus `nav`, `header`, `footer`, `aside`, dialogs, and their ARIA roles.

Scripts, styles, SVG, media, iframes, and anything hidden from people with `hidden` or `aria-hidden` are always dropped, unless an `<AgentOnly>` put it there.

## Streamed content

The handler waits for the whole response. React streams each resolved `<Suspense>` boundary after the page's shell, and the converter moves each one into place, as the browser would. So data loaded behind a fallback is in the Markdown, and the fallback isn't. Content rendered only on the client, in an effect, isn't: the handler converts what the server sent.

## Elements

- Headings, paragraphs, lists, blockquotes, tables, and rules, with GitHub-flavored Markdown for tables, strikethrough, and task lists.
- A heading's link to its own `#fragment` (the usual self-link) is unwrapped, so it reads `## Effects`.
- `<details>` becomes its summary in bold followed by its content, and `<dl>` becomes `**term**: definition`.
- Images need both a `src` and alt text; without alt text, they tell an agent nothing.
- Buttons are dropped. What a page lets you do belongs in its [Affordances graph](https://affordances.vercel.app/docs/concepts/actions).

## Code

`<pre><code class="language-ts">` becomes a `ts` fence. A `data-title` on the `<pre>` becomes the fence's title:

````md
```ts title="app/api/affordances/md/[[...path]]/route.ts"
export { GET } from '@affordances/md/next'
```
````

## Links

Links and images get absolute URLs. A link to `#` or `javascript:` keeps only its text. Links laid out side by side, with no text between them, get a space, so they don't run together.

## Forms

A form becomes a list of what it asks for: each field's label, with its type when it isn't text, and each choice group with its options and which are selected or unavailable. Values, placeholders, hidden inputs, and tokens never appear. The form's other text, such as hints and errors, follows the list.

## The page around it

At the top, YAML frontmatter carries the page's `title`, `description`, canonical `url`, `image`, and `lang`, from its metadata. If the content has no `#` heading, the title becomes one. JSON-LD scripts are appended as fenced JSON.

# Caching and privacy (https://affordances.vercel.app/docs/plugins/md/caching)

The Markdown is the page that caller would see, and it's only cached when the page is public.

The handler forwards the caller's `cookie`, `authorization`, and `accept-language` headers, so a signed-in agent gets the page that person would see. Everything about that response stays personal:

- With a cookie or bearer token, or when the page is `private` or `no-store`, or sets a cookie, the Markdown is sent with `Cache-Control: private, no-store`.
- Otherwise it keeps the page's own `Cache-Control`.
- Every response has `Vary: Accept`, `X-Affordances-Tokens` with an estimate of its length in tokens, and a `Link` to the canonical page when it has one.

The status code is the page's. A redirect to the same site stays in Markdown (to the target's `.md`); one to another origin is passed on, never followed. A page that takes longer than 10 seconds answers `504`, and one larger than 6 MB answers `413`.

## Behind a proxy

The handler fetches pages from the request's own origin. When a proxy changes it, set `AFFORDANCES_MD_ORIGIN`, or build the handler with options:

```ts title="app/api/affordances/md/[[...path]]/route.ts"
import { createMdHandler } from '@affordances/md/next'

export const GET = createMdHandler({ origin: 'http://localhost:3000', timeout: 5000 })
```

| Option     | Default       | Description                                                |
| ---------- | ------------- | ---------------------------------------------------------- |
| `origin`   | the request's | Where to fetch pages from                                  |
| `timeout`  | `10000`       | Milliseconds before answering `504`                        |
| `maxBytes` | 6 MB          | The largest page it converts                               |
| `append`   | none          | More Markdown after the page's, such as an actions summary |

# llms.txt and llms-full (https://affordances.vercel.app/docs/plugins/md/llms)

An index of every page for agents, and the whole site's Markdown in one file, each from one route handler.

[`llms.txt`](https://llmstxt.org/) is where agents look first: the site's name, a summary, and a link to every page's Markdown. `llms-full.txt` is every page's Markdown in one file. `@affordances/md` serves both, each from a route handler.

## Both files in two lines

On an Affordances site, neither handler needs a page list. They read the site's own [index](https://affordances.vercel.app/docs/reference/protocol) at `/.well-known/affordances.json` and list every route that needs no params:

```ts title="app/llms.txt/route.ts"
export { GET } from '@affordances/md/next/llms'
```

```ts title="app/llms-full.txt/route.ts"
export { GET } from '@affordances/md/next/llms-full'
```

`llms.txt` then has:

- the site's name from the index, as its heading;
- a line on reading any page as Markdown, linking `llms-full.txt`;
- a line saying the site is Affordances-enabled: how to ask a page for its graph, and where the site index is. An agent that starts at `llms.txt` learns it can act on the site, not just read it;
- a link to each page's Markdown, titled with the page's own title and described with its route's `description` from `state.ts` (written for agents), or else the page's meta description.

```md title="/llms.txt"
# Acme Store

> Studio goods in small runs.

Every page is also Markdown: add `.md` to its URL, or request it with `Accept: text/markdown`. [llms-full.txt](https://acme.store/llms-full.txt) has every page in one file.

This site is Affordances-enabled: request any page with `Accept: application/vnd.affordances+json` for its graph (what the page shows, and the actions you can call there, with their inputs). [/.well-known/affordances.json](https://acme.store/.well-known/affordances.json) lists every route and its actions.

## Pages

- [Home](https://acme.store/index.md): Every product: its lowest in-stock price, options, and whether it is in stock
- [Cart](https://acme.store/cart.md): The cart: items, quantities and subtotal
```

## Pages behind dynamic routes

A route like `/products/[slug]` has no single page, so it isn't listed on its own. Call the handlers yourself and name its pages; you're given the routes that need no params:

```ts title="app/llms.txt/route.ts"
import { createLlmsTxtHandler } from '@affordances/md/next'
import { products } from '@/lib/store'

export const GET = createLlmsTxtHandler({
  summary: 'Studio goods in small runs.',
  sections: (request, routes) => [
    { title: 'Pages', pages: routes },
    { title: 'Products', pages: products().map((p) => `/products/${p.slug}`) },
  ],
})
```

```ts title="app/llms-full.txt/route.ts"
import { createLlmsFullHandler } from '@affordances/md/next'
import { products } from '@/lib/store'

export const GET = createLlmsFullHandler({
  pages: (request, routes) => [...routes, ...products().map((p) => `/products/${p.slug}`)],
})
```

## Options

`createLlmsTxtHandler`:

| Option     | Type                                      | Description                                                                                                                                  |
| ---------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`    | `string`                                  | The `#` heading. Defaults to the site index's `name`.                                                                                        |
| `summary`  | `string`                                  | The `>` summary under it.                                                                                                                    |
| `intro`    | `string`                                  | More Markdown before the page lists, such as how to use the site.                                                                            |
| `sections` | `(request, routes) => { title, pages }[]` | The page lists, each under a `##` heading. A page is a path, whose title and description are read from it, or `{ url, title, description }`. |
| `full`     | `string \| false`                         | Where `llms-full.txt` is, to link it. Defaults to `/llms-full.txt`; `false` leaves the line out.                                             |

`createLlmsFullHandler` takes `pages: (request, routes) => string[]`, the paths in order, defaulting to the routes. Both also take the [Markdown handler's](https://affordances.vercel.app/docs/plugins/md/setup) `origin` and `timeout`.

A page given as a path is rendered the way `/page.md` is, to read its title and description. With many pages, give `{ url, title, description }` from your content source instead: nothing is rendered, and the file comes back faster. This site does that for its sidebar.

## How the files are made

- Each page goes through the same handler and converter as `/page.md`, so it matches what an agent reads one page at a time.
- Pages are rendered without the caller's cookies: both files are the public site.
- In `llms-full.txt`, frontmatter is stripped, and each page is headed `# Title (url)`. A page that fails is left out rather than failing the file.
- Without an Affordances index (`@affordances/md` on its own), pass `sections` and `pages`: there are no routes to default to, and `llms.txt` leaves out the Affordances line.
- Both are cached publicly for an hour (`s-maxage=3600`).

Both render by requesting the site's own pages, so they run at request time. They read the request first, which keeps Next from prerendering them during the build, when no server is running.

# htmlToMarkdown (https://affordances.vercel.app/docs/plugins/md/converter)

The converter on its own, with no React or Next.js dependency.

`htmlToMarkdown` from `@affordances/md` is the converter the route handler uses. Give it any HTML document:

```ts
import { htmlToMarkdown } from '@affordances/md'

const html = await (await fetch('https://example.com/post')).text()
const { markdown, title, url, tokens } = htmlToMarkdown(html, { url: 'https://example.com/post' })
```

| Option        | Default  | Description                                                                                                       |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `url`         | none     | Base for absolute links and images, usually the page's URL                                                        |
| `extract`     | `'auto'` | `'auto'`: markers, then `<main>`, then the body minus chrome; `'none'`: the whole body; or a function of the tree |
| `frontmatter` | `true`   | Prepend YAML frontmatter from the page's metadata                                                                 |
| `jsonLd`      | `true`   | Append the page's JSON-LD as fenced JSON                                                                          |
| `handlers`    | none     | Per-element overrides, as `hast-util-to-mdast` handlers                                                           |

It returns the Markdown, the page's `title`, its canonical `url` (or the one you passed), and `tokens`, an estimate of the Markdown's length in tokens (characters divided by four).

# Reference (https://affordances.vercel.app/docs/reference)

The Affordances protocol, every option in one place, and the API reference generated from each package's source.

The guides explain how the pieces fit. These pages are what to look things up in.

- [**Protocol**](https://affordances.vercel.app/docs/reference/protocol): the normative Affordances protocol, version 0. What a graph, an action call, and a delta look like on the wire.
- [**Options**](https://affordances.vercel.app/docs/reference/options): every option of `defineAction`, `defineState`, `createAffordances`, `createHandler`, and `withAffordances`, in one place.
- [**CLI**](https://affordances.vercel.app/docs/reference/cli): `affordances init` and `build` to set an app up, and `open` and `call` to see and use a page the way an agent does.
- [**API reference**](https://affordances.vercel.app/docs/reference/api-reference): every package's exports and signatures, generated from source with TypeDoc.

# Protocol (https://affordances.vercel.app/docs/reference/protocol)

The normative Affordances protocol, version 0. This page renders packages/protocol/spec.md from the repository at build time.

Affordances lets an agent read and operate a web page through the same URL a person uses, with the same session. A page answers in HTML for browsers and in JSON for agents. The JSON lists what the page shows (entities), what can be done there (actions), and where to go next (nav). Calling an action returns a delta: the parts of the page that changed.

This document is normative. The key words "must", "must not", "should", and "may" are used as in RFC 2119. The JSON Schemas in `schemas/` are generated from the same source as the TypeScript types and are authoritative for shapes.

## Media type

All Affordances documents use `application/vnd.affordances+json`. A server must not return an Affordances document for a request that did not ask for one.

## Discovery

**Per page.** A client requests the page's own URL with `Accept: application/vnd.affordances+json`. The server responds with a [graph](https://affordances.vercel.app/docs/reference/protocol#graph) for that page, or a `not_found` [delta](https://affordances.vercel.app/docs/reference/protocol#delta) with status `404` if the page has no Affordances graph.

HTML responses for pages with a graph should advertise it in both places:

```http
Link: <?affordances=1>; rel="affordances"
```

```html
<link rel="affordances" href="?affordances=1" />
```

`?affordances=1` is an alias for the `Accept` header, for clients that cannot set headers. A server that supports it must treat `GET <url>?affordances=1` like `GET <url>` with the Affordances `Accept` header, and must leave `affordances` out of the `searchParams` it gives the page's state.

**Per site.** `GET /.well-known/affordances.json` returns a [site index](https://affordances.vercel.app/docs/reference/protocol#site-index): the protocol version, the route patterns that have graphs and their action names, the supported auth modes, and optionally an MCP endpoint.

A shared cache must never serve one representation for the other: graphs send `Vary: Accept` and `Cache-Control: private, no-store`, and a server must make sure cached HTML is keyed on `Accept` too (with `Vary: Accept`, or by routing Affordances requests before the cache, as `@affordances/next` does with rewrites).

## Graph

```ts
type Graph = {
  v: '0'
  page: string // concrete path: /products/heavyweight-tee
  route: string // pattern: /products/[slug]
  entities: Record<string, unknown>
  actions: ActionDescriptor[]
  nav?: { to: string; label?: string; when?: string }[]
  md?: string
}
```

- `entities` is the page's state, keyed by name. It must not contain anything the page would not show the same user in HTML.
- `actions` lists every action on the route that the requester may know about. Actions the requester can't call right now are still listed, with `available: false` and a `reason`.
- `nav` lists links an agent can follow. `when` is a human-readable condition.
- `md` is an optional Markdown rendering of the page's content.
- A graph should stay small. About 2,000 tokens is a good ceiling, and large collections should be summarized in `entities`.

### Action descriptor

```ts
type ActionDescriptor = {
  name: string // unique per route, stable across releases
  description: string
  input: JSONSchema
  output?: JSONSchema
  expose: 'public' | 'session' | 'confirm'
  guard?: string // human-readable precondition
  available: boolean // the guard, evaluated for this request
  reason?: string // why available is false
  effects?: string[] // entity keys the action changes
  readOnly?: boolean
}
```

`expose` says who may call an action:

| `expose`  | Caller                                                                               |
| --------- | ------------------------------------------------------------------------------------ |
| `public`  | anyone                                                                               |
| `session` | an authenticated session, by cookie or bearer token                                  |
| `confirm` | a session, and the call must carry `confirm: true` after the user has seen a summary |

An action with no `expose` is not part of the protocol. It must not appear in graphs and must not be callable.

## Call

```http
POST <page-url>
Content-Type: application/vnd.affordances+json

{ "action": "addToCart", "input": { "sku": "TEE-BLK-M" } }
```

```ts
type Call = { action: string; input?: unknown; confirm?: boolean }
```

The server processes a call in this order, and stops at the first failure:

1. Resolve the action by name on the page's route. Failure: `not_found`.
2. Check the CSRF rule below and `expose` against the caller. Failure: `unauthorized`.
3. Apply the rate limit. Failure: `rate_limited`.
4. Validate `input` against the action's input schema. Failure: `invalid_input`, with `issues`.
5. Evaluate the guard. Failure: `unavailable`, with the guard's reason as `message`.
6. For `confirm` actions without `confirm: true`: `confirm_required`, with a summary of what will happen as `message`, written for the person who approves it. Nothing runs.
7. Run the action, reload the page's state, and respond with a delta.

## Delta

```ts
type Delta = {
  ok: boolean
  changed?: Record<string, unknown>
  output?: unknown
  actionsAdded?: ActionDescriptor[]
  actionsRemoved?: string[]
  redirect?: string
  message?: string
  error?: { code: ErrorCode; message: string; issues?: unknown }
}
```

- `changed` holds the new value of each entity in the action's `effects`. When an action declares no effects, `changed` holds every top-level entity whose value differs after the action ran.
- `output` is the action's return value, described by the descriptor's `output` schema when it has one.
- `actionsAdded` and `actionsRemoved` describe changes to the action list, including availability changes. An action whose `available` flipped appears in `actionsAdded` with its new descriptor.
- `redirect` is a path the person would have been sent to. The agent should request it next.
- `message` is a short sentence suitable to repeat to the user.

### Error codes

| Code               | HTTP | Meaning                                                 |
| ------------------ | ---- | ------------------------------------------------------- |
| `not_found`        | 404  | No such route or action                                 |
| `invalid_input`    | 422  | `input` failed the schema; `issues` says where          |
| `unauthorized`     | 401  | The caller may not call this action                     |
| `confirm_required` | 409  | Resend with `confirm: true` after showing `message`     |
| `unavailable`      | 409  | The guard failed; `message` says why                    |
| `rate_limited`     | 429  | Too many calls; the response should carry `Retry-After` |
| `internal`         | 500  | The action threw; `message` must not leak internals     |

## Site index

```ts
type SiteIndex = {
  v: '0'
  name?: string
  routes: { route: string; description?: string; actions: ActionSummary[] }[]
  auth: ('cookie' | 'bearer')[]
  mcp?: string
}

// an action descriptor without this request's availability (no `available`, no `reason`)
type ActionSummary = Omit<ActionDescriptor, 'available' | 'reason'>
```

The index is enough to plan a task and to call an action without opening its page first: an agent that knows the route and the input can `POST` straight to a concrete URL of that route. It still gets `unavailable` or `unauthorized` if the guard or `expose` says no. Each route's `description` is one line on what the page is for. Input schemas may omit `$schema`; they are JSON Schema 2020-12.

## Security

- Default deny. Only actions that declare `expose` are reachable.
- A call that authenticates by cookie must carry an `Origin` header that matches the site. A call with `Authorization: Bearer` is exempt. A server must not rely on its framework's server-action protections for Affordances calls.
- `confirm` actions must not run without `confirm: true`. Clients acting for a person should show `message` and get approval first.
- Input is validated before the guard runs, and the guard runs before the action.
- URLs must not carry personal data. A graph must not include data that the HTML page would not show to the same user.

## Versioning

`v` is the protocol's major version. A breaking change ships as a new major version. Additive changes, such as new optional fields, may ship within a major version, and clients must ignore fields they don't recognize. Packages declare the range of majors they support.

# Options (https://affordances.vercel.app/docs/reference/options)

Every option of defineAction, defineState, createAffordances, createHandler, and withAffordances, in one place. The generated API reference has the full signatures.

## defineAction

```ts
import { defineAction } from '@affordances/next'
```

Returns a server action that also carries the action's metadata. Use the one from `createAffordances({ auth })` to share a session resolver.

| Option        | Type                                           | Description                                                                                          |
| ------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `name`        | `string`                                       | Required. Unique on the route and stable across releases. Must be a string literal.                  |
| `description` | `string`                                       | Required. What the action does, written for an agent.                                                |
| `input`       | `StandardSchemaV1`                             | Required. Validated on every call. Its JSON Schema becomes the descriptor's `input`.                 |
| `run`         | `(input, ctx) => Output`                       | Required. Does the work. May be async, may throw `AffordancesError` or `redirect()`.                 |
| `expose`      | `'public' \| 'session' \| 'confirm'`           | Who may call it as an agent. Omitted: agents can't reach it.                                         |
| `state`       | `StateDef`                                     | The route's state, so `guard`, `summary`, and `effects` are typed against it.                        |
| `requires`    | `string`                                       | The precondition in words, shown as the descriptor's `guard`.                                        |
| `guard`       | `({ input, state, ctx }) => boolean \| string` | `true` to allow, a string with the reason to refuse. `input` is `undefined` when building the graph. |
| `summary`     | `({ input, state }) => string`                 | What a `confirm` action will do, shown to the person before they approve.                            |
| `message`     | `({ input, output }) => string`                | A sentence for the delta's `message`.                                                                |
| `effects`     | `string[]`                                     | Entity keys the action changes. The delta's `changed` holds exactly these.                           |
| `readOnly`    | `boolean`                                      | Marks the action as side-effect free, for agents and WebMCP's `readOnlyHint`.                        |
| `output`      | `StandardSchemaV1`                             | Describes the return value as the descriptor's `output`.                                             |
| `jsonSchema`  | `Record<string, unknown>`                      | The input's JSON Schema, for schema libraries without Standard JSON Schema.                          |

## defineState

```ts
defineState(loader, { nav })
```

| Option   | Type                                                         | Description                                          |
| -------- | ------------------------------------------------------------ | ---------------------------------------------------- |
| `loader` | `({ params, searchParams, ctx }) => Entities`                | Required. Returns the page's entities. May be async. |
| `nav`    | `(state) => { to: string; label?: string; when?: string }[]` | Links an agent can follow from this page.            |

## createAffordances

```ts
import { createAffordances } from '@affordances/next'

export const { defineAction, defineState } = createAffordances<Session>({ auth })
```

| Option | Type                                    | Description                                                                                |
| ------ | --------------------------------------- | ------------------------------------------------------------------------------------------ |
| `auth` | `(request: Request) => Session \| null` | Resolves the caller's session. Used by the route handler and by the UI path. May be async. |

## createHandler

```ts
import { createHandler } from '@affordances/core'
import { createRouteHandler } from '@affordances/next/route'
```

`createHandler` is the framework-agnostic handler: `(request: Request) => Promise<Response>`. `createRouteHandler(options)` wraps it for Next. It sets `basePath: '/api/affordances/graph'` and `redirectFrom` for Next's `redirect()`, and `manifest` defaults to the app's generated one. `GET` and `POST` from `@affordances/next/route` are `createRouteHandler()` with no options.

| Option           | Type                                               | Description                                                                                          |
| ---------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `manifest`       | `Manifest`                                         | Required. Route patterns mapped to their state and actions. `@affordances/next` generates it.        |
| `basePath`       | `string`                                           | Stripped from the request path before matching, such as `/api/affordances/graph`.                    |
| `auth`           | `(request: Request) => Session \| null`            | Defaults to the `auth` the actions were defined with.                                                |
| `rateLimit`      | `({ request, action, session }) => true \| number` | `true` allows the call; a number of seconds answers `rate_limited` with `Retry-After`. May be async. |
| `allowedOrigins` | `string[]`                                         | Origins besides the request's own that may make cookie-authenticated calls.                          |
| `redirectFrom`   | `(error: unknown) => string \| undefined`          | Reads the path from a framework's own redirect error.                                                |

## withAffordances

```ts
import { withAffordances } from '@affordances/next/config'
import { md } from '@affordances/md/next'

export default withAffordances(nextConfig, { name: 'Store', plugins: [md()] })
```

Returns the same config, with Affordances' rewrites put first in `beforeFiles` and a `Link` header on every page that has a graph, then each plugin applied in order. Your own `rewrites` and `headers` are kept.

| Option    | Type                     | Description                                                                                                                                                    |
| --------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`    | `string`                 | The site's name in `/.well-known/affordances.json`.                                                                                                            |
| `root`    | `string`                 | The project root to scan for `app/` or `src/app/`. Defaults to the directory Next runs in.                                                                     |
| `plugins` | `((config) => config)[]` | More Affordances capabilities, applied in order after the graph, e.g. `[md()]` from `@affordances/md/next`. Each owns a route under `/api/affordances/<name>`. |

## CLI

The `affordances` commands are in [`@affordances/cli`](https://affordances.vercel.app/docs/reference/cli).

# CLI (https://affordances.vercel.app/docs/reference/cli)

The affordances CLI sets up a Next.js app, regenerates its manifest, and shows and calls any page the way an agent does. Every command takes --json.

`@affordances/cli` runs without installing:

```bash
vlx @affordances/cli init
```

It runs in your project's root, the folder with `next.config.ts`. `affordances --help` lists the commands, and `affordances <command> --help` describes each one.

## Commands

| Command                           | What it does                                                                                                              |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `affordances init`                | Writes the route handler, wraps `next.config` with `withAffordances`, ignores `.affordances`, and generates the manifest. |
| `affordances build`               | Regenerates `.affordances/manifest.ts`. `withAffordances` does this when Next starts; use it in scripts and CI.           |
| `affordances open <url>`          | Prints the page's graph as an agent receives it: entities, actions with their input, nav, and about how many tokens.      |
| `affordances call <url> <action>` | Calls an action on the page, with the same checks an agent gets, and prints the delta.                                    |

### init

`init` skips anything that's already done, so it's safe to run again. When it can't wrap your config, such as a default export that isn't a plain identifier, it leaves the file alone and lists it as a todo:

```text
wrote    app/api/affordances/graph/[[...path]]/route.ts
wrapped  next.config.ts                                  with withAffordances
wrote    .gitignore                                      ignores .affordances
wrote    .affordances/manifest.ts                        3 routes
```

### open

```bash
vlx @affordances/cli open localhost:3000/products/tee
```

```text
/products/tee  (/products/[slug])  ~274 tokens

Entities  product, cart

Actions
  ✓ addToCart(sku: string, quantity?: integer)  public
```

`✗` marks an action whose guard says no right now, with the reason. The token count is an estimate, about four characters per token.

### call

```bash
vlx @affordances/cli call localhost:3000/products/tee addToCart --input '{"sku":"TEE-BLK-M"}'
```

| Flag        | What it does                                                                        |
| ----------- | ----------------------------------------------------------------------------------- |
| `--input`   | The action's input, as JSON.                                                        |
| `--confirm` | Confirms an action exposed as `confirm`. Only pass it once the person approves.     |
| `--token`   | Sent as `Authorization: Bearer`, to call as a signed-in user (`open` takes it too). |

A call the server refuses, such as `unauthorized` or `unavailable`, prints why and exits with status 1.

## JSON output

Every command takes `--json`, for scripts and coding agents. A result prints as `{ "ok": true, ... }`, with the same fields the text shows. A failure prints `{ "ok": false, "error": { "code", "message" } }` and exits 1:

```json
{
  "ok": false,
  "error": {
    "code": "Unreachable",
    "message": "Couldn't reach localhost:3000/: ECONNREFUSED. Is the app running?"
  }
}
```

For `call`, `ok` is the delta's own `ok`, and the delta is under `delta`.