Task e57facc2: Undo and live SSE updates in the admin PWA

- api/events.ts: fetch-based reader for GET /api/v1/admin/events (admin JWT
  in the Authorization header via apiFetch, never in the URL), an incremental
  SSE frame parser that buffers frames split across chunks and drops malformed
  frames, and bounded-backoff reconnect with a clean abort on stop.
- api/useTransitions.tsx: one stream per signed-in shell (TransitionsProvider
  in App) fanned out to screens; no provider means no stream.
- Today: Undo posts /instances/{id}/uncomplete, disables every Undo while in
  flight, shows a dismissible message on failure, and refetches the snapshot;
  any transition refetches in place. Mark done stays inert.
- History: quest transitions refetch the active filter in place; rows stay
  read-only.
- Tests for parsing, stream auth/teardown/reconnect, Undo, and live refetch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

admin/src/today/TodayTab.css

@@ -241,6 +241,37 @@
   color: var(--nq-brand-purple);
 }
 
+.today-action:disabled {
+  cursor: default;
+  opacity: 0.5;
+}
+
+/* Non-blocking Undo failure message. */
+.today-action-error {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  padding: var(--nq-a-density-row-pad);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-danger-bg);
+  color: var(--nq-a-danger-strong);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.today-action-dismiss {
+  flex: none;
+  padding: 4px 8px;
+  border: none;
+  background: none;
+  color: inherit;
+  font-family: inherit;
+  font-size: 12.5px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
 .today-empty {
   padding: var(--nq-a-density-card-pad);
   font-size: 13px;

admin/src/today/TodayTab.test.tsx

@@ -1,7 +1,9 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-import { cleanup, fireEvent, render, screen, within } from "@testing-library/react";
+import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
 import TodayTab, { PERMISSION_NOTE } from "./TodayTab";
 import type { AdminSnapshot, SnapshotInstance } from "../api/snapshot";
+import { TransitionsProvider } from "../api/useTransitions";
+import { frame, testStream, type TestStream } from "../api/testStream";
 import { storeTokens } from "../auth/oidc";
 
 function instance(overrides: Partial<SnapshotInstance>): SnapshotInstance {
@@ -221,3 +223,186 @@ describe("TodayTab", () => {
     expect(error.textContent).toContain("nestquest-admins");
   });
 });
+
+/** SNAPSHOT after instance 12 ("Make bed") is reversed back to open. */
+const AFTER_UNDO: AdminSnapshot = {
+  ...SNAPSHOT,
+  children: SNAPSHOT.children.map((child) =>
+    child.child_id !== 1
+      ? child
+      : {
+          ...child,
+          completed_today: 2,
+          remaining_today: 5,
+          completion_pct: 29,
+          instances: child.instances.map((i) =>
+            i.id === 12 ? { ...i, state: "open" as const, completed_at: null, on_time: null } : i,
+          ),
+        },
+  ),
+};
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+
+describe("TodayTab Undo and live updates", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+  let snapshots: AdminSnapshot[];
+  let uncomplete: () => Promise<Response>;
+  let streams: TestStream[];
+
+  function calls(pathSuffix: string, method = "GET") {
+    return fetchMock.mock.calls.filter(
+      ([url, init]) =>
+        new URL(String(url), "http://x").pathname.endsWith(pathSuffix) &&
+        (init?.method ?? "GET") === method,
+    );
+  }
+
+  beforeAll(() => {
+    vi.stubEnv("TZ", "America/Los_Angeles");
+  });
+
+  afterAll(() => {
+    vi.unstubAllEnvs();
+  });
+
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    snapshots = [SNAPSHOT, AFTER_UNDO];
+    uncomplete = () =>
+      Promise.resolve(jsonResponse({ instance_id: 12, state: "open", appended: true }));
+    streams = [];
+    fetchMock = vi.fn((url: string) => {
+      const path = new URL(url, "http://x").pathname;
+      if (path.endsWith("/api/v1/admin/snapshot")) {
+        const next = snapshots.length > 1 ? snapshots.shift()! : snapshots[0];
+        return Promise.resolve(jsonResponse(next));
+      }
+      if (path.endsWith("/api/v1/admin/instances/12/uncomplete")) return uncomplete();
+      if (path.endsWith("/api/v1/admin/events")) {
+        const stream = testStream();
+        streams.push(stream);
+        return Promise.resolve(stream.response);
+      }
+      return Promise.resolve(jsonResponse({ detail: "unexpected" }, 500));
+    });
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("Undo POSTs uncomplete for the completed instance and refetches the snapshot", async () => {
+    render(<TodayTab />);
+    const row = await screen.findByTestId("attention-12");
+    fireEvent.click(within(row).getByRole("button", { name: "Undo" }));
+
+    await waitFor(() => expect(screen.queryByTestId("attention-12")).toBeNull());
+    const posts = calls("/api/v1/admin/instances/12/uncomplete", "POST");
+    expect(posts).toHaveLength(1);
+    expect(posts[0][1].headers.Authorization).toBe("Bearer at-123");
+    expect(calls("/api/v1/admin/snapshot")).toHaveLength(2);
+    // The reversed instance is open again: one fewer done, one more remaining.
+    expect(screen.getByTestId("stat-done").textContent).toBe("6Done");
+    expect(screen.getByTestId("stat-remaining").textContent).toBe("5Remaining");
+    expect(screen.queryByTestId("today-undo-error")).toBeNull();
+  });
+
+  it("disables Undo while the request is in flight (no double submit)", async () => {
+    const pending = deferred<Response>();
+    uncomplete = () => pending.promise;
+    render(<TodayTab />);
+    const row = await screen.findByTestId("attention-12");
+    const button = within(row).getByRole("button", { name: "Undo" }) as HTMLButtonElement;
+
+    fireEvent.click(button);
+    await waitFor(() => expect(button.disabled).toBe(true));
+    expect(button.textContent).toBe("Undoing…");
+    // Every Undo is disabled while one reversal is in flight.
+    const other = within(screen.getByTestId("attention-14")).getByRole("button", {
+      name: "Undo",
+    }) as HTMLButtonElement;
+    expect(other.disabled).toBe(true);
+    fireEvent.click(button);
+    fireEvent.click(other);
+    expect(calls("/api/v1/admin/instances/12/uncomplete", "POST")).toHaveLength(1);
+    expect(calls("/uncomplete", "POST")).toHaveLength(1);
+
+    pending.resolve(jsonResponse({ instance_id: 12, state: "open", appended: true }));
+    await waitFor(() => expect(screen.queryByTestId("attention-12")).toBeNull());
+    expect(other.disabled).toBe(false);
+  });
+
+  it("a failed Undo shows a message and leaves the view intact", async () => {
+    uncomplete = () => Promise.resolve(jsonResponse({ detail: "instance 12 not found" }, 404));
+    render(<TodayTab />);
+    const row = await screen.findByTestId("attention-12");
+    fireEvent.click(within(row).getByRole("button", { name: "Undo" }));
+
+    const alert = await screen.findByTestId("today-undo-error");
+    expect(alert.textContent).toContain("The completion could not be undone: instance 12 not found");
+    // Still the original snapshot: nothing refetched, the row and its Undo remain usable.
+    expect(calls("/api/v1/admin/snapshot")).toHaveLength(1);
+    const button = within(screen.getByTestId("attention-12")).getByRole("button", {
+      name: "Undo",
+    }) as HTMLButtonElement;
+    expect(button.disabled).toBe(false);
+    expect(screen.getByTestId("stat-done").textContent).toBe("7Done");
+
+    fireEvent.click(within(alert).getByRole("button", { name: "Dismiss" }));
+    expect(screen.queryByTestId("today-undo-error")).toBeNull();
+  });
+
+  it("Mark done stays inert", async () => {
+    render(<TodayTab />);
+    const row = await screen.findByTestId("attention-11");
+    fireEvent.click(within(row).getByRole("button", { name: "Mark done" }));
+    expect(fetchMock.mock.calls.filter(([, init]) => init?.method === "POST")).toHaveLength(0);
+  });
+
+  it("a transition on the live stream refetches the snapshot without a reload", async () => {
+    const { unmount } = render(
+      <TransitionsProvider>
+        <TodayTab />
+      </TransitionsProvider>,
+    );
+    await screen.findByTestId("attention-12");
+    await waitFor(() => expect(streams).toHaveLength(1));
+    const [, init] = calls("/api/v1/admin/events")[0];
+    expect(init.headers.Authorization).toBe("Bearer at-123");
+
+    // An uncompletion made elsewhere, its frame split across two chunks.
+    const text = frame("nestquest_quest_uncompleted", {
+      child_id: 1,
+      child_name: "Declan",
+      instance_id: 12,
+      quest_title: "Make bed",
+      window: "morning",
+      due_date: "2026-09-23",
+      due_time: null,
+      occurred_at: "2026-09-23T12:00:00Z",
+    });
+    streams[0].push(text.slice(0, 25));
+    streams[0].push(text.slice(25));
+
+    await waitFor(() => expect(calls("/api/v1/admin/snapshot")).toHaveLength(2));
+    await waitFor(() => expect(screen.queryByTestId("attention-12")).toBeNull());
+    // Refreshed in place: the loading state never replaced the view.
+    expect(screen.queryByTestId("today-loading")).toBeNull();
+
+    const signal = init.signal as AbortSignal;
+    expect(signal.aborted).toBe(false);
+    unmount();
+    expect(signal.aborted).toBe(true);
+    await waitFor(() => expect(streams[0].cancelled()).toBe(true));
+  });
+});

