fix(clients): store project icons as served instead of canvas thumbnails

SVG favicons without width/height attributes report a 300x150 (or, on older
Firefox, 0x0) natural size, so the canvas thumbnail letterboxed the icon at
half size or collapsed it to one pixel and then persisted that image. Fetch
the icon bytes and inline them when they fit the cache limit; only bitmaps
larger than that go through a platform downscaler, and large SVGs stay remote.

Persist one record per icon rather than a single JSON blob so tabs cannot
overwrite each other's entries. On mobile the records live in client_cache so
Settings → Client storage counts and clears them, and clearing also drops the
in-memory images. Remote mobile icons key expo-image's disk cache by revision
again so signed-token rotation reuses cached bytes, and a changed icon starts
from the loading state.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: juliusmarminge

apps/mobile/src/components/ProjectFavicon.tsx

@@ -4,6 +4,7 @@ import { useLayoutEffect, useMemo, useState } from "react";
 import { View } from "react-native";
 import type { EnvironmentId } from "@t3tools/contracts";
 import {
+  getProjectFaviconCacheKey,
   getProjectFaviconResourceKey,
   isProjectFaviconFallbackUrl,
 } from "@t3tools/shared/projectFavicon";
@@ -41,9 +42,13 @@ export function ProjectFavicon(props: {
         }),
   );
   const renderableFaviconUrl = isProjectFaviconFallbackUrl(faviconUrl) ? null : faviconUrl;
+  // Inline images are self-contained; remote URLs key on their revision so signed-token
+  // rotation reuses the disk cache while a changed icon starts from the loading state.
   const cacheKey =
     renderableFaviconUrl && props.workspaceRoot
