fix: address PR review feedback on user theme preferences

Security:
- Add CSS injection guard to ThemeSwatchPreview (rejects values containing
; < }) matching the pattern already used in admin-themes.tsx

Error handling:
- Split network/JSON try blocks in preview, GET themes list, POST policy
fetch — SyntaxError from res.json() is a data error, not a code bug,
and must not be re-thrown via isProgrammingError
- Promote logger.warn → logger.error for themes list fetch failure
- Add logger.warn to preview endpoint catch block (was silently swallowing
AppView failures)

User-facing:
- Map ?error= codes to friendly messages; drop unknown codes (phishing
vector for crafted URLs showing raw internal codes like "invalid-theme")

Tests:
- Add getSetCookie absence assertions to allowUserChoice:false and
invalid-theme POST rejection tests
- Update ?error=invalid-theme GET test to verify friendly message in
settings-banner--error element
- Add tests for themes list non-ok response and network throw paths
- Add test for unknown ?error= code producing no banner

Docs:
- Align theme-resolution.ts internal section comments to use descriptive
headings instead of "Step N" (conflicted with JSDoc 5-step waterfall)
- CLAUDE.md: clarify settings routes bypass ThemeCache intentionally

CLAUDE.md

···
 - User preference cookies are always validated against the current `policy.availableThemes` on read. Stale or removed theme URIs silently fall through to the forum default.
 - `resolveTheme()` never throws -- it always returns a usable `ResolvedTheme`.
 - Settings routes (`/settings`, `/settings/appearance`) require authentication. The preview endpoint (`/settings/preview`) is unauthenticated — it returns only public theme data (color swatches). The preference form is only rendered when `policy.allowUserChoice` is true.
+- **Settings routes bypass ThemeCache intentionally.** `GET /settings` and `POST /settings/appearance` call `fetch()` directly (not via `resolveTheme()`), so they always get fresh policy data. This is by design: preference saves must validate against the current policy, not a potentially stale cached copy.
 
 ## Middleware Patterns
 

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

···
 ): Promise<ResolvedTheme> {
   const colorScheme = detectColorScheme(cookieHeader, colorSchemeHint);
 
-  // ── Step 1: Get theme policy (from cache or AppView) ───────────────────────
+  // ── Policy: fetch or restore from cache ────────────────────────────────────
   let policy: CachedPolicy | null = cache?.getPolicy() ?? null;
 
   if (!policy) {
···
     }
   }
 
-  // ── Step 2: User preference or forum default URI ───────────────────────────
+  // ── URI resolution: user preference → forum default ───────────────────────
   const userPreferenceUri = resolveUserThemePreference(
     cookieHeader,
     colorScheme,
···
   // cid may be absent for live refs (e.g. canonical atbb.space presets) — that is expected
   const expectedCid = matchingTheme?.cid ?? null;
 
-  // ── Step 3: Get theme (from cache or AppView) ──────────────────────────────
+  // ── Theme data: restore from cache if available ────────────────────────────
   const cachedTheme: CachedTheme | null = cache?.getTheme(defaultUri, colorScheme) ?? null;
 
   if (cachedTheme !== null) {
···
     }
   }
 
-  // ── Step 4: Fetch theme from AppView ──────────────────────────────────────
+  // ── Theme data: fetch from AppView ────────────────────────────────────────
   let themeRes: Response;
   try {
     themeRes = await fetch(`${appviewUrl}/api/themes/${rkey}`);
···
     return fallbackForScheme(colorScheme);
   }
 
-  // ── Step 5: Parse theme JSON ───────────────────────────────────────────────
+  // ── Theme data: parse response JSON ───────────────────────────────────────
   let theme: CachedTheme;
   try {
     theme = (await themeRes.json()) as CachedTheme;
···
     return fallbackForScheme(colorScheme);
   }
 
