@publish.os/nextjs 0.0.1-alpha.90 → 0.0.1-alpha.92

package/compiler-assets/nextjs/defaults/group/index.tsx

@@ -1,43 +1,48 @@
 import { Link } from "@components/ui/link";
 import type {
   IndexPageProps,
-  PageNode,
-  TreeNode,
+  NavigationNode,
+  NavigationPageNode,
 } from "@publish.os/nextjs/types";
 import { log } from "@source/_internal/logger";
 
-function pageNodes(nodes: TreeNode[]): PageNode[] {
+function pageNodes(nodes: NavigationNode[]): NavigationPageNode[] {
   return nodes.flatMap((node) => {
     if (node.type === "page") return [node];
-    if (node.type === "section" || node.type === "folder") {
+    if (
+      node.type === "section" ||
+      node.type === "folder" ||
+      node.type === "group"
+    ) {
       return pageNodes(node.children);
     }
+    if (node.type === "view") return pageNodes(node.items);
     return [];
   });
 }
 
 export default function GroupPage(props: IndexPageProps) {
   log.debug("[default:group-page]", props);
-  const { node, tree } = props;
-  const pages = pageNodes(tree);
+  const { node, navigation } = props;
+  const pages = pageNodes(navigation.items);
 
   return (
     <div className="flex min-h-[calc(100vh-var(--layout-global-nav-height))] min-w-0 items-start justify-center px-6 pb-16 pt-[clamp(5rem,18vh,10rem)] text-foreground-1 lg:px-10 supports-[height:100dvh]:min-h-[calc(100dvh-var(--layout-global-nav-height))] supports-[top:anchor-size(--global-navbar_height)]:min-h-[calc(100vh-anchor-size(--global-navbar_height,3.5rem))] supports-[top:anchor-size(--global-navbar_height)]:supports-[height:100dvh]:min-h-[calc(100dvh-anchor-size(--global-navbar_height,3.5rem))]">
       <div className="w-full max-w-md">
         <p className="mb-6 text-sm font-semibold text-foreground-1">
-          {node.title}
+          {node.label}
         </p>
         <h1 className="max-w-sm text-balance text-xl font-semibold leading-7 tracking-tight text-foreground-1">
           Browse the pages in this section.
         </h1>
 
         {pages.length > 0 ? (
-          <nav aria-label={`${node.title} pages`} className="mt-8">
+          <nav aria-label={`${node.label} pages`} className="mt-8">
             <ul className="flex flex-col gap-2 text-sm">
               {pages.map((page) => (
-                <li key={`${page.group}:${page.fileID}`}>
-                  <Link href={page.path} rightIcon="->" size="sm">
-                    {page.title}
+                <li key={page.id}>
+                  <Link href={page.href} rightIcon="->" size="sm">
+                    {page.label}
                   </Link>
                 </li>
               ))}

package/compiler-assets/nextjs/defaults/group/layout.tsx

@@ -3,13 +3,17 @@ import type { LayoutProps } from "@publish.os/nextjs/types";
 import { log } from "@source/_internal/logger";
 
 export default function GroupLayout(props: LayoutProps) {
-  const { children, currentPath, group, node, site, tree } = props;
+  const { children, currentPath, group, node, navigation } = props;
   log.debug("[default:group-layout]", { currentPath, group });
 
   return (
     <section className="mx-auto grid min-h-[calc(100vh-var(--layout-global-nav-height))] w-full max-w-(--layout-site-max-width) grid-cols-1 border-x border-stroke-3 bg-surface-1 md:grid-cols-[var(--layout-sidebar-width)_minmax(0,1fr)] xl:grid-cols-[var(--layout-sidebar-width)_minmax(0,1fr)_var(--layout-toc-width)] supports-[height:100dvh]:min-h-[calc(100dvh-var(--layout-global-nav-height))] supports-[top:anchor-size(--global-navbar_height)]:min-h-[calc(100vh-anchor-size(--global-navbar_height,3.5rem))] supports-[top:anchor-size(--global-navbar_height)]:supports-[height:100dvh]:min-h-[calc(100dvh-anchor-size(--global-navbar_height,3.5rem))]">
       <aside className="fixed top-(--layout-global-nav-height) z-content hidden h-[calc(100vh-var(--layout-global-nav-height))] min-h-0 border-l border-stroke-3 bg-surface-1 md:left-[max(0px,calc((100%-var(--layout-site-max-width))/2))] md:flex md:w-(--layout-sidebar-width) supports-[height:100dvh]:h-[calc(100dvh-var(--layout-global-nav-height))] supports-[top:anchor-size(--global-navbar_height)]:top-[anchor-size(--global-navbar_height,3.5rem)] supports-[top:anchor-size(--global-navbar_height)]:h-[calc(100vh-anchor-size(--global-navbar_height,3.5rem))] supports-[top:anchor-size(--global-navbar_height)]:supports-[height:100dvh]:h-[calc(100dvh-anchor-size(--global-navbar_height,3.5rem))]">
-        <Sidebar currentPath={currentPath} title={node.title} tree={tree} />
+        <Sidebar
+          currentPath={currentPath}
+          title={node.label}
+          navigation={navigation}
+        />
       </aside>
       <main
         className="flex min-h-0 min-w-0 flex-1 scroll-mt-[calc(var(--layout-global-nav-height)+1rem)] flex-col bg-surface-1 md:col-start-2"
@@ -18,10 +22,6 @@ export default function GroupLayout(props: LayoutProps) {
       >
         {children}
       </main>
-      <aside
-        aria-label={`${site.name} secondary navigation`}
-        className="hidden bg-surface-1 xl:block"
-      />
     </section>
   );
 }

package/compiler-assets/nextjs/defaults/group/page.tsx

@@ -1,5 +1,6 @@
-import { AgentActions } from "@components/blocks/AgentActions";
+import { AgentActions } from "@components/blocks/agent-actions";
 import { NextPrev } from "@components/blocks/next-prev";
+import { Toc } from "@components/blocks/toc";
 import { MDX } from "@publish.os/nextjs/mdx";
 import type { PageProps } from "@publish.os/nextjs/types";
 import { log } from "@source/_internal/logger";
@@ -7,35 +8,44 @@ import { log } from "@source/_internal/logger";
 export default async function ContentPage(props: PageProps) {
   log.debug("[default:content-page]", props);
   const sourceUrl =
-    typeof props.page.meta.sourceUrl === "string"
-      ? props.page.meta.sourceUrl
-      : typeof props.page.meta.githubUrl === "string"
-        ? props.page.meta.githubUrl
+    typeof props.page.frontmatter.sourceUrl === "string"
+      ? props.page.frontmatter.sourceUrl
+      : typeof props.page.frontmatter.githubUrl === "string"
+        ? props.page.frontmatter.githubUrl
         : undefined;
 
   return (
-    <div className="flex min-h-[calc(100vh-var(--layout-global-nav-height))] min-w-0 flex-1 flex-col px-6 py-10 text-foreground-1 lg:px-10 supports-[height:100dvh]:min-h-[calc(100dvh-var(--layout-global-nav-height))] supports-[top:anchor-size(--global-navbar_height)]:min-h-[calc(100vh-anchor-size(--global-navbar_height,3.5rem))] supports-[top:anchor-size(--global-navbar_height)]:supports-[height:100dvh]:min-h-[calc(100dvh-anchor-size(--global-navbar_height,3.5rem))]">
-      <div className="mx-auto flex w-full max-w-(--layout-content-max-width) flex-1 flex-col">
-        <article className="min-h-0 min-w-0 flex-1">
-          <h1 className="text-3xl font-semibold tracking-tight text-foreground-1">
-            {props.page.title}
-          </h1>
-          <AgentActions
-            className="mt-4"
-            markdown={props.page.body}
-            pagePath={props.currentPath}
-            siteUrl={props.site.origin}
-            sourceUrl={sourceUrl}
+    <div className="relative flex min-h-[calc(100vh-var(--layout-global-nav-height))] min-w-0 flex-1 flex-col text-foreground-1 supports-[height:100dvh]:min-h-[calc(100dvh-var(--layout-global-nav-height))] supports-[top:anchor-size(--global-navbar_height)]:min-h-[calc(100vh-anchor-size(--global-navbar_height,3.5rem))] supports-[top:anchor-size(--global-navbar_height)]:supports-[height:100dvh]:min-h-[calc(100dvh-anchor-size(--global-navbar_height,3.5rem))]">
+      <Toc
+        content={props.page.body}
+        desktopClassName="xl:absolute xl:inset-y-0 xl:start-full xl:w-(--layout-toc-width) xl:px-3 xl:py-10"
+        desktopListClassName="xl:sticky xl:top-[calc(var(--layout-global-nav-height)_+_1.5rem)] xl:max-h-[calc(100dvh-var(--layout-global-nav-height)-3rem)] xl:overflow-y-auto supports-[top:anchor-size(--global-navbar_height)]:xl:top-[calc(anchor-size(--global-navbar_height,3.5rem)_+_1.5rem)] supports-[top:anchor-size(--global-navbar_height)]:xl:max-h-[calc(100dvh-anchor-size(--global-navbar_height,3.5rem)-3rem)]"
+        mobileClassName="sticky top-(--layout-global-nav-height) z-nav supports-[top:anchor-size(--global-navbar_height)]:top-[anchor-size(--global-navbar_height,3.5rem)]"
+        mobileQuery="(max-width: 1279px)"
+      />
+      <div className="flex min-w-0 flex-1 flex-col px-6 py-10 lg:px-10">
+        <div className="mx-auto flex w-full max-w-(--layout-content-max-width) flex-1 flex-col">
+          <article className="min-h-0 min-w-0 flex-1">
+            <h1 className="text-3xl font-semibold tracking-tight text-foreground-1">
+              {props.page.frontmatter.title}
+            </h1>
+            <AgentActions
+              className="mt-4"
+              markdownRevision={props.markdownRevision}
+              pagePath={props.currentPath}
+              siteUrl={props.site.origin}
+              sourceUrl={sourceUrl}
+            />
+            <div className="mt-6">
+              <MDX page={props.page} />
+            </div>
+          </article>
+          <NextPrev
+            className="mt-auto pt-12"
+            currentPath={props.currentPath}
+            navigation={props.navigation}
           />
-          <div className="mt-6">
-            <MDX page={props.page} />
-          </div>
-        </article>
-        <NextPrev
-          className="mt-auto pt-12"
-          currentPath={props.currentPath}
-          tree={props.tree}
-        />
+        </div>
       </div>
     </div>
   );

package/compiler-assets/nextjs/defaults/project/next.config.mjs

@@ -4,37 +4,47 @@ import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const projectRoot = dirname(fileURLToPath(import.meta.url));
-const ASSET_PREFIX = "__PUBLISHOS_ASSET_PREFIX__";
+const INTERNAL_PREFIX = "__PUBLISHOS_INTERNAL_PREFIX__";
+const SOURCE_ASSET_PREFIX = "__PUBLISHOS_SOURCE_ASSET_PREFIX__";
 const IMAGE_OPTIMIZER_PATH = "__PUBLISHOS_IMAGE_PATH__";
 const NEXT_IMAGE_OPTIMIZER_PATH = "__PUBLISHOS_NEXT_IMAGE_PATH__";
 
 /** @type {import("next").NextConfig} */
 export default {
-  assetPrefix: ASSET_PREFIX,
+  env: { PUBLISHOS_SITE_BUILD_TIME: new Date().toISOString() },
+  assetPrefix: INTERNAL_PREFIX,
   cacheComponents: true,
-  partialPrefetching: false,
+  // Preserve loopback origins so internal rewrites do not proxy back into this app.
+  skipProxyUrlNormalize: true,
+  experimental: { globalNotFound: true },
+  partialPrefetching: true,
+  // macOS native notifications can delay preview updates. Use Next's fallback.
+  watchOptions:
+    process.platform === "darwin" ? { pollIntervalMs: 1_000 } : undefined,
   // Relocating Shiki as an external loses its pnpm-owned dependencies.
   transpilePackages: ["shiki"],
   turbopack: {
     resolveAlias: {
       "@publish.os/nextjs/mdx": "./source/.publishos/mdx.tsx",
+      "next/image": "@publish.os/nextjs/kernel/components/next-image",
+      ...__PUBLISHOS_COMPONENT_ALIASES__,
     },
     root: projectRoot,
   },
+  webpack(config) {
+    config.resolve.alias["next/image"] =
+      "@publish.os/nextjs/kernel/components/next-image";
+    return config;
+  },
   images: {
     dangerouslyAllowSVG: false,
     deviceSizes: [640, 828, 1080, 1200, 1600, 1920, 2560, 3840],
     formats: ["image/webp"],
     imageSizes: [32, 48, 64, 96, 128, 256, 384],
     path: IMAGE_OPTIMIZER_PATH,
-    localPatterns: [
-      {
-        pathname: `${ASSET_PREFIX}/_publishos/assets/**/images/**`,
-        search: "",
-      },
-      { pathname: `${ASSET_PREFIX}/assets/images/**`, search: "" },
-    ],
-    minimumCacheTTL: 2678400,
+    localPatterns: [{ pathname: `${SOURCE_ASSET_PREFIX}/**` }],
+    remotePatterns: [],
+    minimumCacheTTL: 0,
     qualities: [50, 60, 75, 85, 95, 100],
   },
   async rewrites() {

package/compiler-assets/nextjs/defaults/project/tsconfig.json.template

@@ -4,6 +4,7 @@
     "lib": ["dom", "dom.iterable", "esnext"],
     "module": "esnext",
     "moduleResolution": "bundler",
+    "jsxImportSource": "@publish.os/nextjs",
     "jsx": "react-jsx",
     "allowJs": true,
     "strict": true,
@@ -17,6 +18,15 @@
     "paths": {
       "@app/*": ["./app/*"],
       "@publish.os/nextjs/mdx": ["./source/.publishos/mdx"],
+      "@publish.os/nextjs/components/ui/button": [
+        "./node_modules/@publish.os/nextjs/dist/kernel/components/ui/button"
+      ],
+      "@publish.os/nextjs/components/blocks/toc": [
+        "./node_modules/@publish.os/nextjs/dist/kernel/components/blocks/toc"
+      ],
+      "@publish.os/nextjs/components/blocks/agent-actions": [
+        "./node_modules/@publish.os/nextjs/dist/kernel/components/blocks/agent-actions"
+      ],
       "@components/*": [
         "./source/components/*",
         "./node_modules/@publish.os/nextjs/dist/kernel/components/*"

package/compiler-assets/nextjs/defaults/root/css/components/code-block.css

@@ -0,0 +1,18 @@
+[data-slot="copy-code-button"] {
+  transition: opacity 150ms ease-out;
+}
+
+@media (hover: hover) and (pointer: fine) and (any-pointer: fine) and (
+    any-hover: hover
+  ) and (not (any-pointer: coarse)) {
+  [data-slot="code-block"]:not(:hover):not(:focus-within)
+    [data-slot="copy-code-button"]:not([data-copied="true"]) {
+    opacity: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-slot="copy-code-button"] {
+    transition: none;
+  }
+}

package/compiler-assets/nextjs/defaults/root/index.tsx

@@ -1,25 +1,30 @@
 import { Link } from "@components/ui/link";
 import type {
-  LinkNode,
+  NavigationGroupNode,
+  NavigationLinkNode,
   RootPageProps,
-  SectionNode,
-  TreeNode,
 } from "@publish.os/nextjs/types";
 import { log } from "@source/_internal/logger";
 
-type RootNavNode = LinkNode | (SectionNode & { path: string });
+type RootNavNode = NavigationLinkNode | NavigationGroupNode;
 
-function rootNavNodes(nodes: TreeNode[]): RootNavNode[] {
+function rootNavNodes(
+  nodes: RootPageProps["navigation"]["items"],
+): RootNavNode[] {
   return nodes.filter((node): node is RootNavNode => {
     if (node.type === "link") return true;
-    return node.type === "section" && typeof node.path === "string";
+    return (
+      node.type === "group" &&
+      node.presentation === "page" &&
+      Boolean(node.href)
+    );
   });
 }
 
 export default function HomePage(props: RootPageProps) {
   log.debug("[default:root-page]", props);
-  const { site, tree } = props;
-  const navNodes = rootNavNodes(tree);
+  const { site, navigation } = props;
+  const navNodes = rootNavNodes(navigation.items);
 
   return (
     <section className="mx-auto grid min-h-[calc(100vh-var(--layout-global-nav-height))] w-full max-w-(--layout-site-max-width) grid-cols-1 border-x border-stroke-3 bg-surface-1 md:grid-cols-[var(--layout-sidebar-width)_minmax(0,1fr)_var(--layout-toc-width)] supports-[height:100dvh]:min-h-[calc(100dvh-var(--layout-global-nav-height))] supports-[top:anchor-size(--global-navbar_height)]:min-h-[calc(100vh-anchor-size(--global-navbar_height,3.5rem))] supports-[top:anchor-size(--global-navbar_height)]:supports-[height:100dvh]:min-h-[calc(100dvh-anchor-size(--global-navbar_height,3.5rem))]">
@@ -45,11 +50,11 @@ export default function HomePage(props: RootPageProps) {
                   <li key={node.id}>
                     {node.type === "link" ? (
                       <Link href={node.href} rightIcon="->" size="sm">
-                        {node.title}
+                        {node.label}
                       </Link>
                     ) : (
-                      <Link href={node.path} rightIcon="->" size="sm">
-                        {node.title}
+                      <Link href={node.href} rightIcon="->" size="sm">
+                        {node.label}
                       </Link>
                     )}
                   </li>

package/compiler-assets/nextjs/defaults/root/layout.tsx

@@ -4,10 +4,10 @@ import { faviconsAndLogos } from "@source/.publishos/favicons-and-logos.generate
 import { log } from "@source/_internal/logger";
 
 export default function DefaultRootLayout(props: RootLayoutProps) {
-  const { children, site, tree } = props;
+  const { children, site, navigation } = props;
   log.debug("[default:root-layout]", {
     site: site.name,
-    treeItems: tree.length,
+    navigationItems: navigation.items.length,
   });
 
   return (
@@ -18,7 +18,11 @@ export default function DefaultRootLayout(props: RootLayoutProps) {
       >
         Skip to content
       </a>
-      <Navbar logo={faviconsAndLogos.logo} site={site} tree={tree} />
+      <Navbar
+        logo={faviconsAndLogos.logo}
+        site={site}
+        navigation={navigation}
+      />
       <div className="flex w-full flex-1 flex-col">{children}</div>
     </div>
   );

package/compiler-assets/nextjs/shims/agent-user-agents.ts

@@ -0,0 +1,65 @@
+// HTTP User-Agent product names that select Markdown when Accept leaves a tie.
+// Keep crawler names separate from general HTTP clients. A name is a hint, not
+// proof of identity. Check vendor documentation before adding a crawler.
+const AI_CRAWLERS = [
+  // https://developers.openai.com/api/docs/bots
+  "OAI-SearchBot",
+  "GPTBot",
+  "ChatGPT-User",
+  // https://support.claude.com/en/articles/8896518
+  "ClaudeBot",
+  "Claude-SearchBot",
+  "Claude-User",
+  // https://docs.perplexity.ai/docs/resources/perplexity-crawlers
+  "PerplexityBot",
+  "Perplexity-User",
+  // https://developers.google.com/crawling/docs/crawlers-fetchers/google-user-triggered-fetchers
+  "Google-Agent",
+  "Google-GeminiNotebook",
+  // https://developers.google.com/crawling/docs/crawlers-fetchers/google-common-crawlers
+  "Google-CloudVertexBot",
+];
+
+// General HTTP clients follow the existing Markdown tie-break policy.
+const HTTP_CLIENTS = [
+  "axios",
+  "got",
+  "node-fetch",
+  "undici",
+  "curl",
+  "wget",
+  "python-requests",
+  "httpx",
+  "aiohttp",
+];
+
+// Other client product names are not verified crawler identities.
+const CLIENT_PRODUCTS = [
+  "claude-code",
+  "claude",
+  "cursor",
+  "chatgpt",
+  "openai",
+  "perplexity",
+  "anthropic-ai",
+];
+
+const SUPPORTED_PRODUCTS = new Set(
+  [...AI_CRAWLERS, ...HTTP_CLIENTS, ...CLIENT_PRODUCTS].map((name) =>
+    name.toLowerCase(),
+  ),
+);
+
+export function isMarkdownClient(userAgent: string): boolean {
+  // Match whole product names, including those inside a compatible comment.
+  // A preceding slash is excluded so a URL in a comment is not a product.
+  const products = /(?:^|[\s(;])([A-Za-z0-9!#$%&'*+.^_`|~-]+)(?=\/|[\s;)]|$)/g;
+  for (
+    let product = products.exec(userAgent);
+    product;
+    product = products.exec(userAgent)
+  ) {
+    if (SUPPORTED_PRODUCTS.has(product[1].toLowerCase())) return true;
+  }
+  return false;
+}

package/compiler-assets/nextjs/shims/document.tsx

@@ -0,0 +1,46 @@
+import { Providers } from "@app/providers";
+import manifest from "@manifest";
+import { preloadRootFonts, rootFontClassName } from "@source/.fonts.generated";
+import RootLayout from "@source/layout";
+import { type ComponentType, Fragment, type ReactNode } from "react";
+import "@source/.fonts.generated.css";
+import "@app/globals.css";
+
+/** Shared document and authored shell for successful pages and routing-level 404s. */
+export default function SiteDocument({
+  children,
+  head,
+  beforeShell,
+  bodyWrapper: BodyWrapper = Fragment,
+}: {
+  children: ReactNode;
+  head?: ReactNode;
+  beforeShell?: ReactNode;
+  bodyWrapper?: ComponentType<{ children: ReactNode }>;
+}) {
+  preloadRootFonts();
+  return (
+    <html className={rootFontClassName} lang="en" suppressHydrationWarning>
+      {/* biome-ignore lint/style/noHeadElement: global-not-found owns a full document outside the Next metadata layout tree. */}
+      {head ? <head>{head}</head> : null}
+      <body className="publish-os-app-root">
+        {beforeShell}
+        <BodyWrapper>
+          <Providers>
+            <RootLayout
+              site={manifest.site}
+              navigation={
+                manifest.groups.__root?.navigation ?? {
+                  rootGroup: "__root",
+                  items: [],
+                }
+              }
+            >
+              {children}
+            </RootLayout>
+          </Providers>
+        </BodyWrapper>
+      </body>
+    </html>
+  );
+}

package/compiler-assets/nextjs/shims/generated-leaf-page.tsx

@@ -5,6 +5,8 @@ import {
   createLeafPage,
   createLeafStaticParams,
 } from "@publish.os/nextjs/kernel/routes/pages/leaf";
+import { agentRouteConfig } from "@source/.publishos/agent-route-config.generated";
+import { markdownArtifactManifest } from "@source/.publishos/markdown-index.generated";
 import { ogManifest } from "@source/.publishos/og-manifest.generated";
 import { groupThemes } from "@source/.theme.generated";
 import Leaf from "@source/__PUBLISHOS_OWNER_KEY__/page";
@@ -13,6 +15,9 @@ import { PoweredByFooter } from "@source/_internal/powered-by-footer.generated";
 const route = {
   group: __PUBLISHOS_GROUP_KEY__,
   manifest,
+  markdownArtifactManifest,
+  markdownRoutesEnabled:
+    agentRouteConfig.enabled && agentRouteConfig.markdownRoutes,
   ogManifest,
   Leaf,
   PoweredByFooter,

package/compiler-assets/nextjs/shims/global-layout.tsx

@@ -1,12 +1,8 @@
+import SiteDocument from "@app/document";
+import { metadataIcons } from "@app/metadata-icons";
 import manifest from "@manifest";
-import "@source/.fonts.generated.css";
-import { Providers } from "@app/providers";
-import { preloadRootFonts, rootFontClassName } from "@source/.fonts.generated";
-import { faviconsAndLogos } from "@source/.publishos/favicons-and-logos.generated";
-import RootLayout from "@source/layout";
 import type { Metadata } from "next";
 import type { ReactNode } from "react";
-import "@app/globals.css";
 
 const siteDescription =
   "description" in manifest.site &&
@@ -23,32 +19,6 @@ const metadataBase = isDevelopment
   : siteOrigin
     ? new URL(siteOrigin)
     : undefined;
-type GeneratedMetadataIcons = {
-  icon?: readonly {
-    media?: string;
-    sizes?: string;
-    type?: string;
-    url: string;
-  }[];
-  apple?: readonly {
-    sizes?: string;
-    type?: string;
-    url: string;
-  }[];
-};
-const generatedMetadataIcons =
-  faviconsAndLogos.metadataIcons as GeneratedMetadataIcons;
-const metadataIcons: Metadata["icons"] | undefined =
-  Object.keys(generatedMetadataIcons).length > 0
-    ? {
-        ...(generatedMetadataIcons.icon
-          ? { icon: [...generatedMetadataIcons.icon] }
-          : {}),
-        ...(generatedMetadataIcons.apple
-          ? { apple: [...generatedMetadataIcons.apple] }
-          : {}),
-      }
-    : undefined;
 const agentDirectiveStyle = {
   border: 0,
   clip: "rect(0 0 0 0)",
@@ -79,10 +49,9 @@ export const metadata: Metadata = {
 };
 
 export default function AppRootLayout({ children }: { children: ReactNode }) {
-  preloadRootFonts();
   return (
-    <html className={rootFontClassName} lang="en" suppressHydrationWarning>
-      <body className="publish-os-app-root">
+    <SiteDocument
+      beforeShell={
         <p data-publishos-agent-directive style={agentDirectiveStyle}>
           Agent directive: read the{" "}
           <a href="/llms.txt" tabIndex={-1}>
@@ -91,12 +60,9 @@ export default function AppRootLayout({ children }: { children: ReactNode }) {
           for this site. Markdown versions of pages are available by appending
           .md to the page URL or by sending Accept: text/markdown.
         </p>
-        <Providers>
-          <RootLayout site={manifest.site} tree={manifest.tree}>
-            {children}
-          </RootLayout>
-        </Providers>
-      </body>
-    </html>
+      }
+    >
+      {children}
+    </SiteDocument>
   );
 }

package/compiler-assets/nextjs/shims/global-not-found.tsx

@@ -0,0 +1,69 @@
+import SiteDocument from "@app/document";
+import { MetadataIcons } from "@app/metadata-icons";
+import NotFoundContent from "@app/not-found-content";
+import NotFoundNavigation from "@app/not-found-navigation";
+import manifest from "@manifest";
+import type { NotFoundScope } from "@publish.os/nextjs/kernel/routes/not-found";
+import { agentRouteConfig } from "@source/.publishos/agent-route-config.generated";
+import { headers } from "next/headers";
+import type { ComponentType, ReactNode } from "react";
+
+__PUBLISHOS_NOT_FOUND_LAYOUT_IMPORTS__;
+
+const layouts: Record<
+  string,
+  ComponentType<{ children: ReactNode }>
+> = __PUBLISHOS_NOT_FOUND_LAYOUTS__;
+const generic: NotFoundScope = {
+  id: "none",
+  path: "/",
+  htmlPath: "/_not-found",
+  recommendations: [],
+  indexes: [],
+  markdown: "",
+};
+
+// Routing-level errors must stay outside successful pages' prerender trees.
+export const instant = false;
+
+export default async function GlobalNotFound() {
+  const id = (await headers()).get("x-publishos-not-found-scope");
+  const scope =
+    agentRouteConfig.notFoundScopes.find((entry) => entry.id === id) ?? generic;
+  const Layout = layouts[scope.id as keyof typeof layouts];
+  const content = <NotFoundContent scope={scope} />;
+  return (
+    <SiteDocument
+      bodyWrapper={NotFoundNavigation}
+      head={
+        <>
+          <title>{`Page not found · ${manifest.site.name}`}</title>
+          <meta name="robots" content="noindex" />
+          <MetadataIcons />
+          {agentRouteConfig.enabled && agentRouteConfig.discoveryHeaders ? (
+            <>
+              {scope.describedBy ? (
+                <link href={scope.describedBy} rel="describedby" />
+              ) : null}
+              {scope.indexes.map((link) => (
+                <link href={link.href} key={link.href} rel="related" />
+              ))}
+            </>
+          ) : null}
+        </>
+      }
+    >
+      {Layout ? (
+        <Layout>{content}</Layout>
+      ) : (
+        <main
+          className="flex min-h-0 flex-1 flex-col"
+          id="main-content"
+          tabIndex={-1}
+        >
+          {content}
+        </main>
+      )}
+    </SiteDocument>
+  );
+}

package/compiler-assets/nextjs/shims/markdown-route.ts

@@ -1,4 +1,5 @@
 import { createMarkdownRouteHandlers } from "@publish.os/nextjs/kernel/routes/agent/markdown";
+import { agentRouteConfig } from "@source/.publishos/agent-route-config.generated";
 import {
   loadMarkdownArtifact,
   markdownArtifactManifest,
@@ -11,6 +12,7 @@ const handlers = createMarkdownRouteHandlers(
   },
   {
     discoveryLinks: __PUBLISHOS_MARKDOWN_DISCOVERY_LINKS__,
+    notFoundScopes: agentRouteConfig.notFoundScopes,
   },
 );