@publish.os/nextjs 0.0.1-alpha.81 → 0.0.1-alpha.91

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

@@ -0,0 +1,53 @@
+import { Link } from "@components/ui/link";
+import type { NotFoundScope } from "@publish.os/nextjs/kernel/routes/not-found";
+
+export default function NotFoundContent({ scope }: { scope: NotFoundScope }) {
+  const sections = [
+    { title: "Recommendations", links: scope.recommendations },
+    { title: "For crawlers and agents", links: scope.indexes },
+  ];
+  return (
+    <section
+      className="mx-auto flex w-full max-w-xl flex-1 flex-col items-center justify-center px-6 py-16 font-main sm:px-8 sm:py-24"
+      data-publishos-not-found={scope.id}
+    >
+      <h1 className="text-center font-mono text-8xl leading-none font-medium tracking-tight text-foreground-1 sm:text-9xl">
+        404<span className="sr-only"> — Page not found</span>
+      </h1>
+      <p className="mt-6 max-w-md text-center text-sm leading-6 text-pretty text-foreground-3">
+        This page does not exist. Please check the URL and try again.
+      </p>
+      <div className="mt-10 w-full space-y-8">
+        {sections.map(({ title, links }) =>
+          links.length ? (
+            <section aria-label={title} key={title}>
+              <h2 className="text-xs font-medium text-foreground-3">{title}</h2>
+              <ul className="mt-2 space-y-0">
+                {links.map((link) => (
+                  <li className="flex items-baseline gap-3" key={link.href}>
+                    <span
+                      aria-hidden="true"
+                      className="shrink-0 text-sm text-foreground-3"
+                    >
+                      -
+                    </span>
+                    <Link
+                      className="inline-flex min-h-10 min-w-0 max-w-full items-center py-1 text-start wrap-anywhere"
+                      href={link.href}
+                      prefetch={false}
+                      size="sm"
+                      target="_self"
+                      variant="link.inline"
+                    >
+                      {link.title}
+                    </Link>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          ) : null,
+        )}
+      </div>
+    </section>
+  );
+}

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

@@ -0,0 +1,60 @@
+"use client";
+
+import type { MouseEvent, ReactNode } from "react";
+
+/** Next's routing-level error document has no app-router tree to navigate from. */
+export default function NotFoundNavigation({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  function navigate(event: MouseEvent<HTMLDivElement>) {
+    if (
+      event.defaultPrevented ||
+      event.button !== 0 ||
+      event.altKey ||
+      event.ctrlKey ||
+      event.metaKey ||
+      event.shiftKey
+    )
+      return;
+
+    const target = event.target as Node;
+    const element =
+      target.nodeType === 1 ? (target as Element) : target.parentElement;
+    const link = element?.closest<HTMLAnchorElement>("a[href]");
+    const view = event.currentTarget.ownerDocument.defaultView;
+    if (
+      !link ||
+      !view ||
+      link.hasAttribute("download") ||
+      (link.target && link.target !== "_self")
+    )
+      return;
+
+    let destination: URL;
+    try {
+      destination = new URL(link.href, view.location.href);
+    } catch {
+      return;
+    }
+    if (
+      !["http:", "https:"].includes(destination.protocol) ||
+      destination.origin !== view.location.origin ||
+      (destination.pathname === view.location.pathname &&
+        destination.search === view.location.search &&
+        destination.hash)
+    )
+      return;
+
+    event.preventDefault();
+    event.stopPropagation();
+    view.location.assign(destination.href);
+  }
+
+  return (
+    <div className="contents" onClickCapture={navigate}>
+      {children}
+    </div>
+  );
+}

package/compiler-assets/nextjs/shims/proxy.ts

@@ -1,3 +1,7 @@
+import {
+  createNotFoundTextResponse,
+  resolveNotFoundScope,
+} from "@publish.os/nextjs/kernel/routes/not-found";
 import { agentRouteConfig } from "@source/.publishos/agent-route-config.generated";
 import type { NextRequest } from "next/server";
 import { NextResponse } from "next/server";
@@ -5,8 +9,12 @@ import { NextResponse } from "next/server";
 const AGENT_USER_AGENT_PATTERN =
   /\b(?:axios|got|node-fetch|undici|curl|wget|python-requests|httpx|aiohttp|claude-code|claudebot|claude|cursor|chatgpt|openai|perplexity|anthropic-ai)\b/i;
 const INTERNAL_MARKDOWN_PREFIX = "/__publishos/md";
-const PUBLIC_FILE_PATTERN = /\.[a-z0-9]{1,12}$/i;
+const FRAMEWORK_PREFIX = "__PUBLISHOS_FRAMEWORK_PREFIX__";
 const TEXT_METHODS = new Set(["GET", "HEAD"]);
+const PUBLIC_PATHS = new Set<string>(agentRouteConfig.publicPaths);
+const MARKDOWN_PATHS = new Set<string>(agentRouteConfig.markdownPaths);
+const OUTPUT_PATHS = new Set<string>(agentRouteConfig.outputPaths);
+const NOT_FOUND_SCOPE_HEADER = "x-publishos-not-found-scope";
 
 function debugAgentRoute(
   event: string,
@@ -46,29 +54,6 @@ function markdownAlternatePath(pathname: string): string {
   return normalized.endsWith(".md") ? normalized : `${normalized}.md`;
 }
 
-function markdownNotFoundBody(): string {
-  const links = [
-    agentRouteConfig.discoveryLinks.home
-      ? `> Home: ${agentRouteConfig.discoveryLinks.home}`
-      : undefined,
-    agentRouteConfig.discoveryLinks.sitemap
-      ? `> Sitemap: ${agentRouteConfig.discoveryLinks.sitemap}`
-      : undefined,
-    agentRouteConfig.discoveryLinks.llms
-      ? `> LLMS index: ${agentRouteConfig.discoveryLinks.llms}`
-      : undefined,
-  ].filter((line): line is string => Boolean(line));
-
-  return [
-    "# Not found",
-    "",
-    ...links,
-    "",
-    "The requested Markdown page was not found.",
-    "",
-  ].join("\n");
-}
-
 function explicitAcceptQuality(accept: string, mimeType: string): number {
   if (!accept) return 0;
 
@@ -100,8 +85,10 @@ function explicitAcceptQuality(accept: string, mimeType: string): number {
   return bestQuality;
 }
 
-function wantsMarkdown(request: NextRequest): boolean {
-  if (!TEXT_METHODS.has(request.method)) return false;
+function negotiatedTextType(
+  request: NextRequest,
+): "text/markdown; charset=utf-8" | "text/plain; charset=utf-8" | undefined {
+  if (!TEXT_METHODS.has(request.method)) return undefined;
 
   const accept = request.headers.get("accept") ?? "";
   const markdownQuality = agentRouteConfig.markdownAccept
@@ -112,12 +99,13 @@ function wantsMarkdown(request: NextRequest): boolean {
     : 0;
   const htmlQuality = explicitAcceptQuality(accept, "text/html");
 
-  if (markdownQuality > 0 && markdownQuality >= htmlQuality) return true;
+  if (markdownQuality > 0 && markdownQuality >= htmlQuality) {
+    return "text/markdown; charset=utf-8";
+  }
   if (plainQuality > 0 && htmlQuality === 0 && markdownQuality === 0) {
-    return true;
+    return "text/plain; charset=utf-8";
   }
-
-  return false;
+  return undefined;
 }
 
 function looksLikeAgent(request: NextRequest): boolean {
@@ -139,7 +127,7 @@ function markdownRequestReason(
   ) {
     return "extension";
   }
-  if (wantsMarkdown(request)) return "accept";
+  if (negotiatedTextType(request)) return "accept";
   if (looksLikeAgent(request)) return "agent";
   return undefined;
 }
@@ -152,13 +140,11 @@ function isInternalMarkdownRoute(pathname: string): boolean {
 }
 
 function isStaticOrMetadataRoute(pathname: string): boolean {
+  if (OUTPUT_PATHS.has(normalizePagePath(pathname))) return true;
   if (
-    pathname.startsWith("/_next/") ||
-    pathname.startsWith("/_publishos/assets/") ||
-    pathname.startsWith("/_publishos/favicon/") ||
-    pathname.startsWith("/_publishos/logo/") ||
-    pathname.startsWith("/_publishos/og/") ||
-    pathname.startsWith("/assets/")
+    pathname === FRAMEWORK_PREFIX ||
+    pathname.startsWith(`${FRAMEWORK_PREFIX}/`) ||
+    pathname.startsWith("/_next/")
   ) {
     return true;
   }
@@ -176,21 +162,29 @@ function isStaticOrMetadataRoute(pathname: string): boolean {
     return true;
   }
 
-  return PUBLIC_FILE_PATTERN.test(pathname) && !pathname.endsWith(".md");
+  return false;
 }
 
-function rewriteToMarkdown(
-  request: NextRequest,
-  reason: "accept" | "agent" | "extension",
-): NextResponse {
-  const url = request.nextUrl.clone();
+function rewriteToMarkdown({
+  request,
+  reason,
+  requestHeaders,
+}: {
+  request: NextRequest;
+  reason: "accept" | "agent" | "extension";
+  requestHeaders: Headers;
+}): NextResponse {
+  const url = new URL(request.url);
   url.pathname =
     normalizePagePath(url.pathname) === "/"
       ? "/sitemap.md"
       : markdownRoutePath(url.pathname);
+  const revision = request.nextUrl.searchParams.get("publishos_revision");
+  url.search = "";
+  url.hash = "";
+  if (revision) url.searchParams.set("publishos_revision", revision);
 
-  const requestHeaders = new Headers(request.headers);
-  requestHeaders.set("x-publishos-agent-route", "markdown");
+  requestHeaders.set("accept", "text/markdown");
 
   debugAgentRoute("md", {
     accept: request.headers.get("accept") ?? undefined,
@@ -242,18 +236,28 @@ function withDiscoveryHeaders(
 
 export function proxy(request: NextRequest) {
   const { pathname } = request.nextUrl;
+  const requestHeaders = new Headers(request.headers);
+  requestHeaders.delete(NOT_FOUND_SCOPE_HEADER);
+  requestHeaders.delete("x-publishos-agent-route");
+
+  if (pathname === "/_not-found") {
+    requestHeaders.set(NOT_FOUND_SCOPE_HEADER, "none");
+    const response = NextResponse.next({
+      request: { headers: requestHeaders },
+    });
+    response.headers.set("x-robots-tag", "noindex");
+    response.headers.set("vary", "Accept, User-Agent");
+    return response;
+  }
 
   if (isInternalMarkdownRoute(pathname)) {
-    if (request.headers.get("x-publishos-agent-route") === "markdown") {
-      return NextResponse.next();
-    }
     if (!agentRouteConfig.blockInternalMarkdownRoute) {
       debugAgentRoute("pass", {
         method: request.method,
         path: pathname,
         reason: "allowed-internal",
       });
-      return NextResponse.next();
+      return NextResponse.next({ request: { headers: requestHeaders } });
     }
 
     debugAgentRoute("md", {
@@ -263,15 +267,7 @@ export function proxy(request: NextRequest) {
       status: 404,
     });
 
-    return new Response(markdownNotFoundBody(), {
-      status: 404,
-      headers: {
-        "cache-control": "public, max-age=60, s-maxage=300",
-        "content-type": "text/markdown; charset=utf-8",
-        "x-content-type-options": "nosniff",
-        "x-robots-tag": "noindex",
-      },
-    });
+    return createNotFoundTextResponse({ method: request.method });
   }
 
   if (isStaticOrMetadataRoute(pathname)) {
@@ -280,12 +276,93 @@ export function proxy(request: NextRequest) {
       path: pathname,
       reason: "static-or-metadata",
     });
-    return NextResponse.next();
+    return NextResponse.next({ request: { headers: requestHeaders } });
   }
 
   const markdownReason = markdownRequestReason(request);
   if (markdownReason) {
-    return rewriteToMarkdown(request, markdownReason);
+    let htmlPath: string | undefined;
+    try {
+      const decoded = normalizePagePath(decodeURIComponent(pathname));
+      htmlPath = decoded.endsWith(".md")
+        ? decoded.slice(0, -3) || "/"
+        : decoded;
+    } catch {
+      htmlPath = undefined;
+    }
+    const scope = resolveNotFoundScope({
+      scopes: agentRouteConfig.notFoundScopes,
+      pathname,
+    });
+    const hasArtifact =
+      htmlPath === "/"
+        ? OUTPUT_PATHS.has("/sitemap.md")
+        : htmlPath !== undefined && MARKDOWN_PATHS.has(htmlPath);
+    if (!scope || !hasArtifact) {
+      const response = createNotFoundTextResponse({
+        scope,
+        pathname,
+        method: request.method,
+        contentType:
+          markdownReason === "accept" ? negotiatedTextType(request) : undefined,
+        vary: markdownReason !== "extension",
+      });
+      if (!agentRouteConfig.enabled || !agentRouteConfig.discoveryHeaders) {
+        for (const name of [
+          "link",
+          "x-publishos-llms",
+          "x-publishos-sitemap",
+        ]) {
+          response.headers.delete(name);
+        }
+      }
+      return response;
+    }
+    return rewriteToMarkdown({
+      request,
+      reason: markdownReason,
+      requestHeaders,
+    });
+  }
+
+  let pagePath: string;
+  try {
+    pagePath = normalizePagePath(decodeURIComponent(pathname));
+  } catch {
+    pagePath = pathname;
+  }
+  if (!PUBLIC_PATHS.has(pagePath)) {
+    // Select Next's error route before an unknown catch-all can stream.
+    const scope = resolveNotFoundScope({
+      scopes: agentRouteConfig.notFoundScopes,
+      pathname,
+    });
+    requestHeaders.set(NOT_FOUND_SCOPE_HEADER, scope?.id ?? "none");
+    const url = new URL(request.url);
+    url.pathname = "/_not-found";
+    url.search = "";
+    url.hash = "";
+    const response = NextResponse.rewrite(url, {
+      status: 404,
+      request: { headers: requestHeaders },
+    });
+    const recoveryHeaders = createNotFoundTextResponse({
+      scope,
+      pathname,
+      method: request.method,
+      vary: true,
+    }).headers;
+    for (const name of [
+      "x-robots-tag",
+      "vary",
+      ...(agentRouteConfig.enabled && agentRouteConfig.discoveryHeaders
+        ? ["link", "x-publishos-llms", "x-publishos-sitemap"]
+        : []),
+    ]) {
+      const value = recoveryHeaders.get(name);
+      if (value) response.headers.set(name, value);
+    }
+    return response;
   }
 
   if (!agentRouteConfig.enabled || !agentRouteConfig.discoveryHeaders) {
@@ -296,7 +373,7 @@ export function proxy(request: NextRequest) {
         ? "discovery-disabled"
         : "agent-routes-disabled",
     });
-    return NextResponse.next();
+    return NextResponse.next({ request: { headers: requestHeaders } });
   }
 
   debugAgentRoute("html", {
@@ -307,11 +384,12 @@ export function proxy(request: NextRequest) {
     userAgent: request.headers.get("user-agent") ?? undefined,
   });
 
-  return withDiscoveryHeaders(NextResponse.next(), pathname);
+  return withDiscoveryHeaders(
+    NextResponse.next({ request: { headers: requestHeaders } }),
+    pathname,
+  );
 }
 
 export const config = {
-  matcher: [
-    "/((?!_next/static|_next/image|_next/webpack-hmr|_publishos/assets|_publishos/favicon|_publishos/logo|_publishos/og|assets).*)",
-  ],
+  matcher: ["/__PUBLISHOS_MATCHER__"],
 };

package/compiler-assets/nextjs/shims/publish-os-theme-provider.tsx

@@ -6,9 +6,9 @@ import {
   ROOT_FORCED_MODE,
   routeThemes,
 } from "@source/.theme.generated";
-import { useSelectedLayoutSegments } from "next/navigation";
+import { usePathname } from "next/navigation";
 import { ThemeProvider as NextThemes } from "next-themes";
-import type { ReactNode } from "react";
+import { type ReactNode, Suspense, useLayoutEffect, useState } from "react";
 
 type ForcedMode = "dark" | "light" | "none";
 type RouteTheme = {
@@ -16,24 +16,20 @@ type RouteTheme = {
   forcedMode?: ForcedMode;
 };
 
-function selectedPathFromSegments(segments: readonly string[]): string {
-  const path = segments
-    .filter((segment) => segment !== "" && !segment.startsWith("("))
-    .join("/");
-
-  return path ? `/${path}` : "/";
-}
-
 function resolveRouteTheme(
-  segments: readonly string[],
+  pathname: string,
+  themes: Readonly<Record<string, RouteTheme>>,
 ): RouteTheme | undefined {
-  const selectedPath = selectedPathFromSegments(segments);
   let match: RouteTheme | undefined;
   let matchLength = 0;
 
-  const entries = Object.entries(routeThemes) as Array<[string, RouteTheme]>;
+  const entries = Object.entries(themes);
   for (const [basePath, routeTheme] of entries) {
-    if (selectedPath === basePath || selectedPath.startsWith(`${basePath}/`)) {
+    if (
+      basePath === "/" ||
+      pathname === basePath ||
+      pathname.startsWith(`${basePath}/`)
+    ) {
       if (basePath.length > matchLength) {
         match = routeTheme;
         matchLength = basePath.length;
@@ -50,8 +46,57 @@ function effectiveForcedMode(routeTheme: RouteTheme | undefined): ForcedMode {
   return ROOT_FORCED_MODE ?? "none";
 }
 
+function RouteThemeSync({
+  onChange,
+}: {
+  onChange: (theme: RouteTheme | undefined) => void;
+}) {
+  const routeTheme = resolveRouteTheme(usePathname(), routeThemes);
+  useLayoutEffect(() => onChange(routeTheme), [onChange, routeTheme]);
+  return null;
+}
+
+function initialRouteTheme(): RouteTheme | undefined {
+  return typeof window === "undefined"
+    ? undefined
+    : resolveRouteTheme(window.location.pathname, routeThemes);
+}
+
+// Both bootstrap and hydration use the same compiler-generated route mapping.
+const initialThemeScript = `{
+  const route = (${resolveRouteTheme.toString()})(location.pathname, ${JSON.stringify(routeThemes).replaceAll("<", "\\u003c")});
+  document.currentScript.parentElement.setAttribute("data-group", route?.group ?? "");
+  const forcedMode = route?.forcedMode ?? ${JSON.stringify(ROOT_FORCED_MODE) ?? "undefined"};
+  let mode = ${JSON.stringify(ROOT_DEFAULT_MODE)};
+  try { mode = localStorage.getItem("theme") || mode; } catch {}
+  if (forcedMode && forcedMode !== "none") mode = forcedMode;
+  if (mode === "system") mode = matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  if (mode === "light" || mode === "dark") {
+    const root = document.documentElement;
+    root.classList.remove("light", "dark");
+    root.classList.add(mode);
+    root.style.colorScheme = mode;
+  }
+}`;
+
+export function PublishOSThemeScope({
+  children,
+  group,
+}: {
+  children: ReactNode;
+  group: string;
+}) {
+  return (
+    <ThemeScopeProvider group={group}>
+      <div className="contents" data-theme-root="" data-group={group}>
+        {children}
+      </div>
+    </ThemeScopeProvider>
+  );
+}
+
 export function PublishOSThemeProvider({ children }: { children: ReactNode }) {
-  const routeTheme = resolveRouteTheme(useSelectedLayoutSegments());
+  const [routeTheme, setRouteTheme] = useState(initialRouteTheme);
   const forcedMode = effectiveForcedMode(routeTheme);
   const forcedTheme = forcedMode === "none" ? undefined : forcedMode;
 
@@ -62,13 +107,29 @@ export function PublishOSThemeProvider({ children }: { children: ReactNode }) {
       disableTransitionOnChange
       enableSystem
       forcedTheme={forcedTheme}
+      scriptProps={{
+        type: typeof window === "undefined" ? "text/javascript" : "text/plain",
+      }}
     >
       <ThemeScopeProvider group={routeTheme?.group}>
         <div
           className="contents"
+          id="publish-os-theme-root"
           data-theme-root=""
           data-group={routeTheme?.group ?? ""}
+          suppressHydrationWarning
         >
+          <script
+            type={
+              typeof window === "undefined" ? "text/javascript" : "text/plain"
+            }
+            suppressHydrationWarning
+            // biome-ignore lint/security/noDangerouslySetInnerHtml: Compiler-only route metadata escapes HTML; the script must run before paint.
+            dangerouslySetInnerHTML={{ __html: initialThemeScript }}
+          />
+          <Suspense fallback={null}>
+            <RouteThemeSync onChange={setRouteTheme} />
+          </Suspense>
           {children}
         </div>
       </ThemeScopeProvider>

package/compiler-assets/nextjs/shims/root-page.tsx

@@ -4,10 +4,16 @@ import {
   createRootPage,
 } from "@publish.os/nextjs/kernel/routes/pages/root";
 import { ogManifest } from "@source/.publishos/og-manifest.generated";
-import RootPage from "@source/page";
+import RootPage from "@source/index";
 import type { Metadata } from "next";
 
 const route = { manifest, ogManifest, RootPage } as const;
 
 export default createRootPage(route);
 export const metadata: Metadata = createRootMetadata(route);
+
+export const ensureStatic = "navigation";
+
+// Next 16.4 still misclassifies redirect() during instant validation.
+// Keep its HTTP response; ensureStatic independently validates prerendering.
+export const instant = false;

package/compiler-assets/nextjs/shims/site-fenced-code-block.tsx

@@ -0,0 +1,30 @@
+import { CodeBlock } from "@components/mdx/code-block";
+import { type HTMLAttributes, isValidElement, type ReactNode } from "react";
+
+type CodeChildProps = {
+  children?: ReactNode;
+  className?: string;
+  title?: string;
+};
+
+export function FencedCodeBlock({
+  children,
+  title,
+  ...props
+}: HTMLAttributes<HTMLElement>) {
+  const codeElement = isValidElement<CodeChildProps>(children)
+    ? children
+    : null;
+  const code = codeElement?.props.children ?? children;
+  const language = /(?:^|\s)language-([^\s]+)/.exec(
+    codeElement?.props.className ?? "",
+  )?.[1];
+  return (
+    <CodeBlock
+      {...props}
+      code={typeof code === "string" ? code : ""}
+      language={language}
+      title={title ?? codeElement?.props.title}
+    />
+  );
+}

package/compiler-assets/nextjs/shims/site-heading-level.tsx

@@ -0,0 +1,14 @@
+import type { ComponentType, HTMLAttributes } from "react";
+
+type HeadingTag = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+
+export function headingWithLevel(
+  Heading: ComponentType<
+    { as: HeadingTag } & HTMLAttributes<HTMLHeadingElement>
+  >,
+  as: HeadingTag,
+) {
+  return function HeadingLevel(props: HTMLAttributes<HTMLHeadingElement>) {
+    return <Heading as={as} {...props} />;
+  };
+}