@agentvibes/site 0.0.0-stage → 0.10.0

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

@@ -0,0 +1,53 @@
+"use client";
+
+/**
+ * The page action menu: copy the page as Markdown, view the Markdown, open
+ * it in Claude. Copying is async (fetch + clipboard), so it renders all four
+ * states of a Resource.
+ */
+import { Resource } from "@agentvibes/kit/resource";
+import { useCallback, useState } from "react";
+
+import { CopyButton } from "./copy-button";
+
+export type PageActionsProps = {
+  /** Same-origin path of the page's Markdown, e.g. `/docs/init.md`. */
+  readonly markdownPath: string;
+  /** Absolute URL of the Markdown on the host that served this page. */
+  readonly markdownUrl: string;
+};
+
+async function copyMarkdown(path: string): Promise<void> {
+  const response = await fetch(path, { headers: { Accept: "text/markdown" } });
+  if (!response.ok) throw new Error(`GET ${path} answered ${response.status}`);
+  await navigator.clipboard.writeText(await response.text());
+}
+
+function claudeUrl(markdownUrl: string): string {
+  return `https://claude.ai/new?q=${encodeURIComponent(`Read ${markdownUrl} and answer my questions about it.`)}`;
+}
+
+const LINK = "inline-flex items-center rounded-md px-2.5 py-1 text-xs font-medium text-fd-muted-foreground hover:text-fd-foreground";
+
+export function PageActions(props: PageActionsProps) {
+  const [state, setState] = useState<Resource<true>>(Resource.idle());
+  const onCopy = useCallback(() => {
+    setState(Resource.loading());
+    copyMarkdown(props.markdownPath).then(
+      () => setState(Resource.ready(true)),
+      (error: unknown) => setState(Resource.error(error instanceof Error ? error : new Error(String(error))))
+    );
+  }, [props.markdownPath]);
+  const onDismiss = useCallback(() => setState(Resource.idle()), []);
+  return (
+    <div className="not-prose mb-6 flex flex-wrap items-center gap-2" data-page-actions="">
+      <CopyButton state={state} onCopy={onCopy} onDismiss={onDismiss} />
+      <a className={LINK} href={props.markdownPath}>
+        View as Markdown
+      </a>
+      <a className={LINK} href={claudeUrl(props.markdownUrl)} target="_blank" rel="noreferrer">
+        Open in Claude
+      </a>
+    </div>
+  );
+}

package/src/components/page-footer.tsx

@@ -0,0 +1,20 @@
+import { requestContext } from "../context";
+import { footerColumns, telemetryDashboards } from "../nav";
+import type { SiteRuntime } from "../runtime";
+import { SiteFooter } from "./site-footer/site-footer";
+
+/** The footer for this request: the Internal column (preset links, dashboards) only off prod, llms.txt only when indexable. */
+export async function PageFooter(props: { site: SiteRuntime }) {
+  const { site } = props;
+  if (site.chrome?.footer !== undefined) return <>{site.chrome.footer}</>;
+  const ctx = await requestContext(site);
+  const internal = ctx.environment === "prod" ? [] : [...(site.preset?.links?.internal ?? []), ...telemetryDashboards(site.telemetryKeys)];
+  return (
+    <SiteFooter
+      name={site.config.name}
+      description={site.config.description}
+      release={site.generated.release}
+      columns={footerColumns({ config: site.config, llms: ctx.decision.kind === "index", internal })}
+    />
+  );
+}

package/src/components/page-link/page-link.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import NextLink from "next/link";
+import type { ComponentProps } from "react";
+
+/** The props Fumadocs renders its framework link with. */
+type PageLinkProps = ComponentProps<"a"> & { prefetch?: boolean };
+
+const STATIC_BUILD = process.env.NEXT_PUBLIC_SITE_STATIC === "1";
+
+/**
+ * `next/link`, without prefetch in a static build. A static host answers each prefetch as one more
+ * request, and on a host that counts requests a page view should not fetch pages nobody opened.
+ */
+export function PageLink({ href = "#", ...rest }: PageLinkProps) {
+  // Same anchor props; next/link only spells its optional handlers without `undefined`, which it accepts at run time.
+  const props = { ...rest, href } as ComponentProps<typeof NextLink>;
+  return STATIC_BUILD ? <NextLink {...props} prefetch={false} /> : <NextLink {...props} />;
+}

package/src/components/site-error-boundary/error-panel.tsx

