@sudajs/cli 0.18.11 → 0.20.0

package/dist/index.js

@@ -6,9 +6,7 @@ import { createRequire } from 'module';
 import path2 from 'path';
 import { createInterface } from 'readline/promises';
 import { fileURLToPath, pathToFileURL } from 'url';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { themeDesignSystemSchema, createThemeDesignCssVariables, createThemeAgentManifest, createSudaPageAgentRuntime, checkThemeModule, formatThemeCheckResult, agentValidationResultSchema, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
+import { themeDesignSystemSchema, createThemeDesignFontStylesheetUrl, findThemeDesignSystemFieldName, resolveThemeDesignTokens, createThemeDesignCssVariables, createThemeAgentManifest, createSudaPageAgentRuntime, checkThemeModule, formatThemeCheckResult, agentValidationResultSchema } from '@sudajs/theme-engine';
 import { themeManifestSchema, runWithThemePreviewLocale } from '@sudajs/theme-engine/server';
 import { Command } from 'commander';
 import { build } from 'esbuild';
@@ -904,10 +902,13 @@ export const {
   SUDA_COLOR_TOKEN_KEYS,
   createThemeDesignCssVariables,
   createThemeDesignDefault,
+  createThemeDesignFontStylesheetUrl,
   resolveThemeDesignTokens,
   SUDA_CUSTOM_DESIGN_PRESET_ID,
   SUDA_DESIGN_COLOR_KEYS,
   SUDA_DESIGN_RADIUS_KEYS,
+  SUDA_DESIGN_TYPOGRAPHY_KEYS,
+  SUDA_THEME_FONT_FAMILIES,
   compileSudaBlockSlots,
   isSudaLocalBlockComponent,
   SUDA_LOCAL_BLOCK_CATEGORY,
@@ -1185,17 +1186,18 @@ async function validateThemeCssTokenContract(root) {
       }
     }
   }
