feat: Wave 3 — frontend API error parsing + WS exponential backoff

- api.ts: ApiRequestError parses server JSON error body, apiPost/apiDelete helpers
- ws.ts: exponential backoff (1s→30s max), ConnectionState tracking, typed event dispatch
- types.ts: TypeScript interfaces for 5 WS event types + API response types
- Bundle: 481KB (within budget)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

frontend/src/lib/api.ts

@@ -1,5 +1,17 @@
 const API_BASE = "/api/v1";
 
+export class ApiRequestError extends Error {
+  status: number;
+  serverMessage: string;
+
+  constructor(status: number, serverMessage: string) {
+    super(serverMessage);
+    this.name = "ApiRequestError";
+    this.status = status;
+    this.serverMessage = serverMessage;
+  }
+}
+
 export async function apiFetch<T>(
   path: string,
   init?: RequestInit,
@@ -9,9 +21,47 @@ export async function apiFetch<T>(
     ...init,
   });
   if (!res.ok) {
-    throw new Error(`API ${res.status}: ${res.statusText}`);
+    let serverMessage = res.statusText;
+    try {
+      const body = await res.json();
+      if (body?.error) {
+        serverMessage = body.error;
+      }
+    } catch {
+      // response body wasn't JSON, keep statusText
+    }
+    throw new ApiRequestError(res.status, serverMessage);
   }
   return res.json();
 }
 
