@agentvibes/site 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Yatsyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @agentvibes/site
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Site Factory renderer: a site keeps only `site.config.ts` and `content/**/*.mdx`, and this package supplies the Next.js 16 and Fumadocs routes, layouts, header and footer, search, changelog and API pages. The command `agentvibes-site prepare` writes the generated files; run it before `next build`.
+
+MIT licence.

package/bin/agentvibes-site.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// agentvibes-site — `prepare` generates the Next app of a Site Factory site
+// from site.config.ts (run it before `next build` / `next dev`).
+import { tsImport } from "tsx/esm/api";
+
+const cli = await tsImport("../src/cli.ts", import.meta.url);
+process.exitCode = await cli.main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,90 @@
 {
   "name": "@agentvibes/site",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.10.0",
+  "description": "Site Factory renderer: a Next 16 + Fumadocs site generated from site.config.ts and MDX (`agentvibes-site prepare`).",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./proxy": {
+      "types": "./src/proxy.ts",
+      "default": "./src/proxy.ts"
+    },
+    "./client": {
+      "types": "./src/client.ts",
+      "default": "./src/client.ts"
+    },
+    "./mdx-config": {
+      "types": "./src/mdx-config.d.ts",
+      "default": "./src/mdx-config.js"
+    },
+    "./instrumentation": {
+      "types": "./src/instrumentation.ts",
+      "default": "./src/instrumentation.ts"
+    }
+  },
+  "bin": {
+    "agentvibes-site": "./bin/agentvibes-site.mjs"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "dependencies": {
+    "@agentvibes/kit": "^0.2.0",
+    "clsx": "^2.1.1",
+    "mobx": "^6.15.0",
+    "mobx-react-lite": "^4.1.1",
+    "tailwind-merge": "^3.4.0",
+    "ts-pattern": "^5.9.0",
+    "tsx": "^4.21.0",
+    "zod": "^3.25.76",
+    "@agentvibes/site-app": "0.3.4",
+    "@agentvibes/site-config": "0.5.0",
+    "@agentvibes/site-llms": "0.1.2",
+    "@agentvibes/theme-public": "0.1.4",
+    "@agentvibes/site-telemetry": "0.2.1",
+    "@agentvibes/site-mdx": "0.2.2",
+    "@agentvibes/site-seo": "0.1.1"
+  },
+  "peerDependencies": {
+    "fumadocs-core": "~16.4.9",
+    "fumadocs-mdx": "~14.2.6",
+    "fumadocs-ui": "~16.4.9",
+    "next": "^16.1.6",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.3"
+  },
+  "devDependencies": {
+    "@types/mdx": "^2.0.13",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "fumadocs-core": "^16.4.9",
+    "fumadocs-mdx": "^14.2.6",
+    "fumadocs-ui": "^16.4.9",
+    "next": "^16.1.6",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.7"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "siteFactory": {
+    "tier": "public"
+  },
+  "scripts": {
+    "check": "tsc -p tsconfig.json --noEmit && vitest run",
+    "test": "vitest run"
+  }
 }

package/src/app-mode.tsx