-  const sudaAliases = /* @__PURE__ */ new Set();
+  const platformTokenPattern = /var\(\s*--(?:background|foreground|primary(?:-foreground)?|secondary(?:-foreground)?|accent(?:-foreground)?|muted(?:-foreground)?|radius(?:-(?:card|button|input))?)(?:\s*[,)])/;
+  const platformAliases = /* @__PURE__ */ new Set();
   let changed = true;
   while (changed) {
     changed = false;
     for (const [name, value] of declarations) {
-      const dependsOnSuda = /var\(\s*--suda-/.test(value);
-      const dependsOnAlias = [...sudaAliases].some(
+      const dependsOnPlatformToken = platformTokenPattern.test(value);
+      const dependsOnAlias = [...platformAliases].some(
         (alias) => new RegExp(`var\\(\\s*${escapeRegExp(alias)}(?:\\s*[,\\)])`).test(value)
       );
-      if ((dependsOnSuda || dependsOnAlias) && !sudaAliases.has(name)) {
-        sudaAliases.add(name);
+      if ((dependsOnPlatformToken || dependsOnAlias) && !platformAliases.has(name)) {
+        platformAliases.add(name);
         changed = true;
       }
     }
@@ -1211,7 +1213,7 @@ async function validateThemeCssTokenContract(root) {
       }
     }
     const searchable = handwrittenStyles.join("");
-    for (const alias of sudaAliases) {
+    for (const alias of platformAliases) {
       const reference = new RegExp(`var\\(\\s*${escapeRegExp(alias)}(?:\\s*[,\\)])`, "g");
       for (const match of searchable.matchAll(reference)) {
         const line = searchable.slice(0, match.index ?? 0).split("\n").length;
@@ -1224,7 +1226,7 @@ async function validateThemeCssTokenContract(root) {
       [
         "Hand-written theme CSS must not consume Suda-backed Tailwind aliases from `@theme inline`.",
         ...issues.map((issue) => `  - ${issue}`),
-        "Use `var(--suda-*)` directly, or define and consume a theme-prefixed variable on the theme root. Tailwind utilities such as `bg-primary` remain supported."
+        "Use an unprefixed platform token such as `var(--primary)` directly, or define and consume a theme-prefixed variable on the theme root. Tailwind utilities such as `bg-primary` remain supported."
       ].join("\n")
     );
   }
@@ -1724,8 +1726,14 @@ function runFooterContractCheck(theme, renderer) {
   return issues;
 }
 var __testUtils = {
+  activateThemeOutputSchema,
+  contactFormOutputSchema,
+  createPageDraftOutputSchema,
+  createProjectOutputSchema,
   createThemeProjectRequire,
+  createVisualAuditPage,
   createRemotePageDraft,
+  destructivePageOperationOutputSchema,
   findAnchorTagByHref,
   formatMissingSharpWarning,
   loadThemeScopedRenderer,
@@ -1736,13 +1744,19 @@ var __testUtils = {
   performConfirmedPageOperation,
   performUpdateContactForm,
   performUpdateThemeSettings,
+  getRemoteContactForm,
   getRemoteThemeSettings,
+  listProjectsOutputSchema,
   renderDevStarterPageHtml,
   renderDevEditorPageHtml,
+  readDevThemeLocaleMessages,
   writeVitePreviewEntries,
   resolveDevEditorSlug,
   resolveDevStarterSlug,
+  resolveDevVisualAuditComponent,
+  getThemeVisualAuditComponentTypes,
   resolveScreenshotOptions,
+  resolveVisualCheckOptions,
   slugifyThemeName,
   validateThemeKey,
   validateThemeName,
@@ -1753,7 +1767,11 @@ var __testUtils = {
   resolveThemePreviewLocale,
   withSerializedVitePreviewLocaleLoad,
   toViteModuleUrl,
-  updateRemotePageDraft
+  themeSettingsOutputSchema,
+  updateContactFormOutputSchema,
+  updatePageDraftOutputSchema,
+  updateRemotePageDraft,
+  updateThemeSettingsOutputSchema
 };
 async function runThemeCheck(theme) {
   const result = checkThemeModule(theme.module);
@@ -1809,7 +1827,7 @@ async function watchTheme(root, port) {
   console.log(`previewing Vite theme at ${style.url(handle.url)}`);
   await new Promise(() => void 0);
 }
-async function startViteDevPreviewServer(root, port) {
+async function startViteDevPreviewServer(root, port, options = {}) {
   const viteConfig = await findViteConfig(root);
   const vite = await loadThemeVite(root);
   await writeVitePreviewEntries(root);
@@ -1824,13 +1842,14 @@ async function startViteDevPreviewServer(root, port) {
       entries: [".suda-build/preview-client.ts", ".suda-build/editor-client.ts"]
     },
     server: { host, port },
-    plugins: [createSudaPreviewVitePlugin(root)]
+    plugins: [createSudaPreviewVitePlugin(root, options)]
   });
   await server.listen(port);
   const url = server.resolvedUrls?.local.find((candidate) => candidate.includes("127.0.0.1")) ?? server.resolvedUrls?.local[0] ?? `http://${host}:${port}/`;
   return {
     url: url.replace(/\/$/, ""),
     port,
+    server,
     close: () => server.close()
   };
 }
@@ -1840,8 +1859,8 @@ async function writeVitePreviewEntries(root) {
   const buildDir = path2.join(root, ".suda-build");
   await mkdir(buildDir, { recursive: true });
   await writeFile(
-    path2.join(buildDir, "runtime.dev.ts"),
-    createClientRuntimeSource(clientHooksImport, false),
+    path2.join(buildDir, "runtime.dev.js"),
+    createClientRuntimeSource(clientHooksImport, false, false),
     "utf8"
   );
   await writeFile(
@@ -1853,7 +1872,7 @@ async function writeVitePreviewEntries(root) {
       'if(!payloadElement){throw new Error("Missing Suda theme hydration payload.")}',
       "const payload=JSON.parse(payloadElement.textContent ?? '{}');",
       "if(payload.previewLocaleMessages){installThemePreviewLocale(payload.previewLocaleMessages)}",
-      'const runtime=(await loadThemeRuntime("/.suda-build/runtime.dev.ts")).default;',
+      'const runtime=(await loadThemeRuntime("/.suda-build/runtime.dev.js")).default;',
       'const metadata={contactForm:payload.contactForm,resolveAssetUrl:(value: string | undefined)=>resolveAssetPath(value,{legacyResolve:(key)=>key.startsWith("themes/")?`/api/themes/${key.slice("themes/".length)}`:undefined})};',
       'await hydrateThemePage({container:document.querySelector("[data-theme-hydration-root]")!,runtime,pageData:payload.pageData,layoutData:payload.layoutData,metadata,onRecoverableError:(error)=>console.error("[theme-dev] theme hydration recovered from an error",error)});',
       ""
@@ -1864,26 +1883,50 @@ async function writeVitePreviewEntries(root) {
     path2.join(buildDir, "editor-client.ts"),
     [
       'import "@puckeditor/core/puck.css";',
-      'import { composeUnifiedThemeEditorData, createUnifiedThemeEditorConfig, installThemePreviewLocale, resolveAssetPath, ThemeEditor } from "@sudajs/theme-engine";',
+      'import { composeUnifiedThemeEditorData, createThemeDesignFontStylesheetUrl, createUnifiedThemeEditorConfig, installThemeLocale, installThemePreviewLocale, resolveAssetPath, resolveThemeDesignTokens, ThemeEditor } from "@sudajs/theme-engine";',
       'import { createElement } from "react";',
       'import { createRoot } from "react-dom/client";',
-      'import runtime from "./runtime.dev";',
       'const payloadElement=document.querySelector("#suda-theme-editor-data");',
       'if(!payloadElement){throw new Error("Missing Suda theme editor payload.")}',
       "const payload=JSON.parse(payloadElement.textContent ?? '{}');",
+      "if(payload.themeLocaleMessages){installThemeLocale(payload.themeLocaleMessages)}",
       "if(payload.previewLocaleMessages){installThemePreviewLocale(payload.previewLocaleMessages)}",
+      'const runtime=(await import("./runtime.dev")).default;',
       'const resolveAssetUrl=(value: string | undefined)=>resolveAssetPath(value,{legacyResolve:(key)=>key.startsWith("themes/")?`/api/themes/${key.slice("themes/".length)}`:undefined});',
       'const config=createUnifiedThemeEditorConfig(runtime.theme,undefined,{labels:{pageContent:"Page content",themeSettings:"Theme settings"}});',
       "const data=composeUnifiedThemeEditorData(payload.layoutData,payload.pageData,{layoutConfig:runtime.theme.layoutConfig,pageConfig:runtime.theme.pageConfig});",
+      'function applyDesignFont(nextData){const fieldName=payload.designSystemFieldName||"designSystem";const value=nextData?.root?.props?.[fieldName];const tokens=resolveThemeDesignTokens(payload.designSystem,value);const href=createThemeDesignFontStylesheetUrl(tokens);let link=document.querySelector("#suda-theme-fonts");if(!href){link?.remove();return}if(!link){link=document.createElement("link");link.id="suda-theme-fonts";link.rel="stylesheet";document.head.append(link)}link.href=href}',
+      "applyDesignFont(data);",
       'const editorContext={assets:[],resolveAssetUrl,currentPageId:payload.currentPageId,backHref:payload.backHref,editorPages:payload.editorPages,editorLocale:payload.locale,chromeMessages:{backToPages:"Back to preview",pageMenuLabel:"Switch starter page",themeSettings:"Theme settings",outline:"Outline",blocks:"Blocks",switchViewport:"Switch viewport"}};',
       "const metadata={contactForm:payload.contactForm,isEditor:true,resolveAssetUrl};",
-      'createRoot(document.querySelector("#suda-theme-dev-editor-root")!).render(createElement(ThemeEditor,{config,data,editorContext,metadata,iframe:false,height:"100%",publishActionVisible:false}));',
+      'createRoot(document.querySelector("#suda-theme-dev-editor-root")!).render(createElement(ThemeEditor,{config,data,editorContext,metadata,iframe:false,height:"100%",previewStylesheetUrls:["/src/styles.css"],publishActionVisible:false,onChange:applyDesignFont}));',
       ""
     ].join("\n"),
     "utf8"
   );
 }
-function createClientRuntimeSource(clientHooksImport, useClientDirective) {
+function createClientRuntimeSource(clientHooksImport, useClientDirective, typescript = true) {
+  if (!typescript) {
+    return [
+      ...useClientDirective ? ['"use client";'] : [],
+      'import * as themeConfig from "../src/config.js";',
+      clientHooksImport,
+      "const theme = {",
+      "  pageConfig: themeConfig.pageConfig,",
+      "  layoutConfig: themeConfig.layoutConfig,",
+      "};",
+      'if ("rendering" in themeConfig && themeConfig.rendering !== undefined) {',
+      "  theme.rendering = themeConfig.rendering;",
+      "}",
+      "const hooks = clientHooks;",
+      "const runtime = { theme };",
+      "if (hooks.initialize !== undefined) {",
+      "  runtime.initialize = hooks.initialize;",
+      "}",
+      "export default runtime;",
+      ""
+    ].join("\n");
+  }
   return [
     ...useClientDirective ? ['"use client";'] : [],
     'import type { ThemeClientHooks, ThemeClientRuntime, ThemeRenderModule } from "@sudajs/theme-engine/runtime";',
@@ -1905,22 +1948,49 @@ function createClientRuntimeSource(clientHooksImport, useClientDirective) {
     ""
   ].join("\n");
 }
-function createSudaPreviewVitePlugin(root) {
+function createSudaPreviewVitePlugin(root, options = {}) {
   return {
     name: "suda-theme-preview",
+    resolveId(source, importer) {
+      if (importer === void 0 || !source.endsWith(".js") || !source.startsWith(".")) {
+        return void 0;
+      }
+      const requestedPath = path2.resolve(path2.dirname(importer), source);
+      if (!requestedPath.startsWith(`${root}${path2.sep}`)) {
+        return void 0;
+      }
+      for (const extension of [".ts", ".tsx"]) {
+        const candidate = `${requestedPath.slice(0, -3)}${extension}`;
+        if (existsSync(candidate)) {
+          return candidate;
+        }
+      }
+      return void 0;
+    },
     configureServer(server) {
       server.middlewares.use((request, response, next) => {
         void (async () => {
           const url = new URL(request.url ?? "/", "http://localhost");
+          if (url.pathname.startsWith("/src/") && url.pathname.endsWith(".js")) {
+            const sourcePath = path2.join(root, url.pathname.slice(1));
+            for (const extension of [".ts", ".tsx"]) {
+              const candidate = `${sourcePath.slice(0, -3)}${extension}`;
+              if (existsSync(candidate)) {
+                request.url = `${url.pathname.slice(0, -3)}${extension}${url.search}`;
+                break;
+              }
+            }
+          }
           const assetPrefixMatch = url.pathname.match(/^\/api\/themes\/[^/]+\/[^/]+\/assets\/(.+)$/);
           if (assetPrefixMatch?.[1]) {
             request.url = `/assets/${assetPrefixMatch[1]}${url.search}`;
             next();
             return;
           }
+          const visualAuditComponent = resolveDevVisualAuditComponent(url.pathname);
           const editorSlug = resolveDevEditorSlug(url.pathname);
           const previewSlug = resolveDevStarterSlug(url.pathname);
-          if (editorSlug === void 0 && previewSlug === void 0) {
+          if (visualAuditComponent === void 0 && editorSlug === void 0 && previewSlug === void 0) {
             next();
             return;
           }
@@ -1938,11 +2008,11 @@ function createSudaPreviewVitePlugin(root) {
             );
             const renderer = await loadThemeScopedRenderer(root);
             const starterSlug = slug ?? pickStarterSlug(localized.theme);
-            const starter = starterSlug ? findStarterPage(localized.theme, starterSlug) : null;
+            const starter = visualAuditComponent ? createVisualAuditPage(localized.theme, visualAuditComponent) : starterSlug ? findStarterPage(localized.theme, starterSlug) : null;
             if (!starter) {
               response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
               response.end(
-                starterSlug ? `Unknown starter page: ${starterSlug}` : "No starter pages declared by this theme."
+                starterSlug ? `Unknown starter page: ${starterSlug}` : visualAuditComponent ? `Unknown theme page component: ${visualAuditComponent}` : "No starter pages declared by this theme."
               );
               return;
             }
@@ -1952,7 +2022,8 @@ function createSudaPreviewVitePlugin(root) {
               renderer,
               localized.locale,
               url.searchParams,
-              localized.previewLocaleMessages
+              localized.previewLocaleMessages,
+              localized.themeLocaleMessages
             ) : renderDevStarterPageHtml(
               localized.theme,
               starter,
@@ -1960,7 +2031,8 @@ function createSudaPreviewVitePlugin(root) {
               localized.locale,
               canonicalLocale(explicitLang) !== null,
               localized.previewLocaleMessages,
-              url.searchParams
+              url.searchParams,
+              { showDevTools: options.showDevTools !== false }
             );
             const html = await server.transformIndexHtml(url.pathname, htmlSource);
             response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
@@ -1985,8 +2057,9 @@ async function loadLocalizedViteDevTheme(root, server, explicitLang, acceptLangu
       localeParams.acceptLanguage = acceptLanguage;
     }
     const locale = resolveThemePreviewLocale(localeParams);
+    const themeLocaleMessages = await readDevThemeLocaleMessages(root, locale);
     if (!baseTheme.module.manifest.previewLocales) {
-      return { theme: baseTheme, locale };
+      return { theme: baseTheme, locale, themeLocaleMessages };
     }
     const previewLocaleMessages = await readDevPreviewLocaleMessages(root, locale);
     server.moduleGraph.invalidateAll();
@@ -1994,7 +2067,7 @@ async function loadLocalizedViteDevTheme(root, server, explicitLang, acceptLangu
       previewLocaleMessages,
       () => loadViteDevTheme(root, server)
     );
-    return { theme, locale, previewLocaleMessages };
+    return { theme, locale, themeLocaleMessages, previewLocaleMessages };
   });
 }
 var vitePreviewLocaleLoadTails = /* @__PURE__ */ new WeakMap();
@@ -2043,6 +2116,42 @@ function findStarterPage(theme, slug) {
   return theme.module.starterPages.find((page) => page.slug === slug) ?? null;
 }
 var DEV_EDITOR_PATH = "/__suda/editor";
+var DEV_VISUAL_AUDIT_PATH = "/__suda/visual-audit";
+function resolveDevVisualAuditComponent(pathname) {
+  if (!pathname.startsWith(`${DEV_VISUAL_AUDIT_PATH}/`)) {
+    return void 0;
+  }
+  const encodedComponent = pathname.slice(DEV_VISUAL_AUDIT_PATH.length + 1);
+  if (!encodedComponent || encodedComponent.includes("/")) {
+    return void 0;
+  }
+  try {
+    return decodeURIComponent(encodedComponent);
+  } catch {
+    return void 0;
+  }
+}
+function getThemeVisualAuditComponentTypes(theme) {
+  return Object.keys(theme.module.pageConfig.components);
+}
+function createVisualAuditPage(theme, type) {
+  const themeComponent = theme.module.pageConfig.components[type];
+  if (!themeComponent) {
+    return null;
+  }
+  const props = {
+    ...themeComponent.defaultProps ?? {},
+    id: `suda-visual-audit-${safeObjectKeyPart(type)}`
+  };
+  return {
+    slug: `visual-audit-${safeObjectKeyPart(type).toLowerCase()}`,
+    title: `Visual audit: ${type}`,
+    data: {
+      root: { props: {} },
+      content: [{ type, props }]
+    }
+  };
+}
 function resolveDevEditorSlug(pathname) {
   if (pathname === DEV_EDITOR_PATH || pathname === `${DEV_EDITOR_PATH}/`) {
     return null;
@@ -2136,6 +2245,16 @@ async function readDevPreviewLocaleMessages(root, locale) {
   }
   return messages;
 }
+async function readDevThemeLocaleMessages(root, locale) {
+  const localesDir = path2.join(root, "src", "locales");
+  const localizedPath = path2.join(localesDir, `${locale}.json`);
+  const filePath = await pathExists(localizedPath) ? localizedPath : path2.join(localesDir, "en.json");
+  const messages = await readLocaleJson(filePath);
+  if (!isRecord(messages)) {
+    throw new Error(`Theme locale ${locale} must be a JSON object.`);
+  }
+  return messages;
+}
 function escapeHtml(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -2169,8 +2288,10 @@ async function loadThemeScopedRenderer(themeRoot) {
     renderToString: reactDomServerModule.renderToString
   };
 }
-function renderDevStarterPageHtml(theme, page, renderer, locale = "en", preserveLang = false, previewLocaleMessages, searchParams = new URLSearchParams()) {
+function renderDevStarterPageHtml(theme, page, renderer, locale = "en", preserveLang = false, previewLocaleMessages, searchParams = new URLSearchParams(), options = {}) {
   const layoutData = createDevPreviewLayout(theme, searchParams);
+  const designTokens = resolveDevDesignTokens(theme, layoutData);
+  const fontStylesheetUrl = createThemeDesignFontStylesheetUrl(designTokens);
   const chrome = renderer.extractLayoutChrome(layoutData);
   const metadata = {
     resolveAssetUrl: createPreviewAssetResolver(renderer.resolveAssetPath),
@@ -2187,10 +2308,11 @@ function renderDevStarterPageHtml(theme, page, renderer, locale = "en", preserve
   const cssVarStyle = Object.entries(chrome.cssVariables).map(([key, value]) => `${key}: ${value};`).join(" ");
   const customHead = chrome.customHeadCode ?? "";
   const customBody = chrome.customBodyCode ?? "";
-  const designPalette = renderDevDesignPalette(
+  const showDevTools = options.showDevTools !== false;
+  const designPalette = showDevTools ? renderDevDesignPalette(
     theme.module.manifest.designSystem,
     createDevEditorHref(page.slug, searchParams)
-  );
+  ) : null;
   const hydrationPayload = serializeInlineScriptValue({
     pageData: page.data,
     layoutData,
@@ -2209,12 +2331,13 @@ function renderDevStarterPageHtml(theme, page, renderer, locale = "en", preserve
     '<meta name="viewport" content="width=device-width, initial-scale=1" />',
     `<title>${escapeHtml(`${theme.module.manifest.name} \u2014 ${page.title}`)}</title>`,
     '<link rel="stylesheet" href="/src/styles.css" />',
-    designPalette.style,
+    ...fontStylesheetUrl ? [`<link id="suda-theme-fonts" rel="stylesheet" href="${escapeHtml(fontStylesheetUrl)}" />`] : [],
     customHead,
+    designPalette?.style ?? "",
     "</head>",
     `<body${cssVarStyle ? ` style="${cssVarStyle}"` : ""}>`,
     `<div data-theme-hydration-root="" style="display:contents">${body}</div>`,
-    designPalette.html,
+    designPalette?.html ?? "",
     customBody,
     hydrationScript,
     ...preserveLang ? [
@@ -2251,10 +2374,7 @@ function createDevPreviewLayout(theme, searchParams) {
   if (!requestedPreset) {
     return theme.module.defaultLayout;
   }
-  const rootFields = theme.module.layoutConfig.root?.fields ?? {};
-  const designFieldName = Object.entries(rootFields).find(
-    ([, field]) => field.metadata?.sudaField === "designSystem"
-  )?.[0];
+  const designFieldName = findThemeDesignSystemFieldName(theme.module.layoutConfig.root?.fields);
   if (!designFieldName) {
     return theme.module.defaultLayout;
   }
@@ -2268,8 +2388,16 @@ function createDevPreviewLayout(theme, searchParams) {
   };
   return layoutData;
 }
-function renderDevEditorPageHtml(theme, page, renderer, locale = "en", searchParams = new URLSearchParams(), previewLocaleMessages) {
+function resolveDevDesignTokens(theme, layoutData) {
+  const designFieldName = findThemeDesignSystemFieldName(theme.module.layoutConfig.root?.fields);
+  const rootProps = layoutData.root?.props;
+  const designValue = designFieldName ? rootProps?.[designFieldName] : void 0;
+  return resolveThemeDesignTokens(theme.module.manifest.designSystem, designValue);
+}
+function renderDevEditorPageHtml(theme, page, renderer, locale = "en", searchParams = new URLSearchParams(), previewLocaleMessages, themeLocaleMessages) {
   const layoutData = createDevPreviewLayout(theme, searchParams);
+  const designTokens = resolveDevDesignTokens(theme, layoutData);
+  const fontStylesheetUrl = createThemeDesignFontStylesheetUrl(designTokens);
   const chrome = renderer.extractLayoutChrome(layoutData);
   const cssVariables = { ...chrome.cssVariables };
   const cssVarStyle = Object.entries(cssVariables).map(([key, value]) => `${key}: ${value};`).join(" ");
@@ -2285,6 +2413,9 @@ function renderDevEditorPageHtml(theme, page, renderer, locale = "en", searchPar
     layoutData,
     contactForm: PREVIEW_CONTACT_FORM,
     previewLocaleMessages,
+    designSystem: theme.module.manifest.designSystem,
+    designSystemFieldName: findThemeDesignSystemFieldName(theme.module.layoutConfig.root?.fields) ?? "designSystem",
+    themeLocaleMessages,
     locale,
     currentPageId: page.slug,
     backHref: createDevPreviewHref(page, searchParams),
@@ -2298,6 +2429,7 @@ function renderDevEditorPageHtml(theme, page, renderer, locale = "en", searchPar
     '<meta name="viewport" content="width=device-width, initial-scale=1" />',
     `<title>${escapeHtml(`Edit ${theme.module.manifest.name} \u2014 ${page.title}`)}</title>`,
     '<link rel="stylesheet" href="/src/styles.css" />',
+    ...fontStylesheetUrl ? [`<link id="suda-theme-fonts" rel="stylesheet" href="${escapeHtml(fontStylesheetUrl)}" />`] : [],
     "<style>html,body,#suda-theme-dev-editor-root{height:100%;margin:0}body{overflow:hidden}</style>",
     "</head>",
     `<body${cssVarStyle ? ` style="${cssVarStyle}"` : ""}>`,
@@ -2312,10 +2444,14 @@ function serializeInlineScriptValue(value) {
   return JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
 }
 function renderDevDesignPalette(designSystem, editorHref) {
-  const hasPresetSwitcher = designSystem.presets.length >= 2;
+  const primaryColors = new Set(
+    designSystem.presets.map((preset) => preset.tokens.colors.primary)
+  );
+  const hasPresetSwitcher = primaryColors.size >= 2;
   const presets = designSystem.presets.map((preset) => ({
     id: preset.id,
-    variables: createThemeDesignCssVariables(preset.tokens)
+    variables: createThemeDesignCssVariables(preset.tokens),
+    fontStylesheetUrl: createThemeDesignFontStylesheetUrl(preset.tokens)
   }));
   const selectedIcon = renderToStaticMarkup(
     createElement(CircleCheck, {
@@ -2347,7 +2483,7 @@ function renderDevDesignPalette(designSystem, editorHref) {
   });
   return {
     style: '<style data-suda-dev-palette-style>\n#suda-dev-palette{all:initial;position:fixed;z-index:2147483000;top:50%;right:16px;width:64px;max-height:calc(100svh - 32px);padding:8px 9px;overflow-x:hidden;overflow-y:auto;box-sizing:border-box;background:#fff;border:1px solid #d1d5db;border-radius:999px;box-shadow:0 8px 24px rgb(15 23 42 / 12%);transform:translateY(-50%);color-scheme:light;scrollbar-width:none;-ms-overflow-style:none}\n#suda-dev-palette::-webkit-scrollbar{display:none}\n#suda-dev-palette button{all:initial;position:relative;display:grid;width:44px;height:44px;box-sizing:border-box;cursor:pointer;border-radius:999px;place-items:center}\n#suda-dev-palette button span{display:block;width:32px;height:32px;border-radius:999px;transition:transform 120ms ease}\n#suda-dev-palette button:hover span{transform:scale(1.08)}\n#suda-dev-palette button[aria-pressed="true"] span{visibility:hidden}\n#suda-dev-palette .suda-dev-preset-selected-icon{position:absolute;display:block;width:32px;height:32px;color:var(--suda-dev-preset-primary);visibility:hidden;opacity:0;transform:scale(.85);transition:opacity 120ms ease,transform 120ms ease}\n#suda-dev-palette button[aria-pressed="true"] .suda-dev-preset-selected-icon{visibility:visible;opacity:1;transform:scale(1)}\n#suda-dev-palette button:focus-visible{outline:2px solid #94a3b8;outline-offset:2px}\n#suda-dev-palette .suda-dev-edit-divider{display:block;width:28px;height:1px;margin:4px auto;background:#e2e8f0}\n#suda-dev-palette .suda-dev-edit-link{all:initial;display:grid;width:44px;height:44px;box-sizing:border-box;color:#334155;cursor:pointer;border-radius:999px;place-items:center;transition:background-color 120ms ease,color 120ms ease}\n#suda-dev-palette .suda-dev-edit-link:hover{color:#0f172a;background:#f1f5f9}\n#suda-dev-palette .suda-dev-edit-link:focus-visible{outline:2px solid #94a3b8;outline-offset:2px}\n@media(max-width:640px){#suda-dev-palette{right:8px;max-height:calc(100svh - 16px)}}\n@media(prefers-reduced-motion:reduce){#suda-dev-palette button span,#suda-dev-palette .suda-dev-preset-selected-icon,#suda-dev-palette .suda-dev-edit-link{transition:none}}\n</style>',
-    html: `<aside id="suda-dev-palette" aria-label="Theme development tools">${buttons}${hasPresetSwitcher ? '<span class="suda-dev-edit-divider" aria-hidden="true"></span>' : ""}<a class="suda-dev-edit-link" data-suda-dev-editor-link="" href="${escapeHtml(editorHref)}" title="Edit starter page" aria-label="Edit starter page">${editIcon}</a></aside>` + (hasPresetSwitcher ? `<script data-suda-dev-palette-script>(function(){const config=${config};const palette=document.getElementById("suda-dev-palette");if(!palette)return;const byId=new Map(config.presets.map((preset)=>[preset.id,preset]));const params=new URL(location.href).searchParams;const requested=params.get("designPreset");const selected=byId.has(requested)?requested:config.defaultPresetId;function apply(id,updateUrl){const preset=byId.get(id);if(!preset)return;const properties=Object.keys(preset.variables);const targets=[document.documentElement,document.body,...document.querySelectorAll("[style]")].filter((element,index,items)=>items.indexOf(element)===index&&(element===document.documentElement||element===document.body||properties.some((property)=>element.style.getPropertyValue(property)!=="")));for(const target of targets){for(const [property,value] of Object.entries(preset.variables))target.style.setProperty(property,value)}for(const button of palette.querySelectorAll("[data-suda-dev-preset]")){const active=button.dataset.sudaDevPreset===id;button.setAttribute("aria-pressed",String(active));button.style.setProperty("--suda-dev-preset-primary",byId.get(button.dataset.sudaDevPreset).variables["--suda-color-primary"])}const editorLink=palette.querySelector("[data-suda-dev-editor-link]");if(editorLink){const editorUrl=new URL(editorLink.href,location.href);editorUrl.searchParams.set("designPreset",id);editorLink.href=editorUrl.pathname+editorUrl.search+editorUrl.hash}if(updateUrl){const url=new URL(location.href);url.searchParams.set("designPreset",id);history.replaceState(history.state,"",url)}}if(requested&&byId.has(requested))apply(selected,false);else for(const button of palette.querySelectorAll("[data-suda-dev-preset]")){button.setAttribute("aria-pressed",String(button.dataset.sudaDevPreset===selected));button.style.setProperty("--suda-dev-preset-primary",byId.get(button.dataset.sudaDevPreset).variables["--suda-color-primary"])}palette.addEventListener("click",(event)=>{const button=event.target.closest("[data-suda-dev-preset]");if(button)apply(button.dataset.sudaDevPreset,true)})})();</script>` : "")
+    html: `<aside id="suda-dev-palette" aria-label="Theme development tools">${buttons}${hasPresetSwitcher ? '<span class="suda-dev-edit-divider" aria-hidden="true"></span>' : ""}<a class="suda-dev-edit-link" data-suda-dev-editor-link="" href="${escapeHtml(editorHref)}" title="Edit starter page" aria-label="Edit starter page">${editIcon}</a></aside>` + (hasPresetSwitcher ? `<script data-suda-dev-palette-script>(function(){const config=${config};const palette=document.getElementById("suda-dev-palette");if(!palette)return;const byId=new Map(config.presets.map((preset)=>[preset.id,preset]));const params=new URL(location.href).searchParams;const requested=params.get("designPreset");const selected=byId.has(requested)?requested:config.defaultPresetId;function apply(id,updateUrl){const preset=byId.get(id);if(!preset)return;const properties=Object.keys(preset.variables);const targets=[document.documentElement,document.body,...document.querySelectorAll("[style]")].filter((element,index,items)=>items.indexOf(element)===index&&(element===document.documentElement||element===document.body||properties.some((property)=>element.style.getPropertyValue(property)!=="")));for(const target of targets){for(const [property,value] of Object.entries(preset.variables))target.style.setProperty(property,value)}let fontLink=document.querySelector("#suda-theme-fonts");if(preset.fontStylesheetUrl){if(!fontLink){fontLink=document.createElement("link");fontLink.id="suda-theme-fonts";fontLink.rel="stylesheet";document.head.append(fontLink)}fontLink.href=preset.fontStylesheetUrl}else fontLink?.remove();for(const button of palette.querySelectorAll("[data-suda-dev-preset]")){const active=button.dataset.sudaDevPreset===id;button.setAttribute("aria-pressed",String(active));button.style.setProperty("--suda-dev-preset-primary",byId.get(button.dataset.sudaDevPreset).variables["--primary"])}const editorLink=palette.querySelector("[data-suda-dev-editor-link]");if(editorLink){const editorUrl=new URL(editorLink.href,location.href);editorUrl.searchParams.set("designPreset",id);editorLink.href=editorUrl.pathname+editorUrl.search+editorUrl.hash}if(updateUrl){const url=new URL(location.href);url.searchParams.set("designPreset",id);history.replaceState(history.state,"",url)}}if(requested&&byId.has(requested))apply(selected,false);else for(const button of palette.querySelectorAll("[data-suda-dev-preset]")){button.setAttribute("aria-pressed",String(button.dataset.sudaDevPreset===selected));button.style.setProperty("--suda-dev-preset-primary",byId.get(button.dataset.sudaDevPreset).variables["--primary"])}palette.addEventListener("click",(event)=>{const button=event.target.closest("[data-suda-dev-preset]");if(button)apply(button.dataset.sudaDevPreset,true)})})();</script>` : "")
   };
 }
 var SCREENSHOT_DEVICES = ["desktop", "tablet", "mobile"];
@@ -2422,6 +2558,33 @@ function resolveScreenshotOptions(root, options) {
     fullPage: options.fullPage === true
   };
 }
+function parseVisualCheckPresetIds(theme, value) {
+  const available = theme.module.manifest.designSystem.presets.map((preset) => preset.id);
+  if (value === void 0) {
+    return available;
+  }
+  const requested = (Array.isArray(value) ? value : [value]).flatMap((item) => item.split(",")).map((item) => item.trim()).filter(Boolean);
+  if (requested.length === 0) {
+    return available;
+  }
+  const unknown = requested.filter((preset) => !available.includes(preset));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown design preset ${unknown.map((preset) => `"${preset}"`).join(", ")}. Available presets: ${available.join(", ")}.`
+    );
+  }
+  return Array.from(new Set(requested));
+}
+function resolveVisualCheckOptions(root, theme, options) {
+  const outputDir = path2.resolve(root, options.output ?? path2.join(".suda-build", "visual-check"));
+  return {
+    devices: parseScreenshotDevices(options.device),
+    fullPage: options.fullPage === true,
+    outputDir,
+    port: parsePositiveInt(options.port, 4179),
+    presetIds: parseVisualCheckPresetIds(theme, options.preset)
+  };
+}
 function createThemeProjectRequire(themeRoot) {
   return createRequire(path2.join(themeRoot, "package.json"));
 }
@@ -2516,7 +2679,7 @@ async function optimizePngIfAvailable(themeRoot, filePath) {
 }
 async function captureScreenshot(root, options) {
   const playwright = await loadPlaywright(root);
-  const handle = await startViteDevPreviewServer(root, options.port);
+  const handle = await startViteDevPreviewServer(root, options.port, { showDevTools: false });
   try {
     const browser = await playwright.chromium.launch({ headless: true });
     try {
@@ -2549,6 +2712,278 @@ async function screenshotTheme(root, options) {
   const resolved = resolveScreenshotOptions(root, options);
   await captureScreenshot(root, resolved);
 }
+function visualAuditUrl(baseUrl, component, preset) {
+  const url = new URL(`${DEV_VISUAL_AUDIT_PATH}/${encodeURIComponent(component)}`, `${baseUrl}/`);
+  url.searchParams.set("designPreset", preset);
+  return url.href;
+}
+async function runThemeVisualCheck(root, options) {
+  const playwright = await loadPlaywright(root);
+  const handle = await startViteDevPreviewServer(root, parsePositiveInt(options.port, 4179));
+  let theme;
+  try {
+    theme = await loadViteDevTheme(root, handle.server);
+  } catch (error2) {
+    await handle.close();
+    throw error2;
+  }
+  const resolved = resolveVisualCheckOptions(root, theme, options);
+  const components = getThemeVisualAuditComponentTypes(theme);
+  const report = {
+    components,
+    issues: [],
+    outputDir: resolved.outputDir,
+    presets: resolved.presetIds
+  };
+  try {
+    const browser = await playwright.chromium.launch({ headless: true });
+    try {
+      for (const preset of resolved.presetIds) {
+        for (const device of resolved.devices) {
+          const viewport = SCREENSHOT_DEVICE_CONFIG[device].viewport;
+          const context = await browser.newContext({ viewport, deviceScaleFactor: 1 });
+          try {
+            for (const component of components) {
+              const page = await context.newPage();
+              const pageErrors = [];
+              page.on("pageerror", (error2) => pageErrors.push(error2.message));
+              try {
+                await page.goto(visualAuditUrl(handle.url, component, preset), {
+                  waitUntil: "networkidle"
+                });
+                const audit = await page.evaluate(() => {
+                  const issues = [];
+                  const section = document.querySelector("[data-section]");
+                  if (!section) {
+                    return {
+                      issues: [
+                        {
+                          code: "section-missing",
+                          message: "The visual audit page did not render the theme component.",
+                          severity: "error"
+                        }
+                      ]
+                    };
+                  }
+                  const colorForToken = (token) => {
+                    const probe = document.createElement("span");
+                    probe.style.color = `var(${token})`;
+                    probe.style.display = "none";
+                    section.append(probe);
+                    const color = getComputedStyle(probe).color;
+                    probe.remove();
+                    return color;
+                  };
+                  const contrastRatio = (first, second) => {
+                    const channels = (value) => {
+                      const match = value.match(/^rgba?\\(([^)]+)\\)$/);
+                      if (!match?.[1]) return null;
+                      const parsed = match[1].split(",").slice(0, 3).map((channel) => Number.parseFloat(channel.trim()));
+                      if (parsed.length !== 3 || !parsed.every(Number.isFinite)) return null;
+                      const [red, green, blue] = parsed;
+                      if (red === void 0 || green === void 0 || blue === void 0) return null;
+                      return [red, green, blue];
+                    };
+                    const firstRgb = channels(first);
+                    const secondRgb = channels(second);
+                    if (!firstRgb || !secondRgb) return null;
+                    const luminance = (values) => {
+                      const [red, green, blue] = values.map((channel) => {
+                        const normalized = channel / 255;
+                        return normalized <= 0.04045 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
+                      });
+                      return 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+                    };
+                    const firstLuminance = luminance(firstRgb);
+                    const secondLuminance = luminance(secondRgb);
+                    return (Math.max(firstLuminance, secondLuminance) + 0.05) / (Math.min(firstLuminance, secondLuminance) + 0.05);
+                  };
+                  const tokenPairs = [
+                    ["--background", "--foreground"],
+                    ["--primary", "--primary-foreground"],
+                    ["--secondary", "--secondary-foreground"],
+                    ["--accent", "--accent-foreground"],
+                    ["--muted", "--muted-foreground"]
+                  ];
+                  for (const [surfaceToken, foregroundToken] of tokenPairs) {
+                    const ratio = contrastRatio(colorForToken(surfaceToken), colorForToken(foregroundToken));
+                    if (ratio === null) {
+                      issues.push({
+                        code: "token-color-unresolved",
+                        message: `${surfaceToken} or ${foregroundToken} did not resolve to a CSS color.`,
+                        severity: "error"
+                      });
+                    } else if (ratio < 4.5) {
+                      issues.push({
+                        code: "token-contrast",
+                        message: `${surfaceToken} and ${foregroundToken} have ${ratio.toFixed(2)}:1 contrast; 4.5:1 is required.`,
+                        severity: "error"
+                      });
+                    }
+                  }
+                  const semanticTokenPairs = [
+                    ["--background", "--foreground"],
+                    ["--primary", "--primary-foreground"],
+                    ["--secondary", "--secondary-foreground"],
+                    ["--accent", "--accent-foreground"],
+                    ["--muted", "--muted-foreground"]
+                  ];
+                  const semanticSurfaces = semanticTokenPairs.map(([surface, foreground]) => ({
+                    foreground,
+                    foregroundColor: colorForToken(foreground),
+                    surface,
+                    surfaceColor: colorForToken(surface)
+                  }));
+                  const semanticSurfacesByElement = /* @__PURE__ */ new Map();
+                  for (const element of [section, ...section.querySelectorAll("*")]) {
+                    const backgroundColor = getComputedStyle(element).backgroundColor;
+                    const surface = semanticSurfaces.find(
+                      (candidate) => candidate.surfaceColor === backgroundColor
+                    );
+                    if (surface) semanticSurfacesByElement.set(element, surface);
+                  }
+                  const visible = (element) => {
+                    const style2 = getComputedStyle(element);
+                    const rect = element.getBoundingClientRect();
+                    return style2.display !== "none" && style2.visibility !== "hidden" && Number.parseFloat(style2.opacity) > 0 && rect.width > 0 && rect.height > 0;
+                  };
+                  const closestSurface = (element) => {
+                    let current = element;
+                    while (current && section.contains(current)) {
+                      const match = semanticSurfacesByElement.get(current);
+                      if (match) return match;
+                      current = current.parentElement;
+                    }
+                    return null;
+                  };
+                  const reportedTextChecks = /* @__PURE__ */ new Set();
+                  const textWalker = document.createTreeWalker(section, NodeFilter.SHOW_TEXT);
+                  let textNode = textWalker.nextNode();
+                  while (textNode) {
+                    if (!textNode.textContent?.trim()) {
+                      textNode = textWalker.nextNode();
+                      continue;
+                    }
+                    const parent = textNode.parentElement;
+                    if (!parent || !visible(parent)) {
+                      textNode = textWalker.nextNode();
+                      continue;
+                    }
+                    const surface = closestSurface(parent);
+                    if (surface) {
+                      const actualForeground = getComputedStyle(parent).color;
+                      const ratio = contrastRatio(surface.surfaceColor, actualForeground);
+                      const key = `${surface.surface}/${actualForeground}`;
+                      if (ratio !== null && ratio < 4.5 && !reportedTextChecks.has(`contrast/${key}`)) {
+                        issues.push({
+                          code: "surface-text-contrast",
+                          message: `Text on ${surface.surface} has ${ratio.toFixed(2)}:1 contrast; 4.5:1 is required.`,
+                          severity: "error"
+                        });
+                        reportedTextChecks.add(`contrast/${key}`);
+                      }
+                      if (actualForeground !== surface.foregroundColor && !reportedTextChecks.has(`foreground/${key}`)) {
+                        issues.push({
+                          code: "surface-foreground-token-mismatch",
+                          message: `Text on ${surface.surface} uses ${actualForeground} instead of ${surface.foreground}; verify the custom foreground remains readable.`,
+                          severity: "warning"
+                        });
+                        reportedTextChecks.add(`foreground/${key}`);
+                      }
+                    }
+                    textNode = textWalker.nextNode();
+                  }
+                  const sectionRect = section.getBoundingClientRect();
+                  if (document.documentElement.scrollWidth > window.innerWidth + 1 || sectionRect.left < -1 || sectionRect.right > window.innerWidth + 1) {
+                    issues.push({
+                      code: "horizontal-overflow",
+                      message: "The page or audited section overflows the viewport horizontally.",
+                      severity: "error"
+                    });
+                  }
+                  const firstText = section.querySelector("h1, h2, h3, p");
+                  if (firstText) {
+                    const textRect = firstText.getBoundingClientRect();
+                    const overlays = Array.from(document.querySelectorAll("body *")).filter(
+                      (element) => {
+                        if (element === section || section.contains(element)) return false;
+                        const style2 = getComputedStyle(element);
+                        if (style2.position !== "fixed" || style2.visibility === "hidden") return false;
+                        const rect = element.getBoundingClientRect();
+                        return rect.bottom > textRect.top && rect.top < textRect.bottom && rect.right > textRect.left && rect.left < textRect.right;
+                      }
+                    );
+                    if (overlays.length > 0) {
+                      issues.push({
+                        code: "layout-overlay",
+                        message: "A fixed layout element overlaps the first section text. Add spacing in the theme layout if this is unintended.",
+                        severity: "warning"
+                      });
+                    }
+                  }
+                  return { issues };
+                });
+                for (const issue of audit.issues) {
+                  report.issues.push({ ...issue, component, device, preset });
+                }
+                for (const message of pageErrors) {
+                  report.issues.push({
+                    component,
+                    code: "page-error",
+                    device,
+                    message,
+                    preset,
+                    severity: "error"
+                  });
+                }
+                const outputPath = path2.join(
+                  resolved.outputDir,
+                  safeObjectKeyPart(preset),
+                  device,
+                  `${safeObjectKeyPart(component)}.png`
+                );
+                await mkdir(path2.dirname(outputPath), { recursive: true });
+                await page.screenshot({ path: outputPath, fullPage: resolved.fullPage });
+                await optimizePngIfAvailable(root, outputPath);
+              } finally {
+                await page.close();
+              }
+            }
+          } finally {
+            await context.close();
+          }
+        }
+      }
+    } finally {
+      await browser.close();
+    }
+  } finally {
+    await handle.close();
+  }
+  await mkdir(resolved.outputDir, { recursive: true });
+  await writeFile(
+    path2.join(resolved.outputDir, "report.json"),
+    `${JSON.stringify(report, null, 2)}
+`
+  );
+  const errors = report.issues.filter((issue) => issue.severity === "error");
+  const warnings = report.issues.filter((issue) => issue.severity === "warning");
+  if (errors.length === 0) {
+    console.log(success(`visual check passed; screenshots: ${style.path(report.outputDir)}`));
+  } else {
+    console.error(error(`visual check failed with ${errors.length} error(s).`));
+  }
+  for (const issue of report.issues) {
+    const formatter = issue.severity === "error" ? error : warning;
+    console.log(
+      `  ${formatter(issue.severity)} ${issue.preset}/${issue.device}/${issue.component}: ${issue.message}`
+    );
+  }
+  if (warnings.length > 0) {
+    console.log(warning(`visual check completed with ${warnings.length} warning(s).`));
+  }
+  return errors.length === 0;
+}
 async function loadLocalAgentManifest(root) {
   const built = await readJsonIfExists(
     path2.join(root, "dist", "agent-manifest.json")
@@ -2910,422 +3345,6 @@ async function createAgentProject(options) {
     })
   });
 }
-function mcpStructured(summary, value) {
-  return {
-    content: [
-      {
-        type: "text",
-        text: summary
-      }
-    ],
-    structuredContent: value
-  };
-}
-async function startMcpServer() {
-  const server = new McpServer({
-    name: "suda",
-    version: "0.1.0"
-  });
-  server.registerTool(
-    "list_projects",
-    {
-      description: "List Suda projects the current CLI user can access. ALWAYS call this first when the user asks to generate or edit a website. Flow: (1) If `projects` is empty, do NOT call this tool again; instead skip directly to gathering inputs and calling create_project (see its description). (2) If `projects` has one or more entries, you MUST ask the user which project to use before any further action \u2014 even if there is only a single project, present it and ask the user to confirm or pick a different one. Never auto-pick a project on the user's behalf.",
-      inputSchema: {},
-      outputSchema: listProjectsOutputSchema.shape
-    },
-    async () => {
-      const structuredContent = listProjectsOutputSchema.parse({
-        projects: await listAgentProjects()
-      });
-      return mcpStructured("Suda projects accessible to the current user.", structuredContent);
-    }
-  );
-  server.registerTool(
-    "create_project",
-    {
-      description: "Create a new Suda project for the current user. Only call this after list_projects returned an empty list. Conversation flow before calling: (1) Ask the user for the website / brand name in one turn and capture it as `name`. (2) Ask the user for a business introduction; the user is allowed (and expected) to answer over multiple turns \u2014 keep asking follow-up questions and accumulating their answers until they confirm they are done, then concatenate the accumulated text into a single `siteDescription` (trimmed). Do not invent details the user did not provide. Do not call this tool until both fields are confirmed by the user. The project is created with the default theme, starter pages, and a default project contact form. After creation, if the business context suggests better contact fields, call get_contact_form_settings, propose the contact form plan to the user, and only call update_contact_form_settings with confirm:true after they agree. No in-app AI site generation is triggered \u2014 drive page content afterwards via create_page_draft using the returned projectId.",
-      inputSchema: {
-        name: createProjectInputSchema.shape.name.describe(
-          "Website or brand name confirmed by the user in a dedicated turn. Used as the project name and site title."
-        ),
-        siteDescription: createProjectInputSchema.shape.siteDescription.describe(
-          "Business introduction the user provided, possibly across multiple turns, then concatenated and trimmed. Captures what the site is about and who it serves. Used to seed default site metadata."
-        )
-      },
-      outputSchema: createProjectOutputSchema.shape
-    },
-    async ({ name, siteDescription }) => {
-      const result = await createAgentProject({ name, siteDescription });
-      const structuredContent = createProjectOutputSchema.parse({
-        projectId: result.projectId,
-        name: result.name,
-        defaultDomain: result.defaultDomain,
-        dashboardUrl: result.dashboardUrl
-      });
-      return mcpStructured("Created Suda project.", structuredContent);
-    }
-  );
-  server.registerTool(
-    "list_themes",
-    {
-      description: "List themes visible to the current Suda CLI user.",
-      inputSchema: {
-        projectId: z.string().optional(),
-        themeRoot: z.string().optional()
-      },
-      outputSchema: {
-        themes: z.array(
-          z.object({
-            key: z.string(),
-            name: z.string(),
-            version: z.string(),
-            description: z.string().nullable().optional(),
-            categories: z.array(z.string()).optional(),
-            preview: z.string().optional(),
-            active: z.boolean().optional()
-          })
-        )
-      }
-    },
-    async ({ projectId, themeRoot }) => {
-      const structuredContent = { themes: await listAgentThemes({ projectId, themeRoot }) };
-      return mcpStructured("Available Suda themes.", structuredContent);
-    }
-  );
-  server.registerTool(
-    "describe_theme",
-    {
-      description: "Return the raw Suda agent manifest for a theme.",
-      inputSchema: {
-        theme: z.string(),
-        version: z.string().optional(),
-        projectId: z.string().optional(),
-        themeRoot: z.string().optional()
-      },
-      outputSchema: {
-        agentManifest: z.unknown()
-      }
-    },
-    async ({ theme, version, projectId, themeRoot }) => {
-      const structuredContent = {
-        agentManifest: await fetchAgentManifest(theme, { version, projectId, themeRoot })
-      };
-      return mcpStructured("Raw Suda theme agent manifest.", structuredContent);
-    }
-  );
-  server.registerTool(
-    "get_page_schema",
-    {
-      description: "Return the schema for configuring existing Suda theme sections as page content. Use only the returned section types, fields, defaultProps, and slot allowedComponents; never create theme source code or new component types. If the theme has a contact section, generate only the section placement/content props; public form fields and delivery integrations are project contact form settings exposed to themes as metadata.contactForm. Use get_contact_form_settings and update_contact_form_settings for user-approved contact form changes.",
-      inputSchema: {
-        theme: z.string(),
-        version: z.string().optional(),
-        projectId: z.string().optional(),
-        themeRoot: z.string().optional(),
-        includeExample: z.boolean().optional()
-      },
-      outputSchema: agentPageSchemaOutputSchema.shape
-    },
-    async ({ theme, version, projectId, themeRoot, includeExample }) => {
-      const manifest = await fetchAgentManifest(theme, { version, projectId, themeRoot });
-      const structuredContent = createSudaPageAgentRuntime(manifest).getPageSchemaOutput({
-        includeExample: includeExample === true
-      });
-      return mcpStructured("Suda page content configuration schema.", structuredContent);
-    }
-  );
-  server.registerTool(
-    "get_section_schema",
-    {
-      description: "Return the schema for configuring one existing section in a theme. Use the returned fields, defaultProps, and slot allowedComponents to set props; do not design or add theme components. For contact sections, use the schema for presentation props only and do not hardcode form field metadata, notification channels, webhook URLs, or recipients into page content. Use contact form tools for project-level contact settings.",
-      inputSchema: {
-        theme: z.string(),
-        section: z.string(),
-        version: z.string().optional(),
-        projectId: z.string().optional(),
-        themeRoot: z.string().optional()
-      },
-      outputSchema: agentComponentOutputSchema.shape
-    },
-    async ({ theme, section, version, projectId, themeRoot }) => {
-      const manifest = await fetchAgentManifest(theme, { version, projectId, themeRoot });
-      const structuredContent = createSectionSchema(manifest, section);
-      return mcpStructured("Suda section configuration schema.", structuredContent);
-    }
-  );
-  server.registerTool(
-    "validate_page_config",
-    {
-      description: "Validate Suda page content JSON against an existing theme schema.",
-      inputSchema: {
-        theme: z.string(),
-        data: z.unknown(),
-        version: z.string().optional(),
-        projectId: z.string().optional(),
-        themeRoot: z.string().optional()
-      },
-      outputSchema: agentValidationResultSchema.shape
-    },
-    async ({ theme, data, version, projectId, themeRoot }) => {
-      const manifest = await fetchAgentManifest(theme, { version, projectId, themeRoot });
-      const structuredContent = agentValidationResultSchema.parse(
-        createSudaPageAgentRuntime(manifest).validatePageContent(data)
-      );
-      return mcpStructured("Suda page content validation result.", structuredContent);
-    }
-  );
-  server.registerTool(
-    "get_contact_form_settings",
-    {
-      description: "Read project contact form settings. Use this before planning contact form changes. The result includes editable field metadata, masked notification/webhook URLs, and plan features/limits. Secrets are never returned.",
-      inputSchema: {
-        projectId: z.string()
-      },
-      outputSchema: contactFormOutputSchema.shape
-    },
-    async ({ projectId }) => {
-      const auth = await requireCliBaseUrl();
-      const structuredContent = contactFormOutputSchema.parse({
-        contactForm: await getRemoteContactForm(auth, projectId)
-      });
-      return mcpStructured("Suda contact form settings.", structuredContent);
-    }
-  );
-  server.registerTool(
-    "update_contact_form_settings",
-    {
-      description: "Plan or update project contact form settings. Use this when the user asks to change contact form fields, labels, validation, notification channels, or webhooks. Supported field types are text, textarea, checkbox, radio, and select. Conversation flow: first call get_contact_form_settings, then propose the exact draft to the user. Call this tool without confirm or with confirm:false to return the impact summary; only call again with confirm:true after the user explicitly agrees. Do not invent webhook URLs, notification recipients, or external delivery secrets. When updating an existing webhook, omit url to keep the stored secret; new webhooks need a user-provided url.",
-      inputSchema: updateContactFormInputSchema.shape,
-      outputSchema: {
-        status: z.enum(["needs_confirmation", "updated"]),
-        projectId: z.string(),
-        impact: z.string().optional(),
-        draft: updateContactFormInputSchema.omit({ confirm: true }).optional(),
-        contactForm: contactFormViewSchema.optional()
-      }
-    },
-    async (input) => {
-      const parsed = updateContactFormInputSchema.parse(input);
-      const auth = await requireCliBaseUrl();
-      const structuredContent = updateContactFormOutputSchema.parse(
-        await performUpdateContactForm(auth, parsed)
-      );
-      return mcpStructured(
-        structuredContent.status === "needs_confirmation" ? "Updating this contact form requires explicit confirmation." : "Updated Suda contact form settings.",
-        structuredContent
-      );
-    }
-  );
-  server.registerTool(
-    "get_theme_settings",
-    {
-      description: 'Read project theme layout root settings. Use this before planning theme style changes. The result includes manifest.designSystem presets, current rootProps, and the layout root schema. To use a preset, set rootProps.designSystem to { presetId }. To fully customize colors/radius, set rootProps.designSystem to { presetId: "custom", tokens: { colors, radius } } using every token from designSystem.',
-      inputSchema: {
-        projectId: z.string()
-      },
-      outputSchema: themeSettingsOutputSchema.shape
-    },
-    async ({ projectId }) => {
-      const auth = await requireCliBaseUrl();
-      const structuredContent = themeSettingsOutputSchema.parse({
-        themeSettings: await getRemoteThemeSettings(auth, projectId)
-      });
-      return mcpStructured("Suda theme settings.", structuredContent);
-    }
-  );
-  server.registerTool(
-    "update_theme_settings",
-    {
-      description: "Plan or update project theme layout root settings. Use this for choosing a designSystem preset or saving custom design tokens for colors and radius. Conversation flow: first call get_theme_settings, then propose the exact rootProps changes to the user. Call this tool without confirm or with confirm:false to return the impact summary; only call again with confirm:true after the user explicitly agrees. Do not create theme source code or introduce a second token system.",
-      inputSchema: updateThemeSettingsInputSchema.shape,
-      outputSchema: {
-        status: z.enum(["needs_confirmation", "updated"]),
-        projectId: z.string(),
-        impact: z.string().optional(),
-        draft: updateThemeSettingsInputSchema.omit({ confirm: true }).optional(),
-        themeSettings: themeSettingsViewSchema.optional()
-      }
-    },
-    async (input) => {
-      const parsed = updateThemeSettingsInputSchema.parse(input);
-      const auth = await requireCliBaseUrl();
-      const structuredContent = updateThemeSettingsOutputSchema.parse(
-        await performUpdateThemeSettings(auth, parsed)
-      );
-      return mcpStructured(
-        structuredContent.status === "needs_confirmation" ? "Updating these theme settings requires explicit confirmation." : "Updated Suda theme settings.",
-        structuredContent
-      );
-    }
-  );
-  server.registerTool(
-    "create_page_draft",
-    {
-      description: "Create a new workspace page draft from Suda page content JSON that configures existing theme sections. When creating a complete website, mark exactly one primary landing page with isHome: true so it becomes the public homepage at `/`. After this tool succeeds, tell the user the page is only a draft, explain that they can review it in the SudaCloud workspace by navigating to Pages, opening the created page, previewing it, then clicking Publish, and ask whether they want you to publish it now. Do not call publish_page until the user explicitly confirms.",
-      inputSchema: {
-        projectId: z.string(),
-        title: z.string(),
-        slug: z.string(),
-        isHome: z.boolean().optional().describe("Set true for exactly one page that should serve as the public homepage at `/`."),
-        theme: z.string(),
-        data: z.unknown(),
-        version: z.string().optional()
-      },
-      outputSchema: createPageDraftOutputSchema
-    },
-    async ({ projectId, title, slug, isHome, theme, data, version }) => {
-      const manifest = await fetchAgentManifest(theme, { version, projectId });
-      const prepared = createSudaPageAgentRuntime(manifest).preparePageData(data);
-      if (!prepared.validation.valid) {
-        return mcpStructured(
-          "Suda page content validation failed. Fix issues before creating a draft.",
-          createPageDraftOutputSchema.parse({
-            status: "invalid",
-            valid: false,
-            issues: prepared.validation.issues
-          })
-        );
-      }
-      const auth = await requireCliBaseUrl();
-      const response = await createRemotePageDraft(auth, {
-        projectId,
-        title,
-        slug,
-        isHome,
-        themeKey: manifest.manifest.key,
-        themeVersion: manifest.manifest.version,
-        data
-      });
-      return mcpStructured(
-        "Created Suda page draft. Tell the user they can review it in the SudaCloud workspace under Pages by opening the created page, previewing it, then clicking Publish. Ask whether they want you to publish it now before calling publish_page.",
-        createPageDraftOutputSchema.parse({ status: "created", ...response })
-      );
-    }
-  );
-  server.registerTool(
-    "update_page_draft",
-    {
-      description: "Update an existing workspace page draft by slug from Suda page content JSON that configures existing theme sections.",
-      inputSchema: {
-        projectId: z.string(),
-        slug: z.string(),
-        theme: z.string(),
-        data: z.unknown(),
-        version: z.string().optional()
-      },
-      outputSchema: updatePageDraftOutputSchema
-    },
-    async ({ projectId, slug, theme, data, version }) => {
-      const manifest = await fetchAgentManifest(theme, { version, projectId });
-      const prepared = createSudaPageAgentRuntime(manifest).preparePageData(data);
-      if (!prepared.validation.valid) {
-        return mcpStructured(
-          "Suda page content validation failed. Fix issues before updating a draft.",
-          updatePageDraftOutputSchema.parse({
-            status: "invalid",
-            valid: false,
-            issues: prepared.validation.issues
-          })
-        );
-      }
-      const auth = await requireCliBaseUrl();
-      const response = await updateRemotePageDraft(auth, {
-        projectId,
-        slug,
-        themeKey: manifest.manifest.key,
-        themeVersion: manifest.manifest.version,
-        data
-      });
-      return mcpStructured(
-        "Updated Suda page draft.",
-        updatePageDraftOutputSchema.parse({ status: "updated", ...response })
-      );
-    }
-  );
-  server.registerTool(
-    "delete_page",
-    {
-      description: "Delete a Suda page by slug. This is destructive: first call without confirm to get the exact project, slug, and impact; only call again with confirm: true after the user explicitly agrees.",
-      inputSchema: {
-        projectId: z.string(),
-        slug: z.string(),
-        confirm: z.boolean().optional()
-      },
-      outputSchema: destructivePageOperationOutputSchema
-    },
-    async ({ projectId, slug, confirm }) => {
-      const auth = await requireCliBaseUrl();
-      const structuredContent = destructivePageOperationOutputSchema.parse(
-        await performConfirmedPageOperation(auth, {
-          operation: "delete",
-          projectId,
-          slug,
-          confirm
-        })
-      );
-      return mcpStructured(
-        structuredContent.status === "needs_confirmation" ? "Deleting this Suda page requires explicit confirmation." : "Deleted Suda page.",
-        structuredContent
-      );
-    }
-  );
-  server.registerTool(
-    "publish_page",
-    {
-      description: "Publish the current saved draft for a Suda page by slug. This affects the public site: first call without confirm to get the exact project, slug, and impact; only call again with confirm: true after the user explicitly agrees. If the user wants to review manually first, tell them to open the SudaCloud workspace, navigate to Pages, open the created page, preview it, then click Publish.",
-      inputSchema: {
-        projectId: z.string(),
-        slug: z.string(),
-        confirm: z.boolean().optional()
-      },
-      outputSchema: destructivePageOperationOutputSchema
-    },
-    async ({ projectId, slug, confirm }) => {
-      const auth = await requireCliBaseUrl();
-      const structuredContent = destructivePageOperationOutputSchema.parse(
-        await performConfirmedPageOperation(auth, {
-          operation: "publish",
-          projectId,
-          slug,
-          confirm
-        })
-      );
-      return mcpStructured(
-        structuredContent.status === "needs_confirmation" ? "Publishing this Suda page requires explicit confirmation." : "Published Suda page.",
-        structuredContent
-      );
-    }
-  );
-  server.registerTool(
-    "activate_theme",
-    {
-      description: "Activate a theme for a Suda project. This affects how public pages render and may seed starter content on first activation: first call without confirm to get the exact project, theme, and impact; only call again with confirm: true after the user explicitly agrees.",
-      inputSchema: {
-        projectId: z.string(),
-        themeKey: z.string(),
-        themeVersion: z.string().optional(),
-        confirm: z.boolean().optional()
-      },
-      outputSchema: activateThemeOutputSchema
-    },
-    async ({ projectId, themeKey, themeVersion, confirm }) => {
-      const auth = await requireCliBaseUrl();
-      const structuredContent = activateThemeOutputSchema.parse(
-        await performActivateTheme(auth, {
-          projectId,
-          themeKey,
-          themeVersion,
-          confirm
-        })
-      );
-      return mcpStructured(
-        structuredContent.status === "needs_confirmation" ? "Activating this Suda theme requires explicit confirmation." : "Activated Suda theme.",
-        structuredContent
-      );
-    }
-  );
-  await server.connect(new StdioServerTransport());
-}
 async function writeThemeArtifacts(theme) {
   const dist = path2.join(theme.root, "dist");
   const agentManifest = createThemeAgentManifest(theme.module);
@@ -3816,6 +3835,24 @@ function buildProgram() {
   ).option("--output <path>", "Output PNG path relative to theme root. Requires exactly one device.").option("--width <px>", "Override viewport width in pixels.").option("--height <px>", "Override viewport height in pixels.").option("--full-page", "Capture the full page instead of the viewport.").option("--port <port>", "Preview server port used during capture.", "4178").action(async (options) => {
     await screenshotTheme(resolveThemeRoot(options), options);
   });
+  theme.command("visual-check").description(
+    "Render every theme page component across presets and viewports, then report token contrast, semantic surface colors, overflow, and layout overlays."
+  ).option("--theme-root <path>", "Theme source/artifact root.").option(
+    "--device <device>",
+    "Device to audit: desktop, tablet, mobile. Repeat or use comma-separated values.",
+    collectOption,
+    []
+  ).option(
+    "--preset <id>",
+    "Design preset to audit. Repeat or use comma-separated values; defaults to every theme preset.",
+    collectOption,
+    []
+  ).option("--output <path>", "Output directory relative to theme root.").option("--full-page", "Capture full-page screenshots instead of viewport screenshots.").option("--port <port>", "Preview server port used during visual checking.", "4179").action(async (options) => {
+    const ok = await runThemeVisualCheck(resolveThemeRoot(options), options);
+    if (!ok) {
+      process.exitCode = 1;
+    }
+  });
   theme.command("publish").description("Upload artifact to S3 and upsert ThemePackage/ThemeVersion.").option("--theme-root <path>", "Theme source/artifact root.").option("--skip-build", "Publish existing dist files without rebuilding.").option("--host <host>", "Publish to this authenticated SudaCloud workspace host.").option(
     "--force",
     "Development recovery only: clear the existing themes/<key>/<version>/ prefix and ThemeVersion row before republishing. Re-published clients pinned to this version are unavailable until the new publish completes."
@@ -3887,9 +3924,6 @@ function buildProgram() {
     const manifest = await fetchAgentManifest(options.theme, options);
     printJson(createSectionSchema(manifest, options.section));
   });
-  program.command("mcp").description("Run the Suda local MCP server over stdio.").action(async () => {
-    await startMcpServer();
-  });
   const hostCmd = program.command("host").description("Manage the current SudaCloud workspace host.");
   hostCmd.command("current").description("Show the current authenticated workspace host.").action(async () => {
     await showCurrentHost();