jamdesk 1.1.49 → 1.1.51

package/vendored/app/[[...slug]]/page.tsx

@@ -1,195 +1,48 @@
-import { notFound } from 'next/navigation';
+// Catch-all route for docs pages. Reads `headers()` for per-project
+// resolution (`x-project-slug`/`x-host-at-docs` set by middleware), which
+// forces force-dynamic. The `params.project` branch handles direct
+// `/[project]/...` URLs without middleware involvement (used by tests and
+// non-ISR local dev). The render body lives in lib/render-doc-page.tsx.
 import { headers } from 'next/headers';
-import { MDXRemote } from 'next-mdx-remote/rsc';
-
-/**
- * Route Segment Configuration
- *
- * force-dynamic: Always render on each request. Required because:
- * 1. In ISR mode, we read project slug from headers (set by middleware)
- * 2. headers() is a dynamic API that opts out of static generation
- *
- * In static mode (local dev, customer builds), this is ignored because
- * those builds don't deploy to Vercel - they use the static export.
- *
- * Caching strategy:
- * - MDX content cached in R2 (fast fetch)
- * - Vercel edge CDN caches responses
- * - On-demand revalidation via /api/revalidate endpoint
- */
-export const dynamic = 'force-dynamic';
-export const dynamicParams = true; // Allow paths not in generateStaticParams
-import { MDXComponents } from '@/components/mdx/MDXComponents';
-import { Breadcrumb } from '@/components/navigation/Breadcrumb';
-import { TableOfContents } from '@/components/navigation/TableOfContents';
-import { PageColumns } from '@/components/layout/PageColumns';
-import { PageNavigation } from '@/components/navigation/PageNavigation';
-import { SocialFooter } from '@/components/navigation/SocialFooter';
-import { ApiPageWrapper } from '@/components/mdx/ApiPage';
-import { OpenApiEndpoint } from '@/components/mdx/OpenApiEndpoint';
-import { OpenApiError } from '@/components/openapi/OpenApiError';
-import { getHighlighter } from '@/lib/shiki-highlighter';
-import { createShikiRehypePlugin } from '@/lib/shiki-config';
-import rehypeSlug from 'rehype-slug';
-import remarkGfm from 'remark-gfm';
-import { rehypeCodeMeta, rehypeRestoreDataTitle } from '@/lib/rehype-code-meta';
-import { rehypeClassToClassName } from '@/lib/rehype-class-to-classname';
-import { rehypeNoZoomToData } from '@/lib/rehype-nozoom-to-data';
-import { preprocessMdx, containsPanel, containsView, buildSnippetAliasMap } from '@/lib/preprocess-mdx';
-import { loadSnippetsForIsr } from '@/lib/snippet-loader-isr';
-import { PanelWrapper } from '@/components/mdx/PanelWrapper';
-import { ViewWrapper } from '@/components/mdx/View';
-import { getLatexRemarkPlugins, getLatexRehypePlugins } from '@/lib/latex-config';
-import { getTypographyRemarkPlugins } from '@/lib/typography-config';
-import { remarkVisibility } from '@/lib/remark-visibility';
-import { recmaCompoundComponents } from '@/lib/recma-compound-components';
-import { extractInlineComponents } from '@/lib/process-mdx-with-exports';
-import { extractHeadings } from '@/lib/heading-extractor';
-import { StepSlugProvider, type StepSlugEntry } from '@/components/mdx/StepSlugContext';
-import { buildEndpointFromMdx } from '@/lib/build-endpoint-from-mdx';
-import { mdxSecurityOptions } from '@/lib/mdx-security-options';
 import fs from 'fs';
 import path from 'path';
+import type { Metadata } from 'next';
 import { getContentDir } from '@/lib/docs';
-import type { DocsConfig } from '@/lib/docs-types';
-import { buildSeoMetadata, generateAutoDescription, buildSiteTitle } from '@/lib/seo';
-import { buildJsonLd } from '@/lib/json-ld';
 import {
-  getContentLoader,
   isIsrMode,
   getProjectFromRequest,
   getHostAtDocs,
-  normalizeSlugForContent,
-  parseFrontmatter,
-  projectExists,
 } from '@/lib/content-loader';
