@agentvibes/site 0.0.0-stage → 0.10.0

package/src/layouts.tsx

@@ -0,0 +1,63 @@
+import { JsonLdScript } from "@agentvibes/site-seo/json-ld";
+import { siteMetadata } from "@agentvibes/site-seo";
+import { ScrollPage } from "@agentvibes/site-app";
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
+import { RootProvider } from "fumadocs-ui/provider/next";
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+
+import { AppChrome, appMetadata, documentViewport, siteViewport } from "./app-mode";
+import { ErrorsInit } from "./components/errors-init";
+import { PageFooter } from "./components/page-footer";
+import { PageLink } from "./components/page-link/page-link";
+import { TelemetryScripts } from "./components/telemetry-scripts";
+import { requestContext } from "./context";
+import { layoutOptions } from "./layout-options";
+import { ogImageUrl, searchProviderProps } from "./output";
+import type { SiteRuntime } from "./runtime";
+
+
+export function createRootLayout(site: SiteRuntime) {
+  async function generateMetadata(): Promise<Metadata> {
+    const ctx = await requestContext(site);
+    return { ...siteMetadata(site.seo, ctx.decision, ogImageUrl(site.generated.output, "/")), ...appMetadata(site) };
+  }
+
+  async function RootLayout(props: { children: ReactNode }) {
+    const ctx = await requestContext(site);
+    return (
+      <html lang={site.config.lang} suppressHydrationWarning>
+        <head>
+          <JsonLdScript site={site.seo} />
+          <TelemetryScripts site={site} ctx={ctx} />
+        </head>
+        <body className="flex min-h-screen flex-col">
+          <RootProvider components={{ Link: PageLink }} {...(site.chrome?.themeStorageKey === undefined ? {} : { theme: { storageKey: site.chrome.themeStorageKey } })} {...searchProviderProps(site.generated.output)}>
+            <AppChrome site={site}>{props.children}</AppChrome>
+          </RootProvider>
+          <ErrorsInit site={site} ctx={ctx} />
+        </body>
+      </html>
+    );
+  }
+
+  return { generateMetadata, RootLayout, viewport: siteViewport(site) };
+}
+
+/**
+ * `/docs/**`: Fumadocs' docs layout (sidebar from the page tree, header links from config), then the footer.
+ * `data-av-scroll-page`: inside an app-mode shell, docs still scroll as a document.
+ */
+export function createDocsLayout(site: SiteRuntime) {
+  function SiteDocsLayout(props: { children: ReactNode }) {
+    return (
+      <ScrollPage>
+        <DocsLayout tree={site.docs.pageTree} {...layoutOptions(site)}>
+          {props.children}
+        </DocsLayout>
+        <PageFooter site={site} />
+      </ScrollPage>
+    );
+  }
+  return { Layout: SiteDocsLayout, viewport: documentViewport(site) };
+}

package/src/mdx-config.d.ts

@@ -0,0 +1,2 @@
+export { remarkInlineMedia } from "@agentvibes/site-mdx/remark-inline-media";
+export { remarkMarkdownCopy } from "@agentvibes/site-mdx/remark-markdown-copy";

package/src/mdx-config.js

@@ -0,0 +1,7 @@
+/**
+ * What the generated `source.config.ts` imports. Node loads that file with
+ * packages external (and Node 20 cannot load `.ts`), so this entry is plain
+ * JavaScript; types are in mdx-config.d.ts.
+ */
+export { remarkInlineMedia } from "@agentvibes/site-mdx/remark-inline-media";
+export { remarkMarkdownCopy } from "@agentvibes/site-mdx/remark-markdown-copy";

package/src/mdx.tsx

