@m13v/seo-components 0.7.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m13v/seo-components",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "39 animated React components for programmatic SEO pages. Remotion video, Magic UI style animations, trust signals, JSON-LD helpers. Teal/cyan brand, light-theme only.",
   "type": "module",
   "main": "./src/index.ts",

package/src/components/HeadingAnchors.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import { useEffect } from "react";
+import { usePathname } from "next/navigation";
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+/**
+ * Walks every H2 inside the nearest <article> on mount and sets an `id`
+ * attribute derived from the heading text. On initial load, if the URL
+ * has a hash, scrolls to the matching heading once IDs are attached.
+ *
+ * This keeps the sidebar ToC clickable without requiring every page
+ * author to add id attributes manually.
+ */
+export function HeadingAnchors() {
+  const pathname = usePathname();
+
+  useEffect(() => {
+    const article = document.querySelector("article");
+    if (!article) return;
+
+    const headings = article.querySelectorAll<HTMLHeadingElement>("h2");
+    const seen = new Set<string>();
+    headings.forEach((h) => {
+      const text = (h.textContent || "").trim();
+      if (!text) return;
+      const base = slugify(text);
+      if (!base) return;
+      let id = base;
+      let i = 2;
+      while (seen.has(id)) {
+        id = `${base}-${i++}`;
+      }
+      seen.add(id);
+      h.id = id;
+      h.style.scrollMarginTop = "16px";
+    });
+
+    if (window.location.hash) {
+      const target = document.getElementById(
+        decodeURIComponent(window.location.hash.slice(1)),
+      );
+      if (target) {
+        requestAnimationFrame(() => {
+          target.scrollIntoView({ behavior: "smooth", block: "start" });
+        });
+      }
+    }
+  }, [pathname]);
+
+  return null;
+}

package/src/components/SitemapSidebar.tsx