-import { getBaseUrl, pathToSlug } from '@/lib/page-isr-helpers';
-import {
-  parseOpenApiFrontmatter,
-  getCachedSpec,
-  parseEndpoint,
-  generateCodeExamples,
-  formatOpenApiWarning,
-  deriveAuthFromSecurity,
-  type OpenApiEndpointData,
-  type CodeExample,
-  type AuthMethod,
-} from '@/lib/openapi';
-import { classifyOpenApiLoadError } from '@/lib/openapi/classify-load-error';
-import { extractLanguageFromPath, isValidLanguageCode } from '@/lib/language-utils';
-import { findFirstNavPage } from '@/lib/find-first-nav-page';
-import { candidateSpecPaths } from '@/lib/openapi/lang-spec-path';
-import { ApiEndpoint } from '@/components/mdx/ApiEndpoint';
-import { ImagePriorityProvider } from '@/components/mdx/ImagePriorityProvider';
-import { AIActionsMenu } from '@/components/AIActionsMenu';
-import { getContextualOptions } from '@/lib/contextual-defaults';
-
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
-
-/**
- * Parse MDX api frontmatter field (e.g., "POST /analytics/post")
- * Returns the HTTP method and path
- */
-function parseMdxApiField(apiField: string): { method: HttpMethod; path: string } | null {
-  if (!apiField || typeof apiField !== 'string') return null;
-
-  const trimmed = apiField.trim();
-  const methods: HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'TRACE'];
-
-  for (const method of methods) {
-    if (trimmed.toUpperCase().startsWith(method)) {
-      const path = trimmed.slice(method.length).trim();
-      return { method, path };
-    }
-  }
-  return null;
-}
+import { renderDocPage, buildDocMetadata, type RenderInput } from '@/lib/render-doc-page';
 
-// Import generated snippet components (created at build time)
-// This file is auto-generated by scripts/compile-snippets.cjs
-// Note: ProjectSnippets.tsx is server-compatible (no 'use client'),
-// individual components have 'use client' in their own files
-import { SnippetComponents } from '@/components/snippets/ProjectSnippets';
+export const dynamic = 'force-dynamic';
+export const dynamicParams = true;
 
 interface PageProps {
   params: Promise<{
+    project?: string;
     slug?: string[];
   }>;
 }
 
