handoff-app 1.2.2-7 → 2.0.0-1

package/src/app/next.config.mjs

@@ -10,9 +10,60 @@ const resolveBasePath = (rawBasePath) => {
   return trimmed ? `/${trimmed}` : '';
 };
 
+// Resolved build target drives Next's output mode. The target — not NODE_ENV
+// — decides static export vs. dynamic packaging, so workspace dev, the static snapshot, and the
+// registry app never get conflated:
+//   - `static`   → `output: 'export'` (a self-contained static snapshot).
+//   - `registry` → `output: 'standalone'` (a deployable dynamic Next.js app + traced node_modules).
+//   - otherwise  → a normal server (workspace `next dev`/`start`).
+const handoffBuildTarget = process.env.HANDOFF_BUILD_TARGET;
+const handoffWorkingPath = path.resolve('%HANDOFF_WORKING_PATH%');
+
+// A configured custom asset-storage adapter module (relative to the consumer project). It is loaded
+// by a variable dynamic import at runtime, which nft cannot statically trace, so force it (and its
+// resolvable deps) into the registry bundle. Empty/unset for the built-in database/Vercel adapters.
+const handoffAssetStorageModule = '%HANDOFF_ASSET_STORAGE_MODULE%';
+const resolveAssetStorageInclude = () => {
+  if (handoffBuildTarget !== 'registry' || !handoffAssetStorageModule || handoffAssetStorageModule.startsWith('%HANDOFF_')) {
+    return undefined;
+  }
+  const abs = path.isAbsolute(handoffAssetStorageModule) ? handoffAssetStorageModule : path.resolve(handoffWorkingPath, handoffAssetStorageModule);
+  return { '/api/**': [abs] };
+};
+
+const resolveOutputMode = (target) => {
+  if (target === 'static') {
+    // Static export disables Next API routes, which the workspace docs read API (`/api/docs/*`)
+    // depends on, so the static build materializes that read model into route-shaped files instead.
+    return 'export';
+  }
+  if (target === 'registry') {
+    // The registry app is a deployable dynamic server (DB-backed docs/registry APIs). Standalone
+    // traces the runtime + selected DB driver into a self-contained bundle for Vercel/Node/containers
+    // and never runs a static export.
+    return 'standalone';
+  }
+  return undefined;
+};
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
-  output: 'export',
+  output: resolveOutputMode(handoffBuildTarget),
+  // The tracer only copies files inside its root, so root it at the consumer project — the common
+  // ancestor of the staged app (`node_modules/handoff-app/.handoff/<projectId>`) and the runtime deps
+  // hoisted to the top-level `node_modules`. Rooting at the package dir would trace an empty
+  // `node_modules` and ship a non-bootable bundle. Registry-only; workspace dev/static is unchanged.
+  outputFileTracingRoot: handoffBuildTarget === 'registry' ? handoffWorkingPath : undefined,
+  // nft speculatively traces the export-only paths the app references (`export-detail.json` and the
+  // materializer's `.next/export/**` targets) as runtime deps. They never exist in a `standalone`
+  // build, and `copyTracedFiles` copies traced files with no existence guard, so leaving them in
+  // fails the build with `ENOENT`. Exclude them (`**` matches the server + every per-page trace).
+  // Registry-only; static export, which legitimately produces these files, is untouched.
+  outputFileTracingExcludes:
+    handoffBuildTarget === 'registry' ? { '**': ['**/export-detail.json', '**/.next/export/**'] } : undefined,
+  // Force a configured custom asset-storage module into the registry trace (dynamic import is opaque
+  // to nft). Its SDK deps are additionally asserted via `getRequiredRegistryRuntimeModules`.
+  outputFileTracingIncludes: resolveAssetStorageInclude(),
   reactStrictMode: true,
   pageExtensions: ['js', 'jsx', 'ts', 'tsx'],
   trailingSlash: true,