@@ -0,0 +1,16 @@
+export type BoundaryProps = { error: Error & { digest?: string }; reset: () => void };
+
+/** The fallback both error boundaries render: what happened, and a retry. */
+export function ErrorPanel(props: BoundaryProps) {
+  return (
+    <div role="alert" className="mx-auto my-16 max-w-xl rounded-lg border border-fd-error/40 bg-fd-error/10 p-6 text-fd-foreground">
+      <p className="mb-2 font-semibold">This page failed to render.</p>
+      <p className="mb-4 text-sm text-fd-muted-foreground">
+        The error was reported{props.error.digest === undefined ? "" : ` (digest ${props.error.digest})`}.
+      </p>
+      <button type="button" className="rounded-md border border-fd-border bg-fd-secondary px-3 py-1.5 text-sm" onClick={props.reset}>
+        Try again
+      </button>
+    </div>
+  );
+}

package/src/components/site-error-boundary/site-error-boundary.tsx

@@ -0,0 +1,12 @@
+"use client";
+
+import { reportError } from "@agentvibes/site-telemetry/client";
+import { useEffect } from "react";
+
+import { ErrorPanel, type BoundaryProps } from "./error-panel";
+
+/** `app/error.tsx`: reports the error to the error reporter, offers a retry. */
+export function SiteErrorBoundary(props: BoundaryProps) {
+  useEffect(() => reportError(props.error), [props.error]);
+  return <ErrorPanel {...props} />;
+}

package/src/components/site-error-boundary/site-global-error-boundary.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import { reportError } from "@agentvibes/site-telemetry/client";
+import { useEffect } from "react";
+
+import { ErrorPanel, type BoundaryProps } from "./error-panel";
+
+/** `app/global-error.tsx`: same as SiteErrorBoundary, for errors in the root layout. It renders its own `<html>`, so it takes the site's `lang`. */
+export function SiteGlobalErrorBoundary(props: BoundaryProps & { readonly lang?: string }) {
+  const { lang = "en", ...boundary } = props;
+  useEffect(() => reportError(boundary.error), [boundary.error]);
+  return (
+    <html lang={lang}>
+      <body>
+        <ErrorPanel {...boundary} />
+      </body>
+    </html>
+  );
+}

package/src/components/site-footer/footer-column-view.tsx

@@ -0,0 +1,15 @@
+import type { FooterColumn } from "../../nav";
+import { FooterLink } from "./footer-link";
+
+export function FooterColumnView(props: { column: FooterColumn }) {
+  return (
+    <div>
+      <p className="mb-3 text-xs font-semibold uppercase tracking-wide text-fd-muted-foreground">{props.column.title}</p>
+      <ul className="flex flex-col gap-2">
+        {props.column.links.map((link) => (
+          <FooterLink key={link.href} link={link} />
+        ))}
+      </ul>
+    </div>
+  );
+}

package/src/components/site-footer/footer-link.tsx

@@ -0,0 +1,20 @@
+import { PageLink as Link } from "../page-link/page-link";
+
+import type { SiteLink } from "../../nav";
+
+export function FooterLink(props: { link: SiteLink }) {
+  const { link } = props;
+  return (
+    <li>
+      {link.external ? (
+        <a href={link.href} className="text-sm text-fd-muted-foreground hover:text-fd-foreground" rel="noreferrer">
+          {link.label}
+        </a>
+      ) : (
+        <Link href={link.href} className="text-sm text-fd-muted-foreground hover:text-fd-foreground">
+          {link.label}
+        </Link>
+      )}
+    </li>
+  );
+}

package/src/components/site-footer/site-footer.tsx

@@ -0,0 +1,32 @@
+import type { FooterColumn } from "../../nav";
+import { FooterColumnView } from "./footer-column-view";
+
+export type SiteFooterProps = {
+  readonly name: string;
+  readonly description: string | undefined;
+  readonly columns: readonly FooterColumn[];
+  readonly release: string;
+};
+
+/** The site footer: name, description, link columns from site.config, build release. */
+export function SiteFooter(props: SiteFooterProps) {
+  return (
+    <footer className="border-t border-fd-border bg-fd-card text-fd-card-foreground" data-site-footer="">
+      <div className="mx-auto grid max-w-fd-container gap-8 px-6 py-10 md:grid-cols-[1.4fr_repeat(4,1fr)]">
+        <div>
+          <p className="mb-2 font-semibold">{props.name}</p>
+          {props.description === undefined ? null : <p className="max-w-[32ch] text-sm text-fd-muted-foreground">{props.description}</p>}
+        </div>
+        {props.columns.map((column) => (
+          <FooterColumnView key={column.title} column={column} />
+        ))}
+      </div>
+      <div className="mx-auto flex max-w-fd-container justify-between px-6 pb-6 text-xs text-fd-muted-foreground">
+        <span>
+          © {new Date().getFullYear()} {props.name}
+        </span>
+        <span className="font-mono">release {props.release.slice(0, 12)}</span>
+      </div>
+    </footer>
+  );
+}

