handoff-app 1.2.2-7 → 2.0.0-1

package/src/app/components/util/index.ts

@@ -4,15 +4,21 @@ import { ComponentDocumentationOptions, PreviewObject } from '@handoff/types/pre
 import * as fs from 'fs-extra';
 import matter from 'gray-matter';
 import { Types as CoreTypes } from 'handoff-core';
-import { groupBy, startCase, uniq } from 'lodash';
 import path from 'path';
 import { ParsedUrlQuery } from 'querystring';
+import { KNOWN_PATHS } from '@handoff/utils/menu-shell';
+import { getRegistryNavData, getWorkspaceNavData, type NavData, type NavTokenSet, type SectionLink } from '@handoff/nav';
+import { resolveDocsBackend } from '../../lib/docs-api/backend';
+import { tokenFormatStrings } from '../../lib/docs-api/token-detail';
+// Build-time-baked navigation shell. Imported statically (same as `pages/api/docs/nav.json.ts`) so
+// it is bundled into the route chunk and readable at request time in the Vercel registry lambda,
+// where the markdown it is derived from is not traceable. See src/utils/menu-shell.ts.
+import navShell from '@/generated/nav-shell.json';
 // Get the parsed url string type
 export interface IParams extends ParsedUrlQuery {
   slug: string | string[];
 }
 
