@crvouga/atlas 0.0.0-stage → 0.2.0

package/packages/visualizer/src/components/icons.tsx

@@ -0,0 +1,156 @@
+import type { SVGProps } from 'react';
+
+type IconProps = SVGProps<SVGSVGElement> & { size?: number };
+
+function Svg({ size = 14, children, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 16 16" fill="none" aria-hidden="true" focusable="false" {...rest}>
+      {children}
+    </svg>
+  );
+}
+
+export const PlayIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M4.5 2.8v10.4a.6.6 0 0 0 .9.5l8.2-5.2a.6.6 0 0 0 0-1L5.4 2.3a.6.6 0 0 0-.9.5Z" fill="currentColor" />
+  </Svg>
+);
+
+export const BoltIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M9.2 1.2 3.4 9.1h4.1l-1 5.7 6.1-8.2H8.4l.8-5.4Z" fill="currentColor" />
+  </Svg>
+);
+
+export const ClockIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <circle cx="8" cy="8" r="6.2" stroke="currentColor" strokeWidth="1.8" />
+    <path d="M8 4.6V8l2.4 1.6" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" />
+  </Svg>
+);
+
+export const HandOffIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M3 4.5h6.5a3 3 0 0 1 0 6H4.5" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" />
+    <path d="m6.5 8.2-2.4 2.3 2.4 2.3" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" />
+  </Svg>
+);
+
+export const PlusIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M8 3v10M3 8h10" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" />
+  </Svg>
+);
+
+export const MinusIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M3 8h10" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" />
+  </Svg>
+);
+
+export const FitIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M2.5 6V2.5H6M10 2.5h3.5V6M13.5 10v3.5H10M6 13.5H2.5V10" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" />
+  </Svg>
+);
+
+export const CloseIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="m4 4 8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" />
+  </Svg>
+);
+
+export const NoteIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <circle cx="8" cy="8" r="6.2" stroke="currentColor" strokeWidth="1.6" />
+    <path d="M8 7.2v4M8 4.8v.1" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" />
+  </Svg>
+);
+
+export const WarnIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M8 2.2 1.8 13h12.4L8 2.2Z" stroke="currentColor" strokeWidth="1.6" strokeLinejoin="round" />
+    <path d="M8 6.5v3M8 11.3v.1" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" />
+  </Svg>
+);
+
+export const MapIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="m1.8 3.6 4-1.4 4.4 1.6 4-1.4v10l-4 1.4-4.4-1.6-4 1.4v-10Z" stroke="currentColor" strokeWidth="1.5" strokeLinejoin="round" />
+    <path d="M5.8 2.2v10M10.2 3.8v10" stroke="currentColor" strokeWidth="1.5" />
+  </Svg>
+);
+
+export const ChevronIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="m6 3.5 4.5 4.5L6 12.5" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" />
+  </Svg>
+);
+
+export const ChevronDownIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="m3.5 6 4.5 4.5L12.5 6" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" />
+  </Svg>
+);
+
+export const SearchIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <circle cx="7" cy="7" r="4.6" stroke="currentColor" strokeWidth="1.7" />
+    <path d="m10.5 10.5 3.2 3.2" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" />
+  </Svg>
+);
+
+export const CheckIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="m3.2 8.4 3 3 6.6-6.8" stroke="currentColor" strokeWidth="1.9" strokeLinecap="round" strokeLinejoin="round" />
+  </Svg>
+);
+
+export const SlidersIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M2.5 4.5h6M12 4.5h1.5M2.5 11.5H4M7.5 11.5h6" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+    <circle cx="10.2" cy="4.5" r="1.7" stroke="currentColor" strokeWidth="1.6" />
+    <circle cx="5.8" cy="11.5" r="1.7" stroke="currentColor" strokeWidth="1.6" />
+  </Svg>
+);
+
+export const ArrowLeftIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M13 8H3.5M7.5 3.8 3.3 8l4.2 4.2" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" />
+  </Svg>
+);
+
+export const ArrowRightIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M3 8h9.5M8.5 3.8 12.7 8l-4.2 4.2" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" />
+  </Svg>
+);
+
+export const PauseIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <rect x="4" y="3" width="2.8" height="10" rx="0.8" fill="currentColor" />
+    <rect x="9.2" y="3" width="2.8" height="10" rx="0.8" fill="currentColor" />
+  </Svg>
+);
+
+export const ExternalIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M9.5 2.8h3.7v3.7M13 3 7.6 8.4" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" />
+    <path d="M11.5 9.5v2.6a1.1 1.1 0 0 1-1.1 1.1H3.9a1.1 1.1 0 0 1-1.1-1.1V5.6a1.1 1.1 0 0 1 1.1-1.1h2.6" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+  </Svg>
+);
+
+export const RouteIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <circle cx="3.8" cy="12.2" r="1.8" stroke="currentColor" strokeWidth="1.6" />
+    <circle cx="12.2" cy="3.8" r="1.8" stroke="currentColor" strokeWidth="1.6" />
+    <path d="M5.6 12.2h4.2a2.2 2.2 0 0 0 0-4.4H6.2a2.2 2.2 0 0 1 0-4.4h4.2" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+  </Svg>
+);
+
+export const ReplayIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="M3 8a5 5 0 1 0 1.6-3.7" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" />
+    <path d="M3.2 2.6v2.6h2.6" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" />
+  </Svg>
+);