package/src/components/site-video/site-video.tsx

@@ -0,0 +1,25 @@
+import { Video, type VideoSources } from "@agentvibes/site-mdx";
+
+import type { MediaData } from "../../data";
+
+export class SiteMediaError extends Error {
+  override readonly name = "SiteMediaError";
+}
+
+export type SiteVideoProps = Partial<VideoSources> & {
+  /** A video of `sections.media.videos`: `deploy` for `deploy.mp4`, `deploy.webm`, `deploy.png`, `deploy.vtt`. */
+  readonly name?: string;
+};
+
+/** `<Video name="deploy" label="…" />` in MDX: the files come from the media prepare copied; props override them. */
+export function SiteVideo(props: SiteVideoProps & { videos: MediaData["videos"] }) {
+  const { videos, name, ...rest } = props;
+  const entry = name === undefined ? undefined : videos[name];
+  if (name !== undefined && entry === undefined) {
+    throw new SiteMediaError(`<Video name="${name}">: no such video in sections.media.videos (found: ${Object.keys(videos).join(", ") || "none"})`);
+  }
+  const label = rest.label ?? name;
+  const mp4 = rest.mp4 ?? entry?.mp4;
+  if (label === undefined || mp4 === undefined) throw new SiteMediaError("<Video>: pass name (a video of sections.media.videos), or label and mp4");
+  return <Video {...entry} {...rest} label={label} mp4={mp4} />;
+}

package/src/components/telemetry-scripts.tsx

@@ -0,0 +1,18 @@
+import { match } from "ts-pattern";
+
+import type { RequestContext } from "../context";
+import { telemetryTransport, type SiteRuntime } from "../runtime";
+
+/** The analytics script in `<head>`, when the request's telemetry plan turns analytics on. */
+export function TelemetryScripts(props: { site: SiteRuntime; ctx: RequestContext }) {
+  const { site, ctx } = props;
+  const analytics = site.analytics;
+  return (
+    <>
+      {match(ctx.telemetry.analytics)
+        .with({ kind: "on" }, (plan) => (analytics === undefined ? null : <analytics.Script environment={plan.environment} release={plan.release} transport={telemetryTransport(site)} />))
+        .with({ kind: "off" }, () => null)
+        .exhaustive()}
+    </>
+  );
+}

package/src/config.ts

@@ -0,0 +1,9 @@
+import { loadSiteConfigDocument, type SiteConfig } from "@agentvibes/site-config";
+
+/**
+ * The default export of `site.config.ts`, migrated and validated (a
+ * `defineSite()` result passes through unchanged).
+ */
+export function loadConfig(raw: unknown): SiteConfig {
+  return loadSiteConfigDocument(raw).config;
+}

package/src/context.ts

