Add a preview-availability filter to the NFT gallery

NFTs whose media cannot be shown — a dead host, a file that no longer
matches its on-chain hash, or no file at all — render a placeholder tile
but could not be singled out, so finding the broken ones in a large
collection meant scrolling past every healthy one. The gallery's filter
bar gains a third pill next to the Types and Visible/Hidden ones, with
"Preview available" / "Preview not available" checkboxes and counts that
follow the same four-state model as the visibility pill.

The status behind the filter comes from two sources, both kept in a
per-NFT store inside NFTProvider:

- Tiles report what they actually settled on showing. The decision is
  derived from the same booleans NFTPreview renders from, so the filter
  classifies an NFT exactly as its tile does. Only preview-mode tiles
  report; the detail view verifies the full data file rather than the
  thumbnail and can legitimately disagree.
- The gallery is virtualized, so most NFTs never mount. Those are
  classified from the cache's persisted outcomes via the new
  `getCacheInfos` IPC, mirroring the URI walk `useNFTVerifyHash`
  performs: a cached file matching the hash makes the preview available,
  and it is unavailable only once every URI has a settled failure. A URI
  the cache has never seen (or failed only transiently) leaves the NFT
  undecided, and undecided NFTs count as available — a tile would still
  attempt the download. Lookups run in batches of 200 URLs, once per NFT
  per session; a live report always wins over a lookup.

Invalidating an NFT clears its verdict so the refreshed tile reports
anew. Filtering and the statistics counts re-run as verdicts arrive, so
with "Preview not available" selected the gallery converges on the
broken NFTs as tiles settle.

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

Author: jlobue10

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

@@ -0,0 +1,8 @@
+enum NFTPreviewAvailability {
+  AVAILABLE = 'available',
+  UNAVAILABLE = 'unavailable',
+  ALL = 'all',
+  NONE = 'none',
+}
+
+export default NFTPreviewAvailability;

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

@@ -0,0 +1,9 @@
+// Whether an NFT's gallery tile can show its media. UNAVAILABLE covers every
+// placeholder a tile renders instead of content: no file to verify against, a
+// file that failed to download, and a file that does not match its hash.
+enum NFTPreviewStatus {
+  AVAILABLE = 'available',
+  UNAVAILABLE = 'unavailable',
+}
+
+export default NFTPreviewStatus;

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

@@ -1,5 +1,8 @@
 import type FileType from '../constants/FileType';
 
-type NFTsDataStatistics = Record<FileType | 'visible' | 'hidden' | 'total' | 'sensitive', number>;
+type NFTsDataStatistics = Record<
+  FileType | 'visible' | 'hidden' | 'total' | 'sensitive' | 'previewAvailable' | 'previewUnavailable',
+  number
+>;
 
 export default NFTsDataStatistics;

packages/gui/src/components/nfts/NFTFilterProvider.tsx

@@ -1,17 +1,20 @@
 import React, { createContext, useMemo, useState, type ReactNode } from 'react';
 
+import NFTPreviewAvailability from '../../@types/NFTPreviewAvailability';
 import NFTVisibility from '../../@types/NFTVisibility';
 import FileType from '../../constants/FileType';
 
 export interface NFTFilterContextData {
   walletIds: number[];
   types: FileType[];
   visibility: NFTVisibility;
+  previewAvailability: NFTPreviewAvailability;
   search: string | undefined;
 
   setWalletIds: (value: number[]) => void;
   setTypes: (value: FileType[]) => void;
   setVisibility: (value: NFTVisibility) => void;
+  setPreviewAvailability: (value: NFTPreviewAvailability) => void;
   setSearch: (value: string | undefined) => void;
 }
 
@@ -34,21 +37,35 @@ export default function NFTFilterProvider(props: NFTFilterProviderProps) {
     FileType.UNKNOWN,
   ]);
   const [visibility, setVisibility] = useState<NFTVisibility>(NFTVisibility.ALL);
