Give every stack an icon, and put the status on it (0.51.0)

Stacks were a name and a coloured dot. The dot carried the status but nothing
carried identity, so a list of twenty stacks read as twenty identical rows.
This gives each one an icon in front of its name and moves the status onto that
icon as a halo in the status colour, which is the thing the eye lands on anyway.

The constraint that shaped the design: people already have stacks. Asking them
to pick an icon for each one before the feature does anything would mean it
never gets used, so the icon is *derived* from the stack's name and the column
stays empty until somebody overrides it. ~700 keywords in 79 groups cover the
self-hosted long tail (jellyfin -> clapperboard, vaultwarden -> key,
home-assistant -> house) plus generic English and German terms; the longest
match wins, so photoprism beats a bare photo, and short keywords like "tv" only
match as whole words. No backfill, no migration, and a rename moves the icon
with it.

That is also why the catalog and the matcher live in the frontend. It is the
only place that can render an icon, so a copy in the backend would be a list to
keep in sync and nothing else. The server validates the shape of the stored
value and stores uploads; it never needs to know what "lucide:database" looks
like. An icon name that later leaves the catalog falls back to the derived one
rather than blanking the row.

Overriding happens in two places, because there are two moments: the editor
(holding a chosen file until the stack exists, since uploading needs an id) and
a click on the icon on the detail page, which is how a stack that has existed
for a year gets one without a trip through the editor.

Uploads are classified by their bytes, not by the filename or Content-Type the
browser claims, and land in ${DATA_DIR}/stack-icons/ under the stack id. SVG is
allowed — <img> does not execute it — but the endpoint serves every icon as an
attachment so one can never be opened as a document in the API's own origin. A
client-supplied "custom:" value is refused: the server mints those, so a stack
cannot be pointed at a file it does not own. Files follow the stack: replaced on
re-upload (including across formats, or the old one orphans), copied on clone,
removed on delete.

The one piece of plumbing worth knowing about: the icon endpoint needs the
bearer token like everything else, and an <img src> would not carry it. So
StackIcon fetches the bytes through the API client and renders the blob, keyed
on the stored value — which carries an upload timestamp precisely so a re-upload
changes the key and retires the cached image.

Covered by 22 backend tests (the value rules, byte-sniffing, the file lifecycle,
the API round-trip, and that the read-only role cannot change an icon) and 29
frontend ones for the matcher. The schema change was verified against a
hand-built pre-0.51 database: the column is added on start and existing rows
come back NULL, i.e. automatic. Not click-tested in a browser — no Docker in
this environment — so the row height the taller icon produces is unverified.

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

frontend/src/components/ui/StackIcon.tsx