-  // ── Step 6: CID integrity check ────────────────────────────────────────────
+  // ── CID integrity check ────────────────────────────────────────────────────
   if (expectedCid && theme.cid !== expectedCid) {
     logger.warn("Theme CID mismatch — using hardcoded fallback", {
       operation: "resolveTheme",

apps/web/src/routes/__tests__/settings.test.tsx

···
     expect(html).not.toContain("<select");
   });
 
+  // ── GET /settings — Themes list fetch failure ────────────────────────
+
+  it("GET /settings renders form with empty selects when themes list returns non-ok", async () => {
+    // Auth + policy succeed; themes fetch returns 500
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ authenticated: true, did: "did:plc:user", handle: "alice.bsky.social" })
+    );
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({
+        allowUserChoice: true,
+        defaultLightThemeUri: null,
+        defaultDarkThemeUri: null,
+        availableThemes: [],
+      })
+    );
+    mockFetch.mockResolvedValueOnce(mockResponse({}, false, 500)); // themes fetch fails
+    const routes = await loadSettingsRoutes();
+    const res = await routes.request("/settings", {
+      headers: { cookie: "atbb_session=token" },
+    });
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    // Form renders (no crash), but no theme options
+    expect(html).toContain("id=\"lightThemeUri\"");
+    expect(html).not.toContain("<option");
+  });
+
+  it("GET /settings renders form with empty selects when themes list fetch throws", async () => {
+    // Auth + policy succeed; themes fetch throws network error
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ authenticated: true, did: "did:plc:user", handle: "alice.bsky.social" })
+    );
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({
+        allowUserChoice: true,
+        defaultLightThemeUri: null,
+        defaultDarkThemeUri: null,
+        availableThemes: [],
+      })
+    );
+    mockFetch.mockRejectedValueOnce(new Error("Network error")); // themes fetch throws
+    const routes = await loadSettingsRoutes();
+    const res = await routes.request("/settings", {
+      headers: { cookie: "atbb_session=token" },
+    });
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    // Form renders (no crash), but no theme options
+    expect(html).toContain("id=\"lightThemeUri\"");
+    expect(html).not.toContain("<option");
+  });
+
   // ── GET /settings — allowUserChoice: false ───────────────────────────
 
   it("GET /settings shows informational banner when allowUserChoice: false", async () => {
···
     );
   });
 
-  it("GET /settings with ?error=invalid-theme shows error banner", async () => {
+  it("GET /settings with ?error=invalid-theme shows friendly message in error banner", async () => {
     setupAuthenticatedSessionGet();
     const routes = await loadSettingsRoutes();
     const res = await routes.request("/settings?error=invalid-theme", {
···
     });
     expect(res.status).toBe(200);
     const html = await res.text();
-    expect(html).toContain("invalid-theme");
+    expect(html).toContain("settings-banner--error");
+    expect(html).toContain("no longer available");
+  });
+
+  it("GET /settings with unknown ?error= code shows no error banner", async () => {
+    setupAuthenticatedSessionGet();
+    const routes = await loadSettingsRoutes();
+    const res = await routes.request("/settings?error=some-unknown-code", {
+      headers: { cookie: "atbb_session=token" },
+    });
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).not.toContain("settings-banner--error");
+    expect(html).not.toContain("some-unknown-code");
   });
 
   // ── POST /settings/appearance — Unauthenticated ──────────────────────
···
     });
     expect(res.status).toBe(302);
     expect(res.headers.get("location")).toBe("/settings?error=invalid-theme");
+    const cookies = res.headers.getSetCookie?.() ?? [];
+    expect(cookies.length).toBe(0);
   });
 
   it("POST /settings/appearance rejects invalid dark theme URI with ?error=invalid-theme", async () => {
···
     });
     expect(res.status).toBe(302);
     expect(res.headers.get("location")).toBe("/settings?error=invalid-theme");
+    const cookies = res.headers.getSetCookie?.() ?? [];
+    expect(cookies.length).toBe(0);
   });
 
   // ── POST /settings/appearance — Policy fetch failure ──────────────────
···
     });
     expect(res.status).toBe(302);
     expect(res.headers.get("location")).toBe("/settings?error=not-allowed");
+    // Verify no cookies are set (reject before reaching cookie-write code)
+    const cookies = res.headers.getSetCookie?.() ?? [];
+    expect(cookies.length).toBe(0);
   });
 
   // ── POST /settings/appearance — Happy path ──────────────────────────

apps/web/src/routes/settings.tsx

···
 
     const saved = c.req.query("saved") === "1";
     const rawError = c.req.query("error");
-    // decodeURIComponent throws URIError on malformed percent-encoding (e.g. %ZZ)
-    const errorMessage = rawError
-      ? (() => {
-          try {
-            return decodeURIComponent(rawError);
-          } catch {
-            return rawError;
-          }
-        })()
-      : undefined;
+    const ERROR_MESSAGES: Record<string, string> = {
+      invalid: "Please fill in all required fields.",
+      "invalid-theme": "The selected theme is no longer available. Please choose another.",
+      "not-allowed": "Theme selection is managed by the forum administrator.",
+      unavailable: "Theme settings are temporarily unavailable. Please try again later.",
+    };
+    const errorMessage = rawError ? (ERROR_MESSAGES[rawError] ?? undefined) : undefined;
 
     // Fetch theme policy
     let policy: Policy | null = null;