@@ -0,0 +1,18 @@
+import { siteMdxComponents } from "@agentvibes/site-mdx";
+import type { MDXComponents } from "mdx/types";
+
+import { Hero } from "./components/hero/hero";
+import { ModuleCards } from "./components/module-cards/module-cards";
+import { SiteVideo, type SiteVideoProps } from "./components/site-video/site-video";
+import type { SiteRuntime } from "./runtime";
+
+/** MDX components for this site: `@agentvibes/site-mdx` plus the config-aware landing pieces and `Video` bound to the site's media. */
+export function mdxComponentsFor(site: SiteRuntime, overrides: MDXComponents = {}): MDXComponents {
+  const modules = site.config.sections.npm?.modules ?? [];
+  return siteMdxComponents({
+    Hero,
+    ModuleCards: () => <ModuleCards modules={modules} />,
+    Video: (props: SiteVideoProps) => <SiteVideo {...props} videos={site.generated.media.videos} />,
+    ...overrides
+  });
+}

package/src/nav.ts

@@ -0,0 +1,97 @@
+/**
+ * Header and footer links, derived from site.config (nothing hand-kept).
+ */
+import type { NavItem, PresetLink, SiteConfig, TelemetryKeys } from "@agentvibes/site-config";
+
+export type SiteLink = { readonly label: string; readonly href: string; readonly external: boolean };
+export type FooterColumn = { readonly title: string; readonly links: readonly SiteLink[] };
+
+function isExternal(href: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:/i.test(href);
+}
+
+function link(label: string, href: string): SiteLink {
+  return { label, href, external: isExternal(href) };
+}
+
+export function githubUrl(config: SiteConfig): string | undefined {
+  return config.links.github === undefined ? undefined : `https://github.com/${config.links.github}`;
+}
+
+export function hasDocs(config: SiteConfig): boolean {
+  return config.kind !== "landing" && config.sections.docs !== false;
+}
+
+export function hasChangelog(config: SiteConfig): boolean {
+  return config.sections.changelog !== undefined;
+}
+
+function flattenNav(items: readonly NavItem[]): SiteLink[] {
+  return items.flatMap((item) => ("href" in item ? [link(item.title, item.href)] : flattenNav(item.children)));
+}
+
+/** The header's main links: `nav: "auto"` → Docs, each npm module, Changelog; an explicit tree → its leaves. */
+export function headerLinks(config: SiteConfig): SiteLink[] {
+  const extra = config.links.extra.filter((item) => item.placement === "header").map((item) => link(item.label, item.href));
+  if (config.nav !== "auto") return [...flattenNav(config.nav), ...extra];
+  const auto: SiteLink[] = [];
+  if (hasDocs(config)) auto.push(link("Docs", "/docs"));
+  for (const mod of config.sections.npm?.modules ?? []) auto.push(link(mod.title, `/docs/${mod.id}`));
+  if (hasChangelog(config)) auto.push(link("Changelog", "/changelog"));
+  return [...auto, ...extra];
+}
+
+/** Repository links: GitHub, Issues, Releases (each switchable in `links`). */
+export function repositoryLinks(config: SiteConfig): SiteLink[] {
+  const base = githubUrl(config);
+  if (base === undefined) return [];
+  const links = [link("GitHub", base)];
+  if (config.links.issues) links.push(link("Issues", `${base}/issues`));
+  if (config.links.releases) links.push(link("Releases", `${base}/releases`));
+  return links;
+}
+
+export type FooterInput = {
+  readonly config: SiteConfig;
+  /** True when llms.txt is served (indexable request). */
+  readonly llms: boolean;
+  /** Preset internal links; passed only off the canonical production host. */
+  readonly internal: readonly PresetLink[];
+};
+
+export function footerColumns(input: FooterInput): FooterColumn[] {
+  const { config } = input;
+  const site: SiteLink[] = [];
+  if (hasDocs(config)) site.push(link("Docs", "/docs"));
+  for (const mod of config.sections.npm?.modules ?? []) site.push(link(mod.title, `/docs/${mod.id}`));
+  if (hasChangelog(config)) site.push(link("Changelog", "/changelog"));
+
+  const resources: SiteLink[] = [];
+  if (config.sections.npm !== undefined) {
+    for (const mod of config.sections.npm.modules) resources.push(link(`${mod.title} API`, `/docs/${mod.id}/jsdoc`));
+  }
+  if (input.llms) resources.push(link("llms.txt", "/llms.txt"));
+  resources.push(...config.links.extra.filter((item) => item.placement === "footer").map((item) => link(item.label, item.href)));
+
+  const columns: FooterColumn[] = [
+    { title: "Site", links: site },
+    { title: "Resources", links: resources },
+    { title: "Repository", links: repositoryLinks(config) },
+    { title: "Internal", links: input.internal.map((item) => link(item.label, item.href)) }
+  ];
+  return columns.filter((column) => column.links.length > 0);
+}
+
+/**
+ * Dashboards of the configured collectors, for the Internal footer column
+ * (rendered off canonical production only). Origins only: the collector hosts
+ * are known, deep links into their UIs are not part of any contract here.
+ */
+export function telemetryDashboards(keys: TelemetryKeys): PresetLink[] {
+  const links: PresetLink[] = [];
+  if (keys.umami.kind === "configured") links.push({ label: "Analytics (Umami)", href: new URL(keys.umami.host).origin });
+  if (keys.glitchtip.kind === "configured" && URL.canParse(keys.glitchtip.dsn)) {
+    links.push({ label: "Errors (GlitchTip)", href: new URL(keys.glitchtip.dsn).origin });
+  }
+  return links;
+}

