@grove-dev/astro 0.5.2 → 0.5.3

package/src/components/IndexRow.astro

@@ -4,10 +4,11 @@
  *
  * Keeps the historical public props (`record`, `detailHref`,
  * `showChips`, `eager`) so consumer pages copied from earlier versions
- * keep working, while the visual language is now identical to every
- * other card surface. The directory extras — curated badge, license,
- * category · status line, labelled stack/platform chips, and the
- * GitHub footer link — are enabled via `ProjectCard`'s opt-in props.
+ * keep working. The card itself is the same on every surface: a
+ * record must not look like a different record depending on whether
+ * you found it on the home page or in the browse list. The repository
+ * is reached through the card's `owner/repo` line, so this adapter
+ * adds nothing to the card at all.
  */
 import type { IndexRecord } from "@grove-dev/core";
 import ProjectCard from "./ProjectCard.astro";
@@ -15,7 +16,7 @@ import ProjectCard from "./ProjectCard.astro";
 interface Props {
   record: IndexRecord;
   detailHref: string;
-  /** Whether to show stack/platform chips. Default true. */
+  /** @deprecated Ignored — the card renders one fixed layout. */
   showChips?: boolean;
   /** Set true on the first 1-2 rows of a list to bypass lazy
    * loading for the above-the-fold avatars. Pair with
@@ -24,32 +25,13 @@ interface Props {
   class?: string;
 }
 
-const { record, detailHref, showChips = true, eager = false, class: className = "" } = Astro.props;
+const { record, detailHref, eager = false, class: className = "" } = Astro.props;
 
-const repoHref =
-  record.kind === "project" ? (record.repoUrl ?? record.links.github) : record.links.github;
-
-const secondaryLinks = repoHref
-  ? [
-      {
-        label: "GitHub",
-        href: repoHref,
-        external: true,
-        event: "external_repo_click",
-        eventSource: "index_row_github",
-      },
-    ]
-  : [];
 ---
 
 <ProjectCard
   record={record}
   href={detailHref}
-  showCurated
-  showLicense
-  showCategoryStatus
-  labelledChips={showChips}
-  secondaryLinks={secondaryLinks}
   eager={eager}
   class={className}
 />

package/src/components/ProjectCard.astro

@@ -10,18 +10,24 @@
  *   - Default mode: the whole card is one clickable `<a>` (cursor:
  *     pointer, subtle border + surface lift on hover, no more than
  *     1–2px vertical motion).
- *   - When `secondaryLinks` are passed the root becomes an `<article>`
- *     with a stretched title link, because nesting `<a>` inside `<a>`
- *     is invalid HTML. Secondary links sit above the stretched link
+ *   - When the record has a repository the root becomes an
+ *     `<article>` with a stretched title link, because nesting `<a>`
+ *     inside `<a>` is invalid HTML. The `owner/repo` line is a real
+ *     link to the repository and sits above the stretched overlay
  *     (`relative z-10`).
- *   - App icon top-left (48px), app name + repository owner/repo,
+ *   - App icon top-left (48px), app name + clickable owner/repo,
  *     two-line description with reserved vertical space.
- *   - Footer row: platform logos (or labelled stack/platform chips via
- *     `labelledChips`), stars/updated/license on the right, and the
- *     navigation arrow anchored bottom-right.
- *   - Everything beyond the default home-page rendering is opt-in:
- *     `showCurated`, `showLicense`, `showCategoryStatus`,
- *     `labelledChips`, `secondaryLinks`, analytics `data-event` props.
+ *   - Footer row: stack logos on the left, stars and last-updated on
+ *     the right, navigation arrow anchored bottom-right.
+ *
+ * **The layout is fixed.** Earlier versions let list pages opt into a
+ * curated badge, a license tag, a `category · status` line and
+ * labelled chip rows, so the same record rendered differently
+ * depending on where a visitor found it. Those flags are now
+ * deprecated no-ops, as is `secondaryLinks` — the repository is
+ * reached through the `owner/repo` line rather than a separate footer
+ * button. Platform support is likewise off the card: it is reference
+ * detail and belongs on the record page (`RecordSidebar`).
  *
  * Data can come from a full `record` or from explicit props (adapters
  * for shapes like `CollectionEntry` pass fields directly); explicit
@@ -37,14 +43,11 @@ import {
   getOwnerAvatarUrl,
   formatRelative,
   formatStars,
-  licenseDisplay,
   nameInitials,
   projectStackIds,
-  statusDisplay,
 } from "@grove-dev/astro";
 import CardIcon from "./CardIcon.astro";
 import Icon from "./Icon.astro";
-import StackPlatformChips from "./StackPlatformChips.astro";
 
 type CardRecord = IndexRecord | Resource | ProjectRecord | IndexProjectRecord;
 
@@ -78,14 +81,31 @@ interface Props {
   status?: string;
   curated?: boolean;
   stack?: string;
+  /**
+   * @deprecated Cards render the stack, not platform support — that
+   * belongs on the record page. Accepted and ignored.
+   */
   platforms?: string[];
-  /** Opt-in extras (all default off to keep the home grid unchanged). */
+  /**
+   * @deprecated The card renders one fixed metadata set on every
+   * surface. These flags used to add a curated badge, a license tag,
+   * a `category · status` line, and labelled chip rows on list pages
+   * only, which made the same record look like a different record
+   * depending on where you found it. Accepted and ignored.
+   */
   showCurated?: boolean;
+  /** @deprecated Ignored — see `showCurated`. */
   showLicense?: boolean;
+  /** @deprecated Ignored — see `showCurated`. */
   showCategoryStatus?: boolean;
-  /** Labelled stack/platform chip rows instead of the logo strip. */
+  /** @deprecated Ignored — see `showCurated`. */
   labelledChips?: boolean;
   /** Footer links; presence switches the root to `<article>` mode. */
+  /**
+   * @deprecated Ignored. The repository is reached by clicking the
+   * `owner/repo` line under the title, so cards no longer carry a
+   * separate footer link button.
+   */
   secondaryLinks?: SecondaryLink[];
   /** Eager-load the avatar (above-the-fold rows). */
   eager?: boolean;
@@ -105,17 +125,7 @@ const {
   repoUrl: repoUrlProp,
   stars: starsProp,
   pushedAt: pushedAtProp,
-  license: licenseProp,
-  category: categoryProp,
-  status: statusProp,
-  curated: curatedProp,
   stack: stackProp,
-  platforms: platformsProp,
-  showCurated = false,
-  showLicense = false,
-  showCategoryStatus = false,
-  labelledChips = false,
-  secondaryLinks = [],
   eager = false,
   event,
   eventSource,
@@ -148,8 +158,6 @@ const initials = nameInitials(name);
 const description =
   descriptionProp ?? (record as { description?: string } | undefined)?.description ?? "";
 
-const platforms =
-  platformsProp ?? (isProject ? ((record as { platforms?: string[] }).platforms ?? []) : []);
 const stars =
   starsProp ?? (isProject ? (record as { github?: { stars?: number } }).github?.stars : undefined);
 const pushedAt =
@@ -157,53 +165,34 @@ const pushedAt =
   (isProject
     ? (record as { github?: { pushedAt?: string | null } }).github?.pushedAt
     : (record as { publishedAt?: string | null } | undefined)?.publishedAt);
-const license =
-  licenseProp ??
-  (isProject ? (record as { github?: { license?: string | null } }).github?.license : undefined);
-const category = categoryProp ?? (record as { category?: string } | undefined)?.category;
-const status =
-  statusProp ?? (isProject ? (record as { health?: { status?: string } }).health?.status : undefined);
-const curated =
-  curatedProp ??
-  Boolean(
-    (record as { curation?: { reviewed?: boolean } } | undefined)?.curation?.reviewed ||
-      (isProject &&
-        ((record as { bestFor?: string[] }).bestFor?.length ||
-          (record as { whyListed?: string[] }).whyListed?.length ||
-          (record as { caveats?: string[] }).caveats?.length)),
-  );
-
-const stackId =
-  stackProp ??
-  (isProject
-    ? projectStackIds(record as { stack?: string; stacks?: string[] })[0]
-    : undefined);
+const stackIds = stackProp
+  ? [stackProp]
+  : isProject
+    ? projectStackIds(record as { stack?: string; stacks?: string[] })
+    : [];
 
 const starsLabel = formatStars(stars);
 const updatedLabel = formatRelative(pushedAt);
-// "Unknown" is an internal placeholder, not information — suppress it
-// so card metadata never reads "Category · Unknown" to visitors.
-const rawStatusText = status ? statusDisplay(status as Parameters<typeof statusDisplay>[0]) : "";
-const statusText = rawStatusText === "Unknown" ? "" : rawStatusText;
-const licenseLabel = license ? licenseDisplay(license) : null;
 
 const hasStars = starsLabel !== null && typeof stars === "number" && stars > 0;
 const hasUpdated = Boolean(pushedAt);
 
-// `<a>`-in-`<a>` is invalid HTML, so cards with secondary links render
-// as an `<article>` whose title link is stretched over the card.
-const isArticle = secondaryLinks.length > 0;
+// `<a>`-in-`<a>` is invalid HTML, and the `owner/repo` line is its own
+// link to the repository — so any card that shows one renders as an
+// `<article>` whose title link is stretched over the whole card.
+const isArticle = Boolean(repoHref && owner && repo);
 const Root = isArticle ? "article" : "a";
 const rootAttrs = isArticle ? {} : { href, "aria-label": `Open ${name}` };
 
-// Render the homepage brand strip through the shared `Icon` component
-// so brand marks come from the same `/icons/platforms/` files the
-// chip rows use. No more inline SVG strings — one source of truth.
-// `Icon` falls back to initials when an asset is missing, so the
-// strip simply renders whatever platforms the record declares.
-const visiblePlatforms = platforms.slice(0, 4);
-const platformOverflow = platforms.length - visiblePlatforms.length;
-const hasPlatforms = visiblePlatforms.length > 0;
+// The card's brand strip shows the record's STACK, not its platforms.
+// Stack is what distinguishes one card from its neighbours in a list;
+// platform support is reference detail, and it belongs on the record
+// page (`RecordSidebar`) where there is room to label it. Marks come
+// from the shared `Icon` component, which falls back to initials when
+// an asset is missing.
+const visibleStacks = stackIds.slice(0, 4);
+const stackOverflow = stackIds.length - visibleStacks.length;
+const hasStacks = visibleStacks.length > 0;
 ---
 
 <Root
@@ -251,27 +240,25 @@ const hasPlatforms = visiblePlatforms.length > 0;
       </h3>
       {owner && repo && (
         <p class="m-0 truncate font-mono text-[13px] text-ink-500 dark:text-ink-400">
-          {owner}<span class="opacity-60">/</span>{repo}
-        </p>
-      )}
-      {showCategoryStatus && (category || statusText) && (
-        <p class="m-0 truncate text-2xs text-ink-500 dark:text-ink-400">
-          {category}
-          {category && statusText && <span class="mx-1 text-ink-300 dark:text-ink-700">·</span>}
-          {statusText}
+          {repoHref ? (
+            <a
+              href={repoHref}
+              target="_blank"
+              rel="noopener noreferrer"
+              title={`${owner}/${repo} on GitHub`}
+              data-event="external_repo_click"
+              data-event-source="project_card_repo"
+              data-event-item={slug}
+              class="relative z-10 text-inherit no-underline transition-colors hover:text-ink-900 hover:underline dark:hover:text-ink-100"
+            >
+              {owner}<span class="opacity-60">/</span>{repo}
+            </a>
+          ) : (
+            <Fragment>{owner}<span class="opacity-60">/</span>{repo}</Fragment>
+          )}
         </p>
       )}
     </div>
-
-    {showCurated && curated && (
-      <span
-        class="inline-flex shrink-0 items-center gap-1 text-[10px] font-medium uppercase tracking-wider text-muted-foreground"
-        title="Reviewed by a curator"
-      >
-        <CardIcon name="curated" />
-        curated
-      </span>
-    )}
   </header>
 
   {/* Description — two-line clamp with reserved vertical space */}
@@ -281,39 +268,16 @@ const hasPlatforms = visiblePlatforms.length > 0;
     {description}
   </p>
 
-  {/* Labelled stack/platform chip rows (opt-in; directory surfaces) */}
-  {labelledChips && (
-    <StackPlatformChips stack={stackId} platform={platforms} />
-  )}
-
-  {/* Footer: links / platform logos · meta · arrow */}
+  {/* Footer: stack logos · stars/updated · arrow */}
   <footer class="mt-auto flex items-center justify-between gap-3 text-[12px] sm:text-[13px]">
     <div class="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1 text-ink-500 dark:text-ink-400">
-      {secondaryLinks.map((link) => (
-        <a
-          href={link.href}
-          {...(link.external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
-          data-event={link.event}
-          data-event-source={link.eventSource}
-          data-event-item={link.event ? slug : undefined}
-          class="relative z-10 inline-flex items-center gap-1 font-medium text-ink-700 no-underline transition-colors hover:text-ink-900 dark:text-ink-300 dark:hover:text-ink-100"
-        >
-          {link.label}
-          {link.external && <CardIcon name="external" />}
-        </a>
-      ))}
-      {!labelledChips && hasPlatforms && (
-        <div class="flex items-center gap-2.5">
-          {visiblePlatforms.map((platform) => (
-            <Icon
-              name={platform}
-              category="platform"
-              size={22}
-              title={platform}
-            />
+      {hasStacks && (
+        <div class="flex items-center gap-2">
+          {visibleStacks.map((stack) => (
+            <Icon name={stack} category="stack" size={16} title={stack} />
           ))}
-          {platformOverflow > 0 && (
-            <span class="text-[12px] text-ink-500 dark:text-ink-400">+{platformOverflow}</span>
+          {stackOverflow > 0 && (
+            <span class="text-[12px] text-ink-500 dark:text-ink-400">+{stackOverflow}</span>
           )}
         </div>
       )}
@@ -331,11 +295,6 @@ const hasPlatforms = visiblePlatforms.length > 0;
           Updated {updatedLabel}
         </span>
       )}
-      {showLicense && licenseLabel && (
-        <span class="font-mono text-[10px] uppercase tracking-wide" title={`License: ${licenseLabel}`}>
-          {licenseLabel}
-        </span>
-      )}
       <CardIcon
         name="arrow"
         class="shrink-0 text-ink-400 transition-colors group-hover:text-ink-700 dark:text-ink-500 dark:group-hover:text-ink-100"

package/src/index.ts

@@ -29,6 +29,7 @@ import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
 import type { AstroIntegration } from "astro";
 import { loadConfig, prepareDirectory } from "@grove-dev/core";
+import { syncPackagedIcons } from "./lib/packaged-icons.js";
 
 export * from "@grove-dev/core";
 
@@ -58,7 +59,7 @@ export default function groveAstro(): AstroIntegration {
   return {
     name: "@grove-dev/astro",
     hooks: {
-      "astro:config:setup": async ({ config, updateConfig, injectScript }) => {
+      "astro:config:setup": async ({ config, updateConfig, injectScript, logger }) => {
         // Alias the components/layouts source directories so
         // consumer builds can import from
         //   @grove-dev/astro/components/ProjectCard.astro
@@ -68,10 +69,33 @@ export default function groveAstro(): AstroIntegration {
         const groveConfigPath = resolve(consumerRoot, "grove.config.ts");
         if (existsSync(groveConfigPath)) {
           await prepareDirectory(consumerRoot);
-          // Preparation is the integration's only site-level side effect.
-          // Routes belong to the consumer's `src/pages`, where they remain
-          // visible, editable, and safe from future Grove syncs.
+          // Data preparation and the icon sync below are the integration's
+          // only site-level side effects. Routes belong to the consumer's
+          // `src/pages`, where they remain visible, editable, and safe from
+          // future Grove syncs.
           await loadConfig(consumerRoot);
+
+          // `Icon.astro` resolves every mark to `/icons/**` in the
+          // consumer's `public/`, so the packaged SVGs have to land there
+          // before the build asks for them. Files the consumer edited are
+          // left alone and reported.
+          const icons = await syncPackagedIcons(fileURLToPath(config.publicDir));
+          if (icons.adopted && icons.written.length > 0) {
+            // One-time migration for a site that predates the sidecar.
+            // Say so: the overwrite is safe for the scaffold set, but a
+            // pre-sidecar hand edit would show up here, and version
+            // control is what makes it recoverable.
+            logger.info(
+              `Adopted ${icons.written.length} icon(s) into public/icons/ and recorded them in ` +
+                ".grove-icons.json. Review with `git diff public/icons` if you had edited any.",
+            );
+          }
+          if (icons.skipped.length > 0) {
+            logger.warn(
+              `Kept ${icons.skipped.length} locally modified icon(s): ${icons.skipped.join(", ")}. ` +
+                "Run `grove icons sync --force` to restore the packaged versions.",
+            );
+          }
         }
         const globalCssPath = resolve(consumerRoot, "src/styles/global.css");
         const globalCssExists = existsSync(globalCssPath);

package/src/layouts/BaseLayout.astro

@@ -62,6 +62,10 @@ interface Site {
   };
   repoUrl?: string;
   url?: string;
+  /** Header logo path under `public/` (e.g. `/logo.svg`). */
+  logo?: string;
+  /** Favicon path under `public/` (e.g. `/favicon.svg`). */
+  favicon?: string;
   analytics?: {
     googleAnalyticsId?: string;
   };
@@ -172,8 +176,14 @@ if (themeConfig) {
 }
 const themeStyle = themeStyleParts.length > 0 ? `${themeStyleParts.join("; ")};` : undefined;
 
+// `site.favicon` points at a file the consumer owns under `public/`.
+// The fallback is a generated square — tinted with the configured
+// brand color rather than a hardcoded near-black, so an unconfigured
+// site still gets a tab mark that is recognisably its own.
+const faviconFill = (site.theme?.primaryColor ?? "#18181b").trim();
 const favicon =
-  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Crect width='16' height='16' rx='3' fill='%2318181b'/%3E%3C/svg%3E";
+  site.favicon ??
+  `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Crect width='16' height='16' rx='3' fill='${encodeURIComponent(faviconFill)}'/%3E%3C/svg%3E`;
 ---
 
 <!doctype html>

package/src/layouts/Header.astro

@@ -28,6 +28,8 @@ interface Site {
   description?: string;
   repoUrl?: string;
   url?: string;
+  /** Logo path under `public/` (e.g. `/logo.svg`). */
+  logo?: string;
   stats?: {
     /** Stars on this site's own source repository. */
     repositoryStars?: number;
@@ -87,10 +89,23 @@ const starsLabel =
       href="/"
       class="inline-flex min-w-0 shrink items-center gap-2 text-[0.95rem] font-semibold tracking-tight text-ink-900 dark:text-ink-100"
     >
-      <span
-        aria-hidden="true"
-        class="inline-block h-[18px] w-[18px] rounded bg-ink-900 dark:bg-ink-100"
-      ></span>
+      {site.logo ? (
+        <img
+          src={site.logo}
+          alt=""
+          aria-hidden="true"
+          width="18"
+          height="18"
+          class="inline-block h-[18px] w-[18px] shrink-0 object-contain"
+        />
+      ) : (
+        /* No logo configured — a neutral mark is the honest default.
+           Set `site.logo` in grove.config.ts to replace it. */
+        <span
+          aria-hidden="true"
+          class="inline-block h-[18px] w-[18px] rounded bg-ink-900 dark:bg-ink-100"
+        ></span>
+      )}
       <span class="truncate">{site.name}</span>
     </a>
 

package/src/lib/icon-kinds.ts

@@ -0,0 +1,59 @@
+// GENERATED by scripts/sync-icons.mjs — do not edit by hand.
+// Run `pnpm icons:sync` to regenerate.
+/**
+ * How each packaged icon is painted.
+ *
+ * This map CLASSIFIES; it does not gate availability. A name that is
+ * absent falls through to the `<img>` + initials path, which is what
+ * keeps consumer-supplied SVGs under `public/icons/` working.
+ *
+ * Keyed by `${folder}/${resolvedName}` — the folder matters because
+ * `apple` exists under both `stacks/` and `platforms/`.
+ */
+export type IconKind = "color" | "mono";
+
+export const ICON_KINDS: Readonly<Record<string, IconKind>> = {
+  "platforms/android": "color",
+  "platforms/app": "mono",
+  "platforms/chrome": "color",
+  "platforms/desktop": "mono",
+  "platforms/embedded": "mono",
+  "platforms/ios": "mono",
+  "platforms/linux": "color",
+  "platforms/macos": "mono",
+  "platforms/ubuntu": "color",
+  "platforms/web": "mono",
+  "platforms/windows": "color",
+  "stacks/android": "color",
+  "stacks/apple": "mono",
+  "stacks/bun": "color",
+  "stacks/capacitor": "color",
+  "stacks/clojure": "color",
+  "stacks/dart": "color",
+  "stacks/deno": "mono",
+  "stacks/django": "color",
+  "stacks/docker": "color",
+  "stacks/firebase": "color",
+  "stacks/flutter": "color",
+  "stacks/go": "color",
+  "stacks/graphql": "color",
+  "stacks/ionic": "color",
+  "stacks/java": "color",
+  "stacks/javascript": "color",
+  "stacks/kotlin": "color",
+  "stacks/llm": "mono",
+  "stacks/mongodb": "color",
+  "stacks/nodejs": "color",
+  "stacks/python": "color",
+  "stacks/rag": "mono",
+  "stacks/react": "color",
+  "stacks/react-native": "color",
+  "stacks/rust": "mono",
+  "stacks/solidity": "mono",
+  "stacks/sveltekit": "color",
+  "stacks/swift": "color",
+  "stacks/tauri": "mono",
+  "stacks/tensorflow": "color",
+  "stacks/typescript": "color",
+  "stacks/vue": "color",
+};

package/src/lib/icon-registry.ts

@@ -0,0 +1,111 @@
+/**
+ * Icon registry resolution — the name → asset lookup shared by
+ * `components/Icon.astro` and the icon test suite.
+ *
+ * Kept out of the component's frontmatter so tests can assert on the
+ * exact resolution the component performs instead of reimplementing
+ * (and drifting from) the alias and folder rules.
+ */
+
+export type IconCategory = "stack" | "platform" | "brand";
+export type IconFolder = "stacks" | "platforms" | "brands";
+
+/**
+ * Normalize: lowercase + replace spaces/underscores with dashes.
+ *
+ * Deliberately NOT `@grove-dev/core`'s `slugify`, which also strips
+ * dots and other punctuation. Icon names are file names, so they must
+ * survive verbatim apart from case and separator normalization.
+ */
+export function slugifyIconName(s: string): string {
+  return s
+    .toLowerCase()
+    .trim()
+    .replace(/[\s_]+/g, "-");
+}
+
+/**
+ * Built-in id remaps. Stack-only by design: `category="platform"`
+ * resolves straight to the file name so a consumer shipping their own
+ * `public/icons/platforms/ios.svg` is never silently bypassed.
+ */
+const defaultAliases: Partial<Record<IconCategory, Record<string, string>>> = {
+  stack: {
+    ios: "apple",
+    "native-ios": "apple",
+    ipados: "apple",
+    macos: "apple",
+    "objective-c": "apple",
+    spritekit: "apple",
+    swiftui: "apple",
+    kmp: "kotlin",
+    "kotlin-multiplatform": "kotlin",
+    // Names the shipped set covers under a different file.
+    "node.js": "nodejs",
+    node: "nodejs",
+    clojurescript: "clojure",
+    svelte: "sveltekit",
+  },
+};
+
+/** Stack marks that `category="platform"` should reuse rather than duplicate. */
+const platformStackIcons = new Set(["docker"]);
+
+/** Platforms with no mark at all — always render the initials chip. */
+export const textOnlyPlatforms = new Set(["self-host", "self-hosted"]);
+
+export interface ResolvedIconAsset {
+  /** Subfolder under the icon base path. */
+  folder: IconFolder;
+  /** Alias-resolved, slugified file name (no extension). */
+  name: string;
+  /** `${folder}/${name}` — the key used by the generated kind map. */
+  key: string;
+  /** True when this name is text-only and must fall back to initials. */
+  textOnly: boolean;
+}
+
+/**
+ * Resolve a registry id to the asset it points at.
+ *
+ * Lookup order: `aliases` → the built-in stack aliases → the raw
+ * slugified name. Any name not covered by the shipped set simply
+ * resolves to `{category-folder}/{slug}`, which is what lets consumers
+ * drop their own SVGs in without touching this file.
+ */
+export function resolveIconAsset(
+  name: string,
+  category: IconCategory,
+  aliases?: Record<string, string>,
+): ResolvedIconAsset {
+  const resolved = resolveName(name, category, aliases);
+  const folder: IconFolder =
+    category === "stack" || (category === "platform" && platformStackIcons.has(resolved))
+      ? "stacks"
+      : category === "platform"
+        ? "platforms"
+        : "brands";
+
+  return {
+    folder,
+    name: resolved,
+    key: `${folder}/${resolved}`,
+    textOnly: category === "platform" && textOnlyPlatforms.has(resolved),
+  };
+}
+
+function resolveName(
+  raw: string,
+  category: IconCategory,
+  aliases?: Record<string, string>,
+): string {
+  if (!raw) return "";
+  for (const registry of [aliases, defaultAliases[category]]) {
+    if (!registry) continue;
+    const lower = raw.toLowerCase();
+    for (const [k, v] of Object.entries(registry)) {
+      if (k.toLowerCase() === lower) return slugifyIconName(v);
+    }
+  }
+  return slugifyIconName(raw);
+}

package/src/lib/index.ts

@@ -10,6 +10,7 @@
  *     `lib/search`)
  *   - compute taxonomy counts at build time (`lib/taxonomy-counts`)
  *   - pretty-print slugs and label/lens/sort/status ids (`lib/display`)
+ *   - resolve icon registry ids to asset paths (`lib/icon-registry`)
  *
  * All helpers are pure, dependency-free, and typed against
  * `@grove-dev/core` (specifically `ProjectRecord` for the index
@@ -23,3 +24,6 @@ export * from "./search.js";
 export * from "./taxonomy-counts.js";
 export * from "./display.js";
 export * from "./load-collections.js";
+export * from "./icon-registry.js";
+export * from "./icon-kinds.js";
+export * from "./packaged-icons.js";