···
 
     // Fetch available themes list (already filtered by policy server-side in AppView)
     let allThemes: Array<ThemeSummary> = [];
+    let themesRes: Response | undefined;
     try {
-      const themesRes = await fetch(`${appviewUrl}/api/themes`);
-      if (themesRes.ok) {
-        const data = (await themesRes.json()) as { themes: Array<ThemeSummary> };
-        allThemes = data.themes ?? [];
-      }
+      themesRes = await fetch(`${appviewUrl}/api/themes`);
     } catch (err) {
       if (isProgrammingError(err)) throw err;
-      logger.warn("Failed to fetch themes list for settings page", {
+      logger.error("Failed to fetch themes list for settings page", {
         operation: "GET /settings",
         error: err instanceof Error ? err.message : String(err),
       });
     }
+    if (themesRes?.ok) {
+      try {
+        const data = (await themesRes.json()) as { themes: Array<ThemeSummary> };
+        allThemes = data.themes ?? [];
+      } catch {
+        logger.error("Themes list response contained invalid JSON", {
+          operation: "GET /settings",
+        });
+      }
+    }
 
     const lightThemes = allThemes.filter((t) => t.colorScheme === "light");
     const darkThemes = allThemes.filter((t) => t.colorScheme === "dark");
 
-    // Pre-select current preference cookie (Phase 1), falling back to forum default
+    // Pre-select current preference cookie, falling back to forum default
     const currentLightUri =
       resolveUserThemePreference(cookieHeader, "light", allThemes, policy.allowUserChoice) ??
       policy.defaultLightThemeUri;
···
     }
 
     // Fetch FRESH policy (bypass cache) so recently-removed themes can't be saved
-    let policy: { availableThemes: Array<{ uri: string }>; allowUserChoice: boolean } | null =
-      null;
+    type PostPolicy = { availableThemes: Array<{ uri: string }>; allowUserChoice: boolean };
+    let policy: PostPolicy | null = null;
+    let postPolicyRes: Response | undefined;
     try {
-      const policyRes = await fetch(`${appviewUrl}/api/theme-policy`);
-      if (policyRes.ok) {
-        policy = (await policyRes.json()) as { availableThemes: Array<{ uri: string }>; allowUserChoice: boolean };
-      }
+      postPolicyRes = await fetch(`${appviewUrl}/api/theme-policy`);
     } catch (err) {
       if (isProgrammingError(err)) throw err;
       logger.error("Failed to fetch theme policy during preference save", {
         operation: "POST /settings/appearance",
         error: err instanceof Error ? err.message : String(err),
       });
+    }
+    if (postPolicyRes?.ok) {
+      try {
+        policy = (await postPolicyRes.json()) as PostPolicy;
+      } catch {
+        logger.error("Theme policy response contained invalid JSON during preference save", {
+          operation: "POST /settings/appearance",
+        });
+      }
     }
 
     if (!policy) {
···
         <div class="theme-preview__swatches">
           {swatchTokens.map((token) => {
             const color = tokens[token];
-            if (!color) return null;
+            // Reject values that could escape the style attribute via CSS injection
+            if (!color || color.includes(";") || color.includes("<") || color.includes("}")) {
+              return null;
+            }
             return (
               <span
                 class="theme-preview__swatch"
···
     const rkey = parseRkeyFromUri(themeUri);
     if (!rkey || !/^[a-z0-9-]+$/i.test(rkey)) return c.html(emptyFragment);
 
+    let previewRes: Response;
     try {
-      const res = await fetch(`${appviewUrl}/api/themes/${rkey}`);
-      if (!res.ok) return c.html(emptyFragment);
-      const theme = (await res.json()) as {
+      previewRes = await fetch(`${appviewUrl}/api/themes/${rkey}`);
+    } catch (err) {
+      if (isProgrammingError(err)) throw err;
+      logger.warn("Failed to fetch theme for preview", {
+        operation: "GET /settings/preview",
+        rkey,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return c.html(emptyFragment);
+    }
+    if (!previewRes.ok) return c.html(emptyFragment);
+
+    try {
+      const theme = (await previewRes.json()) as {
         name: string;
         tokens: Record<string, string>;
       };
       return c.html(
         <ThemeSwatchPreview name={theme.name ?? ""} tokens={theme.tokens ?? {}} />
       );
-    } catch (err) {
-      if (isProgrammingError(err)) throw err;
+    } catch {
+      logger.warn("Theme preview response contained invalid JSON", {
+        operation: "GET /settings/preview",
+        rkey,
+      });
       return c.html(emptyFragment);
     }
   });