+  const [previewAvailability, setPreviewAvailability] = useState<NFTPreviewAvailability>(NFTPreviewAvailability.ALL);
   const [search, setSearch] = useState('');
 
   const value = useMemo(
     () => ({
       walletIds,
       types,
       visibility,
+      previewAvailability,
       search,
 
       setWalletIds,
       setTypes,
       setVisibility,
+      setPreviewAvailability,
       setSearch,
     }),
-    [walletIds, types, visibility, search, setWalletIds, setTypes, setVisibility, setSearch],
+    [
+      walletIds,
+      types,
+      visibility,
+      previewAvailability,
+      search,
+      setWalletIds,
+      setTypes,
+      setVisibility,
+      setPreviewAvailability,
+      setSearch,
+    ],
   );
 
   return <NFTFilterContext.Provider value={value}>{children}</NFTFilterContext.Provider>;

packages/gui/src/components/nfts/NFTPreview.tsx

@@ -5,6 +5,7 @@ import { alpha, Box, IconButton, Tooltip } from '@mui/material';
 import React, { useMemo, useRef, Fragment, useCallback, useEffect, type ReactNode } from 'react';
 import styled from 'styled-components';
 
+import NFTPreviewStatus from '../../@types/NFTPreviewStatus';
 import AudioSmallIcon from '../../assets/img/audio-small.svg';
 import DocumentBlobIcon from '../../assets/img/document-blob.svg';
 import DocumentSmallIcon from '../../assets/img/document-small.svg';
@@ -30,6 +31,7 @@ import useHideObjectionableContent from '../../hooks/useHideObjectionableContent
 import useNFT from '../../hooks/useNFT';
 import useNFTImageFittingMode from '../../hooks/useNFTImageFittingMode';
 import useNFTMetadata from '../../hooks/useNFTMetadata';
+import useNFTProvider from '../../hooks/useNFTProvider';
 import useNFTVerifyHash from '../../hooks/useNFTVerifyHash';
 import { useNFTVideoLoopGlobal, useNFTVideoLoopForNFT } from '../../hooks/useNFTVideoLoop';
 import useStateAbort from '../../hooks/useStateAbort';
@@ -139,6 +141,7 @@ export default function NFTPreview(props: NFTPreviewProps) {
   } = props;
 
   const { getURI } = useCache();
+  const { setPreviewStatus } = useNFTProvider();
   const nftId = useMemo(() => getNFTId(id), [id]);
   const iframeRef = useRef<any>(null);
   const { isDarkMode } = useDarkMode();