@@ -0,0 +1,153 @@
+import { useEffect, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { cn } from "@/lib/utils";
+import { iconComponent, resolveStackIcon } from "@/lib/stackIcons";
+import { stacksApi } from "@/api/stacks";
+import type { StackStatus } from "@/types";
+
+/**
+ * A stack's icon, wearing its status as a coloured glow.
+ *
+ * This replaces the status dot in the stacks list: the same information, but
+ * carried by the thing the eye lands on anyway. The status is still spelled out
+ * in the badge next to it and in the tooltip here, so the colour is never the
+ * only way to read it.
+ */
+
+type Size = "sm" | "md" | "lg";
+
+const SIZES: Record<Size, { box: string; glyph: string; radius: string }> = {
+  sm: { box: "h-7 w-7", glyph: "h-3.5 w-3.5", radius: "rounded-[9px]" },
+  md: { box: "h-9 w-9", glyph: "h-[18px] w-[18px]", radius: "rounded-[11px]" },
+  lg: { box: "h-12 w-12", glyph: "h-6 w-6", radius: "rounded-[15px]" },
+};
+
+/** Ring + halo per status. Kept as whole class strings because Tailwind only
+ *  sees classes it can find literally in the source. */
+const STATUS_STYLE: Record<StackStatus, { ring: string; halo: string; glyph: string }> = {
+  running: {
+    ring: "ring-green-500/60 dark:ring-green-400/60",
+    halo: "bg-green-500/40 dark:bg-green-400/40",
+    glyph: "text-green-600 dark:text-green-400",
+  },
+  partial: {
+    ring: "ring-yellow-500/60 dark:ring-yellow-400/60",
+    halo: "bg-yellow-500/40 dark:bg-yellow-400/40",
+    glyph: "text-yellow-600 dark:text-yellow-400",
+  },
+  stopped: {
+    ring: "ring-slate-400/50 dark:ring-slate-500/50",
+    halo: "bg-slate-400/20 dark:bg-slate-500/20",
+    glyph: "text-slate-500 dark:text-slate-400",
+  },
+  error: {
+    ring: "ring-red-500/60 dark:ring-red-400/60",
+    halo: "bg-red-500/45 dark:bg-red-400/45",
+    glyph: "text-red-600 dark:text-red-400",
+  },
+  updating: {
+    ring: "ring-sky-500/60 dark:ring-sky-400/60",
+    halo: "bg-sky-500/45 dark:bg-sky-400/45",
+    glyph: "text-sky-600 dark:text-sky-400",
+  },
+  unknown: {
+    ring: "ring-slate-300/60 dark:ring-slate-600/60",
+    halo: "bg-slate-300/20 dark:bg-slate-600/20",
+    glyph: "text-slate-400 dark:text-slate-500",
+  },
+};
+
+export function StackIcon({
+  stack,
+  status,
+  size = "md",
+  previewUrl,
+  className,
+}: {
+  stack: { id: string; name: string; icon?: string | null };
+  status: StackStatus;
+  size?: Size;
+  /** Shows this image instead of the stored icon — used to preview a file that
+   *  has been chosen but not uploaded yet (a stack being created). */
+  previewUrl?: string | null;
+  className?: string;
+}) {
+  const resolved = resolveStackIcon(stack);
+  const dims = SIZES[size];
+  const tone = STATUS_STYLE[status] ?? STATUS_STYLE.unknown;
+  const stored = useCustomIconUrl(
+    stack.id,
+    resolved.kind === "custom" && !previewUrl ? stack.icon : null
+  );
+  const custom = previewUrl ?? stored;
+  const Glyph = iconComponent(resolved.kind === "builtin" ? resolved.name : "");
+
+  return (
+    <span
+      className={cn("relative inline-flex shrink-0", dims.box, className)}
+      role="img"
+      aria-label={`${stack.name} — ${status}`}
+      title={status}
+    >
+      {/* The status "shimmer": a blurred copy of the status colour bleeding out
+          from behind the tile. Pulses while an operation is running. */}
+      <span
+        aria-hidden
+        className={cn(
+          "pointer-events-none absolute -inset-[3px] blur-[5px]",
+          dims.radius,
+          tone.halo,
+          status === "updating" && "animate-pulse"
+        )}
+      />
+      <span
+        className={cn(
+          "relative inline-flex h-full w-full items-center justify-center overflow-hidden",
+          "bg-sp-surface-2 ring-2",
+          dims.radius,
+          tone.ring
+        )}
+      >
+        {custom ? (
+          <img src={custom} alt="" className="h-full w-full object-cover" />
+        ) : (
+          <Glyph className={cn(dims.glyph, tone.glyph)} strokeWidth={2} />
+        )}
+      </span>
+    </span>
+  );
+}
+
+/**
+ * Object URL for a stack's uploaded icon, or null while there is none.
+ *
+ * The icon endpoint needs the bearer token, so the bytes are fetched through
+ * the API client and handed to the browser as a blob. `icon` is part of the
+ * query key and changes on every upload (it carries a version), which is what
+ * retires the previous image instead of leaving a stale one on screen.
+ */
+function useCustomIconUrl(stackId: string, icon: string | null | undefined): string | null {
+  const { data: blob } = useQuery({
+    queryKey: ["stack-icon", stackId, icon],
+    queryFn: () => stacksApi.icon(stackId),
+    enabled: Boolean(icon),
+    staleTime: Infinity,
+    gcTime: 60 * 60 * 1000,
+    retry: false,
+  });
+  const [url, setUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!blob) {
+      setUrl(null);
+      return;
+    }
+    const objectUrl = URL.createObjectURL(blob);
+    setUrl(objectUrl);
+    // Every mount makes its own URL; without this each row would leak one for
+    // the lifetime of the tab.
+    return () => URL.revokeObjectURL(objectUrl);
+  }, [blob]);
+
+  return url;
+}