refactor: wave 4 — TanStack Query API layer + convert worst fetch hotspot

frontend/package.json

@@ -15,6 +15,7 @@
     "typecheck": "tsc -b --noEmit"
   },
   "dependencies": {
+    "@tanstack/react-query": "^5.99.2",
     "@types/diff": "^7.0.2",
     "diff": "^8.0.4",
     "prism-react-renderer": "^2.4.1",
@@ -23,7 +24,8 @@
     "react-markdown": "^10.1.0",
     "react-router-dom": "^7.14.0",
     "recharts": "^2.13.0",
-    "remark-gfm": "^4.0.1"
+    "remark-gfm": "^4.0.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",

frontend/src/api/client.ts

@@ -0,0 +1,82 @@
+/**
+ * Typed fetch wrapper for the SKLD backend.
+ *
+ * One place for: base URL resolution, default headers, error shaping,
+ * response parsing. Every API hook in `src/api/hooks/` runs through this.
+ * No component should ever call `fetch` directly — see docs/clean-code.md §8.
+ */
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly url: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+type RequestInitExt = Omit<RequestInit, "body"> & {
+  body?: unknown;
+};
+
+async function request<T>(path: string, init: RequestInitExt = {}): Promise<T> {
+  const { body, headers, ...rest } = init;
+  const isJson = body !== undefined && !(body instanceof FormData);
+  const response = await fetch(path, {
+    ...rest,
+    headers: {
+      ...(isJson ? { "Content-Type": "application/json" } : {}),
+      ...headers,
+    },
+    body: body === undefined ? undefined : body instanceof FormData ? body : JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    // Try to surface the FastAPI `detail` field when present.
+    let detail: string | undefined;
+    try {
+      const payload = (await response.json()) as { detail?: string };
+      detail = payload?.detail;
+    } catch {
+      // Body wasn't JSON — fall through to generic message.
+    }
+    throw new ApiError(
+      response.status,
+      path,
+      detail ?? `${response.status} ${response.statusText}`,
+    );
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    return (await response.json()) as T;
+  }
+  // Callers that want bytes / text must use `requestText` / `requestBlob`.
+  return (await response.text()) as unknown as T;
+}
+
+async function requestText(path: string, init: RequestInitExt = {}): Promise<string> {
+  const response = await fetch(path, init as RequestInit);
+  if (!response.ok) {
+    throw new ApiError(response.status, path, `${response.status} ${response.statusText}`);
+  }
+  return response.text();
+}
+
+async function requestBlob(path: string, init: RequestInitExt = {}): Promise<Blob> {
+  const response = await fetch(path, init as RequestInit);
+  if (!response.ok) {
+    throw new ApiError(response.status, path, `${response.status} ${response.statusText}`);
+  }
+  return response.blob();
+}
+
+export const apiClient = {
+  get: <T>(path: string) => request<T>(path, { method: "GET" }),
+  getText: (path: string) => requestText(path, { method: "GET" }),
+  getBlob: (path: string) => requestBlob(path, { method: "GET" }),
+  post: <T>(path: string, body?: unknown) => request<T>(path, { method: "POST", body }),
+  delete: <T>(path: string) => request<T>(path, { method: "DELETE" }),
+};

frontend/src/api/hooks/runs.ts

@@ -0,0 +1,83 @@
+/**
+ * React Query hooks for /api/runs/* endpoints.
+ *
+ * One hook per endpoint. See docs/clean-code.md §8 — no raw fetch()
+ * in components, no manual useEffect chains for data-fetching, no
+ * custom loading/error/retry logic. React Query owns all of that.
+ */
+
+import { useQuery } from "@tanstack/react-query";
+
+import { apiClient } from "@/api/client";
+import type {
+  BenchFamilyDetail,
+  DimensionStatus,
+  LineageEdge,
+  LineageNode,
+  RunDetail,
+  RunReport,
+  Variant,
+} from "@/types";
+
+interface LineagePayload {
+  nodes: LineageNode[];
+  edges: LineageEdge[];
+}
+
+const runKey = (runId: string) => ["run", runId] as const;
+
+export function useRun(runId: string | null) {
+  return useQuery({
+    queryKey: runKey(runId ?? "").concat("detail") as readonly unknown[],
+    queryFn: () => apiClient.get<RunDetail>(`/api/runs/${runId}`),
+    enabled: !!runId,
+  });
+}
+
+export function useRunReport(runId: string | null) {
+  return useQuery({
+    queryKey: [...runKey(runId ?? ""), "report"],
+    queryFn: () => apiClient.get<RunReport>(`/api/runs/${runId}/report`),
+    enabled: !!runId,
+  });
+}
+
+export function useRunDimensions(runId: string | null) {
+  return useQuery({
+    queryKey: [...runKey(runId ?? ""), "dimensions"],
+    queryFn: () => apiClient.get<DimensionStatus[]>(`/api/runs/${runId}/dimensions`),
+    enabled: !!runId,
+  });
+}
+
+export function useRunLineage(runId: string | null) {
+  return useQuery({
+    queryKey: [...runKey(runId ?? ""), "lineage"],
+    queryFn: () => apiClient.get<LineagePayload>(`/api/runs/${runId}/lineage`),
+    enabled: !!runId,
+  });
+}
+
+export function useRunSkillMd(runId: string | null) {
+  return useQuery({
+    queryKey: [...runKey(runId ?? ""), "skill_md"],
+    queryFn: () => apiClient.getText(`/api/runs/${runId}/export?format=skill_md`),
+    enabled: !!runId,
+  });
+}
+
+export function useFamilyVariants(familyId: string | null | undefined) {
+  return useQuery({
+    queryKey: ["family", familyId, "variants"] as const,
+    queryFn: () => apiClient.get<Variant[]>(`/api/families/${familyId}/variants`),
+    enabled: !!familyId,
+  });
+}
+
+export function useBenchFamily(slug: string | null | undefined) {
+  return useQuery({
+    queryKey: ["bench", slug] as const,
+    queryFn: () => apiClient.get<BenchFamilyDetail>(`/api/bench/${slug}`),
+    enabled: !!slug,
+  });
+}