@@ -0,0 +1,353 @@
+"use client";
+
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { usePathname } from "next/navigation";
+
+interface PageSection {
+  id: string;
+  title: string;
+}
+
+interface PageEntry {
+  href: string;
+  title: string;
+  description: string;
+  datePublished?: string;
+  sections: PageSection[];
+  category: string;
+}
+
+export interface SitemapSidebarProps {
+  /** All pages to show in the sidebar (from walkPages on the server). */
+  pages: PageEntry[];
+  /** Brand name shown in the header and footer. */
+  brandName: string;
+  /** Optional custom logo element. Falls back to brandName text + accent dot. */
+  brandLogo?: React.ReactNode;
+  /** Link for the brand logo / "Back to ..." link. Default: "/" */
+  homeHref?: string;
+  /** Custom category labels. Keys are path segments, values are display names.
+   *  Built-in defaults: t -> "Guides", blog -> "Blog", compare -> "Comparisons", etc. */
+  categoryLabels?: Record<string, string>;
+}
+
+const DEFAULT_LABELS: Record<string, string> = {
+  t: "Guides",
+  compare: "Comparisons",
+  blog: "Blog",
+  "use-case": "Use Cases",
+  automate: "Automations",
+  alternative: "Alternatives",
+};
+
+function getCategoryLabel(
+  category: string,
+  custom?: Record<string, string>,
+): string {
+  if (custom?.[category]) return custom[category];
+  if (DEFAULT_LABELS[category]) return DEFAULT_LABELS[category];
+  return category
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+function groupPages(pages: PageEntry[]): Map<string, PageEntry[]> {
+  const groups = new Map<string, PageEntry[]>();
+  for (const page of pages) {
+    const cat = page.category || "pages";
+    if (!groups.has(cat)) groups.set(cat, []);
+    groups.get(cat)!.push(page);
+  }
+  return groups;
+}
+
+export function SitemapSidebar({
+  pages,
+  brandName,
+  brandLogo,
+  homeHref = "/",
+  categoryLabels,
+}: SitemapSidebarProps) {
+  const pathname = usePathname();
+  const [query, setQuery] = useState("");
+  const [mobileOpen, setMobileOpen] = useState(false);
+  const [activeSection, setActiveSection] = useState<string | null>(null);
+  const activeRef = useRef<HTMLAnchorElement | null>(null);
+  const navRef = useRef<HTMLElement | null>(null);
+
+  const filtered = query
+    ? pages.filter(
+        (p) =>
+          p.title.toLowerCase().includes(query.toLowerCase()) ||
+          p.description.toLowerCase().includes(query.toLowerCase()),
+      )
+    : pages;
+
+  const groups = groupPages(filtered);
+
+  const scrollActiveIntoView = () => {
+    const active = activeRef.current;
+    const nav = navRef.current;
+    if (!active || !nav) return;
+    const activeRect = active.getBoundingClientRect();
+    const navRect = nav.getBoundingClientRect();
+    const relativeTop = activeRect.top - navRect.top + nav.scrollTop;
+    nav.scrollTop = Math.max(0, relativeTop - 24);
+  };
+
+  useLayoutEffect(() => {
+    scrollActiveIntoView();
+    const raf = requestAnimationFrame(scrollActiveIntoView);
+    return () => cancelAnimationFrame(raf);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pathname]);
+
+  // Track which H2 section is currently in view.
+  useEffect(() => {
+    const article = document.querySelector("article");
+    if (!article) return;
+
+    const headings = Array.from(
+      article.querySelectorAll<HTMLHeadingElement>("h2[id]"),
+    );
+    if (headings.length === 0) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const visible = entries
+          .filter((e) => e.isIntersecting)
+          .sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
+        if (visible.length > 0) {
+          setActiveSection(visible[0].target.id);
+        }
+      },
+      { rootMargin: "-20% 0px -70% 0px", threshold: 0 },
+    );
+
+    headings.forEach((h) => observer.observe(h));
+    return () => observer.disconnect();
+  }, [pathname]);
+
+  const handleSectionClick = (
+    e: React.MouseEvent<HTMLAnchorElement>,
+    sectionId: string,
+  ) => {
+    e.preventDefault();
+    const el = document.getElementById(sectionId);
+    if (el) {
+      el.scrollIntoView({ behavior: "smooth", block: "start" });
+      if (typeof window !== "undefined") {
+        history.replaceState(null, "", `#${sectionId}`);
+      }
+      setActiveSection(sectionId);
+      setMobileOpen(false);
+    }
+  };
+
+  return (
+    <>
+      {/* Mobile toggle */}
+      <button
+        onClick={() => setMobileOpen(!mobileOpen)}
+        className="lg:hidden fixed bottom-4 left-4 z-50 text-white p-3 rounded-full shadow-lg transition-colors"
+        style={{
+          backgroundColor: "var(--seo-accent, #14b8a6)",
+        }}
+        aria-label="Toggle site navigation"
+      >
+        <svg
+          width="20"
+          height="20"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          {mobileOpen ? (
+            <>
+              <line x1="18" y1="6" x2="6" y2="18" />
+              <line x1="6" y1="6" x2="18" y2="18" />
+            </>
+          ) : (
+            <>
+              <line x1="3" y1="12" x2="21" y2="12" />
+              <line x1="3" y1="6" x2="21" y2="6" />
+              <line x1="3" y1="18" x2="21" y2="18" />
+            </>
+          )}
+        </svg>
+      </button>
+
+      {/* Mobile backdrop */}
+      {mobileOpen && (
+        <div
+          className="lg:hidden fixed inset-0 z-40 bg-black/30 backdrop-blur-sm"
+          onClick={() => setMobileOpen(false)}
+        />
+      )}
+
+      {/* Sidebar */}
+      <aside
+        className={`
+          fixed lg:sticky top-0 left-0 z-40 h-screen
+          w-72 bg-white border-r border-zinc-200
+          flex flex-col
+          transition-transform duration-200 ease-out
+          lg:translate-x-0
+          ${mobileOpen ? "translate-x-0" : "-translate-x-full"}
+        `}
+      >
+        {/* Header */}
+        <div className="p-4 border-b border-zinc-100">
+          <a href={homeHref} className="flex items-baseline gap-0 mb-4">
+            {brandLogo ?? (
+              <>
+                <span className="font-mono font-bold text-lg tracking-tight text-zinc-900">
+                  {brandName}
+                </span>
+                <span
+                  className="w-1.5 h-1.5 rounded-full ml-0.5 mb-0.5 inline-block"
+                  style={{ backgroundColor: "var(--seo-accent, #14b8a6)" }}
+                />
+              </>
+            )}
+          </a>
+          <div className="relative">
+            <svg
+              className="absolute left-2.5 top-1/2 -translate-y-1/2 text-zinc-400"
+              width="14"
+              height="14"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            >
+              <circle cx="11" cy="11" r="8" />
+              <line x1="21" y1="21" x2="16.65" y2="16.65" />
+            </svg>
+            <input
+              type="text"
+              placeholder="Search pages..."
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              className="w-full pl-8 pr-3 py-2 text-sm border border-zinc-200 rounded-lg bg-zinc-50 placeholder:text-zinc-400 focus:outline-none focus:ring-2 focus:border-transparent transition"
+              style={
+                {
+                  "--tw-ring-color":
+                    "color-mix(in srgb, var(--seo-accent, #14b8a6) 20%, transparent)",
+                } as React.CSSProperties
+              }
+            />
+          </div>
+        </div>
+
+        {/* Page list */}
+        <nav ref={navRef} className="flex-1 overflow-y-auto p-3">
+          {filtered.length === 0 && (
+            <p className="text-sm text-zinc-400 px-3 py-4">No pages found</p>
+          )}
+
+          {Array.from(groups.entries()).map(([category, categoryPages]) => (
+            <div key={category} className="mb-4">
+              {/* Category header (only show if more than one category) */}
+              {groups.size > 1 && (
+                <div className="px-3 py-1.5 text-xs font-semibold text-zinc-400 uppercase tracking-wider">
+                  {getCategoryLabel(category, categoryLabels)}
+                </div>
+              )}
+
+              {categoryPages.map((page) => {
+                const isActive = pathname === page.href;
+                return (
+                  <div key={page.href} className="mb-0.5">
+                    <a
+                      ref={isActive ? activeRef : null}
+                      href={page.href}
+                      onClick={() => setMobileOpen(false)}
+                      className={`block px-3 py-2.5 rounded-lg transition-colors ${
+                        isActive
+                          ? "text-zinc-900 font-medium"
+                          : "text-zinc-600 hover:bg-zinc-50 hover:text-zinc-900"
+                      }`}
+                      style={
+                        isActive
+                          ? {
+                              backgroundColor:
+                                "color-mix(in srgb, var(--seo-accent, #14b8a6) 10%, transparent)",
+                              color: "var(--seo-accent-dark, #0d9488)",
+                            }
+                          : undefined
+                      }
+                    >
+                      <span className="text-sm leading-snug line-clamp-2">
+                        {page.title}
+                      </span>
+                      {page.datePublished && (
+                        <span className="text-[11px] text-zinc-400 mt-0.5 block">
+                          {page.datePublished}
+                        </span>
+                      )}
+                    </a>
+
+                    {/* Subsections for the active page */}
+                    {isActive && page.sections.length > 0 && (
+                      <ul className="mt-1 mb-2 ml-3 border-l border-zinc-200 space-y-0.5">
+                        {page.sections.map((section) => {
+                          const isSectionActive =
+                            activeSection === section.id;
+                          return (
+                            <li key={section.id}>
+                              <a
+                                href={`#${section.id}`}
+                                onClick={(e) =>
+                                  handleSectionClick(e, section.id)
+                                }
+                                className={`block pl-3 pr-2 py-1.5 -ml-px border-l-2 text-[13px] leading-snug transition-colors ${
+                                  isSectionActive
+                                    ? "font-medium"
+                                    : "border-transparent text-zinc-500 hover:text-zinc-900 hover:border-zinc-300"
+                                }`}
+                                style={
+                                  isSectionActive
+                                    ? {
+                                        borderColor:
+                                          "var(--seo-accent, #14b8a6)",
+                                        color:
+                                          "var(--seo-accent-dark, #0d9488)",
+                                      }
+                                    : undefined
+                                }
+                              >
+                                {section.title}
+                              </a>
+                            </li>
+                          );
+                        })}
+                      </ul>
+                    )}
+                  </div>
+                );
+              })}
+            </div>
+          ))}
+        </nav>
+
+        {/* Footer */}
+        <div className="p-4 border-t border-zinc-100">
+          <a
+            href={homeHref}
+            className="text-sm font-medium transition-colors"
+            style={{ color: "var(--seo-accent, #14b8a6)" }}
+          >
+            &larr; Back to {brandName}
+          </a>
+        </div>
+      </aside>
+    </>
+  );
+}