@@ -0,0 +1,110 @@
+/**
+ * App mode in the renderer (`app: { fullscreen, pwa }`, spec §5), on
+ * `@agentvibes/site-app`: the root viewport and shell, the manifest, the
+ * service worker route, the offline page. Without `app` every function here
+ * returns the docs behaviour.
+ */
+import {
+  appColors,
+  AppShell,
+  DOCS_VIEWPORT,
+  ICON_SET,
+  iconUrl,
+  rootViewport,
+  serviceWorkerScript,
+  shortName,
+  webManifest,
+  type AppColors
+} from "@agentvibes/site-app";
+import { OfflinePage, ServiceWorkerUpdatePrompt } from "@agentvibes/site-app/client";
+import type { Metadata, MetadataRoute, Viewport } from "next";
+import { notFound } from "next/navigation";
+import type { ReactNode } from "react";
+
+import type { SiteRuntime } from "./runtime";
+import { siteTheme } from "./theme";
+
+export class AppModeConfigError extends Error {
+  override readonly name = "AppModeConfigError";
+}
+
+function colorsOf(site: SiteRuntime): AppColors | undefined {
+  const pwa = site.config.app?.pwa;
+  return pwa === undefined ? undefined : appColors(pwa, siteTheme(site.preset).light);
+}
+
+/** The root layout's viewport: app (no zoom, `viewport-fit=cover`) when `app.fullscreen`. */
+export function siteViewport(site: SiteRuntime): Viewport {
+  return rootViewport(site.config.app, colorsOf(site)?.theme);
+}
+
+/** Docs, changelog and landing pages keep pinch zoom, also inside an app-mode site. */
+export function documentViewport(site: SiteRuntime): Viewport {
+  const theme = colorsOf(site)?.theme;
+  return theme === undefined ? DOCS_VIEWPORT : { ...DOCS_VIEWPORT, themeColor: theme };
+}
+
+/** Home-screen metadata (iOS reads `apple-mobile-web-app-*` and the touch icon, not the manifest). */
+export function appMetadata(site: SiteRuntime): Metadata {
+  const pwa = site.config.app?.pwa;
+  if (pwa === undefined) return {};
+  const apple = ICON_SET.find((spec) => spec.purpose === "apple-touch");
+  return {
+    appleWebApp: { capable: true, title: shortName(site.config.name, pwa), statusBarStyle: site.config.app?.fullscreen === true ? "black-translucent" : "default" },
+    ...(apple === undefined ? {} : { icons: { apple: iconUrl(apple) } })
+  };
+}
+
+/** Wraps every page: the fullscreen shell and the service worker prompt, as configured. */
+export function AppChrome(props: { site: SiteRuntime; children: ReactNode }) {
+  const app = props.site.config.app;
+  const prompt = app?.pwa?.offline === true ? <ServiceWorkerUpdatePrompt /> : null;
+  if (app?.fullscreen !== true) {
+    return (
+      <>
+        {props.children}
+        {prompt}
+      </>
+    );
+  }
+  return (
+    <AppShell>
+      {props.children}
+      {prompt}
+    </AppShell>
+  );
+}
+
+function requirePwa(site: SiteRuntime, what: string) {
+  const pwa = site.config.app?.pwa;
+  if (pwa === undefined) throw new AppModeConfigError(`${what} needs app.pwa in site.config`);
+  return pwa;
+}
+
+/** `app/manifest.ts` (Next serves it as `/manifest.webmanifest` and links it from every page). */
+export function createManifest(site: SiteRuntime) {
+  return function manifest(): MetadataRoute.Manifest {
+    const pwa = requirePwa(site, "the web manifest");
+    return webManifest({ name: site.config.name, description: site.config.description, pwa, colors: appColors(pwa, siteTheme(site.preset).light) });
+  };
+}
+
+/** `/sw.js`: the generated service worker, versioned by the build's release. */
+export function createServiceWorkerRoute(site: SiteRuntime) {
+  return function GET(): Response {
+    const pwa = site.config.app?.pwa;
+    if (pwa?.offline !== true) return new Response("Not found", { status: 404 });
+    return new Response(serviceWorkerScript({ release: site.generated.release, precache: pwa.precache, shellRoutes: pwa.shellRoutes }), {
+      headers: { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-cache", "service-worker-allowed": "/" }
+    });
+  };
+}
+
+/** `/~offline`: shown by the service worker for pages it never cached. */
+export function createOfflinePage(site: SiteRuntime) {
+  function Page() {
+    if (site.config.app?.pwa?.offline !== true) notFound();
+    return <OfflinePage name={site.config.name} />;
+  }
+  return { Page };
+}

package/src/catalog.ts

@@ -0,0 +1,80 @@
+/**
+ * Every page the site serves, in one list: content pages, docs pages, the
+ * JSDoc page of each npm module, the changelog. Sitemap, llms.txt, search and
+ * the Markdown route all read it, so they cannot disagree about what exists.
+ */
+import { jsdocMarkdown } from "./jsdoc";
+import { hasChangelog, hasDocs } from "./nav";
+import type { SiteRuntime, SiteSource } from "./runtime";
+
+export type CatalogPage = {
+  readonly title: string;
+  readonly description: string | undefined;
+  /** URL path, starting with "/". */
+  readonly path: string;
+  /** The llms.txt section the page is listed under. */
+  readonly section: string;
+  /** Markdown body (processed MDX, or generated text). */
+  markdown(): Promise<string>;
+};
+
+function contentPages(site: SiteRuntime, source: SiteSource, sectionOf: (slugs: readonly string[]) => string): CatalogPage[] {
+  return source.getPages().map((page) => ({
+    title: page.data.title ?? page.url,
+    description: page.data.description,
+    path: page.url,
+    section: sectionOf(page.slugs),
+    markdown: () => page.data.getText("processed")
+  }));
+}
+
+export function changelogMarkdown(site: SiteRuntime): string {
+  return site.generated.changelog.map((entry) => `## ${entry.packageName}\n\n${entry.markdown.trim()}`).join("\n\n");
+}
+
+export function catalog(site: SiteRuntime): CatalogPage[] {
+  const modules = site.config.sections.npm?.modules ?? [];
+  const moduleTitle = new Map(modules.map((mod) => [mod.id, mod.title]));
+  const pages = contentPages(site, site.pages, () => "Pages");
+  // kind "app": the home is the author's app/page.tsx, which no MDX source lists.
+  const appHome: CatalogPage[] =
+    site.config.kind === "app" && !pages.some((page) => page.path === "/")
+      ? [{ title: site.config.name, description: site.config.description, path: "/", section: "Pages", markdown: async () => site.config.description ?? "" }]
+      : [];
+  const docs = hasDocs(site.config)
+    ? contentPages(site, site.docs, (slugs) => {
+        const first = slugs[0];
+        return first === undefined ? "Docs" : (moduleTitle.get(first) ?? "Docs");
+      })
+    : [];
+  const api: CatalogPage[] = modules.map((mod) => ({
+    title: `${mod.title} API reference`,
+    description: `Exports of ${mod.npm.name}.`,
+    path: `/docs/${mod.id}/jsdoc`,
+    section: mod.title,
+    markdown: async () => jsdocMarkdown(site.generated.jsdoc.modules[mod.id]?.items ?? [])
+  }));
+  const changelog: CatalogPage[] = hasChangelog(site.config)
+    ? [{ title: "Changelog", description: `Release notes of ${site.config.name}.`, path: "/changelog", section: "Changelog", markdown: async () => changelogMarkdown(site) }]
+    : [];
+  return [...appHome, ...pages, ...docs, ...api, ...changelog];
+}
+
+export function findPage(site: SiteRuntime, path: string): CatalogPage | undefined {
+  const normalized = path === "" ? "/" : path.replace(/\/+$/, "") || "/";
+  return catalog(site).find((page) => page.path === normalized);
+}
+
+/** Sections in llms.txt order: pages, general docs, one per npm module, changelog. */
+export function catalogSections(site: SiteRuntime): Array<{ title: string; pages: CatalogPage[] }> {
+  const order: string[] = [];
+  const bySection = new Map<string, CatalogPage[]>();
+  for (const page of catalog(site)) {
+    if (!bySection.has(page.section)) {
+      order.push(page.section);
+      bySection.set(page.section, []);
+    }
+    bySection.get(page.section)?.push(page);
+  }
+  return order.map((title) => ({ title, pages: bySection.get(title) ?? [] }));
+}

package/src/cli.ts

@@ -0,0 +1,51 @@
+import { parseArgs } from "node:util";
+
+import type { OutputFlags } from "./output";
+import { prepare } from "./prepare";
+import { finishStatic } from "./prepare/finish-static";
+
+const usage = `usage:
+  agentvibes-site prepare [site-dir]                 (follows output in site.config)
+  agentvibes-site prepare [site-dir] --static [--origin <https://host>] [--base-path </x/name>]   (overrides it)
+  agentvibes-site finish-static [site-dir] [--base-path </x/name>]`;
+
+const OPTIONS = { static: { type: "boolean" }, origin: { type: "string" }, "base-path": { type: "string" } } as const;
+
+function outputFrom(flags: { static?: boolean | undefined; origin?: string | undefined; "base-path"?: string | undefined }): OutputFlags {
+  return { static: flags.static, origin: flags.origin, basePath: flags["base-path"] };
+}
+
+async function runPrepare(dir: string | undefined, output: OutputFlags): Promise<void> {
+  const result = await prepare(dir ?? process.cwd(), process.env, output);
+  for (const migration of result.migrations) console.log(`site.config migrated ${migration} (run in memory; update the file to drop this step)`);
+  const { written, unchanged, removed } = result.report;
+  console.log(`agentvibes-site prepare: ${written.length} written, ${unchanged.length} unchanged, ${removed.length} removed in ${result.siteDir}`);
+  for (const file of removed) console.log(`  removed ${file}`);
+}
+
+async function runFinish(dir: string | undefined, basePath: string): Promise<void> {
+  const report = await finishStatic(dir ?? process.cwd(), basePath);
+  console.log(`agentvibes-site finish-static: ${report.files} files, ${report.bytes} bytes, ${report.markdownTwins} Markdown twins`);
+  console.log(`  largest: ${report.largest.file} (${report.largest.bytes} bytes)`);
+  for (const redirect of report.redirects) console.log(`  redirect ${redirect.source} -> ${redirect.destination}`);
+}
+
+export async function main(argv: readonly string[]): Promise<number> {
+  try {
+    const { values, positionals } = parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true });
+    const [command, dir] = positionals;
+    if (command === "prepare") {
+      await runPrepare(dir, outputFrom(values));
+      return 0;
+    }
+    if (command === "finish-static") {
+      await runFinish(dir, values["base-path"] ?? "");
+      return 0;
+    }
+    console.error(usage);
+    return 2;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}