package/src/og-route.tsx

@@ -0,0 +1,29 @@
+import { ogImage } from "@agentvibes/site-seo/og";
+
+import { catalog, findPage } from "./catalog";
+import { pathFromStaticSlug, staticSlugOf } from "./output";
+import type { SiteRuntime } from "./runtime";
+import { ogColors, siteTheme } from "./theme";
+
+type SlugContext = { params: Promise<{ slug?: string[] }> };
+
+/** Static output: one `.png` file per page, and `index.png` for the site. */
+export function createOgParams(site: SiteRuntime) {
+  return () => [{ slug: staticSlugOf("/", ".png") }, ...catalog(site).filter((page) => page.path !== "/").map((page) => ({ slug: staticSlugOf(page.path, ".png") }))];
+}
+
+/** `/og/<path>`: the Open Graph image of a page (`/og` for the site). */
+export function createOgRoute(site: SiteRuntime) {
+  return async function GET(_request: Request, context: SlugContext): Promise<Response> {
+    const { slug = [] } = await context.params;
+    const path = site.generated.output.kind === "static" ? pathFromStaticSlug(slug, ".png") : `/${slug.join("/")}`;
+    const page = slug.length === 0 || path === "/" ? undefined : findPage(site, path);
+    if (slug.length > 0 && path !== "/" && page === undefined) return new Response("Not found", { status: 404 });
+    return ogImage({
+      siteName: site.config.name,
+      title: page?.title ?? site.config.name,
+      description: page?.description ?? site.config.description,
+      colors: ogColors(siteTheme(site.preset))
+    });
+  };
+}

package/src/output.ts

