feat(api): publish iconUrl on /api/js-apps from Space siblings

Detects a custom app glyph by scanning each Space's `siblings`
(returned by HF's `?full=true`) for `icon.svg` or `icon.png` at
the repo root, then emits an absolute `resolve/main/<file>` URL
on the app entry as `iconUrl`. Falls back to `null` when neither
candidate is present, so clients keep painting the front-matter
emoji for the long tail of apps that don't ship a custom icon.

SVG wins over PNG when both are present so authors can rely on a
single vector asset across every mount point.

Resolution lives server-side behind the existing 5-minute catalog
cache, so the lookup cost stays O(apps) per refresh - independent
of client fleet size. The HF API call already pulls `siblings` via
`full=true`; no extra network roundtrip.

Documents the convention in docs/APP_ICON_CONVENTION.md for app
authors.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/APP_ICON_CONVENTION.md

@@ -0,0 +1,113 @@
+# App icon convention
+
+> Status: convention v1
+> Audience: authors shipping a Reachy Mini app to the Hugging Face Hub
+> Implemented by: `reachy-mini-website` catalog server (this repo) +
+> `reachy_mini_mobile_app`, `reachy_mini_desktop_app`
+> Source of truth: `server/index.js` → `findIconUrl()`
+
+This document specifies how a Reachy Mini app declares a custom icon.
+Apps that don't follow it keep working - the surface falls back to the
+front-matter `emoji:` glyph, which is the existing behaviour.
+
+---
+
+## 1. The convention in three lines
+
+To ship a custom icon for your Reachy Mini app:
+
+1. Commit `icon.svg` (preferred) **or** `icon.png` at the root of your
+   Hugging Face Space repository.
+2. That's it. Within ~5 minutes (the catalog cache TTL) the mobile
+   shell, the desktop app and the website surface your icon
+   automatically, replacing the README front-matter emoji.
+3. If both files are present, `icon.svg` wins.
+
+No README change required. No tag to add. No PR to file against this
+repo. The catalog server scans the file list once per refresh and
+publishes a resolved URL on the app entry; every client consumes it.
+
+---
+
+## 2. Why a file convention and not `cardData.thumbnail`
+
+HF Spaces support a `thumbnail:` field in README front-matter, but:
+
+- `thumbnail` is full-bleed marketing artwork (typically 1200x630),
+  not a square avatar. Scaling it to a 22 px or 44 px tile produces
+  muddy thumbnails.
+- We want app authors to ship a dedicated, optimised glyph they
+  control without learning the HF metadata schema.
+- SVG support means the icon scales cleanly across every mount point
+  (rail tile, pinned grid, iframe header) from a single asset.
+
+`thumbnail:` keeps its existing role (banner artwork on the Space's
+HF page) and is not consulted by this resolution path.
+
+---
+
+## 3. Format & dimension recommendations
+
+| Property | Recommended | Hard requirement |
+|----------|-------------|------------------|
+| Format | `icon.svg` (vector) | `icon.svg` or `icon.png` |
+| Aspect ratio | 1:1 (square) | Renderers crop with `object-fit: contain`, but non-square icons render with letterboxing - prefer a true square |
+| Min PNG size | 256x256 | None enforced. PNGs below 64x64 will look soft on the pinned grid (44 px on retina ≈ 88 effective px) |
+| Background | Transparent OR solid colour | None - your call. Renderers don't add their own plate, so an icon with no background renders directly on the tile colour |
+| Padding | Bake ~10% inner padding into the asset | None - but icons that bleed edge-to-edge will touch the tile's rounded corners |
+| Light/dark variants | Single asset that works on both | None - if you must, ship two SVGs and use `prefers-color-scheme` inside the SVG via CSS |
+
+### Style notes
+
+- **Iconic, not photographic.** A solid filled silhouette reads at
+  22 px; a screenshot doesn't.
+- **High contrast against `background.paper`.** The mobile app paints
+  the tile background with the surface colour (very light grey on
+  light, near-black on dark). A pure white icon disappears on light.
+- **No drop shadow** baked into the asset. The renderer doesn't add
+  one either, and a baked shadow won't scale across sizes.
+
+---
+
+## 4. How resolution works (for the curious)
+
+1. The catalog server calls
+   `https://huggingface.co/api/spaces?filter=reachy_mini&full=true`.
+   With `full=true`, the HF Hub returns `siblings: [{ rfilename: ... }]`
+   for every Space - the complete file list.
+2. For each app, `findIconUrl()` (in `server/index.js`) scans the
+   list for root-level filenames matching `ICON_CANDIDATES` in order
+   (`icon.svg` → `icon.png`).
+3. The first match becomes:
+
+   ```
+   https://huggingface.co/spaces/<author>/<repo>/resolve/main/<filename>
+   ```
+
+   `resolve/main/` (not `raw/main/`) so LFS pointers follow through
+   transparently and the `Content-Type` is set from the extension,
+   which `<img>` needs.
+4. The URL is published on the app entry as a top-level `iconUrl`
+   field. `null` when neither candidate exists.
+5. Clients (`reachy_mini_mobile_app`, `reachy_mini_desktop_app`) read
+   `iconUrl` and render an `<img>` when present, falling back to the
+   front-matter emoji otherwise. A runtime image load failure
+   re-falls-back to the emoji without a refresh.
+
+The whole resolution path is server-side, behind the 5-minute catalog
+cache. Adding 100 more apps adds zero per-client probes.
+
+---
+
+## 5. Adding new icon formats
+
+If you need to support a new format (say, `icon.webp`), edit
+`ICON_CANDIDATES` in `server/index.js`:
+
+```js
+const ICON_CANDIDATES = ['icon.svg', 'icon.png', 'icon.webp'];
+```
+
+Order matters - the first hit wins, so put the preferred format first.
+Bumping the catalog cache (POST `/api/js-apps/refresh-categories` or
+just wait 5 minutes) picks up the new resolution rule.

server/index.js

@@ -53,6 +53,65 @@ const HF_SPACES_LIMIT = 1000;
 // from the mobile codebase down the line.
 const JS_APP_TAG = 'reachy_mini_js_app';
 
+// =====================================================================
+// App icon convention
+// =====================================================================
+//
+// Convention: an app MAY commit `icon.svg` (preferred) or
+// `icon.png` at the root of its HF Space repository. When present,
+// the mobile shell + desktop store render it as the app glyph
+// instead of the front-matter `emoji:` codepoint.
+//
+// We resolve the icon ONCE at indexing time (here) rather than
+// probing per-client because:
+//   1. We already pull `siblings` from `?full=true` (one cheap
+//      hub call returns the file list for every app), so the
+//      lookup is a pure JS filter, no extra network.
+//   2. Clients see a single field (`iconUrl`) in the payload and
+//      don't have to know about HF resolve URLs, LFS pointers,
+//      or the candidate-order race ("SVG wins if both exist").
+//   3. The HF API caps probes at ~hub side; doing it server-side
+//      keeps fanout under a 5-minute TTL behind ONE token, instead
+//      of every mobile shell hammering `huggingface.co/resolve/`
+//      to discover icons.
+//
+// Resolution order: `icon.svg` → `icon.png`. SVG first because the
+// same asset scales cleanly across every mount point (small rail
+// tile, larger pinned tile, iframe header) from a single file.
+// Extra formats can be added to `ICON_CANDIDATES` if needed; order
+// matters - the first match wins.
+const ICON_CANDIDATES = ['icon.svg', 'icon.png'];
+
+/**
+ * Look for a standard app icon file at the root of the Space.
+ * Returns the absolute HF resolve URL when found, `null` otherwise.
+ *
+ * We hit `resolve/main/` (not `raw/main/`) so:
+ *   - LFS pointers follow transparently (large PNGs work).
+ *   - `Content-Type` comes from the extension, which `<img>` needs.
+ *   - The URL is cacheable cross-session by the browser, so
+ *     repeated mounts of the same app glyph don't re-fetch.
+ */
+function findIconUrl(spaceId, siblings) {
+  if (!spaceId || !Array.isArray(siblings)) return null;
+  // Build a Set of root-level filenames for O(1) candidate
+  // lookups. HF returns `siblings` as `[{ rfilename: "path/in/repo" }, ...]`,
+  // so we filter to repo-root (no slash) before testing.
+  const rootFiles = new Set();
+  for (const s of siblings) {
+    const name = s && typeof s.rfilename === 'string' ? s.rfilename : null;
+    if (!name) continue;
+    if (name.includes('/')) continue;
+    rootFiles.add(name);
+  }
+  for (const candidate of ICON_CANDIDATES) {
+    if (rootFiles.has(candidate)) {
+      return `https://huggingface.co/spaces/${spaceId}/resolve/main/${candidate}`;
+    }
+  }
+  return null;
+}
+
 // Serialised LLM batch concurrency: we want at most one
 // categorization sweep running at a time, regardless of how many
 // /api/js-apps requests come in. The flag also prevents the
@@ -98,6 +157,13 @@ async function fetchAppsFromHF() {
       const author = spaceId.split('/')[0];
       const name = spaceId.split('/').pop();
       
+      // Server-resolved icon URL. Looks for `icon.svg` or `icon.png`
+      // at the repo root via the `siblings` list returned by
+      // `?full=true`. See `findIconUrl()` above for the rationale.
+      // `null` when the author hasn't shipped one; clients fall
+      // back to the front-matter emoji.
+      const iconUrl = findIconUrl(spaceId, space.siblings);
+
       return {
         // Core fields (used by both website and desktop)
         id: spaceId,
@@ -106,7 +172,8 @@ async function fetchAppsFromHF() {
         url: `https://huggingface.co/spaces/${spaceId}`,
         source_kind: 'hf_space',
         isOfficial,
-        
+        iconUrl,
+
         // Extra metadata (desktop-compatible structure)
         extra: {
           id: spaceId,