feat(web+appview): theme caching layer (ATB-56) (#96)

* feat(web+appview): theme caching layer (ATB-56)

Add in-memory TTL cache for resolved theme data on the web server to
avoid redundant AppView API calls on every page request.

- New ThemeCache class (theme-cache.ts): TTL entries for policy (single)
and themes (keyed by uri:colorScheme to keep light/dark isolated)
- resolveTheme now accepts an optional ThemeCache; checks cache before
each fetch, populates after successful CID validation; stale CID on
cache hit falls through to a fresh fetch rather than serving stale data
- createThemeMiddleware creates one ThemeCache at startup (shared across
all requests); accepts configurable cacheTtlMs (default 5 min)
- THEME_CACHE_TTL_MS env var exposed via WebConfig.themeCacheTtlMs
- AppView theme endpoints now set Cache-Control: public, max-age=300;
GET /api/themes/:rkey also sets ETag from the theme record CID

* fix(web+appview): address code review feedback on theme caching (ATB-56)

Critical: Cache-Control on GET /themes was set before DB queries, causing
CDNs to cache error responses for 5 minutes. Moved to immediately before
each success return, matching the existing pattern in GET /:rkey.

Important fixes:
- Add THEME_CACHE_TTL_MS to turbo.json env array (Turbo blocks env vars
not declared here, causing tests to receive NaN TTL via turbo)
- Guard parseInt result with Number.isNaN fallback in config (invalid
env value would produce an immortal cache with no operator feedback)
- Add ThemeCache.deleteTheme(): evict stale entry when CID mismatch is
detected so failed re-fetches don't loop per-request indefinitely
- CachedTheme.tokens: Record<string,string> (was unknown) — eliminates
downstream casts and prevents numeric token values entering the cache
- Remove unused re-export of cache types from theme-resolution.ts

Suggestions applied:
- JSDoc on CachedPolicy.availableThemes[].cid explaining live vs pinned refs
- getPolicy()/getTheme() now return Readonly<T> to prevent external mutation
- Comment on ThemeCache construction in middleware explaining why it must
be outside the request handler

Test additions:
- 503 from GET /themes must NOT include Cache-Control header (regression)
- stale CID + failed fresh fetch: eviction means next request retries cleanly
- cache repopulated after stale-CID recovery: third call makes no fetches
- deleteTheme() targeted eviction tests
- Fixed misleading comment in policy-cache-hit test

apps/appview/src/routes/__tests__/themes.test.ts

···
 
     const res = await app.request("/themes");
     expect(res.status).toBe(503);
+    // Error responses must NOT be cached by CDNs/proxies
+    expect(res.headers.get("Cache-Control")).toBeNull();
+  });
+
+  it("sets Cache-Control: public, max-age=300 on successful response", async () => {
+    const res = await app.request("/themes");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Cache-Control")).toBe("public, max-age=300");
   });
 });
 
···
     const res = await app.request("/themes/any-rkey");
     expect(res.status).toBe(503);
   });
+
+  it("sets Cache-Control: public, max-age=300 and ETag from CID on successful response", async () => {
+    await ctx.db.insert(themes).values({
+      did: ctx.config.forumDid,
+      rkey: "3lblcachetest",
+      cid: "bafycachetest123",
+      name: "Cache Test Theme",
+      colorScheme: "light",
+      tokens: { "color-bg": "#fff" },
+      createdAt: new Date(),
+      indexedAt: new Date(),
+    });
+
+    const res = await app.request("/themes/3lblcachetest");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Cache-Control")).toBe("public, max-age=300");
+    expect(res.headers.get("ETag")).toBe('"bafycachetest123"');
+  });
 });
 
 // ── GET /api/theme-policy ────────────────────────────────
···
 
     const res = await app.request("/theme-policy");
     expect(res.status).toBe(503);
+  });
+
+  it("sets Cache-Control: public, max-age=300 on successful response", async () => {
+    await ctx.db.insert(themePolicies).values({
+      did: ctx.config.forumDid,
+      rkey: "self",
+      cid: "bafypolicycache",
+      defaultLightThemeUri: `at://${ctx.config.forumDid}/space.atbb.forum.theme/3lbllight`,
+      defaultDarkThemeUri: `at://${ctx.config.forumDid}/space.atbb.forum.theme/3lbldark`,
+      allowUserChoice: true,
+      indexedAt: new Date(),
+    });
+
+    const res = await app.request("/theme-policy");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Cache-Control")).toBe("public, max-age=300");
   });
 });

