Map & Walker

You declare the JourneyMap; the session is the Walker; the recording carries both.

That sentence is the whole model. The map is static data you author once — pages, the things inside them, the journeys worth finishing. The walker is the live session standing somewhere on it. And because every move goes through the session, the recording holds both halves: the map as declared, and the path actually walked over it.

Since 1.10.0 the two nouns have names in the API, as permanent aliases of the doors that have always been there:

Both names ship forever and neither is a rename: they are the same function object and the same type, so a codebase can speak either dialect, and a mixed codebase is not a mistake.

import { defineJourneyMap } from 'hcifootprint';
import type { JourneyMap } from 'hcifootprint';

const map: JourneyMap<'catalog' | 'checkout'> = defineJourneyMap('shop', {
  pages: {
    catalog: {
      route: '/catalog',
      actions: {
        'add-to-cart': { does: 'Add the open dress to the cart', writes: ['cart.items'] },
        'go-checkout': { does: 'Go to checkout', goTo: 'checkout' },
      },
    },
    checkout: {
      route: '/checkout',
      actions: {
        'place-order': { does: 'Place the order', enabledWhen: { 'cart.items': { gt: 0 } } },
      },
    },
  },
  journeys: { purchase: { does: 'Buy a dress end to end', steps: ['add-to-cart', 'place-order'] } },
});

const walker = map.createSession({ node: 'catalog' }); // the walker IS the session

There is no Walker to construct

The library exports no Walker object, and that is deliberate. A walker is not a thing you wire up — it is the session you already create, standing on a node, moving. Exporting a synonym for it would turn a way of reading the library into a second runtime object to keep in step with the first.

The three movers

A cursor only ever moves for three reasons, and each one is recorded as a Cause — kind (was an offered edge fired, or did the world move?) plus principal (whose move was it?).

And a fourth thing that is not a mover, because nobody chose it: the world moves on its own — a back button, a server push, a session expiry. That is Cause.kind: 'stimulus', recorded rather than silently absorbed, because a cursor that moved without an offered edge is exactly what an agent must not be allowed to miss.

Where the reader is: page, container, state

Sync pages; observe the deeper place. sync() moves the walker and decides what is served; observeFocus() says which tab or area the reader is in. Declare containers, and report the deepest one on screen.

Position has three tiers, and each has exactly one door.

The container tier is the one that gets skipped, because nothing forces it: declaring tabs: compiles, mounts, masks and narrows guards perfectly well while never once saying which tab the person is looking at. Declaring a container gives you mount-tracking; observing it is what gives you position.

And it has to be its own door. A tab is not a place the walker can stand — actions are served from the page, so a cursor parked on run-detail.why would be served nothing at all. Nor could a fire carry it: focus used to move only on fire() and sync(), and a person clicking a tab fires nothing, which is exactly the case worth reporting.

The same session, told two ways

import { defineJourneyMap } from 'hcifootprint';

const map = defineJourneyMap('runs', {
  pages: {
    'run-detail': {
      route: '/runs/:id',
      actions: { export: { does: 'Export this run as JSON', writes: ['run.exported'] } },
      tabs: {
        why: { does: 'Why this step ran', actions: { 'open-slice': { does: 'Open the causal slice' } } },
        timeline: { does: 'The run timeline', actions: { scrub: { does: 'Scrub to a step' } } },
      },
    },
  },
});

const session = map.createSession({ node: 'run-detail' });

// COARSE — the router reported the page, and nothing reported the tab.
session.sync('run-detail');

// DEEPEST — your own tab handler, reporting both facts about the tab it opened.
function onTabChange(tab: 'why' | 'timeline') {
  session.show(`run-detail.${tab}`); //                            which tab is VISIBLE
  session.observeFocus(`run-detail.${tab}`, { principal: 'user' }); // where the READER is
}

What the model is handed, page-only:

You are on: run-detail.
No actions have been performed in this app this session.

…and with the deepest container observed:

You are on: run-detail.
Focus: run-detail.why.
No actions have been performed in this app this session.

Every served answer carries the same two halves as data — youAreOn is the page that serves, and lookingAt is the deeper place, present only when there is one:

{ "youAreOn": "run-detail", "lookingAt": "run-detail.why" }

Without that, a screen-driving agent has to deduce the open tab from whatever unlabelled state keys happen to move, and every turn it spends deducing is a turn it does not spend acting.

Three facts, three doors

show(), observeFocus() and sync() answer different questions, and an app that flips a tab reports the first two:

observeFocus refuses by name rather than guessing: a node this map does not declare, and a node belonging to another page (sync that page first). Observing the page itself says the reader came back up with no container open. A container the app also says is hidden — a closed modal, a tab whose sibling is shown — is walked home to the nearest place that is really there, because a closed modal cannot hold anyone.

Hand sync() a container path and it does the safe thing rather than the literal one: it syncs the page that owns the container and warns once, naming observeFocus. Before 1.11.0 that call put the cursor off-graph — a session that served nothing, silently. An undeclared path is still honest: the cursor follows reality off-graph, exactly as it always has.

"system unknown changed: …" — the other half of the same symptom

When in-page position rides an ordinary state key, this is what the model reads in the session ledger:

system unknown changed: runDetail.activeTab, runDetail.selectedStep

That line is the honest floor for a report that named no stimulus and no principal: the world moved, nobody said who or why, and the key names are all anyone gets. The first cure is the rule above — report position as position, so the tab stops riding a state key at all.

The CI half

lintGraph reads the map alone and can never see a runtime call, so it proves the half that is authored: a tab no declared control can put the cursor inside — nothing lives in it, and nothing binds to it as a tab switch — on a page that authors controls beside it. That is the unevidenceable-tab note (advisory, never an error: an app that observes its tabs has already handled it). See the drift harness.

The five things a walker does

Nothing on this list is new machinery. It is the same five moves any walker makes, and the column on the right is what already answers each one.

The honesty backstop under the last row is the drift sensor: lintGraph and checkGraph fail in CI when the map has drifted from the app, because a walker that verifies against a stale map is verifying against fiction.

The same pattern, at three altitudes

footprintjs walks stages, agentfootprint (defineSkillMap) walks skills, and this walks screens — one declared map, one walker on it, one recording that carries both.