@crvouga/atlas 0.4.0 → 0.6.0

package/packages/visualizer/src/live/live-stream.ts

@@ -0,0 +1,225 @@
+import { AtlasChangeSchema, LiveRunSchema, type LiveRun, type AtlasChange } from '@crvouga/atlas/schema';
+import { useSyncExternalStore } from 'react';
+
+import { runtimeConfig, runtimeUrl } from '../runtime';
+
+/** What the server tells a viewer as it happens. */
+export type LiveEvent =
+  | { readonly type: 'open' }
+  | { readonly type: 'run'; readonly run: LiveRun }
+  | { readonly type: 'projects' }
+  | { readonly type: 'report'; readonly report: ReportAnnouncement }
+  | { readonly type: 'change'; readonly change: AtlasChange };
+
+/** One announcement that results arrived: enough to say who sent them without asking again. */
+export type ReportAnnouncement = {
+  readonly version: string;
+  readonly totalLayers: number;
+  readonly addedTotal: number;
+  readonly added: readonly {
+    readonly id: string;
+    readonly producer: string;
+    readonly environment?: string | null;
+    readonly branch?: string | null;
+    readonly counts?: Readonly<Record<string, number>>;
+  }[];
+};
+
+/** `connecting` before the first answer, `live` while the stream is open, `reconnecting` after it was lost. */
+export type LiveStatus = 'off' | 'connecting' | 'live' | 'reconnecting';
+
+type Listener = (event: LiveEvent) => void;
+
+/** The server sends a comment every 15 seconds; this long without a word means the connection is dead. */
+const SILENCE_MS = 45_000;
+const BACKOFF_MS = [1_000, 2_000, 5_000, 10_000, 30_000] as const;
+
+type Stream = {
+  readonly url: string;
+  readonly listeners: Set<Listener>;
+  source: EventSource | null;
+  status: LiveStatus;
+  attempts: number;
+  timer: ReturnType<typeof setTimeout> | null;
+  watchdog: ReturnType<typeof setTimeout> | null;
+};
+
+const streams = new Map<string, Stream>();
+const statusListeners = new Set<() => void>();
+
+function setStatus(stream: Stream, status: LiveStatus) {
+  if (stream.status === status) return;
+  stream.status = status;
+  for (const listener of statusListeners) listener();
+}
+
+function emit(stream: Stream, event: LiveEvent) {
+  for (const listener of [...stream.listeners]) {
+    try {
+      listener(event);
+    } catch {
+      // One listener's mistake must not stop the others hearing.
+    }
+  }
+}
+
+function parse(data: string): unknown {
+  try {
+    return JSON.parse(data) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+function connect(stream: Stream) {
+  if (typeof EventSource === 'undefined') return;
+  stream.timer = null;
+  const source = new EventSource(stream.url);
+  stream.source = source;
+  let silenceMs = SILENCE_MS;
+  const on = (name: string, handler: (event: Event) => void) => source.addEventListener(name, event => {
+    if (stream.source === source) handler(event);
+  });
+  const heard = () => {
+    if (stream.watchdog) clearTimeout(stream.watchdog);
+    stream.watchdog = setTimeout(() => lose(stream), silenceMs);
+  };
+  on('open', () => {
+    heard();
+    stream.attempts = 0;
+    setStatus(stream, 'live');
+    // Anything may have happened while the stream was away, so a (re)connection reads everything again.
+    emit(stream, { type: 'open' });
+  });
+  on('hello', event => {
+    const hello = parse((event as MessageEvent<string>).data) as { heartbeatMs?: unknown } | null;
+    if (typeof hello?.heartbeatMs === 'number' && Number.isFinite(hello.heartbeatMs) && hello.heartbeatMs > 0) silenceMs = Math.max(SILENCE_MS, hello.heartbeatMs * 3);
+    heard();
+  });
+  on('ping', heard);
+  on('report', (event) => {
+    heard();
+    const report = parse((event as MessageEvent<string>).data) as ReportAnnouncement | null;
+    if (report && typeof report.version === 'string') emit(stream, { type: 'report', report: { ...report, added: Array.isArray(report.added) ? report.added : [] } });
+  });
+  on('run', event => {
+    heard();
+    const run = LiveRunSchema.safeParse(parse((event as MessageEvent<string>).data));
+    if (run.success) emit(stream, { type: 'run', run: run.data });
+  });
+  on('projects', () => { heard(); emit(stream, { type: 'projects' }); });
+  on('atlas:change', (event) => {
+    heard();
+    const change = AtlasChangeSchema.safeParse(parse((event as MessageEvent<string>).data));
+    if (change.success) emit(stream, { type: 'change', change: change.data });
+  });
+  // The server's heartbeat is a named `ping` event, so a quiet server is told apart from a dead connection.
+  on('error', () => {
+    setStatus(stream, stream.attempts === 0 && stream.status === 'connecting' ? 'connecting' : 'reconnecting');
+    // The browser retries a dropped stream by itself. A refused one (401, 503) it gives up on: retry that here, slowly.
+    if (source.readyState === EventSource.CLOSED) lose(stream);
+  });
+  heard();
+}
+
+function lose(stream: Stream) {
+  if (stream.watchdog) clearTimeout(stream.watchdog);
+  stream.watchdog = null;
+  stream.source?.close();
+  stream.source = null;
+  if (!stream.listeners.size) return;
+  setStatus(stream, 'reconnecting');
+  if (stream.timer) return;
+  const wait = BACKOFF_MS[Math.min(stream.attempts, BACKOFF_MS.length - 1)]!;
+  stream.attempts += 1;
+  stream.timer = setTimeout(() => connect(stream), wait);
+}
+
+function release(stream: Stream) {
+  if (stream.listeners.size) return;
+  if (stream.timer) clearTimeout(stream.timer);
+  if (stream.watchdog) clearTimeout(stream.watchdog);
+  stream.source?.close();
+  stream.source = null;
+  streams.delete(stream.url);
+  setStatus(stream, 'off');
+}
+
+/**
+ * Hear what the server at `url` announces. Everything in the page that listens to one address shares one
+ * connection, which is opened with the first listener and closed with the last.
+ */
+export function listenLive(url: string, listener: Listener): () => void {
+  let stream = streams.get(url);
+  if (!stream) {
+    stream = { url, listeners: new Set(), source: null, status: 'connecting', attempts: 0, timer: null, watchdog: null };
+    streams.set(url, stream);
+    stream.listeners.add(listener);
+    connect(stream);
+    for (const notify of statusListeners) notify();
+  } else {
+    stream.listeners.add(listener);
+  }
+  const mine = stream;
+  return () => {
+    mine.listeners.delete(listener);
+    release(mine);
+  };
+}
+
+/** Changes to specs and runs, in the form the data layer already understands. */
+export function listenChanges(url: string, onChange: (change: AtlasChange) => void): () => void {
+  return listenLive(url, (event) => {
+    if (event.type === 'change') onChange(event.change);
+    // A fresh connection may have missed changes while it was away.
+    if (event.type === 'open') {
+      onChange({ scope: 'specs', files: [], runIds: [] });
+      onChange({ scope: 'runs', files: [], runIds: [] });
+    }
+    if (event.type === 'report') onChange({ scope: 'runs', files: [], runIds: [] });
+  });
+}
+
+/** The address of this server's event stream, when the page has one. */
+export const eventsAddress = () => runtimeUrl(runtimeConfig()?.eventsUrl);
+
+function snapshot(): LiveStatus {
+  const url = eventsAddress();
+  return (url && streams.get(url)?.status) || (url ? 'connecting' : 'off');
+}
+
+function subscribeStatus(listener: () => void) {
+  statusListeners.add(listener);
+  return () => statusListeners.delete(listener);
+}
+
+/** Whether the report on screen is being kept up to date by the server. `off` for a static site. */
+export function useLiveStatus(): LiveStatus {
+  return useSyncExternalStore(subscribeStatus, snapshot, () => 'off');
+}
+
+/** Test seam: forget every stream. */
+export function resetLiveStreams() {
+  for (const stream of streams.values()) {
+    stream.listeners.clear();
+    release(stream);
+  }
+  streams.clear();
+}
+
+/**
+ * `act` at once, and then no more than once per `ms` however often it is called: a call made inside the wait
+ * runs when the wait ends. The last word is never lost.
+ */
+export function throttled(act: () => void, ms: number): (() => void) & { cancel: () => void } {
+  let last = -Infinity;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const call = () => {
+    if (timer) return;
+    const wait = last + ms - Date.now();
+    if (wait <= 0) { last = Date.now(); act(); return; }
+    timer = setTimeout(() => { timer = null; last = Date.now(); act(); }, wait);
+  };
+  call.cancel = () => { if (timer) clearTimeout(timer); timer = null; };
+  return call;
+}

package/packages/visualizer/src/live/report-progress.ts

@@ -0,0 +1,62 @@
+import { addSummaries, summarizeSlots, type CheckSlot, type EvidenceView, type SpecEvidence } from '@crvouga/atlas/reports/evidence-view';
+import type { LiveTest } from './live-runs';
+
+type LiveIndex = ReadonlyMap<string, readonly LiveTest[]>;
+const testKey = (id: string, file: string | null) => JSON.stringify([file, id]);
+
+/** Build once per server update so rendering a row only looks up that test's executions. */
+export function indexLiveTests(tests: readonly LiveTest[]): LiveIndex {
+  const index = new Map<string, LiveTest[]>();
+  for (const test of tests) {
+    const key = testKey(test.check.id, test.check.specPath ?? null);
+    const values = index.get(key);
+    if (values) values.push(test);
+    else index.set(key, [test]);
+  }
+  return index;
+}
+
+/** Match identity and spec, never a display title: different specs can use the same test name. */
+export function testsForSlot(index: LiveIndex, slot: Pick<CheckSlot, 'id' | 'specPath' | 'latestAtMs'>) {
+  const seen = new Set<string>();
+  return (index.get(testKey(slot.id, slot.specPath)) ?? []).filter(({ run }) => {
+    const identity = JSON.stringify([run.producer, run.environment, run.branch]);
+    if (seen.has(identity)) return false;
+    seen.add(identity);
+    return run.status === 'running' || (run.finishedAtMs ?? run.lastProgressAtMs) >= slot.latestAtMs;
+  });
+}
+
+/** Display current execution beside history without changing immutable layers or report composition. */
+export function withLiveProgress(view: EvidenceView, tests: readonly LiveTest[]): EvidenceView {
+  if (!tests.length) return view;
+  const specs = new Map(view.specs);
+  const index = indexLiveTests(tests);
+  const bySpec = new Map<string | null, Map<string, CheckSlot>>();
+  for (const { check } of tests) {
+    const file = check.specPath ?? null;
+    if (!bySpec.has(file)) bySpec.set(file, new Map((file ? specs.get(file)?.slots ?? [] : view.unassigned).map(slot => [slot.id, slot])));
+    const slots = bySpec.get(file)!;
+    if (!slots.has(check.id)) slots.set(check.id, { key: testKey(check.id, file), id: check.id, title: check.title, specPath: file,
+      status: check.status, outcomes: [], diagnostics: [], latestAtMs: 0, live: false });
+  }
+  const update = (slots: CheckSlot[]) => slots.map(slot => {
+    const matches = testsForSlot(index, slot);
+    if (!matches.length) return slot;
+    const running = matches.some(({ run, check }) => run.status === 'running' && check.status === 'running');
+    const latest = matches[0]!;
+    const status = running ? 'running' : slot.outcomes.length ? slot.status : latest.check.status === 'running' ? 'not-run' : latest.check.status;
+    const interrupted = matches.some(({ run, check }) => run.status === 'interrupted' && check.status === 'not-run');
+    return { ...slot, status: interrupted && !running ? 'not-run' as const : status, live: running,
+      latestAtMs: Math.max(slot.latestAtMs, ...matches.map(({ run }) => run.lastProgressAtMs)) };
+  });
+  let unassigned = view.unassigned;
+  for (const [file, slots] of bySpec) {
+    const updated = update([...slots.values()]);
+    if (file) {
+      const entry: SpecEvidence = { slots: updated, summary: summarizeSlots(updated) };
+      specs.set(file, entry);
+    } else unassigned = updated;
+  }
+  return { specs, unassigned, total: addSummaries([...specs.values()].map(entry => entry.summary)) };
+}

package/packages/visualizer/src/live/test-progress.tsx

@@ -0,0 +1,34 @@
+import type { CheckSlot } from '@crvouga/atlas/reports/evidence-view';
+import { StatusMark } from '../evidence/marks';
+import styles from '../evidence/evidence.module.css';
+import { useLiveTests, type LiveTest } from './live-runs';
+import { testsForSlot } from './report-progress';
+
+export function useTestProgress(slot: CheckSlot | null) {
+  const { index, error } = useLiveTests();
+  return { tests: slot ? testsForSlot(index, slot) : [], error };
+}
+
+/** A test's own progress log. Historical evidence stays available below it. */
+export function TestProgress({ tests, error }: { tests: readonly LiveTest[]; error?: string | null }) {
+  if (!tests.length) return null;
+  return <div aria-label="Test progress">
+    {tests.map(({ run, check }) => {
+      const running = run.status === 'running' && check.status === 'running';
+      const interrupted = run.status === 'interrupted' && check.status === 'not-run';
+      const status = running ? 'running' : interrupted ? 'not-run' : check.status === 'running' ? 'not-run' : check.status;
+      return <div key={`${run.id}:${check.id}`}>
+        <p className={styles.detailMeta} role="status"><StatusMark status={status} />
+          <strong>{running ? 'Running' : interrupted ? 'Interrupted' : status === 'passed' ? 'Passed' : status === 'failed' ? 'Failed' : 'Not run'}</strong>
+          <span>{run.producer}{run.environment ? ` · ${run.environment}` : ''}</span>
+        </p>
+        {check.detail && check.detail !== run.reason && <pre className={styles.pre}>{check.detail}</pre>}
+        {!!check.steps?.length && <ol className={styles.steps} aria-label="Progress log">{check.steps.map((step, index) => <li key={index}>
+          <div className={styles.stepRow}><StatusMark status={step.status === 'passed' || step.status === 'failed' || step.status === 'running' ? step.status : 'none'} size={14} /><span className={styles.stepText}>{step.name}</span></div>
+        </li>)}</ol>}
+        {interrupted && <p className={styles.notice} role="status">{run.reason ?? 'The test run was interrupted.'} No completed outcome was received for this test.</p>}
+      </div>;
+    })}
+    {error && <p className={styles.notice} role="alert">{error}</p>}
+  </div>;
+}

package/packages/visualizer/src/runtime.ts

@@ -0,0 +1,35 @@
+/**
+ * The address book an Atlas server writes into the page it serves (`window.__ATLAS_CONFIG__`), so one build
+ * of the viewer works for every project and on every host. Under `atlas dev` the Vite dev server writes the
+ * same thing, so the viewer cannot tell the two apart: both are one host, with `/api` behind it.
+ */
+export type RuntimeConfig = {
+  readonly api?: string;
+  readonly reportsUrl?: string;
+  readonly dataUrl?: string;
+  readonly eventsUrl?: string;
+  readonly effective?: boolean;
+  readonly projectsUrl?: string;
+};
+
+/** The project selected in the page address. A full navigation on change isolates caches and connections. */
+export const currentProject = () => typeof window === 'undefined' ? null : new URL(window.location.href).searchParams.get('project');
+
+export const runtimeConfig = (): RuntimeConfig | undefined => {
+  const config = (globalThis as { __ATLAS_CONFIG__?: RuntimeConfig }).__ATLAS_CONFIG__;
+  const project = currentProject();
+  if (!config?.api || !project || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(project) || project.length > 64) return config;
+  const api = new URL(config.api, window.location.href).href.replace(/\/$/, '');
+  const scoped = `${api}/projects/${project}`;
+  const scope = (address: string | undefined) => {
+    if (!address) return address;
+    const absolute = new URL(address, window.location.href).href;
+    return absolute === api || absolute.startsWith(`${api}/`) ? scoped + absolute.slice(api.length) : absolute;
+  };
+  return { ...config, api: scoped, reportsUrl: scope(config.reportsUrl), dataUrl: scope(config.dataUrl), eventsUrl: scope(config.eventsUrl) };
+};
+
+/** An address from the config, resolved against the page, as an absolute URL. */
+export function runtimeUrl(value: string | undefined): string | undefined {
+  return value ? new URL(value, window.location.href).href : undefined;
+}

package/packages/visualizer/src/state/ui-store.ts

@@ -2,9 +2,10 @@ import { ALL_SOURCES, type SourceSelection } from '@crvouga/atlas/reports/eviden
 import type { Viewport } from '@xyflow/react';
 import { create } from 'zustand';
 import { createJSONStorage, persist } from 'zustand/middleware';
+import { currentProject } from '../runtime';
 
 /** Which specs the index lists, by what has been recorded for them. */
-export type ResultFilter = 'all' | 'results' | 'failed' | 'none';
+export type ResultFilter = 'all' | 'results' | 'running' | 'failed' | 'none';
 
 type UiState = {
   viewports: Record<string, Viewport>;
@@ -36,7 +37,7 @@ export const useUiStore = create<UiState>()(
       setExcluded: (excluded) => set({ excluded })
     }),
     {
-      name: 'atlas-ui',
+      name: currentProject() ? `atlas-ui:${currentProject()}` : 'atlas-ui',
       storage: createJSONStorage(() => sessionStorage),
       partialize: (s) => ({ viewports: s.viewports, excluded: s.excluded, resultFilter: s.resultFilter }),
       merge: (persisted, current) => {

package/packages/visualizer/src/views/ChartPage.tsx

@@ -5,6 +5,7 @@ import { mapFrame } from '../layout/graph';
 import { ChartMap } from '../map/ChartMap';
 import { SidePanel } from './SidePanel';
 import styles from './views.module.css';
+import { ChartTests } from './ChartTests';
 
 export function ChartPage() {
   const { chartId } = useParams({ from: '/chart/$chartId' });
@@ -47,6 +48,7 @@ export function ChartPage() {
       <div className={styles.mapArea}>
         <ChartMap key={`${chartId}:${search.group ?? ''}`} view={view} chartId={chartId} selection={selection} group={search.group} />
       </div>
+      <ChartTests view={view} chartId={chartId} compact />
     </div>
   );
 }

package/packages/visualizer/src/views/ChartTests.tsx

@@ -0,0 +1,43 @@
+import { lazy, Suspense, useState } from 'react';
+import type { AtlasView } from '../data/model';
+import { useEvidence } from '../evidence/evidence-context';
+import { CheckDetail, ResultRow, type CheckSelection } from '../evidence/check-detail';
+import { TestFilter, useRunningFilter } from '../evidence/test-filter';
+import { Bounded } from '../evidence/marks';
+import { outlinePath } from '../spec-kind';
+import styles from '../evidence/evidence.module.css';
+
+const RecordingPage = lazy(() => import('../evidence/recording-page').then(module => ({ default: module.RecordingPage })));
+
+/** Statechart test reports stay in the chart, including while their recordings are still arriving. */
+export function ChartTests({ view, chartId, compact = false }: { view: AtlasView; chartId: string; compact?: boolean }) {
+  const evidence = useEvidence();
+  const runningOnly = useRunningFilter();
+  const [selection, setSelection] = useState<CheckSelection>({});
+  const [selectedKey, setSelectedKey] = useState<string | null>(null);
+  const [recording, setRecording] = useState(false);
+  const [moment, setMoment] = useState<number | null>(null);
+  const files = new Set<string>();
+  let chart = view.charts.get(chartId);
+  while (chart && !files.has(outlinePath(chart.file))) {
+    files.add(outlinePath(chart.file));
+    chart = chart.parent ? view.charts.get(chart.parent.chartId) : undefined;
+  }
+  const slots = [...files].flatMap(file => evidence.view.specs.get(file)?.slots ?? []);
+  const visible = slots.filter(slot => !runningOnly || slot.status === 'running');
+  if (!slots.length) return null;
+  return <section aria-label="Chart tests" className={styles.block} style={compact ? { maxHeight: '40vh', overflowY: 'auto', flexShrink: 0 } : undefined}>
+    <h3 className={styles.blockTitle}>Tests</h3>
+    <TestFilter slots={slots} />
+    <ul className={styles.results}><Bounded items={visible} size={40} more="More tests">{slot =>
+      <ResultRow key={slot.key} label={slot.title} slot={slot} open={selectedKey === slot.key}
+        onToggle={() => { setSelectedKey(selectedKey === slot.key ? null : slot.key); setSelection({ check: slot.id }); setRecording(false); setMoment(null); }}>
+        {recording ? <Suspense fallback={<p role="status">Loading the recording…</p>}><RecordingPage slot={slot} layerId={selection.layer} label={slot.title} back="Test report" moment={moment} onMoment={setMoment} onClose={() => setRecording(false)} /></Suspense>
+          : <CheckDetail slot={slot} layerId={selection.layer} reads="steps" select={patch => {
+            setSelection({ check: patch.check ?? slot.id, layer: patch.layer ?? undefined });
+            if (patch.view === 'recording') { setRecording(true); setMoment(null); }
+          }} />}
+      </ResultRow>
+    }</Bounded></ul>
+  </section>;
+}

package/packages/visualizer/src/views/SidePanel.tsx

@@ -12,6 +12,7 @@ import { Stage } from '../looks/Stage';
 import { mapScope } from '../layout/graph';
 import type { MapSelection } from '../map/ChartMap';
 import styles from './views.module.css';
+import { ChartTests } from './ChartTests';
 
 function Section({ title, children }: { title: string; children: ReactNode }) {
   return (
@@ -314,6 +315,7 @@ export function SidePanel({ view, chartId, selection }: { view: AtlasView; chart
   return (
     <article className={styles.plateScroll} aria-label={label}>
       {body}
+      <ChartTests view={view} chartId={chartId} />
       <Link
         to="/chart/$chartId"
         params={{ chartId }}

package/packages/visualizer/vite/atlas-files.test.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 
 import { afterAll, describe, expect, it } from 'bun:test';
 
-import { DEFAULT_FIXTURE, FIXTURES_ROOT, isSpecFile, listSpecFiles, publicReportSources, resolveReportSources, resolveRoots, safeJoin, summarizeRun } from './atlas-files';
+import { FIXTURES_ROOT, isSpecFile, listSpecFiles, publicReportSources, resolveReportSources, resolveRoots, safeJoin, summarizeRun } from './atlas-files';
 
 const tmp = mkdtempSync(path.join(os.tmpdir(), 'atlas-files-'));
 afterAll(() => rmSync(tmp, { recursive: true, force: true }));
@@ -31,10 +31,10 @@ describe('resolveRoots', () => {
     expect(resolveRoots({ ATLAS_SPECS_ROOT: 'x' }, project).specs).toBe(path.join(project, 'x'));
   });
 
-  it('shows the example when nothing is configured and there is no specs/ directory', () => {
+  it('keeps an unconfigured project empty instead of loading a bundled example', () => {
     const roots = resolveRoots({ INIT_CWD: path.join(tmp, 'empty') });
-    expect(roots.specs).toBe(path.join(FIXTURES_ROOT, DEFAULT_FIXTURE, 'specs'));
-    expect(roots.label).toMatch(/^example/);
+    expect(roots.specs).toBe(path.join(tmp, 'empty', 'specs'));
+    expect(roots.label).toBe('configured');
   });
 
   it('reads a named fixture and rejects an unknown one', () => {

package/packages/visualizer/vite/atlas-files.ts

@@ -53,17 +53,13 @@ export function fixtureRoots(name: string): AtlasRoots {
  * (`ATLAS_FIXTURE`), explicit roots (`ATLAS_SPECS_ROOT`, `ATLAS_RUNS_ROOT`), then `specs/` and
  * `atlas-runs/` where the command was run. Relative paths resolve against `INIT_CWD` (where pnpm
  * was run) or the current directory. With nothing configured and no `specs/` there, the bundled
- * example fixture is shown.
+ * project stays empty. Bundled examples require an explicit fixture selection.
  */
 export function resolveRoots(env: NodeJS.ProcessEnv = process.env, cwd = process.cwd()): AtlasRoots {
   if (env.ATLAS_FIXTURE) return fixtureRoots(env.ATLAS_FIXTURE);
   const base = env.INIT_CWD || cwd;
-  const specsSet = Boolean(env.ATLAS_SPECS_ROOT);
   const specs = path.resolve(base, env.ATLAS_SPECS_ROOT || DEFAULT_SPECS_DIR);
   const runs = path.resolve(base, env.ATLAS_RUNS_ROOT || DEFAULT_RUNS_DIR);
-  if (!specsSet && !env.ATLAS_RUNS_ROOT && !existsSync(specs)) {
-    return { ...fixtureRoots(DEFAULT_FIXTURE), label: `example (no ${DEFAULT_SPECS_DIR}/ in ${base}; set ATLAS_SPECS_ROOT)` };
-  }
   return { specs, runs, label: 'configured' };
 }
 

package/packages/visualizer/vite/atlas-server-proxy.ts

@@ -0,0 +1,37 @@
+import type { Plugin, ProxyOptions } from 'vite';
+
+/** What the viewer is told about the server it is served with: the same words `atlas serve` writes into its page. */
+export const serverPageConfig = { api: './api', reportsUrl: './api/reports', dataUrl: './api/data/', eventsUrl: './api/events', projectsUrl: './api/projects', effective: true } as const;
+
+/**
+ * Put the Atlas server behind the dev server. The browser talks to one host; `/api` goes to the server, so the
+ * page, its data and its event stream have one origin in development exactly as they do when deployed.
+ */
+export function atlasServerProxy(target: string): { readonly proxy: Record<string, ProxyOptions> } {
+  return {
+    proxy: {
+      '/admin': { target, changeOrigin: false },
+      '/api': {
+        target,
+        changeOrigin: false,
+        ws: false,
+        // The event stream stays open for hours: no timeout, and nothing may hold its bytes back.
+        timeout: 0,
+        proxyTimeout: 0,
+        configure: (proxy) => {
+          proxy.on('proxyRes', (response) => {
+            if (String(response.headers['content-type'] ?? '').startsWith('text/event-stream')) response.headers['cache-control'] = 'no-cache, no-transform';
+          });
+        }
+      }
+    }
+  };
+}
+
+/** Write the server's address book into the page the dev server serves. */
+export function atlasServerPage(): Plugin {
+  return {
+    name: 'atlas-server-page',
+    transformIndexHtml: () => [{ tag: 'script', children: `window.__ATLAS_CONFIG__=${JSON.stringify(serverPageConfig)}`, injectTo: 'head-prepend' }]
+  };
+}

package/packages/visualizer/vite.config.ts

@@ -8,14 +8,22 @@ import { resolveRoots } from './vite/atlas-files';
 import { servesExampleReports } from './vite/example-reports';
 import { reportsDevPlugin } from './vite/reports-dev-plugin';
 import { atlasDevPlugin } from './vite/atlas-dev-plugin';
+import { atlasServerPage, atlasServerProxy } from './vite/atlas-server-proxy';
 
 const appRoot = path.dirname(fileURLToPath(import.meta.url));
-const reportsModule = process.env.ATLAS_REPORTS_MODULE || (servesExampleReports(resolveRoots().specs) ? path.join(appRoot, 'vite/example-reports.ts') : '');
+
+// `atlas dev` runs the Atlas server on a port of its own and tells this config where. The browser then talks to
+// this dev server alone: `/api` is proxied to the server, and the page gets the same address book a served
+// build gets, so the viewer cannot tell the two apart. Without a server, the viewer reads the working tree.
+const serverUrl = process.env.ATLAS_API_URL || '';
+const reportsModule = serverUrl ? '' : process.env.ATLAS_REPORTS_MODULE || (servesExampleReports(resolveRoots().specs) ? path.join(appRoot, 'vite/example-reports.ts') : '');
 
 export default defineConfig({
   base: './',
-  plugins: [react(), atlasDevPlugin(), ...(reportsModule ? [reportsDevPlugin({ repoRoot: process.env.INIT_CWD || process.cwd(), appModule: reportsModule })] : [])],
+  plugins: serverUrl
+    ? [react(), atlasServerPage()]
+    : [react(), atlasDevPlugin(), ...(reportsModule ? [reportsDevPlugin({ repoRoot: process.env.INIT_CWD || process.cwd(), appModule: reportsModule })] : [])],
   worker: { format: 'es' },
-  server: { port: Number(process.env.PORT ?? 5180), strictPort: false },
+  server: { port: Number(process.env.PORT ?? 5180), strictPort: false, ...(serverUrl ? atlasServerProxy(serverUrl) : {}) },
   build: { outDir: 'dist', emptyOutDir: true, chunkSizeWarningLimit: 2_500 }
 });