@grove-dev/astro 0.3.4 → 0.4.1

package/dist/lib/index.d.ts

@@ -23,4 +23,5 @@ export * from "./search.js";
 export * from "./scores.js";
 export * from "./taxonomy-counts.js";
 export * from "./display.js";
+export * from "./load-collections.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC"}

package/dist/lib/index.js

@@ -23,4 +23,5 @@ export * from "./search.js";
 export * from "./scores.js";
 export * from "./taxonomy-counts.js";
 export * from "./display.js";
+export * from "./load-collections.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC"}

package/dist/lib/load-collections.d.ts

@@ -0,0 +1,12 @@
+import type { Collection } from "@grove-dev/core";
+/**
+ * Load all `Collection` YAML files from `<cwd>/data/collections/*.yml`.
+ *
+ * Returns an empty array if the directory does not exist, so callers can
+ * safely render an empty/loading state without having to guard each
+ * invocation site. Parse errors and other unexpected failures are NOT
+ * swallowed — they surface so real problems (malformed YAML, permission
+ * errors, etc.) are visible instead of silently producing empty output.
+ */
+export declare function loadCollections(cwd: string): Promise<Collection[]>;
+//# sourceMappingURL=load-collections.d.ts.map

package/dist/lib/load-collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-collections.d.ts","sourceRoot":"","sources":["../../src/lib/load-collections.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAkBxE"}

package/dist/lib/load-collections.js

@@ -0,0 +1,34 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+/**
+ * Load all `Collection` YAML files from `<cwd>/data/collections/*.yml`.
+ *
+ * Returns an empty array if the directory does not exist, so callers can
+ * safely render an empty/loading state without having to guard each
+ * invocation site. Parse errors and other unexpected failures are NOT
+ * swallowed — they surface so real problems (malformed YAML, permission
+ * errors, etc.) are visible instead of silently producing empty output.
+ */
+export async function loadCollections(cwd) {
+    const dir = resolve(cwd, "data/collections");
+    let files;
+    try {
+        files = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const f of files.filter((f) => f.endsWith(".yml"))) {
+        const raw = parseYaml(await readFile(join(dir, f), "utf8"));
+        if (!raw || typeof raw !== "object") {
+            throw new Error(`Invalid collection YAML: ${f}`);
+        }
+        out.push(raw);
+    }
+    return out;
+}
+//# sourceMappingURL=load-collections.js.map

package/dist/lib/load-collections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-collections.js","sourceRoot":"","sources":["../../src/lib/load-collections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAG1C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW;IAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;IAC7C,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAChE,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QACxD,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC5D,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,EAAE,CAAC,CAAC;QACnD,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,GAAiB,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grove-dev/astro",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "type": "module",
   "description": "Composable Astro UI, data adapters, and integration for Grove directories.",
   "license": "MIT",
@@ -54,7 +54,8 @@
     "astro": "^7.1.3",
     "marked": "^18.0.0",
     "sanitize-html": "^2.17.5",
