@sudajs/cli 0.13.3 → 0.14.0

package/dist/index.d.ts

@@ -1702,6 +1702,7 @@ declare function fetchJson<T>(url: string, options?: RequestInit & {
 declare function validateThemeTailwindContract(root: string): Promise<void>;
 declare function validateTheme(root: string): Promise<ValidatedTheme>;
 declare function validateThemeLocales(root: string): Promise<void>;
+declare function validateThemePreviewLocales(root: string, previewLocales: string[] | undefined): Promise<void>;
 declare function toViteModuleUrl(root: string, absolutePath: string): string;
 declare function buildTheme(root: string): Promise<ValidatedTheme>;
 declare function finalizeTheme(root: string): Promise<ValidatedTheme>;
@@ -1728,11 +1729,20 @@ declare const __testUtils: {
     validateThemeName: typeof validateThemeName;
     validateThemeTailwindContract: typeof validateThemeTailwindContract;
     validateThemeLocales: typeof validateThemeLocales;
+    validateThemePreviewLocales: typeof validateThemePreviewLocales;
+    resolveThemePreviewLocale: typeof resolveThemePreviewLocale;
+    withSerializedVitePreviewLocaleLoad: typeof withSerializedVitePreviewLocaleLoad;
     toViteModuleUrl: typeof toViteModuleUrl;
     updateRemotePageDraft: typeof updateRemotePageDraft;
 };
 declare function watchTheme(root: string, port: number): Promise<void>;
+declare function withSerializedVitePreviewLocaleLoad<Result>(server: object, load: () => Promise<Result>): Promise<Result>;
 declare function resolveDevStarterSlug(pathname: string): string | null | undefined;
+declare function resolveThemePreviewLocale(params: {
+    previewLocales: string[] | undefined;
+    explicitLang?: string | null;
+    acceptLanguage?: string;
+}): string;
 /**
  * Theme-project-scoped renderer bundle. We deliberately resolve `react`,
  * `react-dom/server` and `@sudajs/theme-engine/server` through the theme
@@ -1751,7 +1761,7 @@ interface ThemeRenderer {
     renderToString: typeof renderToString;
 }
 declare function loadThemeScopedRenderer(themeRoot: string): Promise<ThemeRenderer>;
-declare function renderDevStarterPageHtml(theme: ValidatedTheme, page: ThemeStarterPage, renderer: ThemeRenderer): string;
+declare function renderDevStarterPageHtml(theme: ValidatedTheme, page: ThemeStarterPage, renderer: ThemeRenderer, locale?: string, preserveLang?: boolean): string;
 interface ScreenshotOptions extends ThemeRootOptions {
     device?: string[] | string;
     output?: string;

package/dist/index.js

@@ -9,7 +9,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { themeDesignSystemSchema, createThemeAgentManifest, createSudaPageAgentRuntime, checkThemeModule, formatThemeCheckResult, agentValidationResultSchema, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
-import { themeManifestSchema } from '@sudajs/theme-engine/server';
+import { themeManifestSchema, runWithThemePreviewLocale } from '@sudajs/theme-engine/server';
 import { Command } from 'commander';
 import { build } from 'esbuild';
 import { z } from 'zod';
@@ -839,6 +839,7 @@ async function validateTheme(root) {
   validateThemeModule(module);
   await validateThemeTailwindContract(root);
   await validateThemeLocales(root);
+  await validateThemePreviewLocales(root, module.manifest.previewLocales);
   const result = {
     root,
     module,
@@ -885,7 +886,16 @@ async function listLocaleFiles(localesDir) {
     return [];
   }
   const entries = await readdir(localesDir, { withFileTypes: true });
-  return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => entry.name).sort((a, b) => a.localeCompare(b));
+  return entries.filter(
+    (entry) => entry.isFile() && entry.name.endsWith(".json") && !entry.name.endsWith(".content.json")
+  ).map((entry) => entry.name).sort((a, b) => a.localeCompare(b));
+}
+async function listPreviewLocaleFiles(localesDir) {
+  if (!await pathExists(localesDir)) {
+    return [];
+  }
+  const entries = await readdir(localesDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".content.json")).map((entry) => entry.name).sort((a, b) => a.localeCompare(b));
 }
 async function validateThemeLocales(root) {
   const localesDir = path2.join(root, "dist", "locales");
@@ -921,6 +931,47 @@ ${details}`
     }
   }
 }
+async function validateThemePreviewLocales(root, previewLocales) {
+  const localesDir = path2.join(root, "dist", "locales");
+  const files = await listPreviewLocaleFiles(localesDir);
+  const declared = previewLocales ?? [];
+  const expectedFiles = new Set(declared.map((locale) => `${locale}.content.json`));
+  const undeclared = files.filter((file) => !expectedFiles.has(file));
+  const missing = [...expectedFiles].filter((file) => !files.includes(file));
+  if (missing.length > 0 || undeclared.length > 0) {
+    const details = [
+      ...missing.map((file) => `  - missing locales/${file}`),
+      ...undeclared.map((file) => `  - undeclared locales/${file}`)
+    ].join("\n");
+    throw new Error(`Theme preview locale files do not match manifest.previewLocales:
+${details}`);
+  }
+  if (declared.length === 0) {
+    return;
+  }
+  const referenceFile = "en.content.json";
+  const referenceMessages = await readLocaleJson(path2.join(localesDir, referenceFile));
+  const referenceKeys = new Set(collectLocaleKeys(referenceMessages).sort());
+  for (const file of files) {
+    if (file === referenceFile) {
+      continue;
+    }
+    const messages = await readLocaleJson(path2.join(localesDir, file));
+    const keys = new Set(collectLocaleKeys(messages).sort());
+    const missingKeys = [...referenceKeys].filter((key) => !keys.has(key));
+    const extraKeys = [...keys].filter((key) => !referenceKeys.has(key));
+    if (missingKeys.length > 0 || extraKeys.length > 0) {
+      const details = [
+        ...missingKeys.map((key) => `  - missing ${key}`),
+        ...extraKeys.map((key) => `  - extra ${key}`)
+      ].join("\n");
+      throw new Error(
+        `Theme preview locale ${file} does not match ${referenceFile} key set:
+${details}`
+      );
+    }
+  }
+}
 var VITE_CONFIG_FILES = [
   "vite.config.ts",
   "vite.config.mts",
@@ -1284,6 +1335,9 @@ var __testUtils = {
   validateThemeName,
   validateThemeTailwindContract,
   validateThemeLocales,
+  validateThemePreviewLocales,
+  resolveThemePreviewLocale,
+  withSerializedVitePreviewLocaleLoad,
   toViteModuleUrl,
   updateRemotePageDraft
 };
@@ -1381,7 +1435,15 @@ function createSudaPreviewVitePlugin(root) {
             return;
           }
           try {
-            const theme = await loadViteDevTheme(root, server);
+            const acceptLanguageHeader = request.headers["accept-language"];
+            const acceptLanguage = Array.isArray(acceptLanguageHeader) ? acceptLanguageHeader.join(",") : acceptLanguageHeader;
+            const explicitLang = url.searchParams.get("lang");
+            const { theme, locale } = await loadLocalizedViteDevTheme(
+              root,
+              server,
+              explicitLang,
+              acceptLanguage
+            );
             const renderer = await loadThemeScopedRenderer(root);
             if (slug === null) {
               const homeSlug = pickStarterSlug(theme);
@@ -1398,7 +1460,13 @@ function createSudaPreviewVitePlugin(root) {
               }
               const html2 = await server.transformIndexHtml(
                 url.pathname,
-                renderDevStarterPageHtml(theme, starter2, renderer)
+                renderDevStarterPageHtml(
+                  theme,
+                  starter2,
+                  renderer,
+                  locale,
+                  canonicalLocale(explicitLang) !== null
+                )
               );
               response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
               response.end(html2);
@@ -1412,7 +1480,13 @@ function createSudaPreviewVitePlugin(root) {
             }
             const html = await server.transformIndexHtml(
               url.pathname,
-              renderDevStarterPageHtml(theme, starter, renderer)
+              renderDevStarterPageHtml(
+                theme,
+                starter,
+                renderer,
+                locale,
+                canonicalLocale(explicitLang) !== null
+              )
             );
             response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
             response.end(html);
@@ -1425,6 +1499,48 @@ function createSudaPreviewVitePlugin(root) {
     }
   };
 }
+async function loadLocalizedViteDevTheme(root, server, explicitLang, acceptLanguage) {
+  return withSerializedVitePreviewLocaleLoad(server, async () => {
+    const baseTheme = await loadViteDevTheme(root, server);
+    const localeParams = {
+      previewLocales: baseTheme.module.manifest.previewLocales,
+      explicitLang
+    };
+    if (acceptLanguage !== void 0) {
+      localeParams.acceptLanguage = acceptLanguage;
+    }
+    const locale = resolveThemePreviewLocale(localeParams);
+    if (!baseTheme.module.manifest.previewLocales) {
+      return { theme: baseTheme, locale };
+    }
+    const messages = await readDevPreviewLocaleMessages(root, locale);
+    server.moduleGraph.invalidateAll();
+    const theme = await runWithThemePreviewLocale(
+      messages,
+      () => loadViteDevTheme(root, server)
+    );
+    return { theme, locale };
+  });
+}
+var vitePreviewLocaleLoadTails = /* @__PURE__ */ new WeakMap();
+async function withSerializedVitePreviewLocaleLoad(server, load) {
+  const previous = vitePreviewLocaleLoadTails.get(server) ?? Promise.resolve();
+  let release;
+  const gate = new Promise((resolve) => {
+    release = resolve;
+  });
+  const tail = previous.then(() => gate);
+  vitePreviewLocaleLoadTails.set(server, tail);
+  await previous;
+  try {
+    return await load();
+  } finally {
+    release();
+    if (vitePreviewLocaleLoadTails.get(server) === tail) {
+      vitePreviewLocaleLoadTails.delete(server);
+    }
+  }
+}
 async function loadViteDevTheme(root, server) {
   const serverEntryPath = await findServerEntry(root);
   const imported = await server.ssrLoadModule(toViteModuleUrl(root, serverEntryPath));
@@ -1461,6 +1577,73 @@ function resolveDevStarterSlug(pathname) {
   }
   return decodeURIComponent(normalized);
 }
+function canonicalLocale(value) {
+  const candidate = value?.trim();
+  if (!candidate || candidate === "*") {
+    return null;
+  }
+  try {
+    return Intl.getCanonicalLocales(candidate)[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+function acceptLanguageLocales(value) {
+  if (!value) {
+    return [];
+  }
+  return value.split(",").map((part, index) => {
+    const [rawLocale, ...parameters] = part.trim().split(";");
+    const locale = canonicalLocale(rawLocale);
+    const qualityParameter = parameters.find((parameter) => parameter.trim().startsWith("q="));
+    const parsedQuality = qualityParameter ? Number.parseFloat(qualityParameter.trim().slice(2)) : 1;
+    const quality = Number.isFinite(parsedQuality) ? parsedQuality : 0;
+    return { locale, quality, index };
+  }).filter(
+    (entry) => Boolean(entry.locale) && entry.quality > 0
+  ).sort((left, right) => right.quality - left.quality || left.index - right.index).map((entry) => entry.locale);
+}
+function localeLookupCandidates(locale) {
+  const candidates = [];
+  let current = locale;
+  while (current) {
+    candidates.push(current);
+    const separator = current.lastIndexOf("-");
+    if (separator < 0) {
+      break;
+    }
+    current = current.slice(0, separator);
+  }
+  return candidates;
+}
+function resolveThemePreviewLocale(params) {
+  const supported = params.previewLocales ?? ["en"];
+  const supportedByNormalized = new Map(
+    supported.map((locale) => [locale.toLowerCase(), locale])
+  );
+  const explicitLocale = canonicalLocale(params.explicitLang);
+  const requestedLocales = explicitLocale ? [explicitLocale] : acceptLanguageLocales(params.acceptLanguage);
+  for (const requested of requestedLocales) {
+    for (const candidate of localeLookupCandidates(requested)) {
+      const supportedLocale = supportedByNormalized.get(candidate.toLowerCase());
+      if (supportedLocale) {
+        return supportedLocale;
+      }
+    }
+    if (explicitLocale) {
+      break;
+    }
+  }
+  return supportedByNormalized.get("en") ?? "en";
+}
+async function readDevPreviewLocaleMessages(root, locale) {
+  const filePath = path2.join(root, "src", "locales", `${locale}.content.json`);
+  const messages = await readLocaleJson(filePath);
+  if (!isRecord(messages)) {
+    throw new Error(`Theme preview 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;");
 }
@@ -1494,7 +1677,7 @@ async function loadThemeScopedRenderer(themeRoot) {
     renderToString: reactDomServerModule.renderToString
   };
 }
-function renderDevStarterPageHtml(theme, page, renderer) {
+function renderDevStarterPageHtml(theme, page, renderer, locale = "en", preserveLang = false) {
   const chrome = renderer.extractLayoutChrome(theme.module.defaultLayout);
   const metadata = {
     resolveAssetUrl: createPreviewAssetResolver(renderer.resolveAssetPath),
@@ -1513,7 +1696,7 @@ function renderDevStarterPageHtml(theme, page, renderer) {
   const customBody = chrome.customBodyCode ?? "";
   return [
     "<!doctype html>",
-    '<html lang="en">',
+    `<html lang="${escapeHtml(locale)}">`,
     "<head>",
     '<meta charset="utf-8" />',
     '<meta name="viewport" content="width=device-width, initial-scale=1" />',
@@ -1524,6 +1707,9 @@ function renderDevStarterPageHtml(theme, page, renderer) {
     `<body${cssVarStyle ? ` style="${cssVarStyle}"` : ""}>`,
     body,
     customBody,
+    ...preserveLang ? [
+      '<script>for(const a of document.querySelectorAll("a[href]")){try{const u=new URL(a.href,location.href);if(u.origin===location.origin){u.searchParams.set("lang",new URL(location.href).searchParams.get("lang"));a.href=u.pathname+u.search+u.hash}}catch{}}</script>'
+    ] : [],
     "</body>",
     "</html>"
   ].join("");