handoff-app 1.2.2-6 → 2.0.0-0

package/src/app/pages/foundations/icons/[name]/index.tsx

@@ -9,10 +9,12 @@ import Footer from '../../../../components/Footer';
 import Layout from '../../../../components/Layout/Main';
 import HeadersType from '../../../../components/Typography/Headers';
 import { buttonVariants } from '../../../../components/ui/button';
-import { AssetDocumentationProps, fetchDocPageMarkdown, getClientRuntimeConfig, getTokens } from '../../../../components/util';
+import { AssetDocumentationProps, buildTimeAssets, fetchDocPageMarkdown, getClientRuntimeConfig, getTokens, isRegistryRuntime } from '../../../../components/util';
+import { useSingleAsset, type DisplayableAsset } from '../../../../components/util/useCollectionAssets';
 
-const DisplayIcon: React.FC<{ icon: CoreTypes.IAssetObject }> = ({ icon }) => {
+const DisplayIcon: React.FC<{ icon: DisplayableAsset }> = ({ icon }) => {
   const htmlData = React.useMemo(() => {
+    if (!icon.data) return '';
     // For SSR
     if (typeof window === 'undefined') {
       return icon.data.replace('<svg', '<svg class="o-icon"');
@@ -30,19 +32,28 @@ const DisplayIcon: React.FC<{ icon: CoreTypes.IAssetObject }> = ({ icon }) => {
     return svgElement.outerHTML;
   }, [icon.data]);
 
+  // Registry: no inline body yet, so render the individual asset content URL.
+  if (!icon.data) {
+    return <img className="o-icon" src={icon.src} alt={icon.name} />;
+  }
   return <>{HtmlReactParser(htmlData)}</>;
 };
 
 /**
- * Render all index pages
+ * Render all index pages. In registry mode the icon set is unknown at build time (nothing is baked),
+ * so paths are resolved on demand via `fallback: 'blocking'` and the page hydrates from the API.
  * @returns
  */
 export async function getStaticPaths() {
-  const paths = getTokens().assets?.icons?.map((icon) => ({
-    params: {
-      name: icon.name,
-    },
-  })) ?? [];
+  if (isRegistryRuntime()) {
+    return { paths: [], fallback: 'blocking' as const };
+  }
+  const paths =
+    getTokens().assets?.icons?.map((icon) => ({
+      params: {
+        name: icon.name,
+      },
+    })) ?? [];
 
   return {
     paths,
@@ -58,12 +69,12 @@ export async function getStaticPaths() {
  * @param context GetStaticProps
  * @returns
  */
-export const getStaticProps: GetStaticProps = () => {
+export const getStaticProps: GetStaticProps = async () => {
   return {
     props: {
-      ...fetchDocPageMarkdown('docs/foundations/', 'icons', `/foundations`).props,
+      ...(await fetchDocPageMarkdown('docs/foundations/', 'icons', `/foundations`)).props,
       config: getClientRuntimeConfig(),
-      assets: getTokens().assets,
+      assets: buildTimeAssets(),
     },
   };
 };
@@ -73,12 +84,13 @@ export default function SingleIcon({ menu, metadata, current, config, assets }:
   const nameParam = router.query.name;
   let name = undefined;
   if (typeof nameParam === 'string') { name = nameParam } else if (Array.isArray(nameParam)) { name = nameParam[0] } else { name = undefined }
-  const icon = assets?.icons.find((i) => i.icon === name);
+  // Workspace/static uses the baked asset; registry hydrates the single asset (+ its SVG body) by id.
+  const icon = useSingleAsset('icons', name, assets?.icons?.find((i) => i.icon === name));
 
   const copySvg = React.useCallback<React.MouseEventHandler>(
     (event) => {
       event.preventDefault();
-      if (icon) {
+      if (icon?.data) {
         navigator.clipboard.writeText(icon.data);
       }
     },
@@ -113,7 +125,7 @@ export default function SingleIcon({ menu, metadata, current, config, assets }:
               </Link>
 
               <Link
-                href={'data:text/plain;charset=utf-8,' + encodeURIComponent(icon.data)}
+                href={icon.src ?? 'data:text/plain;charset=utf-8,' + encodeURIComponent(icon.data ?? '')}
                 download={icon.name}
                 className={buttonVariants({ variant: 'outline', size: 'sm' }) + ' font-normal [&_svg]:size-3!'}
               >

package/src/app/pages/foundations/icons/index.tsx

@@ -12,10 +12,12 @@ import { MarkdownComponents, remarkCodeMeta } from '../../../components/Markdown
 import HeadersType from '../../../components/Typography/Headers';
 import { buttonVariants } from '../../../components/ui/button';
 import { Input } from '../../../components/ui/input';
-import { AssetDocumentationProps, fetchDocPageMarkdown, getClientRuntimeConfig, getTokens } from '../../../components/util';
+import { AssetDocumentationProps, buildTimeAssets, fetchDocPageMarkdown, getClientRuntimeConfig } from '../../../components/util';
+import { useCollectionAssets, type DisplayableAsset } from '../../../components/util/useCollectionAssets';
 
-export const DisplayIcon: React.FC<{ icon: CoreTypes.IAssetObject }> = ({ icon }) => {
+export const DisplayIcon: React.FC<{ icon: DisplayableAsset }> = ({ icon }) => {
   const htmlData = React.useMemo(() => {
+    if (!icon.data) return '';
     // For SSR
     if (typeof window === 'undefined') {
       return icon.data.replace('<svg', '<svg class="o-icon"');
@@ -35,7 +37,8 @@ export const DisplayIcon: React.FC<{ icon: CoreTypes.IAssetObject }> = ({ icon }
     <div className="flex flex-col gap-2">
       <Link href={`/foundations/icons/${icon.icon}`}>
         <div className="flex flex-col items-center gap-6 rounded-lg border border-gray-100/80 bg-gray-100/80 py-12 transition-all hover:border-gray-300 hover:bg-gray-100 dark:border-gray-800 dark:bg-gray-900 dark:hover:border-gray-700 dark:hover:bg-gray-900">
-          <div dangerouslySetInnerHTML={{ __html: htmlData }} />
+          {/* Workspace/static: inline SVG body. Registry: the individual asset content URL. */}
+          {icon.data ? <div dangerouslySetInnerHTML={{ __html: htmlData }} /> : <img className="o-icon h-6 w-6" src={icon.src} alt={icon.name} />}
         </div>
       </Link>
       <Link href={`/foundations/icons/${icon.icon}`}>
@@ -55,9 +58,9 @@ export const DisplayIcon: React.FC<{ icon: CoreTypes.IAssetObject }> = ({ icon }
 export const getStaticProps: GetStaticProps = async () => {
   return {
     props: {
-      ...fetchDocPageMarkdown('docs/foundations/', 'icons', `/foundations`).props,
+      ...(await fetchDocPageMarkdown('docs/foundations/', 'icons', `/foundations`)).props,
       config: getClientRuntimeConfig(),
-      assets: getTokens().assets,
+      assets: buildTimeAssets(),
     },
   };
 };
@@ -66,11 +69,12 @@ const IconsPage = ({ content, menu, metadata, current, config, assets }: AssetDo
   const [search, setSearch] = React.useState('');
   const inputRef = React.useRef<HTMLInputElement>(null);
 
+  // Workspace/static hydrates from build-time props; registry hydrates from the docs read API.
+  const allIcons = useCollectionAssets('icons', assets?.icons);
   const icons = React.useMemo(() => {
-    if (!assets || !Array.isArray(assets.icons)) return [];
-    if (!search) return assets.icons;
-    return assets.icons.filter(icon => icon.index.includes(search));
-  }, [assets, search]);
+    if (!search) return allIcons;
+    return allIcons.filter((icon) => icon.index.includes(search));
+  }, [allIcons, search]);
 
   const filterList = React.useCallback<React.ChangeEventHandler<HTMLInputElement>>((event) => {
     setSearch(event.currentTarget.value.toLowerCase().replace(/[\W_]+/g, ' '));

package/src/app/pages/foundations/index.tsx

@@ -20,7 +20,7 @@ import { DocumentationProps, fetchDocPageMarkdown, getClientRuntimeConfig } from
 export const getStaticProps: GetStaticProps = async () => {
   return {
     props: {
-      ...fetchDocPageMarkdown('docs/', 'foundations', `/foundations`).props,
+      ...(await fetchDocPageMarkdown('docs/', 'foundations', `/foundations`)).props,
       config: getClientRuntimeConfig(),
     },
   };

package/src/app/pages/foundations/logo.tsx

@@ -1,7 +1,8 @@
 import type { GetStaticProps } from 'next';
 import Link from 'next/link';
 
-import { AssetDocumentationProps, fetchDocPageMarkdown, getClientRuntimeConfig, getTokens } from '../../components/util';
+import { AssetDocumentationProps, buildTimeAssets, fetchDocPageMarkdown, getClientRuntimeConfig } from '../../components/util';
+import { useCollectionAssets } from '../../components/util/useCollectionAssets';
 
 import { Download } from 'lucide-react';
 import ReactMarkdown from 'react-markdown';
@@ -39,14 +40,16 @@ import { buttonVariants } from '../../components/ui/button';
 export const getStaticProps: GetStaticProps = async () => {
   return {
     props: {
-      ...fetchDocPageMarkdown('docs/foundations/', 'logo', `/foundations`).props,
+      ...(await fetchDocPageMarkdown('docs/foundations/', 'logo', `/foundations`)).props,
       config: getClientRuntimeConfig(),
-      assets: getTokens().assets,
+      assets: buildTimeAssets(),
     },
   };
 };
 
 const LogoPage = ({ content, menu, metadata, current, config, assets }: AssetDocumentationProps) => {
+  // Workspace/static uses build-time props; registry hydrates from the docs read API.
+  const logos = useCollectionAssets('logos', assets?.logos);
   return (
     <Layout config={config} menu={menu} metadata={metadata} current={current}>
       <div className="flex flex-col gap-2 pb-7">
@@ -67,7 +70,7 @@ const LogoPage = ({ content, menu, metadata, current, config, assets }: AssetDoc
         <p className="mb-8">There is one main {config?.app?.client} logo that supports two variations.</p>
       </div>
       <div className="mb-8 grid grid-cols-2 gap-6">
-        {assets?.logos?.map((logo) => (
+        {logos.map((logo) => (
           <DisplayLogo logo={logo} content={config?.app?.client} key={logo.path} />
         ))}
       </div>

package/src/app/pages/foundations/typography.tsx

@@ -10,7 +10,8 @@ import Layout from '../../components/Layout/Main';
 import { MarkdownComponents, remarkCodeMeta } from '../../components/Markdown/MarkdownComponents';
 import AnchorNav, { anchorSlugify } from '../../components/Navigation/AnchorNav';
 import HeadersType from '../../components/Typography/Headers';
-import { fetchFoundationDocPageMarkdown, FoundationDocumentationProps, getClientRuntimeConfig, getTokens } from '../../components/util';
+import { fetchFoundationDocPageMarkdown, FoundationDocumentationProps, getClientRuntimeConfig, getTokens, buildTimeFoundationDesign } from '../../components/util';
+import { useFoundationTokens } from '../../components/util/useFoundationTokens';
 
 export interface typographyTypes {
   [key: string]: any;
@@ -27,9 +28,9 @@ export interface typographyTypes {
 export const getStaticProps: next.GetStaticProps = async () => {
   return {
     props: {
-      ...fetchFoundationDocPageMarkdown('docs/foundations/', 'typography', `/foundations`).props,
+      ...(await fetchFoundationDocPageMarkdown('docs/foundations/', 'typography', `/foundations`)).props,
       config: getClientRuntimeConfig(),
-      design: getTokens().localStyles,
+      design: buildTimeFoundationDesign(),
     },
   };
 };
@@ -39,13 +40,22 @@ const Typography = ({
   menu,
   metadata,
   current,
-  scss,
-  css,
-  styleDictionary,
-  types,
+  scss: scssProp,
+  css: cssProp,
+  styleDictionary: styleDictionaryProp,
+  types: typesProp,
   config,
-  design,
+  design: designProp,
 }: FoundationDocumentationProps) => {
+  // In registry mode the build-time token data/downloads are empty; hydrate from the docs read API.
+  const { design, css, scss, styleDictionary, types } = useFoundationTokens('typography', {
+    design: designProp,
+    css: cssProp,
+    scss: scssProp,
+    styleDictionary: styleDictionaryProp,
+    types: typesProp,
+  });
+
   const typography = design.typography.slice().sort((a, b) => {
     const l = (config?.app?.type_sort ?? []).indexOf(a.name) >>> 0;
     const r = (config?.app?.type_sort ?? []).indexOf(b.name) >>> 0;
@@ -57,7 +67,7 @@ const Typography = ({
       ...result,
       [current.values.fontFamily]: result[current.values.fontFamily]
         ? // sorts and returns unique font weights
-          sortedUniq([...result[current.values.fontFamily], current.values.fontWeight].sort((a, b) => a - b))
+        sortedUniq([...result[current.values.fontFamily], current.values.fontWeight].sort((a, b) => a - b))
         : [current.values.fontWeight],
     };
   }, {} as FontFamily);

package/src/app/pages/index.tsx

@@ -23,7 +23,7 @@ import { DocumentationProps, fetchDocPageMarkdown, getClientRuntimeConfig } from
 export const getStaticProps: GetStaticProps = async () => {
   return {
     props: {
-      ...fetchDocPageMarkdown('docs/', 'index', `/`).props,
+      ...(await fetchDocPageMarkdown('docs/', 'index', `/`)).props,
       config: getClientRuntimeConfig(),
     },
   };

package/src/app/pages/system/component/[component]/index.tsx

@@ -1,4 +1,5 @@
 'use client';
+import { buildArtifactUrl } from '@handoff/artifacts/url';
 import { OptionalPreviewRender } from '@handoff/transformers/preview/types';
 import { PreviewObject } from '@handoff/types/preview';
 import { evaluateFilter, type Filter } from '@handoff/utils/filter';
@@ -8,6 +9,7 @@ import ReactMarkdown from 'react-markdown';
 import rehypeRaw from 'rehype-raw';
 import remarkGfm from 'remark-gfm';
 import { ComponentPreview } from '../../../../components/Component/Preview';
+import { RegistryActions } from '../../../../components/Component/RegistryActions';
 import { HotReloadProvider } from '../../../../components/context/HotReloadProvider';
 import { PreviewContextProvider } from '../../../../components/context/PreviewContext';
 import Layout from '../../../../components/Layout/Main';
@@ -18,15 +20,21 @@ import HeadersType from '../../../../components/Typography/Headers';
 import { Button } from '../../../../components/ui/button';
 import { Drawer, DrawerContent, DrawerHeader, DrawerTitle, DrawerTrigger } from '../../../../components/ui/drawer';
 import { JsonTreeView } from '../../../../components/ui/json-tree-view';
-import { fetchComponents, fetchDocPageMetadataAndContent, getClientRuntimeConfig, getCurrentSection, IParams, staticBuildMenu } from '../../../../components/util';
+import { fetchComponents, fetchDocPageMetadataAndContent, getClientRuntimeConfig, getNavProps, IParams, isRegistryRuntime } from '../../../../components/util';
 
 /**
  * Render all index pages
  * @returns
  */
 export async function getStaticPaths() {
+  // Registry content is mutable at runtime and may be empty/unreachable at build time, so resolve
+  // component pages on demand against the live DB instead of freezing the path list to the build
+  // snapshot. The static-export target stays fully prerendered (`fallback: false`).
+  if (isRegistryRuntime()) {
+    return { paths: [], fallback: 'blocking' as const };
+  }
   return {
-    paths: fetchComponents()?.map((exportable) => ({ params: { component: exportable.id } })) ?? [],
+    paths: (await fetchComponents()).map((exportable) => ({ params: { component: exportable.id } })),
     fallback: false, // can also be true or 'blocking'
   };
 }
@@ -72,10 +80,15 @@ export const getStaticProps = async (context) => {
 
   // const componentObject = getTokens().components[reduceSlugToString(component)] ?? null;
   // const isFigmaComponent = false;
-  const components = fetchComponents()!;
-  const menu = staticBuildMenu();
-  const config = getClientRuntimeConfig();
+  const components = await fetchComponents();
   const componentData = components.find((c) => c.id === component);
+  // Under `fallback: 'blocking'` this runs on demand for arbitrary ids; surface a real 404 for ids
+  // that do not exist in the active mode instead of dereferencing an undefined record below.
+  if (!componentData) {
+    return { notFound: true };
+  }
+  const navProps = await getNavProps('/system');
+  const config = getClientRuntimeConfig();
   const docs = fetchDocPageMetadataAndContent('docs/system/', component as string);
   const componentHotReloadIsAvailable = process.env.NODE_ENV === 'development';
   const sameGroupComponents = components.filter((c) => c.group === componentData?.group);
@@ -83,7 +96,7 @@ export const getStaticProps = async (context) => {
   const previousComponent = sameGroupComponents[groupIndex - 1] ?? null;
   const nextComponent = sameGroupComponents[groupIndex + 1] ?? null;
 
-  const fallbackTitle = componentData.name || startCase(component as string);
+  const fallbackTitle = componentData.title || startCase(component as string);
   const fallbackMetaTitle = `${fallbackTitle}${config?.app?.client ? ` | ${config.app.client} Design System` : ''}`;
 
   return {
@@ -91,12 +104,11 @@ export const getStaticProps = async (context) => {
       id: component,
       // isFigmaComponent: true,
       previews: { components: {} },
-      menu,
+      ...navProps,
       config,
-      current: getCurrentSection(menu, '/system') ?? [],
       metadata: {
         ...componentData,
-        title: componentData.name || docs.metadata.title || startCase(component as string),
+        title: componentData.title || docs.metadata.title || startCase(component as string),
         description: componentData.description,
         metaTitle: docs.metadata.metaTitle || fallbackMetaTitle,
         metaDescription: docs.metadata.metaDescription || componentData.description,
@@ -117,28 +129,46 @@ const GenericComponentPage = ({ menu, metadata, current, id, config, componentHo
   const [component, setComponent] = useState<PreviewObject>(undefined);
   const ref = React.useRef<HTMLDivElement>(null);
   const [componentPreviews, setComponentPreviews] = useState<PreviewObject | [string, PreviewObject][]>();
+  const [previewsUnavailable, setPreviewsUnavailable] = useState(false);
 
   const appBasePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
   const normalizedBasePath = appBasePath ? `/${appBasePath.replace(/^\/+|\/+$/g, '')}` : '';
   const componentRoute = (componentId: string) => `${normalizedBasePath}/system/component/${componentId}`;
 
-  const fetchComponents = async () => {
-    const data = await fetch(`${normalizedBasePath}/api/component/${id}.json`).then((res) => res.json());
-    setComponent(data as PreviewObject);
+  const componentDataUrl = buildArtifactUrl(`component/${id}.json`, appBasePath);
+
+  const fetchComponents = async (signal: AbortSignal) => {
+    try {
+      const res = await fetch(componentDataUrl, { signal });
+      if (!res.ok) {
+        setPreviewsUnavailable(true);
+        setComponent(undefined);
+        return;
+      }
+      const data = await res.json();
+      setComponent(data as PreviewObject);
+    } catch (err) {
+      // A superseded fetch (the user navigated to another component before this one resolved) is
+      // aborted on effect cleanup; ignore it so a slow response can't overwrite the current one.
+      if ((err as Error)?.name !== 'AbortError') throw err;
+    }
   };
 
   const previousLink = previousComponent ? {
     href: previousComponent ? componentRoute(previousComponent.id) : null,
-    title: previousComponent ? previousComponent.name : null,
+    title: previousComponent ? previousComponent.title : null,
   } : null;
   const nextLink = nextComponent ? {
     href: componentRoute(nextComponent.id),
-    title: nextComponent.name,
+    title: nextComponent.title,
   } : null;
 
   useEffect(() => {
+    const controller = new AbortController();
     setComponent(undefined);
-    fetchComponents();
+    setPreviewsUnavailable(false);
+    fetchComponents(controller.signal);
+    return () => controller.abort();
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [id]);
 
@@ -163,8 +193,47 @@ const GenericComponentPage = ({ menu, metadata, current, id, config, componentHo
     }
   }, [component, id]);
 
-  if (!component) return <p>Loading...</p>;
-  const apiUrl = (window.location.origin && window.location.origin) + `${normalizedBasePath}/api/component/${id}.json`;
+  if (previewsUnavailable) {
+    return (
+      <Layout config={config} menu={menu} current={current} metadata={metadata}>
+        <div className="flex flex-col gap-3 pb-14">
+          <small className="text-sm font-medium text-sky-600 dark:text-gray-300">Components</small>
+          <HeadersType.H1>{metadata.title}</HeadersType.H1>
+          {metadata.description && (
+            <div className="prose max-w-[800px] text-xl font-light leading-relaxed text-gray-600 dark:text-gray-300">
+              <ReactMarkdown components={MarkdownComponents} remarkPlugins={[remarkGfm, remarkCodeMeta]} rehypePlugins={[rehypeRaw]}>
+                {metadata.description}
+              </ReactMarkdown>
+            </div>
+          )}
+          <div className="mt-4 max-w-[800px] rounded-md border border-amber-200 bg-amber-50 p-4 text-sm text-amber-800 dark:border-amber-900/50 dark:bg-amber-950/40 dark:text-amber-200">
+            This component has no published artifacts yet, so previews and code samples are unavailable. Publish it to the
+            registry to populate its documentation.
+          </div>
+          <hr className="mt-8" />
+          <PrevNextNav previous={previousLink} next={nextLink} />
+        </div>
+      </Layout>
+    );
+  }
+  if (!component) {
+    return (
+      <Layout config={config} menu={menu} current={current} metadata={metadata}>
+        <div className="flex flex-col gap-3 pb-14" aria-busy="true" aria-live="polite">
+          <small className="text-sm font-medium text-sky-600 dark:text-gray-300">Components</small>
+          <HeadersType.H1>{metadata.title}</HeadersType.H1>
+          {metadata.description && (
+            <div className="prose max-w-[800px] text-xl font-light leading-relaxed text-gray-600 dark:text-gray-300">
+              <ReactMarkdown components={MarkdownComponents} remarkPlugins={[remarkGfm, remarkCodeMeta]} rehypePlugins={[rehypeRaw]}>
+                {metadata.description}
+              </ReactMarkdown>
+            </div>
+          )}
+        </div>
+      </Layout>
+    );
+  }
+  const apiUrl = (window.location.origin && window.location.origin) + componentDataUrl;
   return (
     <Layout config={config} menu={menu} current={current} metadata={metadata}>
       <div className="flex flex-col gap-3 pb-14">
@@ -178,6 +247,7 @@ const GenericComponentPage = ({ menu, metadata, current, id, config, componentHo
             </ReactMarkdown>
           </div>
           <div className="flex flex-row gap-3">
+            <RegistryActions mode={config.runtime.mode} connected={config.runtime.connected} entityType="component" id={id} />
             {component.figma && (
               <Button asChild variant={'outline'} size={'sm'} className="font-normal [&_svg]:size-3!">
                 <a href={component.figma} target="_blank">

package/src/app/pages/system/index.tsx

@@ -36,7 +36,7 @@ export const getStaticProps: GetStaticProps = async () => {
   return {
     props: {
       config,
-      ...fetchDocPageMarkdown('docs/', 'system', `/system`).props,
+      ...(await fetchDocPageMarkdown('docs/', 'system', `/system`)).props,
     } as ComponentPageDocumentationProps,
   };
 };
@@ -49,13 +49,22 @@ const ComponentsPage = ({ content, menu, metadata, current, config }: ComponentP
   // Fetch components from api
   const [components, setComponents] = useState<PreviewObject[]>(undefined);
   const fetchComponents = async () => {
-    const data = await fetch(`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/components.json`).then((res) => res.json());
+    const data = await fetch(`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/docs/components.json`).then((res) => res.json());
     setComponents(data as PreviewObject[]);
   };
   useEffect(() => {
     fetchComponents();
   }, []);
-  if (!components) return <p>Loading...</p>;
+  if (!components) {
+    return (
+      <Layout config={config} menu={menu} current={current} metadata={metadata}>
+        <div className="flex flex-col gap-2 pb-7" aria-busy="true" aria-live="polite">
+          <HeadersType.H1>{metadata.title}</HeadersType.H1>
+          <p className="mt-3 text-lg leading-relaxed text-gray-600 dark:text-gray-300">{metadata.description}</p>
+        </div>
+      </Layout>
+    );
+  }
 
   if ((components ?? []).length === 0) {
     return (
@@ -90,7 +99,7 @@ const ComponentsPage = ({ content, menu, metadata, current, config }: ComponentP
     );
   }
 
-  const apiUrl = (window.location.origin && window.location.origin) + `${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/components.json`;
+  const apiUrl = (window.location.origin && window.location.origin) + `${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/docs/components.json`;
   return (
     <Layout config={config} menu={menu} current={current} metadata={metadata}>
       <div className="flex flex-col gap-2 pb-7">

package/src/app/pages/system/pattern/[pattern]/index.tsx

@@ -1,4 +1,5 @@
 'use client';
+import { buildArtifactUrl } from '@handoff/artifacts/url';
 import { PatternListObject } from '@handoff/transformers/preview/types';
 import { startCase } from 'lodash';
 import React, { useCallback, useEffect, useState } from 'react';
@@ -7,6 +8,7 @@ import rehypeRaw from 'rehype-raw';
 import Layout from '../../../../components/Layout/Main';
 import { MarkdownComponents } from '../../../../components/Markdown/MarkdownComponents';
 import PrevNextNav from '../../../../components/Navigation/PrevNextNav';
+import NotFound from '../../../../components/NotFound';
 import HeadersType from '../../../../components/Typography/Headers';
 import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '../../../../components/ui/accordion';
 import { Badge } from '../../../../components/ui/badge';
@@ -15,9 +17,9 @@ import {
   DocumentationProps,
   fetchPatterns,
   getClientRuntimeConfig,
-  getCurrentSection,
+  getNavProps,
   IParams,
-  staticBuildMenu,
+  isRegistryRuntime,
 } from '../../../../components/util';
 
 type PatternNavItem = { id: string; title: string; description: string; group: string };
@@ -89,18 +91,29 @@ const getArgSummary = (args?: Record<string, unknown>) => {
 };
 
 export async function getStaticPaths() {
+  // Registry content is mutable at runtime and may be empty/unreachable at build time, so resolve
+  // pattern pages on demand against the live DB instead of freezing the path list to the build
+  // snapshot. The static-export target stays fully prerendered (`fallback: false`).
+  if (isRegistryRuntime()) {
+    return { paths: [], fallback: 'blocking' as const };
+  }
   return {
-    paths: fetchPatterns()?.map((p) => ({ params: { pattern: p.id } })) ?? [],
+    paths: (await fetchPatterns()).map((p) => ({ params: { pattern: p.id } })),
     fallback: false,
   };
 }
 
 export const getStaticProps = async (context: { params: IParams }) => {
   const { pattern: patternId } = context.params;
-  const patterns = fetchPatterns() ?? [];
-  const menu = staticBuildMenu();
-  const config = getClientRuntimeConfig();
+  const patterns = await fetchPatterns();
   const patternData = patterns.find((p) => p.id === patternId);
+  // Under `fallback: 'blocking'` this runs on demand for arbitrary ids; surface a real 404 for ids
+  // that do not exist in the active mode.
+  if (!patternData) {
+    return { notFound: true };
+  }
+  const navProps = await getNavProps('/system');
+  const config = getClientRuntimeConfig();
 
   const sameGroupPatterns = patterns.filter((p) => p.group === patternData?.group);
   const groupIndex = sameGroupPatterns.findIndex((p) => p.id === patternId);
@@ -112,9 +125,8 @@ export const getStaticProps = async (context: { params: IParams }) => {
   return {
     props: {
       id: patternId,
-      menu,
+      ...navProps,
       config,
-      current: getCurrentSection(menu, '/system') ?? [],
       metadata: {
         title: fallbackTitle,
         description: patternData?.description || '',
@@ -130,6 +142,7 @@ export const getStaticProps = async (context: { params: IParams }) => {
 const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nextPattern }: PatternPageProps) => {
   const [pattern, setPattern] = useState<PatternListObject | undefined>(undefined);
   const [fetchError, setFetchError] = useState<string | undefined>(undefined);
+  const [patternNotFound, setPatternNotFound] = useState(false);
   const [iframeHeight, setIframeHeight] = useState('400px');
   const iframeRef = React.useRef<HTMLIFrameElement>(null);
 
@@ -145,13 +158,20 @@ const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nex
     const controller = new AbortController();
     setPattern(undefined);
     setFetchError(undefined);
+    setPatternNotFound(false);
 
-    fetch(`${normalizedBasePath}/api/pattern/${id}.json`, { signal: controller.signal })
+    fetch(buildArtifactUrl(`pattern/${id}.json`, appBasePath), { signal: controller.signal })
       .then((res) => {
+        if (res.status === 404) {
+          setPatternNotFound(true);
+          return null;
+        }
         if (!res.ok) throw new Error(`Failed to load pattern: ${res.status} ${res.statusText}`);
         return res.json();
       })
-      .then((data) => setPattern(data as PatternListObject))
+      .then((data) => {
+        if (data) setPattern(data as PatternListObject);
+      })
       .catch((err) => {
         if (err.name !== 'AbortError') {
           setFetchError(err instanceof Error ? err.message : 'Failed to load pattern data.');
@@ -159,7 +179,7 @@ const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nex
       });
 
     return () => controller.abort();
-  }, [id, normalizedBasePath]);
+  }, [id, appBasePath]);
 
   const onIframeLoad = useCallback(() => {
     if (iframeRef.current?.contentWindow?.document?.body) {
@@ -167,8 +187,44 @@ const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nex
     }
   }, []);
 
-  if (fetchError) return <p className="p-4 text-red-500">{fetchError}</p>;
-  if (!pattern) return <p>Loading...</p>;
+  if (patternNotFound) {
+    return (
+      <Layout config={config} menu={menu} current={current} metadata={{ ...metadata, title: '404 - Page Not Found', metaTitle: '404 - Page Not Found' }}>
+        <div className="flex min-h-[60vh] flex-col items-center justify-center">
+          <NotFound />
+        </div>
+      </Layout>
+    );
+  }
+
+  if (fetchError) {
+    return (
+      <Layout config={config} menu={menu} current={current} metadata={metadata}>
+        <div className="flex min-h-[60vh] flex-col items-center justify-center gap-2">
+          <p className="text-lg font-semibold text-gray-700 dark:text-gray-300">Something went wrong</p>
+          <p className="text-sm text-red-500">{fetchError}</p>
+        </div>
+      </Layout>
+    );
+  }
+
+  if (!pattern) {
+    return (
+      <Layout config={config} menu={menu} current={current} metadata={metadata}>
+        <div className="flex flex-col gap-3 pb-14" aria-busy="true" aria-live="polite">
+          <small className="text-sm font-medium text-sky-600 dark:text-gray-300">Patterns</small>
+          <HeadersType.H1>{metadata.title}</HeadersType.H1>
+          {metadata.description && (
+            <div className="prose max-w-[800px] text-xl font-light leading-relaxed text-gray-600 dark:text-gray-300">
+              <ReactMarkdown components={MarkdownComponents} rehypePlugins={[rehypeRaw]}>
+                {metadata.description}
+              </ReactMarkdown>
+            </div>
+          )}
+        </div>
+      </Layout>
+    );
+  }
 
   return (
     <Layout config={config} menu={menu} current={current} metadata={metadata}>
@@ -217,7 +273,7 @@ const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nex
                   display: 'block',
                   border: 'none',
                 }}
-                src={`${normalizedBasePath}/api/pattern/${pattern.url}`}
+                src={buildArtifactUrl(`pattern/${pattern.url}`, appBasePath)}
               />
             ) : (
               <div className="flex items-center justify-center p-8 text-sm text-gray-500">No preview available for this pattern.</div>