@@ -0,0 +1,68 @@
+/**
+ * The per-request view of the site: which host asked, whether it may be
+ * indexed (spec §4), which environment errors are tagged with, and whether
+ * telemetry runs. Pages read it through `next/headers`; route handlers from
+ * their `Request`.
+ */
+import { decideIndexing, readDeploymentEnv, siteEnvironment, type IndexingDecision, type SiteEnvironment } from "@agentvibes/site-seo";
+import { planTelemetry, readAnalyticsOnPreview, type TelemetryPlan } from "@agentvibes/site-telemetry";
+import { headers } from "next/headers";
+
+import type { SiteRuntime } from "./runtime";
+
+export type RequestContext = {
+  readonly host: string | undefined;
+  /** `https://<host>` of this request (links that must work on a preview). */
+  readonly origin: string;
+  readonly decision: IndexingDecision;
+  readonly environment: SiteEnvironment;
+  readonly telemetry: TelemetryPlan;
+};
+
+function hostOf(get: (name: string) => string | null): string | undefined {
+  const value = get("x-forwarded-host") ?? get("host");
+  return value === null || value === "" ? undefined : (value.split(",")[0]?.trim() ?? undefined);
+}
+
+function originOf(get: (name: string) => string | null, host: string | undefined, siteUrl: string): string {
+  if (host === undefined) return new URL(siteUrl).origin;
+  const proto = get("x-forwarded-proto")?.split(",")[0]?.trim() ?? "https";
+  return `${proto}://${host}`;
+}
+
+export function contextFor(site: SiteRuntime, get: (name: string) => string | null): RequestContext {
+  const host = hostOf(get);
+  const env = readDeploymentEnv(process.env);
+  const decision = decideIndexing({ index: site.config.index, siteUrl: site.config.siteUrl, env, host });
+  const environment = siteEnvironment({ siteUrl: site.config.siteUrl, env, host });
+  const telemetry = planTelemetry({
+    decision,
+    environment,
+    release: site.generated.release,
+    analyticsConfigured: site.analytics !== undefined,
+    errorsConfigured: site.errors !== undefined,
+    analyticsOnPreview: readAnalyticsOnPreview(process.env)
+  });
+  return { host, origin: originOf(get, host, site.config.siteUrl), decision, environment, telemetry };
+}
+
+/** A static site has no request: its context is that of a request to the origin the files are served from. */
+function staticHeaders(origin: string): (name: string) => string | null {
+  const url = new URL(origin);
+  return (name) => (name === "host" ? url.host : name === "x-forwarded-proto" ? url.protocol.replace(":", "") : null);
+}
+
+/** For server components and `generateMetadata`. */
+export async function requestContext(site: SiteRuntime): Promise<RequestContext> {
+  const output = site.generated.output;
+  if (output.kind === "static") return contextFor(site, staticHeaders(output.origin));
+  const all = await headers();
+  return contextFor(site, (name) => all.get(name));
+}
+
+/** For route handlers. */
+export function requestContextOf(site: SiteRuntime, request: Request): RequestContext {
+  const output = site.generated.output;
+  if (output.kind === "static") return contextFor(site, staticHeaders(output.origin));
+  return contextFor(site, (name) => request.headers.get(name));
+}

package/src/data.ts

@@ -0,0 +1,64 @@
+/**
+ * Data the `prepare` step bakes at build time into `app/_site/generated.json`
+ * (no file-system reads at request time).
+ */
+import type { ProjectToml } from "@agentvibes/site-config";
+
+import type { SiteOutput } from "./output";
+
+export type ApiMember = {
+  readonly kind: "constructor" | "method" | "property";
+  readonly name: string;
+  readonly signature: string;
+  readonly description?: string | undefined;
+};
+
+export type ApiItemKind = "class" | "function" | "type" | "interface" | "const" | "enum";
+
+export type ApiItem = {
+  readonly kind: ApiItemKind;
+  readonly name: string;
+  readonly signature?: string | undefined;
+  readonly description?: string | undefined;
+  readonly members?: readonly ApiMember[] | undefined;
+};
+
+export type JsdocData = {
+  readonly modules: Readonly<Record<string, { readonly entry: string | null; readonly items: readonly ApiItem[] }>>;
+};
+
+export type ChangelogEntry = {
+  /** npm package name, from the package's package.json. */
+  readonly packageName: string;
+  /** Markdown of the package's CHANGELOG.md without its top-level `#` title. */
+  readonly markdown: string;
+};
+
+/** One video of `sections.media.videos`, as URLs under `/_av/media/`. */
+export type VideoEntry = {
+  readonly mp4: string;
+  readonly webm?: string;
+  readonly compactMp4?: string;
+  readonly compactWebm?: string;
+  readonly poster?: string;
+  readonly captions?: string;
+  readonly width?: number;
+  readonly height?: number;
+};
+
+export type MediaData = {
+  /** By name: `<Video name="deploy" label="…" />`. */
+  readonly videos: Readonly<Record<string, VideoEntry>>;
+};
+
+export type GeneratedSiteData = {
+  /** Server or static files (`prepare --static`). */
+  readonly output: SiteOutput;
+  /** Git SHA of the build (`release` tag), or "unknown" outside a git checkout. */
+  readonly release: string;
+  /** `.agentvibes/project.toml`, when the repository has one. */
+  readonly projectToml: ProjectToml | null;
+  readonly jsdoc: JsdocData;
+  readonly changelog: readonly ChangelogEntry[];
+  readonly media: MediaData;
+};

package/src/docs-title.ts