-    "@grove-dev/core": "0.3.4"
+    "yaml": "^2.9.0",
+    "@grove-dev/core": "0.4.1"
   },
   "peerDependencies": {
     "astro": "^6.0.0 || ^7.0.0"

package/src/components/CollectionIndex.astro

@@ -0,0 +1,107 @@
+---
+/**
+ * CollectionIndex — renders a grid of every collection defined in
+ * `data/collections/*.yml`. Each card links to the collection's
+ * detail page and shows the entry count.
+ *
+ * Consumes a `CollectionIndexModel` produced by
+ * `getCollectionIndexModel`. Pass `limit` (e.g. 3) for a teaser-style
+ * subset; the framework also re-exports this component as
+ * `CollectionTeaser` for the homepage use case.
+ *
+ * API parity with `RecordSection`:
+ *  - `id`, `eyebrow`, `title`, `description`
+ *  - `viewAllHref`, `viewAllLabel` — header CTA
+ *  - `emptyLabel` — copy when there are no collections
+ *  - `<slot name="header-actions">` — custom buttons in header
+ *  - `class` — extra class on the outer <section>
+ */
+import Container from "../layouts/Container.astro";
+import SectionHeader from "../layouts/SectionHeader.astro";
+import type { CollectionIndexModel } from "../server/collections.js";
+
+interface Props {
+  model: CollectionIndexModel;
+  id?: string;
+  eyebrow?: string;
+  title?: string;
+  description?: string;
+  /** Header "View all" link. Hides when not provided. */
+  viewAllHref?: string;
+  viewAllLabel?: string;
+  emptyLabel?: string;
+  /** Cap the number of cards rendered. Omit for "all". */
+  limit?: number;
+  class?: string;
+}
+
+const {
+  model,
+  id,
+  eyebrow = "Collections",
+  title = "Collections",
+  description = "Curated and generated directories of related items.",
+  viewAllHref,
+  viewAllLabel = "View all",
+  emptyLabel = "No collections yet.",
+  limit,
+  class: className = "",
+} = Astro.props;
+
+const cards = typeof limit === "number" ? model.collections.slice(0, limit) : model.collections;
+const headerActions = Astro.slots.has("header-actions");
+---
+
+<section id={id} class={`py-12 sm:py-16 ${className}`}>
+  <Container>
+    <div class="mb-6 flex flex-wrap items-end justify-between gap-3">
+      <SectionHeader eyebrow={eyebrow} title={title} description={description} />
+      {(viewAllHref || headerActions) && (
+        <div class="flex shrink-0 items-center gap-2 pb-2">
+          {viewAllHref && (
+            <a
+              href={viewAllHref}
+              class="text-2xs font-medium text-ink-500 transition-colors hover:text-ink-900 sm:inline dark:text-ink-400 dark:hover:text-ink-100"
+            >
+              {viewAllLabel} →
+            </a>
+          )}
+          <slot name="header-actions" />
+        </div>
+      )}
+    </div>
+
+    {cards.length === 0 ? (
+      <p class="rounded-md border border-dashed border-ink-200 bg-white p-6 text-sm text-ink-500 dark:border-ink-800 dark:bg-ink-950 dark:text-ink-400">
+        {emptyLabel}
+      </p>
+    ) : (
+      <ul class="m-0 grid list-none grid-cols-1 gap-3 p-0 sm:grid-cols-2 lg:grid-cols-3">
+        {cards.map((c) => (
+          <li class="m-0 p-0">
+            <a
+              href={c.url}
+              data-event="collection_card_click"
+              data-event-source="collection_index"
+              data-event-item={c.slug}
+              class="flex h-full flex-col gap-2 rounded-md border border-ink-200 bg-white p-5 transition-colors hover:border-ink-400 dark:border-ink-800 dark:bg-ink-950 dark:hover:border-ink-600"
+            >
+              <span class="text-2xs font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">
+                {c.kind === "curated" ? "Curated" : "Generated"}
+              </span>
+              <span class="text-[1.0625rem] font-semibold tracking-tight text-ink-900 dark:text-ink-100">
+                {c.title}
+              </span>
+              <span class="text-[0.875rem] text-ink-500 dark:text-ink-400">
+                {c.description}
+              </span>
+              <span class="mt-auto pt-2 text-2xs font-medium text-ink-500 dark:text-ink-400">
+                {c.count} {c.count === 1 ? "item" : "items"} →
+              </span>
+            </a>
+          </li>
+        ))}
+      </ul>
+    )}
+  </Container>
+</section>

package/src/components/CollectionPage.astro

@@ -0,0 +1,105 @@
+---
+/**
+ * CollectionPage — renders a single curated/generated collection.
+ *
+ * Consumes a `CollectionPageModel` produced by `getCollectionPageModel`.
+ * Renders the header via `SectionHeader` (framework consistency),
+ * the matched entries via `CollectionRow`, and a related-collections
+ * section.
+ *
+ * Generic: no blueprint-specific copy. Consumers can override
+ * `eyebrow`, `title`, `description`; the `<slot name="intro">` is
+ * the natural place for editorial intros (markdown rendered with
+ * the consumer's content pipeline). `emptyLabel` matches
+ * `RecordSection`'s API for empty-state copy.
+ */
+import CollectionRow from "./CollectionRow.astro";
+import Container from "../layouts/Container.astro";
+import SectionHeader from "../layouts/SectionHeader.astro";
+import type { CollectionPageModel } from "../server/collections.js";
+
+interface Props {
+  model: CollectionPageModel;
+  /** Override the eyebrow text (default: derived from collection kind). */
+  eyebrow?: string;
+  /** Override the title (default: collection.title). */
+  title?: string;
+  /** Override the description (default: collection.description). */
+  description?: string;
+  /** Default copy when the collection has no matching entries. */
+  emptyLabel?: string;
+  /** Section id (deep link + stable key). */
+  id?: string;
+  class?: string;
+}
+
+const {
+  model,
+  eyebrow,
+  title,
+  description,
+  emptyLabel = "This collection is currently empty.",
+  id,
+  class: className = "",
+} = Astro.props;
+
+const finalTitle = title ?? model.collection.title;
+const finalDescription = description ?? model.collection.description;
+const finalEyebrow = eyebrow ?? (model.collection.kind === "curated" ? "Curated collection" : "Generated collection");
+---
+
+<section id={id} class={`py-12 sm:py-16 ${className}`}>
+  <Container>
+    <SectionHeader eyebrow={finalEyebrow} title={finalTitle} description={finalDescription} />
+
+    {model.collection.selectionNote && (
+      <p class="m-0 mb-6 max-w-[64ch] text-[0.875rem] font-medium text-ink-700 dark:text-ink-300">
+        <span class="text-2xs font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">Selection criteria · </span>
+        {model.collection.selectionNote}
+      </p>
+    )}
+
+    <slot name="intro" />
+
+    <p class="m-0 mb-4 text-2xs font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">
+      {model.total} {model.total === 1 ? "item" : "items"}
+    </p>
+
+    {model.isEmpty ? (
+      <p class="rounded-md border border-dashed border-ink-200 bg-white p-6 text-sm text-ink-500 dark:border-ink-800 dark:bg-ink-950 dark:text-ink-400">
+        {emptyLabel}
+      </p>
+    ) : (
+      <ul class="m-0 flex list-none flex-col gap-3 p-0">
+        {model.entries.map((entry, i) => (
+          <li class="m-0 p-0">
+            <CollectionRow entry={entry} eager={i < 2} />
+          </li>
+        ))}
+      </ul>
+    )}
+
+    {model.related.length > 0 && (
+      <section class="mt-12 border-t border-ink-200 pt-8 dark:border-ink-800">
+        <SectionHeader
+          eyebrow="Related"
+          title="Related collections"
+          description="Other curated groupings of related items."
+          level={3}
+        />
+        <ul class="m-0 grid list-none grid-cols-1 gap-2 p-0 sm:grid-cols-2 lg:grid-cols-4">
+          {model.related.map((r) => (
+            <li class="m-0 p-0">
+              <a
+                href={r.url}
+                class="group flex h-full flex-col gap-1 rounded-md border border-ink-200 bg-white px-3 py-2.5 no-underline transition-colors hover:border-ink-400 dark:border-ink-800 dark:bg-ink-950 dark:hover:border-ink-600"
+              >
+                <span class="text-sm font-medium text-ink-900 group-hover:underline dark:text-ink-100">{r.title}</span>
+              </a>
+            </li>
+          ))}
+        </ul>
+      </section>
+    )}
+  </Container>
+</section>

package/src/components/CollectionRow.astro

@@ -0,0 +1,246 @@
+---
+/**
+ * CollectionRow — card-shaped row for a single entry inside a
+ * curated/generated collection.
+ *
+ * Mirrors `ItemCard`'s visual treatment so a collection page sitting
+ * next to the directory index reads as the same site. The component
+ * consumes the lightweight `CollectionEntry` shape directly — the
+ * existing `IndexRow` is too tightly coupled to `IndexRecord`
+ * (which carries `kind`, `repoUrl`, `github`, `bestFor` etc.) to
+ * accept a `CollectionEntry` cleanly.
+ *
+ * API parity with `ItemCard`:
+ *  - `entry` — the collection entry (slug, title, description, …)
+ *  - `href` — full detail URL; wins over `routeSlug`
+ *  - `routeSlug` — blueprint slug (e.g. "projects"); details derived
+ *    as `/${routeSlug}/${slug}` when `href` is not provided
+ *  - `showChips` — render platform + stack chip row (default true)
+ *  - `showMeta` — render stars/updated/license metadata row (default true)
+ *  - `showLabel` — render the curated/category label (default true)
+ *  - `class` — extra class on the outer <article>
+ *  - `eager` — bypass lazy loading for above-the-fold avatars (first 1-2)
+ *
+ * Footer links:
+ *  - "View repo" — when `entry.repoHref` is set
+ *  - "Visit site" — when `entry.homepageHref` is set
+ *  - "Details →" — always rendered (links to the consumer's detail page)
+ *
+ * Analytics: emits `data-event="collection_item_click"` and
+ * `data-event-source="collection_row"` so sites wire one handler
+ * in BaseLayout.
+ */
+import type { CollectionEntry } from "@grove-dev/core";
+import { formatRelative, formatStars, statusDisplay, getOwnerAndRepoFromRepoUrl, getOwnerAvatarUrl } from "@grove-dev/astro";
+import StackPlatformChips from "./StackPlatformChips.astro";
+
+interface Props {
+  entry: CollectionEntry;
+  /** Full detail-page URL. Wins over `routeSlug`. */
+  href?: string;
+  /** Blueprint route slug; detail URL = `/${routeSlug}/${slug}`. */
+  routeSlug?: string;
+  showChips?: boolean;
+  showMeta?: boolean;
+  showLabel?: boolean;
+  eager?: boolean;
+  class?: string;
+}
+
+const {
+  entry,
+  href: hrefProp,
+  routeSlug,
+  showChips = true,
+  showMeta = true,
+  showLabel = true,
+  eager = false,
+  class: className = "",
+} = Astro.props;
+
+const slug = entry.slug;
+const base = (routeSlug ?? "").replace(/^\/+|\/+$/g, "");
+const detailHref =
+  typeof hrefProp === "string" && hrefProp.length > 0
+    ? hrefProp
+    : entry.url || (base ? `/${base}/${slug}` : `/${slug}`);
+
+const title = entry.title;
+const initials = title
+  .split(/\s+/)
+  .map((w) => w[0])
+  .filter(Boolean)
+  .slice(0, 2)
+  .join("")
+  .toUpperCase();
+
+// Derive a logo URL from the entry's `repoHref` when present;
+// otherwise fall back to the detail URL. Detail URL is the
+// consumer's page, not necessarily a GitHub owner — so the
+// initials placeholder is the safe default when nothing matches.
+const repoHref = entry.repoHref;
+const { owner } = getOwnerAndRepoFromRepoUrl(repoHref ?? "");
+const avatar = owner ? getOwnerAvatarUrl(owner, 80) : undefined;
+
+const stack = entry.stack ? [entry.stack] : [];
+const platform = entry.platform?.slice(0, 4) ?? [];
+const platformOverflow = (entry.platform?.length ?? 0) - platform.length;
+
+const stars = entry.stars;
+const starsLabel = formatStars(stars);
+const updatedAt = entry.pushedAt;
+const updatedLabel = formatRelative(updatedAt);
+const license = entry.license ?? null;
+const status = entry.status;
+const statusText = status ? statusDisplay(status as Parameters<typeof statusDisplay>[0]) : "";
+const category = entry.categories?.[0];
+const curated = Boolean(entry.curationScore || (entry.activityScore && entry.activityScore > 0.5));
+
+const homepageHref = entry.homepageHref;
+const showViewRepo = typeof repoHref === "string" && repoHref.length > 0;
+const showVisitSite = typeof homepageHref === "string" && homepageHref.length > 0;
+---
+
+<article
+  data-event="collection_item_click"
+  data-event-source="collection_row"
+  data-event-item={slug}
+  class={`rounded-[calc(var(--radius)+0.25rem)] border-0 bg-muted shadow-none transition-colors hover:bg-secondary group relative flex h-full flex-col gap-3 p-4 ${className}`}
+>
+  <header class="flex items-start gap-3">
+    {avatar ? (
+      <img
+        src={avatar}
+        alt={`${title} avatar`}
+        width="40"
+        height="40"
+        loading={eager ? "eager" : "lazy"}
+        fetchpriority={eager ? "high" : undefined}
+        decoding="async"
+        class="h-10 w-10 shrink-0 rounded-md border border-ink-200 bg-white object-cover dark:border-ink-800 dark:bg-ink-900"
+      />
+    ) : (
+      <span
+        aria-hidden="true"
+        class="flex h-10 w-10 shrink-0 items-center justify-center rounded-md border border-ink-200 bg-ink-50 text-2xs font-semibold text-ink-700 dark:border-ink-800 dark:bg-ink-900/60 dark:text-ink-300"
+      >
+        {initials}
+      </span>
+    )}
+    <div class="flex min-w-0 flex-1 flex-col gap-0.5">
+      <h3 class="m-0 truncate text-[0.9375rem] font-semibold tracking-tight text-ink-900 group-hover:underline dark:text-ink-100">
+        <a href={detailHref} class="inline-flex min-h-6 min-w-6 items-center text-inherit no-underline">
+          {title}
+        </a>
+      </h3>
+      {showLabel && (
+        <span class="truncate text-2xs text-ink-500 dark:text-ink-400">
+          {category}
+          {status && (
+            <>
+              <span class="mx-1 text-ink-300 dark:text-ink-700">·</span>
+              <span class="text-ink-500 dark:text-ink-400">{statusText}</span>
+            </>
+          )}
+        </span>
+      )}
+    </div>
+    {curated && showLabel && (
+      <span
+        class="inline-flex shrink-0 items-center gap-1 text-[10px] font-medium uppercase tracking-wider text-emerald-700 dark:text-emerald-400"
+        title="Has curation or activity score"
+      >
+        <svg viewBox="0 0 16 16" width="10" height="10" aria-hidden="true" fill="currentColor">
+          <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0Zm3.41 5.09a.75.75 0 0 0-1.06 0L6.75 8.69 5.65 7.59a.75.75 0 1 0-1.06 1.06l1.65 1.65a.75.75 0 0 0 1.06 0l4.11-4.11a.75.75 0 0 0 0-1.06Z" />
+        </svg>
+        curated
+      </span>
+    )}
+  </header>
+
+  {entry.description && (
+    <p class="m-0 line-clamp-2 text-[0.8125rem] leading-relaxed text-ink-500 dark:text-ink-400">
+      {entry.description}
+    </p>
+  )}
+
+  {/* Stack + platform rendered as 2 distinct labelled rows so the
+      primary/secondary hierarchy is unambiguous. Stack is the more
+      identifying signal for an item (it's the main technology) and
+      gets a filled pill; platform is secondary and gets an outlined
+      pill. Shared with `IndexRow` / `ItemCard` so the pattern is
+      identical across all card-shaped components. */}
+  <StackPlatformChips
+    show={showChips}
+    stack={stack[0]}
+    platform={platform}
+  />
+
+  {showMeta && (
+    <div class="flex flex-wrap items-center gap-x-3 gap-y-1 text-2xs text-ink-500 dark:text-ink-400">
+      {starsLabel !== null && (
+        <span class="inline-flex items-center gap-1" title={`${stars ?? 0} stars`}>
+          <svg viewBox="0 0 16 16" width="11" height="11" aria-hidden="true" fill="currentColor" class="text-amber-500">
+            <path d="M8 .25a.75.75 0 0 1 .673.418l1.882 3.815 4.21.612a.75.75 0 0 1 .416 1.279l-3.046 2.97.719 4.192a.751.751 0 0 1-1.088.791L8 12.347l-3.766 1.98a.75.75 0 0 1-1.088-.79l.72-4.194L.818 6.374a.75.75 0 0 1 .416-1.28l4.21-.611L7.327.668A.75.75 0 0 1 8 .25Z" />
+          </svg>
+          <span class="font-mono">{starsLabel}</span>
+        </span>
+      )}
+      {updatedAt && (
+        <span class="inline-flex items-center gap-1" title={`Last updated ${updatedAt}`}>
+          <svg viewBox="0 0 16 16" width="11" height="11" aria-hidden="true" fill="currentColor" class="text-ink-400">
+            <path d="M8 2a6 6 0 1 0 0 12A6 6 0 0 0 8 2Zm0 1.5a4.5 4.5 0 1 1 0 9 4.5 4.5 0 0 1 0-9Zm-.5 1.5a.5.5 0 0 0-1 0v3.25c0 .15.07.29.18.39l1.95 1.65a.5.5 0 0 0 .66-.76L7.5 7.55V5Z" />
+          </svg>
+          <span class="font-mono">Updated {updatedLabel}</span>
+        </span>
+      )}
+      {license && (
+        <span class="inline-flex items-center gap-1" title={`License: ${license}`}>
+          <span class="font-mono uppercase tracking-wide text-[10px]">{license}</span>
+        </span>
+      )}
+    </div>
+  )}
+
+  {/* Footer: source links (View repo / Visit site) + Details. */}
+  <footer class="mt-1 flex items-center justify-between gap-3 border-t border-ink-100 pt-2 text-2xs dark:border-ink-900">
+    <div class="flex min-w-0 items-center gap-3">
+      {showViewRepo && (
+        <a
+          href={repoHref}
+          target="_blank"
+          rel="noopener noreferrer"
+          data-event="external_repo_click"
+          data-event-source="collection_row_view_repo"
+          data-event-item={slug}
+          class="inline-flex items-center gap-1 font-medium text-ink-700 transition-colors hover:text-ink-900 dark:text-ink-300 dark:hover:text-ink-100"
+        >
+          View repo
+          <svg viewBox="0 0 16 16" width="10" height="10" aria-hidden="true" fill="currentColor">
+            <path d="M3.75 2A1.75 1.75 0 0 0 2 3.75v8.5C2 13.216 2.784 14 3.75 14h8.5A1.75 1.75 0 0 0 14 12.25v-3.5a.75.75 0 0 0-1.5 0v3.5a.25.25 0 0 1-.25.25h-8.5a.25.25 0 0 1-.25-.25v-8.5a.25.25 0 0 1 .25-.25h3.5a.75.75 0 0 0 0-1.5h-3.5Z" />
+            <path d="M10 0a.75.75 0 0 0-.75.75v.75h-3a.75.75 0 0 0 0 1.5h3v.75A.75.75 0 0 0 10.75 4.5h2.5A.75.75 0 0 0 14 3.75v-2.5A.75.75 0 0 0 13.25.5H10Z" />
+          </svg>
+        </a>
+      )}
+      {showVisitSite && (
+        <a
+          href={homepageHref}
+          target="_blank"
+          rel="noopener noreferrer"
+          data-event="external_link_click"
+          data-event-source="collection_row_visit_site"
+          data-event-item={slug}
+          class="inline-flex items-center gap-1 font-medium text-ink-500 transition-colors hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100"
+        >
+          Visit site →
+        </a>
+      )}
+    </div>
+    <a
+      href={detailHref}
+      class="inline-flex shrink-0 items-center gap-1 font-medium text-ink-500 transition-colors hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100"
+    >
+      Details →
+    </a>
+  </footer>
+</article>

package/src/components/CollectionTeaser.astro

@@ -0,0 +1,43 @@
+---
+/**
+ * CollectionTeaser — homepage-friendly subset of `CollectionIndex`.
+ *
+ * Thin wrapper that defaults `limit` to 3 and sets homepage-friendly
+ * "View all collections" link + copy. For custom card counts or
+ * different copy, use `CollectionIndex` directly with explicit
+ * `limit` and `viewAllHref` props.
+ */
+import CollectionIndex from "./CollectionIndex.astro";
+import type { CollectionIndexModel } from "../server/collections.js";
+
+interface Props {
+  model: CollectionIndexModel;
+  title?: string;
+  description?: string;
+  viewAllHref?: string;
+  viewAllLabel?: string;
+  /** Cap the number of cards rendered. Default: 3. */
+  limit?: number;
+  class?: string;
+}
+
+const {
+  model,
+  title = "Featured collections",
+  description = "Hand-picked and auto-generated groupings of related items.",
+  viewAllHref = "/collections/",
+  viewAllLabel = "View all collections",
+  limit = 3,
+  class: className,
+} = Astro.props;
+---
+
+<CollectionIndex
+  model={model}
+  title={title}
+  description={description}
+  viewAllHref={viewAllHref}
+  viewAllLabel={viewAllLabel}
+  limit={limit}
+  class={className}
+/>

package/src/components/CurationGrid.astro

@@ -27,9 +27,9 @@ const columns = [
   >
     {columns.map((column) => (
       <div class="rounded-[calc(var(--radius)+0.25rem)] border-0 bg-muted shadow-none transition-colors p-5">
-        <h3 class="m-0 text-sm font-semibold uppercase tracking-wider text-ink-500 dark:text-ink-400">
+        <h2 class="m-0 text-sm font-semibold uppercase tracking-wider text-ink-500 dark:text-ink-400">
           {column.title}
-        </h3>
+        </h2>
         <ul class="mt-3 mb-0 flex list-disc flex-col gap-1.5 pl-5">
           {column.items.map((item) => (
             <li class="text-sm text-ink-700 dark:text-ink-200">{item}</li>

package/src/components/GroveDocumentHead.astro

@@ -0,0 +1,28 @@
+---
+import type { PageDocument } from "@grove-dev/core";
+interface Props {
+  document: PageDocument;
+}
+const { document: doc } = Astro.props;
+---
+<title>{doc.metadata.title}</title>
+<meta name="description" content={doc.metadata.description} />
+<meta name="robots" content={doc.metadata.robots} />
+<link rel="canonical" href={doc.identity.canonical.toString()} />
+{doc.identity.hreflang?.map((lang) => (
+  <link rel="alternate" hreflang={lang} href={doc.identity.canonical.toString()} />
+))}
+<meta property="og:title" content={doc.metadata.openGraph.title} />
+<meta property="og:description" content={doc.metadata.openGraph.description} />
+<meta property="og:url" content={doc.metadata.openGraph.url} />
+<meta property="og:image" content={doc.metadata.openGraph.image} />
+<meta property="og:type" content={doc.metadata.openGraph.type} />
+{doc.metadata.openGraph.siteName && (
+  <meta property="og:site_name" content={doc.metadata.openGraph.siteName} />
+)}
+<meta name="twitter:card" content={doc.metadata.twitter.card} />
+{doc.metadata.twitter.site && <meta name="twitter:site" content={doc.metadata.twitter.site} />}
+{doc.metadata.twitter.creator && <meta name="twitter:creator" content={doc.metadata.twitter.creator} />}
+{doc.structuredData.map((node) => (
+  <script type="application/ld+json" set:html={JSON.stringify(node)} />
+))}

package/src/components/Hero.astro

@@ -230,7 +230,6 @@ const trustStats: { value: string; label: string }[] = [
       {quickFilters.length > 0 && (
         <p
           class="mt-2 text-2xs text-ink-500 dark:text-ink-400 m-0"
-          aria-hidden="true"
         >
           Try{" "}
           {quickFilters.map((f, i) => (