apps/appview/src/routes/themes.ts

···
           .where(eq(themePolicies.did, ctx.config.forumDid));
 
         if (availableRows.length === 0) {
+          c.header("Cache-Control", "public, max-age=300");
           return c.json({ themes: [] });
         }
 
···
           .filter((rkey): rkey is string => !!rkey);
 
         if (rkeys.length === 0) {
+          c.header("Cache-Control", "public, max-age=300");
           return c.json({ themes: [] });
         }
 
···
           )
           .limit(100);
 
+        c.header("Cache-Control", "public, max-age=300");
         return c.json({ themes: themeList.map(serializeThemeSummary) });
       } catch (error) {
         return handleRouteError(c, error, "Failed to retrieve themes", {
···
           return c.json({ error: "Theme not found" }, 404);
         }
 
+        c.header("Cache-Control", "public, max-age=300");
+        c.header("ETag", `"${theme.cid}"`);
         return c.json(serializeThemeFull(theme));
       } catch (error) {
         return handleRouteError(c, error, "Failed to retrieve theme", {
···
         .from(themePolicyAvailableThemes)
         .where(eq(themePolicyAvailableThemes.policyId, policy.id));
 
+      c.header("Cache-Control", "public, max-age=300");
       return c.json({
         defaultLightThemeUri: policy.defaultLightThemeUri,
         defaultDarkThemeUri: policy.defaultDarkThemeUri,

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

···
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { ThemeCache, type CachedPolicy, type CachedTheme } from "../theme-cache.js";
+
+const TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+const MOCK_POLICY: CachedPolicy = {
+  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" },
+  ],
+};
+
+const MOCK_THEME: CachedTheme = {
+  cid: "bafylight",
+  tokens: { "color-bg": "#fff" },
+  cssOverrides: null,
+  fontUrls: null,
+};
+
+describe("ThemeCache — policy", () => {
+  let cache: ThemeCache;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    cache = new ThemeCache(TTL_MS);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns null when policy has not been set", () => {
+    expect(cache.getPolicy()).toBeNull();
+  });
+
+  it("returns policy immediately after setting", () => {
+    cache.setPolicy(MOCK_POLICY);
+    expect(cache.getPolicy()).toEqual(MOCK_POLICY);
+  });
+
+  it("returns null after TTL expires", () => {
+    cache.setPolicy(MOCK_POLICY);
+    vi.advanceTimersByTime(TTL_MS + 1);
+    expect(cache.getPolicy()).toBeNull();
+  });
+
+  it("returns policy just before TTL expires", () => {
+    cache.setPolicy(MOCK_POLICY);
+    vi.advanceTimersByTime(TTL_MS - 1);
+    expect(cache.getPolicy()).toEqual(MOCK_POLICY);
+  });
+
+  it("can be refreshed before expiry (re-set resets TTL)", () => {
+    cache.setPolicy(MOCK_POLICY);
+    vi.advanceTimersByTime(TTL_MS - 1);
+    cache.setPolicy({ ...MOCK_POLICY, allowUserChoice: false });
+    vi.advanceTimersByTime(TTL_MS - 1);
+    // Total elapsed: (TTL-1) + (TTL-1) = 2*TTL - 2ms, but the re-set happened at TTL-1
+    // so the new entry expires at (TTL-1) + TTL = 2*TTL - 1ms from start
+    const result = cache.getPolicy();
+    expect(result).not.toBeNull();
+    expect(result!.allowUserChoice).toBe(false);
+  });
+});
+
+describe("ThemeCache — themes", () => {
+  let cache: ThemeCache;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    cache = new ThemeCache(TTL_MS);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns null on cache miss", () => {
+    expect(
+      cache.getTheme("at://did:plc:forum/space.atbb.forum.theme/3lbllight", "light")
+    ).toBeNull();
+  });
+
+  it("returns theme immediately after setting", () => {
+    const uri = "at://did:plc:forum/space.atbb.forum.theme/3lbllight";
+    cache.setTheme(uri, "light", MOCK_THEME);
+    expect(cache.getTheme(uri, "light")).toEqual(MOCK_THEME);
+  });
+
+  it("returns null after TTL expires", () => {
+    const uri = "at://did:plc:forum/space.atbb.forum.theme/3lbllight";
+    cache.setTheme(uri, "light", MOCK_THEME);
+    vi.advanceTimersByTime(TTL_MS + 1);
+    expect(cache.getTheme(uri, "light")).toBeNull();
+  });
+
+  it("treats light and dark as separate cache entries", () => {
+    const uri = "at://did:plc:forum/space.atbb.forum.theme/shared";
+    const lightTheme: CachedTheme = { cid: "bafylight", tokens: { "color-bg": "#fff" }, cssOverrides: null, fontUrls: null };
+    const darkTheme: CachedTheme = { cid: "bafydark", tokens: { "color-bg": "#111" }, cssOverrides: null, fontUrls: null };
+
+    cache.setTheme(uri, "light", lightTheme);
+    cache.setTheme(uri, "dark", darkTheme);
+
+    expect(cache.getTheme(uri, "light")).toEqual(lightTheme);
+    expect(cache.getTheme(uri, "dark")).toEqual(darkTheme);
+  });
+
+  it("different URIs are stored independently", () => {
+    const lightUri = "at://did/col/light";
+    const darkUri = "at://did/col/dark";
+    const lightTheme: CachedTheme = { cid: "bafylight", tokens: { "color-bg": "#fff" }, cssOverrides: null, fontUrls: null };
+    const darkTheme: CachedTheme = { cid: "bafydark", tokens: { "color-bg": "#111" }, cssOverrides: null, fontUrls: null };
+
+    cache.setTheme(lightUri, "light", lightTheme);
+    cache.setTheme(darkUri, "dark", darkTheme);
+
+    expect(cache.getTheme(lightUri, "light")).toEqual(lightTheme);
+    expect(cache.getTheme(darkUri, "dark")).toEqual(darkTheme);
+    expect(cache.getTheme(lightUri, "dark")).toBeNull();
+    expect(cache.getTheme(darkUri, "light")).toBeNull();
+  });
+
+  it("deleteTheme removes a specific entry before TTL", () => {
+    const uri = "at://did/col/theme";
+    cache.setTheme(uri, "light", MOCK_THEME);
+    cache.deleteTheme(uri, "light");
+    expect(cache.getTheme(uri, "light")).toBeNull();
+  });
+
+  it("deleteTheme only removes the targeted uri:colorScheme entry", () => {
+    const uri = "at://did/col/theme";
+    const darkTheme: CachedTheme = { cid: "bafydark", tokens: { "color-bg": "#111" }, cssOverrides: null, fontUrls: null };
+    cache.setTheme(uri, "light", MOCK_THEME);
+    cache.setTheme(uri, "dark", darkTheme);
+    cache.deleteTheme(uri, "light");
+    expect(cache.getTheme(uri, "light")).toBeNull();
+    expect(cache.getTheme(uri, "dark")).toEqual(darkTheme);
+  });
+
+  it("evicts stale entry from the map on expired access", () => {
+    const uri = "at://did/col/theme";
+    cache.setTheme(uri, "light", MOCK_THEME);
+    vi.advanceTimersByTime(TTL_MS + 1);
+    // Access after expiry
+    expect(cache.getTheme(uri, "light")).toBeNull();
+    // After eviction, setting a new entry works correctly
+    const newTheme = { ...MOCK_THEME, cid: "bafynew" };
+    cache.setTheme(uri, "light", newTheme);
+    expect(cache.getTheme(uri, "light")).toEqual(newTheme);
+  });
+});

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

···
   FALLBACK_THEME,
   resolveTheme,
 } from "../theme-resolution.js";