package/src/index.ts

@@ -54,12 +54,17 @@ export { MotionSequence } from "./components/MotionSequence";
 export { RemotionClip, ConceptReveal } from "./components/RemotionClip";
 export { LottiePlayer } from "./components/LottiePlayer";
 
+// Sitemap sidebar + heading anchors
+export { SitemapSidebar } from "./components/SitemapSidebar";
+export type { SitemapSidebarProps } from "./components/SitemapSidebar";
+export { HeadingAnchors } from "./components/HeadingAnchors";
+
 // Guide chat (AI page assistant) — client-safe
 export { GuideChatPanel } from "./components/GuideChatPanel";
 export type { GuideChatPanelProps } from "./components/GuideChatPanel";
 
 // Server utilities: import from "@seo/components/server" instead
-// (createGuideChatHandler, logAiUsage, discoverGuides, etc.)
+// (walkPages, createGuideChatHandler, logAiUsage, discoverGuides, etc.)
 
 // Magic UI style components
 export { Marquee } from "./components/Marquee";

package/src/lib/discover-guides.ts

@@ -1,16 +1,12 @@
-import fs from "node:fs";
 import path from "node:path";
-
-const TITLE_RE = /const\s+TITLE\s*=\s*"([^"]+)"/;
-const DESC_RE = /const\s+DESCRIPTION\s*=\s*"([^"]+)"/;
-const DATE_RE = /const\s+DATE_PUBLISHED\s*=\s*"([^"]+)"/;
-const H2_RE = /<h2\b[^>]*>([\s\S]*?)<\/h2>/g;
+import { walkPages, type PageEntry } from "./walk-pages";
 
 export interface GuideEntry {
   slug: string;
   title: string;
   description: string;
   datePublished: string;
+  href: string;
   sections: { id: string; title: string }[];
   hasFaq: boolean;
 }