+export async function apiPost<T>(
+  path: string,
+  body?: unknown,
+): Promise<T> {
+  return apiFetch<T>(path, {
+    method: "POST",
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+}
+
+export async function apiDelete(path: string): Promise<void> {
+  const res = await fetch(`${API_BASE}${path}`, {
+    method: "DELETE",
+    headers: { "Content-Type": "application/json" },
+  });
+  if (!res.ok) {
+    let serverMessage = res.statusText;
+    try {
+      const body = await res.json();
+      if (body?.error) {
+        serverMessage = body.error;
+      }
+    } catch {
+      // response body wasn't JSON, keep statusText
+    }
+    throw new ApiRequestError(res.status, serverMessage);
+  }
+}
+
 export const swrFetcher = <T>(path: string): Promise<T> => apiFetch<T>(path);

frontend/src/lib/types.ts

@@ -0,0 +1,63 @@
+// WebSocket event types matching Rust FlowEvent #[serde(tag="type", content="data")]
+
+export interface TaskStatusChanged {
+  task_id: string;
+  epic_id: string;
+  from_status: string;
+  to_status: string;
+}
+
+export interface DagMutated {
+  mutation: string;
+  details: unknown;
+}
+
+export interface AgentLog {
+  agent_id: string;
+  task_id: string;
+  level: string;
+  message: string;
+}
+
+export interface EpicUpdated {
+  epic_id: string;
+  field: string;
+  value: unknown;
+}
+
+// Heartbeat has no data (content is null in serde)
+export type Heartbeat = null;
+
+export type FlowEventType =
+  | "TaskStatusChanged"
+  | "DagMutated"
+  | "AgentLog"
+  | "EpicUpdated"
+  | "Heartbeat";
+
+export type FlowEventData =
+  | TaskStatusChanged
+  | DagMutated
+  | AgentLog
+  | EpicUpdated
+  | Heartbeat;
+
+/** Envelope sent over WebSocket: TimestampedEvent from Rust */
+export interface TimestampedEvent {
+  timestamp: string;
+  event: {
+    type: FlowEventType;
+    data?: FlowEventData;
+  };
+}
+
+/** Generic API response wrapper */
+export interface ApiResponse<T> {
+  data: T;
+}
+
+/** API error shape returned by the daemon */
+export interface ApiError {
+  error: string;
+  status: number;
+}

frontend/src/lib/ws.ts

@@ -1,26 +1,130 @@
-type EventHandler = (data: unknown) => void;
-
-export function connectEvents(onMessage: EventHandler): WebSocket {
-  const proto = window.location.protocol === "https:" ? "wss:" : "ws:";
-  const ws = new WebSocket(`${proto}//${window.location.host}/api/v1/events`);
-
-  ws.onmessage = (event) => {
-    try {
-      const data = JSON.parse(event.data);
-      onMessage(data);
-    } catch {
-      console.warn("Failed to parse WS message:", event.data);
+import type { FlowEventType, FlowEventData, TimestampedEvent } from "./types";
+
+export type ConnectionState = "connected" | "disconnected" | "reconnecting";
+
+type ConnectionChangeHandler = (state: ConnectionState) => void;
+type EventTypeHandler<T = FlowEventData> = (data: T, timestamp: string) => void;
+
+const MAX_BACKOFF_MS = 30_000;
+const PERSISTENT_WARNING_THRESHOLD = 5;
+
+export interface EventConnection {
+  /** Current connection state */
+  state: ConnectionState;
+  /** Register a handler for a specific event type */
+  on<T extends FlowEventData>(type: FlowEventType, handler: EventTypeHandler<T>): void;
+  /** Register a handler for connection state changes */
+  onConnectionChange(handler: ConnectionChangeHandler): void;
+  /** Close the connection (no reconnect) */
+  close(): void;
+}
+
+export function connectEvents(
+  onMessage?: (data: unknown) => void,
+): EventConnection {
+  let ws: WebSocket | null = null;
+  let closed = false;
+  let failures = 0;
+  let currentState: ConnectionState = "disconnected";
+
+  const connectionChangeHandlers: ConnectionChangeHandler[] = [];
+  const eventHandlers = new Map<FlowEventType, EventTypeHandler[]>();
+
+  function setState(s: ConnectionState) {
+    currentState = s;
+    connection.state = s;
+    for (const h of connectionChangeHandlers) {
+      h(s);
     }
-  };
+  }
 
-  ws.onerror = (err) => {
-    console.error("WebSocket error:", err);
-  };
+  function backoffMs(): number {
+    // 1s, 2s, 4s, 8s, 16s, capped at 30s
+    const ms = Math.min(1000 * Math.pow(2, failures), MAX_BACKOFF_MS);
+    return ms;
+  }
+
+  function connect() {
+    if (closed) return;
+
+    const proto = window.location.protocol === "https:" ? "wss:" : "ws:";
+    ws = new WebSocket(`${proto}//${window.location.host}/api/v1/events`);
+
+    ws.onopen = () => {
+      failures = 0;
+      setState("connected");
+    };
+
+    ws.onmessage = (event) => {
+      try {
+        const raw = JSON.parse(event.data);
+
+        // Legacy callback
+        if (onMessage) {
+          onMessage(raw);
+        }
+
+        // Typed dispatch: TimestampedEvent = {timestamp, event: {type, data?}}
+        const stamped = raw as TimestampedEvent;
+        if (stamped?.event?.type) {
+          const handlers = eventHandlers.get(stamped.event.type);
+          if (handlers) {
+            for (const h of handlers) {
+              h(stamped.event.data ?? null, stamped.timestamp);
+            }
+          }
+        }
+      } catch {
+        console.warn("Failed to parse WS message:", event.data);
+      }
+    };
+
+    ws.onerror = () => {
+      // onerror is always followed by onclose, handle reconnect there
+    };
+
+    ws.onclose = () => {
+      if (closed) {
+        setState("disconnected");
+        return;
+      }
+
+      failures++;
+      setState("reconnecting");
+
+      if (failures >= PERSISTENT_WARNING_THRESHOLD) {
+        console.warn(
+          `WebSocket reconnect attempt ${failures} — daemon may be restarting`,
+        );
+      }
+
+      const delay = backoffMs();
+      setTimeout(connect, delay);
+    };
+  }
+
+  const connection: EventConnection = {
+    state: currentState,
+
+    on<T extends FlowEventData>(type: FlowEventType, handler: EventTypeHandler<T>) {
+      let handlers = eventHandlers.get(type);
+      if (!handlers) {
+        handlers = [];
+        eventHandlers.set(type, handlers);
+      }
+      handlers.push(handler as EventTypeHandler);
+    },
+
+    onConnectionChange(handler: ConnectionChangeHandler) {
+      connectionChangeHandlers.push(handler);
+    },
 
-  ws.onclose = () => {
-    // Reconnect after 3 seconds
-    setTimeout(() => connectEvents(onMessage), 3000);
+    close() {
+      closed = true;
+      ws?.close();
+    },
   };
 
-  return ws;
+  connect();
+  return connection;
 }