@agentvibes/site 0.0.0-stage → 0.10.0

package/src/prepare/jsdoc-extract.ts

@@ -0,0 +1,182 @@
+/**
+ * Build-time API extraction with the TypeScript compiler (ported from the
+ * npm-factory site's scripts/build-jsdoc.mjs). Reads each npm module's source
+ * entry and returns its exports with signatures and JSDoc.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import ts from "typescript";
+import { z } from "zod/v4";
+
+import type { ApiItem, ApiItemKind, ApiMember } from "../data";
+
+function jsdocText(node: ts.Node): string | undefined {
+  const parts = ts
+    .getJSDocCommentsAndTags(node)
+    .filter(ts.isJSDoc)
+    .map((doc) => (typeof doc.comment === "string" ? doc.comment : (doc.comment ?? []).map((part) => part.text).join("")).trim())
+    .filter((text) => text !== "");
+  return parts.length === 0 ? undefined : parts.join("\n\n");
+}
+
+function symbolDoc(symbol: ts.Symbol, checker: ts.TypeChecker): string | undefined {
+  const text = ts.displayPartsToString(symbol.getDocumentationComment(checker)).trim();
+  return text === "" ? undefined : text;
+}
+
+function isPublicMember(member: ts.Node): boolean {
+  const modifiers = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined;
+  return !(modifiers ?? []).some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword);
+}
+
+function classify(decl: ts.Declaration): ApiItemKind | undefined {
+  if (ts.isClassDeclaration(decl)) return "class";
+  if (ts.isFunctionDeclaration(decl)) return "function";
+  if (ts.isInterfaceDeclaration(decl)) return "interface";
+  if (ts.isTypeAliasDeclaration(decl)) return "type";
+  if (ts.isEnumDeclaration(decl)) return "enum";
+  if (ts.isVariableDeclaration(decl)) return "const";
+  return undefined;
+}
+
+function signatureOf(checker: ts.TypeChecker, name: string, decl: ts.SignatureDeclaration): string | undefined {
+  const sig = checker.getSignatureFromDeclaration(decl);
+  if (sig === undefined) return undefined;
+  const raw = checker.signatureToString(sig, decl, ts.TypeFormatFlags.NoTruncation);
+  return raw.startsWith("(") ? `${name}${raw}` : raw;
+}
+
+function typeText(checker: ts.TypeChecker, node: ts.Node): string {
+  return checker.typeToString(checker.getTypeAtLocation(node), node, ts.TypeFormatFlags.NoTruncation);
+}
+
+function withDescription<T extends object>(value: T, description: string | undefined): T & { description?: string } {
+  return description === undefined ? value : { ...value, description };
+}
+
+function classMembers(checker: ts.TypeChecker, decl: ts.ClassDeclaration): ApiMember[] {
+  const members: ApiMember[] = [];
+  for (const member of decl.members) {
+    if (!isPublicMember(member)) continue;
+    if (ts.isConstructorDeclaration(member)) {
+      members.push(withDescription({ kind: "constructor" as const, name: "constructor", signature: signatureOf(checker, "constructor", member) ?? "constructor()" }, jsdocText(member)));
+    } else if (ts.isMethodDeclaration(member)) {
+      const name = member.name.getText();
+      members.push(withDescription({ kind: "method" as const, name, signature: signatureOf(checker, name, member) ?? `${name}()` }, jsdocText(member)));
+    } else if (ts.isPropertyDeclaration(member)) {
+      const name = member.name.getText();
+      members.push(withDescription({ kind: "property" as const, name, signature: `${name}: ${typeText(checker, member)}` }, jsdocText(member)));
+    }
+  }
+  return members;
+}
+
+function interfaceMembers(checker: ts.TypeChecker, decl: ts.InterfaceDeclaration): ApiMember[] {
+  const members: ApiMember[] = [];
+  for (const member of decl.members) {
+    if (ts.isMethodSignature(member)) {
+      const name = member.name.getText();
+      members.push(withDescription({ kind: "method" as const, name, signature: signatureOf(checker, name, member) ?? `${name}()` }, jsdocText(member)));
+    } else if (ts.isPropertySignature(member)) {
+      const name = member.name.getText();
+      members.push(withDescription({ kind: "property" as const, name, signature: `${name}: ${typeText(checker, member)}` }, jsdocText(member)));
+    }
+  }
+  return members;
+}
+
+function itemOf(symbol: ts.Symbol, checker: ts.TypeChecker, sourceFile: ts.SourceFile, name: string): ApiItem | undefined {
+  const decls = symbol.getDeclarations() ?? [];
+  const decl = decls.find((d) => classify(d) !== undefined);
+  if (decl === undefined) return undefined;
+  const description = symbolDoc(symbol, checker) ?? jsdocText(decl);
+  if (ts.isFunctionDeclaration(decl)) {
+    return withDescription({ kind: "function" as const, name, signature: signatureOf(checker, name, decl) ?? `${name}()` }, description);
+  }
+  if (ts.isClassDeclaration(decl)) {
+    return withDescription({ kind: "class" as const, name, signature: `class ${name}`, members: classMembers(checker, decl) }, description);
+  }
+  if (ts.isInterfaceDeclaration(decl)) {
+    return withDescription({ kind: "interface" as const, name, signature: `interface ${name}`, members: interfaceMembers(checker, decl) }, description);
+  }
+  if (ts.isTypeAliasDeclaration(decl)) {
+    const text = typeText(checker, decl);
+    return withDescription({ kind: "type" as const, name, signature: `type ${name} = ${text === name ? decl.type.getText() : text}` }, description);
+  }
+  if (ts.isEnumDeclaration(decl)) {
+    const members = decl.members.map((m) => withDescription({ kind: "property" as const, name: m.name.getText(), signature: m.name.getText() }, jsdocText(m)));
+    return withDescription({ kind: "enum" as const, name, signature: `enum ${name}`, members }, description);
+  }
+  if (ts.isVariableDeclaration(decl)) {
+    const text = checker.typeToString(checker.getTypeOfSymbolAtLocation(symbol, sourceFile), decl, ts.TypeFormatFlags.NoTruncation);
+    return withDescription({ kind: "const" as const, name, signature: `const ${name}: ${text}` }, description);
+  }
+  return undefined;
+}
+
+/** Exports of a TypeScript entry file. */
+export function extractApi(entry: string): ApiItem[] {
+  const options: ts.CompilerOptions = {
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    jsx: ts.JsxEmit.ReactJSX
+  };
+  const program = ts.createProgram([entry], options, ts.createCompilerHost(options, true));
+  const sourceFile = program.getSourceFile(entry);
+  if (sourceFile === undefined) return [];
+  const checker = program.getTypeChecker();
+  const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+  if (moduleSymbol === undefined) return [];
+  return checker.getExportsOfModule(moduleSymbol).flatMap((symbol) => {
+    const target = (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
+    const item = itemOf(target, checker, sourceFile, symbol.getName());
+    return item === undefined ? [] : [item];
+  });
+}
+
+const ExportTarget = z.union([z.string(), z.looseObject({ import: z.string().optional(), default: z.string().optional(), types: z.string().optional() })]);
+const PackageJson = z.looseObject({
+  name: z.string().optional(),
+  exports: z.union([z.string(), z.looseObject({ ".": ExportTarget.optional() })]).optional(),
+  types: z.string().optional(),
+  main: z.string().optional(),
+  module: z.string().optional()
+});
+
+export type PackageJsonInfo = z.output<typeof PackageJson>;
+
+export function readPackageJson(packageDir: string): PackageJsonInfo | undefined {
+  const file = path.join(packageDir, "package.json");
+  if (!fs.existsSync(file)) return undefined;
+  return PackageJson.parse(JSON.parse(fs.readFileSync(file, "utf8")));
+}
+
+function candidates(pkg: PackageJsonInfo): string[] {
+  const out: string[] = [];
+  const root = typeof pkg.exports === "string" ? pkg.exports : pkg.exports?.["."];
+  if (typeof root === "string") out.push(root);
+  else if (root !== undefined) for (const key of ["import", "default", "types"] as const) if (root[key] !== undefined) out.push(root[key]);
+  for (const field of [pkg.types, pkg.main, pkg.module]) if (field !== undefined) out.push(field);
+  return out;
+}
+
+/** `dist/x.js` → `src/x.ts`; a `src/*.ts(x)` path stays. */
+function sourceOf(candidate: string): string | undefined {
+  const stripped = candidate.replace(/^\.\//, "");
+  if (/^src\/.+\.tsx?$/.test(stripped)) return stripped;
+  const dist = stripped.match(/^dist\/(.+?)\.(?:m?js|cjs|d\.ts)$/);
+  return dist?.[1] === undefined ? undefined : path.join("src", `${dist[1]}.ts`);
+}
+
+/** The TypeScript source entry of a package directory, or undefined. */
+export function resolveSourceEntry(packageDir: string): string | undefined {
+  const pkg = readPackageJson(packageDir);
+  for (const candidate of pkg === undefined ? [] : candidates(pkg)) {
+    const rel = sourceOf(candidate);
+    if (rel !== undefined && fs.existsSync(path.join(packageDir, rel))) return path.join(packageDir, rel);
+  }
+  const fallback = path.join(packageDir, "src", "index.ts");
+  return fs.existsSync(fallback) ? fallback : undefined;
+}

package/src/prepare/release.ts

@@ -0,0 +1,12 @@
+/** Environment variables that carry the build's git SHA, in priority order. */
+const RELEASE_ENV = ["VERCEL_GIT_COMMIT_SHA", "GITHUB_SHA"] as const;
+
+/**
+ * The git SHA tagged on every analytics event and error. An empty variable
+ * counts as unset: `vercel pull` writes `VERCEL_GIT_COMMIT_SHA=""` for CLI
+ * deploys, which would otherwise hide `GITHUB_SHA` and the git checkout.
+ */
+export function releaseOf(env: Record<string, string | undefined>, gitHead: () => string | undefined): string {
+  const fromEnv = RELEASE_ENV.map((name) => env[name]?.trim()).find((value) => value !== undefined && value !== "");
+  return fromEnv ?? gitHead() ?? "unknown";
+}

package/src/prepare/templates.ts

@@ -0,0 +1,415 @@
+/**
+ * The files of a generated site. Each route file only binds a factory from
+ * `@agentvibes/site` to the site runtime, so all behaviour lives (and is
+ * tested) in the package, and regenerating never loses anything.
+ */
+import { APP_SHELL_CSS } from "@agentvibes/site-app";
+import type { SiteAppConfig } from "@agentvibes/site-config";
+import { FONTS_URL, siteMediaCss, terminalFontFaceCss, terminalFontStack } from "@agentvibes/site-mdx/media";
+
+import type { GeneratedSiteData } from "../data";
+import { withBasePath, type SiteOutput } from "../output";
+import { withHeader, type GeneratedFile } from "./files";
+
+export type TemplateInput = {
+  /** `server`, or `static` for `next build` with `output: "export"`. */
+  readonly output: SiteOutput;
+  /** site.config `index`: a static build writes sitemap.xml and llms.txt only when it is true. */
+  readonly indexed: boolean;
+  /** Package name of the preset, when site.config names one. */
+  readonly presetPackage: string | undefined;
+  readonly generated: GeneratedSiteData;
+  /** CSS of the preset theme (may be empty). */
+  readonly themeCss: string;
+  /** Tailwind `@source` globs, relative to `app/`. */
+  readonly tailwindSources: readonly string[];
+  /** Packages Next must compile (workspace packages that ship TypeScript). */
+  readonly transpilePackages: readonly string[];
+  readonly docs: boolean;
+  readonly jsdoc: boolean;
+  readonly changelog: boolean;
+  /** The site's icon (its SVG, or the default letter mark); undefined when the author's `app/` has its own icon. */
+  readonly icon: string | undefined;
+  /** `/favicon.ico` (base64), rendered from `icon`; undefined when the author serves their own favicon. */
+  readonly favicon: string | undefined;
+  /** The site has `site.entries.ts`: the runtime passes its search documents and llms.txt text to the routes. */
+  readonly authorEntries: boolean;
+  /** `app` from site.config (spec §5); undefined for a docs site. */
+  readonly app: SiteAppConfig | undefined;
+  /** kind "app": the author writes `app/page.tsx` (the app's home); prepare does not generate it. */
+  readonly authorHome: boolean;
+  /** The preset's mono font stack, the terminal font's fallback. */
+  readonly monoFallback: string | undefined;
+  /** `sections.media.tui.frames` (a glob with one `*`, relative to the site), for `<TerminalFrame name>`. */
+  readonly framesGlob: string | undefined;
+  /** site.config `lang`: the `<html lang>` of the global error page, which replaces the root layout. */
+  readonly lang: string;
+  /** The site has `site.next.mjs`: next.config passes its config through that file's default export. */
+  readonly authorNextConfig: boolean;
+  /** The site has `site.css`: globals.css imports it after the theme. */
+  readonly authorCss: boolean;
+  /** The site has `site.proxy.ts`: the generated proxy runs its default export first. */
+  readonly authorProxy: boolean;
+  /** The site has `site.chrome.tsx`: the generated runtime passes its default export. */
+  readonly authorChrome: boolean;
+};
+
+/**
+ * Optional files the site author owns, for what site.config does not
+ * describe (workspace packages to compile, module aliases, redirects, the
+ * site's own component styles).
+ */
+export const AUTHOR_NEXT_CONFIG = "site.next.mjs";
+export const AUTHOR_CSS = "site.css";
+/** Optional author file: search documents and llms.txt text beyond the MDX pages (`defineSiteEntries`). */
+export const AUTHOR_ENTRIES = "site.entries.ts";
+/** Optional author file: a guard run before every request (`SiteGuard`), for a login gate. */
+export const AUTHOR_PROXY = "site.proxy.ts";
+/** Optional author file: the site's own header title, footer and theme storage key (`defineSiteChrome`). */
+export const AUTHOR_CHROME = "site.chrome.tsx";
+
+const DYNAMIC = `// Rendered per request: indexing, robots and telemetry depend on the request host (spec §4).\nexport const dynamic = "force-dynamic";\n`;
+const STATIC = `// Static output: rendered once at build time, for the origin given to prepare --static.\nexport const dynamic = "force-static";\n`;
+
+function rendering(input: TemplateInput): string {
+  return input.output.kind === "static" ? STATIC : DYNAMIC;
+}
+
+function ts(path: string, body: string): GeneratedFile {
+  return { path, content: withHeader("slash", body) };
+}
+
+function runtimeFile(input: TemplateInput): GeneratedFile {
+  const presetImport =
+    input.presetPackage === undefined ? `const preset = undefined;` : `import preset from ${JSON.stringify(input.presetPackage)};`;
+  const entriesImport = input.authorEntries ? `import entries from "../../${AUTHOR_ENTRIES.replace(/\.ts$/, "")}";\n` : "";
+  const entriesField = input.authorEntries ? ",\n  entries" : "";
+  const chromeImport = input.authorChrome ? `import chrome from "../../${AUTHOR_CHROME.replace(/\.tsx$/, "")}";\n` : "";
+  const chromeField = input.authorChrome ? ",\n  chrome" : "";
+  return ts(
+    "app/_site/runtime.ts",
+    `import { createSiteRuntime, loadConfig, siteSource } from "@agentvibes/site";
+import { loader } from "fumadocs-core/source";
+
+${presetImport}
+import { docs, pages } from "../../.source/server";
+${entriesImport}${chromeImport}import rawConfig from "../../site.config";
+import generated from "./generated";
+
+export const site = createSiteRuntime({
+  config: loadConfig(rawConfig),
+  preset,
+  generated,
+  docs: siteSource(loader({ baseUrl: "/docs", source: docs.toFumadocsSource() })),
+  pages: siteSource(loader({ baseUrl: "/", source: pages.toFumadocsSource() }))${entriesField}${chromeField}
+});
+`
+  );
+}
+
+function generatedFile(data: GeneratedSiteData): GeneratedFile {
+  return ts(
+    "app/_site/generated.ts",
+    `import type { GeneratedSiteData } from "@agentvibes/site";
+
+const generated: GeneratedSiteData = ${JSON.stringify(data, null, 2)};
+
+export default generated;
+`
+  );
+}
+
+function pageFile(input: TemplateInput, path: string, factory: string, withMetadata: boolean): GeneratedFile {
+  const metadata = withMetadata ? `export const generateMetadata = page.generateMetadata;\nexport const viewport = page.viewport;\n` : "";
+  const params = input.output.kind === "static" && path.includes("[") ? `export const dynamicParams = false;\nexport const generateStaticParams = page.generateStaticParams;\n` : "";
+  return ts(
+    path,
+    `import { ${factory} } from "@agentvibes/site";
+
+import { site } from "${"../".repeat(path.split("/").length - 2) || "./"}_site/runtime";
+
+${rendering(input)}
+const page = ${factory}(site);
+${metadata}${params}export default page.Page;
+`
+  );
+}
+
+function routeFile(input: TemplateInput, path: string, factory: string, methods: readonly string[], paramsFactory?: string): GeneratedFile {
+  const depth = path.split("/").length - 2;
+  const imports = paramsFactory === undefined ? factory : `${factory}, ${paramsFactory}`;
+  const params = paramsFactory === undefined ? "" : `export const dynamicParams = false;\nexport const generateStaticParams = ${paramsFactory}(site);\n`;
+  const exports = methods.map((method) => `export const ${method} = handler;`).join("\n");
+  return ts(
+    path,
+    `import { ${imports} } from "@agentvibes/site";
+
+import { site } from "${"../".repeat(depth)}_site/runtime";
+
+${rendering(input)}
+const handler = ${factory}(site);
+${params}${exports}
+`
+  );
+}
+
+/** Routes that answer per request: the host-dependent lists, the Markdown and OG routes, the telemetry tunnels, doctor's probes. */
+function serverOnlyRoutes(input: TemplateInput): GeneratedFile[] {
+  return [
+    routeFile(input, "app/sitemap.xml/route.ts", "createSitemapRoute", ["GET"]),
+    routeFile(input, "app/llms.txt/route.ts", "createLlmsRoute", ["GET"]),
+    routeFile(input, "app/llms.mdx/[[...slug]]/route.ts", "createMarkdownRoute", ["GET"]),
+    routeFile(input, "app/og/[[...slug]]/route.ts", "createOgRoute", ["GET"]),
+    // `%5F` is an escaped "_": Next treats `_name` folders as private.
+    routeFile(input, "app/%5Fa/[...path]/route.ts", "createAnalyticsTunnel", ["GET", "POST"]),
+    routeFile(input, "app/%5Fe/route.ts", "createErrorsTunnel", ["POST"]),
+    // site doctor's errors-captured probes: 404 unless the server runs with AGENTVIBES_DOCTOR_ROUTES=1.
+    ts(
+      "app/%5Fdoctor/throw/route.ts",
+      `import { createDoctorThrowRoute } from "@agentvibes/site";\n\n${DYNAMIC}export const GET = createDoctorThrowRoute();\n`
+    ),
+    ts(
+      "app/%5Fdoctor/throw-client/page.tsx",
+      `import { createDoctorThrowPage } from "@agentvibes/site";\n\n${DYNAMIC}export default createDoctorThrowPage();\n`
+    )
+  ];
+}
+
+/**
+ * The same content as files. Every path ends in an extension, because Next
+ * writes a route's output to a file named after its path, and `/docs` next to
+ * `/docs/init` would need `docs` to be a file and a directory at once.
+ */
+function staticRoutes(input: TemplateInput): GeneratedFile[] {
+  return [
+    ...(input.indexed
+      ? [routeFile(input, "app/sitemap.xml/route.ts", "createSitemapRoute", ["GET"]), routeFile(input, "app/llms.txt/route.ts", "createLlmsRoute", ["GET"])]
+      : []),
+    routeFile(input, "app/llms.mdx/[...slug]/route.ts", "createMarkdownRoute", ["GET"], "createMarkdownParams"),
+    routeFile(input, "app/og/[...slug]/route.ts", "createOgRoute", ["GET"], "createOgParams")
+  ];
+}
+
+function appFiles(input: TemplateInput): GeneratedFile[] {
+  const files: GeneratedFile[] = [
+    runtimeFile(input),
+    generatedFile(input.generated),
+    ts(
+      "app/layout.tsx",
+      `import "./globals.css";
+
+import { createRootLayout } from "@agentvibes/site";
+
+import { site } from "./_site/runtime";
+
+${rendering(input)}
+const root = createRootLayout(site);
+export const generateMetadata = root.generateMetadata;
+export const viewport = root.viewport;
+export default root.RootLayout;
+`
+    ),
+    ts(
+      "app/not-found.tsx",
+      `import { createNotFoundPage } from "@agentvibes/site";
+
+import { site } from "./_site/runtime";
+
+export default createNotFoundPage(site);
+`
+    ),
+    ts("app/error.tsx", `"use client";\n\nimport { SiteErrorBoundary } from "@agentvibes/site/client";\n\nexport default SiteErrorBoundary;\n`),
+    ts(
+      "app/global-error.tsx",
+      `"use client";\n\nimport { SiteGlobalErrorBoundary } from "@agentvibes/site/client";\n\nexport default function GlobalError(props: Parameters<typeof SiteGlobalErrorBoundary>[0]) {\n  return <SiteGlobalErrorBoundary {...props} lang={${JSON.stringify(input.lang)}} />;\n}\n`
+    ),
+    {
+      path: "app/globals.css",
+      content: withHeader(
+        "css",
+        [
+          `@import "tailwindcss";`,
+          `@import "fumadocs-ui/css/neutral.css";`,
+          `@import "fumadocs-ui/css/preset.css";`,
+          "",
+          ...input.tailwindSources.map((glob) => `@source ${JSON.stringify(glob)};`),
+          "",
+          input.themeCss,
+          terminalFontFaceCss(withBasePath(input.output, FONTS_URL)),
+          // Code blocks use the served terminal font too, so site doctor's fonts-coverage can check every glyph.
+          `:root {\n  --font-mono: ${terminalFontStack(input.monoFallback)};\n}\n`,
+          siteMediaCss(input.monoFallback),
+          ...(input.app?.fullscreen === true ? [APP_SHELL_CSS] : []),
+          // The site's own styles, last so they win over the defaults above.
+          ...(input.authorCss ? [`@import "../${AUTHOR_CSS}";\n`] : [])
+        ].join("\n")
+      )
+    },
+    routeFile(input, "app/robots.txt/route.ts", "createRobotsRoute", ["GET"]),
+    ...(input.output.kind === "server" ? serverOnlyRoutes(input) : staticRoutes(input))
+  ];
+  if (!input.authorHome) files.push(pageFile(input, "app/page.tsx", "createLandingPage", true));
+  files.push(...appModeFiles(input));
+  // The search handler is an object of methods, not a function.
+  files.push(ts(
+    "app/api/search/route.ts",
+    `import { createSearchRoute } from "@agentvibes/site";
+
+import { site } from "../../_site/runtime";
+
+${rendering(input)}
+export const { ${input.output.kind === "static" ? "staticGET: GET" : "GET"} } = createSearchRoute(site);
+`
+  ));
+  if (input.docs) {
+    files.push(
+      ts(
+        "app/docs/layout.tsx",
+        `import { createDocsLayout } from "@agentvibes/site";
+
+import { site } from "../_site/runtime";
+
+const layout = createDocsLayout(site);
+export const viewport = layout.viewport;
+export default layout.Layout;
+`
+      ),
+      pageFile(input, "app/docs/[[...slug]]/page.tsx", "createDocsPage", true)
+    );
+  }
+  if (input.docs && input.jsdoc) files.push(pageFile(input, "app/docs/[moduleId]/jsdoc/page.tsx", "createJsdocPage", true));
+  if (input.changelog) files.push(pageFile(input, "app/changelog/page.tsx", "createChangelogPage", true));
+  if (input.icon !== undefined) {
+    const svg = input.icon.replace(/^\s*(<\?xml[^>]*\?>\s*)?/, "");
+    files.push({ path: "app/icon.svg", content: withHeader("xml", svg) });
+  }
+  if (input.favicon !== undefined) {
+    files.push(
+      ts(
+        "app/favicon.ico/route.ts",
+        `import { createFaviconRoute } from "@agentvibes/site";\n\n// The bytes of /favicon.ico (16, 32 and 48 px), rendered from app/icon.svg.\nexport const dynamic = "force-static";\nexport const GET = createFaviconRoute(${JSON.stringify(input.favicon)});\n`
+      )
+    );
+  }
+  return files;
+}
+
+/** `app.pwa` → the manifest; `app.pwa.offline` → the service worker and the offline page. */
+function appModeFiles(input: TemplateInput): GeneratedFile[] {
+  const pwa = input.app?.pwa;
+  if (pwa === undefined) return [];
+  const files = [
+    ts(
+      "app/manifest.ts",
+      `import { createManifest } from "@agentvibes/site";\n\nimport { site } from "./_site/runtime";\n\nexport default createManifest(site);\n`
+    )
+  ];
+  if (pwa.offline) {
+    files.push(routeFile(input, "app/sw.js/route.ts", "createServiceWorkerRoute", ["GET"]), pageFile(input, "app/~offline/page.tsx", "createOfflinePage", false));
+  }
+  return files;
+}
+
+/** The fields a static export needs, applied after the author's hook so it cannot undo them. `from` names the config they extend. */
+function staticNextConfig(output: Extract<SiteOutput, { kind: "static" }>, from: string): string {
+  const basePath = output.basePath === "" ? "" : ` basePath: ${JSON.stringify(output.basePath)},`;
+  return `{ ...${from}, output: "export", trailingSlash: true, images: { unoptimized: true },${basePath} env: { ...${from}.env, NEXT_PUBLIC_SITE_STATIC: "1" } }`;
+}
+
+function nextConfigFile(input: TemplateInput): GeneratedFile {
+  const base = `/** @type {import("next").NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  transpilePackages: ${JSON.stringify(input.transpilePackages)}
+};
+`;
+  const extended = input.authorNextConfig ? "await extendNextConfig(nextConfig)" : "nextConfig";
+  const authored = input.output.kind === "static" ? `const authored = ${extended};\n` : "";
+  const finalConfig = input.output.kind === "static" ? staticNextConfig(input.output, "authored") : extended;
+  const authorImport = input.authorNextConfig ? `\nimport extendNextConfig from "./${AUTHOR_NEXT_CONFIG}";\n` : "";
+  const authorNote = input.authorNextConfig ? `// ${AUTHOR_NEXT_CONFIG} (the site's own file) receives the generated config and returns the one Next uses.\n` : "";
+  return ts(
+    "next.config.mjs",
+    `import { createMDX } from "fumadocs-mdx/next";
+${authorImport}
+const withMDX = createMDX();
+
+${base}
+${authorNote}${authored}export default withMDX(${finalConfig});
+`
+  );
+}
+
+/** The proxy and server instrumentation: a static host runs neither. */
+function serverRootFiles(input: TemplateInput): GeneratedFile[] {
+  if (input.output.kind === "static") return [];
+  return [
+    ts(
+      "proxy.ts",
+      `import { createProxy, loadConfig } from "@agentvibes/site/proxy";
+${input.authorProxy ? `\nimport guard from "./${AUTHOR_PROXY.replace(/\.ts$/, "")}";` : ""}
+import rawConfig from "./site.config";
+
+export const proxy = createProxy(loadConfig(rawConfig)${input.authorProxy ? ", guard" : ""});
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|_av/|favicon.ico|icon.svg|sw.js).*)"]
+};
+`
+    ),
+    // Server-side errors (spec §4): Next calls onRequestError for render, route and action errors.
+    ts(
+      "instrumentation.ts",
+      `import { createRequestErrorHandler } from "@agentvibes/site/instrumentation";
+
+// The runtime is loaded on the first error, and only in the Node.js runtime
+// (the edge bundle must not pull in the site's content).
+export const onRequestError = createRequestErrorHandler(async () => {
+  if (process.env.NEXT_RUNTIME === "nodejs") return (await import("./app/_site/runtime")).site;
+  return undefined;
+});
+`
+    )
+  ];
+}
+
+function rootFiles(input: TemplateInput): GeneratedFile[] {
+  const collection = (name: string, dir: string) => `export const ${name} = defineDocs({ dir: ${JSON.stringify(dir)} });`;
+  return [
+    ts(
+      "source.config.ts",
+      `import { remarkInlineMedia, remarkMarkdownCopy } from "@agentvibes/site/mdx-config";
+import { defineConfig, defineDocs } from "fumadocs-mdx/config";
+
+${collection("docs", "content/docs")}
+
+${collection("pages", "content/pages")}
+
+// remarkMarkdownCopy writes what page.data.getText("processed") returns
+// (the .md copies, llms-full.txt), in place of includeProcessedMarkdown.
+// remarkInlineMedia then inlines <Diagram src> and <TerminalFrame src|name>
+// files into the page (after the copy, so the .md keeps the short src).
+export default defineConfig({
+  mdxOptions: { remarkPlugins: [remarkMarkdownCopy, [remarkInlineMedia, ${JSON.stringify({ frames: input.framesGlob ?? null })}]] }
+});
+`
+    ),
+    nextConfigFile(input),
+    ts("postcss.config.mjs", `export default {\n  plugins: {\n    "@tailwindcss/postcss": {}\n  }\n};\n`),
+    ...serverRootFiles(input)
+  ];
+}
+
+/** `app/.gitignore`: the generated files under app/, so only the author's own routes are committed. */
+function appGitignore(files: readonly GeneratedFile[]): GeneratedFile {
+  const lines = files
+    .map((file) => file.path)
+    .filter((path) => path.startsWith("app/"))
+    .map((path) => `/${path.slice("app/".length).replace(/[[\]]/g, (c) => `\\${c}`)}`);
+  return { path: "app/.gitignore", content: withHeader("hash", `/.gitignore\n${lines.join("\n")}\n`) };
+}
+
+export function siteFiles(input: TemplateInput): GeneratedFile[] {
+  const app = appFiles(input);
+  return [...app, appGitignore(app), ...rootFiles(input)];
+}

package/src/prepare/unimplemented.ts

@@ -0,0 +1,32 @@
+/**
+ * Config the schema accepts but no code acts on. `prepare` refuses it, so an
+ * author never takes a build that silently left a declared feature out for a
+ * finished site. Each problem names the thing to write instead.
+ */
+import type { SiteConfig } from "@agentvibes/site-config";
+
+/** The extension points that do exist, for the plugin message. */
+const AUTHOR_FILES = "site.next.mjs (Next config), site.css, site.entries.ts (search and llms.txt), site.chrome.tsx (header title and footer), site.proxy.ts (request guard)";
+
+/** Messages for every declared-but-unimplemented feature in `config`; empty when there is none. */
+export function unimplementedConfig(config: SiteConfig): string[] {
+  const problems: string[] = [];
+  const api = config.sections.api;
+  if ((api?.typescript?.length ?? 0) > 0) {
+    problems.push(
+      "sections.api.typescript is not implemented: no API pages are generated from entry files. Write the reference as an MDX page, e.g. content/docs/api.mdx (with title and description in its frontmatter). Packages listed in sections.npm.modules already get generated JSDoc pages."
+    );
+  }
+  if ((api?.openapi?.length ?? 0) > 0) {
+    problems.push("sections.api.openapi is not implemented: no OpenAPI reference is generated. Write the reference as an MDX page, e.g. content/docs/api.mdx.");
+  }
+  if (config.sections.cli !== undefined) {
+    problems.push("sections.cli is not implemented: no CLI reference is generated. Write it as an MDX page, e.g. content/docs/cli.mdx, with the output of your --help in a code block.");
+  }
+  if (config.plugins.length > 0) {
+    problems.push(
+      `plugins is not implemented (${config.plugins.map((plugin) => plugin.name).join(", ")}): no plugin hook runs, so a plugin would change nothing. Use the author files instead: ${AUTHOR_FILES}.`
+    );
+  }
+  return problems;
+}