package/src/client.ts

@@ -0,0 +1,5 @@
+"use client";
+
+/** Client components the generated `app/error.tsx` and `app/global-error.tsx` bind. */
+export { SiteErrorBoundary } from "./components/site-error-boundary/site-error-boundary";
+export { SiteGlobalErrorBoundary } from "./components/site-error-boundary/site-global-error-boundary";

package/src/components/changelog-entry-view.tsx

@@ -0,0 +1,11 @@
+import { Markdown } from "fumadocs-core/content";
+
+/** One package's CHANGELOG.md on `/changelog`. */
+export function ChangelogEntryView(props: { packageName: string; markdown: string }) {
+  return (
+    <section className="mb-12">
+      <h2>{props.packageName}</h2>
+      <Markdown>{props.markdown}</Markdown>
+    </section>
+  );
+}

package/src/components/doctor-throw/doctor-throw.tsx

@@ -0,0 +1,15 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Throws in the browser after it mounts, so the page's error boundary
+ * (`app/error.tsx`) catches it and reports it: site doctor's client-side
+ * synthetic error (rule `errors-captured`).
+ */
+export function DoctorThrow(props: { id: string }) {
+  const [armed, setArmed] = useState(false);
+  useEffect(() => setArmed(true), []);
+  if (armed) throw new Error(`site-doctor synthetic client error ${props.id}`);
+  return <p data-av-doctor="armed">Throwing a synthetic client error…</p>;
+}

