KQ-2067 · FOOTPRINT/MAP

Footprint Map

A live map of a repository while agents work in it: folders and files laid out as a squarified treemap sized by file size, each working agent a marker that glides from file to file along a gentle arc on springs.glide as it reads and edits, its newest trail segment cut at the marker's own progress so the line is drawn out behind it, older files fading behind. Touched files are washed by read or write, by the last agent's colour or by heat; two active agents in one file open a soft warn ring on springs.snap with a possible-conflict chip, and a stalled agent holds still with a dashed ring. Tab moves through the agents, F follows the focused one and Enter opens the history of its file; the map is one tab stop whose arrow keys move spatially between files, and under 30rem the map gives way to a list of files ranked by activity.

KQ-2067 · FOOTPRINT/MAP

fernworks/web

3 agents · 9 files touched · 3 written

and 3 more touched files

Recent steps

13:58Reed edited CouponField.tsx
13:57Juno read cart.ts
13:56Reed read Input.tsx
13:55Ash edited coupons.md

3 agents in fernworks/web · 9 files touched

Open it on the Canvas stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/footprint-map

Props

files: FootprintFile[]; default defaultFootprintFiles (23); Every file in the repository as { path, size }; folders come from the paths and size sets each file's area.
agents: FootprintAgent[]; default defaultFootprintAgents (3); The agents working in it: { id, name, task, state?, tint? }. Idle agents are not drawn; stalled ones hold still with a dashed ring.
events: FootprintEvent[]; default defaultFootprintEvents (12); What they read and wrote, oldest first: { id, agent, path, op, at }. Each agent sits in the file of its newest event.
repo: string; default "fernworks/web"; The repository's name, in the header and as the region's accessible name.
now: number; default the newest event; The moment the map is read, in ms; stalls are counted from it.
utcOffset: number; default 0; Minutes added to UTC before a time is printed.
stallAfter: number; default 180000; An active agent whose newest step is older than this, in ms, reads as stalled.
follow / defaultFollow: string | null; default — / null; The followed agent: its trail and log come forward and the others dim.
onFollowAgent: (agentId: string | null) => void; default —; Fires from the press or key (F) that followed an agent or stopped following.
paused / defaultPaused: boolean; default — / false; Whether the agents are paused; the markers dim and the header says so.
onPause: (paused: boolean) => void; default —; Pause agents (or Resume agents) was pressed, with the new state.
onSelectFile: (path: string, history: FootprintEvent[]) => void; default —; A file's history was opened (Enter or a press), with its events newest first.
trailLength: number; default 3; How many of each agent's recent files stay joined by its trail; 0 draws markers only.
tint: "access" | "agent" | "heat"; default "access"; How touched files are washed: by read or write (with a pen mark), by the last agent's colour, or by how often they were touched.
accent: string; default "var(--accent-bright)"; Access and heat washes, the follow highlight and focus accents — any CSS colour.
mapHeight: number; default 260; The treemap's height, px.
status: "ready" | "loading" | "error"; default "ready"; Whether the repository has been read; loading draws placeholders, error offers Try again.
onReload: () => void; default —; Try again was pressed after the map failed to load.
disabled: boolean; default false; Read only: nothing can be followed, paused or opened.
className: string; default —; Classes for the outer region.

Prop	Type	Default	Description
files	FootprintFile[]	defaultFootprintFiles (23)	Every file in the repository as { path, size }; folders come from the paths and size sets each file's area.
agents	FootprintAgent[]	defaultFootprintAgents (3)	The agents working in it: { id, name, task, state?, tint? }. Idle agents are not drawn; stalled ones hold still with a dashed ring.
events	FootprintEvent[]	defaultFootprintEvents (12)	What they read and wrote, oldest first: { id, agent, path, op, at }. Each agent sits in the file of its newest event.
repo	string	"fernworks/web"	The repository's name, in the header and as the region's accessible name.
now	number	the newest event	The moment the map is read, in ms; stalls are counted from it.
utcOffset	number	0	Minutes added to UTC before a time is printed.
stallAfter	number	180000	An active agent whose newest step is older than this, in ms, reads as stalled.
follow / defaultFollow	string \| null	— / null	The followed agent: its trail and log come forward and the others dim.
onFollowAgent	(agentId: string \| null) => void	—	Fires from the press or key (F) that followed an agent or stopped following.
paused / defaultPaused	boolean	— / false	Whether the agents are paused; the markers dim and the header says so.
onPause	(paused: boolean) => void	—	Pause agents (or Resume agents) was pressed, with the new state.
onSelectFile	(path: string, history: FootprintEvent[]) => void	—	A file's history was opened (Enter or a press), with its events newest first.
trailLength	number	3	How many of each agent's recent files stay joined by its trail; 0 draws markers only.
tint	"access" \| "agent" \| "heat"	"access"	How touched files are washed: by read or write (with a pen mark), by the last agent's colour, or by how often they were touched.
accent	string	"var(--accent-bright)"	Access and heat washes, the follow highlight and focus accents — any CSS colour.
mapHeight	number	260	The treemap's height, px.
status	"ready" \| "loading" \| "error"	"ready"	Whether the repository has been read; loading draws placeholders, error offers Try again.
onReload	() => void	—	Try again was pressed after the map failed to load.
disabled	boolean	false	Read only: nothing can be followed, paused or opened.
className	string	—	Classes for the outer region.