admin/src/today/TodayTab.tsx

@@ -1,7 +1,7 @@
 /**
  * Today tab — compact density (design/ADMIN-SPEC.md §2.1–2.3, §2.5–2.6).
  */
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import {
   fetchSnapshot,
   type AdminSnapshot,
@@ -9,6 +9,9 @@ import {
   type SnapshotInstance,
 } from "../api/snapshot";
 import { ApiForbiddenError } from "../api/client";
+import { ApiRequestError } from "../api/definitions";
+import { uncompleteInstance } from "../api/instances";
+import { useTransitions } from "../api/useTransitions";
 import {
   formatClockTime,
   formatDueTime,
@@ -144,11 +147,18 @@ function attentionItems(snapshot: AdminSnapshot): AttentionItem[] {
   return [...overdue, ...completed];
 }
 
-function AttentionRow({ item }: { item: AttentionItem }) {
+interface UndoControl {
+  /** The instance whose Undo is in flight, or null. */
+  pendingId: number | null;
+  onUndo: (instanceId: number) => void;
+}
+
+function AttentionRow({ item, undo }: { item: AttentionItem; undo: UndoControl }) {
   const { instance, childName } = item;
   const overdue = isOverdueOpen(instance);
-  // TODO(e57facc2): wire "Mark done" / "Undo" mutations and live updates.
-  // The admin plane has no complete route yet, so both actions are inert here.
+  const undoing = undo.pendingId === instance.id;
+  // TODO(e57facc2): wire "Mark done". The admin plane has no complete route
+  // yet, so that action is inert here.
   return (
     <li className="today-event" data-testid={`attention-${instance.id}`}>
       <span
@@ -173,12 +183,21 @@ function AttentionRow({ item }: { item: AttentionItem }) {
           </div>
         )}
       </div>
-      <button
-        type="button"
-        className={overdue ? "today-action today-action--done" : "today-action today-action--undo"}
-      >
-        {overdue ? "Mark done" : "Undo"}
-      </button>
+      {overdue ? (
+        <button type="button" className="today-action today-action--done">
+          Mark done
+        </button>
+      ) : (
+        <button
+          type="button"
+          className="today-action today-action--undo"
+          disabled={undo.pendingId !== null}
+          aria-busy={undoing}
+          onClick={() => undo.onUndo(instance.id)}
+        >
+          {undoing ? "Undoing…" : "Undo"}
+        </button>
+      )}
     </li>
   );
 }
@@ -197,10 +216,25 @@ function PermissionNote() {
 export default function TodayTab() {
   const [state, setState] = useState<LoadState>({ kind: "loading" });
   const [attempt, setAttempt] = useState(0);
+  /** The next load is a refresh in place: keep the current view, no loading state. */
+  const silentNext = useRef(false);
+  const [undoingId, setUndoingId] = useState<number | null>(null);
+  const undoingRef = useRef(false);
+  const [undoError, setUndoError] = useState<string | null>(null);
+
+  function refresh() {
+    silentNext.current = true;
+    setAttempt((n) => n + 1);
+  }
+
+  // Any transition (completed, uncompleted, missed, day complete) changes the snapshot.
+  useTransitions(refresh);
 
   useEffect(() => {
     let cancelled = false;
-    setState({ kind: "loading" });
+    const silent = silentNext.current;
+    silentNext.current = false;
+    if (!silent) setState({ kind: "loading" });
     fetchSnapshot()
       .then((snapshot) => {
         if (!cancelled) setState({ kind: "ready", snapshot });
@@ -211,13 +245,37 @@ export default function TodayTab() {
           error instanceof ApiForbiddenError
             ? error.message
             : "Today's snapshot could not be loaded. Check your connection and try again.";
-        setState({ kind: "error", message });
+        // A failed refresh keeps the snapshot already on screen.
+        setState((prev) => (silent && prev.kind === "ready" ? prev : { kind: "error", message }));
       });
     return () => {
       cancelled = true;
     };
   }, [attempt]);
 
+  /** Reverse one completion, then refetch the snapshot. One request at a time. */
+  async function undo(instanceId: number) {
+    if (undoingRef.current) return;
+    undoingRef.current = true;
+    setUndoingId(instanceId);
+    setUndoError(null);
+    try {
+      await uncompleteInstance(instanceId);
+      refresh();
+    } catch (error: unknown) {
+      setUndoError(
+        error instanceof ApiForbiddenError
+          ? error.message
+          : error instanceof ApiRequestError && error.detail
+            ? `The completion could not be undone: ${error.detail}`
+            : "The completion could not be undone. Check your connection and try again.",
+      );
+    } finally {
+      undoingRef.current = false;
+      setUndoingId(null);
+    }
+  }
+
   let sub = "";
   let body;
   if (state.kind === "loading") {
@@ -251,7 +309,11 @@ export default function TodayTab() {
         {attention.length > 0 ? (
           <ul className="today-card today-list" aria-label="Needs attention">
             {attention.map((item) => (
-              <AttentionRow key={item.instance.id} item={item} />
+              <AttentionRow
+                key={item.instance.id}
+                item={item}
+                undo={{ pendingId: undoingId, onUndo: (id) => void undo(id) }}
+              />
             ))}
           </ul>
         ) : (
@@ -270,6 +332,14 @@ export default function TodayTab() {
         data-testid="today-scroll"
         style={{ paddingBottom: SCROLL_BOTTOM_PADDING }}
       >
+        {undoError !== null ? (
+          <div className="today-action-error" role="alert" data-testid="today-undo-error">
+            <span>{undoError}</span>
+            <button type="button" className="today-action-dismiss" onClick={() => setUndoError(null)}>
+              Dismiss
+            </button>
+          </div>
+        ) : null}
         {body}
       </div>
     </div>