@@ -26,25 +77,42 @@ const nextConfig = {
   typescript: {
     tsconfigPath: 'tsconfig.json',
   },
-  //distDir: 'out',
   basePath: resolveBasePath('%HANDOFF_APP_BASE_PATH%'),
   env: {
     HANDOFF_PROJECT_ID: '%HANDOFF_PROJECT_ID%',
     HANDOFF_APP_BASE_PATH: '%HANDOFF_APP_BASE_PATH%',
+    // Resolved build target, baked so the client can tell a self-contained static snapshot apart
+    // from a live workspace/registry app (e.g. the header hides the runtime-mode badge in the
+    // static export). Read straight from the build env — empty for workspace dev/start.
+    HANDOFF_BUILD_TARGET: handoffBuildTarget ?? '',
     HANDOFF_WORKING_PATH: '%HANDOFF_WORKING_PATH%',
     HANDOFF_MODULE_PATH: '%HANDOFF_MODULE_PATH%',
     HANDOFF_EXPORT_PATH: '%HANDOFF_EXPORT_PATH%',
     HANDOFF_WEBSOCKET_PORT: '%HANDOFF_WEBSOCKET_PORT%',
+    // Resolved runtime mode + registry connection *inputs* (names only, never secrets), baked at
+    // build time so the deployed registry app resolves its mode and DB env-var name without any
+    // build-machine filesystem (the absolute paths above do not exist on the deploy host). Mode stays
+    // config-only — these are derived from `runtime.*`, not inferred from env at runtime. The DB
+    // connection string itself is read from the named env var at request time (deployment-supplied).
+    HANDOFF_RUNTIME_MODE: '%HANDOFF_RUNTIME_MODE%',
+    HANDOFF_REGISTRY_ADAPTER: '%HANDOFF_REGISTRY_ADAPTER%',
+    HANDOFF_REGISTRY_DATABASE_URL_ENV: '%HANDOFF_REGISTRY_DATABASE_URL_ENV%',
+    HANDOFF_REGISTRY_API_TOKEN_ENV: '%HANDOFF_REGISTRY_API_TOKEN_ENV%',
+    // Asset storage selection (provider + non-secret options + env-var names). Secret values (Blob
+    // token, custom credentials) are read from their named env var at request time, never baked.
+    HANDOFF_ASSET_STORAGE_ADAPTER: '%HANDOFF_ASSET_STORAGE_ADAPTER%',
+    HANDOFF_ASSET_STORAGE_MODULE: '%HANDOFF_ASSET_STORAGE_MODULE%',
+    HANDOFF_ASSET_STORAGE_TOKEN_ENV: '%HANDOFF_ASSET_STORAGE_TOKEN_ENV%',
+    HANDOFF_ASSET_STORAGE_MAX_INLINE_BYTES: '%HANDOFF_ASSET_STORAGE_MAX_INLINE_BYTES%',
+    HANDOFF_ASSET_STORAGE_OPTIONS: '%HANDOFF_ASSET_STORAGE_OPTIONS%',
   },
   images: {
     unoptimized: true,
   },
   sassOptions: {
     additionalData: (content, _) => {
-      // Local state
       let foundTheme = false;
 
-      // Local environment
       const env = {
         HANDOFF_PROJECT_ID: '%HANDOFF_PROJECT_ID%',
         HANDOFF_APP_BASE_PATH: '%HANDOFF_APP_BASE_PATH%',
@@ -54,22 +122,16 @@ const nextConfig = {
         HANDOFF_WEBSOCKET_PORT: '%HANDOFF_WEBSOCKET_PORT%',
       };
 
-      // Check if client configuration exists
       const clientConfigPath = path.resolve(env.HANDOFF_WORKING_PATH, 'handoff.config.json');
       if (fs.existsSync(clientConfigPath)) {
-        // Load client configuration
         const clientConfigRaw = fs.readFileSync(clientConfigPath);
         const clientConfig = JSON.parse(clientConfigRaw);
-        // Check if client configuration is a valid object
         if (typeof clientConfig === 'object' && !Array.isArray(clientConfig) && clientConfig !== null) {
-          // Check if the client configuration specifies a theme
-          // If the theme is specified, check if the theme exists in the 'themes' folder
           if (
             clientConfig.hasOwnProperty('app') &&
             clientConfig['app'].hasOwnProperty('theme') &&
             fs.existsSync(path.resolve(env.HANDOFF_WORKING_PATH, 'theme', `${clientConfig['app']['theme']}.scss`))
           ) {
-            // Use custom theme
             foundTheme = true;
             content = content + `\n@import '${path.resolve(env.HANDOFF_WORKING_PATH, 'theme', clientConfig['app']['theme'])}';`;
             console.log(
@@ -84,9 +146,7 @@ const nextConfig = {
       }
 
       if (!foundTheme) {
-        // Check if there is a custom version of the default theme
         if (fs.existsSync(path.resolve(env.HANDOFF_WORKING_PATH, 'theme', `default.scss`))) {
-          // Use custom theme
           content = content + `\n@import 'theme/default';`;
           console.log(
             `- ${chalk.cyan('info')} Using default app theme override (path: ${path.resolve(
@@ -96,7 +156,6 @@ const nextConfig = {
             )})`
           );
         } else {
-          // Use default theme
           content = content + `\n@import 'themes/default';`;
           console.log(`- ${chalk.cyan('info')} Using default app theme`);
         }

package/src/app/pages/[...slug]/index.tsx

@@ -1,6 +1,5 @@
 import { GetStaticProps } from 'next';
 import Head from 'next/head';
-import Link from 'next/link';
 import { useRef } from 'react';
 import ReactMarkdown from 'react-markdown';
 import rehypeRaw from 'rehype-raw';
@@ -8,32 +7,101 @@ import remarkGfm from 'remark-gfm';
 import Layout from '../../components/Layout/Main';
 import { MarkdownComponents, remarkCodeMeta } from '../../components/Markdown/MarkdownComponents';
 import { PageTOC } from '../../components/Navigation/AnchorNav';
+import NotFound from '../../components/NotFound';
 import HeadersType from '../../components/Typography/Headers';
+import defaultPages from '../../generated/default-pages.json';
 import {
   buildCatchAllStaticPaths,
   DocumentationProps,
   fetchDocPageMarkdown,
   getClientRuntimeConfig,
+  getNavProps,
+  isRegistryRuntime,
 } from '../../components/util';
+import { resolveDocsBackend } from '../../lib/docs-api/backend';
+
+/**
+ * Registry deployments can run across independent serverless instances whose local ISR caches do
+ * not share on-demand invalidations. Keep mutable page entries short-lived so every instance
+ * converges on the published DB record even when it did not handle the publish request.
+ */
+const REGISTRY_PAGE_REVALIDATE_SECONDS = 1;
+
+type BakedDefaultPage = { metadata: Record<string, unknown>; content: string };
+
+/** Normalize published records and baked frontmatter into the page component's metadata contract. */
+const documentationMetadata = (source: Record<string, unknown>) => {
+  const value = (key: string): string => (typeof source[key] === 'string' ? (source[key] as string) : '');
+  const title = value('title');
+  const description = value('description');
+  return {
+    title,
+    description,
+    metaTitle: value('metaTitle') || title,
+    metaDescription: value('metaDescription') || description,
+  };
+};
 
 export async function getStaticPaths() {
+  // Registry resolves every catch-all page on demand so a cold serverless instance queries the DB
+  // before it can cache a package default. Defaults are baked into the server bundle as JSON.
+  // Workspace/static stays fully prerendered from markdown (workspace pages included).
+  if (isRegistryRuntime()) {
+    return { paths: [], fallback: 'blocking' as const };
+  }
   return {
     paths: buildCatchAllStaticPaths(),
     fallback: false,
   };
 }
 
-export const getStaticProps: GetStaticProps = (context) => {
+export const getStaticProps: GetStaticProps = async (context) => {
   const { slug } = context.params as { slug: string[] };
+  const config = getClientRuntimeConfig();
   const dirParts = slug.slice(0, -1);
   const file = slug[slug.length - 1];
   const docPath = dirParts.length > 0 ? `docs/${dirParts.join('/')}/` : 'docs/';
   const sectionId = `/${slug[0]}`;
 
+  // Registry mode resolves published content first, then the package-default fallback baked during
+  // the build. Workspace markdown is never read and the deployed server needs no build-machine path.
+  if (isRegistryRuntime()) {
+    const id = slug.join('/');
+    const detail = await (await resolveDocsBackend()).getPageDetail(id);
+    if (detail) {
+      const navProps = await getNavProps(sectionId);
+      return {
+        props: {
+          metadata: documentationMetadata(detail as unknown as Record<string, unknown>),
+          content: detail.content,
+          ...navProps,
+          config,
+        },
+        revalidate: REGISTRY_PAGE_REVALIDATE_SECONDS,
+      };
+    }
+
+    const defaultPage = (defaultPages as Record<string, BakedDefaultPage>)[id];
+    if (defaultPage) {
+      const navProps = await getNavProps(sectionId);
+      return {
+        props: {
+          metadata: documentationMetadata(defaultPage.metadata),
+          content: defaultPage.content,
+          ...navProps,
+          config,
+        },
+        revalidate: REGISTRY_PAGE_REVALIDATE_SECONDS,
+      };
+    }
+
+    return { notFound: true, revalidate: REGISTRY_PAGE_REVALIDATE_SECONDS };
+  }
+
   return {
     props: {
-      ...fetchDocPageMarkdown(docPath, file, sectionId).props,
-      config: getClientRuntimeConfig(),
+      ...(await fetchDocPageMarkdown(docPath, file, sectionId)).props,
+      config,
     },
   };
 };
@@ -41,28 +109,14 @@ export const getStaticProps: GetStaticProps = (context) => {
 export default function DocCatchAllPage({ content, menu, metadata, current, config }: DocumentationProps) {
   const bodyRef = useRef<HTMLDivElement>(null);
 
-  if (!content) {
+  if (!content && !metadata?.title) {
     return (
       <div className="flex min-h-screen flex-col items-center justify-center bg-white dark:bg-gray-900">
         <Head>
           <title>404 - Page Not Found</title>
           <meta name="description" content="Page Not Found" />
         </Head>
-        <div className="flex flex-col items-center">
-          <div className="mb-2 text-7xl font-bold text-gray-800 dark:text-white">404</div>
-          <h1 className="mb-4 text-2xl font-semibold text-gray-700 dark:text-gray-300">Oops! Page not found.</h1>
-          <p className="mb-6 max-w-md text-center text-gray-500 dark:text-gray-400">
-            Sorry, the page you are looking for does not exist or has been moved.
-            <br />
-            Please check the URL or return to the homepage.
-          </p>
-          <Link
-            href="/"
-            className="rounded-md bg-blue-600 px-6 py-2 font-medium text-white shadow-md transition-colors duration-200 hover:bg-blue-700"
-          >
-            Go Home
-          </Link>
-        </div>
+        <NotFound />
       </div>
     );
   }

package/src/app/pages/_app.tsx

@@ -1,14 +1,17 @@
 import type { AppProps } from 'next/app';
 
+import { NavProvider } from '../components/context/NavProvider';
 import '../css/index.css';
 import '../css/theme.css';
 
 function MyApp({ Component, pageProps }: AppProps) {
   return (
-    <>
+    // NavProvider lives above the page tree so the registry nav (shell + entities) is fetched once
+    // and cached across soft navigations, resetting only on hard refresh.
+    <NavProvider initialNav={pageProps.navData} currentSectionId={pageProps.currentSectionId}>
       {/* @ts-ignore */}
       <Component {...pageProps} />
-    </>
+    </NavProvider>
   );
 }
 

package/src/app/pages/api/docs/artifacts/[...artifactPath].ts

@@ -0,0 +1,16 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { handleDocsRoute, serveArtifactBySegments } from '@/lib/docs-api';
+
+/**
+ * Canonical artifact route — `GET {basePath}/api/docs/artifacts/{artifactPath}`.
+ * Serves CSS/JS/HTML/JSON/text artifacts by logical path with traversal rejection and correct
+ * content types. Every artifact reference in generated HTML and docs read data resolves here, from
+ * the filesystem in workspace mode and from the database in registry mode.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    const { artifactPath } = req.query;
+    const segments = Array.isArray(artifactPath) ? artifactPath : artifactPath ? [artifactPath] : undefined;
+    await serveArtifactBySegments(res, segments, backend);
+  });
+}

package/src/app/pages/api/docs/assets/[collection]/[...path].ts

@@ -0,0 +1,50 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { singleQueryValue } from '@/lib/api/query';
+import { handleDocsRoute, sendDocsError } from '@/lib/docs-api';
+
+/**
+ * `GET /api/docs/assets/{collection}/{...path}`: one asset's content, by its logical path
+ * (`assets/icons/add.svg`, `icons-sprite.svg`, `icons.zip`, `fonts/Inter.zip`, …). Serves the bytes
+ * with the correct `Content-Type`/`Content-Length`, an `ETag` of the content hash, and revalidation
+ * caching (stable logical URLs re-validate when their mapped hash changes); object-backed content is
+ * redirected to a provider URL. Mode-independent.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    const collection = singleQueryValue(req.query.collection);
+    const segments = req.query.path;
+    const logicalPath = Array.isArray(segments) ? segments.join('/') : segments;
+    if (!collection || !logicalPath) {
+      sendDocsError(res, 'not_found', 'Missing asset collection or path.');
+      return;
+    }
+
+    const content = await backend.getAssetContent(collection, logicalPath);
+    if (!content) {
+      sendDocsError(res, 'artifact_not_found', `Asset "${logicalPath}" was not found in collection "${collection}".`);
+      return;
+    }
+
+    // Object-backed content: redirect to the provider URL (keeps large payloads out of the function).
+    if (content.redirectUrl) {
+      res.redirect(302, content.redirectUrl);
+      return;
+    }
+    if (!content.body) {
+      sendDocsError(res, 'artifact_not_found', `Asset "${logicalPath}" has no resolvable content.`);
+      return;
+    }
+
+    const etag = `"${content.contentHash}"`;
+    // Logical URLs revalidate against the content-hash ETag so a republish surfaces new bytes.
+    res.setHeader('ETag', etag);
+    res.setHeader('Cache-Control', 'public, max-age=0, must-revalidate');
+    if (req.headers['if-none-match'] === etag) {
+      res.status(304).end();
+      return;
+    }
+    res.setHeader('Content-Type', content.contentType);
+    res.setHeader('Content-Length', String(content.body.length));
+    res.status(200).send(content.body);
+  });
+}

package/src/app/pages/api/docs/assets/[collection]/index.ts

@@ -0,0 +1,22 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { singleQueryValue } from '@/lib/api/query';
+import { handleDocsRoute, sendDocsData, sendDocsError } from '@/lib/docs-api';
+
+/**
+ * `GET /api/docs/assets/{collection}`: lightweight metadata for every asset in a collection. Never
+ * carries a binary/SVG body: bodies are fetched one at a time via the `[...path]` content route, and
+ * the icon grid uses the published sprite. Mode-independent; `Cache-Control: no-store` so a publish
+ * surfaces without a rebuild/redeploy.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    const collection = singleQueryValue(req.query.collection);
+    if (!collection) {
+      sendDocsError(res, 'not_found', 'Missing asset collection.');
+      return;
+    }
+    const assets = await backend.listAssets(collection);
+    res.setHeader('Cache-Control', 'no-store, max-age=0');
+    sendDocsData(res, 200, { collection, assets });
+  });
+}

package/src/app/pages/api/docs/components/[id]/assets/[asset].ts

@@ -0,0 +1,33 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { singleQueryValue } from '@/lib/api/query';
+import { handleDocsRoute, sendDocsError, serveArtifactBySegments } from '@/lib/docs-api';
+
+/**
+ * `GET /api/docs/components/{id}/assets/{asset}` — serves a component asset artifact:
+ * `style`→`component/{id}.css`, `script`→`component/{id}.js`,
+ * `client`→`component/{id}.client.js`. Unknown asset kinds are `404 not_found`; a known asset with
+ * no generated/published artifact is `404 artifact_not_found`. In registry mode the artifact
+ * resolves from the database.
+ */
+const ASSET_FILE_SUFFIX: Record<string, string> = {
+  style: 'css',
+  script: 'js',
+  client: 'client.js',
+};
+
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    const id = singleQueryValue(req.query.id);
+    const asset = singleQueryValue(req.query.asset);
+    if (!id || !asset) {
+      sendDocsError(res, 'not_found', 'Missing component id or asset kind.');
+      return;
+    }
+    const suffix = ASSET_FILE_SUFFIX[asset];
+    if (!suffix) {
+      sendDocsError(res, 'not_found', `Unknown component asset "${asset}".`);
+      return;
+    }
+    await serveArtifactBySegments(res, ['component', `${id}.${suffix}`], backend);
+  });
+}

package/src/app/pages/api/docs/components/[id]/inspect/[previewId].ts

@@ -0,0 +1,20 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { singleQueryValue } from '@/lib/api/query';
+import { handleDocsRoute, sendDocsError, serveArtifactBySegments } from '@/lib/docs-api';
+
+/**
+ * `GET /api/docs/components/{id}/inspect/{previewId}` — serves the inspect HTML artifact
+ * `component/{id}-{previewId}-inspect.html`. A metadata-only record yields
+ * `404 artifact_not_found`. In registry mode the artifact resolves from the database.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    const id = singleQueryValue(req.query.id);
+    const previewId = singleQueryValue(req.query.previewId);
+    if (!id || !previewId) {
+      sendDocsError(res, 'not_found', 'Missing component id or preview id.');
+      return;
+    }
+    await serveArtifactBySegments(res, ['component', `${id}-${previewId}-inspect.html`], backend);
+  });
+}

package/src/app/pages/api/docs/components/[id]/previews/[previewId].ts

@@ -0,0 +1,21 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { singleQueryValue } from '@/lib/api/query';
+import { handleDocsRoute, sendDocsError, serveArtifactBySegments } from '@/lib/docs-api';
+
+/**
+ * `GET /api/docs/components/{id}/previews/{previewId}` — serves the preview HTML artifact
+ * `component/{id}-{previewId}.html`. A metadata-only record (no generated
+ * preview) yields `404 artifact_not_found`. In registry mode the artifact and its required
+ * references resolve from the database.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    const id = singleQueryValue(req.query.id);
+    const previewId = singleQueryValue(req.query.previewId);
+    if (!id || !previewId) {
+      sendDocsError(res, 'not_found', 'Missing component id or preview id.');
+      return;
+    }
+    await serveArtifactBySegments(res, ['component', `${id}-${previewId}.html`], backend);
+  });
+}

package/src/app/pages/api/docs/components/[id].ts

@@ -0,0 +1,24 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { handleDocsRoute, idFromJsonParam, sendDocsData, sendDocsError } from '@/lib/docs-api';
+
+/**
+ * `GET /api/docs/components/{id}.json` — a single `ComponentListObject` including build state;
+ * `404 not_found` when the component does not exist. The dynamic param
+ * carries the explicit `.json` extension, which is stripped to recover the id. The shape is
+ * identical regardless of whether the filesystem or the database backs it.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    const id = idFromJsonParam(req.query.id);
+    if (!id) {
+      sendDocsError(res, 'not_found', 'Missing component id.');
+      return;
+    }
+    const detail = await backend.getComponentDetail(id);
+    if (!detail) {
+      sendDocsError(res, 'not_found', `Component "${id}" was not found.`);
+      return;
+    }
+    sendDocsData(res, 200, detail);
+  });
+}

package/src/app/pages/api/docs/components.json.ts

@@ -0,0 +1,12 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { handleDocsRoute, sendDocsData } from '@/lib/docs-api';
+
+/**
+ * `GET /api/docs/components.json` — the component list (`ComponentListObject[]`), each record
+ * carrying its `path`. Identical shape in workspace and registry mode.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    sendDocsData(res, 200, await backend.listComponents());
+  });
+}

package/src/app/pages/api/docs/nav.json.ts

@@ -0,0 +1,48 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { getRegistryNavData, type NavTokenSet, type SectionLink } from '@handoff/nav';
+import { setNameForId } from '@handoff/registry/tokens/sets';
+import { ensureGet, resolveDocsBackend, sendDocsData, sendDocsError } from '@/lib/docs-api';
+// Kept static so the baked structure is traced into every registry serverless bundle.
+import navShell from '@/generated/nav-shell.json';
+
+/** Thin registry refresh adapter. The adapter/resolver owns all navigation structure and filling. */
+export default async function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  if (!ensureGet(req, res)) return;
+
+  try {
+    const nav = await getRegistryNavData({
+      shell: navShell as unknown as SectionLink[],
+      load: 'refresh',
+      basePath: process.env.HANDOFF_APP_BASE_PATH,
+      fetchRecords: async () => {
+        const backend = await resolveDocsBackend();
+        const safe = async <T>(read: () => Promise<T[]>): Promise<T[]> => {
+          try {
+            return (await read()) ?? [];
+          } catch {
+            return [];
+          }
+        };
+        const [components, patterns, pages, tokenSets] = await Promise.all([
+          safe(() => backend.listComponents()),
+          safe(() => backend.listPatterns()),
+          safe(() => backend.listPages()),
+          safe(() => backend.listTokenSets()),
+        ]);
+        return {
+          components,
+          patterns,
+          pages,
+          tokenSets: tokenSets
+            .filter((set) => set.kind === 'component')
+            .map((set) => ({ id: setNameForId(set.id), kind: 'component' })) as NavTokenSet[],
+        };
+      },
+    });
+    res.setHeader('Cache-Control', 'no-store, max-age=0');
+    sendDocsData(res, 200, nav);
+  } catch (error) {
+    console.error('Docs navigation response failed.', error);
+    sendDocsError(res, 'unexpected_error', 'Unexpected docs read API error.');
+  }
+}

package/src/app/pages/api/docs/patterns/[id]/preview.ts

@@ -0,0 +1,19 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { singleQueryValue } from '@/lib/api/query';
+import { handleDocsRoute, sendDocsError, serveArtifactBySegments } from '@/lib/docs-api';
+
+/**
+ * `GET /api/docs/patterns/{id}/preview` — serves the pattern preview HTML artifact
+ * `pattern/{id}.html`. A metadata-only pattern yields `404 artifact_not_found`.
+ * In registry mode the artifact resolves from the database.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    const id = singleQueryValue(req.query.id);
+    if (!id) {
+      sendDocsError(res, 'not_found', 'Missing pattern id.');
+      return;
+    }
+    await serveArtifactBySegments(res, ['pattern', `${id}.html`], backend);
+  });
+}

package/src/app/pages/api/docs/patterns/[id].ts

@@ -0,0 +1,24 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { handleDocsRoute, idFromJsonParam, sendDocsData, sendDocsError } from '@/lib/docs-api';
+
+/**
+ * `GET /api/docs/patterns/{id}.json` — a single `PatternListObject` including build state;
+ * `404 not_found` when the pattern does not exist. The dynamic param carries
+ * the explicit `.json` extension, which is stripped to recover the id. The shape is identical
+ * regardless of whether the filesystem or the database backs it.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    const id = idFromJsonParam(req.query.id);
+    if (!id) {
+      sendDocsError(res, 'not_found', 'Missing pattern id.');
+      return;
+    }
+    const detail = await backend.getPatternDetail(id);
+    if (!detail) {
+      sendDocsError(res, 'not_found', `Pattern "${id}" was not found.`);
+      return;
+    }
+    sendDocsData(res, 200, detail);
+  });
+}

package/src/app/pages/api/docs/patterns.json.ts

@@ -0,0 +1,12 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { handleDocsRoute, sendDocsData } from '@/lib/docs-api';
+
+/**
+ * `GET /api/docs/patterns.json` — the pattern list (`PatternListObject[]`).
+ * Identical shape in workspace and registry mode.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    sendDocsData(res, 200, await backend.listPatterns());
+  });
+}

package/src/app/pages/api/docs/tokens/components/[id].ts

@@ -0,0 +1,30 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { handleDocsRoute, idFromJsonParam, sendDocsData, sendDocsError } from '@/lib/docs-api';
+import { tokenFormatStrings } from '@/lib/docs-api/token-detail';
+
+/**
+ * `GET /api/docs/tokens/components/{id}.json` — the `component/{id}` token set: the component token
+ * object (`component`) plus the generated download strings (css/scss/styleDictionary/types) and the
+ * full artifact list. Mode-independent shape. `Cache-Control: no-store` so a publish surfaces without
+ * a rebuild/redeploy.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  return handleDocsRoute(req, res, async (backend) => {
+    const id = idFromJsonParam(req.query.id);
+    if (!id) {
+      sendDocsError(res, 'not_found', 'Missing component token id.');
+      return;
+    }
+    const detail = await backend.getTokenSetDetail(`component/${id}`);
+    if (!detail) {
+      sendDocsError(res, 'not_found', `Component token set "${id}" was not found.`);
+      return;
+    }
+    res.setHeader('Cache-Control', 'no-store, max-age=0');
+    sendDocsData(res, 200, {
+      component: detail.record,
+      ...tokenFormatStrings(detail.artifacts),
+      artifacts: detail.artifacts,
+    });
+  });
+}