Demos
Two runnable demo apps in the repo plus the three-commit dress shop — every one runs with no API key, no network, and behaves identically every time.
Every demo runs on a deterministic scripted model by default: no API key, no network, and the same behaviour every time. Pasting a key flips the same code path to a live model — nothing else changes.
In this repo — demos/
Onboarding wizard — the graph grows from what the app already had
A five-page signup wizard whose journey graph is not typed out by hand: it is grown from
the two descriptions the app already owned — a route table and a journey list — and its
navigation has no handlers at all (the navigate session option carries every url
gesture). The sources panel proves the sources are load-bearing by compiling throwaway
graphs on the spot and diffing them.
cd demos/onboarding-wizard
npm install
npm run dev # http://localhost:5173, no key needed
npm run verify # typecheck + tests + production buildThe wiring it demonstrates: Graph sources and Actuation & materialisation.
Live Desk — the actions arrive from the app's own store
A support inbox whose graph declares places — two pages, two tabs, a blocking compose
modal, a repeating ticket row — and not a single tool. Every action arrives at runtime from
the app's own action store, read in by fromLiveStore. Hide a control and its action stops
existing. Reach for a gesture nobody wired and the refusal names the gesture — the backlog
panel clusters it as a work item addressed to whoever owns that control.
cd demos/live-desk
npm run build --prefix ../.. # the demo links hcifootprint from the repo root
npm install
npm run dev # http://localhost:5173, no key needed
npm run verify # typecheck + tests + production buildThe wiring it demonstrates: Live bindings and the gesture words on refusals (Actuation).
After rebuilding the library, clear Vite's dep cache
Both demos link hcifootprint from the repo root, and Vite pre-bundles linked
dependencies into node_modules/.vite. That cache does not notice a fresh npm run build at
the root, so the dev server can keep serving the previous build — a change that "did not take
effect" when it did. Clear it:
rm -rf node_modules/.vite && npm run dev # or: npm run dev -- --forceRunnable examples — examples/
Smaller than a demo app and closer to a doc page: each one runs in plain node, prints a real transcript, and carries its own tests (Convention 2 — examples are integration tests).
npm run example:wizard # the guarded-journey transcript
npx vitest run examples/guarded-wizard # …and its proofsexamples/guarded-wizard is the source the Guarded journeys page is
written from: guarded steps, a greyed Next, a verify contract catching a handler that ran
and did nothing, the cross-link spine, and the facts block. examples/dress-shop is the
end-to-end mixed-initiative journey, plus a live Claude chatbot (npm run demo:chat, needs a
key).
The dress shop — the pitch as a diff
The dress-shop demo is a separate public
repo that tells the story in three commits: (1) a plain store built with zero knowledge of
any agent layer; (2) the agent layer — the declared graph plus three wires, with a git diff
of the app's own code that is empty; (3) an assistant (agentfootprint + Claude) driving
the same session with human-in-the-loop checkpointing on order placement.
git clone https://github.com/footprintjs/hcifootprint-demo && cd hcifootprint-demo/dress-shop
npm install
npm test # commits 1+2: the app's tests + the integration proof (no API key)
npm run chat # commit 3: the assistant in your terminal (needs ANTHROPIC_API_KEY)
npm run serve # the storefront in a browser — click OR chat, same session
npm run drift # watch the drift harness catch a deliberately-drifted graphThe adoption ladder
Start in read-only guide mode with zero handlers, then register handlers, then serve an agent — one authored graph carries you the whole way.
The navigation graph
buildNavigationGraph turns the container tree you already picture — pages, areas, tabs, modals, tools — into a validated, frozen graph with typed node paths.