feat(web): implement resolveTheme waterfall with CID integrity check (ATB-53)

apps/web/src/lib/__tests__/theme-resolution.test.ts

···
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import {
   detectColorScheme,
   parseRkeyFromUri,
   FALLBACK_THEME,
+  resolveTheme,
 } from "../theme-resolution.js";
+import { logger } from "../logger.js";
+
+vi.mock("../logger.js", () => ({
+  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), fatal: vi.fn() },
+}));
 
 describe("detectColorScheme", () => {
   it("returns 'light' by default when no cookie or hint", () => {
···
     expect(FALLBACK_THEME.cssOverrides).toBeNull();
   });
 });
+
+describe("resolveTheme", () => {
+  const mockFetch = vi.fn();
+  const APPVIEW = "http://localhost:3001";
+
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    vi.mocked(logger.warn).mockClear();
+    vi.mocked(logger.error).mockClear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    mockFetch.mockReset();
+  });
+
+  function policyResponse(overrides: object = {}) {
+    return {
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          defaultLightThemeUri:
+            "at://did:plc:forum/space.atbb.forum.theme/3lbllight",
+          defaultDarkThemeUri:
+            "at://did:plc:forum/space.atbb.forum.theme/3lbldark",
+          allowUserChoice: true,
+          availableThemes: [
+            { uri: "at://did:plc:forum/space.atbb.forum.theme/3lbllight", cid: "bafylight" },
+            { uri: "at://did:plc:forum/space.atbb.forum.theme/3lbldark", cid: "bafydark" },
+          ],
+          ...overrides,
+        }),
+    };
+  }
+
+  function themeResponse(colorScheme: "light" | "dark", cid: string) {
+    return {
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          cid,
+          tokens: { "color-bg": colorScheme === "light" ? "#fff" : "#111" },
+          cssOverrides: null,
+          fontUrls: null,
+          colorScheme,
+        }),
+    };
+  }
+
+  it("returns FALLBACK_THEME with detected colorScheme when policy fetch fails (non-ok)", async () => {
+    mockFetch.mockResolvedValueOnce({ ok: false, status: 404 });
+    const result = await resolveTheme(APPVIEW, undefined, undefined);
+    expect(result.tokens).toEqual(FALLBACK_THEME.tokens);
+    expect(result.colorScheme).toBe("light");
+  });
+
+  it("returns FALLBACK_THEME with dark colorScheme when policy fails and dark cookie set", async () => {
+    mockFetch.mockResolvedValueOnce({ ok: false, status: 500 });
+    const result = await resolveTheme(APPVIEW, "atbb-color-scheme=dark", undefined);
+    expect(result.tokens).toEqual(FALLBACK_THEME.tokens);
+    expect(result.colorScheme).toBe("dark");
+  });
+
+  it("returns FALLBACK_THEME when policy has no defaultLightThemeUri", async () => {
+    mockFetch.mockResolvedValueOnce(policyResponse({ defaultLightThemeUri: null }));
+    const result = await resolveTheme(APPVIEW, undefined, undefined);
+    expect(result.tokens).toEqual(FALLBACK_THEME.tokens);
+  });
+
+  it("returns FALLBACK_THEME when theme fetch fails", async () => {
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce({ ok: false, status: 404 });
+    const result = await resolveTheme(APPVIEW, undefined, undefined);
+    expect(result.tokens).toEqual(FALLBACK_THEME.tokens);
+  });
+
+  it("returns FALLBACK_THEME and logs warning on CID mismatch", async () => {
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("light", "WRONG_CID"));
+    const result = await resolveTheme(APPVIEW, undefined, undefined);
+    expect(result.tokens).toEqual(FALLBACK_THEME.tokens);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("CID mismatch"),
+      expect.objectContaining({ expectedCid: "bafylight", actualCid: "WRONG_CID" })
+    );
+  });
+
+  it("resolves the light theme on happy path (no cookie)", async () => {
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("light", "bafylight"));
+    const result = await resolveTheme(APPVIEW, undefined, undefined);
+    expect(result.tokens["color-bg"]).toBe("#fff");
+    expect(result.colorScheme).toBe("light");
+    expect(result.cssOverrides).toBeNull();
+    expect(result.fontUrls).toBeNull();
+  });
+
+  it("resolves the dark theme when atbb-color-scheme=dark cookie is set", async () => {
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("dark", "bafydark"));
+    const result = await resolveTheme(APPVIEW, "atbb-color-scheme=dark", undefined);
+    expect(result.tokens["color-bg"]).toBe("#111");
+    expect(result.colorScheme).toBe("dark");
+    expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining("3lbldark"));
+  });
+
+  it("resolves dark theme from Sec-CH-Prefers-Color-Scheme hint when no cookie", async () => {
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("dark", "bafydark"));
+    const result = await resolveTheme(APPVIEW, undefined, "dark");
+    expect(result.colorScheme).toBe("dark");
+  });
+
+  it("returns FALLBACK_THEME and logs error on network exception", async () => {
+    mockFetch.mockRejectedValueOnce(new Error("fetch failed"));
+    const result = await resolveTheme(APPVIEW, undefined, undefined);
+    expect(result.tokens).toEqual(FALLBACK_THEME.tokens);
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining("Theme resolution failed"),
+      expect.objectContaining({ operation: "resolveTheme" })
+    );
+  });
+
+  it("passes cssOverrides and fontUrls through from theme response", async () => {
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            cid: "bafylight",
+            tokens: { "color-bg": "#fff" },
+            cssOverrides: ".btn { font-weight: 700; }",
+            fontUrls: ["https://fonts.example.com/font.css"],
+            colorScheme: "light",
+          }),
+      });
+    const result = await resolveTheme(APPVIEW, undefined, undefined);
+    expect(result.cssOverrides).toBe(".btn { font-weight: 700; }");
+    expect(result.fontUrls).toEqual(["https://fonts.example.com/font.css"]);
+  });
+});

