feat(editor): move admin settings onto TanStack Query (#7437)

# Description of Changes

## The problem

`useAdminSettings` backs all 18 admin config sections. Each section
fetched its own copy of its settings block, held it in hand-rolled
loading/saving state, and refetched manually after every save.

Three consequences:

- **Duplicate fetching.** Four AI tabs all read the `aiEngine` block.
Nothing was shared, so each open refetched it.
- **Duplicated wiring.** All 18 sections carried the same effect to
trigger the fetch, each one depending on a `fetchSettings` callback that
would have refetched on every render had it ever become unstable.
- **Console noise.** The hook made 11 `console.*` calls, four of them
`JSON.stringify(settings, null, 2)` on **every fetch and every save** —
admin configuration serialised into the console of every admin session.

Every save also ended with a hand-written `await fetchSettings()`.
Forget it in a new section and its pending badges silently go stale.

## The fix

The hook uses TanStack Query, keyed on `sectionName`, so sections
reading the same block share one fetch and one cache entry.

The fetch gate moved into the hook. Sections used to write:

```ts
const { settings, fetchSettings } = useAdminSettings({ sectionName: "legal" });

useEffect(() => {
  if (loginEnabled) fetchSettings();
}, [loginEnabled, fetchSettings]);
```

and now write:

```ts
const { settings } = useAdminSettings({
  sectionName: "legal",
  enabled: loginEnabled,
});
```

Saving is a mutation that invalidates the section on success, so the
refetch is structural rather than something each section remembers.

The delta computation and the save transformer are unchanged — that is
domain logic, not fetching. `settings` is still an editable draft seeded
from the server response, so forms behave exactly as before.

## Why it is better

Measured against the previous implementation across identical scenarios.
`commits` counts committed renders.

| Scenario | Before | After |
|---|---|---|
| Open one section | 2 commits, 1 request | 2 commits, 1 request |
| Browse the four AI tabs | 8 commits, 4 requests | **5 commits, 1
request** |
| Edit and save | 4 commits, 2 requests | 4 commits, 2 requests |

Committed renders are equal or better everywhere; browsing the AI tabs
costs a quarter of the requests.

The diff reads +449 / −303, but that includes a test file for a hook
that had no tests:

| | Added | Removed | Net |
|---|---|---|---|
| Production code (21 files) | 154 | 303 | **−149** |
| Tests (1 file) | 295 | 0 | +295 |

The 18 section files account for −133 of that: each drops an effect, a
destructure and usually an import, and gains one `enabled:` line. The
hook itself goes from 234 to 180 lines. `console.*` calls go from 11 to
0.

## Caching

Settings inherit the client's 30s stale window rather than refetching on
every mount, which is where the request saving comes from.

Nothing inside a cached block is server-observed — the only live reads
in these sections, `/api/v1/ai/health` and the tessdata language list,
are separate calls outside this query. A block therefore only changes
when another admin writes it.

Two things bound the staleness:

- Sections already held a single snapshot for as long as the modal
stayed open, with no refetch on focus. 30s is shorter than that window,
not longer.
- `computeDelta` only emits fields whose draft differs from the baseline
it was seeded from, so a stale baseline cannot produce a collateral
write. The only race is two admins editing the same field, which is
unchanged. Saving invalidates, so acting refreshes to current values.

The blocks where a stale read would matter most — `security`, `premium`,
`database` — are set once at deployment and effectively never edited
concurrently. The block with the most cache reuse, `aiEngine`, is the
least consequential.

**Convention:** config blocks cache; observed state does not. A section
that displays live server state inside its settings block should
override `staleTime` locally.

## Testing

14 tests, covering the shared fetch, cache reuse across tab reopens, key
separation between blocks, the `enabled` gate, delta-only saves, the
empty-delta short circuit, post-save invalidation, pending-value
display, and draft reseeding.

Each was checked by breaking the implementation and confirming the suite
fails: per-consumer query keys, sending the whole draft instead of the
delta, dropping the post-save invalidate, reporting loaded while
disabled, skipping the empty-delta short circuit, and reverting the
stale window to zero.

`task frontend:check` green. Two unrelated tests fail on this branch —
`workbenchSession.test.ts` and `notificationActions.test.tsx` — and fail
identically on `main`.

## Follow-ups

The sections that fetch through services rather than this hook — Teams,
TeamDetails, People, roughly 2,600 lines — are unchanged. Between them
they share two reads (`getTeams` and `getUsers`, both used by all three)
and carry ten distinct write operations, with no test coverage today.

---

## Primer: mutations

`useQuery` is for reads. It caches, dedupes, and re-renders when data
arrives. `useMutation` is for writes, where none of that applies — a
write happens once, when the user asks.

```ts
const save = useMutation({
  mutationFn: (body) => putAdminSection("legal", body),
  onSuccess: () => queryClient.invalidateQueries({ queryKey }),
});

save.mutate(body);            // fire and forget
await save.mutateAsync(body); // or await it
save.isPending;               // disable the button
save.error;                   // show the failure
```

`isPending` and `error` replace the `useState` flag and
`try/catch/finally` you would otherwise write around every save.

After a write the cache holds stale data. Two ways to fix it:

| | What it does | Use when |
|---|---|---|
| `invalidateQueries` | Marks the data stale so it refetches | The
server may transform, queue or reject part of what you sent |
| `setQueryData` | Writes your value into the cache, no request | The
response tells you exactly what the server now holds |

**Invalidate by default. Use `setQueryData` only when the response is
authoritative.**

This hook has to invalidate: the server can queue a settings change
rather than applying it, returning it in a `_pending` block that the
form renders as a badge. Writing the local draft into the cache would
show a queued change as applied.

Most mutations are not like that. A "rename a team" write, where the
response is the new team, is a `setQueryData` case.

One gotcha: `mutate` does not throw, `mutateAsync` does. An awaited
`mutateAsync` without a `try/catch` is an unhandled rejection.

Author: ConnorYoh

frontend/editor/src/core/api/adminSettings.ts

@@ -0,0 +1,22 @@
+import apiClient from "@app/services/apiClient";
+
+export async function fetchAdminSection<T>(sectionName: string): Promise<T> {
+  const response = await apiClient.get<T>(
+    `/api/v1/admin/settings/section/${sectionName}`,
+  );
+  return (response.data ?? {}) as T;
+}
+
+export async function putAdminSection(
+  sectionName: string,
+  delta: unknown,
+): Promise<void> {
+  await apiClient.put(`/api/v1/admin/settings/section/${sectionName}`, delta);
+}
+
+/** Flat dotted-path settings, for sections that write outside their own block. */
+export async function putAdminSettings(
+  settings: Record<string, unknown>,
+): Promise<void> {
+  await apiClient.put("/api/v1/admin/settings", { settings });
+}

frontend/editor/src/core/hooks/useAdminSettings.test.tsx

@@ -0,0 +1,313 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+import { useAdminSettings } from "@app/hooks/useAdminSettings";
+import { qk } from "@app/query/keys";
+import {
+  fetchAdminSection,
+  putAdminSection,
+  putAdminSettings,
+} from "@app/api/adminSettings";
+
+vi.mock("@app/api/adminSettings", () => ({
+  fetchAdminSection: vi.fn(),
+  putAdminSection: vi.fn(),
+  putAdminSettings: vi.fn(),
+}));
+
+const mockFetch = vi.mocked(fetchAdminSection);
+const mockPutSection = vi.mocked(putAdminSection);
+const mockPutSettings = vi.mocked(putAdminSettings);
+
+function makeWrapper() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={client}>{children}</QueryClientProvider>
+  );
+}
+
+describe("useAdminSettings", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockFetch.mockResolvedValue({ appName: "Stirling" });
+    mockPutSection.mockResolvedValue(undefined);
+    mockPutSettings.mockResolvedValue(undefined);
+  });
+
+  it("loads the section and seeds the editable draft", async () => {
+    const { result } = renderHook(
+      () => useAdminSettings({ sectionName: "general" }),
+      { wrapper: makeWrapper() },
+    );
+
+    expect(result.current.loading).toBe(true);
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.settings).toEqual({ appName: "Stirling" });
+    expect(mockFetch).toHaveBeenCalledWith("general");
+  });
+
+  it("shares one fetch between sections reading the same block", async () => {
+    const { result } = renderHook(
+      () => ({
+        a: useAdminSettings({ sectionName: "aiEngine" }),
+        b: useAdminSettings({ sectionName: "aiEngine" }),
+        c: useAdminSettings({ sectionName: "aiEngine" }),
+      }),
+      { wrapper: makeWrapper() },
+    );
+
+    await waitFor(() => expect(result.current.a.loading).toBe(false));
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("serves a reopened tab from cache within the stale window", async () => {
+    const client = new QueryClient({
+      defaultOptions: { queries: { retry: false, staleTime: 30_000 } },
+    });
+    const shared = ({ children }: { children: ReactNode }) => (
+      <QueryClientProvider client={client}>{children}</QueryClientProvider>
+    );
+
+    for (let i = 0; i < 4; i++) {
+      const tab = renderHook(
+        () => useAdminSettings({ sectionName: "aiEngine" }),
+        { wrapper: shared },
+      );
+      await waitFor(() => expect(tab.result.current.loading).toBe(false));
+      tab.unmount();
+    }
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps sections with different blocks apart", async () => {
+    const { result } = renderHook(
+      () => ({
+        a: useAdminSettings({ sectionName: "general" }),
+        b: useAdminSettings({ sectionName: "security" }),
+      }),
+      { wrapper: makeWrapper() },
+    );
+
+    await waitFor(() => expect(result.current.a.loading).toBe(false));
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    expect(mockFetch).toHaveBeenCalledWith("general");
+    expect(mockFetch).toHaveBeenCalledWith("security");
+  });
+
+  it("does not fetch while disabled, and reports itself unloaded", async () => {
+    const { result } = renderHook(
+      () => useAdminSettings({ sectionName: "general", enabled: false }),
+      {
+        wrapper: makeWrapper(),
+      },
+    );
+
+    expect(mockFetch).not.toHaveBeenCalled();
+    // Sections gate their render on this; false would show an empty form.
+    expect(result.current.loading).toBe(true);
+  });
+
+  it("fetches when the gate opens", async () => {
+    const { result, rerender } = renderHook(
+      ({ on }: { on: boolean }) =>
+        useAdminSettings({ sectionName: "general", enabled: on }),
+      { wrapper: makeWrapper(), initialProps: { on: false } },
+    );
+
+    expect(mockFetch).not.toHaveBeenCalled();
+    rerender({ on: true });
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("sends only changed fields", async () => {
+    mockFetch.mockResolvedValue({ appName: "Stirling", theme: "dark" });
+    const { result } = renderHook(
+      () =>
+        useAdminSettings<{ appName: string; theme: string }>({
+          sectionName: "general",
+        }),
+      { wrapper: makeWrapper() },
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    act(() => {
+      result.current.setSettings({ appName: "Renamed", theme: "dark" });
+    });
+    await act(async () => {
+      await result.current.saveSettings();
+    });
+
+    expect(mockPutSection).toHaveBeenCalledWith("general", {
+      appName: "Renamed",
+    });
+  });
+
+  it("skips the request when nothing changed", async () => {
+    const { result } = renderHook(
+      () => useAdminSettings({ sectionName: "general" }),
+      { wrapper: makeWrapper() },
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    await act(async () => {
+      await result.current.saveSettings();
+    });
+
+    expect(mockPutSection).not.toHaveBeenCalled();
+  });
+
+  it("refetches after a save so the _pending block is current", async () => {
+    mockFetch.mockResolvedValue({ appName: "Stirling" });
+    const { result } = renderHook(
+      () => useAdminSettings<{ appName: string }>({ sectionName: "general" }),
+      {
+        wrapper: makeWrapper(),
+      },
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+
+    mockFetch.mockResolvedValue({
+      appName: "Stirling",
+      _pending: { appName: "Renamed" },
+    });
+    act(() => {
+      result.current.setSettings({ appName: "Renamed" });
+    });
+    await act(async () => {
+      await result.current.saveSettings();
+    });
+
+    await waitFor(() => expect(mockFetch).toHaveBeenCalledTimes(2));
+    await waitFor(() => expect(result.current.hasPendingChanges()).toBe(true));
+  });
+
+  it("surfaces pending values in the draft and flags the field", async () => {
+    mockFetch.mockResolvedValue({
+      appName: "Stirling",
+      _pending: { appName: "Queued" },
+    });
+    const { result } = renderHook(
+      () => useAdminSettings<{ appName: string }>({ sectionName: "general" }),
+      {
+        wrapper: makeWrapper(),
+      },
+    );
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    // The draft shows the queued value, not the active one.
+    expect(result.current.settings.appName).toBe("Queued");
+    expect(result.current.isFieldPending("appName")).toBe(true);
+  });
+
+  it("resets the draft when a fetch delivers new values", async () => {
+    const client = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    const { result } = renderHook(
+      () => useAdminSettings<{ appName: string }>({ sectionName: "general" }),
+      {
+        wrapper: ({ children }: { children: ReactNode }) => (
+          <QueryClientProvider client={client}>{children}</QueryClientProvider>
+        ),
+      },
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    act(() => {
+      result.current.setSettings({ appName: "Half-typed" });
+    });
+    expect(result.current.settings.appName).toBe("Half-typed");
+
+    mockFetch.mockResolvedValue({ appName: "From server" });
+    await act(async () => {
+      await client.invalidateQueries({ queryKey: qk.adminSection("general") });
+    });
+
+    // A fetch is authoritative over the draft.
+    await waitFor(() =>
+      expect(result.current.settings.appName).toBe("From server"),
+    );
+  });
+
+  it("does not clobber an in-progress edit on re-render", async () => {
+    const { result, rerender } = renderHook(
+      () => useAdminSettings<{ appName: string }>({ sectionName: "general" }),
+      {
+        wrapper: makeWrapper(),
+      },
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    act(() => {
+      result.current.setSettings({ appName: "Half-typed" });
+    });
+    rerender();
+    rerender();
+
+    expect(result.current.settings.appName).toBe("Half-typed");
+  });
+
+  it("routes transformer output to both endpoints", async () => {
+    mockFetch.mockResolvedValue({ a: 1, b: 2 });
+    const { result } = renderHook(
+      () =>
+        useAdminSettings<{ a: number; b: number }>({
+          sectionName: "general",
+          saveTransformer: (s) => ({
+            sectionData: { a: s.a },
+            deltaSettings: { "some.flat.path": s.b },
+          }),
+        }),
+      { wrapper: makeWrapper() },
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    act(() => {
+      result.current.setSettings({ a: 9, b: 8 });
+    });
+    await act(async () => {
+      await result.current.saveSettings();
+    });
+
+    expect(mockPutSection).toHaveBeenCalledWith("general", { a: 9 });
+    expect(mockPutSettings).toHaveBeenCalledWith({ "some.flat.path": 8 });
+  });
+
+  it("reports saving while the save is in flight", async () => {
+    const { result } = renderHook(
+      () => useAdminSettings<{ appName: string }>({ sectionName: "general" }),
+      {
+        wrapper: makeWrapper(),
+      },
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    let release: () => void = () => {};
+    mockPutSection.mockReturnValueOnce(
+      new Promise<void>((resolve) => {
+        release = resolve;
+      }),
+    );
+
+    act(() => {
+      result.current.setSettings({ appName: "Renamed" });
+    });
+    let done: Promise<void>;
+    act(() => {
+      done = result.current.saveSettings();
+    });
+    await waitFor(() => expect(result.current.saving).toBe(true));
+
+    await act(async () => {
+      release();
+      await done;
+    });
+    await waitFor(() => expect(result.current.saving).toBe(false));
+  });
+});