@grove-dev/astro 0.5.0-next.2 → 0.5.0

package/src/components/SubmissionClient.astro

@@ -3,51 +3,84 @@ interface Props {
   existingSlugs: string[];
   existingFullNames: string[];
   repoUrl: string;
-  fields: { category: boolean; stack: boolean; platforms: boolean; tags: boolean };
+  fields: { category: boolean; stack: boolean; platforms: boolean; tags: boolean; license?: boolean };
   /** Taxonomy ids for client-side validation. */
   taxonomy?: {
     categoryIds?: string[];
     stackIds?: string[];
     platformIds?: string[];
   };
+  /**
+   * Optional path of a server-side proxy endpoint that wraps
+   * `api.github.com` (SSR consumers with an adapter can wire one and
+   * read a `GITHUB_TOKEN` env var to lift the rate limit). When
+   * omitted — the static-build default — the visitor's browser calls
+   * `https://api.github.com/repos/{owner}/{repo}` directly, which
+   * works on any static host but is subject to GitHub's per-IP
+   * unauthenticated limit (60 requests/hour).
+   */
+  githubProxyPath?: string;
 }
-const { existingSlugs, existingFullNames, repoUrl, fields, taxonomy } = Astro.props;
+const {
+  existingSlugs,
+  existingFullNames,
+  repoUrl,
+  fields,
+  taxonomy,
+  githubProxyPath = '',
+} = Astro.props;
 ---
 
-<script is:inline define:vars={{ existingSlugs, existingFullNames, repoUrl, fields, taxonomy }}>
-    // @ts-nocheck
-    const $ = (selector) => document.querySelector(selector);
+<script is:inline define:vars={{ existingSlugs, existingFullNames, repoUrl, fields, taxonomy, githubProxyPath }}>
+    /** @typedef {{ name: string; description: string | null; html_url: string; homepage: string | null; language: string | null; private: boolean; topics: string[] }} GitHubRepo */
+    /** @type {GitHubRepo | null} */
+    let repository = null;
+
+    const $ = /** @param {string} selector */ (selector) => /** @type {HTMLElement | null} */ (document.querySelector(selector));
+    /** @type {Record<string, HTMLInputElement | HTMLTextAreaElement | null>} */
     const inputs = {
-      repo: $("#repo-url"), name: $("#item-name"), slug: $("#item-slug"),
-      description: $("#item-description"), category: $("#item-category"),
-      stack: $("#primary-stack"), tags: $("#item-tags"),
-      website: $("#item-website"), bestFor: $("#best-for"),
+      repo: /** @type {HTMLInputElement | null} */ ($("#repo-url")),
+      name: /** @type {HTMLInputElement | null} */ ($("#item-name")),
+      slug: /** @type {HTMLInputElement | null} */ ($("#item-slug")),
+      description: /** @type {HTMLInputElement | null} */ ($("#item-description")),
+      category: /** @type {HTMLSelectElement | null} */ ($("#item-category")),
+      stack: /** @type {HTMLSelectElement | null} */ ($("#primary-stack")),
+      tags: /** @type {HTMLInputElement | null} */ ($("#item-tags")),
+      license: /** @type {HTMLSelectElement | null} */ ($("#item-license")),
+      website: /** @type {HTMLInputElement | null} */ ($("#item-website")),
+      bestFor: /** @type {HTMLTextAreaElement | null} */ ($("#best-for")),
     };
-    const fetchButton = $("#fetch-repo");
-    const preview = $("#yaml-preview");
-    const status = $("#submit-status");
-    const copyButton = $("#copy-yaml");
-    const openPrLink = $("#open-pr-link");
+    const fetchButton = /** @type {HTMLButtonElement | null} */ ($("#fetch-repo"));
+    const preview = /** @type {HTMLElement | null} */ ($("#yaml-preview"));
+    const status = /** @type {HTMLElement | null} */ ($("#submit-status"));
+    const copyButton = /** @type {HTMLButtonElement | null} */ ($("#copy-yaml"));
+    const openPrLink = /** @type {HTMLAnchorElement | null} */ ($("#open-pr-link"));
     const slugSet = new Set(existingSlugs);
     const repoSet = new Set(existingFullNames);
     const categoryIds = new Set(taxonomy?.categoryIds ?? []);
     const stackIds = new Set(taxonomy?.stackIds ?? []);
     const platformIds = new Set(taxonomy?.platformIds ?? []);