-const DEFAULT_SITE_URL = 'https://docs.example.com';
-
-/**
- * Resolve the base URL for SEO metadata and JSON-LD.
- * ISR mode: derived from request headers (handles custom domains).
- * Static mode: uses SITE_URL env var set during build.
- */
-function resolveBaseUrl(
-  requestHeaders: Headers | null,
-  projectSlug: string | null,
-  hostAtDocs: boolean
-): string {
-  if (requestHeaders && projectSlug) {
-    return getBaseUrl(requestHeaders, projectSlug, hostAtDocs);
-  }
-  return process.env.SITE_URL || DEFAULT_SITE_URL;
-}
-
-/**
- * docs.json override is treated as a UNIT — if method is set, both method and name
- * come from docs.json, avoiding a stale customer-set `name` pairing with a
- * spec-derived `method`. Falls back to deriving auth from the OpenAPI security schemes.
- */
-function resolveAuth(
-  endpoint: OpenApiEndpointData | null | undefined,
-  config: DocsConfig,
-): { method?: AuthMethod; headerName?: string } {
-  const override = config.api?.mdx?.auth;
-  if (override?.method) {
-    return { method: override.method, headerName: override.name };
-  }
-  return endpoint ? deriveAuthFromSecurity(endpoint.security) : {};
-}
-
-/**
- * Frontmatter data from MDX files.
- */
-interface FrontmatterData {
-  title?: string;
-  description?: string;
-  api?: string;
-  openapi?: string;
-  playground?: string;
-  mode?: string;
-  hideFooter?: boolean;
-  rss?: boolean;
-  [key: string]: unknown;
-}
-
 function getAllDocPaths(): string[] {
   const contentDir = getContentDir();
   const paths: string[] = [];
 
   function traverseDir(dir: string, basePath: string = '') {
     if (!fs.existsSync(dir)) return;
-
     const files = fs.readdirSync(dir);
-
     for (const file of files) {
-      // Skip hidden files/directories (like .claude, .git, etc.)
+      // Skip dotfiles (.claude, .git, etc.)
       if (file.startsWith('.')) continue;
-
       const filePath = path.join(dir, file);
-
-      // Handle broken symlinks gracefully
       let stat;
       try {
         stat = fs.statSync(filePath);
       } catch {
-        // Broken symlink or inaccessible file - skip
+        // Broken symlink or inaccessible — skip
         continue;
       }
-
       if (stat.isDirectory()) {
         traverseDir(filePath, path.join(basePath, file));
       } else if (file.endsWith('.mdx')) {
@@ -203,618 +56,70 @@ function getAllDocPaths(): string[] {
   return paths;
 }
 
-function findFirstPage(config: DocsConfig, lang?: string): string {
-  const nav = config.navigation;
-  const langBlock = lang ? nav.languages?.find((l) => l.language === lang) : undefined;
-  const result = (langBlock && findFirstNavPage(langBlock)) || findFirstNavPage(nav);
-  return result ? result.replace(/^\//, '') : 'introduction';
-}
-
-function needsSlugRewrite(slug: string[]): boolean {
-  return slug.length === 0 || (slug.length === 1 && isValidLanguageCode(slug[0]));
-}
-
-function resolveSlug(normalizedSlug: string[], config: DocsConfig): string[] {
-  if (normalizedSlug.length === 0) return pathToSlug(findFirstPage(config));
-  if (normalizedSlug.length === 1 && isValidLanguageCode(normalizedSlug[0])) {
-    return pathToSlug(findFirstPage(config, normalizedSlug[0]));
-  }
-  return normalizedSlug;
-}
-
 export async function generateStaticParams() {
-  // In ISR mode, pages are generated on-demand, not at build time
-  // Return empty array so Next.js doesn't try to pre-render pages
-  if (isIsrMode()) {
-    return [];
-  }
+  // ISR: pages generated on-demand, no build-time pre-render.
+  if (isIsrMode()) return [];
 
-  // Static mode: pre-render all pages from filesystem
   const paths = getAllDocPaths();
+  // next-mdx-remote can't compile relative MDX imports — skip those tests.
+  const unsupportedPatterns = ['deep-relative-test', 'relative-snippets-test'];
 
-  // Filter out pages with relative MDX imports (not supported by next-mdx-remote)
-  const unsupportedPatterns = [
-    'deep-relative-test',
-    'relative-snippets-test',
-  ];
-
-  const supportedPaths = paths.filter(path => {
-    const hasUnsupportedPattern = unsupportedPatterns.some(pattern =>
-      path.includes(pattern)
-    );
-    if (hasUnsupportedPattern) {
-      console.log(`[Build] Skipping page with unsupported relative imports: ${path}`);
-    }
-    return !hasUnsupportedPattern;
+  const supportedPaths = paths.filter(p => {
+    const skip = unsupportedPatterns.some(pattern => p.includes(pattern));
+    if (skip) console.log(`[Build] Skipping page with unsupported relative imports: ${p}`);
+    return !skip;
   });
 
-  // Include empty slug for root route (resolves to first page in-place)
   return [
     { slug: [] },
-    ...supportedPaths.map((path) => ({
-      slug: path.split('/'),
-    })),
+    ...supportedPaths.map((p) => ({ slug: p.split('/') })),
   ];
 }
 
-export async function generateMetadata({ params }: PageProps) {
-  const resolvedParams = await params;
-
-  // Get project from request headers (only present in ISR mode)
-  let projectSlug: string | null = null;
-  let hostAtDocs = process.env.HOST_AT_DOCS === 'true'; // Local dev fallback
-  let requestHeaders: Headers | null = null;
-
-  if (isIsrMode()) {
-    requestHeaders = await headers();
-    projectSlug = getProjectFromRequest(requestHeaders);
-    hostAtDocs = getHostAtDocs(requestHeaders);
-
-    if (!projectSlug) {
-      return { title: 'Not Found' };
-    }
-
-    const exists = await projectExists(projectSlug);
-    if (!exists) {
-      return { title: 'Not Found' };
-    }
-  }
-
-  // Get content loader (ISR: R2, static: filesystem)
-  const loader = getContentLoader(projectSlug ?? undefined);
-
-  // Normalize slug: strip /docs prefix when hostAtDocs=true.
-  // Empty root → resolve to first page (see DocPage for the full rationale).
-  const normalizedSlug = normalizeSlugForContent(resolvedParams.slug || [], hostAtDocs);
-  const configP = loader.getConfig();
-  const slug = needsSlugRewrite(normalizedSlug)
-    ? resolveSlug(normalizedSlug, await configP)
-    : normalizedSlug;
-  const isRoot = normalizedSlug.length === 0;
-  const pagePath = slug.join('/');
-
-  const [fileContents, config] = await Promise.all([
-    loader.getContent(pagePath).catch(() => null),
-    configP,
-  ]);
-
-  if (!fileContents) {
+// Resolve project + hostAtDocs from URL params (direct `/[project]/...`
+// hits in non-ISR local dev / tests) or from middleware-set headers (the
+// production path). The header read is what forces this segment dynamic.
+async function resolveInput(params: PageProps['params']): Promise<RenderInput> {
+  const resolved = await params;
+  const projectFromParams = resolved.project ?? null;
+
+  if (projectFromParams) {
+    // Direct /[project]/... URLs only hit this branch from tests and the
+    // non-ISR CLI dev server — production always goes through middleware
+    // and the header branch below. hostAtDocs derived from env so the
+    // segment stays statically analyzable when this branch is hit.
     return {
-      title: 'Not Found',
+      slug: resolved.slug || [],
+      projectSlug: projectFromParams,
+      hostAtDocs: process.env.HOST_AT_DOCS === 'true',
+      requestHeaders: null,
     };
   }
 
-  const parsed = parseFrontmatter(fileContents);
-  const data = parsed.data as FrontmatterData;
-
-  // Auto-generate description from content when frontmatter has none
-  if (!data.description) {
-    data.description = generateAutoDescription(parsed.content);
+  if (!isIsrMode()) {
+    return {
+      slug: resolved.slug || [],
+      projectSlug: null,
+      hostAtDocs: process.env.HOST_AT_DOCS === 'true',
+      requestHeaders: null,
+    };
   }
 
-  const baseUrl = resolveBaseUrl(requestHeaders, projectSlug, hostAtDocs);
-  const languages = config.navigation?.languages;
-
-  const seoMetadata = buildSeoMetadata(config, data, pagePath, baseUrl, languages);
-
-  // If page title matches config.name, use absolute to prevent "X — X" double-wrap.
-  // If no title, use buildSiteTitle (which avoids "X Documentation Documentation").
-  const titleValue = data.title
-    ? (data.title === config.name ? { absolute: data.title } : data.title)
-    : { absolute: buildSiteTitle(config.name) };
-
+  const requestHeaders = await headers();
   return {
-    title: titleValue,
-    description: data.description || '',
-    ...seoMetadata,
-    // Root serves first-page content but canonical points at /{firstPage};
-    // noindex as a second dedup signal alongside the canonical tag.
-    ...(isRoot && { robots: { index: false, follow: true } }),
-    ...(data.rss ? {
-      alternates: {
-        ...seoMetadata.alternates,
-        types: {
-          'application/rss+xml': hostAtDocs ? '/docs/feed.xml' : '/feed.xml',
-        },
-      },
-    } : {}),
+    slug: resolved.slug || [],
+    projectSlug: getProjectFromRequest(requestHeaders),
+    hostAtDocs: getHostAtDocs(requestHeaders),
+    requestHeaders,
   };
 }
 
-export default async function DocPage({ params }: PageProps) {
-  const resolvedParams = await params;
-
-  // Get project from request headers (only present in ISR mode)
-  let projectSlug: string | null = null;
-  let hostAtDocs = process.env.HOST_AT_DOCS === 'true'; // Local dev fallback
-  let requestHeaders: Headers | null = null;
-  if (isIsrMode()) {
-    requestHeaders = await headers();
-    projectSlug = getProjectFromRequest(requestHeaders);
-    hostAtDocs = getHostAtDocs(requestHeaders);
-    if (!projectSlug) {
-      notFound(); // Project not resolved by middleware
-    }
-
-    // Check if project has content in R2
-    // This returns 404 instead of 500 for projects that haven't been built yet
-    const exists = await projectExists(projectSlug);
-    if (!exists) {
-      notFound(); // Project not built to R2 yet
-    }
-  }
-
-  // Get content loader (ISR: R2, static: filesystem)
-  const loader = getContentLoader(projectSlug ?? undefined);
-
-  // Normalize slug: strip /docs prefix when hostAtDocs=true.
-  // Empty root renders the first page in place rather than 307'ing — Next's
-  // redirect() emits cache-control: private, blocking CDN caching. Canonical
-  // + noindex in generateMetadata prevent duplicate indexing.
-  const normalizedSlug = normalizeSlugForContent(resolvedParams.slug || [], hostAtDocs);
-  const configP = loader.getConfig();
-  const slug = needsSlugRewrite(normalizedSlug)
-    ? resolveSlug(normalizedSlug, await configP)
-    : normalizedSlug;
-  const pagePath = slug.join('/');
-  const currentLang = extractLanguageFromPath(`/${pagePath}`);
-  const [fileContents, config] = await Promise.all([
-    loader.getContent(pagePath).catch(() => null),
-    configP,
-  ]);
-
-  // Check if content exists (getContent returns null via catch if not found)
-  if (!fileContents) {
-    notFound();
-  }
-
-  const parsed = parseFrontmatter(fileContents);
-  const data = parsed.data as FrontmatterData;
-  const rawContent = parsed.content;
-
-  // JSON-LD structured data for rich search results.
-  // XSS-safe: replaces < with unicode escape per Next.js guide.
-  // Same pattern as marketing/app/layout.tsx and marketing/app/blog/[slug]/page.tsx.
-  const baseUrl = resolveBaseUrl(requestHeaders, projectSlug, hostAtDocs);
-  const jsonLd = buildJsonLd({
-    config,
-    pagePath,
-    pageTitle: data.title || pagePath,
-    baseUrl,
-  });
-  const jsonLdScript = (
-    <script
-      type="application/ld+json"
-      dangerouslySetInnerHTML={{
-        __html: JSON.stringify(jsonLd).replace(/</g, '\\u003c'),
-      }}
-    />
-  );
-
-  // Get cached Shiki highlighter for syntax highlighting
-  // This singleton is reused across all page renders for performance
-  const highlighter = await getHighlighter();
-
-  // Load snippets - different behavior for ISR vs static mode:
-  // - ISR mode: Fetch and compile snippets dynamically from R2
-  // - Static mode: Use pre-compiled SnippetComponents from build time
-  let snippetAliases: Record<string, React.ComponentType<unknown>> = {};
-
-  if (isIsrMode() && projectSlug) {
-    // ISR mode: Load snippets dynamically from R2
-    // This is required because ISR pages are rendered on-demand and can't use
-    // the static SnippetComponents which are empty in ISR builds
-    snippetAliases = await loadSnippetsForIsr(projectSlug, rawContent, MDXComponents);
-  } else {
-    // Static mode: Use pre-compiled snippets from build time
-    // This maps import aliases to compiled components:
-    //   import Propagating from '/snippets/custom-subpath-propagating.mdx'
-    // maps 'Propagating' -> SnippetComponents['CustomSubpathPropagating']
-    snippetAliases = buildSnippetAliasMap(rawContent, SnippetComponents);
-  }
-
-  // Preprocess MDX content to strip snippet imports
-  // (snippets are injected globally via AllComponents)
-  const content = preprocessMdx(rawContent, { assetVersion: config.assetVersion });
-
-  // Pre-resolve unique slugs for every <Step> on the page so duplicate titles
-  // across separate <Steps> blocks get -2, -3, ... suffixes that match the
-  // build-time TOC. Provider supplies the list to <Step> via context.
-  const stepEntries: StepSlugEntry[] = extractHeadings(content)
-    .filter(h => typeof h.stepNumber === 'number')
-    .map(h => ({ title: h.text, slug: h.id }));
-
-  // Extract and compile inline component exports from MDX
-  // Only pass MDXComponents (server-compatible) to inline extraction
-  const { inlineComponents, paramFields } = await extractInlineComponents(content, MDXComponents);
-
-  // Check for component name collisions and warn
-  const overriddenComponents = Object.keys(inlineComponents).filter(
-    (name) => name in MDXComponents
-  );
-  if (overriddenComponents.length > 0) {
-    console.warn(
-      `[MDX] Inline component(s) override built-in: ${overriddenComponents.join(', ')} in ${slug.join('/')}`
-    );
-  }
-
-  // Merge all components for MDXRemote:
-  // 1. Built-in MDX components (Card, Note, etc.)
-  // 2. Compiled snippet components (by filename-based names)
-  // 3. Snippet alias mappings (user's import aliases -> components)
-  // 4. Inline component exports from this MDX file
-  // 5. Auto-prefix `a` for hostAtDocs sites (so /path → /docs/path)
-  const AllComponentsWithInline = {
-    ...MDXComponents,
-    ...SnippetComponents,
-    ...snippetAliases,
-    ...inlineComponents,
-    // When hostAtDocs is true, override the base `a` from MDXComponents.tsx
-    // to auto-prefix absolute internal links with /docs.
-    // Styling must stay in sync with the base `a` in MDXComponents.tsx.
-    ...(hostAtDocs ? {
-      a: ({ ariaLabel, href, ...props }: any) => {
-        const needsPrefix = href?.startsWith('/') && !href.startsWith('/docs/') && href !== '/docs';
-        return (
-          <a
-            className="text-theme-accent hover:text-theme-accent-hover transition-colors"
-            aria-label={ariaLabel}
-            href={needsPrefix ? `/docs${href}` : href}
-            {...props}
-          />
-        );
-      },
-    } : {}),
-  };
-
-  // Check if this is an API page (has api or openapi frontmatter)
-  const isApiPage = !!data.api || !!data.openapi;
-
-  // Check if wide mode is enabled (hides TOC, content expands to full width)
-  const isWideMode = data.mode === 'wide';
-
-  // Check if content contains a Panel component (replaces ToC with custom sidebar content)
-  const hasPanel = containsPanel(content);
-
-  // Check if content contains View components (multi-view content like language-specific docs)
-  const hasView = containsView(content);
-  
-  // Parse OpenAPI endpoint data if openapi frontmatter is present
-  let openApiEndpointData: OpenApiEndpointData | null = null;
-  let openApiCodeExamples: CodeExample[] | null = null;
-  let openApiError: string | null = null;
-
-  // OpenAPI spec parsing - supports both static and ISR modes
-  let lastFailure: { err: unknown; specPath: string } | null = null;
-  if (data.openapi && typeof data.openapi === 'string') {
-    try {
-      // Normalize config to array (handles string, array, or undefined)
-      const openApiConfig = config.api?.openapi;
-      const allSpecPaths: string[] = typeof openApiConfig === 'string'
-        ? [openApiConfig]
-        : Array.isArray(openApiConfig)
-          ? openApiConfig
-          : [];
-
-      const parsed = parseOpenApiFrontmatter(
-        data.openapi,
-        allSpecPaths.length > 0 ? allSpecPaths : undefined
-      );
-
-      const baseSpecs = parsed.isShortFormat && allSpecPaths.length > 1
-        ? allSpecPaths
-        : [parsed.specPath];
-      // For each base spec, expand into [<base>.<lang>.ext, <base>.ext] when
-      // the page is under a localized URL. Resolver tries each in order; the
-      // first that loads wins. Missing lang variant falls back to English.
-      const specsToTry = baseSpecs.flatMap(p => candidateSpecPaths(p, currentLang));
-
-      // Hoist mode-dependent values before the loop
-      const useIsr = isIsrMode() && !!projectSlug;
-      const resolveSpec = useIsr
-        ? (await import('@/lib/openapi-isr')).resolveOpenApiSpec
-        : null;
-      const contentDir = useIsr ? null : getContentDir();
-
-      for (let i = 0; i < specsToTry.length; i++) {
-        const specPath = specsToTry[i];
-        try {
-          if (resolveSpec && projectSlug) {
-            const spec = await resolveSpec(projectSlug, specPath);
-            openApiEndpointData = parseEndpoint(
-              spec as Parameters<typeof parseEndpoint>[0],
-              parsed.method,
-              parsed.path,
-              specPath
-            );
-          } else {
-            const { api } = await getCachedSpec(specPath, contentDir!);
-            openApiEndpointData = parseEndpoint(api, parsed.method, parsed.path, specPath);
-          }
-          lastFailure = null;
-          break;
-        } catch (err) {
-          lastFailure = { err, specPath };
-          const isLast = i === specsToTry.length - 1;
-          if (!isLast) {
-            // Lang variant (or intermediate candidate) failed — log so we
-            // notice transient R2 errors that silently fall through to English.
-            console.warn(
-              `[openapi] spec candidate "${specPath}" failed; trying next: ${(err as Error).message}`
-            );
-          }
-        }
-      }
-
-      if (lastFailure) {
-        throw lastFailure.err;
-      }
-
-      // Generate code examples
-      if (openApiEndpointData) {
-        const { method: authMethod, headerName: authHeaderName } = resolveAuth(openApiEndpointData, config);
-        const languages = config.api?.examples?.languages;
-        openApiCodeExamples = generateCodeExamples(openApiEndpointData, { authMethod, authHeaderName, languages });
-      }
-    } catch (err) {
-      const typed = classifyOpenApiLoadError(err, lastFailure?.specPath ?? null);
-      console.warn(formatOpenApiWarning(typed));
-      openApiError = typed.suggestion
-        ? `${typed.message} — ${typed.suggestion}`
-        : typed.message;
-    }
-  }
-
-  // Parse MDX api field for pages with api: frontmatter (but not openapi:)
-  let mdxApiMethod: HttpMethod | null = null;
-  let mdxApiPath: string | null = null;
-
-  if (data.api && typeof data.api === 'string' && !data.openapi) {
-    const parsed = parseMdxApiField(data.api);
-    if (parsed) {
-      mdxApiMethod = parsed.method;
-      mdxApiPath = parsed.path;
-    }
-  }
-
-  // RSS feed icon for pages with rss: true
-  const rssIcon = data.rss ? (
-    <a
-      href={hostAtDocs ? '/docs/feed.xml' : '/feed.xml'}
-      target="_blank"
-      rel="noopener noreferrer"
-      aria-label="Subscribe to RSS feed"
-      title="RSS feed"
-      className="flex-shrink-0 text-[var(--color-text-muted)] hover:text-[var(--color-primary)] transition-colors cursor-pointer"
-    >
-      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" className="w-5 h-5">
-        <circle cx="6.18" cy="17.82" r="2.18" />
-        <path d="M4 4.44v2.83c7.03 0 12.73 5.7 12.73 12.73h2.83c0-8.59-6.97-15.56-15.56-15.56zm0 5.66v2.83c3.9 0 7.07 3.17 7.07 7.07h2.83c0-5.47-4.43-9.9-9.9-9.9z" />
-      </svg>
-    </a>
-  ) : null;
-
-  // Contextual AI Actions menu options
-  const contextualOptions = getContextualOptions(config);
-  const hasAiActions = contextualOptions.length > 0;
-
-  // Prose class for MDX content styling (defined in base.css)
-  const proseClasses = 'prose max-w-none';
-
-  // Playground configuration — covers both openapi: and api: pages
-  const hasApiEndpoint = openApiEndpointData || (mdxApiMethod && mdxApiPath);
-  const playgroundDisplay = hasApiEndpoint
-    ? ((data.playground as 'interactive' | 'simple' | 'none' | undefined)
-        || config.api?.playground?.display || 'interactive') as 'interactive' | 'simple' | 'none'
-    : 'none';
-  const mdxServerConfig = config.api?.mdx?.server;
-  const fallbackServerUrl = Array.isArray(mdxServerConfig) ? mdxServerConfig[0] : mdxServerConfig;
-  // Force proxy on hostAtDocs sites — direct mode is always cross-origin there
-  const proxyEnabled = hostAtDocs
-    || config.api?.playground?.proxy
-    || (config.api?.playground?.proxy == null && playgroundDisplay === 'interactive');
-
-  // Build endpoint data for api: pages (for playground)
-  let mdxEndpointData: OpenApiEndpointData | undefined;
-  if (!openApiEndpointData && mdxApiMethod && mdxApiPath && playgroundDisplay !== 'none') {
-    mdxEndpointData = buildEndpointFromMdx(mdxApiMethod, mdxApiPath, paramFields, fallbackServerUrl);
-  }
-
-  const resolvedMdxAuth = resolveAuth(mdxEndpointData, config);
-  const resolvedOpenApiAuth = resolveAuth(openApiEndpointData, config);
-
-  // For API pages, wrap the entire content area with ApiPageWrapper
-  // so code panels can be positioned as siblings at the page level
-  if (isApiPage) {
-    return (
-      <>{jsonLdScript}<ApiPageWrapper>
-        <article className="px-4 sm:px-6 lg:px-8 py-6 sm:py-10 flex-1 min-w-0">
-          {/* Breadcrumb */}
-          <Breadcrumb slug={slug} config={config} />
-
-          {/* Page Header */}
-          {data.title && (
-            <header className="mb-4 sm:mb-6">
-              <div className="flex items-center gap-3">
-                <h1 className="text-2xl sm:text-3xl lg:text-4xl font-bold text-theme-text-primary tracking-tight">
-                  {data.title}
-                </h1>
-                {rssIcon}
-                {hasAiActions && <div className="ml-auto flex-shrink-0 hidden sm:block"><AIActionsMenu options={contextualOptions} projectName={config.name} /></div>}
-              </div>
-              {data.description && (
-                <p className="text-base sm:text-lg text-theme-text-secondary leading-relaxed mt-2 sm:mt-3">
-                  {data.description}
-                </p>
-              )}
-              {hasAiActions && <div className="mt-3 sm:hidden" style={{ paddingLeft: 0 }}><AIActionsMenu options={contextualOptions} projectName={config.name} /></div>}
-            </header>
-          )}
-
-          {/* Content */}
-          <div className={proseClasses}>
-            {/* MDX API endpoint badge (for pages with api: frontmatter) */}
-            {mdxApiMethod && mdxApiPath && (
-              mdxEndpointData && playgroundDisplay !== 'none' ? (
-                <OpenApiEndpoint
-                  endpoint={mdxEndpointData}
-                  playgroundOnly
-                  playgroundDisplay={playgroundDisplay}
-                  authMethod={resolvedMdxAuth.method}
-                  authHeaderName={resolvedMdxAuth.headerName}
-                  serverUrl={fallbackServerUrl}
-                  proxyEnabled={proxyEnabled}
-                  languages={config.api?.examples?.languages}
-                />
-              ) : (
-                <ApiEndpoint
-                  method={mdxApiMethod}
-                  path={mdxApiPath}
-                  baseUrl={fallbackServerUrl}
-                />
-              )
-            )}
-
-            {/* OpenAPI endpoint documentation (auto-generated from spec) */}
-            {openApiEndpointData && (
-              <OpenApiEndpoint
-                endpoint={openApiEndpointData}
-                codeExamples={openApiCodeExamples || undefined}
-                playgroundDisplay={playgroundDisplay}
-                authMethod={resolvedOpenApiAuth.method}
-                authHeaderName={resolvedOpenApiAuth.headerName}
-                serverUrl={fallbackServerUrl}
-                proxyEnabled={proxyEnabled}
-                languages={config.api?.examples?.languages}
-              />
-            )}
-
-            {/* OpenAPI error — shown when spec parsing fails */}
-            {!openApiEndpointData && openApiError && (
-              <OpenApiError message={openApiError} slug={slug.join('/')} />
-            )}
-
-            {/* Additional MDX content — strip <ResponseExample> on OpenAPI pages
-                (auto-generated ResponseExamplePanel already handles responses) */}
-            <ImagePriorityProvider>
-              <StepSlugProvider entries={stepEntries}>
-                <MDXRemote
-                  source={openApiEndpointData
-                    ? content.replace(/<ResponseExample>[\s\S]*?<\/ResponseExample>/g, '')
-                    : content}
-                  components={AllComponentsWithInline}
-                  options={{
-                    // Keep expression props (e.g. cols={2}) compatible under next-mdx-remote v6.
-                    ...mdxSecurityOptions,
-                    mdxOptions: {
-                      remarkPlugins: [remarkGfm, [remarkVisibility, { audience: 'humans' }], ...getTypographyRemarkPlugins(config), ...getLatexRemarkPlugins(config)],
-                      rehypePlugins: [rehypeNoZoomToData, rehypeClassToClassName, rehypeCodeMeta, createShikiRehypePlugin(highlighter, config), rehypeRestoreDataTitle, ...getLatexRehypePlugins(config), rehypeSlug],
-                      recmaPlugins: [recmaCompoundComponents],
-                    },
-                  }}
-                />
-              </StepSlugProvider>
-            </ImagePriorityProvider>
-          </div>
-
-          {/* Previous/Next Navigation */}
-          <PageNavigation currentSlug={slug.join('/')} config={config} />
-          <SocialFooter config={config} hidden={data.hideFooter} projectSlug={projectSlug ?? undefined} />
-        </article>
-      </ApiPageWrapper></>
-    );
-  }
-
-  // MDX content for non-API pages (extracted for conditional ViewWrapper wrapping)
-  const mdxContent = (
-    <StepSlugProvider entries={stepEntries}>
-      <MDXRemote
-        source={content}
-        components={AllComponentsWithInline}
-        options={{
-          // Keep expression props (e.g. cols={2}) compatible under next-mdx-remote v6.
-          ...mdxSecurityOptions,
-          mdxOptions: {
-            remarkPlugins: [remarkGfm, [remarkVisibility, { audience: 'humans' }], ...getTypographyRemarkPlugins(config), ...getLatexRemarkPlugins(config)],
-            rehypePlugins: [rehypeNoZoomToData, rehypeClassToClassName, rehypeCodeMeta, createShikiRehypePlugin(highlighter, config), rehypeRestoreDataTitle, ...getLatexRehypePlugins(config), rehypeSlug],
-            recmaPlugins: [recmaCompoundComponents],
-          },
-        }}
-      />
-    </StepSlugProvider>
-  );
-
-  // Shared article content for non-API pages
-  const articleContent = (
-    <article className="px-4 sm:px-6 lg:px-8 py-6 sm:py-10">
-      {/* Breadcrumb */}
-      <Breadcrumb slug={slug} config={config} />
-
-      {/* Page Header */}
-      {data.title && (
-        <header className="mb-6 sm:mb-10">
-          <div className="flex items-center gap-3">
-            <h1 className="text-2xl sm:text-3xl lg:text-4xl font-bold text-theme-text-primary tracking-tight">
-              {data.title}
-            </h1>
-            {rssIcon}
-            {hasAiActions && <div className="ml-auto flex-shrink-0 hidden sm:block"><AIActionsMenu options={contextualOptions} projectName={config.name} /></div>}
-          </div>
-          {data.description && (
-            <p className="text-base sm:text-lg text-theme-text-secondary leading-relaxed mt-2 sm:mt-3">
-              {data.description}
-            </p>
-          )}
-          {hasAiActions && <div className="mt-3 sm:hidden" style={{ paddingLeft: 0 }}><AIActionsMenu options={contextualOptions} projectName={config.name} /></div>}
-        </header>
-      )}
-
-      {/* Content */}
-      <div className={proseClasses}>
-        <ImagePriorityProvider>
-          {hasView ? <ViewWrapper>{mdxContent}</ViewWrapper> : mdxContent}
-        </ImagePriorityProvider>
-
-        {/* Previous/Next Navigation - inside prose to match content width */}
-        <PageNavigation currentSlug={slug.join('/')} config={config} isWideMode={isWideMode || hasPanel} />
-      </div>
-      <SocialFooter config={config} hidden={data.hideFooter} projectSlug={projectSlug ?? undefined} />
-    </article>
-  );
-
-  // Pages with Panel component: use PanelWrapper to move Panel content to sidebar
-  if (hasPanel) {
-    return <>{jsonLdScript}<PanelWrapper>{articleContent}</PanelWrapper></>;
-  }
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const input = await resolveInput(params);
+  return buildDocMetadata(input);
+}
 
-  // Non-API pages: standard layout with Table of Contents (or inline chat)
-  // PageColumns handles TOC ↔ chat column switching on xl+ screens
-  return (
-    <>
-      {jsonLdScript}
-      <PageColumns toc={<TableOfContents content={content} />} isWideMode={isWideMode}>
-        {articleContent}
-      </PageColumns>
-    </>
-  );
+export default async function DocPage({ params }: PageProps) {
+  const input = await resolveInput(params);
+  return renderDocPage(input);
 }