@@ -0,0 +1,90 @@
+import type { OutputKind } from "@agentvibes/site-config";
+
+/**
+ * Where a built site runs. `server` is the default: Next on a server, every
+ * page rendered per request. `static` is `next build` with `output: "export"`,
+ * for hosts that only serve files, optionally under a sub-path. `origin` and
+ * `basePath` say where the files will be served from, since no request exists
+ * at build time to read them from.
+ */
+export type SiteOutput =
+  | { readonly kind: "server" }
+  | {
+      readonly kind: "static";
+      /** The origin the files are served from: indexing and errors treat it as the request's host. */
+      readonly origin: string;
+      /** The sub-path of the site on that origin, `""` at the root, else `/x/name` (no trailing slash). */
+      readonly basePath: string;
+    };
+
+export const SERVER_OUTPUT: SiteOutput = { kind: "server" };
+
+export class SiteOutputError extends Error {
+  override readonly name = "SiteOutputError";
+}
+
+/** Validated `static` output from the `--origin` and `--base-path` flags. */
+export function staticOutput(origin: string, basePath: string): SiteOutput {
+  if (!URL.canParse(origin) || new URL(origin).origin !== origin) {
+    throw new SiteOutputError(`--origin must be an origin (scheme + host, no path or trailing slash), got ${JSON.stringify(origin)}`);
+  }
+  if (basePath !== "" && !/^(\/[A-Za-z0-9._~-]+)+$/.test(basePath)) {
+    throw new SiteOutputError(`--base-path must be empty or look like /x/name (no trailing slash), got ${JSON.stringify(basePath)}`);
+  }
+  return { kind: "static", origin, basePath };
+}
+
+/** The old `prepare` flags. They override site.config's `output`, so existing build scripts keep working. */
+export type OutputFlags = { readonly static?: boolean | undefined; readonly origin?: string | undefined; readonly basePath?: string | undefined };
+
+/**
+ * The output a build uses: the flags if any, else site.config's `output`.
+ * A static site's origin is `siteUrl` unless `--origin` says where the
+ * files are served from (a preview or lab host).
+ */
+export function resolveOutput(configOutput: OutputKind, siteUrl: string, flags: OutputFlags): SiteOutput {
+  const kind: OutputKind = flags.static === true ? "static" : configOutput;
+  if (kind === "server") {
+    if (flags.origin !== undefined || flags.basePath !== undefined) {
+      throw new SiteOutputError('--origin and --base-path only apply to a static build: set output: "static" in site.config, or pass --static');
+    }
+    return SERVER_OUTPUT;
+  }
+  return staticOutput(flags.origin ?? new URL(siteUrl).origin, flags.basePath ?? "");
+}
+
+/** `path` as the browser must ask for it: Next adds the base path to its links, but not to plain URLs. */
+export function withBasePath(output: SiteOutput, path: string): string {
+  return output.kind === "static" ? `${output.basePath}${path}` : path;
+}
+
+/** The address of a page's Open Graph image; a static site has one PNG file per page. */
+export function ogImageUrl(output: SiteOutput, path: string): string {
+  if (output.kind === "server") return path === "/" ? "/og" : `/og${path}`;
+  // Absolute: metadataBase is the canonical site, which is not where a copy's files live.
+  return `${output.origin}${output.basePath}/og${path === "/" ? "/index" : path}.png`;
+}
+
+/** The address of a page's Markdown twin in `<link rel="alternate">`, for the same reason as {@link ogImageUrl}. */
+export function markdownAlternateUrl(output: SiteOutput, markdownPath: string): string {
+  return output.kind === "server" ? markdownPath : `${output.origin}${output.basePath}${markdownPath}`;
+}
+
+/** The URL path a static route's last segment stands for: `["docs", "init.md"]` with `.md` → `/docs/init`. */
+export function pathFromStaticSlug(slug: readonly string[], extension: string): string {
+  const joined = `/${slug.join("/")}`;
+  const path = joined.endsWith(extension) ? joined.slice(0, -extension.length) : joined;
+  return path === "/index" ? "/" : path;
+}
+
+/** `/docs/init` with `.md` → `["docs", "init.md"]`; `/` → `["index.md"]`. */
+export function staticSlugOf(path: string, extension: string): string[] {
+  const parts = path === "/" ? ["index"] : path.split("/").filter(Boolean);
+  const last = parts.pop() ?? "index";
+  return [...parts, `${last}${extension}`];
+}
+
+/** A static site has no search server: Fumadocs' default dialog loads the prebuilt index the search route exported. */
+export function searchProviderProps(output: SiteOutput) {
+  return output.kind === "server" ? {} : { search: { options: { type: "static" as const, api: withBasePath(output, "/api/search") } } };
+}

package/src/pages.tsx

