![\"HACI](\"docs/assets/haci-hero-light.svg\")
\n Human & Agent · Computer Interaction
\n\n\n Your agent can reach your app — but it's flying blind.
\n Your app already knows what can be done here, and by whom. Hand the agent that map.\n
\n \n
\n ![\"npm](\"https://img.shields.io/npm/v/hcifootprint?style=flat&color=e0a400\")
![\"3366](\"https://img.shields.io/badge/tests-3366%20passing-f5b301?style=flat\"){kind=icon}
![\"zero-dependency](\"https://img.shields.io/badge/core-zero--dependency-f5b301?style=flat\"){kind=icon}
![\"serves](\"https://img.shields.io/badge/serves-a%20real%20MCP%20server-f5b301?style=flat\"){kind=icon}
![\"MIT\"](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n
\n 🌐 footprintjs.github.io/hcifootprint ·\n Docs ·\n Quick start\n
\n\n```bash\nnpm install hcifootprint\n```\n\n> **1.0 — the names are frozen.** You author **actions**, you name **journeys**, and a **tool** is\n> what is served to a model. The pre-1.0 spellings (`tools:`, `skills:`) are gone, not deprecated —\n> see the [migration](CHANGELOG.md#100---2026-08-02).\n> **Agents:** [`llms.txt`](llms.txt) is the whole API surface on one page.\n\n---\n\n## The problem\n\nAn agent can already reach your app. The question is how it *operates* one.\n\n| How agents drive a UI today | The cost |\n|---|---|\n| Screenshot the page, reason over pixels | slow, fragile, redone every turn |\n| Dump the DOM into the prompt | every wrapper and class, re-sent each turn — and it still guesses what does what |\n| Hard-coded selectors, RPA scripts | break on the next redesign |\n\nAll three relearn your app from scratch on every visit.\n\n**Measured, on a real page**: a five-page demo's rendered DOM is 2,027 tokens; what this library\nsends for the same page is 332 — **6.1× less per turn**, at 41.5 tokens per available action. That is\none page of one small app whose DOM is dominated by its shell, so treat it as a floor rather than a\nheadline; the script is in the repo (`node bench/token-cost/token-cost.mjs`) and the honest way to\nknow your own number is to run it against your own app. A returning human doesn't — they carry a\nmental model of where things are and what they're allowed to do. **Your app holds that same map. This\nhands it to the agent.**\n\nAnd it is safe to adopt for one reason: **you are not opening your backend — you are letting an agent\ndrive the frontend a human already can.** It acts as the signed-in user, through your own buttons and\nhandlers, inside exactly the permissions they already have. No new endpoints, no new grants.\n\n---\n\n## The model\n\n**Three contexts.** An agent driving your app asks three questions, and this library answers exactly\nthose — each in the same three parts: what you **declare**, what you **wire**, and what the **agent\ngets**.\n\n### 1 · The map — *what can this app do?*\n\n**Declare** the app as the tree you already picture: places, the things inside them, the named flows\nworth finishing. One sentence per action — that sentence is your label *and* the tool description the\nmodel reads.\n\n```ts\npages: {\n catalog: { route: '/catalog', actions: { 'add-to-cart': { does: 'Add the open dress to the cart', writes: ['cart.items'] } } },\n checkout: { route: '/checkout', actions: { 'place-order': { does: 'Place the order', enabledWhen: { 'cart.items': { gt: 0 } }, confirm: true } } },\n},\njourneys: { purchase: { does: 'Buy a dress end to end', steps: ['add-to-cart', 'place-order'] } },\n```\n\nAlready have a route table, a router's own nested route tree, a journey list, a live action store?\n`fromRoutes`, `fromReactRouter`, `fromJourneys` and `fromLiveStore` adopt them under one documented\nmerge order — nobody re-types anything. `fromReactRouter` transcribes a page name from a fully-static\naddress (`/projects/new` → `projects-new`) and refuses, naming both doors, wherever there is nothing\nto transcribe — a `:param`, a `*`, the root. It never guesses a name.\n\n**Wire: nothing.** A map is static data. It validates and freezes in one call, so it can be linted in\nCI and argued about in a pull request before your app runs at all.\n\n**The agent gets** one tool per journey, plus four fixed generics. **The tool list *is* the map**, and\nits bytes never change for the life of a conversation. A whole-page dump is never served — that is the\nthesis, not an optimisation.\n\n### 2 · Traversal — *where am I, and how do I get there?*\n\n**Declare** two fields, on the map you already wrote: `route` on a page, `goTo` on an action. An\naction's claim **is** the edge; pages declare no edges to one another.\n\n```ts\ncart: { route: '/cart', actions: { pay: { does: 'Check out', goTo: 'checkout' } } },\n```\n\n**Wire** the session, and one line wherever your router already knows the page changed.\n\n```ts\nconst session = graph.createSession({ node: 'catalog' });\nsession.sync('checkout'); // the router moved → the cursor moves\n```\n\n**The agent gets** where it is, whether arrival is `claimed` or `observed` — never a guessed third\nvalue meaning *did not arrive* — and the declared hops to any destination.\n\n### 3 · Actions — *what is possible here?*\n\n**Declare** what an action is, once, where it lives: `does`, `writes`, `enabledWhen`, `goTo`,\n`confirm`, `verify`, `input`, `humanDecides`.\n\n**Wire** your own functions, by reference, when the component that renders them mounts.\n\n```ts\nconst group = session.registerActions('checkout', {\n handlers: { 'place-order': (input) => shop.placeOrder(input) },\n});\ngroup.setEnabled('place-order', false); // the greyed button\ngroup.setBusy('place-order', 'Placing your order…'); // your words, never ours\nsession.updateState({ 'cart.items': 3 }); // your store → conditions re-evaluate\n```\n\n**The agent gets** one row per action that is offered here, carrying `enabled`, `blockedBecause`,\n`busy`, `holds`, `goesTo`, `expects`, `highEffect`, `humanDecides` and `unblockedBy`. Every stamp is\npresence-only: a key means your app said so, and no key means the library does not know.\n\n### Declared or wired? One question decides\n\n> **Can this fact change while the page is open?** If **no**, it is a declaration\n> (`enabledWhen`). If **yes**, it is a wire (`setBusy`).\n\nThat is why there is no `busyWhen`: a condition can prove a state, but it cannot author a label, and a\nlibrary-written label would be a library-written meaning.\n\n### And a fourth thing — which you never build\n\nThe relations *between* actions are the part people expect to have to author. You don't.\n\n*Is `place-order` blocked, and by what?* `add-to-cart` writes `cart.items`; `place-order` waits on it.\nNobody wrote an edge, and the edge is unambiguously there — so it is **derived, never authored**, and\ncannot drift from your graph:\n\n```ts\nsession.whatUnblocks('checkout.place-order');\n// [{ affordanceId: 'catalog.add-to-cart', viaKeys: ['cart.items'] }]\n```\n\n*How do I get to checkout?* A route is walked from the `goTo` claims you already made:\n\n```ts\nsession.howToReach('checkout'); // [{ action: 'catalog.open', to: 'product' }, …]\n```\n\n**Everything relational is derived from declarations you make for other reasons.** There is no edge\nAPI in this library — not between pages, not between actions. The only thing you declare that cannot\nbe derived is *intent*: \"these steps, in this order, toward this goal\" — a\n[journey](https://footprintjs.github.io/hcifootprint/docs/map/journeys), because a preferred order is\nmeaning, and meaning is yours.\n\n→ [The three contexts](https://footprintjs.github.io/hcifootprint/docs/get-started/three-contexts) ·\n[What would free it](https://footprintjs.github.io/hcifootprint/docs/actions/what-would-free-it) ·\n[How to reach a page](https://footprintjs.github.io/hcifootprint/docs/traversal/how-to-reach) ·\n[Navigation graph](https://footprintjs.github.io/hcifootprint/docs/map/navigation-graph)\n\n---\n\n## Map & Walker\n\nThe three contexts above have one sentence under them, and it is the same sentence this\nlibrary's siblings say at their own altitude:\n\n> **You declare the JourneyMap; the session is the Walker; the recording carries both.**\n\nSince 1.10.0 those two nouns have names in the API — `defineJourneyMap` and `JourneyMap`,\n**permanent aliases** of `buildNavigationGraph` and `NavigationGraph`. Same function object,\nsame type, both names forever; neither is a rename, and a codebase may speak either dialect.\n\n```ts\nimport { defineJourneyMap } from 'hcifootprint';\n\nconst map = defineJourneyMap('shop', { pages: { /* … */ } });\nconst walker = map.createSession({ node: 'catalog' }); // the walker IS the session\n```\n\nThere is deliberately **no `Walker` to construct**. A walker is not a thing you wire up — it is\nthe session you already create, standing on a node, moving. Three movers move it, and each\nlands on the record as a `Cause` (`kind` — was an offered edge fired, or did the world move? —\nplus `principal`, whose move it was):\n\n| Mover | What moves the cursor | On the record |\n|---|---|---|\n| **human** | a real click in your own controls — `watchPage` senses it, `contextful` catches the app's own call | `kind: 'fired'`, `principal: 'user'`, with `Attribution` grading what that claim is worth |\n| **agent** | the four served verbs through the MCP door — `whats_here`, `why`, `do_action`, `did_it_work` | `kind: 'fired'`, `principal: 'agent'`, plus the `offerId` of the row it planned against |\n| **guard** | your data: an action's `when` / `enabledWhen` judged against the state your store pushed | the guard's own evidence, and `blockedBecause` / `unblockedBy` when it says no |\n\nAnd the world moves on its own — a back button, a server push, an expiry. That is\n`kind: 'stimulus'`: recorded, never silently absorbed.\n\nFive moves make up walking, and every one of them is answered by something that already ships:\n\n| A walker… | Here it is |\n|---|---|\n| **looks** | `whats_here` — one row per action offered on this node |\n| **navigates** | `do_action` on an action declaring `goTo`; the row carries `goesTo`, and `howToReach` walks the hops first |\n| **moves inside a screen** | a fire landing on an area, a tab or a modal moves the **focus**, not the page — `session.focus`, with `focusHistory` recording who moved it |\n| **keeps a task list** | **journeys** — `commitJourney` opens a frame, `journeyStanding` says where the flow stands |\n| **verifies** | `did_it_work` — the settled facts of one fire, never a guess; the drift sensor (`checkGraph`) is the honesty backstop under it |\n\nThe same pattern sits at three altitudes: [footprintjs](https://github.com/footprintjs/footPrint)\nwalks **stages**, [agentfootprint](https://github.com/footprintjs/agentfootprint)\n(`defineSkillMap`) walks **skills**, and this walks **screens**.\n\n### Where the reader is: page, container, state\n\n> **Sync pages; observe the deeper place. `sync()` moves the walker and decides what is\n> served; `observeFocus()` says which tab or area the reader is in. Declare containers, and\n> report the deepest one on screen.**\n\nPosition has three tiers, and each has one door: the page (`sync('run-detail')` — the walker\nmoves, and what is served moves with it), the container inside it\n(`observeFocus('run-detail.why')` — any declared tab, area or modal path, and serving does NOT\nmove), and state (`updateState`, which is not position). The middle one gets skipped because\nnothing forces it: declaring `tabs:` compiles, mounts and masks perfectly well while never once\nsaying which tab the person is looking at.\n\nIt has to be its own door. A tab is not a place the walker can stand — actions are served from\nthe **page**, so a cursor parked on a tab would be served nothing — and a **person** clicking a\ntab fires nothing, which is exactly the case worth reporting.\n\n```ts\nsession.show('run-detail.why'); // which tab is VISIBLE\nsession.observeFocus('run-detail.why', { principal: 'user' }); // where the READER is\n```\n\n```text\nYou are on: run-detail. → You are on: run-detail.\n Focus: run-detail.why.\n```\n\nEvery served answer carries both halves as data: `youAreOn` is the page that serves,\n`lookingAt` is the deeper place. Without it a screen-driving agent has to deduce the open tab\nfrom whatever unlabelled state keys happen to move. `lintGraph` proves the authored half\n(`unevidenceable-tab`).\n\n→ [Map & Walker](https://footprintjs.github.io/hcifootprint/docs/map/map-and-walker)\n\n### When the action is already done\n\n> **An effect that is already true is not a pending one. When an action's declarative verify\n> contract covers every key it declares it writes and already holds at fire time, the fire never\n> waits for a state report that nothing will send — it settles on its own handler and answers\n> `alreadyTrue`.**\n\nAn agent pressed a control while the thing it does was already the case — it asked to open a domain\nview while already inside that domain. The app's store publishes on *change*, so writing the value\nit already held notified nobody, no state report arrived, and the fire waited for one forever.\n`did_it_work` could only answer `still-pending`; the model read that as *the app is still working*\nand burned fifteen of its thirty steps on an outcome that could never arrive.\n\nDeclare the postcondition beside the action and the library can see it, because `verify` is the one\ndeclaration carrying a **value** (`writes` is key names only, by design — nothing here infers what\nyour handler would set):\n\n```ts\n'open-billing': {\n does: 'Open the billing domain view',\n writes: ['view.domain'],\n verify: { 'view.domain': { eq: 'billing' } },\n}\n```\n\nThe fire comes back carrying `alreadyTrue` — the conditions that already hold — plus one authored\nsentence that tells the model to move on. Your handler still runs; what changed is only what the\nfire *waits on*.\n\n→ [When it is already true](https://footprintjs.github.io/hcifootprint/docs/actions/already-true)\n\n---\n\n## Why this makes an agent better\n\nNot by making the model smarter. By never making it guess.\n\nEvery turn, the agent gets **only what is true here, now** — one page's actions, not your whole app:\n\n```\nYou are on: Checkout (step 3 of 4)\n\nActions here:\n edit-address Change the delivery address\n place-order Place the order [not available]\n waiting on: cart.items\n which \"Add to cart\" writes — and it is running right now\n needs a person's approval before an agent may fire it\n\nLast outcome: address update — performed, verified\n```\n\nFollow what that removes. The model doesn't infer the page — it's told. It doesn't guess whether a\ncontrol is clickable — it's told, and told *why not*, and *what would change it*. It doesn't wonder\nwhether its last action worked — the outcome is a fact, not an assumption. It doesn't hunt for the\nfinish line — a journey names the steps and the library says which are still open.\n\n**A greyed button is the whole argument.** A production integration's agent met one, was told only\nthat it was disabled, fired it again to find out what would change, then told its human the app was\nbroken. Nothing had failed — an upload was still running. That agent wasn't bad at its job; it was\nanswering a question nobody had given it the facts for.\n\nThree consequences, in order of how much they matter:\n\n- **It stops hallucinating capability.** Anything derived rather than observed is flagged\n (`arrival: 'claimed'`, `guardUnevaluated`, `presence: 'unknown'`). Every refusal is typed and\n teaches — so the agent replans instead of inventing a cause.\n- **A smaller model goes further.** The reasoning that used to reconstruct your app from a DOM dump is\n simply not spent. This is context engineering, not model choice.\n- **Tokens are bounded by the page, not the app.** What's on screen is what's sent.\n\n→ [Reading an action row](https://footprintjs.github.io/hcifootprint/docs/actions/reading-an-action-row) ·\n[Grounding](https://footprintjs.github.io/hcifootprint/docs/actions/grounding) ·\n[Modes](https://footprintjs.github.io/hcifootprint/docs/map/modes)\n\n---\n\n## Quick start\n\nThree steps. The first two run offline, with no API key.\n\n**1 · Describe the app** — the tree you already picture.\n\n```ts\nimport { buildNavigationGraph } from 'hcifootprint';\n\nconst graph = buildNavigationGraph('shop', {\n pages: {\n catalog: { actions: { 'add-to-cart': { does: 'Add the open dress to the cart' } } },\n checkout: { actions: { 'place-order': { does: 'Place the order', confirm: true } } },\n },\n});\n```\n\n**2 · Connect it** — components register what they have when they render; your router reports the page.\n\n```ts\nconst session = graph.createSession();\n\nconst group = session.registerActions('catalog', {\n handlers: { 'add-to-cart': (input) => shop.add(input.id) }, // your own function, by reference\n});\n\nsession.sync('checkout'); // router change → the cursor moves\nsession.updateState({ cartCount: 1 }); // your store → guards re-evaluate\n```\n\n**3 · Serve it** as a fixed set of MCP-shaped tools. The tool list never changes; what's doable *right\nnow* arrives inside each result.\n\n```ts\nimport { mcpServer } from 'hcifootprint/mcp';\nmcpServer(session);\n```\n\n→ [Quick start](https://footprintjs.github.io/hcifootprint/docs/get-started/quick-start) ·\n[Adoption ladder](https://footprintjs.github.io/hcifootprint/docs/get-started/adoption-ladder) —\nstart in guide mode, where the agent can only *describe* what's possible.\n\n---\n\n## Honest by construction\n\nTwo properties do most of the safety work, and they are why this is worth adopting over a DOM dump.\n\n**It says what it can't see.** Derived facts are marked as derived. Unknowable ones are `unknown`,\nnever guessed. A failed read says *\"the app could not re-read its actions here\"* instead of serving an\nempty list as truth. Silence is never a verdict, and a clock is never evidence.\n\n**A human's yes is a reference, not a claim.** For a high-effect action, an agent asserting *\"the user\napproved\"* proves nothing. The library requires a pointer to a decision a person actually recorded,\nbound to the receipts they were shown.\n\n**And some choices are not the agent's to make at all.** `humanDecides` says a decision belongs to a\nperson — the agent presents the options and stops, and the human answers through your own control.\nIt is disclosed on every surface and enforced on none: the flow is simply in someone's hands, and\nthe library can say so without inventing a gate you never declared.\n\n```ts\n'choose-shipping-speed': {\n does: 'Choose a shipping speed',\n writes: ['checkout.shipping'],\n humanDecides: {\n about: 'which shipping speed', // your words, carried as data\n doneWhen: { 'checkout.shipping': { ne: '' } }, // your own \"it has been decided\"\n },\n}\n```\n\n→ [Human-in-the-loop](https://footprintjs.github.io/hcifootprint/docs/actions/receipts) ·\n[Whose decision it is](https://footprintjs.github.io/hcifootprint/docs/actions/whose-decision-it-is) ·\n[Paused is not failed](https://footprintjs.github.io/hcifootprint/docs/actions/paused-not-failed) ·\n[The human sensor](https://footprintjs.github.io/hcifootprint/docs/actions/human-sensor)\n\n---\n\n## More\n\n| | |\n|---|---|\n| **Async & progress** — the promise is the completion signal; `busy` in the app's own words | [Going async](https://footprintjs.github.io/hcifootprint/docs/actions/going-async) · [Waiting for the app](https://footprintjs.github.io/hcifootprint/docs/actions/waiting-for-the-app) |\n| **Keep the graph true** — a drift harness that fails in CI, not in front of a user, and a conformance check no source adapter can silently drop a declared field past | [Testing](https://footprintjs.github.io/hcifootprint/docs/reference/testing) |\n| **Adopt what you have** — routes, journeys or a live store as graph sources | [Graph sources](https://footprintjs.github.io/hcifootprint/docs/map/graph-sources) |\n| **React** — one hook per control, and a five-line port for any other framework | [React binding](https://footprintjs.github.io/hcifootprint/docs/actions/react-binding) |\n| **Tree-shakeable, ESM-first** — the sensor is 11.9 KB; the React hook 610 B | [Tree-shaking](https://footprintjs.github.io/hcifootprint/docs/reference/tree-shaking) |\n| **The gap ledger** — what the agent *couldn't* do, recorded, never hidden | [Grounding](https://footprintjs.github.io/hcifootprint/docs/actions/grounding) |\n\n---\n\n## Development\n\n```bash\nnpm install && npm test # the suite, with the badge gate\nnpm run build # dist/, ESM-first\nnpm run docs:truth # does the documentation describe what ships?\n```\n\n## Built on\n\n[footprintjs](https://github.com/footprintjs/footPrint) for the graph engine and commit log ·\n[agentfootprint](https://github.com/footprintjs/agentfootprint) if you want the agent loop too.\n\n## Citing\n\nSee [`CITATION.cff`](CITATION.cff), or use GitHub's **Cite this repository**.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}