feat(web): progress subscriber + useProgress hook

web/src/lib/progress.ts

@@ -0,0 +1,75 @@
+export type ProgressState =
+  | { phase: "idle" }
+  | {
+      phase: "running";
+      kind: "single" | "dialog";
+      turn: number;
+      total: number;
+      elapsedS: number;
+    }
+  | { phase: "done"; elapsedS: number }
+  | { phase: "error"; message: string };
+
+type ProgressEvent = {
+  type: "start" | "tick" | "turn_complete" | "done" | "error";
+  elapsed_s: number;
+  kind?: "single" | "dialog";
+  turn?: number;
+  total_turns?: number;
+  message?: string;
+  seed_used?: number | null;
+};
+
+export function subscribeProgress(
+  onState: (s: ProgressState) => void,
+): () => void {
+  const es = new EventSource("/api/progress");
+  let doneTimer: number | null = null;
+
+  es.onmessage = (m: MessageEvent) => {
+    if (doneTimer !== null) {
+      window.clearTimeout(doneTimer);
+      doneTimer = null;
+    }
+    let evt: ProgressEvent;
+    try {
+      evt = JSON.parse(m.data) as ProgressEvent;
+    } catch {
+      return;
+    }
+    if (evt.type === "start" || evt.type === "tick" || evt.type === "turn_complete") {
+      onState({
+        phase: "running",
+        kind: (evt.kind ?? "single"),
+        turn: evt.turn ?? 0,
+        total: evt.total_turns ?? 1,
+        elapsedS: evt.elapsed_s ?? 0,
+      });
+      return;
+    }
+    if (evt.type === "done") {
+      onState({ phase: "done", elapsedS: evt.elapsed_s });
+      doneTimer = window.setTimeout(() => onState({ phase: "idle" }), 1000);
+      return;
+    }
+    if (evt.type === "error") {
+      onState({ phase: "error", message: evt.message ?? "Generation failed" });
+    }
+  };
+
+  return () => {
+    if (doneTimer !== null) window.clearTimeout(doneTimer);
+    es.close();
+  };
+}
+
+import { useEffect, useState } from "react";
+
+export function useProgress(): ProgressState {
+  const [state, setState] = useState<ProgressState>({ phase: "idle" });
+  useEffect(() => {
+    const close = subscribeProgress(setState);
+    return close;
+  }, []);
+  return state;
+}

web/src/test/progress.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { subscribeProgress, type ProgressState } from "@/lib/progress";
+
+class MockEventSource {
+  url: string;
+  onmessage: ((m: { data: string }) => void) | null = null;
+  closed = false;
+  static last: MockEventSource;
+  constructor(url: string) {
+    this.url = url;
+    MockEventSource.last = this;
+  }
+  emit(data: object) {
+    this.onmessage?.({ data: JSON.stringify(data) });
+  }
+  close() {
+    this.closed = true;
+  }
+}
+
+beforeEach(() => {
+  vi.stubGlobal("EventSource", MockEventSource);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("subscribeProgress", () => {
+  it("emits running on start", () => {
+    const states: ProgressState[] = [];
+    subscribeProgress((s) => states.push(s));
+    MockEventSource.last.emit({
+      type: "start", elapsed_s: 0, kind: "dialog", total_turns: 3, turn: 0,
+    });
+    expect(states[0]).toMatchObject({ phase: "running", kind: "dialog", total: 3 });
+  });
+
+  it("updates turn on turn_complete", () => {
+    const states: ProgressState[] = [];
+    subscribeProgress((s) => states.push(s));
+    MockEventSource.last.emit({
+      type: "start", elapsed_s: 0, kind: "dialog", total_turns: 3, turn: 0,
+    });
+    MockEventSource.last.emit({
+      type: "turn_complete", elapsed_s: 1.2, kind: "dialog", total_turns: 3, turn: 2,
+    });
+    const last = states[states.length - 1];
+    expect(last).toMatchObject({ phase: "running", turn: 2, total: 3 });
+  });
+
+  it("transitions to done then idle", async () => {
+    vi.useFakeTimers();
+    const states: ProgressState[] = [];
+    subscribeProgress((s) => states.push(s));
+    MockEventSource.last.emit({ type: "done", elapsed_s: 4.5 });
+    expect(states[states.length - 1]).toMatchObject({ phase: "done", elapsedS: 4.5 });
+    vi.advanceTimersByTime(1100);
+    expect(states[states.length - 1]).toMatchObject({ phase: "idle" });
+    vi.useRealTimers();
+  });
+
+  it("emits error", () => {
+    const states: ProgressState[] = [];
+    subscribeProgress((s) => states.push(s));
+    MockEventSource.last.emit({
+      type: "error", elapsed_s: 2, message: "boom",
+    });
+    expect(states[states.length - 1]).toMatchObject({ phase: "error", message: "boom" });
+  });
+
+  it("close() shuts down EventSource", () => {
+    const close = subscribeProgress(() => {});
+    close();
+    expect(MockEventSource.last.closed).toBe(true);
+  });
+});