-    let repository = null;
 
-    const slugify = (value) => String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-    const parseRepo = (value) => {
-      const match = String(value).match(/github\.com\/([^/]+)\/([^/?#]+)/);
+    const slugify = /** @param {unknown} value */ (value) =>
+      String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    const parseRepo = /** @param {unknown} value */ (value) => {
+      const match = String(value ?? "").match(/github\.com\/([^/]+)\/([^/?#]+)/);
       return match ? { owner: match[1], repo: match[2].replace(/\.git$/, "") } : null;
     };
-    const quote = (value) => `"${String(value ?? "").replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-    const lines = (values, indent = 2) => values.map((value) => `${" ".repeat(indent)}- ${value}`).join("\n");
-    const selectedPlatforms = () => [...document.querySelectorAll("input[name=platform]:checked")].map((input) => input.value);
+    const quote = /** @param {unknown} value */ (value) =>
+      `"${String(value ?? "").replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    const lines = /** @param {string[]} values */ (values, indent = 2) =>
+      values.map((value) => `${" ".repeat(indent)}- ${value}`).join("\n");
+    const selectedPlatforms = () =>
+      /** @type {string[]} */ ([...document.querySelectorAll("input[name=platform]:checked")].map((input) => /** @type {HTMLInputElement} */ (input).value));
     const setStatus = (text, tone = "muted") => {
+      if (!status) return;
       status.textContent = text;
-      status.className = `mt-3 min-h-5 text-2xs ${tone === "error" ? "text-red-600 dark:text-red-400" : tone === "warn" ? "text-amber-700 dark:text-amber-400" : tone === "success" ? "text-emerald-700 dark:text-emerald-400" : "text-ink-500 dark:text-ink-400"}`;
+      // Status tokens (danger/warning/success) so the submit states use
+      // the same semantic roles as the rest of the system.
+      status.className = `mt-3 min-h-5 text-2xs ${tone === "error" ? "text-danger" : tone === "warn" ? "text-warning" : tone === "success" ? "text-success" : "text-muted-foreground"}`;
     };
-    const inferStack = (repo) => {
+    const inferStack = /** @param {GitHubRepo} repo */ (repo) => {
       const language = String(repo.language || "").toLowerCase();
       const topics = (repo.topics || []).map((topic) => String(topic).toLowerCase());
       if (topics.includes("flutter") || language === "dart") return "flutter";
@@ -58,25 +91,26 @@ const { existingSlugs, existingFullNames, repoUrl, fields, taxonomy } = Astro.pr
     };
     const generateYaml = () => {
       if (!repository) return "";
-      const parsed = parseRepo(inputs.repo.value);
+      const parsed = parseRepo(inputs.repo?.value ?? "");
       if (!parsed) return "";
-      const tags = String(inputs.tags?.value || "").split(",").map((tag) => tag.trim()).filter(Boolean);
+      const tags = String(inputs.tags?.value ?? "").split(",").map((tag) => tag.trim()).filter(Boolean);
       const platforms = selectedPlatforms();
-      const bestFor = inputs.bestFor.value.split("\n").map((item) => item.trim()).filter(Boolean);
+      const bestFor = String(inputs.bestFor?.value ?? "").split("\n").map((item) => item.trim()).filter(Boolean);
       return [
         "kind: project",
-        `slug: ${slugify(inputs.slug.value || repository.name)}`,
-        `name: ${quote(inputs.name.value)}`,
-        `description: ${quote(inputs.description.value)}`,
+        `slug: ${slugify(inputs.slug?.value ?? repository.name)}`,
+        `name: ${quote(inputs.name?.value ?? "")}`,
+        `description: ${quote(inputs.description?.value ?? "")}`,
         ...(fields.category ? [`category: ${inputs.category?.value || "uncategorized"}`] : []),
         "projectType: real-app",
         ...(fields.stack && inputs.stack?.value ? [`stack: ${quote(inputs.stack.value)}`] : []),
         ...(fields.platforms ? ["platforms:", platforms.length ? lines(platforms) : "  []"] : []),
         ...(fields.tags ? ["tags:", tags.length ? lines(tags) : "  []"] : []),
+        ...(fields.license && inputs.license?.value ? ["licenses:", lines([inputs.license.value])] : []),
         `repoUrl: ${repository.html_url}`,
         "links:",
         `  github: ${repository.html_url}`,
-        ...(inputs.website.value ? [`  website: ${inputs.website.value}`] : []),
+        ...(inputs.website?.value ? [`  website: ${inputs.website.value}`] : []),
         "bestFor:", bestFor.length ? lines(bestFor) : "  []",
         "source:",
         "  type: manual",
@@ -91,17 +125,24 @@ const { existingSlugs, existingFullNames, repoUrl, fields, taxonomy } = Astro.pr
     };
     const validationIssues = () => {
       const issues = [];
-      if (slugSet.has(slugify(inputs.slug.value))) {
+      if (inputs.slug && slugSet.has(slugify(inputs.slug.value))) {
         issues.push("A record with that slug already exists — update the existing one instead of opening a duplicate PR.");
       }
-      if (inputs.description.value.trim().length < 40) {
+      const description = String(inputs.description?.value ?? "");
+      if (description.trim().length < 40) {
         issues.push("Description must be at least 40 characters.");
       }
-      if (fields.category && (!inputs.category.value || inputs.category.value === "uncategorized" || (categoryIds.size > 0 && !categoryIds.has(inputs.category.value)))) {
-        issues.push("Choose a category from the taxonomy.");
+      if (fields.category && inputs.category) {
+        const v = inputs.category.value;
+        if (!v || v === "uncategorized" || (categoryIds.size > 0 && !categoryIds.has(v))) {
+          issues.push("Choose a category from the taxonomy.");
+        }
       }
-      if (fields.stack && (!inputs.stack.value || (stackIds.size > 0 && !stackIds.has(inputs.stack.value)))) {
-        issues.push("Choose a primary stack from the taxonomy.");
+      if (fields.stack && inputs.stack) {
+        const v = inputs.stack.value;
+        if (!v || (stackIds.size > 0 && !stackIds.has(v))) {
+          issues.push("Choose a primary stack from the taxonomy.");
+        }
       }
       if (fields.platforms && selectedPlatforms().length === 0) {
         issues.push("Select at least one platform.");
@@ -113,13 +154,8 @@ const { existingSlugs, existingFullNames, repoUrl, fields, taxonomy } = Astro.pr
     };
     const refresh = () => {
       const yaml = generateYaml();
-      preview.textContent = yaml || "Paste a GitHub URL to generate a draft.";
-      if (!yaml) {
-        openPrLink.classList.add("pointer-events-none", "opacity-50");
-        copyButton.disabled = true;
-        copyButton.classList.add("pointer-events-none", "opacity-50");
-        return;
-      }
+      if (preview) preview.textContent = yaml || "Paste a GitHub URL to generate a draft.";
+      if (!yaml || !openPrLink || !copyButton) return;
       const issues = validationIssues();
       if (issues.length > 0) {
         setStatus(issues[0], "error");
@@ -128,47 +164,88 @@ const { existingSlugs, existingFullNames, repoUrl, fields, taxonomy } = Astro.pr
         copyButton.classList.add("pointer-events-none", "opacity-50");
         return;
       }
-      const params = new URLSearchParams({ filename: `data/records/${slugify(inputs.slug.value)}.yml`, value: yaml });
+      const params = new URLSearchParams({ filename: `data/records/${slugify(inputs.slug?.value ?? "")}.yml`, value: yaml });
       openPrLink.href = `${repoUrl}/new/main?${params}`;
       openPrLink.classList.remove("pointer-events-none", "opacity-50");
       copyButton.disabled = false;
       copyButton.classList.remove("pointer-events-none", "opacity-50");
     };
 
-    fetchButton.addEventListener("click", async () => {
-      const parsed = parseRepo(inputs.repo.value);
+    fetchButton?.addEventListener("click", async () => {
+      const parsed = parseRepo(inputs.repo?.value ?? "");
       if (!parsed) return setStatus("Enter a valid GitHub repository URL.", "error");
       const fullName = `${parsed.owner}/${parsed.repo}`.toLowerCase();
       if (repoSet.has(fullName)) setStatus("This repository is already listed. The draft can update its record.", "warn");
-      fetchButton.disabled = true;
+      if (fetchButton) fetchButton.disabled = true;
       setStatus("Fetching GitHub metadata...");
       try {
-        const response = await fetch(`https://api.github.com/repos/${parsed.owner}/${parsed.repo}`, { headers: { Accept: "application/vnd.github+json" } });
-        if (response.status === 404) throw new Error("Repository not found or not public.");
-        if (response.status === 403) throw new Error("GitHub rate limit reached. Try again shortly.");
-        if (!response.ok) throw new Error(`GitHub returned ${response.status}.`);
-        repository = await response.json();
+        if (githubProxyPath) {
+          // Server-side proxy (SSR consumers) — the endpoint reads an
+          // optional `GITHUB_TOKEN` env var and forwards the request
+          // with a Bearer header (or unauthenticated, if no token).
+          const proxyUrl = `${githubProxyPath}?owner=${encodeURIComponent(parsed.owner)}&repo=${encodeURIComponent(parsed.repo)}`;
+          const response = await fetch(proxyUrl);
+          const payload = /** @type {{ ok: boolean; status?: number; message?: string; data?: GitHubRepo }} */ (await response.json());
+          if (!response.ok || !payload.ok || !payload.data) {
+            throw new Error(payload.message || `GitHub returned ${response.status}.`);
+          }
+          repository = payload.data;
+        } else {
+          // Static-build default — call api.github.com directly. The
+          // raw payload carries the same field names the form fill
+          // logic consumes (name, description, html_url, homepage,
+          // language, private, topics).
+          const response = await fetch(
+            `https://api.github.com/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}`,
+            { headers: { Accept: "application/vnd.github+json" } },
+          );
+          if (response.status === 404) {
+            throw new Error("Repository not found or not public.");
+          }
+          if (response.status === 403 || response.status === 429) {
+            throw new Error(
+              "GitHub rate limit reached (60 requests/hour per visitor). Try again later or fill the fields manually.",
+            );
+          }
+          if (!response.ok) {
+            throw new Error(`GitHub returned ${response.status}.`);
+          }
+          const data = /** @type {GitHubRepo & { topics?: string[] }} */ (await response.json());
+          repository = {
+            name: data.name,
+            description: data.description ?? null,
+            html_url: data.html_url,
+            homepage: data.homepage ?? null,
+            language: data.language ?? null,
+            private: Boolean(data.private),
+            topics: Array.isArray(data.topics) ? data.topics : [],
+          };
+        }
         if (repository.private) throw new Error("Private repositories cannot be submitted.");
-        inputs.name.value = repository.name || parsed.repo;
-        inputs.slug.value = slugify(repository.name || parsed.repo);
-        inputs.description.value = repository.description || "";
+        if (inputs.name) inputs.name.value = repository.name || parsed.repo;
+        if (inputs.slug) inputs.slug.value = slugify(repository.name || parsed.repo);
+        if (inputs.description) inputs.description.value = repository.description || "";
         if (inputs.stack) inputs.stack.value = inferStack(repository);
         if (inputs.tags) inputs.tags.value = (repository.topics || []).slice(0, 8).join(", ");
-        inputs.website.value = repository.homepage || "";
-        const duplicate = slugSet.has(inputs.slug.value);
-        setStatus(duplicate ? "That slug already exists. Choose another or update the existing record." : "Draft generated. Edit any field and the YAML will refresh.", duplicate ? "warn" : "success");
+        if (inputs.website) inputs.website.value = repository.homepage || "";
+        const duplicate = inputs.slug ? slugSet.has(inputs.slug.value) : false;
+        setStatus(
+          duplicate ? "That slug already exists. Choose another or update the existing record." : "Draft generated. Edit any field and the YAML will refresh.",
+          duplicate ? "warn" : "success",
+        );
         refresh();
       } catch (error) {
         repository = null;
-        setStatus(error.message || "Unable to fetch repository metadata.", "error");
+        setStatus(error instanceof Error ? error.message : "Unable to fetch repository metadata.", "error");
       } finally {
-        fetchButton.disabled = false;
+        if (fetchButton) fetchButton.disabled = false;
       }
     });
-    $("#submit-form").addEventListener("input", refresh);
-    copyButton.addEventListener("click", async () => {
+    $("#submit-form")?.addEventListener("input", refresh);
+    $("#submit-form")?.addEventListener("change", refresh);
+    copyButton?.addEventListener("click", async () => {
       try {
-        await navigator.clipboard.writeText(preview.textContent || "");
+        await navigator.clipboard.writeText(preview?.textContent || "");
         setStatus("Copied YAML to clipboard.", "success");
       } catch {
         setStatus("Couldn't copy automatically. Select the YAML and copy it.", "error");

package/src/components/TableOfContents.astro

@@ -6,8 +6,9 @@
  *
  * Behavior:
  *   - Mobile (<lg): rendered as a closed `<details>` dropdown.
- *   - Desktop (lg+): forced open via `lg:!open` so the nav stays
- *     visible while the user scrolls.
+ *   - Desktop (lg+): forced open by the `.grove-toc` media rule in
+ *     `styles.css` (CSS reveals the list without the `open`
+ *     attribute) so the nav stays visible while the user scrolls.
  *   - Heading IDs come from the markdown renderer; the TOC entries
  *     are pre-computed by `extractToc` and passed in.
  *
@@ -31,7 +32,7 @@ const hasItems = items.length > 1;
 ---
 
 {hasItems && (
-  <details class="grove-toc mb-8 rounded-[var(--radius-lg)] border border-ink-200 bg-background open:bg-background dark:border-ink-800 lg:!open">
+  <details class="grove-toc rounded-[var(--radius-lg)] border border-ink-200 bg-card open:bg-card dark:border-ink-800">
     <summary class="cursor-pointer list-none px-4 py-3 text-2xs font-semibold uppercase tracking-wider text-ink-500 hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100 lg:cursor-default lg:pointer-events-none">
       <span class="inline-flex items-center gap-1.5">
         <svg viewBox="0 0 16 16" width="11" height="11" aria-hidden="true" fill="currentColor" class="grove-toc-chevron transition-transform lg:hidden">
@@ -43,12 +44,23 @@ const hasItems = items.length > 1;
         </span>
       </span>
     </summary>
+    {/* Full list, no inner scroll — the TOC lives in the right rail
+        and every entry stays visible. h3 entries indent under their
+        h2 parents. */}
     <ol class="grove-toc-list mt-1 list-none border-t border-ink-200 p-2 text-sm dark:border-ink-800 lg:border-t-0 lg:p-0">
       {items.map((entry) => (
-        <li class="grove-toc-item border-b border-ink-100 last:border-b-0 dark:border-ink-800 lg:border-b-0 lg:py-0.5">
+        <li
+          class:list={[
+            "grove-toc-item border-b border-ink-100 last:border-b-0 dark:border-ink-800 lg:border-b-0 lg:py-0.5",
+            entry.depth >= 3 && "ml-4 lg:ml-3",
+          ]}
+        >
           <a
             href={`#${entry.id}`}
-            class="grove-toc-link block truncate px-3 py-2 text-ink-500 no-underline transition-colors hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100 lg:px-2 lg:py-1"
+            class:list={[
+              "grove-toc-link block truncate px-3 py-2 text-ink-500 no-underline transition-colors hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100 lg:px-2 lg:py-1",
+              entry.depth >= 3 && "text-[0.8125rem]",
+            ]}
             data-toc-link={entry.id}
           >
             {entry.text}
@@ -62,6 +74,20 @@ const hasItems = items.length > 1;
 {hasItems && (
   <script is:inline define:vars={{ tocIds: items.map((i) => i.id) }}>
     (function () {
+      // Desktop (lg+): force the details open so the nav stays visible
+      // while scrolling; the summary is pointer-events-none there. On
+      // narrow viewports restore the closed dropdown default. CSS in
+      // styles.css covers the no-JS case.
+      var toc = document.querySelector(".grove-toc");
+      if (toc) {
+        var mq = window.matchMedia("(min-width: 64rem)");
+        var syncOpen = function () { toc.open = mq.matches; };
+        if (typeof mq.addEventListener === "function") {
+          mq.addEventListener("change", syncOpen);
+        }
+        syncOpen();
+      }
+
       // Smooth scroll + history-replace on TOC link clicks.
       function onClick(e) {
         var link = e.target.closest("a[data-toc-link]");

package/src/components/WhyThisExists.astro

@@ -82,7 +82,7 @@ const items = points && points.length > 0 ? points : defaultPoints;
       aria-label="Why this directory"
     >
       {items.map((p) => (
-        <li class="rounded-[calc(var(--radius)+0.25rem)] border-0 bg-muted shadow-none transition-colors p-4">
+        <li class="rounded-[calc(var(--radius)+0.25rem)] border border-border bg-card shadow-none transition-colors p-4">
           <div
             aria-hidden="true"
             class="mb-3 flex h-8 w-8 items-center justify-center rounded-md border border-ink-200 bg-white text-ink-700 dark:border-ink-800 dark:bg-ink-950 dark:text-ink-300"

package/src/index.ts

@@ -5,7 +5,7 @@
  *  - `default` export: an Astro integration that wires the
  *    `@grove-dev/astro/components/*` and `@grove-dev/astro/layouts/*`
  *    subpath imports into Vite so consumer projects can write:
- *        import ItemCard from "@grove-dev/astro/components/ItemCard.astro";
+ *        import ProjectCard from "@grove-dev/astro/components/ProjectCard.astro";
  *    and have Vite resolve the source `.astro` file (the package's
  *    `dist/` only contains TypeScript helpers, not the components
  *    themselves).
@@ -61,7 +61,7 @@ export default function groveAstro(): AstroIntegration {
       "astro:config:setup": async ({ config, updateConfig, injectScript }) => {
         // Alias the components/layouts source directories so
         // consumer builds can import from
-        //   @grove-dev/astro/components/ItemCard.astro
+        //   @grove-dev/astro/components/ProjectCard.astro
         // without us shipping a glob-shaped `exports` map that
         // Vite/Rollup does not expand reliably.
         const consumerRoot = fileURLToPath(config.root);

package/src/layouts/BaseLayout.astro

@@ -14,10 +14,11 @@
  * GA4 can be configured once through `site.analytics.googleAnalyticsId`
  * or overridden per page with `gaId`. Omit both for privacy-first deployments.
  */
-import "../styles.css";
-import Header from "./Header.astro";
-import Footer from "./Footer.astro";
-import Seo from "./Seo.astro";
+import '../styles.css';
+import Header from './Header.astro';
+import Footer from './Footer.astro';
+import Seo from './Seo.astro';
+import { derivePrimaryPalette } from '../server/contrast';
 
 interface NavItem {
   label: string;
@@ -68,6 +69,18 @@ interface Site {
    * at generate time. Components use it to render hero counts,
    * origin card stats, and footer summary lines. */
   stats?: SiteStats;
+  /** Theme knobs from grove.config.ts — resolved into CSS custom
+   * properties on `<html>` so the package stylesheet picks them up.
+   * Values are plain strings because the prop usually arrives from a
+   * JSON import; unknown values fall back to the package defaults. */
+  theme?: {
+    primaryColor?: string;
+    /** "none" | "soft" | "round" */
+    radius?: string;
+    /** "compact" | "comfortable" | "spacious" */
+    density?: string;
+    containerWidth?: string;
+  };
   blueprintConfig?: {
     routeSlug?: string;
     labelSingular?: string;
@@ -79,7 +92,7 @@ interface Props {
   title: string;
   description: string;
   site: Site;
-  type?: "website" | "article" | "profile";
+  type?: 'website' | 'article' | 'profile';
   noindex?: boolean;
   jsonLd?: Record<string, unknown> | Record<string, unknown>[];
   /** Optional Google Analytics 4 Measurement ID (e.g. "G-XXXXXX"). */
@@ -104,16 +117,67 @@ const {
   submitLabel,
   submitHref,
 } = Astro.props;
-const directoryPath =
-  searchPath ?? `/${site.blueprintConfig?.routeSlug ?? "items"}`;
+const directoryPath = searchPath ?? `/${site.blueprintConfig?.routeSlug ?? 'items'}`;
 const effectiveGaId = gaId ?? site.analytics?.googleAnalyticsId;
 
+// ── Theme wiring ─────────────────────────────────────────────────
+// `theme.*` from grove.config.ts resolves to CSS custom properties
+// on the <html> style attribute. An attribute (not an inline
+// <style>) so the override wins over the bundled stylesheet
+// regardless of how Vite orders the CSS output.
+const RADIUS_PRESETS: Record<string, [string, string, string]> = {
+  none: ["0rem", "0rem", "0rem"],
+  soft: ["0.625rem", "0.5rem", "0.75rem"],
+  round: ["0.875rem", "0.75rem", "1rem"],
+};
+const DENSITY_SPACING: Record<string, string> = {
+  compact: "0.225rem",
+  comfortable: "0.25rem",
+  spacious: "0.28rem",
+};
+
+// Brand fill and text derive from ONE WCAG computation (contrast.ts)
+// so background and foreground can never drift apart across themes.
+
+const themeConfig = site.theme;
+const themeStyleParts: string[] = [];
+if (themeConfig) {
+  const radius = RADIUS_PRESETS[themeConfig.radius ?? "soft"];
+  if (radius && themeConfig.radius && themeConfig.radius !== "soft") {
+    themeStyleParts.push(
+      `--grove-radius: ${radius[0]}`,
+      `--grove-radius-lg: ${radius[1]}`,
+      `--grove-radius-xl: ${radius[2]}`,
+    );
+  }
+  const spacing = DENSITY_SPACING[themeConfig.density ?? "comfortable"];
+  if (spacing && themeConfig.density && themeConfig.density !== "comfortable") {
+    themeStyleParts.push(`--spacing: ${spacing}`);
+  }
+  if (themeConfig.containerWidth) {
+    themeStyleParts.push(`--grove-container: ${themeConfig.containerWidth}`);
+  }
+  const primary = themeConfig.primaryColor;
+  if (typeof primary === "string" && /^#[0-9a-fA-F]{3,8}$/.test(primary)) {
+    const palette = derivePrimaryPalette(primary);
+    if (palette) {
+      themeStyleParts.push(
+        `--grove-theme-primary: ${palette.solid}`,
+        `--grove-theme-primary-foreground: ${palette.solidForeground}`,
+        `--grove-theme-primary-dark: ${palette.dark}`,
+        `--grove-theme-primary-dark-foreground: ${palette.darkForeground}`,
+      );
+    }
+  }
+}
+const themeStyle = themeStyleParts.length > 0 ? `${themeStyleParts.join("; ")};` : undefined;
+
 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";
 ---
 
 <!doctype html>
-<html lang="en">
+<html lang="en" style={themeStyle}>
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
@@ -209,6 +273,12 @@ const favicon =
     </script>
   </head>
   <body class="min-h-screen bg-background text-foreground">
+    <a
+      href="#main"
+      class="sr-only z-50 rounded-md bg-background px-3 py-2 text-sm font-medium text-foreground outline-none ring-2 ring-ring focus:not-sr-only focus:fixed focus:left-3 focus:top-3"
+    >
+      Skip to content
+    </a>
     <slot name="header">
       <Header
         site={site}
@@ -217,7 +287,7 @@ const favicon =
       />
     </slot>
 
-    <main>
+    <main id="main">
       <slot />
     </main>
 

package/src/layouts/Header.astro

@@ -14,6 +14,7 @@
  */
 
 import ThemeToggle from "./ThemeToggle.astro";
+import { buttonClass } from "../ui/button.js";
 
 interface NavItem {
   label: string;
@@ -60,8 +61,8 @@ const defaultNavItems = site.blueprintConfig
   ? [
       { label: "Recently added", href: `${directoryPath}?sort=recently-added` },
       { label: "Trending", href: `${directoryPath}?label=hot` },
-      { label: "Categories", href: directoryPath },
-      { label: "Stacks", href: directoryPath },
+      { label: "Categories", href: "/categories" },
+      { label: "Stacks", href: "/stacks" },
       { label: "About", href: "/about" },
     ]
   : [];
@@ -128,7 +129,7 @@ const starsLabel =
       {submitHref && (
         <a
           href={submitHref}
-          class="inline-flex h-8 cursor-pointer items-center justify-center gap-1.5 rounded-[var(--radius)] border border-transparent px-3 text-sm font-medium leading-none no-underline outline-none transition-colors focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/35 border-border bg-secondary text-foreground hover:bg-accent max-sm:!hidden"
+          class={buttonClass("secondary", "sm", "max-sm:!hidden")}
         >
           <svg
             viewBox="0 0 16 16"
@@ -150,7 +151,7 @@ const starsLabel =
           rel="noopener noreferrer"
           aria-label={`${repoLabel} on GitHub${starsLabel ? ` — ${stars} stars` : ""}`}
           title={`${repoLabel} on GitHub`}
-          class="inline-flex h-8 cursor-pointer items-center justify-center gap-1.5 overflow-hidden rounded-[var(--radius)] border border-border bg-secondary p-0 text-sm font-medium leading-none text-foreground no-underline outline-none transition-colors hover:bg-accent focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/35"
+          class={buttonClass("secondary", "bare", "h-8 overflow-hidden p-0 text-sm")}
         >
           <span class="flex items-center gap-1.5 px-2.5 py-1.5 text-ink-900 dark:text-ink-100">
             <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" fill="currentColor">

package/src/layouts/SectionHeader.astro

@@ -4,11 +4,12 @@ interface Props {
   title: string;
   description?: string;
   align?: "left" | "center";
-  level?: 2 | 3;
+  /** Pass 1 when this header IS the page title (one h1 per route). */
+  level?: 1 | 2 | 3;
 }
 
 const { eyebrow, title, description, align = "left", level = 2 } = Astro.props;
-const Heading = `h${level}` as "h2" | "h3";
+const Heading = `h${level}` as "h1" | "h2" | "h3";
 ---
 
 <header