-      ? getProjectFaviconResourceKey(props.environmentId, props.workspaceRoot, props.faviconPath)
+      ? renderableFaviconUrl.startsWith("data:")
+        ? getProjectFaviconResourceKey(props.environmentId, props.workspaceRoot, props.faviconPath)
+        : getProjectFaviconCacheKey(props.environmentId, props.workspaceRoot, renderableFaviconUrl)
       : null;
 
   return (
@@ -79,7 +84,7 @@ function ProjectFaviconImage(props: {
   }, [faviconRequest]);
 
   const [status, setStatus] = useState<"loading" | "loaded" | "error">(() =>
-    props.faviconUrl?.startsWith("data:image/") || hasLoadedProjectFavicon(props.cacheKey)
+    props.faviconUrl?.startsWith("data:") || hasLoadedProjectFavicon(props.cacheKey)
       ? "loaded"
       : "loading",
   );
@@ -110,12 +115,12 @@ function ProjectFaviconImage(props: {
       {requestIsActive ? (
         <Image
           key={faviconRequest.faviconUrl}
-          source={{
-            uri: faviconRequest.faviconUrl,
-          }}
-          cachePolicy={
-            faviconRequest.faviconUrl.startsWith("data:image/") ? "memory" : "memory-disk"
+          source={
+            faviconRequest.faviconUrl.startsWith("data:")
+              ? { uri: faviconRequest.faviconUrl }
+              : { uri: faviconRequest.faviconUrl, cacheKey: faviconRequest.cacheKey }
           }
+          cachePolicy={faviconRequest.faviconUrl.startsWith("data:") ? "memory" : "memory-disk"}
           recyclingKey={faviconRequest.cacheKey}
           accessibilityLabel={`${props.projectTitle} favicon`}
           style={{

apps/mobile/src/connection/environment-cache-store.test.ts

@@ -32,6 +32,12 @@ function makeDatabase() {
   const database = MobileDatabase.of({
     loadCache: (environmentId, kind, cacheKey) =>
       Effect.succeed(Option.fromUndefinedOr(values.get(cacheId(environmentId, kind, cacheKey)))),
+    listCache: (kind) =>
+      Effect.sync(() =>
+        [...values.entries()]
+          .filter(([key]) => key.split(":")[1] === kind)
+          .map(([, payload]) => payload),
+      ),
     saveCache: (environmentId, kind, cacheKey, _schemaVersion, payload) =>
       Effect.sync(() => {
         values.set(cacheId(environmentId, kind, cacheKey), payload);

apps/mobile/src/connection/environment-cache-store.ts

@@ -238,9 +238,9 @@ export const make = Effect.fn("MobileEnvironmentCacheStore.make")(function* () {
         .pipe(Effect.mapError(mapDatabaseError("clear-vcs-refs"))),
     ),
     clear: Effect.fn("MobileEnvironmentCache.clear")((environmentId) =>
-      database.clearEnvironmentCache(environmentId).pipe(
+      Effect.promise(() => projectFaviconCache.clearEnvironment(environmentId)).pipe(
+        Effect.andThen(database.clearEnvironmentCache(environmentId)),
         Effect.mapError(mapDatabaseError("clear-environment")),
-        Effect.tap(() => Effect.promise(() => projectFaviconCache.clearEnvironment(environmentId))),
       ),
     ),
   });

apps/mobile/src/lib/projectFaviconCache.test.ts

@@ -27,9 +27,10 @@ vi.mock("expo-file-system", () => ({
   },
 }));
 
-import { createProjectFaviconThumbnail } from "./projectFaviconCache";
+import { downscaleProjectFavicon } from "./projectFaviconCache";
 
 const png = "iVBORw0KGgoAAAAA";
+const image = { url: "https://remote/icon.png" };
 
 beforeEach(() => {
   vi.clearAllMocks();
@@ -46,10 +47,7 @@ describe("mobile project icon thumbnails", () => {
     native.read.mockResolvedValueOnce(
       `iVBORw0KGgo${"a".repeat(PROJECT_FAVICON_MAX_DATA_URL_LENGTH)}`,
     );
-    const thumbnail = await createProjectFaviconThumbnail(
-      "https://remote/icon.png",
-      new AbortController().signal,
-    );
+    const thumbnail = await downscaleProjectFavicon(image, new AbortController().signal);
     expect(thumbnail).toBe(`data:image/png;base64,${png}`);
     expect(native.load.mock.calls.map(([, options]) => options.maxWidth)).toEqual([96, 48]);
     expect(native.remove).toHaveBeenCalledTimes(2);
@@ -64,19 +62,17 @@ describe("mobile project icon thumbnails", () => {
       controller.abort();
       return { width: 96, height: 96, release };
     });
-    await expect(
-      createProjectFaviconThumbnail("https://remote/icon.png", controller.signal),
-    ).rejects.toThrow();
+    await expect(downscaleProjectFavicon(image, controller.signal)).rejects.toThrow();
     expect(release).toHaveBeenCalledOnce();
     expect(native.write).not.toHaveBeenCalled();
   });
 
   it("rejects an image the native decoder did not downsize", async () => {
     const release = vi.fn();
     native.load.mockResolvedValueOnce({ width: 4000, height: 3000, release });
-    await expect(
-      createProjectFaviconThumbnail("https://remote/icon.png", new AbortController().signal),
-    ).rejects.toThrow("not resized");
+    await expect(downscaleProjectFavicon(image, new AbortController().signal)).rejects.toThrow(
+      "not resized",
+    );
     expect(native.write).not.toHaveBeenCalled();
     expect(release).toHaveBeenCalledOnce();
   });

apps/mobile/src/lib/projectFaviconCache.ts

@@ -1,31 +1,56 @@
 import {
   createProjectFaviconCache,
+  createProjectFaviconImageLoader,
   PROJECT_FAVICON_MAX_DATA_URL_LENGTH,
   PROJECT_FAVICON_THUMBNAIL_SIZE,
+  type ProjectFaviconEntry,
 } from "@t3tools/client-runtime/project-favicon-cache";
+import * as Effect from "effect/Effect";
 
-export async function createProjectFaviconThumbnail(url: string, signal: AbortSignal) {
+import * as MobileDatabase from "../persistence/mobile-database";
+
+const CACHE_KIND = "project-favicon";
+const CACHE_SCHEMA_VERSION = 1;
+
+// The runtime's persistence layer owns the cache store that hydrates this module, so
+// it is loaded on first use rather than at import time.
+const runDatabase = async <A, E>(
+  use: (database: MobileDatabase.MobileDatabase["Service"]) => Effect.Effect<A, E>,
+) => {
+  const { runtime } = await import("./runtime");
+  return runtime.runPromise(MobileDatabase.MobileDatabase.pipe(Effect.flatMap(use)));
+};
+
+/**
+ * Rasterizes a bitmap that is too large to inline. The native decoder writes the
+ * downsized frame to expo-image's disk cache, which is the only encode path it
+ * exposes; the temporary entry is removed once its bytes are read.
+ */
+export async function downscaleProjectFavicon(
+  image: { readonly url: string },
+  signal: AbortSignal,
+) {
   const [{ Image }, { File }] = await Promise.all([
     import("expo-image"),
     import("expo-file-system"),
   ]);
   for (const size of [PROJECT_FAVICON_THUMBNAIL_SIZE, PROJECT_FAVICON_THUMBNAIL_SIZE / 2]) {
     signal.throwIfAborted();
-    const image = await Image.loadAsync(url, { maxWidth: size, maxHeight: size });
-    const cacheKey = `t3-favicon-thumbnail:${size}:${url}`;
+    const decoded = await Image.loadAsync(image.url, { maxWidth: size, maxHeight: size });
+    const cacheKey = `t3-favicon-thumbnail:${size}:${image.url}`;
     try {
       signal.throwIfAborted();
-      if (image.width > size || image.height > size) {
+      if (decoded.width > size || decoded.height > size) {
         throw new Error("Project icon was not resized.");
       }
-      await Image.writeToCacheAsync(image, cacheKey);
+      await Image.writeToCacheAsync(decoded, cacheKey);
       const path = await Image.getCachePathAsync(cacheKey);
       if (!path) throw new Error("Project icon thumbnail was not written.");
       const file = new File(path.startsWith("file:") ? path : `file://${path}`);
       try {
         if (file.size > PROJECT_FAVICON_MAX_DATA_URL_LENGTH) continue;
         const base64 = await file.base64();
-        // SDWebImage chooses JPEG for opaque images and PNG for transparency.
+        // SDWebImage chooses JPEG for opaque images and PNG for transparency; Glide always writes PNG.
         const mimeType = base64.startsWith("/9j/")
           ? "image/jpeg"
           : base64.startsWith("iVBORw0KGgo")
@@ -38,25 +63,41 @@ export async function createProjectFaviconThumbnail(url: string, signal: AbortSi
         file.delete();
       }
     } finally {
-      image.release();
+      decoded.release();
     }
   }
   throw new Error("Project icon thumbnail exceeds the cache limit.");
 }
 
-async function cacheFile() {
-  const { File, Paths } = await import("expo-file-system");
-  return new File(Paths.cache, "t3-project-favicons-v1.json");
-}
-
+/** Rows live in `client_cache` so Settings → Client storage counts and clears them. */
 export const projectFaviconCache = createProjectFaviconCache({
-  async read() {
-    const file = await cacheFile();
-    return file.exists ? file.text() : null;
-  },
-  async write(json) {
-    const file = await cacheFile();
-    file.write(json);
+  storage: {
+    list: () =>
+      runDatabase((database) =>
+        database.listCache(CACHE_KIND).pipe(
+          Effect.map((payloads) =>
+            payloads.flatMap((payload): Array<unknown> => {
+              try {
+                return [JSON.parse(payload)];
+              } catch {
+                return [];
+              }
+            }),
+          ),
+        ),
+      ),
+    put: (key, entry: ProjectFaviconEntry) =>
+      runDatabase((database) =>
+        database.saveCache(
+          entry.environmentId,
+          CACHE_KIND,
+          key,
+          CACHE_SCHEMA_VERSION,
+          JSON.stringify(entry),
+        ),
+      ),
+    remove: (key, entry) =>
+      runDatabase((database) => database.removeCache(entry.environmentId, CACHE_KIND, key)),
   },
-  thumbnail: createProjectFaviconThumbnail,
+  load: createProjectFaviconImageLoader({ downscale: downscaleProjectFavicon }),
 });

apps/mobile/src/persistence/mobile-database.ts

@@ -16,7 +16,13 @@ const LEGACY_CACHE_DIRECTORIES = [
   "connection-vcs-refs",
 ] as const;
 
-export const ClientCacheKind = Schema.Literals(["shell", "thread", "server-config", "vcs-refs"]);
+export const ClientCacheKind = Schema.Literals([
+  "shell",
+  "thread",
+  "server-config",
+  "vcs-refs",
+  "project-favicon",
+]);
 export type ClientCacheKind = typeof ClientCacheKind.Type;
 
 export interface ClientCacheSummaryRow {
@@ -44,6 +50,7 @@ const MobileDatabaseOperation = Schema.Literals([
   "open",
   "migrate",
   "load-cache",
+  "list-cache",
   "save-cache",
   "remove-cache",
   "clear-cache-kind",
@@ -192,6 +199,9 @@ export class MobileDatabase extends Context.Service<
       kind: ClientCacheKind,
       cacheKey: string,
     ) => Effect.Effect<Option.Option<string>, MobileDatabaseError>;
+    readonly listCache: (
+      kind: ClientCacheKind,
+    ) => Effect.Effect<ReadonlyArray<string>, MobileDatabaseError>;
     readonly saveCache: (
       environmentId: EnvironmentId,
       kind: ClientCacheKind,
@@ -292,6 +302,16 @@ const makeAvailable = Effect.gen(function* () {
         catch: databaseError("load-cache"),
       }).pipe(Effect.map((row) => Option.fromNullishOr(row?.payload))),
     ),
+    listCache: Effect.fn("MobileDatabase.listCache")((kind) =>
+      Effect.tryPromise({
+        try: () =>
+          database.getAllAsync<{ readonly payload: string }>(
+            "SELECT payload FROM client_cache WHERE kind = ? ORDER BY updated_at",
+            kind,
+          ),
+        catch: databaseError("list-cache"),
+      }).pipe(Effect.map((rows) => rows.map((row) => row.payload))),
+    ),
     saveCache: Effect.fn("MobileDatabase.saveCache")(
       (environmentId, kind, cacheKey, schemaVersion, payload) =>
         Effect.tryPromise({
@@ -405,6 +425,7 @@ function makeUnavailable(error: MobileDatabaseError): MobileDatabase["Service"]
   const fail = Effect.fail(error);
   return MobileDatabase.of({
     loadCache: () => fail,
+    listCache: () => fail,
     saveCache: () => fail,
     removeCache: () => fail,
     clearCacheKind: () => fail,

apps/mobile/src/state/client-cache-state.ts

@@ -3,6 +3,7 @@ import * as Effect from "effect/Effect";
 import { Atom } from "effect/unstable/reactivity";
 
 import { type ClientCacheKind, MobileDatabase } from "../persistence/mobile-database";
+import { projectFaviconCache } from "../lib/projectFaviconCache";
 import * as Runtime from "../lib/runtime";
 
 export interface EnvironmentClientCacheSummary {
@@ -71,7 +72,12 @@ export const clientCacheSummaryAtom = clientCacheRuntime
 
 export const clearClientCacheAtom = clientCacheRuntime
   .fn((scope: ClientCacheClearScope, get) =>
-    MobileDatabase.pipe(
+    Effect.promise(() =>
+      scope.type === "all"
+        ? projectFaviconCache.clearAll()
+        : projectFaviconCache.clearEnvironment(scope.environmentId),
+    ).pipe(
+      Effect.andThen(MobileDatabase),
       Effect.flatMap((database) =>
         scope.type === "all"
           ? database.clearAllCaches