@@ -0,0 +1,186 @@
+import { markdownPath } from "@agentvibes/site-llms";
+import { pageMetadata, type IndexingDecision } from "@agentvibes/site-seo";
+import { JsonLdScript } from "@agentvibes/site-seo/json-ld";
+import { DocsBody, DocsDescription, DocsPage, DocsTitle } from "fumadocs-ui/layouts/docs/page";
+import type { Metadata } from "next";
+import { PageLink as Link } from "./components/page-link/page-link";
+import { notFound, redirect } from "next/navigation";
+
+import { documentViewport } from "./app-mode";
+import { markdownAlternateUrl, ogImageUrl, withBasePath } from "./output";
+import { hasOwnTitle } from "./docs-title";
+import { ChangelogEntryView } from "./components/changelog-entry-view";
+import { HomeShell } from "./components/home-shell";
+import { JsdocView } from "./components/jsdoc-view/jsdoc-view";
+import { PageActions } from "./components/page-actions/page-actions";
+import { requestContext } from "./context";
+import { mdxComponentsFor } from "./mdx";
+import type { SiteRuntime } from "./runtime";
+
+type SlugParams = { params: Promise<{ slug?: string[] }> };
+type ModuleParams = { params: Promise<{ moduleId: string }> };
+
+function meta(site: SiteRuntime, decision: IndexingDecision, page: { title: string; description: string | undefined; path: string }): Metadata {
+  const output = site.generated.output;
+  return pageMetadata(
+    site.seo,
+    { title: page.title, description: page.description, path: page.path, markdownPath: markdownAlternateUrl(output, markdownPath(page.path)), ogImagePath: ogImageUrl(output, page.path) },
+    decision
+  );
+}
+
+function breadcrumbs(path: string, title: string): Array<{ name: string; path: string }> {
+  const parts = path.split("/").filter(Boolean);
+  return parts.map((part, index) => ({ name: index === parts.length - 1 ? title : part, path: `/${parts.slice(0, index + 1).join("/")}` }));
+}
+
+async function Actions(props: { site: SiteRuntime; path: string }) {
+  const ctx = await requestContext(props.site);
+  const md = withBasePath(props.site.generated.output, markdownPath(props.path));
+  return <PageActions markdownPath={md} markdownUrl={`${ctx.origin}${md}`} />;
+}
+
+/** `/docs/[[...slug]]`. */
+export function createDocsPage(site: SiteRuntime) {
+  async function generateMetadata(props: SlugParams): Promise<Metadata> {
+    const { slug } = await props.params;
+    const page = site.docs.getPage(slug ?? []);
+    if (page === undefined) notFound();
+    const ctx = await requestContext(site);
+    return meta(site, ctx.decision, { title: page.data.title ?? page.url, description: page.data.description, path: page.url });
+  }
+
+  async function Page(props: SlugParams) {
+    const { slug } = await props.params;
+    const page = site.docs.getPage(slug ?? []);
+    if (page === undefined) notFound();
+    const Body = page.data.body;
+    const title = page.data.title ?? page.url;
+    const ownTitle = hasOwnTitle(page.data.toc);
+    return (
+      <DocsPage toc={page.data.toc} full={page.data.full ?? false}>
+        {ownTitle ? null : <DocsTitle>{title}</DocsTitle>}
+        {ownTitle || page.data.description === undefined ? null : <DocsDescription>{page.data.description}</DocsDescription>}
+        <Actions site={site} path={page.url} />
+        <DocsBody>
+          <Body components={mdxComponentsFor(site, { a: site.docs.relativeLink(page) })} />
+        </DocsBody>
+        <JsonLdScript site={site.seo} page={{ title, description: page.data.description, path: page.url, breadcrumbs: breadcrumbs(page.url, title) }} />
+      </DocsPage>
+    );
+  }
+
+  /** Static output: every page of the collection, as a file. */
+  function generateStaticParams() {
+    return site.docs.getPages().map((page) => ({ slug: [...page.slugs] }));
+  }
+
+  return { generateMetadata, generateStaticParams, Page, viewport: documentViewport(site) };
+}
+
+function moduleOf(site: SiteRuntime, moduleId: string) {
+  return site.config.sections.npm?.modules.find((mod) => mod.id === moduleId);
+}
+
+/** `/docs/[moduleId]/jsdoc`: the API reference of an npm module. */
+export function createJsdocPage(site: SiteRuntime) {
+  async function generateMetadata(props: ModuleParams): Promise<Metadata> {
+    const { moduleId } = await props.params;
+    const mod = moduleOf(site, moduleId);
+    if (mod === undefined) notFound();
+    const ctx = await requestContext(site);
+    return meta(site, ctx.decision, { title: `${mod.title} API reference`, description: `Exports of ${mod.npm.name}.`, path: `/docs/${mod.id}/jsdoc` });
+  }
+
+  async function Page(props: ModuleParams) {
+    const { moduleId } = await props.params;
+    const mod = moduleOf(site, moduleId);
+    if (mod === undefined) notFound();
+    const path = `/docs/${mod.id}/jsdoc`;
+    return (
+      <DocsPage>
+        <DocsTitle>{mod.title} API reference</DocsTitle>
+        <DocsDescription>
+          Exports of <code>{mod.npm.name}</code>. <Link href={`/docs/${mod.id}`}>Back to the module</Link>
+        </DocsDescription>
+        <Actions site={site} path={path} />
+        <DocsBody>
+          <JsdocView items={site.generated.jsdoc.modules[mod.id]?.items ?? []} />
+        </DocsBody>
+      </DocsPage>
+    );
+  }
+
+  function generateStaticParams() {
+    return (site.config.sections.npm?.modules ?? []).map((mod) => ({ moduleId: mod.id }));
+  }
+
+  return { generateMetadata, generateStaticParams, Page, viewport: documentViewport(site) };
+}
+
+/** `/changelog`: every package's CHANGELOG.md (written by changesets). */
+export function createChangelogPage(site: SiteRuntime) {
+  async function generateMetadata(): Promise<Metadata> {
+    const ctx = await requestContext(site);
+    return meta(site, ctx.decision, { title: "Changelog", description: `Release notes of ${site.config.name}.`, path: "/changelog" });
+  }
+
+  function Page() {
+    return (
+      <HomeShell site={site}>
+        <div className="prose mx-auto max-w-3xl py-12">
+          <h1>Changelog</h1>
+          <Actions site={site} path="/changelog" />
+          {site.generated.changelog.length === 0 ? <p>No releases yet.</p> : null}
+          {site.generated.changelog.map((entry) => (
+            <ChangelogEntryView key={entry.packageName} packageName={entry.packageName} markdown={entry.markdown} />
+          ))}
+        </div>
+      </HomeShell>
+    );
+  }
+
+  return { generateMetadata, Page, viewport: documentViewport(site) };
+}
+
+/** `/`: `content/pages/index.mdx` in the home layout; without it, a docs site redirects to `/docs`. */
+export function createLandingPage(site: SiteRuntime) {
+  async function generateMetadata(): Promise<Metadata> {
+    const page = site.pages.getPage([]);
+    const ctx = await requestContext(site);
+    return meta(site, ctx.decision, { title: page?.data.title ?? site.config.name, description: page?.data.description ?? site.config.description, path: "/" });
+  }
+
+  function Page() {
+    const page = site.pages.getPage([]);
+    if (page === undefined) {
+      if (site.config.kind === "landing") notFound();
+      redirect("/docs");
+    }
+    const Body = page.data.body;
+    return (
+      <HomeShell site={site}>
+        <div className="prose max-w-none">
+          <Body components={mdxComponentsFor(site)} />
+        </div>
+      </HomeShell>
+    );
+  }
+
+  return { generateMetadata, Page, viewport: documentViewport(site) };
+}
+
+export function createNotFoundPage(site: SiteRuntime) {
+  return function NotFound() {
+    return (
+      <HomeShell site={site}>
+        <div className="mx-auto max-w-xl py-24 text-center">
+          <h1 className="mb-3 text-3xl font-semibold">Page not found</h1>
+          <p className="text-fd-muted-foreground">
+            <Link href="/">Back to {site.config.name}</Link>
+          </p>
+        </div>
+      </HomeShell>
+    );
+  };
+}