package/src/components/errors-init.tsx

@@ -0,0 +1,14 @@
+import { ErrorReporterInit } from "@agentvibes/site-telemetry/client";
+import { match } from "ts-pattern";
+
+import type { RequestContext } from "../context";
+import { telemetryTransport, type SiteRuntime } from "../runtime";
+
+/** Starts the browser error reporter, when the request's telemetry plan turns errors on. */
+export function ErrorsInit(props: { site: SiteRuntime; ctx: RequestContext }) {
+  const reporter = props.site.errors;
+  return match(props.ctx.telemetry.errors)
+    .with({ kind: "on" }, (plan) => (reporter === undefined ? null : <ErrorReporterInit config={reporter.clientConfig({ ...plan, origin: props.ctx.origin, transport: telemetryTransport(props.site) })} />))
+    .with({ kind: "off" }, () => null)
+    .exhaustive();
+}

package/src/components/hero/hero-action-link.tsx

@@ -0,0 +1,15 @@
+import { PageLink as Link } from "../page-link/page-link";
+
+export type HeroAction = { readonly label: string; readonly href: string };
+
+export function HeroActionLink(props: { action: HeroAction; primary: boolean }) {
+  return props.primary ? (
+    <Link href={props.action.href} className="rounded-md bg-fd-primary px-4 py-2 text-sm font-medium text-fd-primary-foreground no-underline">
+      {props.action.label}
+    </Link>
+  ) : (
+    <Link href={props.action.href} className="rounded-md border border-fd-border px-4 py-2 text-sm font-medium text-fd-foreground no-underline">
+      {props.action.label}
+    </Link>
+  );
+}

package/src/components/hero/hero.tsx