package/packages/visualizer/src/components/labels.tsx

@@ -0,0 +1,22 @@
+import type { EventKind } from '@crvouga/atlas/schema';
+
+import { BoltIcon, ClockIcon, HandOffIcon, PlayIcon } from './icons';
+
+export const KIND_LABEL: Record<EventKind, string> = {
+  user: 'User action',
+  system: 'System event',
+  time: 'Time passes',
+  'hand-off': 'Hand-off'
+};
+
+export const KIND_ICON = {
+  user: PlayIcon,
+  system: BoltIcon,
+  time: ClockIcon,
+  'hand-off': HandOffIcon
+} satisfies Record<EventKind, unknown>;
+
+export function KindIcon({ kind, size }: { kind: EventKind; size?: number }) {
+  const Icon = KIND_ICON[kind];
+  return <Icon size={size} />;
+}

package/packages/visualizer/src/data/adapters/adapter.ts

@@ -0,0 +1,112 @@
+import { AtlasChangeSchema, type AtlasChange } from '@crvouga/atlas/schema';
+
+export type { AtlasChange } from '@crvouga/atlas/schema';
+
+export type AtlasAdapter = {
+  kind: 'static' | 'dev' | 'api';
+  /** Where the data comes from, for the developer section. */
+  label: string;
+  specIndex: () => Promise<unknown>;
+  specFile: (path: string) => Promise<string>;
+  runsIndex: () => Promise<unknown>;
+  manifest: (runId: string) => Promise<unknown>;
+  manifestPath: (runId: string) => string;
+  mediaUrl: (runId: string, path: string) => string;
+  subscribe: ((onChange: (change: AtlasChange) => void) => () => void) | null;
+};
+
+export class LoadError extends Error {
+  constructor(
+    readonly url: string,
+    readonly status: number | null,
+    message: string
+  ) {
+    super(message);
+  }
+}
+
+function encodePath(path: string) {
+  if (!path || path.split(/[\\/]/).some((part) => part === '..' || part === '.') || path.startsWith('/')) throw new Error('The file path must stay inside its report.');
+  return path.split('/').map(encodeURIComponent).join('/');
+}
+
+async function get(url: string) {
+  let response: Response;
+  try {
+    response = await fetch(url, { cache: 'no-cache', signal: AbortSignal.timeout(15_000) });
+  } catch {
+    throw new LoadError(url, null, 'The server could not be reached.');
+  }
+  if (response.status === 404) throw new LoadError(url, 404, 'The file is not there.');
+  if (!response.ok) throw new LoadError(url, response.status, `The server answered with an error (${response.status}).`);
+  return response;
+}
+
+export async function getJson(url: string): Promise<unknown> {
+  const text = await (await get(url)).text();
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new LoadError(url, 200, 'The file is not valid JSON.');
+  }
+}
+
+/**
+ * Files over HTTP from a base URL laid out as `specs/index.json`, `specs/<path>`,
+ * `runs/index.json` and `runs/<id>/manifest.json` plus media.
+ */
+export function createHttpAdapter(baseUrl: string, kind: AtlasAdapter['kind'] = 'static', eventsUrl?: string): AtlasAdapter {
+  const base = new URL(baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`, window.location.href).href;
+  const location = new URL(base);
+  if (!['http:', 'https:'].includes(location.protocol) || location.username || location.password) throw new Error('Use an HTTP URL without credentials.');
+  const url = (path: string) => new URL(path, base).href;
+  const runPath = (runId: string) => {
+    if (!runId || runId === '.' || runId === '..' || /[\\/]/.test(runId)) throw new Error('The report id must name one run.');
+    return `runs/${encodeURIComponent(runId)}`;
+  };
+  return {
+    kind,
+    label: base,
+    specIndex: () => getJson(url('specs/index.json')),
+    specFile: async (path) => (await get(url(`specs/${encodePath(path)}`))).text(),
+    runsIndex: async () => {
+      try {
+        return await getJson(url(kind === 'api' ? 'runs' : 'runs/index.json'));
+      } catch (error) {
+        if (kind !== 'api' && error instanceof LoadError && error.status === 404) return { runs: [] };
+        throw error;
+      }
+    },
+    manifest: (runId) => getJson(url(`${runPath(runId)}/${kind === 'api' ? 'manifest' : 'manifest.json'}`)),
+    manifestPath: (runId) => url(`${runPath(runId)}/${kind === 'api' ? 'manifest' : 'manifest.json'}`),
+    mediaUrl: (runId, path) => {
+      try {
+        return url(`${runPath(runId)}/${kind === 'api' ? 'files/' : ''}${encodePath(path)}`);
+      } catch {
+        return '';
+      }
+    },
+    subscribe: eventsUrl ? subscribeToEvents(new URL(eventsUrl, base).href) : null
+  };
+}
+
+function subscribeToEvents(url: string): NonNullable<AtlasAdapter['subscribe']> {
+  const location = new URL(url);
+  if (!['http:', 'https:'].includes(location.protocol) || location.username || location.password) throw new Error('Use an HTTP event URL without credentials.');
+  return (onChange) => {
+    if (typeof EventSource === 'undefined') return () => undefined;
+    const stream = new EventSource(url);
+    const receive = (event: MessageEvent<string>) => {
+      try {
+        const change = AtlasChangeSchema.safeParse(JSON.parse(event.data));
+        if (change.success) onChange(change.data);
+      } catch {
+        return;
+      }
+    };
+    stream.addEventListener('message', receive);
+    stream.addEventListener('atlas:change', receive);
+    stream.addEventListener('open', () => onChange({ scope: 'runs', files: [], runIds: [] }));
+    return () => stream.close();
+  };
+}

package/packages/visualizer/src/data/adapters/context.tsx

@@ -0,0 +1,11 @@
+import { createContext, useContext } from 'react';
+
+import type { AtlasAdapter } from './adapter';
+
+export const AdapterContext = createContext<AtlasAdapter | null>(null);
+
+export function useAdapter() {
+  const adapter = useContext(AdapterContext);
+  if (!adapter) throw new Error('useAdapter needs an AdapterContext provider');
+  return adapter;
+}

package/packages/visualizer/src/data/adapters/index.ts

@@ -0,0 +1,29 @@
+import { createHttpAdapter, type AtlasAdapter, type AtlasChange } from './adapter';
+
+export * from './adapter';
+
+const DEV_PREFIX = '/__atlas/';
+const CHANGE_EVENT = 'atlas:change';
+
+export function createDevAdapter(base = DEV_PREFIX, label = 'Live from disk', sourceId = 'workspace'): AtlasAdapter {
+  const adapter = createHttpAdapter(base, 'dev');
+  return {
+    ...adapter,
+    label,
+    subscribe: (onChange) => {
+      const hot = import.meta.hot;
+      if (!hot) return () => undefined;
+      const handler = (change: AtlasChange) => {
+        if (change.scope === 'specs' || (change.sourceId ?? 'workspace') === sourceId) onChange(change);
+      };
+      hot.on(CHANGE_EVENT, handler);
+      return () => hot.off(CHANGE_EVENT, handler);
+    }
+  };
+}
+
+/** The dev adapter under `vite dev`, the static adapter everywhere else. */
+export function createAdapter(): AtlasAdapter {
+  if (import.meta.env.DEV && import.meta.hot) return createDevAdapter();
+  return createHttpAdapter(import.meta.env.VITE_ATLAS_BASE_URL ?? './data/');
+}

package/packages/visualizer/src/data/adapters/report-backend.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'bun:test';
+
+import { selectReport } from '../queries';
+import { createHttpAdapter, LoadError } from './adapter';
+import { createReportBackend, reportKey, sourceRuns } from './report-backend';
+
+const replaced = new Map<string, PropertyDescriptor | undefined>();
+
+/** Replace a global for one test; `afterEach` puts back whatever was there. */
+function stubGlobal(name: string, value: unknown) {
+  if (!replaced.has(name)) replaced.set(name, Object.getOwnPropertyDescriptor(globalThis, name));
+  Object.defineProperty(globalThis, name, { value, configurable: true, writable: true });
+}
+
+beforeEach(() => stubGlobal('window', { location: { href: 'https://atlas.example.test/site/' } }));
+afterEach(() => {
+  for (const [name, descriptor] of replaced) {
+    if (descriptor) Object.defineProperty(globalThis, name, descriptor);
+    else Reflect.deleteProperty(globalThis, name);
+  }
+  replaced.clear();
+});
+
+describe('report backends', () => {
+  it('keeps identical report ids from different backends separate and routes selection', () => {
+    const first = createReportBackend({ id: 'local', label: 'Local', type: 'http', baseUrl: '/local/' });
+    const second = createReportBackend({ id: 'ci', label: 'CI', type: 'api', baseUrl: '/ci/' });
+    const runs = [
+      ...sourceRuns(second, [{ id: 'same report', startedAt: '2026-10-09T12:00:00Z', progress: 'running' }]),
+      ...sourceRuns(first, [{ id: 'same report', startedAt: '2026-10-08T12:00:00Z', progress: 'complete' }])
+    ];
+    expect(new Set(runs.map((run) => run.id)).size).toBe(2);
+    expect(selectReport(runs, [first, second])?.backend.id).toBe('ci');
+    expect(selectReport(runs, [first, second], runs[1]!.id)?.backend.id).toBe('local');
+    expect(second.mediaUrl('same report', 'media/a.png')).toBe('https://atlas.example.test/ci/runs/same%20report/files/media/a.png');
+    expect(first.mediaUrl('same report', 'media/a.png')).toBe('https://atlas.example.test/local/runs/same%20report/media/a.png');
+  });
+
+  it('resolves qualified links before the source index arrives and retains legacy workspace links', () => {
+    const backend = createReportBackend({ id: 'workspace', label: 'Local', type: 'http', baseUrl: '/local/' });
+    expect(selectReport([], [backend], 'old-run')?.nativeId).toBe('old-run');
+    expect(selectReport([], [backend], reportKey('workspace', 'id with ~ and spaces'))?.nativeId).toBe('id with ~ and spaces');
+    expect(selectReport([], [backend], 'missing~run')).toBeNull();
+    expect(selectReport([], [backend], 'workspace~%broken')).toBeNull();
+  });
+
+  it('reads the API contract and reports an API outage instead of treating it as an empty source', async () => {
+    const fetch = vi.fn(async (_input: RequestInfo | URL) => new Response('{"runs":[]}'));
+    stubGlobal('fetch', fetch);
+    const adapter = createHttpAdapter('/api/', 'api');
+    await adapter.runsIndex();
+    expect(fetch.mock.calls[0]?.[0]).toBe('https://atlas.example.test/api/runs');
+    await adapter.manifest('run');
+    expect(fetch.mock.calls[1]?.[0]).toBe('https://atlas.example.test/api/runs/run/manifest');
+    fetch.mockImplementation(async () => new Response('', { status: 404 }));
+    await expect(adapter.runsIndex()).rejects.toBeInstanceOf(LoadError);
+    await expect(createHttpAdapter('/files/').runsIndex()).resolves.toEqual({ runs: [] });
+  });
+
+  it.each(['../private.png', '/private.png', '..\\private.png', 'media/../../secret'])('rejects media escaping its report: %s', (file) => {
+    expect(createHttpAdapter('/data/').mediaUrl('run', file)).toBe('');
+  });
+
+  it.each(['javascript:alert(1)', 'file:///reports', 'https://token@example.test/data'])(
+    'rejects an unsafe backend location: %s',
+    (url) => {
+      expect(() => createHttpAdapter(url)).toThrow();
+    }
+  );
+
+  it('refreshes after event-stream reconnection, ignores malformed events, and closes on unsubscribe', () => {
+    const streams: Stream[] = [];
+    class Stream extends EventTarget {
+      close = vi.fn();
+      constructor(readonly url: string) {
+        super();
+        streams.push(this);
+      }
+    }
+    stubGlobal('EventSource', Stream);
+    const adapter = createHttpAdapter('/api/', 'api', './events');
+    const receive = vi.fn();
+    const unsubscribe = adapter.subscribe!(receive);
+    const stream = streams[0]!;
+    expect(stream.url).toBe('https://atlas.example.test/api/events');
+    stream.dispatchEvent(new Event('open'));
+    expect(receive).toHaveBeenLastCalledWith({ scope: 'runs', files: [], runIds: [] });
+    stream.dispatchEvent(new MessageEvent('atlas:change', { data: '{"scope":"runs","runIds":["live"]}' }));
+    expect(receive).toHaveBeenLastCalledWith({ scope: 'runs', files: [], runIds: ['live'] });
+    stream.dispatchEvent(new MessageEvent('message', { data: '{broken' }));
+    stream.dispatchEvent(new MessageEvent('message', { data: '{"scope":"unknown"}' }));
+    expect(receive).toHaveBeenCalledTimes(2);
+    unsubscribe();
+    expect(stream.close).toHaveBeenCalledTimes(1);
+  });
+});

package/packages/visualizer/src/data/adapters/report-backend.ts

@@ -0,0 +1,42 @@
+import type { RemoteReportSource, RunSummary } from '@crvouga/atlas/schema';
+
+import type { AtlasAdapter } from './index';
+import { createDevAdapter, createHttpAdapter } from './index';
+
+export type ReportBackend = Pick<AtlasAdapter, 'label' | 'runsIndex' | 'manifest' | 'manifestPath' | 'mediaUrl' | 'subscribe'> & {
+  id: string;
+  kind: string;
+  cacheKey: string;
+  pollMs: number;
+};
+
+export type SourcedRunSummary = RunSummary & { sourceId: string; sourceLabel: string; nativeId: string };
+
+export function reportKey(sourceId: string, runId: string) {
+  return `${sourceId}~${encodeURIComponent(runId)}`;
+}
+
+export function sourceRuns(backend: ReportBackend, runs: RunSummary[]): SourcedRunSummary[] {
+  return runs.map((run) => ({
+    ...run,
+    id: reportKey(backend.id, run.id),
+    nativeId: run.id,
+    sourceId: backend.id,
+    sourceLabel: backend.label
+  }));
+}
+
+export function createReportBackend(config: RemoteReportSource): ReportBackend {
+  const adapter =
+    config.live && import.meta.hot
+      ? createDevAdapter(config.baseUrl, config.label, config.id)
+      : createHttpAdapter(config.baseUrl, config.type === 'api' ? 'api' : 'static', config.eventsUrl);
+  return {
+    ...adapter,
+    id: config.id,
+    label: config.label,
+    kind: config.live ? 'directory' : config.type,
+    cacheKey: JSON.stringify([config.id, config.type, adapter.label, config.baseUrl, config.eventsUrl]),
+    pollMs: config.pollMs ?? 10_000
+  };
+}