+import { ThemeCache } from "../theme-cache.js";
 import { logger } from "../logger.js";
 
 vi.mock("../logger.js", () => ({
···
     expect(mockFetch).toHaveBeenCalledTimes(1);
   });
 
+  it("no cache provided — behaves identically to pre-cache implementation", async () => {
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("light", "bafylight"));
+    const result = await resolveTheme(APPVIEW, undefined, undefined, undefined);
+    expect(result.tokens["color-bg"]).toBe("#fff");
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
   it("resolves theme from live ref (no CID in policy) without logging CID mismatch", async () => {
     // Live refs have no CID — canonical atbb.space presets ship this way.
     // The CID integrity check must be skipped when expectedCid is null.
···
     );
   });
 });
+
+describe("resolveTheme — cache integration", () => {
+  const mockFetch = vi.fn();
+  const APPVIEW = "http://localhost:3001";
+  const TTL_MS = 60_000;
+
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+  });
+
+  afterEach(() => {
+    mockFetch.mockReset();
+    vi.unstubAllGlobals();
+  });
+
+  function policyResponse() {
+    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" },
+          ],
+        }),
+    };
+  }
+
+  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,
+        }),
+    };
+  }
+
+  it("policy cache hit skips policy fetch on second call", async () => {
+    const cache = new ThemeCache(TTL_MS);
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("light", "bafylight"));
+
+    await resolveTheme(APPVIEW, undefined, undefined, cache);
+    await resolveTheme(APPVIEW, undefined, undefined, cache);
+
+    // Both policy and theme are cached after the first call — second call makes no fetches
+    expect(mockFetch).toHaveBeenCalledTimes(2); // policy (1) + theme (1), both from first call
+  });
+
+  it("theme cache hit skips theme fetch on second call", async () => {
+    const cache = new ThemeCache(TTL_MS);
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("light", "bafylight"));
+
+    await resolveTheme(APPVIEW, undefined, undefined, cache);
+    // Second call: policy is cached, theme is cached — zero fetches
+    mockFetch.mockClear();
+    await resolveTheme(APPVIEW, undefined, undefined, cache);
+
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("cache returns correct tokens on second call without fetch", async () => {
+    const cache = new ThemeCache(TTL_MS);
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("light", "bafylight"));
+
+    const first = await resolveTheme(APPVIEW, undefined, undefined, cache);
+    const second = await resolveTheme(APPVIEW, undefined, undefined, cache);
+
+    expect(second.tokens["color-bg"]).toBe("#fff");
+    expect(second.tokens).toEqual(first.tokens);
+  });
+
+  it("light and dark are cached independently — color scheme determines which is served", async () => {
+    const cache = new ThemeCache(TTL_MS);
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("light", "bafylight"))
+      // Dark request: policy is cached, but dark theme is not yet
+      .mockResolvedValueOnce(themeResponse("dark", "bafydark"));
+
+    const light = await resolveTheme(APPVIEW, undefined, undefined, cache);
+    const dark = await resolveTheme(APPVIEW, "atbb-color-scheme=dark", undefined, cache);
+
+    expect(light.colorScheme).toBe("light");
+    expect(light.tokens["color-bg"]).toBe("#fff");
+    expect(dark.colorScheme).toBe("dark");
+    expect(dark.tokens["color-bg"]).toBe("#111");
+    // policy (1) + light theme (1) + dark theme (1) = 3 fetches
+    expect(mockFetch).toHaveBeenCalledTimes(3);
+  });
+
+  it("stale cache CID triggers eviction, fresh fetch, and logs warning", async () => {
+    const cache = new ThemeCache(TTL_MS);
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("light", "bafylight"));
+    await resolveTheme(APPVIEW, undefined, undefined, cache);
+
+    // Update cached policy to reflect a new CID (simulates admin updating the theme)
+    cache.setPolicy({
+      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: "bafynew" },
+        { uri: "at://did:plc:forum/space.atbb.forum.theme/3lbldark", cid: "bafydark" },
+      ],
+    });
+
+    mockFetch.mockResolvedValueOnce(themeResponse("light", "bafynew"));
+
+    const mockLogger = vi.mocked(logger);
+    const result = await resolveTheme(APPVIEW, undefined, undefined, cache);
+
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("stale CID"),
+      expect.objectContaining({ expectedCid: "bafynew", cachedCid: "bafylight" })
+    );
+    expect(result.tokens["color-bg"]).toBe("#fff");
+    expect(mockFetch).toHaveBeenCalledTimes(3); // initial policy+theme + 1 fresh theme
+  });
+
+  it("stale CID + failed fresh fetch falls back and evicts so next request retries", async () => {
+    const cache = new ThemeCache(TTL_MS);
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("light", "bafylight"));
+    await resolveTheme(APPVIEW, undefined, undefined, cache);
+
+    // Update policy to reflect a new CID
+    cache.setPolicy({
+      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: "bafynew" },
+        { uri: "at://did:plc:forum/space.atbb.forum.theme/3lbldark", cid: "bafydark" },
+      ],
+    });
+
+    // Fresh fetch fails (AppView outage)
+    mockFetch.mockResolvedValueOnce({ ok: false, status: 503 });
+    const fallbackResult = await resolveTheme(APPVIEW, undefined, undefined, cache);
+
+    // Falls back to FALLBACK_THEME — stale data is not served
+    expect(fallbackResult.tokens).toEqual(FALLBACK_THEME.tokens);
+
+    // On the NEXT request: stale entry was evicted, so a fresh fetch is attempted again
+    // (rather than re-detecting stale CID and looping forever)
+    mockFetch.mockResolvedValueOnce(themeResponse("light", "bafynew"));
+    const recoveredResult = await resolveTheme(APPVIEW, undefined, undefined, cache);
+
+    expect(recoveredResult.tokens["color-bg"]).toBe("#fff");
+    expect(mockFetch).toHaveBeenCalledTimes(4); // initial 2 + failed fetch + recovered fetch
+  });
+
+  it("cache repopulated after stale-CID fresh fetch — third call makes no fetches", async () => {
+    const cache = new ThemeCache(TTL_MS);
+    mockFetch
+      .mockResolvedValueOnce(policyResponse())
+      .mockResolvedValueOnce(themeResponse("light", "bafylight"));
+    await resolveTheme(APPVIEW, undefined, undefined, cache);
+
+    cache.setPolicy({
+      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: "bafynew" },
+        { uri: "at://did:plc:forum/space.atbb.forum.theme/3lbldark", cid: "bafydark" },
+      ],
+    });
+
+    mockFetch.mockResolvedValueOnce(themeResponse("light", "bafynew"));
+    await resolveTheme(APPVIEW, undefined, undefined, cache); // triggers fresh fetch, repopulates cache
+
+    mockFetch.mockClear();
+    await resolveTheme(APPVIEW, undefined, undefined, cache); // should be a full cache hit
+
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+});