@@ -0,0 +1,31 @@
+import { HeroActionLink, type HeroAction } from "./hero-action-link";
+
+export type { HeroAction };
+
+export type HeroProps = {
+  readonly eyebrow?: string;
+  readonly title: string;
+  readonly tagline?: string;
+  /** A shell command shown as the install line. */
+  readonly install?: string;
+  readonly actions?: readonly HeroAction[];
+};
+
+/** The landing hero, written in `content/pages/index.mdx` as `<Hero … />`. */
+export function Hero(props: HeroProps) {
+  return (
+    <section className="not-prose border-b border-fd-border py-16">
+      {props.eyebrow === undefined ? null : <p className="mb-6 text-xs font-semibold uppercase tracking-widest text-fd-muted-foreground">{props.eyebrow}</p>}
+      <h1 className="mb-5 max-w-[18ch] text-5xl font-semibold leading-tight text-fd-foreground">{props.title}</h1>
+      {props.tagline === undefined ? null : <p className="mb-7 max-w-[60ch] text-lg text-fd-muted-foreground">{props.tagline}</p>}
+      {props.install === undefined ? null : (
+        <pre className="mb-6 inline-block rounded-md bg-fd-muted px-4 py-2.5 font-mono text-sm text-fd-foreground">{props.install}</pre>
+      )}
+      <div className="flex flex-wrap gap-3">
+        {(props.actions ?? []).map((action, index) => (
+          <HeroActionLink key={action.href} action={action} primary={index === 0} />
+        ))}
+      </div>
+    </section>
+  );
+}

package/src/components/home-shell.tsx

@@ -0,0 +1,19 @@
+import { ScrollPage } from "@agentvibes/site-app";
+import { HomeLayout } from "fumadocs-ui/layouts/home";
+import type { ReactNode } from "react";
+
+import { layoutOptions } from "../layout-options";
+import type { SiteRuntime } from "../runtime";
+import { PageFooter } from "./page-footer";
+
+/** Landing, changelog and other top-level pages: Fumadocs' home layout, then the footer (a document page, also in app mode). */
+export function HomeShell(props: { site: SiteRuntime; children: ReactNode }) {
+  return (
+    <ScrollPage>
+      <HomeLayout {...layoutOptions(props.site)}>
+        <main className="mx-auto w-full max-w-fd-container flex-1 px-6 pb-16">{props.children}</main>
+      </HomeLayout>
+      <PageFooter site={props.site} />
+    </ScrollPage>
+  );
+}

package/src/components/jsdoc-view/group-view.tsx

@@ -0,0 +1,14 @@
+import type { ApiItem } from "../../data";
+import { sectionTitle } from "../../jsdoc";
+import { ItemView } from "./item-view";
+
+export function GroupView(props: { kind: ApiItem["kind"]; items: readonly ApiItem[] }) {
+  return (
+    <section className="grid gap-4">
+      <h2 className="text-lg font-semibold">{sectionTitle(props.kind)}</h2>
+      {props.items.map((item) => (
+        <ItemView key={item.name} item={item} />
+      ))}
+    </section>
+  );
+}

package/src/components/jsdoc-view/item-view.tsx

@@ -0,0 +1,24 @@
+import type { ApiItem } from "../../data";
+import { MemberView } from "./member-view";
+
+export function ItemView(props: { item: ApiItem }) {
+  const { item } = props;
+  const members = item.members ?? [];
+  return (
+    <article id={item.name} className="rounded-xl border border-fd-border bg-fd-card p-4">
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <h3 className="m-0 text-base font-semibold">{item.name}</h3>
+        <span className="rounded-full bg-fd-muted px-2 py-0.5 text-xs uppercase tracking-wide">{item.kind}</span>
+      </div>
+      {item.description === undefined ? null : <p className="mt-2 text-sm text-fd-muted-foreground">{item.description}</p>}
+      {item.signature === undefined ? null : <pre className="mt-3 overflow-x-auto rounded-lg bg-fd-muted p-3 text-sm">{item.signature}</pre>}
+      {members.length === 0 ? null : (
+        <div className="mt-4 grid gap-3">
+          {members.map((member, index) => (
+            <MemberView key={`${member.name}-${index}`} member={member} />
+          ))}
+        </div>
+      )}
+    </article>
+  );
+}

package/src/components/jsdoc-view/jsdoc-view.tsx