@@ -18,55 +14,34 @@ export interface GuideEntry {
 let cachedDir: string | null = null;
 let cachedGuides: GuideEntry[] | null = null;
 
+/**
+ * Legacy helper that discovers guides under a specific content directory.
+ * Internally delegates to walkPages() then filters to the relevant path prefix.
+ *
+ * For new integrations, prefer walkPages() directly.
+ */
 export function discoverGuides(contentDir?: string): GuideEntry[] {
   const dir = contentDir ?? path.join(process.cwd(), "src/app/(content)/t");
 
   if (cachedDir === dir && cachedGuides) return cachedGuides;
 
-  if (!fs.existsSync(dir)) return [];
-
-  const slugs = fs
-    .readdirSync(dir, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && !d.name.startsWith("["))
-    .map((d) => d.name);
-
-  const guides: GuideEntry[] = [];
-  for (const slug of slugs) {
-    const pagePath = path.join(dir, slug, "page.tsx");
-    let src: string;
-    try {
-      src = fs.readFileSync(pagePath, "utf-8");
-    } catch {
-      continue;
-    }
+  // Determine which URL prefix these pages live under by
+  // finding the path segments after src/app (skipping route groups).
+  const appDir = path.join(process.cwd(), "src/app");
+  const allPages = walkPages({ appDir });
 
-    const title = src.match(TITLE_RE)?.[1] ?? "";
-    const description = src.match(DESC_RE)?.[1] ?? "";
-    const datePublished = src.match(DATE_RE)?.[1] ?? "";
-    if (!title) continue;
+  // Figure out the href prefix from contentDir.
+  // e.g. "src/app/(content)/t" -> "/t", "src/app/t" -> "/t"
+  const relative = path.relative(appDir, dir);
+  const segments = relative
+    .split(path.sep)
+    .filter((s) => !s.startsWith("(") || !s.endsWith(")"));
+  const hrefPrefix = "/" + segments.join("/");
 
-    const sections: { id: string; title: string }[] = [];
-    let m: RegExpExecArray | null;
-    while ((m = H2_RE.exec(src)) !== null) {
-      const raw = m[1].replace(/<[^>]+>/g, "").trim();
-      if (raw) {
-        const id = raw
-          .toLowerCase()
-          .replace(/[^a-z0-9]+/g, "-")
-          .replace(/^-|-$/g, "");
-        sections.push({ id, title: raw });
-      }
-    }
-
-    guides.push({
-      slug,
-      title,
-      description,
-      datePublished,
-      sections,
-      hasFaq: /<FaqSection\b/.test(src),
-    });
-  }
+  const guides: GuideEntry[] = allPages
+    .filter((p) => p.href.startsWith(hrefPrefix + "/") || p.href === hrefPrefix)
+    .filter((p) => p.href !== hrefPrefix) // exclude the index page
+    .map(pageToGuide);
 
   guides.sort(
     (a, b) =>
@@ -78,3 +53,19 @@ export function discoverGuides(contentDir?: string): GuideEntry[] {
   cachedGuides = guides;
   return guides;
 }
+
+function pageToGuide(p: PageEntry): GuideEntry {
+  const parts = p.href.split("/");
+  const slug = parts[parts.length - 1] || "";
+  return {
+    slug,
+    title: p.title,
+    description: p.description,
+    datePublished: p.datePublished ?? "",
+    href: p.href,
+    sections: p.sections,
+    hasFaq: p.sections.some(
+      (s) => s.id === "frequently-asked-questions",
+    ),
+  };
+}

package/src/lib/slugify.ts

@@ -0,0 +1,7 @@
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}

package/src/lib/walk-pages.ts

@@ -0,0 +1,244 @@
+import fs from "node:fs";
+import path from "node:path";
+import { slugify } from "./slugify";
+
+export interface PageSection {
+  id: string;
+  title: string;
+}
+
+export interface PageEntry {
+  href: string;
+  title: string;
+  description: string;
+  datePublished?: string;
+  sections: PageSection[];
+  category: string;
+}
+
+export interface WalkPagesOptions {
+  /** Absolute path to src/app directory. Defaults to `process.cwd()/src/app`. */
+  appDir?: string;
+  /** Filter out specific path segments (e.g. ["checkout", "trial-required"]). */
+  excludePaths?: string[];
+  /** If true, include the home page (href "/"). Default: false. */
+  includeHome?: boolean;
+}
+
+// Metadata patterns: `const TITLE = "..."` style
+const CONST_TITLE_RE = /const\s+TITLE\s*=\s*["'`](.+?)["'`]/;
+const CONST_DESC_RE = /const\s+DESCRIPTION\s*=\s*\n?\s*["'`](.+?)["'`]/;
+const CONST_DATE_RE = /const\s+DATE_PUBLISHED\s*=\s*["'`](.+?)["'`]/;
+
+// Metadata patterns: `export const metadata = { title: "..." }` style
+const META_TITLE_RE = /title:\s*["'`](.+?)["'`]/;
+const META_DESC_RE = /description:\s*["'`](.+?)["'`]/;
+
+const H2_RE = /<h2\b[^>]*>([\s\S]*?)<\/h2>/g;
+const FAQ_SECTION_RE = /<FaqSection\b/;
+
+const ENTITY_MAP: Record<string, string> = {
+  "&ldquo;": "\u201c",
+  "&rdquo;": "\u201d",
+  "&lsquo;": "\u2018",
+  "&rsquo;": "\u2019",
+  "&apos;": "'",
+  "&quot;": '"',
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&nbsp;": " ",
+  "&mdash;": ",",
+  "&ndash;": ",",
+  "&hellip;": "...",
+};
+
+function decodeEntities(s: string): string {
+  return s
+    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n, 10)))
+    .replace(
+      /&#x([0-9a-f]+);/gi,
+      (_, n) => String.fromCharCode(parseInt(n, 16)),
+    )
+    .replace(/&[a-z]+;/gi, (m) => ENTITY_MAP[m.toLowerCase()] ?? m);
+}
+
+function slugToTitle(slug: string): string {
+  return slug
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+function extractSections(src: string): PageSection[] {
+  const seen = new Set<string>();
+  const out: PageSection[] = [];
+  let m: RegExpExecArray | null;
+  H2_RE.lastIndex = 0;
+  while ((m = H2_RE.exec(src)) !== null) {
+    const raw = m[1];
+    const text = decodeEntities(
+      raw
+        .replace(/\{[^}]*\}/g, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/\s+/g, " "),
+    ).trim();
+    if (!text) continue;
+    const base = slugify(text);
+    if (!base) continue;
+    let id = base;
+    let i = 2;
+    while (seen.has(id)) {
+      id = `${base}-${i++}`;
+    }
+    seen.add(id);
+    out.push({ id, title: text });
+  }
+  if (FAQ_SECTION_RE.test(src)) {
+    const faqTitle = "Frequently asked questions";
+    const faqId = slugify(faqTitle);
+    if (!seen.has(faqId)) {
+      out.push({ id: faqId, title: faqTitle });
+    }
+  }
+  return out;
+}
+
+function extractMetadata(src: string, fallbackSlug: string) {
+  // Try const TITLE first, fall back to metadata.title
+  const title =
+    src.match(CONST_TITLE_RE)?.[1] ??
+    src.match(META_TITLE_RE)?.[1] ??
+    slugToTitle(fallbackSlug);
+  const description =
+    src.match(CONST_DESC_RE)?.[1] ?? src.match(META_DESC_RE)?.[1] ?? "";
+  const datePublished = src.match(CONST_DATE_RE)?.[1];
+
+  return {
+    title: decodeEntities(title),
+    description: decodeEntities(description),
+    datePublished,
+  };
+}
+
+/**
+ * Recursively discovers all page.tsx files under a Next.js app directory.
+ * Same logic as the sitemap.ts walkPages() that already exists on every site,
+ * but enriched with title, description, sections, and category.
+ *
+ * Import from "@seo/components/server".
+ */
+export function walkPages(opts?: WalkPagesOptions): PageEntry[] {
+  const appDir =
+    opts?.appDir ?? path.join(process.cwd(), "src/app");
+  const excludeSet = new Set(opts?.excludePaths ?? []);
+
+  const pages: PageEntry[] = [];
+
+  function walk(dir: string, urlSegments: string[]) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name === "page.tsx") {
+        const href =
+          urlSegments.length === 0 ? "/" : "/" + urlSegments.join("/");
+
+        // Skip home page unless requested
+        if (href === "/" && !opts?.includeHome) continue;
+
+        const filePath = path.join(dir, entry.name);
+        let src: string;
+        try {
+          src = fs.readFileSync(filePath, "utf-8");
+        } catch {
+          continue;
+        }
+
+        const lastSegment = urlSegments[urlSegments.length - 1] ?? "";
+        const meta = extractMetadata(src, lastSegment);
+        const sections = extractSections(src);
+        const category = urlSegments[0] ?? "";
+
+        pages.push({
+          href,
+          title: meta.title,
+          description: meta.description,
+          datePublished: meta.datePublished,
+          sections,
+          category,
+        });
+        continue;
+      }
+
+      if (!entry.isDirectory()) continue;
+
+      const name = entry.name;
+      if (name.startsWith("_")) continue;
+      if (name === "api") continue;
+      if (name.startsWith("[") && name.endsWith("]")) continue;
+      if (excludeSet.has(name)) continue;
+
+      const isRouteGroup = name.startsWith("(") && name.endsWith(")");
+      const nextSegments = isRouteGroup
+        ? urlSegments
+        : [...urlSegments, name];
+
+      walk(path.join(dir, name), nextSegments);
+    }
+  }
+
+  walk(appDir, []);
+
+  // Sort: pages with dates descending, then alphabetically by title
+  pages.sort(
+    (a, b) =>
+      (b.datePublished ?? "").localeCompare(a.datePublished ?? "") ||
+      a.title.localeCompare(b.title),
+  );
+
+  return pages;
+}
+
+/**
+ * Groups pages by their category (first URL segment).
+ * Returns a Map where keys are category names and values are page arrays.
+ * Categories are auto-labeled from the path segment (e.g. "use-case" becomes "Use Case").
+ */
+export function groupByCategory(
+  pages: PageEntry[],
+): Map<string, PageEntry[]> {
+  const groups = new Map<string, PageEntry[]>();
+  for (const page of pages) {
+    const cat = page.category || "pages";
+    if (!groups.has(cat)) groups.set(cat, []);
+    groups.get(cat)!.push(page);
+  }
+  return groups;
+}
+
+/**
+ * Converts a category slug to a display label.
+ * "t" -> "Guides", "use-case" -> "Use Cases", "compare" -> "Comparisons", etc.
+ */
+export function categoryLabel(category: string): string {
+  const labels: Record<string, string> = {
+    t: "Guides",
+    compare: "Comparisons",
+    blog: "Blog",
+    "use-case": "Use Cases",
+    automate: "Automations",
+    alternative: "Alternatives",
+  };
+  return (
+    labels[category] ??
+    category
+      .split("-")
+      .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+      .join(" ")
+  );
+}

package/src/server.ts

@@ -1,6 +1,11 @@
-// Server-side utilities for guide chat, token accounting, and content discovery.
+// Server-side utilities for page discovery, guide chat, token accounting.
 // Import from "@seo/components/server" in API routes and server components only.
 
+export { walkPages, groupByCategory, categoryLabel } from "./lib/walk-pages";
+export type { PageEntry, PageSection, WalkPagesOptions } from "./lib/walk-pages";
+
+export { slugify } from "./lib/slugify";
+
 export { createGuideChatHandler } from "./lib/guide-chat-route";
 export type { GuideChatConfig } from "./lib/guide-chat-route";