apps/web/src/lib/config.ts

···
   port: number;
   appviewUrl: string;
   logLevel: LogLevel;
+  /** In-memory theme cache TTL in milliseconds. Defaults to 5 minutes. */
+  themeCacheTtlMs: number;
 }
 
 export function loadConfig(): WebConfig {
···
     port: parseInt(process.env.WEB_PORT ?? "3001", 10),
     appviewUrl: process.env.APPVIEW_URL ?? "http://localhost:3000",
     logLevel: (process.env.LOG_LEVEL as LogLevel) ?? "info",
+    themeCacheTtlMs: (() => {
+      const parsed = parseInt(process.env.THEME_CACHE_TTL_MS ?? "300000", 10);
+      return Number.isNaN(parsed) ? 300_000 : parsed;
+    })(),
   };
 }

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

···
+export interface CachedPolicy {
+  defaultLightThemeUri: string | null;
+  defaultDarkThemeUri: string | null;
+  allowUserChoice: boolean;
+  availableThemes: Array<{
+    uri: string;
+    /**
+     * Present for pinned refs (locked to an exact version).
+     * Absent for live refs (e.g. canonical atbb.space presets) — those
+     * resolve to the current record at the URI without CID verification.
+     */
+    cid?: string;
+  }>;
+}
+
+export interface CachedTheme {
+  cid: string;
+  /** All token values are CSS strings at the cache boundary. */
+  tokens: Record<string, string>;
+  cssOverrides: string | null;
+  fontUrls: string[] | null;
+}
+
+interface CacheEntry<T> {
+  data: T;
+  expiresAt: number;
+}
+
+/**
+ * In-memory TTL cache for resolved theme data on the web server.
+ *
+ * Themes change rarely. A single instance is created per server startup
+ * (inside createThemeMiddleware) and shared across all requests.
+ *
+ * Policy: single entry, keyed to the forum.
+ * Themes: map keyed by `${at-uri}:${colorScheme}` — colorScheme in the key
+ * ensures light and dark cached entries are never confused, even if the same
+ * AT-URI is used for both defaults.
+ */
+export class ThemeCache {
+  private policy: CacheEntry<CachedPolicy> | null = null;
+  private themes = new Map<string, CacheEntry<CachedTheme>>();
+
+  constructor(readonly ttlMs: number) {}
+
+  getPolicy(): Readonly<CachedPolicy> | null {
+    if (!this.policy || Date.now() > this.policy.expiresAt) {
+      this.policy = null;
+      return null;
+    }
+    return this.policy.data;
+  }
+
+  setPolicy(data: CachedPolicy): void {
+    this.policy = { data, expiresAt: Date.now() + this.ttlMs };
+  }
+
+  getTheme(uri: string, colorScheme: "light" | "dark"): Readonly<CachedTheme> | null {
+    const key = `${uri}:${colorScheme}`;
+    const entry = this.themes.get(key);
+    if (!entry || Date.now() > entry.expiresAt) {
+      this.themes.delete(key);
+      return null;
+    }
+    return entry.data;
+  }
+
+  setTheme(uri: string, colorScheme: "light" | "dark", data: CachedTheme): void {
+    const key = `${uri}:${colorScheme}`;
+    this.themes.set(key, { data, expiresAt: Date.now() + this.ttlMs });
+  }
+
+  /** Evict a stale theme entry so the next request fetches fresh data. */
+  deleteTheme(uri: string, colorScheme: "light" | "dark"): void {
+    this.themes.delete(`${uri}:${colorScheme}`);
+  }
+}

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