@@ -0,0 +1,16 @@
+import type { ApiItem } from "../../data";
+import { groupByKind } from "../../jsdoc";
+import { GroupView } from "./group-view";
+
+/** The API reference of one npm module, from the data `prepare` extracted with the TypeScript compiler. */
+export function JsdocView(props: { items: readonly ApiItem[] }) {
+  const groups = groupByKind(props.items);
+  if (groups.length === 0) return <p>No exports yet.</p>;
+  return (
+    <div className="not-prose grid gap-10">
+      {groups.map((group) => (
+        <GroupView key={group.kind} kind={group.kind} items={group.items} />
+      ))}
+    </div>
+  );
+}

package/src/components/jsdoc-view/member-view.tsx

@@ -0,0 +1,15 @@
+import type { ApiMember } from "../../data";
+
+export function MemberView(props: { member: ApiMember }) {
+  const { member } = props;
+  return (
+    <div className="rounded-lg border border-fd-border bg-fd-background p-3">
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <h4 className="m-0 text-sm font-medium">{member.name}</h4>
+        <span className="rounded-full bg-fd-muted px-2 py-0.5 text-[10px] uppercase tracking-wide">{member.kind}</span>
+      </div>
+      {member.description === undefined ? null : <p className="mt-2 text-xs text-fd-muted-foreground">{member.description}</p>}
+      <pre className="mt-2 overflow-x-auto rounded-md bg-fd-muted p-2 text-xs">{member.signature}</pre>
+    </div>
+  );
+}

package/src/components/module-cards/module-card.tsx

@@ -0,0 +1,13 @@
+import type { NpmModule } from "@agentvibes/site-config";
+import { Card } from "fumadocs-ui/components/card";
+
+export function ModuleCard(props: { module: NpmModule }) {
+  const { module } = props;
+  return (
+    <Card title={module.title} description={module.description} href={`/docs/${module.id}`}>
+      <span className="mt-2 block font-mono text-xs text-fd-muted-foreground">
+        {module.npm.name} · {module.kind} · {module.stability}
+      </span>
+    </Card>
+  );
+}

package/src/components/module-cards/module-cards.tsx

@@ -0,0 +1,15 @@
+import type { NpmModule } from "@agentvibes/site-config";
+import { Cards } from "fumadocs-ui/components/card";
+
+import { ModuleCard } from "./module-card";
+
+/** Cards for `sections.npm.modules`, for `<ModuleCards />` in MDX. */
+export function ModuleCards(props: { modules: readonly NpmModule[] }) {
+  return (
+    <Cards>
+      {props.modules.map((module) => (
+        <ModuleCard key={module.id} module={module} />
+      ))}
+    </Cards>
+  );
+}

package/src/components/page-actions/copy-button.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import type { Resource } from "@agentvibes/kit/resource";
+import { match } from "ts-pattern";
+
+const BUTTON = "inline-flex items-center gap-1.5 rounded-md border border-fd-border bg-fd-secondary px-2.5 py-1 text-xs font-medium text-fd-secondary-foreground hover:bg-fd-accent disabled:opacity-60";
+
+/** "Copy as Markdown", rendering each state of the copy: idle, copying, copied, failed with retry. */
+export function CopyButton(props: { state: Resource<true>; onCopy: () => void; onDismiss: () => void }) {
+  return match(props.state)
+    .with({ status: "idle" }, () => (
+      <button type="button" className={BUTTON} onClick={props.onCopy}>
+        Copy as Markdown
+      </button>
+    ))
+    .with({ status: "loading" }, () => (
+      <button type="button" className={BUTTON} disabled aria-busy="true">
+        <span aria-hidden="true" className="size-3 animate-spin rounded-full border-2 border-fd-muted-foreground border-t-transparent" />
+        Copying…
+      </button>
+    ))
+    .with({ status: "ready" }, () => (
+      <button type="button" className={BUTTON} onClick={props.onCopy} data-state="copied">
+        <span aria-hidden="true">✓</span>
+        Copied
+      </button>
+    ))
+    .with({ status: "error" }, ({ error }) => (
+      <span role="alert" className="inline-flex items-center gap-2 rounded-md border border-fd-error/40 bg-fd-error/10 px-2.5 py-1 text-xs text-fd-error">
+        Copy failed: {error.message}
+        <button type="button" className="underline" onClick={props.onCopy}>
+          Retry
+        </button>
+        <button type="button" className="underline" onClick={props.onDismiss}>
+          Dismiss
+        </button>
+      </span>
+    ))
+    .exhaustive();
+}