package/src/prepare/assets.ts

@@ -0,0 +1,98 @@
+/**
+ * `public/_av/`: the static files prepare owns: the terminal font
+ * (`fonts/`), the app icons rendered from one SVG (`icons/`, with `app.pwa`)
+ * and the videos of `sections.media.videos` (`media/`). Binary files cannot
+ * carry the generated-file header, so the directory carries it: a marker file
+ * says prepare owns it, and its `.gitignore` keeps it out of git. A
+ * `public/_av/` without the marker belongs to the author and is never touched.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import { ICONS_DIR } from "@agentvibes/site-app";
+import { imageSize, renderIcons } from "@agentvibes/site-app/icons";
+import { copyTerminalFonts } from "@agentvibes/site-mdx/node";
+
+import type { MediaData, VideoEntry } from "../data";
+import { GENERATED_MARKER } from "./files";
+
+export const ASSETS_DIR = "public/_av";
+export const ASSETS_MARKER_FILE = ".agentvibes-generated";
+const MEDIA_URL = "/_av/media/";
+
+export class AssetsError extends Error {
+  override readonly name = "AssetsError";
+}
+
+export type AssetsPlan = {
+  /** The app icon and the background its maskable icons are drawn on, with `app.pwa`. */
+  readonly icon: { readonly svgFile: string; readonly background: string } | undefined;
+  /** `sections.media.videos`, resolved. */
+  readonly videosDir: string | undefined;
+};
+
+function claimDir(dir: string): void {
+  if (fs.existsSync(dir) && !fs.existsSync(path.join(dir, ASSETS_MARKER_FILE))) {
+    throw new AssetsError(`${dir} exists and was not written by agentvibes-site prepare; move it away so prepare can own it.`);
+  }
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, ASSETS_MARKER_FILE), `${GENERATED_MARKER}: the whole directory is rewritten on every run.\n`);
+  fs.writeFileSync(path.join(dir, ".gitignore"), `# ${GENERATED_MARKER}\n*\n`);
+}
+
+const VIDEO_FILE = /^(?<name>[\w.-]+?)(?<compact>-compact)?\.(?<ext>mp4|webm|png|jpe?g|webp|vtt)$/;
+
+type Draft = { -readonly [K in keyof VideoEntry]?: VideoEntry[K] };
+
+function assign(draft: Draft, file: string, compact: boolean, ext: string): void {
+  const url = `${MEDIA_URL}${file}`;
+  if (ext === "mp4") draft[compact ? "compactMp4" : "mp4"] = url;
+  else if (ext === "webm") draft[compact ? "compactWebm" : "webm"] = url;
+  else if (ext === "vtt" && !compact) draft.captions = url;
+  else if (!compact) draft.poster = url;
+}
+
+/**
+ * Copies the videos into `media/` and lists them by name: `deploy.mp4`,
+ * `deploy.webm`, `deploy.png` (poster), `deploy.vtt` (captions),
+ * `deploy-compact.{mp4,webm}`. Every video needs its H.264 MP4.
+ */
+async function collectVideos(sourceDir: string, outDir: string): Promise<MediaData["videos"]> {
+  if (!fs.existsSync(sourceDir)) throw new AssetsError(`sections.media.videos: ${sourceDir} does not exist`);
+  fs.mkdirSync(outDir, { recursive: true });
+  const drafts = new Map<string, { draft: Draft; posterFile?: string }>();
+  for (const file of fs.readdirSync(sourceDir).sort()) {
+    const match = VIDEO_FILE.exec(file);
+    const name = match?.groups?.["name"];
+    const ext = match?.groups?.["ext"];
+    if (name === undefined || ext === undefined) continue;
+    fs.copyFileSync(path.join(sourceDir, file), path.join(outDir, file));
+    const entry = drafts.get(name) ?? { draft: {} };
+    const compact = match?.groups?.["compact"] !== undefined;
+    assign(entry.draft, file, compact, ext);
+    if (!compact && /^(png|jpe?g|webp)$/.test(ext)) entry.posterFile = path.join(sourceDir, file);
+    drafts.set(name, entry);
+  }
+  const videos: Record<string, VideoEntry> = {};
+  for (const [name, { draft, posterFile }] of drafts) {
+    const mp4 = draft.mp4;
+    if (mp4 === undefined) throw new AssetsError(`sections.media.videos: ${name} has no ${name}.mp4 (H.264); iPhones play nothing else`);
+    const size = posterFile === undefined ? undefined : await imageSize(posterFile);
+    videos[name] = { ...draft, mp4, ...(size ?? {}) };
+  }
+  return videos;
+}
+
+/** Rewrites `public/_av/` and returns the media manifest baked into the site data. */
+export async function writeAssets(siteDir: string, plan: AssetsPlan): Promise<MediaData> {
+  const dir = path.join(siteDir, ASSETS_DIR);
+  claimDir(dir);
+  copyTerminalFonts(path.join(dir, "fonts"));
+  if (plan.icon !== undefined) {
+    if (!fs.existsSync(plan.icon.svgFile)) throw new AssetsError(`app.pwa.icon: ${plan.icon.svgFile} does not exist`);
+    await renderIcons(plan.icon.svgFile, path.join(siteDir, "public", ICONS_DIR), plan.icon.background);
+  }
+  const videos = plan.videosDir === undefined ? {} : await collectVideos(plan.videosDir, path.join(dir, "media"));
+  return { videos };
+}