@@ -513,6 +516,40 @@ export default function NFTPreview(props: NFTPreviewProps) {
     !icon &&
     ![FileType.MODEL, FileType.DOCUMENT].includes(previewFileType);
 
+  // What the tile settled on showing — the same decision the render below
+  // makes — so the gallery's preview filter classifies NFTs exactly as their
+  // tiles do. Undefined while the tile is still loading.
+  const previewStatus = useMemo(() => {
+    if (isLoading) {
+      return undefined;
+    }
+
+    if (!hasFile || isHashMismatch) {
+      return NFTPreviewStatus.UNAVAILABLE;
+    }
+
+    if (usesIframe) {
+      if (prepareError) {
+        return NFTPreviewStatus.UNAVAILABLE;
+      }
+
+      if (!previewContent) {
+        return undefined;
+      }
+    }
+
+    return NFTPreviewStatus.AVAILABLE;
+  }, [isLoading, hasFile, isHashMismatch, usesIframe, prepareError, previewContent]);
+
+  useEffect(() => {
+    // Only preview-mode tiles report: the detail view verifies the full data
+    // file rather than the thumbnail and can legitimately disagree with the
+    // gallery tile for the same NFT.
+    if (isPreview && previewStatus) {
+      setPreviewStatus(nftId, previewStatus);
+    }
+  }, [isPreview, previewStatus, nftId, setPreviewStatus]);
+
   return (
     <StyledCardPreview width={width} height={height} sx={{ aspectRatio: ratio.toString() }}>
       {isLoading ? (

packages/gui/src/components/nfts/gallery/NFTGallery.tsx

@@ -35,6 +35,7 @@ import { xor, intersection /* , sortBy */ } from 'lodash';
 import React, { useMemo, useCallback, useRef, useEffect } from 'react';
 import { VirtuosoGrid } from 'react-virtuoso';
 
+import NFTPreviewAvailability from '../../../@types/NFTPreviewAvailability';
 import NFTVisibility from '../../../@types/NFTVisibility';
 import FileType from '../../../constants/FileType';
 import useFilteredNFTs from '../../../hooks/useFilteredNFTs';
@@ -111,6 +112,9 @@ export default function NFTGallery() {
     visibility,
     setVisibility,
 
+    previewAvailability,
+    setPreviewAvailability,
+
     statistics,
   } = useFilteredNFTs();
 
@@ -245,6 +249,40 @@ export default function NFTGallery() {
     }
   }
 
+  function togglePreviewAvailable() {
+    switch (previewAvailability) {
+      case NFTPreviewAvailability.ALL:
+        setPreviewAvailability(NFTPreviewAvailability.UNAVAILABLE);
+        return;
+      case NFTPreviewAvailability.AVAILABLE:
+        setPreviewAvailability(NFTPreviewAvailability.NONE);
+        return;
+      case NFTPreviewAvailability.NONE:
+        setPreviewAvailability(NFTPreviewAvailability.AVAILABLE);
+        return;
+      case NFTPreviewAvailability.UNAVAILABLE:
+      default:
+        setPreviewAvailability(NFTPreviewAvailability.ALL);
+    }
+  }
+
+  function togglePreviewUnavailable() {
+    switch (previewAvailability) {
+      case NFTPreviewAvailability.ALL:
+        setPreviewAvailability(NFTPreviewAvailability.AVAILABLE);
+        return;
+      case NFTPreviewAvailability.AVAILABLE:
+        setPreviewAvailability(NFTPreviewAvailability.ALL);
+        return;
+      case NFTPreviewAvailability.NONE:
+        setPreviewAvailability(NFTPreviewAvailability.UNAVAILABLE);
+        return;
+      case NFTPreviewAvailability.UNAVAILABLE:
+      default:
+        setPreviewAvailability(NFTPreviewAvailability.NONE);
+    }
+  }
+
   function renderNFTCard(index: number, nft: NFTInfo) {
     return (
       <NFTCard
@@ -450,6 +488,82 @@ export default function NFTGallery() {
                     </FilterPill>
                   </Box>
                 </Fade>
+                <Fade in={showFilters} unmountOnExit>
+                  <Box>
+                    <FilterPill
+                      title={
+                        previewAvailability === NFTPreviewAvailability.ALL ? (
+                          <Trans>
+                            Any preview &nbsp;
+                            <Chip label={<FormatLargeNumber value={statistics.total} />} size="extraSmall" />
+                          </Trans>
+                        ) : previewAvailability === NFTPreviewAvailability.AVAILABLE ? (
+                          <Trans>
+                            Preview available &nbsp;
+                            <Chip label={<FormatLargeNumber value={statistics.previewAvailable} />} size="extraSmall" />
+                          </Trans>
+                        ) : previewAvailability === NFTPreviewAvailability.UNAVAILABLE ? (
+                          <Trans>
+                            Preview not available &nbsp;
+                            <Chip
+                              label={<FormatLargeNumber value={statistics.previewUnavailable} />}
+                              size="extraSmall"
+                            />
+                          </Trans>
+                        ) : (
+                          <Trans>None (0)</Trans>
+                        )
+                      }
+                    >
+                      <FormControl>
+                        <Flex flexDirection="column">
+                          <FormControlLabel
+                            control={
+                              <Checkbox
+                                checked={[NFTPreviewAvailability.AVAILABLE, NFTPreviewAvailability.ALL].includes(
+                                  previewAvailability,
+                                )}
+                                onChange={togglePreviewAvailable}
+                              />
+                            }
+                            label={
+                              <Flex width="100%" gap={1} justifyContent="space-between" alignItems="center">
+                                <Box>
+                                  <Trans>Preview available</Trans>
+                                </Box>
+                                <Chip
+                                  label={<FormatLargeNumber value={statistics.previewAvailable} />}
+                                  size="extraSmall"
+                                />
+                              </Flex>
+                            }
+                          />
+                          <FormControlLabel
+                            control={
+                              <Checkbox
+                                checked={[NFTPreviewAvailability.UNAVAILABLE, NFTPreviewAvailability.ALL].includes(
+                                  previewAvailability,
+                                )}
+                                onChange={togglePreviewUnavailable}
+                              />
+                            }
+                            label={
+                              <Flex width="100%" gap={1} justifyContent="space-between" alignItems="center">
+                                <Box>
+                                  <Trans>Preview not available</Trans>
+                                </Box>
+                                <Chip
+                                  label={<FormatLargeNumber value={statistics.previewUnavailable} />}
+                                  size="extraSmall"
+                                />
+                              </Flex>
+                            }
+                          />
+                        </Flex>
+                      </FormControl>
+                    </FilterPill>
+                  </Box>
+                </Fade>
               </Flex>
             </Box>
           </Flex>

packages/gui/src/components/nfts/provider/NFTProvider.tsx

@@ -9,6 +9,7 @@ import useMetadataData from './hooks/useMetadataData';
 import useNFTData from './hooks/useNFTData';
 import useNFTDataNachos from './hooks/useNFTDataNachos';
 import useNFTDataOnDemand from './hooks/useNFTDataOnDemand';
+import useNFTPreviewStatuses from './hooks/useNFTPreviewStatuses';
 
 const log = debug('nft:NFTProvider');
 
@@ -131,6 +132,13 @@ export default function NFTProvider(props: NFTProviderProps) {
     [subscribeToDataChanges, subscribeToNachosChanges],
   );
 
+  const { getPreviewStatus, setPreviewStatus, invalidatePreviewStatus, subscribeToPreviewStatusChanges } =
+    useNFTPreviewStatuses({
+      nfts,
+      nachos,
+      subscribeToChanges,
+    });
+
   const invalidateNFT = useCallback(
     async (id: string | undefined) => {
       log(`Invalidating ${id}`);
@@ -143,6 +151,9 @@ export default function NFTProvider(props: NFTProviderProps) {
         return;
       }
 
+      // the files are about to be re-fetched, so the preview verdict is stale
+      invalidatePreviewStatus(id);
+
       // invalidate nft files
       const promises = [];
       const { dataUris, metadataUris } = nft;
@@ -177,7 +188,15 @@ export default function NFTProvider(props: NFTProviderProps) {
 
       await Promise.all([invalidateNachos(), invalidateMetadata(id), invalidateNFTOnDemand(id)]);
     },
-    [fetchNFT, fetchMetadata, invalidate, invalidateNachos, invalidateMetadata, invalidateNFTOnDemand],
+    [
+      fetchNFT,
+      fetchMetadata,
+      invalidate,
+      invalidateNachos,
+      invalidateMetadata,
+      invalidateNFTOnDemand,
+      invalidatePreviewStatus,
+    ],
   );
 
   const context = useMemo(
@@ -192,6 +211,10 @@ export default function NFTProvider(props: NFTProviderProps) {
       getMetadata,
       subscribeToMetadataChanges,
 
+      getPreviewStatus,
+      setPreviewStatus,
+      subscribeToPreviewStatusChanges,
+
       subscribeToChanges,
 
       invalidate: invalidateNFT,
@@ -214,6 +237,9 @@ export default function NFTProvider(props: NFTProviderProps) {
       subscribeToNFTChanges,
       getMetadata,
       subscribeToMetadataChanges,
+      getPreviewStatus,
+      setPreviewStatus,
+      subscribeToPreviewStatusChanges,
       count,
       loaded,
       progress,

packages/gui/src/components/nfts/provider/NFTProviderContext.ts

@@ -2,6 +2,7 @@ import { type NFTInfo } from '@chia-network/api';
 import { createContext } from 'react';
 
 import type MetadataState from '../../../@types/MetadataState';
+import type NFTPreviewStatus from '../../../@types/NFTPreviewStatus';
 import type NFTState from '../../../@types/NFTState';
 
 const NFTProviderContext = createContext<
@@ -29,6 +30,10 @@ const NFTProviderContext = createContext<
         id: string | undefined,
         callback: (metadataState: MetadataState) => void,
       ) => () => void;
+
+      getPreviewStatus: (id: string | undefined) => NFTPreviewStatus | undefined;
+      setPreviewStatus: (id: string, status: NFTPreviewStatus) => void;
+      subscribeToPreviewStatusChanges: (callback: () => void) => () => void;
     }
   | undefined
 >(undefined);