Expose the cache's persisted state per URL to the renderer

CacheManager records the outcome of every download in a `-info` sidecar
next to the cached file, but the renderer could only reach that state by
asking for the content itself, which starts a download for anything not
yet cached. A new read-only `getCacheInfos(urls)` IPC returns the
persisted CacheInfo for a batch of URLs — CACHED with its checksum, the
persisted ERROR, or NOT_CACHED for a URL never requested — without ever
fetching. A URL the cache cannot key at all is reported as an ERROR entry
for that URL instead of failing the whole batch.

This lets the renderer classify NFTs it has not rendered from what
earlier visits and sessions already learned about their files.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YKEGodEgVdEuvUM8dza52q

Author: jlobue10

packages/gui/src/@types/CacheService.ts

@@ -1,3 +1,5 @@
+import type CacheInfo from './CacheInfo';
+
 type CacheRequestOptions = {
   maxSize?: number;
   timeout?: number;
@@ -22,6 +24,8 @@ type CacheService = {
   getChecksum: (url: string, options?: CacheRequestOptions) => Promise<string>;
   getURI: (url: string, options?: CacheRequestOptions) => Promise<string>;
   invalidate: (url: string) => Promise<void>;
+  // Read-only lookup of the persisted cache state of each url — never downloads
+  getCacheInfos: (urls: string[]) => Promise<CacheInfo[]>;
 
   // Event subscriptions
   subscribeToDirectoryChange: (callback: (newDirectory: string) => void) => () => void;

packages/gui/src/electron/CacheManager.test.ts

@@ -219,3 +219,57 @@ describe('CacheManager eviction', () => {
     expect(mockDownloadFile).toHaveBeenCalledTimes(1);
   });
 });
+
+describe('CacheManager getCacheInfos', () => {
+  let cacheDirectory: string;
+
+  beforeEach(async () => {
+    mockDownloadFile.mockReset();
+    cacheDirectory = await fs.mkdtemp(path.join(os.tmpdir(), 'chia-cache-manager-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(cacheDirectory, { recursive: true, force: true });
+  });
+
+  it('reports persisted outcomes per url without downloading anything', async () => {
+    const payload = Buffer.from('cached payload');
+    mockDownloadFile.mockImplementation(async (url, localPath) => {
+      if (url === 'https://example.com/broken.png') {
+        throw new Error('getaddrinfo ENOTFOUND example.com');
+      }
+      await fs.writeFile(localPath, payload);
+      return {
+        'content-type': 'image/png',
+      };
+    });
+
+    const cacheManager = new CacheManager({
+      cacheDirectory,
+      maxCacheSize: 1024,
+    });
+    await cacheManager.init();
+
+    await expect(cacheManager.getContent('https://example.com/ok.png')).resolves.toEqual(payload);
+    await expect(cacheManager.getContent('https://example.com/broken.png')).rejects.toThrow('ENOTFOUND');
+    mockDownloadFile.mockClear();
+
+    const infos = await cacheManager.getCacheInfos([
+      'https://example.com/ok.png',
+      'https://example.com/broken.png',
+      'https://example.com/never-requested.png',
+      'not a url',
+    ]);
+
+    expect(infos.map((info) => [info.url, info.state])).toEqual([
+      ['https://example.com/ok.png', 'CACHED'],
+      ['https://example.com/broken.png', 'ERROR'],
+      ['https://example.com/never-requested.png', 'NOT_CACHED'],
+      ['not a url', 'ERROR'],
+    ]);
+    expect(infos[0]).toMatchObject({ checksum: expect.any(String) });
+    expect(infos[1]).toMatchObject({ error: 'getaddrinfo ENOTFOUND example.com' });
+    expect(infos[3]).toMatchObject({ error: 'Invalid URL: not a url' });
+    expect(mockDownloadFile).not.toHaveBeenCalled();
+  });
+});

packages/gui/src/electron/CacheManager.ts

@@ -235,6 +235,7 @@ export default class CacheManager extends EventEmitter {
       this.getURI(url, options),
     );
     ipcMainHandle(CacheAPI.INVALIDATE, (url: string) => this.invalidate(url));
+    ipcMainHandle(CacheAPI.GET_CACHE_INFOS, (urls: string[]) => this.getCacheInfos(urls));
 
     ipcMainHandle(CacheAPI.GET_CACHE_DIRECTORY, () => this.cacheDirectory);
     ipcMainHandle(CacheAPI.GET_MAX_CACHE_SIZE, () => this.maxCacheSize);
@@ -642,6 +643,29 @@ export default class CacheManager extends EventEmitter {
     throw new Error('Unknown cache state');
   }
 
+  // Reports what the cache already knows about each url without fetching
+  // anything: a download that never happened stays NOT_CACHED, and a url the
+  // cache cannot key at all is reported as an error instead of failing the
+  // whole batch. This lets the renderer classify NFTs that are not on screen
+  // (and so never verify their files) from outcomes persisted by earlier
+  // visits and sessions.
+  async getCacheInfos(urls: string[]): Promise<CacheInfo[]> {
+    return Promise.all(
+      urls.map(async (url) => {
+        try {
+          return await this.getCacheInfoByURL(url);
+        } catch (error) {
+          return {
+            url,
+            state: CacheState.ERROR,
+            error: (error as Error).message,
+            timestamp: Date.now(),
+          };
+        }
+      }),
+    );
+  }
+
   async clearCache() {
     // cancel all ongoing requests
     for (const ongoingRequest of this.ongoingRequests.values()) {

packages/gui/src/electron/constants/CacheAPI.ts

@@ -18,6 +18,7 @@ enum CacheAPI {
   GET_HEADERS = `${API.CACHE}:getHeaders`,
   GET_CHECKSUM = `${API.CACHE}:getChecksum`,
   GET_URI = `${API.CACHE}:getUri`,
+  GET_CACHE_INFOS = `${API.CACHE}:getCacheInfos`,
   INVALIDATE = `${API.CACHE}:invalidate`,
 
   // Event subscriptions

packages/gui/src/electron/preload.ts

@@ -132,6 +132,7 @@ contextBridge.exposeInMainWorld(API.CACHE, {
   getURI: (url: string, options?: { maxSize?: number; timeout?: number }) =>
     invokeWithCustomErrors(CacheAPI.GET_URI, url, options),
   invalidate: (url: string) => invokeWithCustomErrors(CacheAPI.INVALIDATE, url),
+  getCacheInfos: (urls: string[]) => invokeWithCustomErrors(CacheAPI.GET_CACHE_INFOS, urls),
   subscribeToDirectoryChange: (callback: (...args: unknown[]) => void) =>
     onIpcEvent(CacheAPI.ON_CACHE_DIRECTORY_CHANGED, callback),
   subscribeToMaxSizeChange: (callback: (...args: unknown[]) => void) =>