package/src/prepare/author-next-config.ts

@@ -0,0 +1,46 @@
+/**
+ * Reads the site's own `site.next.mjs` outside of `next build`, for the two steps that must know what it asks for:
+ * `prepare` (reject `headers()` in a static export before the build) and `finish-static` (turn `redirects()` into pages).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { z } from "zod";
+
+import { AUTHOR_NEXT_CONFIG } from "./templates";
+
+/**
+ * The shape of the config the generated next.config.mjs hands to the author's hook. `transpilePackages` is the
+ * real list there; a hook that spreads or appends to it must not crash here, and nothing we read depends on its content.
+ */
+const AUTHOR_BASE_CONFIG = { reactStrictMode: true, transpilePackages: [] as string[] };
+
+const AuthorModule = z.object({ default: z.function() });
+// ast-grep-ignore: zod-optional-nullable -- the author's file is a NextConfig, where redirects and headers are optional keys
+const AuthorConfig = z.object({ redirects: z.function().optional(), headers: z.function().optional() }).passthrough();
+// strict: a redirect conditioned on `has` or `missing` needs a server, and must not silently become unconditional.
+// ast-grep-ignore: zod-optional-nullable -- permanent and statusCode are optional in Next's redirect type
+const AuthorRedirects = z.array(z.object({ source: z.string(), destination: z.string(), permanent: z.boolean().optional(), statusCode: z.number().optional() }).strict());
+const AuthorHeaders = z.array(z.object({ source: z.string() }).passthrough());
+
+export type AuthorRedirect = z.infer<typeof AuthorRedirects>[number];
+
+/** What the hook returned: no file and a file that sets neither are the same to the callers. */
+export type AuthorNextConfig = {
+  readonly redirects: () => Promise<AuthorRedirect[]>;
+  readonly headers: () => Promise<{ source: string }[]>;
+};
+
+const NONE: AuthorNextConfig = { redirects: async () => [], headers: async () => [] };
+
+export async function loadAuthorNextConfig(siteDir: string): Promise<AuthorNextConfig> {
+  const file = path.join(siteDir, AUTHOR_NEXT_CONFIG);
+  if (!fs.existsSync(file)) return NONE;
+  const imported = AuthorModule.parse(await import(pathToFileURL(file).href));
+  const config = AuthorConfig.parse(await imported.default({ ...AUTHOR_BASE_CONFIG, transpilePackages: [] }));
+  return {
+    redirects: async () => (config.redirects === undefined ? [] : AuthorRedirects.parse(await config.redirects())),
+    headers: async () => (config.headers === undefined ? [] : AuthorHeaders.parse(await config.headers()))
+  };
+}

package/src/prepare/changelog.ts

@@ -0,0 +1,17 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { ChangelogEntry } from "../data";
+import { readPackageJson } from "./jsdoc-extract";
+
+/** CHANGELOG.md (written by changesets) of each package directory that has one, title line removed. */
+export function readChangelogs(repoRoot: string, packageDirs: readonly string[]): ChangelogEntry[] {
+  return packageDirs.flatMap((dir) => {
+    const abs = path.resolve(repoRoot, dir);
+    const file = path.join(abs, "CHANGELOG.md");
+    if (!fs.existsSync(file)) return [];
+    const markdown = fs.readFileSync(file, "utf8").replace(/^#\s+[^\n]*\n+/, "");
+    const packageName = readPackageJson(abs)?.name ?? path.basename(abs);
+    return [{ packageName, markdown }];
+  });
+}