@@ -0,0 +1,8 @@
+/**
+ * True when the MDX body has its own `# ` heading. Pages without one get the
+ * frontmatter `title` and `description` as the page heading, as a hand-written
+ * Fumadocs page does; pages with one keep theirs and get no second title.
+ */
+export function hasOwnTitle(toc: ReadonlyArray<{ readonly depth: number }>): boolean {
+  return toc.some((item) => item.depth === 1);
+}

package/src/doctor-routes.tsx

@@ -0,0 +1,44 @@
+/**
+ * Test routes for site doctor's `errors-captured` rule: `/_doctor/throw`
+ * (a server error) and `/_doctor/throw-client` (a browser error). Every build
+ * has them; they answer 404 unless the server runs with
+ * `AGENTVIBES_DOCTOR_ROUTES=1`, so the artefact the doctor checks is the one
+ * that is deployed.
+ */
+import { notFound } from "next/navigation";
+
+import { DoctorThrow } from "./components/doctor-throw/doctor-throw";
+
+export const DOCTOR_ROUTES_ENV = "AGENTVIBES_DOCTOR_ROUTES";
+
+function doctorRoutesOn(): boolean {
+  return process.env[DOCTOR_ROUTES_ENV] === "1";
+}
+
+function idOf(search: URLSearchParams): string {
+  return (search.get("id") ?? "none").replace(/[^\w-]/g, "").slice(0, 64);
+}
+
+export class DoctorSyntheticError extends Error {
+  override readonly name = "DoctorSyntheticError";
+}
+
+/** `/_doctor/throw?id=…`: throws, so Next's `onRequestError` reports it. */
+export function createDoctorThrowRoute() {
+  return function GET(request: Request): Response {
+    if (!doctorRoutesOn()) return new Response("Not found", { status: 404 });
+    throw new DoctorSyntheticError(`site-doctor synthetic server error ${idOf(new URL(request.url).searchParams)}`);
+  };
+}
+
+type SearchProps = { searchParams: Promise<Record<string, string | string[] | undefined>> };
+
+/** `/_doctor/throw-client?id=…`: a page whose client component throws after mount. */
+export function createDoctorThrowPage() {
+  return async function Page(props: SearchProps) {
+    if (!doctorRoutesOn()) notFound();
+    const raw = (await props.searchParams)["id"];
+    const search = new URLSearchParams(typeof raw === "string" ? { id: raw } : {});
+    return <DoctorThrow id={idOf(search)} />;
+  };
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+export { loadConfig } from "./config";
+export {
+  createSiteRuntime,
+  defineSiteChrome,
+  defineSiteEntries,
+  siteSource,
+  SiteTelemetryConfigError,
+  type SiteChrome,
+  type SiteEntries,
+  type SitePage,
+  type SitePageData,
+  type SiteRuntime,
+  type SiteRuntimeInput,
+  type SiteSearchEntry,
+  type SiteSource
+} from "./runtime";
+export type { ApiItem, ApiMember, ChangelogEntry, GeneratedSiteData, JsdocData, MediaData, VideoEntry } from "./data";
+export { HomeShell } from "./components/home-shell";
+export { createDocsLayout, createRootLayout } from "./layouts";
+export { createChangelogPage, createDocsPage, createJsdocPage, createLandingPage, createNotFoundPage } from "./pages";
+export {
+  createAnalyticsTunnel,
+  createErrorsTunnel,
+  createFaviconRoute,
+  createLlmsRoute,
+  createMarkdownParams,
+  createMarkdownRoute,
+  createRobotsRoute,
+  createSearchRoute,
+  createSitemapRoute
+} from "./routes";
+export { createOgParams, createOgRoute } from "./og-route";
+export { type SiteOutput } from "./output";
+export { catalog, catalogSections, findPage, type CatalogPage } from "./catalog";
+export { footerColumns, headerLinks, repositoryLinks, type FooterColumn, type SiteLink } from "./nav";
+export { themeCss } from "./theme";
+export { mdxComponentsFor } from "./mdx";
+export { createDoctorThrowPage, createDoctorThrowRoute, DOCTOR_ROUTES_ENV, DoctorSyntheticError } from "./doctor-routes";
+export { AppChrome, appMetadata, AppModeConfigError, createManifest, createOfflinePage, createServiceWorkerRoute, documentViewport, siteViewport } from "./app-mode";

package/src/instrumentation.ts

@@ -0,0 +1,53 @@
+/**
+ * Server-side error capture: Next calls `onRequestError` for every error
+ * thrown while rendering a page, in a route handler, a server action or the
+ * proxy. The generated `instrumentation.ts` binds this to the site runtime;
+ * the error goes to the configured reporter with the same environment and
+ * release gating as the browser (`planTelemetry`).
+ */
+import { warnDegraded } from "@agentvibes/kit/diagnostics";
+import type { Instrumentation } from "next";
+import { match } from "ts-pattern";
+
+import { contextFor } from "./context";
+import type { SiteRuntime } from "./runtime";
+
+type RequestHeaders = Parameters<Instrumentation.onRequestError>[1]["headers"];
+
+function headerReader(headers: RequestHeaders): (name: string) => string | null {
+  return (name) => {
+    const value = headers[name];
+    return Array.isArray(value) ? (value[0] ?? null) : (value ?? null);
+  };
+}
+
+/**
+ * `load` imports the runtime lazily, so instrumentation does not pull the
+ * site into every server entry; it returns undefined where the runtime is not
+ * available (the edge runtime), and the error is then left to Next's log.
+ */
+export function createRequestErrorHandler(load: () => Promise<SiteRuntime | undefined>): Instrumentation.onRequestError {
+  return async function onRequestError(error, request, context) {
+    const site = await load();
+    const reporter = site?.errors;
+    if (site === undefined || reporter === undefined) return;
+    const ctx = contextFor(site, headerReader(request.headers));
+    await match(ctx.telemetry.errors)
+      .with({ kind: "on" }, (plan) =>
+        reporter
+          .captureServer(error, {
+            environment: plan.environment,
+            release: plan.release,
+            path: request.path,
+            method: request.method,
+            routePath: context.routePath,
+            routeType: context.routeType
+          })
+          .catch((failure: unknown) => {
+            warnDegraded("site.errors.server", `a server error was not reported: ${failure instanceof Error ? failure.message : String(failure)}`);
+          })
+      )
+      .with({ kind: "off" }, async () => undefined)
+      .exhaustive();
+  };
+}

package/src/jsdoc.ts

@@ -0,0 +1,38 @@
+import { match } from "ts-pattern";
+
+import type { ApiItem, ApiItemKind } from "./data";
+
+const KIND_ORDER: readonly ApiItemKind[] = ["class", "function", "type", "interface", "const", "enum"];
+
+export function sectionTitle(kind: ApiItemKind): string {
+  return match(kind)
+    .with("class", () => "Classes")
+    .with("function", () => "Functions")
+    .with("type", () => "Types")
+    .with("interface", () => "Interfaces")
+    .with("const", () => "Constants")
+    .with("enum", () => "Enums")
+    .exhaustive();
+}
+
+export function groupByKind(items: readonly ApiItem[]): Array<{ kind: ApiItemKind; items: ApiItem[] }> {
+  return KIND_ORDER.map((kind) => ({ kind, items: items.filter((item) => item.kind === kind) })).filter((group) => group.items.length > 0);
+}
+
+/** The API reference as Markdown, for `.md` and llms. */
+export function jsdocMarkdown(items: readonly ApiItem[]): string {
+  return groupByKind(items)
+    .map((group) => {
+      const entries = group.items.map((item) => {
+        const lines = [`### ${item.name}`, ""];
+        if (item.description !== undefined) lines.push(item.description, "");
+        if (item.signature !== undefined) lines.push("```ts", item.signature, "```", "");
+        for (const member of item.members ?? []) {
+          lines.push(`- \`${member.signature}\`${member.description === undefined ? "" : ` — ${member.description}`}`);
+        }
+        return lines.join("\n").trimEnd();
+      });
+      return [`## ${sectionTitle(group.kind)}`, "", entries.join("\n\n")].join("\n");
+    })
+    .join("\n\n");
+}

package/src/layout-options.ts

@@ -0,0 +1,18 @@
+import type { LinkItemType } from "fumadocs-ui/layouts/shared";
+
+import { githubUrl, headerLinks } from "./nav";
+import type { SiteRuntime } from "./runtime";
+
+function navLinks(site: SiteRuntime): LinkItemType[] {
+  return headerLinks(site.config).map((link) => ({ text: link.label, url: link.href, external: link.external, active: "nested-url" as const }));
+}
+
+/** Header options shared by the docs and home layouts: title, links from config, GitHub. */
+export function layoutOptions(site: SiteRuntime) {
+  const github = githubUrl(site.config);
+  return {
+    nav: { title: site.chrome?.navTitle ?? site.config.name, url: "/" },
+    links: navLinks(site),
+    ...(github === undefined ? {} : { githubUrl: github })
+  };
+}