···
 import neobrutalLight from "../styles/presets/neobrutal-light.json" with { type: "json" };
 import { isProgrammingError } from "./errors.js";
 import { logger } from "./logger.js";
+import { ThemeCache, type CachedPolicy, type CachedTheme } from "./theme-cache.js";
 
 export type ResolvedTheme = {
   tokens: Record<string, string>;
···
   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
+ *   3. Forum default      — fetched from GET /api/theme-policy (cached in memory)
  *   4. Hardcoded fallback — FALLBACK_THEME (neobrutal-light)
  *
+ * Pass a ThemeCache instance to enable in-memory TTL caching of policy and
+ * theme data. The cache is checked before each network request and populated
+ * after a successful fetch + CID validation.
+ *
  * Never throws — always returns a usable theme.
  */
 export async function resolveTheme(
   appviewUrl: string,
   cookieHeader: string | undefined,
-  colorSchemeHint: string | undefined
+  colorSchemeHint: string | undefined,
+  cache?: ThemeCache
 ): Promise<ResolvedTheme> {
   const colorScheme = detectColorScheme(cookieHeader, colorSchemeHint);
   // TODO: user preference (Theme Phase 4)
 
-  // ── Step 1: Fetch theme policy ─────────────────────────────────────────────
-  let policyRes: Response;
-  try {
-    policyRes = await fetch(`${appviewUrl}/api/theme-policy`);
-    if (!policyRes.ok) {
-      logger.warn("Theme policy fetch returned non-ok status — using fallback", {
+  // ── Step 1: Get theme policy (from cache or AppView) ───────────────────────
+  let policy: CachedPolicy | null = cache?.getPolicy() ?? null;
+
+  if (!policy) {
+    let policyRes: Response;
+    try {
+      policyRes = await fetch(`${appviewUrl}/api/theme-policy`);
+      if (!policyRes.ok) {
+        logger.warn("Theme policy fetch returned non-ok status — using fallback", {
+          operation: "resolveTheme",
+          status: policyRes.status,
+          url: `${appviewUrl}/api/theme-policy`,
+        });
+        return { ...FALLBACK_THEME, colorScheme };
+      }
+    } catch (error) {
+      if (isProgrammingError(error)) throw error;
+      logger.error("Theme policy fetch failed — using fallback", {
         operation: "resolveTheme",
-        status: policyRes.status,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return { ...FALLBACK_THEME, colorScheme };
+    }
+
+    try {
+      // SyntaxError from Response.json() is a data error, not a code bug — do not re-throw
+      policy = (await policyRes.json()) as CachedPolicy;
+      cache?.setPolicy(policy);
+    } catch {
+      logger.error("Theme policy response contained invalid JSON — using fallback", {
+        operation: "resolveTheme",
         url: `${appviewUrl}/api/theme-policy`,
       });
       return { ...FALLBACK_THEME, colorScheme };
     }
-  } catch (error) {
-    if (isProgrammingError(error)) throw error;
-    logger.error("Theme policy fetch failed — using fallback", {
-      operation: "resolveTheme",
-      error: error instanceof Error ? error.message : String(error),
-    });
-    return { ...FALLBACK_THEME, colorScheme };
   }
 
-  // ── Step 2: Parse policy JSON ──────────────────────────────────────────────
-  let policy: ThemePolicyResponse;
-  try {
-    policy = (await policyRes.json()) as ThemePolicyResponse;
-  } catch {
-    // SyntaxError from Response.json() is a data error, not a code bug — do not re-throw
-    logger.error("Theme policy response contained invalid JSON — using fallback", {
-      operation: "resolveTheme",
-      url: `${appviewUrl}/api/theme-policy`,
-    });
-    return { ...FALLBACK_THEME, colorScheme };
-  }
-
-  // ── Step 3: Extract default theme URI and rkey ─────────────────────────────
+  // ── Step 2: Extract default theme URI and rkey ─────────────────────────────
   const defaultUri =
     colorScheme === "dark" ? policy.defaultDarkThemeUri : policy.defaultLightThemeUri;
   if (!defaultUri) return { ...FALLBACK_THEME, colorScheme };
···
   // cid may be absent for live refs (e.g. canonical atbb.space presets) — that is expected
   const expectedCid = matchingTheme?.cid ?? null;
 
-  // ── Step 4: Fetch theme ────────────────────────────────────────────────────
+  // ── Step 3: Get theme (from cache or AppView) ──────────────────────────────
+  const cachedTheme: CachedTheme | null = cache?.getTheme(defaultUri, colorScheme) ?? null;
+
+  if (cachedTheme !== null) {
+    // CID check on the cached entry — guards against stale cache when the policy
+    // refreshed (TTL expired) with a new CID while the theme entry is still live.
+    if (expectedCid && cachedTheme.cid !== expectedCid) {
+      logger.warn("Cached theme has stale CID — evicting and fetching fresh from AppView", {
+        operation: "resolveTheme",
+        expectedCid,
+        cachedCid: cachedTheme.cid,
+        themeUri: defaultUri,
+      });
+      // Evict the stale entry so that if the fresh fetch also fails,
+      // the next request doesn't re-enter this loop indefinitely.
+      cache?.deleteTheme(defaultUri, colorScheme);
+      // Fall through to fresh fetch below
+    } else {
+      // Cache hit — CID matches (or live ref with no expected CID)
+      return {
+        tokens: cachedTheme.tokens,
+        cssOverrides: cachedTheme.cssOverrides ?? null,
+        fontUrls: cachedTheme.fontUrls ?? null,
+        colorScheme,
+      };
+    }
+  }
+
+  // ── Step 4: Fetch theme from AppView ──────────────────────────────────────
   let themeRes: Response;
   try {
     themeRes = await fetch(`${appviewUrl}/api/themes/${rkey}`);
···
   }
 
   // ── Step 5: Parse theme JSON ───────────────────────────────────────────────
-  let theme: ThemeResponse;
+  let theme: CachedTheme;
   try {
-    theme = (await themeRes.json()) as ThemeResponse;
+    theme = (await themeRes.json()) as CachedTheme;
   } catch {
     logger.error("Theme response contained invalid JSON — using fallback", {
       operation: "resolveTheme",
···
     return { ...FALLBACK_THEME, colorScheme };
   }
 
+  // Populate cache only after successful validation
+  cache?.setTheme(defaultUri, colorScheme, theme);
+
   return {
-    tokens: theme.tokens as Record<string, string>,
+    tokens: theme.tokens,
     cssOverrides: theme.cssOverrides ?? null,
     fontUrls: theme.fontUrls ?? null,
     colorScheme,

apps/web/src/middleware/__tests__/theme.test.ts

···
     expect(mockResolveTheme).toHaveBeenCalledWith(
       expect.any(String),
       "atbb-color-scheme=dark; session=abc",
-      undefined
+      undefined,
+      expect.objectContaining({ ttlMs: expect.any(Number) })
     );
   });
 
···
     expect(mockResolveTheme).toHaveBeenCalledWith(
       expect.any(String),
       undefined,
-      "dark"
+      "dark",
+      expect.objectContaining({ ttlMs: expect.any(Number) })
     );
   });
 
···
     expect(mockResolveTheme).toHaveBeenCalledWith(
       "http://custom-appview.example.com",
       undefined,
-      undefined
+      undefined,
+      expect.objectContaining({ ttlMs: expect.any(Number) })
     );
   });
 
···
     expect(mockResolveTheme).toHaveBeenCalledWith(
       "http://appview.test",
       undefined,
-      undefined
+      undefined,
+      expect.objectContaining({ ttlMs: expect.any(Number) })
     );
   });
 
···
     expect(res.status).toBe(200);
     const body = await res.json() as { message: string };
     expect(body.message).toBe("handler ran");
+  });
+
+  it("passes a ThemeCache instance to resolveTheme (4th argument is not undefined)", async () => {
+    const app = new Hono<WebAppEnv>()
+      .use("*", createThemeMiddleware("http://appview.test", 60_000))
+      .get("/test", (c) => c.json({ ok: true }));
+
+    await app.request("http://localhost/test");
+
+    // The 4th argument (cache) should be a non-null object — not undefined
+    expect(mockResolveTheme).toHaveBeenCalledWith(
+      expect.any(String),
+      undefined,
+      undefined,
+      expect.objectContaining({ ttlMs: 60_000 })
+    );
+  });
+
+  it("uses default 5-minute TTL when cacheTtlMs is not provided", async () => {
+    const app = new Hono<WebAppEnv>()
+      .use("*", createThemeMiddleware("http://appview.test"))
+      .get("/test", (c) => c.json({ ok: true }));
+
+    await app.request("http://localhost/test");
+
+    expect(mockResolveTheme).toHaveBeenCalledWith(
+      expect.any(String),
+      undefined,
+      undefined,
+      expect.objectContaining({ ttlMs: 5 * 60 * 1000 })
+    );
   });
 
   it("catches unexpected throws from resolveTheme, logs the error, and sets FALLBACK_THEME", async () => {

apps/web/src/middleware/theme.ts

···
 import type { MiddlewareHandler } from "hono";
 import type { WebAppEnv } from "../lib/theme-resolution.js";
 import { resolveTheme, FALLBACK_THEME } from "../lib/theme-resolution.js";
+import { ThemeCache } from "../lib/theme-cache.js";
 import { logger } from "../lib/logger.js";
 
-export function createThemeMiddleware(appviewUrl: string): MiddlewareHandler<WebAppEnv> {
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+export function createThemeMiddleware(
+  appviewUrl: string,
+  cacheTtlMs: number = DEFAULT_CACHE_TTL_MS
+): MiddlewareHandler<WebAppEnv> {
+  // Intentionally outside the request handler: one shared instance per server
+  // startup. Moving this inside the handler would create a new cache per
+  // request, silently defeating the feature.
+  const cache = new ThemeCache(cacheTtlMs);
   return async (c, next) => {
     const cookieHeader = c.req.header("Cookie");
     const colorSchemeHint = c.req.header("Sec-CH-Prefers-Color-Scheme");
     let theme;
     try {
-      theme = await resolveTheme(appviewUrl, cookieHeader, colorSchemeHint);
+      theme = await resolveTheme(appviewUrl, cookieHeader, colorSchemeHint, cache);
     } catch (error) {
       logger.error("createThemeMiddleware: resolveTheme threw unexpectedly — using fallback", {
         operation: "createThemeMiddleware",

apps/web/src/routes/index.ts

···
 const config = loadConfig();
 
 export const webRoutes = new Hono<WebAppEnv>()
-  .use("*", createThemeMiddleware(config.appviewUrl))
+  .use("*", createThemeMiddleware(config.appviewUrl, config.themeCacheTtlMs))
   .route("/", createHomeRoutes(config.appviewUrl))
   .route("/", createBoardsRoutes(config.appviewUrl))
   .route("/", createTopicsRoutes(config.appviewUrl))

turbo.json

···
     },
     "test": {
       "dependsOn": ["^build"],
-      "env": ["DATABASE_URL", "LOG_LEVEL", "BACKFILL_RATE_LIMIT", "BACKFILL_CONCURRENCY", "BACKFILL_CURSOR_MAX_AGE_HOURS"]
+      "env": ["DATABASE_URL", "LOG_LEVEL", "BACKFILL_RATE_LIMIT", "BACKFILL_CONCURRENCY", "BACKFILL_CURSOR_MAX_AGE_HOURS", "THEME_CACHE_TTL_MS"]
     },
     "clean": {
       "cache": false