Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

fix(ui): make the Architecture Refresh buttons say what they did (A3)

Bernhard Jackiewicz91d47cb187ab
diff --git a/graph-ui/src/architecture/BehaviorJourney.tsx b/graph-ui/src/architecture/BehaviorJourney.tsx
index 2437c444b..ae02f71d8 100644
--- a/graph-ui/src/architecture/BehaviorJourney.tsx
+++ b/graph-ui/src/architecture/BehaviorJourney.tsx
@@ -7,6 +7,7 @@ import { useLiftedPlace, useOnIdentityChange } from './lifted-place';
import type { SystemProjection, SystemSymbol } from './system-architecture-source';
import BehaviorSourceEvidence, { type BehaviorSourceSnapshot } from './BehaviorSourceEvidence';
import { useSelectionEvidence, type SelectionEvidenceListener } from '../galaxy/selection-evidence';
+import { RefreshControl, type RefreshFeedback } from './refresh-feedback';
import './behavior-journey.css';
const Scene = lazy(() => import('./SystemArchitectureScene'));
@@ -28,6 +29,8 @@ export interface BehaviorJourneyProps {
onClearSelection?: () => void;
onSelectionEvidence?: SelectionEvidenceListener;
onRefresh: () => void; onSelectSymbol: (symbol: SystemSymbol) => void;
+ /** What the last Refresh did, shown beside its button (hand test 2026-10-04, A3). */
+ refresh?: RefreshFeedback;
onNavigate: (path: string, line?: number, name?: string) => void;
}
@@ -53,7 +56,7 @@ export function journeyPage(scene: SystemSceneModel, step: number, choices = fal
}
export default function BehaviorJourney({ project, generation, data, entries, targets, entryId, targetId, active, pending, error, filter,
- onRequest, onRefresh, onSelectSymbol, onNavigate, onClearSelection, onSelectionEvidence, from, place: liftedPlace, onPlace, onShownStart }: BehaviorJourneyProps) {
+ onRequest, onRefresh, refresh, onSelectSymbol, onNavigate, onClearSelection, onSelectionEvidence, from, place: liftedPlace, onPlace, onShownStart }: BehaviorJourneyProps) {
const [place, changePlace] = useLiftedPlace<JourneyPlace>(liftedPlace, onPlace, () => ({}));
const { path: pathIndex = 0, step = 0, page: branchPage = 0, planar = false } = place;
const [overview, setOverview] = useState(false);
@@ -160,7 +163,7 @@ export default function BehaviorJourney({ project, generation, data, entries, ta
<header className="behavior-heading"><div><span className="system-eyebrow">Behavior · source-guided exploration</span>
<h2>{targetId !== undefined ? `${entry?.name ?? 'Operation'} → ${selectedTarget?.name ?? 'destination'}` : `What can ${entry?.name ?? 'this operation'} call?`}</h2>
<p>{path ? 'Follow one recorded call chain across the parts it touches.' : 'Choose a starting operation. Explore its calls, or follow a path to a destination.'}</p></div>
- <button onClick={onRefresh}>Refresh</button></header>
+ <RefreshControl labels={text.refreshFeedback.behavior} feedback={refresh} onRefresh={onRefresh} /></header>
<div className="behavior-requests">
{/* The field names the operation the journey shows, also when the projection chose it. */}
<label>Start <select aria-label="Behavior entry point" value={entry?.id ?? ''} onChange={event => request(availableEntries.find(item => item.id === Number(event.target.value)))}>
diff --git a/graph-ui/src/architecture/ContainerMap.test.tsx b/graph-ui/src/architecture/ContainerMap.test.tsx
index 39f1ad1d3..7a02a6031 100644
--- a/graph-ui/src/architecture/ContainerMap.test.tsx
+++ b/graph-ui/src/architecture/ContainerMap.test.tsx
@@ -75,3 +75,41 @@ describe('service map interactions', () => {
expect(loadContainerTopology).not.toHaveBeenCalled(); expect(loadContainerInventory).not.toHaveBeenCalled();
});
});
+
+/* Hand test 2026-10-04 (A3): a Refresh that reads everything again says so, and says what it found. */
+describe('service map refresh feedback', () => {
+ const refresh = () => [...container.querySelectorAll('button')].find(element => /^Refresh(ing…)?$/.test(element.textContent ?? ''))!;
+ const status = () => container.querySelector('[role="status"].atlas-arch-refresh-status')?.textContent;
+ afterEach(() => { vi.useRealTimers(); });
+
+ it('A3: reads the declared services again, busy meanwhile, then names the time and whether anything changed', async () => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(new Date(2026, 9, 4, 9, 5, 7));
+ await act(async () => root.render(<ContainerMap project="p" active filter="" onNavigate={vi.fn()} />));
+ let finish!: (value: ContainerReading) => void;
+ vi.mocked(loadContainerTopology).mockImplementationOnce(() => new Promise(resolve => { finish = resolve; }));
+ await act(async () => refresh().click());
+ expect(refresh().textContent).toBe('Refreshing…');
+ expect(refresh().getAttribute('aria-disabled')).toBe('true');
+ await act(async () => finish(sample()));
+ expect(refresh().textContent).toBe('Refresh');
+ expect(status()).toBe('Up to date at 09:05:07: no changes since the last load');
+ const changed = sample();
+ changed.topology.services.pop();
+ vi.mocked(loadContainerTopology).mockResolvedValueOnce(changed);
+ await act(async () => refresh().click());
+ expect(status()).toBe('Service map refreshed at 09:05:07');
+ });
+
+ it('A3: also answers for a project without deployment files', async () => {
+ vi.mocked(loadContainerInventory).mockResolvedValue({ project: 'p', rootPath: '/p', files: new Map(), manifests: [], warnings: [] });
+ await act(async () => root.render(<ContainerMap project="p" active filter="" onNavigate={vi.fn()} />));
+ let finish!: (value: Awaited<ReturnType<typeof loadContainerInventory>>) => void;
+ vi.mocked(loadContainerInventory).mockImplementationOnce(() => new Promise(resolve => { finish = resolve; }));
+ await act(async () => refresh().click());
+ expect(refresh().textContent).toBe('Refreshing…');
+ await act(async () => finish({ project: 'p', rootPath: '/p', files: new Map(), manifests: [], warnings: [] }));
+ expect(refresh().textContent).toBe('Refresh');
+ expect(status()).toMatch(/^Up to date at \d\d:\d\d:\d\d: no changes since the last load$/);
+ });
+});
diff --git a/graph-ui/src/architecture/ContainerMap.tsx b/graph-ui/src/architecture/ContainerMap.tsx
index 8d67d33b4..65685f488 100644
--- a/graph-ui/src/architecture/ContainerMap.tsx
+++ b/graph-ui/src/architecture/ContainerMap.tsx
@@ -7,6 +7,7 @@ import { loadContainerInventory, loadContainerTopology, type ContainerReading, t
import type { ServiceEvidence } from './container-topology';
import { useSelectionEvidence, type SelectionEvidenceListener } from '../galaxy/selection-evidence';
import { architectureText as text } from './strings';
+import { RefreshControl, useRefreshFeedback } from './refresh-feedback';
import './spatial-architecture.css';
import './container-map.css';
@@ -32,6 +33,8 @@ export default function ContainerMap({ project, generation, active, filter, onNa
const [available, setAvailable] = useState<ProjectEntry[]>([]);
const [selections, setSelections] = useState<ContainerSelection[]>([]);
const [discovery, setDiscovery] = useState<Discovery>('reading');
+ /** The `discoveryRevision` the current `discovery` answers, so a refresh can tell its own answer from the earlier one. */
+ const [discovered, setDiscovered] = useState<number>();
const [reading, setReading] = useState<{ key: string; result?: ContainerReading; error?: string }>();
const [revision, setRevision] = useState(0);
const [discoveryRevision, setDiscoveryRevision] = useState(0);
@@ -55,12 +58,21 @@ export default function ContainerMap({ project, generation, active, filter, onNa
const inventory = await loadContainerInventory(current, client);
if (controller.signal.aborted) return;
setAvailable(projects); setSelections([{ inventory, manifest: inventory.manifests[0] ?? '' }]);
- setDiscovery(inventory.manifests.length ? undefined : 'none');
- }).catch(() => { if (!controller.signal.aborted) setDiscovery('failed'); });
+ setDiscovery(inventory.manifests.length ? undefined : 'none'); setDiscovered(discoveryRevision);
+ }).catch(() => { if (!controller.signal.aborted) { setDiscovery('failed'); setDiscovered(discoveryRevision); } });
return () => controller.abort();
}, [project, active, generation, discoveryRevision]);
const selectionKey = JSON.stringify(selections.map(item => [item.inventory.project, item.manifest]));
const key = `${project}:${generation ?? ''}:${selectionKey}:${revision}`;
+ // Settled once the inventory answered this revision and, when a Compose file is chosen, its services were read.
+ const readsTopology = selections.some(item => item.manifest);
+ const topologyReading = reading?.key === key ? reading : undefined;
+ const shownTopology = topologyReading?.result?.topology;
+ const shown = useMemo(() => [discovery, shownTopology], [discovery, shownTopology]);
+ const refresh = useRefreshFeedback({ key: `${key}:${discoveryRevision}`,
+ settled: discovered === discoveryRevision && discovery !== 'reading' && (!readsTopology || Boolean(topologyReading?.result || topologyReading?.error)),
+ value: shown,
+ error: discovery === 'failed' ? text.serviceMap.failed : topologyReading?.error });
useEffect(() => {
if (!active || !selections.length || selections[0].inventory.project !== project || !selections.some(item => item.manifest)) return;
const controller = new AbortController(), client = new RpcIntelligenceClient({ signal: controller.signal });
@@ -137,10 +149,11 @@ export default function ContainerMap({ project, generation, active, filter, onNa
<header className="spatial-heading"><div><span className="spatial-eyebrow">Routes / Services</span><h2>How the services connect</h2>
<p>One square per declared service. Follow a connection to see the configuration and code behind it.</p></div>
<div className="spatial-camera-controls"><button aria-pressed={!planar} onClick={() => setPlanar(false)}>3D</button><button aria-pressed={planar} onClick={() => setPlanar(true)}>Plan</button>
- <button onClick={() => setResetKey(value => value + 1)}>Fit map</button><button onClick={() => {
+ <button onClick={() => setResetKey(value => value + 1)}>Fit map</button><RefreshControl labels={text.refreshFeedback.services} feedback={refresh.feedback} onRefresh={() => {
+ refresh.begin();
setRevision(value => value + 1);
if (!selections.length || !selections[0].inventory.manifests.length) setDiscoveryRevision(value => value + 1);
- }}>Refresh</button></div></header>
+ }} /></div></header>
<div className="container-projects" aria-label="Deployment sources">{selections.map((selection, index) => <label key={selection.inventory.project}><span>{selection.inventory.project}</span>
<select aria-label={`Compose file for ${selection.inventory.project}`} value={selection.manifest} onChange={event => setSelections(current => current.map((item, i) => i === index ? { ...item, manifest: event.target.value } : item))}>
<option value="">Source only</option>{selection.inventory.manifests.map(path => <option key={path}>{path}</option>)}</select>
diff --git a/graph-ui/src/architecture/SpatialArchitecture.test.tsx b/graph-ui/src/architecture/SpatialArchitecture.test.tsx
index d5355316c..cc3448b12 100644
--- a/graph-ui/src/architecture/SpatialArchitecture.test.tsx
+++ b/graph-ui/src/architecture/SpatialArchitecture.test.tsx
@@ -198,3 +198,45 @@ it('focuses an aggregated hotspot area and restores all areas on empty backgroun
expect(host.querySelector('[aria-label="Hotspot area"]')).toBeNull();
expect(host.querySelector('input[type="search"]')).toBeNull();
});
+/*
+ * Hand test 2026-10-04 (A3): "Refresh connections" fetched everything again and nothing on screen changed. Now the
+ * button says it runs, the map keeps the connections it shows meanwhile, and a status names the time and the result.
+ */
+it('A3: Refresh connections says that it runs and what it found, and keeps the map while it runs', async () => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ try {
+ vi.setSystemTime(new Date(2026, 9, 4, 13, 45, 12));
+ const route: GraphNode = { id: 2, label: 'Route', name: '/api/', qualified_name: 'sample.route.2', file_path: 'app/urls.py', x: 0, y: 0, z: 0, size: 1, color: '' };
+ const input: GraphData = { nodes: [node, route], edges: [], total_nodes: 2 };
+ await act(async () => root.render(<SpatialArchitecture project="sample" graph={input} overview={overview} view="routes" filter="" active onNavigate={vi.fn()} onView={vi.fn()} />));
+ const refresh = () => [...host.querySelectorAll('button')].find(button => /^Refresh(ing)? connections/.test(button.textContent ?? ''))!;
+ const status = () => host.querySelector('[role="status"].atlas-arch-refresh-status')?.textContent;
+ expect(refresh().textContent).toBe('Refresh connections');
+ expect(status()).toBe('');
+
+ let finish!: (value: Awaited<ReturnType<typeof loadRouteGraph>>) => void;
+ vi.mocked(loadRouteGraph).mockImplementationOnce(() => new Promise(resolve => { finish = resolve; }));
+ await act(async () => refresh().click());
+ expect(refresh().textContent).toBe('Refreshing connections…');
+ expect(refresh().getAttribute('aria-disabled')).toBe('true');
+ // The map keeps what it shows; it does not fall back to "reading" while the refresh runs.
+ expect(host.textContent).not.toContain('Reading indexed endpoint connections…');
+ expect(host.textContent).not.toContain('(checking…)');
+ // A second press while it runs starts nothing.
+ await act(async () => refresh().click());
+ expect(loadRouteGraph).toHaveBeenCalledTimes(2);
+ await act(async () => finish({ relationships: [], truncated: false, warnings: [] }));
+ expect(refresh().textContent).toBe('Refresh connections');
+ expect(refresh().getAttribute('aria-disabled')).toBeNull();
+ expect(status()).toBe('Up to date at 13:45:12: no changes since the last load');
+
+ vi.setSystemTime(new Date(2026, 9, 4, 13, 46, 3));
+ vi.mocked(loadRouteGraph).mockResolvedValueOnce({ relationships: [{ source: route, target: node, type: 'HANDLES', id: 7 }], truncated: false, warnings: [] });
+ await act(async () => refresh().click());
+ expect(status()).toBe('Connections refreshed at 13:46:03');
+
+ vi.mocked(loadRouteGraph).mockRejectedValueOnce(new Error('daemon unavailable'));
+ await act(async () => refresh().click());
+ expect(status()).toBe('Refresh failed at 13:46:03: daemon unavailable');
+ } finally { vi.useRealTimers(); }
+});
diff --git a/graph-ui/src/architecture/SpatialArchitecture.tsx b/graph-ui/src/architecture/SpatialArchitecture.tsx
index ac2f0377e..f838625ff 100644
--- a/graph-ui/src/architecture/SpatialArchitecture.tsx
+++ b/graph-ui/src/architecture/SpatialArchitecture.tsx
@@ -15,6 +15,7 @@ import type { CoverageIndex } from '../app/tree-model';
import { buildHotspotGraph, collectHotspots, hotspotsForNode, hotspotSignals, hotspotIdentity } from './hotspot-map';
import { hotspotAreas } from './hotspot-areas';
import { useViewPreferences } from '../settings/view-preferences';
+import { RefreshControl, useRefreshFeedback } from './refresh-feedback';
import './spatial-architecture.css';
interface Props {
@@ -67,29 +68,36 @@ export default function SpatialArchitecture({ project, generation, graph, overvi
const [inventoryLimit, setInventoryLimit] = useState(24);
const [resetKey, setResetKey] = useState(0);
const [selection, setSelection] = useState<{ scope: string; node?: string; edge?: string }>();
- const [routeReading, setRouteReading] = useState<{ key: string; snapshot?: RouteGraphSnapshot; error?: string }>();
+ const [routeReading, setRouteReading] = useState<{ key: string; base?: string; snapshot?: RouteGraphSnapshot; error?: string; refreshing?: boolean }>();
const [routeRevision, setRouteRevision] = useState(0);
const [memberLimit, setMemberLimit] = useState(5);
const [includeTestRoutes, setIncludeTestRoutes] = useState(false);
// A reindex clears the hotspot area; a view that mounts again keeps the place it is handed.
useOnIdentityChange(`${project}:${generation ?? ''}`, () => { if (place.hotspotArea) changePlace({ hotspotArea: undefined }, true); });
- const routeKey = `${project}:${generation ?? ''}:${routeRevision}`;
+ const routeBase = `${project}:${generation ?? ''}`;
+ const routeKey = `${routeBase}:${routeRevision}`;
useEffect(() => {
if (view !== 'routes' || !active) return;
const controller = new AbortController();
- setRouteReading({ key: routeKey });
+ // A refresh of the same index keeps the connections on screen until the new ones arrive (hand test 2026-10-04, A3).
+ const kept = (current?: typeof routeReading) => current?.base === routeBase && current.snapshot ? { snapshot: current.snapshot } : {};
+ setRouteReading(current => ({ key: routeKey, base: routeBase, ...kept(current), refreshing: true }));
void loadRouteGraph(project, { signal: controller.signal }).then(snapshot => {
- if (!controller.signal.aborted) setRouteReading({ key: routeKey, snapshot });
+ if (!controller.signal.aborted) setRouteReading({ key: routeKey, base: routeBase, snapshot });
}).catch((error: unknown) => {
- if (!controller.signal.aborted) setRouteReading({ key: routeKey, error: error instanceof Error ? error.message : String(error) });
+ const message = error instanceof Error ? error.message : String(error);
+ if (!controller.signal.aborted) setRouteReading(current => ({ key: routeKey, base: routeBase, ...kept(current), error: message }));
});
return () => controller.abort();
- }, [project, routeKey, view, active]);
+ }, [project, routeKey, routeBase, view, active]);
+ const routeRefresh = useRefreshFeedback({ key: routeKey, settled: routeReading?.key === routeKey && !routeReading.refreshing,
+ value: routeReading?.key === routeKey ? routeReading.snapshot : undefined, error: routeReading?.key === routeKey ? routeReading.error : undefined });
const entries = useMemo(() => semanticEntryPoints(graph, overview.entryPoints.flatMap(entry => entry.qualifiedName ? [entry.qualifiedName] : [])), [graph, overview.entryPoints]);
const currentEntry = entries.find(node => entryChoice?.node.qualified_name
? node.qualified_name === entryChoice.node.qualified_name && node.file_path === entryChoice.node.file_path
: entryChoice?.generation === generation && node.id === entryChoice?.node.id && node.file_path === entryChoice.node.file_path) ?? entries[0];
- const routeSnapshot = routeReading?.key === routeKey ? routeReading.snapshot : undefined;
+ // A refresh of the same index shows the earlier connections until its own arrive.
+ const routeSnapshot = routeReading?.base === routeBase ? routeReading.snapshot : undefined;
// Which routes are test code is decided by their registration, handler and caller evidence.
const routesChecking = view === 'routes' && !routeSnapshot && !(routeReading?.key === routeKey && routeReading.error);
const knownFiles = useMemo(() => [...new Set([...overview.files, ...[...(coverage?.records.values() ?? [])].filter(record => record.kind === 'file').map(record => record.path)])], [overview.files, coverage]);
@@ -188,7 +196,8 @@ export default function SpatialArchitecture({ project, generation, graph, overvi
{!entries.length && <option value="">No indexed entry points</option>}{entries.map(node => <option key={node.id} value={node.id}>{node.name} · {node.file_path}</option>)}
</select></label><label>Call depth <select aria-label="Call depth" value={depth} onChange={event => setDepth(Number(event.target.value))}>{[1, 2, 3, 4].map(value => <option key={value}>{value}</option>)}</select></label></>}
{view === 'hotspots' && hotspotArea && <nav aria-label="Hotspot area"><button onClick={clearScope}>All hotspots</button><span>/ {hotspotArea}</span></nav>}
- {view === 'routes' && <button onClick={() => setRouteRevision(value => value + 1)}>Refresh connections</button>}
+ {view === 'routes' && <RefreshControl labels={text.refreshFeedback.routes} feedback={routeRefresh.feedback}
+ onRefresh={() => { routeRefresh.begin(); setRouteRevision(value => value + 1); }} />}
{view === 'routes' && <label className="spatial-gravity-toggle"><input type="checkbox" checked={includeTestRoutes} onChange={event => { setIncludeTestRoutes(event.target.checked); setSelection(undefined); }} />{routesChecking ? text.includeTestRoutesChecking : text.includeTestRoutes(model.hiddenRoutes ?? 0)}</label>}
{filePath && (view === 'overview' || view === 'dependencies') && <button onClick={() => onNavigate(filePath, 1)}>Read this file</button>}
{(view === 'overview' || view === 'dependencies') && <div className="spatial-relations" role="group" aria-label="Relationship types">
diff --git a/graph-ui/src/architecture/SystemArchitecture.test.tsx b/graph-ui/src/architecture/SystemArchitecture.test.tsx
index edbe55504..c5b6dcbc8 100644
--- a/graph-ui/src/architecture/SystemArchitecture.test.tsx
+++ b/graph-ui/src/architecture/SystemArchitecture.test.tsx
@@ -595,3 +595,49 @@ describe('system architecture workspace', () => {
expect(container.querySelector('[role="alert"]')?.textContent).toContain('Analysis budget exceeded'); expect(loader).toHaveBeenCalledTimes(1);
});
});
+
+/* Hand test 2026-10-04 (A3): "Refresh analysis" and the Behavior "Refresh" read again and said nothing. */
+describe('system architecture refresh feedback', () => {
+ const refresh = (pattern: RegExp) => [...container.querySelectorAll('button')].find(element => pattern.test(element.textContent ?? ''))!;
+ const status = () => container.querySelector('[role="status"].atlas-arch-refresh-status')?.textContent;
+ afterEach(() => { vi.useRealTimers(); });
+
+ it('A3: Refresh analysis is busy while it runs, then names the time and whether the index changed', async () => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(new Date(2026, 9, 4, 18, 0, 9));
+ const loader = vi.fn<SystemArchitectureLoader>().mockResolvedValue(response(overviewFixture()));
+ await render(loader);
+ let finish!: (value: SystemArchitectureResponse) => void;
+ loader.mockImplementationOnce(() => new Promise(resolve => { finish = resolve; }));
+ await act(async () => refresh(/^Refresh(ing)? analysis/).click());
+ expect(refresh(/^Refresh(ing)? analysis/).textContent).toBe('Refreshing analysis…');
+ expect(refresh(/^Refresh(ing)? analysis/).getAttribute('aria-disabled')).toBe('true');
+ // The structure stays on screen meanwhile.
+ expect(container.querySelector('[data-testid="system-scene"]')).not.toBeNull();
+ await act(async () => finish(response(overviewFixture())));
+ expect(refresh(/^Refresh(ing)? analysis/).textContent).toBe('Refresh analysis');
+ expect(status()).toBe('Up to date at 18:00:09: no changes since the last load');
+ loader.mockResolvedValueOnce({ ...response(overviewFixture()), generation: 'g2' });
+ await act(async () => refresh(/^Refresh(ing)? analysis/).click());
+ expect(status()).toBe('Analysis refreshed at 18:00:09');
+ loader.mockRejectedValueOnce(new Error('Daemon stopped.'));
+ await act(async () => refresh(/^Refresh(ing)? analysis/).click());
+ expect(status()).toBe('Refresh failed at 18:00:09: Daemon stopped.');
+ });
+
+ it('A3: the Behavior Refresh says the same beside its button', async () => {
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(new Date(2026, 9, 4, 18, 1, 0));
+ const loader = vi.fn<SystemArchitectureLoader>().mockResolvedValue(response(overviewFixture()));
+ await render(loader, { view: 'behavior' });
+ const button = () => container.querySelector<HTMLButtonElement>('.behavior-heading .atlas-arch-refresh button')!;
+ expect(button()?.textContent).toBe('Refresh');
+ let finish!: (value: SystemArchitectureResponse) => void;
+ loader.mockImplementationOnce(() => new Promise(resolve => { finish = resolve; }));
+ await act(async () => button().click());
+ expect(button().textContent).toBe('Refreshing…');
+ await act(async () => finish(response(overviewFixture())));
+ expect(button().textContent).toBe('Refresh');
+ expect(container.querySelector('.behavior-heading [role="status"]')?.textContent).toBe('Up to date at 18:01:00: no changes since the last load');
+ });
+});
diff --git a/graph-ui/src/architecture/SystemArchitecture.tsx b/graph-ui/src/architecture/SystemArchitecture.tsx
index 8a6afe080..0af327d75 100644
--- a/graph-ui/src/architecture/SystemArchitecture.tsx
+++ b/graph-ui/src/architecture/SystemArchitecture.tsx
@@ -10,6 +10,7 @@ import type { FlowSummary } from '../traces/trace-schemas';
import BehaviorJourney from './BehaviorJourney';
import type { BehaviorPlace, JourneyPlace, PlaceChange, SystemPlace } from './architecture-history';
import { useLiftedPlace, useOnIdentityChange } from './lifted-place';
+import { RefreshControl, useRefreshFeedback } from './refresh-feedback';
import './system-architecture.css';
const Scene = lazy(() => import('./SystemArchitectureScene'));
@@ -159,6 +160,9 @@ export default function SystemArchitecture({ project, generation, view, filter,
});
const structureData = useMemo(() => data ? { ...data, dependencies: data.dependencies.filter(edge => connectionAllowed(edge.type, connectionView)) } : undefined, [data, connectionView]);
const error = current?.error ?? (current?.response?.status === 'failed' ? current.response.error ?? 'Architecture analysis failed.' : undefined);
+ /* Refresh analysis and the Behavior Refresh say what they did (hand test 2026-10-04, A3). The same index answers with the same generation. */
+ const refresh = useRefreshFeedback({ key: requestKey, settled: Boolean(current) && !queryPending, value: current?.response?.generation, error });
+ const refreshAnalysis = () => { refresh.begin(); setRevision(value => value + 1); };
const chosenEntries = entryChoices?.project === project && entryChoices.generation === generation ? entryChoices.entries : data?.entrypoints ?? [];
// With no or only a handful of classified entry points (limited projections, Python without main, a few
// route handlers) the ranked flows add their starts after the classified ones.
@@ -318,7 +322,7 @@ export default function SystemArchitecture({ project, generation, view, filter,
}, automatic);
const behaviorPage = view === 'behavior' ? <BehaviorJourney project={project} generation={projectionGeneration} data={queryData}
entries={entries} targets={targets} entryId={requestedEntry} targetId={requestedTarget} active={active} pending={queryPending}
- error={error} filter={filter} onRefresh={() => setRevision(value => value + 1)} onNavigate={onNavigate} onSelectSymbol={selectSymbol} onClearSelection={onClearSelection} onSelectionEvidence={onSelectionEvidence}
+ error={error} filter={filter} onRefresh={refreshAnalysis} refresh={refresh.feedback} onNavigate={onNavigate} onSelectSymbol={selectSymbol} onClearSelection={onClearSelection} onSelectionEvidence={onSelectionEvidence}
from={requestedEntry !== undefined ? entryChoice?.from : undefined} place={journeyPlace} onPlace={changeJourney}
onShownStart={name => { if (name !== place.shown) changePlace({ shown: name }, true); }}
onRequest={(entry, targetId, detail) => {
@@ -332,7 +336,8 @@ export default function SystemArchitecture({ project, generation, view, filter,
return <section className="system-architecture" data-testid="system-architecture" aria-label={view === 'structure' ? 'System structure' : 'Behavior'} aria-busy={active && pending}>
<div className="system-toolbar">
<p>{view === 'structure' ? 'Inspect the parts and the code that connects them.' : 'Follow a question through the same system map.'}</p>
- <button className="atlas-arch-action system-refresh" onClick={() => { setRevision(value => value + 1); setResetKey(value => value + 1); }}>Refresh analysis</button>
+ <RefreshControl className="atlas-arch-action system-refresh" labels={text.refreshFeedback.structure} feedback={refresh.feedback}
+ onRefresh={() => { refreshAnalysis(); setResetKey(value => value + 1); }} />
</div><div className="system-controls">
<div className="system-scope-actions"><button disabled={!focusId} onClick={clearSelection}>Whole system</button></div>
{view === 'structure' && <label>Connections <select aria-label="Connection view" value={connectionView} onChange={event => { setConnectionView(event.target.value as ConnectionView); setCyclesOnly(false); }}>
diff --git a/graph-ui/src/architecture/architecture.css b/graph-ui/src/architecture/architecture.css
index 66ba9422b..ab6f8dcca 100644
--- a/graph-ui/src/architecture/architecture.css
+++ b/graph-ui/src/architecture/architecture.css
@@ -78,6 +78,12 @@
.atlas-arch-recent-menu button:hover:not(:disabled) { background: var(--atlas-panel-raised); }
.atlas-arch-recent-menu button span { max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 11px; color: var(--atlas-dim); }
.atlas-arch-recent-menu button[aria-current="true"] { opacity: 0.6; }
+/* Hand test 2026-10-04 (A3): a Refresh says that it runs and, beside it, what it found. The live region stays in the tree. */
+.atlas-arch-refresh { display: inline-flex; align-items: center; flex-wrap: wrap; min-width: 0; }
+.atlas-arch-refresh > button[aria-disabled="true"] { opacity: 0.6; cursor: progress; }
+.atlas-arch-refresh-status { color: var(--atlas-dim); font-size: 11px; line-height: 1.4; }
+.atlas-arch-refresh-status:not(:empty) { margin-left: 8px; }
+.atlas-arch-refresh-status[data-phase="failed"] { color: var(--atlas-alarm); }
.atlas-arch-toolbar { margin-bottom: 24px; gap: 10px; }
.atlas-arch-filter { position: relative; flex: 1; max-width: 370px; }
.atlas-arch-filter svg { color: var(--atlas-dim); left: 11px; position: absolute; top: 10px; pointer-events: none; }
diff --git a/graph-ui/src/architecture/behavior-journey.css b/graph-ui/src/architecture/behavior-journey.css
index 410ff50b2..6ed94e177 100644
--- a/graph-ui/src/architecture/behavior-journey.css
+++ b/graph-ui/src/architecture/behavior-journey.css
@@ -3,7 +3,7 @@
.behavior-heading h2 { font-size: 25px; font-weight: 500; letter-spacing: -.6px; margin: 7px 0; overflow-wrap: anywhere; }
.behavior-heading p { color: var(--atlas-dim); font-size: 12px; margin: 0; }
.behavior-journey button { cursor: pointer; }
-.behavior-heading > button, .behavior-navigation > button, .behavior-inspector-actions button, .behavior-walk button, .behavior-visual-toolbar > button, .behavior-source-heading button { background: var(--journey-tint); color: var(--arch-label-text); border: 1px solid var(--journey-line); border-radius: 6px; padding: 6px 10px; font: inherit; font-size: 11px; }
+.behavior-heading > button, .behavior-heading > .atlas-arch-refresh > button, .behavior-navigation > button, .behavior-inspector-actions button, .behavior-walk button, .behavior-visual-toolbar > button, .behavior-source-heading button { background: var(--journey-tint); color: var(--arch-label-text); border: 1px solid var(--journey-line); border-radius: 6px; padding: 6px 10px; font: inherit; font-size: 11px; }
.behavior-journey button:disabled { opacity: .35; cursor: default; }
.behavior-journey button:focus-visible { outline: 2px solid var(--arch-label-focus); outline-offset: 3px; }
.behavior-requests { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; padding: 12px; border: 1px solid var(--journey-line); border-radius: 10px; background: var(--journey-tint); }
diff --git a/graph-ui/src/architecture/refresh-feedback.test.tsx b/graph-ui/src/architecture/refresh-feedback.test.tsx
new file mode 100644
index 000000000..bc431f8ba
--- /dev/null
+++ b/graph-ui/src/architecture/refresh-feedback.test.tsx
@@ -0,0 +1,48 @@
+// @vitest-environment jsdom
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, expect, it } from 'vitest';
+import { clockTime, RefreshControl, useRefreshFeedback, type RefreshReading } from './refresh-feedback';
+
+let host: HTMLDivElement, root: Root;
+beforeEach(() => {
+ (globalThis as unknown as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+ host = document.createElement('div'); document.body.append(host); root = createRoot(host);
+});
+afterEach(async () => { await act(async () => root.unmount()); host.remove(); });
+
+const labels = { idle: 'Refresh', busy: 'Refreshing…', done: (time: string) => `Refreshed at ${time}` };
+let begin: () => void = () => {};
+function Fixture({ reading }: { reading: RefreshReading }) {
+ const refresh = useRefreshFeedback(reading, () => new Date(2026, 9, 4, 7, 3, 9).getTime());
+ begin = refresh.begin;
+ return <RefreshControl labels={labels} feedback={refresh.feedback} onRefresh={refresh.begin} />;
+}
+const show = (reading: RefreshReading) => act(async () => root.render(<Fixture reading={reading} />));
+const status = () => host.querySelector('[role="status"]')?.textContent;
+
+it('names the wall clock with two digits each', () => {
+ expect(clockTime(new Date(2026, 9, 4, 7, 3, 9).getTime())).toBe('07:03:09');
+});
+
+it('waits for the reading the refresh started, not the one shown when it was pressed', async () => {
+ await show({ key: 'a', settled: true, value: { routes: 1 } });
+ await act(async () => begin());
+ // Still the earlier reading: nothing is decided yet.
+ await show({ key: 'a', settled: true, value: { routes: 1 } });
+ expect(host.querySelector('button')?.textContent).toBe('Refreshing…');
+ await show({ key: 'b', settled: false });
+ expect(status()).toBe('');
+ await show({ key: 'b', settled: true, value: { routes: 1 } });
+ expect(status()).toBe('Up to date at 07:03:09: no changes since the last load');
+});
+
+it('drops the status once another reading than the refreshed one is shown', async () => {
+ await show({ key: 'a', settled: true, value: 1 });
+ await act(async () => begin());
+ await show({ key: 'b', settled: true, value: 2 });
+ expect(status()).toBe('Refreshed at 07:03:09');
+ // Another start or a reindex: the status would speak about data no longer shown.
+ await show({ key: 'c', settled: true, value: 3 });
+ expect(status()).toBe('');
+});
diff --git a/graph-ui/src/architecture/refresh-feedback.tsx b/graph-ui/src/architecture/refresh-feedback.tsx
new file mode 100644
index 000000000..acee2b579
--- /dev/null
+++ b/graph-ui/src/architecture/refresh-feedback.tsx
@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useRef, useState, type JSX } from 'react';
+import { architectureText } from './strings';
+
+const text = architectureText.refreshFeedback;
+
+/**
+ * What a Refresh button of Architecture says it did (hand test 2026-10-04, A3:
+ * "Refresh connections" fetched everything again and nothing on screen
+ * changed). While the reading runs the button reads "Refreshing …"; then a
+ * status beside it names the time and whether anything changed, or the error.
+ */
+export type RefreshFeedback =
+ | { phase: 'running' }
+ | { phase: 'done'; at: number; changed: boolean }
+ | { phase: 'failed'; at: number; error: string };
+
+/**
+ * The reading a view shows: its key (a refresh always leads to a new one),
+ * whether it has settled, and what it holds. `value` is compared as JSON
+ * before and after, so a view hands something small: the route snapshot, the
+ * service topology, the analysis generation.
+ */
+export interface RefreshReading { key: string; settled: boolean; value?: unknown; error?: string }
+
+const signature = (value: unknown) => JSON.stringify(value) ?? '';
+
+export function useRefreshFeedback(reading: RefreshReading, now: () => number = Date.now): { feedback?: RefreshFeedback; begin: () => void } {
+ const [feedback, setFeedback] = useState<RefreshFeedback>();
+ const started = useRef<{ key: string; before: string } | undefined>(undefined);
+ const described = useRef(reading.key);
+ const latest = useRef(reading);
+ latest.current = reading;
+ const { key, settled, value, error } = reading;
+ useEffect(() => {
+ const start = started.current;
+ if (start) {
+ if (key === start.key || !settled) return;
+ started.current = undefined;
+ described.current = key;
+ setFeedback(error !== undefined ? { phase: 'failed', at: now(), error } : { phase: 'done', at: now(), changed: signature(value) !== start.before });
+ return;
+ }
+ // Another reading than the refreshed one (another start, a reindex): the status no longer speaks about what is shown.
+ if (key !== described.current) { described.current = key; setFeedback(undefined); }
+ }, [key, settled, value, error, now]);
+ const begin = useCallback(() => {
+ const current = latest.current;
+ started.current = { key: current.key, before: signature(current.value) };
+ setFeedback({ phase: 'running' });
+ }, []);
+ return { feedback, begin };
+}
+
+const two = (value: number) => String(value).padStart(2, '0');
+/** The wall clock as the status names it: 13:45:12. */
+export function clockTime(at: number): string {
+ const date = new Date(at);
+ return `${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())}`;
+}
+
+export function refreshStatus(feedback: RefreshFeedback | undefined, done: (time: string) => string): string {
+ if (!feedback || feedback.phase === 'running') return '';
+ const time = clockTime(feedback.at);
+ return feedback.phase === 'failed' ? text.failed(time, feedback.error) : feedback.changed ? done(time) : text.unchanged(time);
+}
+
+/**
+ * The button and its status. A running refresh keeps the button in the focus
+ * order (`aria-disabled`, not `disabled`), so a keyboard reader stays where
+ * they were; a second press while it runs does nothing.
+ */
+export function RefreshControl({ labels, feedback, onRefresh, className }: {
+ labels: { idle: string; busy: string; done: (time: string) => string };
+ feedback?: RefreshFeedback; onRefresh: () => void; className?: string;
+}): JSX.Element {
+ const running = feedback?.phase === 'running';
+ return <span className="atlas-arch-refresh" data-phase={feedback?.phase}>
+ <button type="button" className={className} aria-disabled={running || undefined} aria-busy={running || undefined}
+ onClick={() => { if (!running) onRefresh(); }}>{running ? labels.busy : labels.idle}</button>
+ <span className="atlas-arch-refresh-status" role="status" data-phase={feedback?.phase}>{refreshStatus(feedback, labels.done)}</span>
+ </span>;
+}
diff --git a/graph-ui/src/architecture/strings.ts b/graph-ui/src/architecture/strings.ts
index e9b3bf937..8a7410a8c 100644
--- a/graph-ui/src/architecture/strings.ts
+++ b/graph-ui/src/architecture/strings.ts
@@ -100,6 +100,15 @@ export const architectureText = {
openedFile: 'Opened file',
scopeMeasure: (files: number, lines?: number) => `${files.toLocaleString()} files · ${lines === undefined ? 'unknown' : lines.toLocaleString()} indexed lines`,
openedScopeHint: 'Select a part or connection to inspect it. The location above leads back to the repository.',
+ /** Each Refresh button says what it did (hand test 2026-10-04, A3): busy while it runs, then when, and whether anything changed. */
+ refreshFeedback: {
+ routes: { idle: 'Refresh connections', busy: 'Refreshing connections…', done: (time: string) => `Connections refreshed at ${time}` },
+ services: { idle: 'Refresh', busy: 'Refreshing…', done: (time: string) => `Service map refreshed at ${time}` },
+ structure: { idle: 'Refresh analysis', busy: 'Refreshing analysis…', done: (time: string) => `Analysis refreshed at ${time}` },
+ behavior: { idle: 'Refresh', busy: 'Refreshing…', done: (time: string) => `Journey refreshed at ${time}` },
+ unchanged: (time: string) => `Up to date at ${time}: no changes since the last load`,
+ failed: (time: string, error: string) => `Refresh failed at ${time}: ${error}`,
+ },
};
/**