-
 // Type for the metadata from frontmatter
 export interface Metadata {
   title: string;
@@ -21,23 +27,7 @@ export interface Metadata {
   metaDescription: string;
 }
 
-// Define what a section link looks like
-export interface SectionLink {
-  title: string;
-  weight: number;
-  external?: string | boolean;
-  path: string;
-  subSections: {
-    title: string;
-    path: string;
-    image: string;
-    menu?: {
-      title: string;
-      path: string;
-      image: string;
-    }[];
-  }[];
-}
+export type { SectionLink } from '@handoff/nav';
 // Documentation Page Properties
 export interface DocumentationProps {
   metadata: Metadata;
@@ -45,6 +35,8 @@ export interface DocumentationProps {
   options?: ComponentDocumentationOptions;
   menu: SectionLink[];
   current: SectionLink;
+  navData: NavData;
+  currentSectionId: string;
   config: ClientConfig;
 }
 
@@ -76,30 +68,10 @@ export interface FoundationDocumentationProps extends DocumentationWithTokensPro
   design: CoreTypes.IDocumentationObject['localStyles'];
 }
 /**
- * List the default paths
+ * Default paths that have dedicated route files (excluded from auto-scanned submenus). Single source
+ * of truth lives in `@handoff/utils/menu-shell` (shared with the build-time shell builder).
  */
-export const knownPaths = [
-  'assets',
-  'assets/fonts',
-  'assets/icons',
-  'assets/logos',
-  'foundations',
-  'foundations/colors',
-  'foundations/icons',  
-  'foundations/effects',
-  'foundations/logos',
-  'foundations/logo',
-  'foundations/typography',
-  'system',
-  'system/component',
-  'system/tokens',
-  'system/tokens/foundations',
-  'system/tokens/foundations/colors',
-  'system/tokens/foundations/effects',
-  'system/tokens/foundations/typography',
-  'system/tokens/components',
-  'system/pattern',
-];
+export const knownPaths = KNOWN_PATHS;
 
 /**
  * Get the plural name of a component
@@ -146,12 +118,12 @@ const collectMarkdownPaths = (rootDir: string, relativeParts: string[] = []): st
  * Build catch-all static paths for all markdown pages at any depth.
  * Excludes paths in knownPaths (those have dedicated route files).
  */
-export const buildCatchAllStaticPaths = () => {
+export const buildCatchAllStaticPaths = (includeWorkspacePages = true) => {
   const docRoot = path.resolve(process.env.HANDOFF_MODULE_PATH ?? '', 'config/docs');
   const pageRoot = path.resolve(process.env.HANDOFF_WORKING_PATH ?? '', 'pages');
 
   const docPaths = collectMarkdownPaths(docRoot);
-  const pagePaths = collectMarkdownPaths(pageRoot);
+  const pagePaths = includeWorkspacePages ? collectMarkdownPaths(pageRoot) : [];
 
   const seen = new Set<string>();
   const allPaths: string[][] = [];
@@ -165,323 +137,24 @@ export const buildCatchAllStaticPaths = () => {
     }
   }
 
-  return allPaths
-    .filter((segments) => knownPaths.indexOf(segments.join('/')) < 0)
-    .map((segments) => ({ params: { slug: segments } }));
-};
-
-/**
- * Recursively build menu entries from .md files in a directory.
- * Returns sub-section items with nested menu items for subdirectories.
- */
-const buildMenuFromDirectory = (dirPath: string, urlPrefix: string): any[] => {
-  if (!fs.existsSync(dirPath)) return [];
-  const entries = fs.readdirSync(dirPath);
-  const items: any[] = [];
-
-  for (const entry of entries) {
-    const fullPath = path.join(dirPath, entry);
-    if (fs.lstatSync(fullPath).isDirectory()) {
-      const nestedItems = buildMenuFromDirectory(fullPath, `${urlPrefix}/${entry}`);
-      if (nestedItems.length > 0) {
-        items.push({
-          title: startCase(entry),
-          path: `${urlPrefix}/${entry}`,
-          menu: nestedItems,
-        });
-      }
-    } else if (entry.endsWith('.md') && entry !== 'index.md') {
-      const slug = entry.replace('.md', '');
-      const fullSlugPath = `${urlPrefix}/${slug}`.replace(/^\/+/, '');
-      if (knownPaths.indexOf(fullSlugPath) >= 0) continue;
-
-      const contents = fs.readFileSync(fullPath, 'utf-8');
-      const { data: metadata } = matter(contents);
-      if (metadata.enabled === false) continue;
-
-      items.push({
-        title: metadata.menuTitle ?? metadata.title ?? startCase(slug),
-        path: `/${fullSlugPath}`,
-        weight: metadata.weight ?? 0,
-      });
-    }
-  }
-
-  return items.sort((a, b) => (a.weight ?? 0) - (b.weight ?? 0));
+  return allPaths.filter((segments) => knownPaths.indexOf(segments.join('/')) < 0).map((segments) => ({ params: { slug: segments } }));
 };
 
 /**
- * Build the static menu for rendering pages
- * @returns SectionLink[]
+ * Fetch patterns from the mode-aware docs read API.
+ *
+ * Resolves through {@link resolveDocsBackend}, so the active `runtime.mode` decides the source:
+ * generated workspace artifacts in workspace mode, the registry database in registry mode.
  */
-export const staticBuildMenu = () => {
-  const docRoot = path.join(process.env.HANDOFF_MODULE_PATH ?? '', 'config/docs');
-  if (!fs.existsSync(docRoot)) {
-    return [];
-  }
-  const files = fs.readdirSync(docRoot);
-  let list = files;
-  const workingPages = path.resolve(process.env.HANDOFF_WORKING_PATH ?? '', 'pages');
-  let pages: string[] = [];
-  if (fs.existsSync(workingPages)) {
-    pages = fs.readdirSync(workingPages);
-    list = list.concat(pages);
-  }
-  const sections: SectionLink[] = [];
-  const custom = uniq(list)
-    .map((fileName: string) => {
-      let search = '';
-      if (pages.includes(fileName)) {
-        search = path.resolve(workingPages, fileName);
-      } else {
-        search = path.resolve(docRoot, fileName);
-      }
-      if (
-        !fs.lstatSync(search).isDirectory() &&
-        search !== path.resolve(docRoot, 'index.md') &&
-        search !== path.resolve(workingPages, 'index.md') &&
-        fileName.endsWith('md')
-      ) {
-        const contents = fs.readFileSync(search, 'utf-8');
-        const { data: metadata } = matter(contents);
-        if (metadata.enabled === false) {
-          return undefined;
-        }
-
-        const filepath = `/${fileName.replace('.md', '')}`;
-        let subSections = [];
-
-        if (metadata.menu) {
-          subSections = Object.keys(metadata.menu)
-            .map((key) => {
-              const sub = metadata.menu[key];
-              if (sub.components) {
-                return {
-                  title: sub.title,
-                  menu: staticBuildComponentMenu(sub.components),
-                };
-              }
-              if (sub.tokens) {
-                return {
-                  title: 'Tokens',
-                  menu: staticBuildTokensMenu(),
-                };
-              }
-              if (sub.patterns) {
-                const patternMenu = staticBuildPatternMenu();
-                if (patternMenu.length > 0) {
-                  return {
-                    title: sub.title || 'Patterns',
-                    menu: patternMenu,
-                  };
-                }
-                return undefined;
-              }
-              if (sub.enabled !== false) {
-                return sub;
-              }
-            })
-            .filter(filterOutUndefined);
-        } else {
-          // Only auto-scan directories when no frontmatter menu is defined
-          const dirName = fileName.replace('.md', '');
-          const docDir = path.resolve(docRoot, dirName);
-          const pagesDir = path.resolve(workingPages, dirName);
-          const nestedFromDocs = buildMenuFromDirectory(docDir, `/${dirName}`);
-          const nestedFromPages = buildMenuFromDirectory(pagesDir, `/${dirName}`);
-
-          const seenPaths = new Set<string>();
-          for (const item of [...nestedFromPages, ...nestedFromDocs]) {
-            if (item.path && !seenPaths.has(item.path)) {
-              seenPaths.add(item.path);
-              subSections.push(item);
-            }
-          }
-        }
-
-        let external: string | boolean = false;
-        if (
-          typeof metadata.external === 'string' &&
-          (metadata.external.startsWith('http://') || metadata.external.startsWith('https://') || metadata.external.startsWith('/'))
-        ) {
-          external = metadata.external;
-        }
-
-        return {
-          title: metadata.menuTitle ?? metadata.title,
-          external,
-          weight: metadata.weight ?? 0,
-          path: `${filepath}`,
-          subSections,
-        };
-      }
-    })
-    .filter(filterOutUndefined);
-  return sections.concat(custom).sort((a: SectionLink, b: SectionLink) => a.weight - b.weight);
-};
-
-const buildBasePath = () => {
-  if (!process.env.HANDOFF_APP_BASE_PATH) {
-    return '';
-  }
-  return (process.env.HANDOFF_APP_BASE_PATH ?? '').replace(/^\/+|\/+$/g, '') + '/';
-};
-
-const staticBuildComponentMenu = (type?: boolean | string) => {
-  const basePath = buildBasePath();
-  let menu = [];
-  let components = fetchComponents({ includeTokens: false });
-  if (typeof type === 'string' && type !== '') {
-    components = components.filter((component) => component.type == type);
-  }
-  // Build the submenu of exportables (components)
-  const groupedComponents = groupBy(components, (e) => e.group ?? '');
-  Object.keys(groupedComponents).forEach((group) => {
-    const menuGroup = { title: group || 'Uncategorized', menu: [] };
-    groupedComponents[group].forEach((component) => {
-      const docs = fetchDocPageMetadataAndContent('docs/system/', component.id);
-      let title = startCase(component.id);
-      if (docs.metadata.title) {
-        title = docs.metadata.title;
-      }
-      if (component.name) {
-        title = component.name;
-      }
-      menuGroup.menu.push({ path: `${basePath}system/component/${component.id}`, title });
-    });
-    // sort the menu group by name alphabetical
-    menuGroup.menu = menuGroup.menu.sort((a, b) => a.title.localeCompare(b.title));
-    menu.push(menuGroup);
-  });
-  // sort the menu by name alphabetical
-  menu = menu.sort((a, b) => a.title.localeCompare(b.title));
-  return menu;
-};
-
-const staticBuildTokensMenu = () => {
-  const basePath = buildBasePath();
-
-  const menu = [
-    {
-      title: `Foundations`,
-      path: `${basePath}system/tokens/foundations`,
-      menu: [
-        {
-          title: `Colors`,
-          path: `${basePath}system/tokens/foundations/colors`,
-        },
-        {
-          title: `Effects`,
-          path: `${basePath}system/tokens/foundations/effects`,
-        },
-        {
-          title: `Typography`,
-          path: `${basePath}system/tokens/foundations/typography`,
-        },
-      ],
-    },
-  ];
-
-  const componentMenuItems = [];
-  const components = fetchComponents({ includeApi: false });
-  // Build the submenu of exportables (components)
-  const groupedComponents = groupBy(components, (e) => e.group ?? '');
-  Object.keys(groupedComponents).forEach((group) => {
-    groupedComponents[group].forEach((component) => {
-      const docs = fetchDocPageMetadataAndContent('docs/system/', component.id);
-      let title = startCase(component.id);
-      if (docs.metadata.title) {
-        title = docs.metadata.title;
-      }
-      if (component.name) {
-        title = component.name;
-      }
-      componentMenuItems.push({ path: `${basePath}system/tokens/components/${component.id}`, title });
-    });
-  });
-
-  if (componentMenuItems.length > 0) {
-    menu.push({
-      title: `Components`,
-      path: `${basePath}system/tokens/components`,
-      menu: componentMenuItems,
-    });
-  }
-
-  return menu;
-};
-
-const staticBuildTokenMenu = () => {
-    const basePath = buildBasePath();
-
-  let subSections = {
-    title: 'Tokens',
-    path: `${basePath}system/tokens`,
-    menu: [],
-  };
-  const tokens = getTokens();
-
-  return subSections;
-};
-
-/**
- * Fetch patterns from the patterns.json API file
- */
-export const fetchPatterns = (): { id: string; title: string; description: string; group: string }[] => {
-  const patternsFilePath = path.resolve(
-    process.env.HANDOFF_MODULE_PATH ?? '',
-    '.handoff',
-    `${process.env.HANDOFF_PROJECT_ID}`,
-    'public',
-    'api',
-    'patterns.json'
-  );
-
-  if (!fs.existsSync(patternsFilePath)) {
-    return [];
-  }
-
+export const fetchPatterns = async (): Promise<PatternListObject[]> => {
   try {
-    const patternList = JSON.parse(
-      fs.readFileSync(patternsFilePath, 'utf-8')
-    ) as PatternListObject[];
-
-    return patternList.map((p) => ({
-      id: p.id,
-      title: p.title || '',
-      description: p.description || '',
-      group: p.group || '',
-    }));
+    const backend = await resolveDocsBackend();
+    return (await backend.listPatterns()) ?? [];
   } catch {
     return [];
   }
 };
 
-const staticBuildPatternMenu = () => {
-  const basePath = buildBasePath();
-  const patterns = fetchPatterns();
-
-  if (patterns.length === 0) return [];
-
-  const grouped = groupBy(patterns, (p) => p.group ?? '');
-  let menu: { title: string; menu: { path: string; title: string }[] }[] = [];
-
-  Object.keys(grouped).forEach((group) => {
-    const menuGroup = { title: group || 'Uncategorized', menu: [] as { path: string; title: string }[] };
-    grouped[group].forEach((pattern) => {
-      menuGroup.menu.push({
-        path: `${basePath}system/pattern/${pattern.id}`,
-        title: pattern.title || startCase(pattern.id),
-      });
-    });
-    menuGroup.menu.sort((a, b) => a.title.localeCompare(b.title));
-    menu.push(menuGroup);
-  });
-
-  menu.sort((a, b) => a.title.localeCompare(b.title));
-  return menu;
-};
-
 /**
  * Filter the menus by the current path
  * @param menu
@@ -491,14 +164,54 @@ const staticBuildPatternMenu = () => {
 export const getCurrentSection = (menu: SectionLink[], path: string): SectionLink | null =>
   menu.filter((section) => section.path === path)[0];
 
+/**
+ * Resolve the render-ready first-paint navigation for every page. Registry initial delivery is
+ * deliberately shell-only; workspace delivery fills the same canonical tree from local records.
+ * The legacy `menu`/`current` aliases remain page-layout props while all navigation consumers read
+ * `navData` through `NavProvider`.
+ */
+export const getNavProps = async (
+  currentSectionId: string
+): Promise<{ navData: NavData; currentSectionId: string; menu: SectionLink[]; current: SectionLink | null }> => {
+  let navData: NavData;
+  if (isRegistryRuntime()) {
+    navData = await getRegistryNavData({
+      shell: navShell as unknown as SectionLink[],
+      load: 'initial',
+      basePath: process.env.HANDOFF_APP_BASE_PATH,
+      fetchRecords: async () => ({ components: [], patterns: [], pages: [], tokenSets: [] }),
+    });
+  } else {
+    const backend = await resolveDocsBackend();
+    navData = await getWorkspaceNavData({
+      docRoot: path.resolve(process.env.HANDOFF_MODULE_PATH ?? '', 'config/docs'),
+      workingPagesDir: path.resolve(process.env.HANDOFF_WORKING_PATH ?? '', 'pages'),
+      basePath: process.env.HANDOFF_APP_BASE_PATH,
+      load: 'initial',
+      loaders: {
+        components: () => backend.listComponents(),
+        patterns: () => backend.listPatterns(),
+        pages: () => backend.listPages(),
+        tokenSets: async () => (await backend.listTokenSets()) as NavTokenSet[],
+      },
+    });
+  }
+  return {
+    navData,
+    currentSectionId,
+    menu: navData.shell,
+    current: getCurrentSection(navData.shell, currentSectionId) ?? null,
+  };
+};
+
 /**
  * Build a static object for rending markdown pages
  * @param path
  * @param slug
  * @returns
  */
-export const fetchDocPageMarkdown = (path: string, slug: string | undefined, id: string, runtimeConfig?: RuntimeConfig) => {
-  const menu = staticBuildMenu();
+export const fetchDocPageMarkdown = async (path: string, slug: string | undefined, id: string, runtimeConfig?: RuntimeConfig) => {
+  const nav = await getNavProps(id);
   const { metadata, content, options } = fetchDocPageMetadataAndContent(path, slug, runtimeConfig);
   // Return props
   return {
@@ -506,8 +219,10 @@ export const fetchDocPageMarkdown = (path: string, slug: string | undefined, id:
       metadata,
       content,
       options,
-      menu,
-      current: getCurrentSection(menu, `${id}`) ?? null,
+      menu: nav.menu,
+      current: nav.current,
+      navData: nav.navData,
+      currentSectionId: nav.currentSectionId,
     },
   };
 };
@@ -519,10 +234,10 @@ export const fetchDocPageMarkdown = (path: string, slug: string | undefined, id:
  * @param id
  * @returns
  */
-export const fetchCompDocPageMarkdown = (path: string, slug: string | undefined, id: string, runtimeConfig?: RuntimeConfig) => {
+export const fetchCompDocPageMarkdown = async (path: string, slug: string | undefined, id: string, runtimeConfig?: RuntimeConfig) => {
   return {
     props: {
-      ...fetchDocPageMarkdown(path, slug, id, runtimeConfig).props,
+      ...(await fetchDocPageMarkdown(path, slug, id, runtimeConfig)).props,
       scss: slug ? fetchTokensString(slug, 'scss') : '',
       css: slug ? fetchTokensString(slug, 'css') : '',
       styleDictionary: slug ? fetchTokensString(slug, 'styleDictionary') : '',
@@ -531,19 +246,68 @@ export const fetchCompDocPageMarkdown = (path: string, slug: string | undefined,
   };
 };
 
-type FetchComponentsOptions = {
+/**
+ * Fetch components from the mode-aware docs read API.
+ *
+ * Resolves through {@link resolveDocsBackend}, so the active `runtime.mode` decides the source:
+ * generated workspace artifacts in workspace mode, the registry database in registry mode. This is
+ * the entity list the navigation, detail, and preview views all share, so they agree on the same
+ * set for the active mode.
+ */
+export const fetchComponents = async (): Promise<ComponentListObject[]> => {
+  try {
+    const backend = await resolveDocsBackend();
+    return (await backend.listComponents()) ?? [];
+  } catch {
+    return [];
+  }
+};
+
+/** A component token set resolved for a docs page: the token object + the four download strings. */
+export interface ComponentTokensResult {
+  component: CoreTypes.IFileComponentObject;
+  css: string;
+  scss: string;
+  styleDictionary: string;
+  types: string;
+}
+
+/**
+ * Fetch a component's token set through the mode-aware docs read API. Resolves through
+ * {@link resolveDocsBackend}, so registry mode reads the DB-backed `component/<id>` set (mutable,
+ * publishable after deploy) while workspace mode reads the generated files. Returns `null` when the
+ * set does not exist.
+ */
+export const fetchComponentTokens = async (componentId: string): Promise<ComponentTokensResult | null> => {
+  try {
+    const backend = await resolveDocsBackend();
+    const detail = await backend.getTokenSetDetail(`component/${componentId}`);
+    if (!detail) {
+      return null;
+    }
+    return { component: detail.record as CoreTypes.IFileComponentObject, ...tokenFormatStrings(detail.artifacts) };
+  } catch {
+    return null;
+  }
+};
+
+type FetchLocalComponentsOptions = {
   includeTokens?: boolean;
   includeApi?: boolean;
 };
 
 /**
- * Fetch exportables id's from the JSON files in the exportables directory
+ * Fetch components from the local, build-time workspace artifacts (`tokens.json` and the generated
+ * `components.json`). This is the legacy, mode-independent local read used **only** by the tokens
+ * views, which are not yet covered by the registry read path (out of scope); it intentionally stays
+ * local so token behavior is preserved exactly until tokens are migrated.
+ *
  * @param options - Configuration object to specify which component sources to include
  * @param options.includeTokens - Include components from tokens.json (default: true)
  * @param options.includeApi - Include components from components.json API (default: true)
- * @returns {string[]} Array of component objects with id, type, group, name, and description
+ * @returns Array of component objects with id, type, group, name, and description
  */
-export const fetchComponents = (options?: FetchComponentsOptions) => {
+export const fetchLocalComponents = (options?: FetchLocalComponentsOptions) => {
   const includeTokens = options?.includeTokens ?? true;
   const includeApi = options?.includeApi ?? true;
 
@@ -619,36 +383,61 @@ let cachedClientConfig: ClientConfigCache | null = null;
 
 const getDefaultClientConfig = (): ClientConfigCache => {
   return {
-    config: {} as ClientConfig,
+    config: { runtime: { mode: 'workspace', connected: false } } as ClientConfig,
   };
 };
 
+/**
+ * Resolve the persisted client config path. Workspace dev/static reads it from the build-machine
+ * `.handoff/<projectId>` staging dir; the packaged registry app reads it from the entry
+ * dir the build copies it into (the standalone server's cwd), since the build-machine path does not
+ * exist on the deploy host.
+ */
+const resolveClientConfigPath = (): string | null => {
+  const candidates = [
+    path.resolve(process.env.HANDOFF_MODULE_PATH ?? '', '.handoff', process.env.HANDOFF_PROJECT_ID ?? '', 'client.config.json'),
+    path.resolve(process.cwd(), 'client.config.json'),
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+};
+
+/**
+ * Apply the build-time-baked runtime mode over a loaded client config. Mode is
+ * config-only and baked into the bundle, so the packaged registry app reports `registry` even when
+ * its client.config.json cannot be resolved on the deploy host.
+ */
+const applyRuntimeModeOverride = (cache: ClientConfigCache): ClientConfigCache => {
+  const bakedMode = process.env.HANDOFF_RUNTIME_MODE?.trim();
+  if (bakedMode === 'workspace' || bakedMode === 'registry') {
+    // A baked registry mode is never a connected workspace, so clear `connected` to keep the
+    // projected state internally consistent regardless of the source project's config.
+    const connected = bakedMode === 'registry' ? false : (cache.config.runtime?.connected ?? false);
+    return { config: { ...cache.config, runtime: { ...cache.config.runtime, mode: bakedMode, connected } } };
+  }
+  return cache;
+};
+
 const loadClientConfig = (): ClientConfigCache => {
   if (cachedClientConfig) {
     return cachedClientConfig;
   }
 
-  const modulePath = process.env.HANDOFF_MODULE_PATH ?? '';
-  const projectId = process.env.HANDOFF_PROJECT_ID ?? '';
-  const clientConfigPath = path.resolve(modulePath, '.handoff', projectId, 'client.config.json');
-
-  if (!fs.existsSync(clientConfigPath)) {
-    // Return empty default instead of throwing to support running without fetch
-    return getDefaultClientConfig();
+  const clientConfigPath = resolveClientConfigPath();
+  if (!clientConfigPath) {
+    // No persisted config: still honor a baked runtime mode so the packaged app reports correctly.
+    return applyRuntimeModeOverride(getDefaultClientConfig());
   }
 
   try {
     const cacheContent = fs.readFileSync(clientConfigPath, 'utf-8');
-    cachedClientConfig = JSON.parse(cacheContent) as ClientConfigCache;
+    cachedClientConfig = applyRuntimeModeOverride(JSON.parse(cacheContent) as ClientConfigCache);
     return cachedClientConfig;
   } catch (e) {
     // Return empty default on error instead of throwing
-    return getDefaultClientConfig();
+    return applyRuntimeModeOverride(getDefaultClientConfig());
   }
 };
 
-
-
 /**
  * Fetch Component Doc Page Markdown
  * @param path
@@ -656,14 +445,17 @@ const loadClientConfig = (): ClientConfigCache => {
  * @param id
  * @returns
  */
-export const fetchFoundationDocPageMarkdown = (path: string, slug: string | undefined, id: string) => {
+export const fetchFoundationDocPageMarkdown = async (path: string, slug: string | undefined, id: string) => {
+  // In a registry build the download strings must not be frozen from the build machine's generated
+  // files; they hydrate at request time from the DB-backed docs read API (`useFoundationTokens`).
+  const readTokens = !isRegistryRuntime() && slug;
   return {
     props: {
-      ...fetchDocPageMarkdown(path, slug, id).props,
-      scss: slug ? fetchTokensString(pluralizeComponent(slug), 'scss') : '',
-      css: slug ? fetchTokensString(pluralizeComponent(slug), 'css') : '',
-      styleDictionary: slug ? fetchTokensString(pluralizeComponent(slug), 'styleDictionary') : '',
-      types: slug ? fetchTokensString(pluralizeComponent(slug), 'types') : '',
+      ...(await fetchDocPageMarkdown(path, slug, id)).props,
+      scss: readTokens ? fetchTokensString(pluralizeComponent(slug), 'scss') : '',
+      css: readTokens ? fetchTokensString(pluralizeComponent(slug), 'css') : '',
+      styleDictionary: readTokens ? fetchTokensString(pluralizeComponent(slug), 'styleDictionary') : '',
+      types: readTokens ? fetchTokensString(pluralizeComponent(slug), 'types') : '',
     },
   };
 };
@@ -673,6 +465,35 @@ export const getClientRuntimeConfig = (): ClientConfig => {
   return clientConfig.config;
 };
 
+/**
+ * Whether the docs app is running in registry mode. Drives the request-time behaviors (on-demand
+ * detail rendering and the live nav fetch) that must not affect the workspace dev or static-export
+ * builds. Resolves from the same baked/persisted runtime mode the docs read API uses.
+ */
+export const isRegistryRuntime = (): boolean => getClientRuntimeConfig().runtime?.mode === 'registry';
+
+/**
+ * Build-time foundation `localStyles` for a foundation page's `getStaticProps`. In workspace/static
+ * this is the local `tokens.json` snapshot (correct: static exports are immutable). In a **registry**
+ * build it is empty — foundation token data must not be frozen into build-time page props from the
+ * build machine's `tokens.json`; the page hydrates it at request time from the DB-backed docs read
+ * API (`useFoundationTokens`). Without this gate a registry build bakes the builder's local tokens,
+ * so foundations would appear before anything is published.
+ */
+export const buildTimeFoundationDesign = (): CoreTypes.IDocumentationObject['localStyles'] =>
+  isRegistryRuntime()
+    ? ({ color: [], typography: [], effect: [] } as CoreTypes.IDocumentationObject['localStyles'])
+    : getTokens().localStyles;
+
+/**
+ * Build-time asset collections for an asset page's `getStaticProps`. Workspace/static bakes the local
+ * `tokens.json` assets (correct: static exports are immutable snapshots). A **registry** build returns
+ * empty: asset bodies must not be frozen into build-time page props from the build machine; the page
+ * hydrates them at request time from the DB-backed docs read API (`useCollectionAssets`). Without this
+ * gate a registry build bakes the builder's local assets, so they would appear before any publish.
+ */
+export const buildTimeAssets = (): CoreTypes.IDocumentationObject['assets'] => (isRegistryRuntime() ? {} : getTokens().assets);
+
 export const getTokens = (): CoreTypes.IDocumentationObject => {
   const exportedFilePath = process.env.HANDOFF_EXPORT_PATH
     ? path.resolve(process.env.HANDOFF_EXPORT_PATH, 'tokens.json')
@@ -731,7 +552,9 @@ export const fetchDocPageMetadataAndContent = (localPath: string, slug: string |
   const contentModuleFilePath = path.resolve(handoffModulePath, 'config', `${localPath}${slug}.md`);
   const contentWorkingFilePath = path.resolve(handoffWorkingPath, `${pagePath}${slug}.md`);
 
-  if (fs.existsSync(contentWorkingFilePath)) {
+  // Registry serves package `config/docs` only; workspace overrides are invisible to it (custom
+  // content comes from the DB), so the working-path read is skipped in registry mode.
+  if (!isRegistryRuntime() && fs.existsSync(contentWorkingFilePath)) {
     currentContents = fs.readFileSync(contentWorkingFilePath, 'utf-8');
   } else if (!fs.existsSync(contentModuleFilePath)) {
     return { metadata: {}, content: currentContents, options: {} };