apps/web/src/lib/theme-resolution.ts

···
 import neobrutalLight from "../styles/presets/neobrutal-light.json" with { type: "json" };
+import { logger } from "./logger.js";
 
 export type ResolvedTheme = {
   tokens: Record<string, string>;
···
   if (parts.length < 5) return null;
   return parts[4] ?? null;
 }
+
+interface ThemePolicyResponse {
+  defaultLightThemeUri: string | null;
+  defaultDarkThemeUri: string | null;
+  allowUserChoice: boolean;
+  availableThemes: Array<{ uri: string; cid: string }>;
+}
+
+interface ThemeResponse {
+  cid: string;
+  tokens: Record<string, unknown>;
+  cssOverrides: string | null;
+  fontUrls: string[] | null;
+}
+
+/**
+ * Resolves which theme to render for a request using the waterfall:
+ *   1. User preference   — not yet implemented (TODO: Theme Phase 4)
+ *   2. Color scheme default — atbb-color-scheme cookie or Sec-CH hint
+ *   3. Forum default      — fetched from GET /api/theme-policy
+ *   4. Hardcoded fallback — FALLBACK_THEME (neobrutal-light)
+ *
+ * Never throws — always returns a usable theme.
+ */
+export async function resolveTheme(
+  appviewUrl: string,
+  cookieHeader: string | undefined,
+  colorSchemeHint: string | undefined
+): Promise<ResolvedTheme> {
+  const colorScheme = detectColorScheme(cookieHeader, colorSchemeHint);
+
+  // Step 1: User preference
+  // TODO: implement when space.atbb.membership.preferredTheme is added (Theme Phase 4)
+
+  // Steps 2-3: Forum default via theme policy
+  try {
+    const policyRes = await fetch(`${appviewUrl}/api/theme-policy`);
+    if (!policyRes.ok) {
+      return { ...FALLBACK_THEME, colorScheme };
+    }
+
+    const policy = (await policyRes.json()) as ThemePolicyResponse;
+
+    const defaultUri =
+      colorScheme === "dark"
+        ? policy.defaultDarkThemeUri
+        : policy.defaultLightThemeUri;
+
+    if (!defaultUri) {
+      return { ...FALLBACK_THEME, colorScheme };
+    }
+
+    const rkey = parseRkeyFromUri(defaultUri);
+    if (!rkey) {
+      return { ...FALLBACK_THEME, colorScheme };
+    }
+
+    const expectedCid =
+      policy.availableThemes.find((t) => t.uri === defaultUri)?.cid ?? null;
+
+    const themeRes = await fetch(`${appviewUrl}/api/themes/${rkey}`);
+    if (!themeRes.ok) {
+      return { ...FALLBACK_THEME, colorScheme };
+    }
+
+    const theme = (await themeRes.json()) as ThemeResponse;
+
+    if (expectedCid && theme.cid !== expectedCid) {
+      logger.warn("Theme CID mismatch — using hardcoded fallback", {
+        operation: "resolveTheme",
+        expectedCid,
+        actualCid: theme.cid,
+        themeUri: defaultUri,
+      });
+      return { ...FALLBACK_THEME, colorScheme };
+    }
+
+    return {
+      tokens: theme.tokens as Record<string, string>,
+      cssOverrides: theme.cssOverrides ?? null,
+      fontUrls: theme.fontUrls ?? null,
+      colorScheme,
+    };
+  } catch (error) {
+    // Intentionally don't re-throw: a broken theme system should serve the
+    // fallback and log the error, rather than crash every page request.
+    logger.error("Theme resolution failed — using hardcoded fallback", {
+      operation: "resolveTheme",
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return { ...FALLBACK_THEME, colorScheme };
+  }
+}