@sudajs/cli 0.13.4 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.13.4",
+  "version": "0.15.0",
   "type": "module",
   "bin": {
     "suda": "./bin/suda.js"
@@ -34,7 +34,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "zod": "^3.24.1",
-    "@sudajs/theme-engine": "5.1.4"
+    "@sudajs/theme-engine": "6.0.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",

package/templates/theme/AGENTS.md

@@ -439,7 +439,8 @@ or AI examples.
 ## Theme contract
 
 - Keep `renderMode: "ssr"` in `src/manifest.ts`.
-- Keep source entries at `src/index.tsx`, `src/runtime.client.ts`, and `src/styles.css`.
+- Keep source entries at `src/index.tsx` and `src/styles.css`. The CLI owns and generates `dist/runtime.client.js`; do not add `src/runtime.client.ts(x)`.
+- If the theme needs browser-only setup, export `clientHooks` from `src/client.ts`. Do not export theme configuration from that file.
 - Export a complete `ThemeModule` from `src/index.tsx`: `manifest`, `pageConfig`, `layoutConfig`, `defaultLayout`, `starterPages`, and `cmsTemplates`.
 - Starter page slugs preview at site-like root routes in `suda theme dev`: `index` is `/index`, `contact-us` is `/contact-us`. Do not use `/pages/...` as a preview route prefix.
 - Keep `pageConfig` focused on page content sections. Keep `layoutConfig` focused on shared site chrome such as root, header, page outlet, and footer.
@@ -597,14 +598,33 @@ other editor-facing configuration string.
 - When adding another locale such as `src/locales/zh-CN.json`, keep its leaf key
   set exactly aligned with `src/locales/en.json`; missing or extra keys fail
   `suda theme validate`, `suda theme check`, `pnpm build`, and publish.
-- The CLI copies `src/locales/*.json` into `dist/locales/` during build. Do not
+- The CLI copies `src/locales/*.json` into `dist/locales/` during build. Files
+  named `<locale>.json` are editor messages; files named
+  `<locale>.content.json` are starter preview content messages. Do not
   edit `dist/locales/` directly.
 - If an installed legacy theme is missing locale files, the editor falls back to
   showing translation keys instead of crashing. New themes must still pass
   locale validation before publishing.
-- Do not put actual page content, starter page copy, default prop values, or
-  public-site text through `t(...)`. Those belong in component props and starter
-  page data so users can edit them.
+- Keep editor `t(...)` out of actual page content, starter page copy, default
+  prop values, and public-site text. Starter preview copy may instead use the
+  separate `t` exported by `src/preview-i18n.ts`; direct strings remain valid
+  and editor-saved values are always plain strings.
+
+## Starter preview content locales
+
+Use `src/preview-i18n.ts` only inside starter page templates for user-visible
+content such as page titles, headings, descriptions, list copy, and button
+labels. Keep URLs, slugs, IDs, component types, and asset paths as direct
+strings. Do not use preview translations in component labels, fields, default
+props, layout configuration, or CMS templates.
+
+- `src/locales/en.content.json` is the required default content locale whenever
+  `manifest.previewLocales` is declared.
+- Add every supported locale to `manifest.previewLocales`, including `en`, and
+  create the matching `src/locales/<locale>.content.json` file.
+- Every content locale file must have exactly the same string leaf keys as
+  `en.content.json`; undeclared, missing, extra, or partial locale files fail
+  validation and publishing.
 
 Example:
 

package/templates/theme/README.md

@@ -19,11 +19,11 @@ pnpm build
 pnpm validate
 ```
 
-`pnpm dev` starts the Vite-powered preview. `pnpm build` produces the Suda artifact contract in `dist/`, including `dist/index.js`, `dist/runtime.client.js`, `dist/manifest.json`, and `dist/styles.css`. Published artifact paths omit the local `dist/` prefix.
+`pnpm dev` starts the Vite-powered preview. `pnpm build` produces the Suda artifact contract in `dist/`, including the CLI-owned `dist/runtime.client.js`, `dist/index.js`, `dist/manifest.json`, and `dist/styles.css`. Published artifact paths omit the local `dist/` prefix. Do not add `src/runtime.client.ts(x)`; optional browser setup belongs in a `clientHooks` export from `src/client.ts`.
 
 Theme-local assets live in top-level `assets/`. The starter hero exposes a Logo field that defaults to `assets/brand/suda-logo.svg`, so you can replace it with your own brand image or choose a different image in the editor.
 
-Editor labels are localized through `src/i18n.ts` and `src/locales/*.json`. Use `t("...")` for component labels, field labels, and option labels, then add matching string leaves to `src/locales/en.json`. `en.json` is required, and any additional locale file must have the same leaf key set. `pnpm validate`, `suda theme check`, and `pnpm build` verify the locale contract.
+Editor labels are localized through `src/i18n.ts` and `src/locales/<locale>.json`. Starter preview content uses the separate `src/preview-i18n.ts` helper and `src/locales/<locale>.content.json`. Keep `previewLocales` in the manifest aligned with the content locale files. `pnpm validate`, `suda theme check`, and `pnpm build` verify both locale contracts.
 
 Preview screenshots are required before publishing:
 

package/templates/theme/src/locales/en.content.json

@@ -0,0 +1,94 @@
+{
+  "pages": {
+    "index": {
+      "title": "Home",
+      "hero": {
+        "eyebrow": "Starter page",
+        "title": "Welcome to __SUDA_THEME_KEY__",
+        "description": "This page was generated by suda theme init.",
+        "primaryLabel": "Explore features"
+      },
+      "features": {
+        "title": "Designed for editable sites",
+        "description": "Starter sections show agents and editors how this theme is structured.",
+        "items": {
+          "typedFields": {
+            "title": "Typed fields",
+            "description": "Each section exposes a clear field schema."
+          },
+          "starterPages": {
+            "title": "Starter pages",
+            "description": "Templates show realistic section composition."
+          },
+          "cliWorkflow": {
+            "title": "CLI workflow",
+            "description": "Build, validate, preview, and publish from one tool."
+          }
+        }
+      },
+      "featuredPosts": {
+        "title": "Featured posts",
+        "description": "Use CMS posts to keep the homepage fresh without manual card editing."
+      },
+      "callToAction": {
+        "title": "Launch your first page",
+        "description": "Customize this starter template or let an agent generate a new draft.",
+        "buttonLabel": "Get in touch"
+      }
+    },
+    "services": {
+      "title": "Services",
+      "hero": {
+        "eyebrow": "Services",
+        "title": "Show what you offer",
+        "description": "Use this page to explain core services, packages, or capabilities.",
+        "primaryLabel": "Contact us"
+      },
+      "features": {
+        "title": "Service highlights",
+        "description": "Replace these cards with the most important ways you help customers."
+      }
+    },
+    "team": {
+      "title": "Team",
+      "hero": {
+        "eyebrow": "Team",
+        "title": "Introduce the people behind the work",
+        "description": "Share experience, roles, and the human story behind the project.",
+        "primaryLabel": "Work with us"
+      },
+      "testimonial": {
+        "quote": "Use this block for a founder note, client quote, or team philosophy.",
+        "author": "Team lead",
+        "role": "Founder"
+      }
+    },
+    "about": {
+      "title": "About",
+      "hero": {
+        "eyebrow": "About",
+        "title": "A clean starting point for your story",
+        "description": "Use this page to introduce the project, audience, and promise.",
+        "primaryLabel": "Contact us"
+      },
+      "testimonial": {
+        "quote": "This starter theme keeps the editable surface focused and predictable.",
+        "role": "Theme team"
+      }
+    },
+    "contact": {
+      "title": "Contact",
+      "hero": {
+        "eyebrow": "Contact",
+        "title": "Let's talk",
+        "description": "Tell visitors how to reach you and what happens next.",
+        "primaryLabel": "Email us"
+      },
+      "callToAction": {
+        "title": "Start the conversation",
+        "description": "Replace this copy with your preferred contact details or form link.",
+        "buttonLabel": "Send an email"
+      }
+    }
+  }
+}

package/templates/theme/src/locales/zh-CN.content.json

@@ -0,0 +1,94 @@
+{
+  "pages": {
+    "index": {
+      "title": "首页",
+      "hero": {
+        "eyebrow": "起始页面",
+        "title": "欢迎使用 __SUDA_THEME_KEY__",
+        "description": "此页面由 suda theme init 生成。",
+        "primaryLabel": "探索功能"
+      },
+      "features": {
+        "title": "为可视化编辑的网站而设计",
+        "description": "起始区块帮助智能体和编辑者理解主题结构。",
+        "items": {
+          "typedFields": {
+            "title": "类型化字段",
+            "description": "每个区块都提供清晰的字段结构。"
+          },
+          "starterPages": {
+            "title": "起始页面",
+            "description": "模板展示真实可用的区块组合。"
+          },
+          "cliWorkflow": {
+            "title": "CLI 工作流",
+            "description": "通过一个工具完成构建、校验、预览和发布。"
+          }
+        }
+      },
+      "featuredPosts": {
+        "title": "精选文章",
+        "description": "使用 CMS 文章持续更新首页，无需手动维护卡片。"
+      },
+      "callToAction": {
+        "title": "创建你的第一个页面",
+        "description": "自定义此起始模板，或让智能体生成新的草稿。",
+        "buttonLabel": "联系我们"
+      }
+    },
+    "services": {
+      "title": "服务",
+      "hero": {
+        "eyebrow": "服务",
+        "title": "展示你提供的服务",
+        "description": "使用此页面介绍核心服务、套餐或能力。",
+        "primaryLabel": "联系我们"
+      },
+      "features": {
+        "title": "服务亮点",
+        "description": "将这些卡片替换为你帮助客户的关键方式。"
+      }
+    },
+    "team": {
+      "title": "团队",
+      "hero": {
+        "eyebrow": "团队",
+        "title": "介绍工作背后的成员",
+        "description": "分享经验、角色以及项目背后的团队故事。",
+        "primaryLabel": "与我们合作"
+      },
+      "testimonial": {
+        "quote": "使用此区块展示创始人寄语、客户评价或团队理念。",
+        "author": "团队负责人",
+        "role": "创始人"
+      }
+    },
+    "about": {
+      "title": "关于我们",
+      "hero": {
+        "eyebrow": "关于我们",
+        "title": "从这里开始讲述你的故事",
+        "description": "使用此页面介绍项目、受众与品牌承诺。",
+        "primaryLabel": "联系我们"
+      },
+      "testimonial": {
+        "quote": "这个起始主题让可编辑内容保持聚焦且可预测。",
+        "role": "主题团队"
+      }
+    },
+    "contact": {
+      "title": "联系",
+      "hero": {
+        "eyebrow": "联系",
+        "title": "欢迎交流",
+        "description": "告诉访客如何联系你，以及接下来会发生什么。",
+        "primaryLabel": "发送邮件"
+      },
+      "callToAction": {
+        "title": "开始沟通",
+        "description": "将此文案替换为你偏好的联系方式或表单链接。",
+        "buttonLabel": "发送邮件"
+      }
+    }
+  }
+}

package/templates/theme/src/manifest.ts

@@ -7,6 +7,7 @@ import type { ThemeSourceManifest } from "@sudajs/theme-engine";
 export const sourceManifest: ThemeSourceManifest = {
   key: "__SUDA_THEME_KEY__",
   name: "__SUDA_THEME_KEY__",
+  previewLocales: ["en", "zh-CN"],
   categories: ["other"],
   minEngineVersion: "4.0.0",
   designSystem: {
@@ -58,7 +59,6 @@ export const sourceManifest: ThemeSourceManifest = {
     ],
   },
   entry: "index.js",
-  clientEntry: "runtime.client.js",
   // Required. SudaCloud currently hosts SSR themes only; CSR/Hybrid postures
   // are on the roadmap. Authoring `renderMode` is the contract a theme uses
   // to declare which posture it expects from the host.

package/templates/theme/src/preview-i18n.ts

@@ -0,0 +1,13 @@
+import { createThemePreviewTranslate } from "@sudajs/theme-engine/runtime";
+
+import en from "./locales/en.content.json" with { type: "json" };
+
+type DotPath<T, Prefix extends string = ""> = T extends string
+  ? Prefix
+  : {
+      [Key in keyof T & string]: DotPath<T[Key], Prefix extends "" ? Key : `${Prefix}.${Key}`>;
+    }[keyof T & string];
+
+export type PreviewMessageKeys = DotPath<typeof en>;
+
+export const t = createThemePreviewTranslate<PreviewMessageKeys>(en);

package/templates/theme/src/templates.ts

@@ -1,11 +1,12 @@
 import type { ThemeCmsTemplates, ThemeStarterPage } from "@sudajs/theme-engine";
 
+import { t } from "./preview-i18n.js";
 import { themeAsset } from "./theme-asset.js";
 
 export const starterPages: ThemeStarterPage[] = [
   {
     slug: "index",
-    title: "Home",
+    title: t("pages.index.title"),
     isHome: true,
     data: {
       root: { props: {} },
@@ -15,10 +16,10 @@ export const starterPages: ThemeStarterPage[] = [
           props: {
             id: "Hero-1",
             logo: themeAsset("assets/brand/suda-logo.svg"),
-            eyebrow: "Starter page",
-            title: "Welcome to __SUDA_THEME_KEY__",
-            description: "This page was generated by suda theme init.",
-            primaryLabel: "Explore features",
+            eyebrow: t("pages.index.hero.eyebrow"),
+            title: t("pages.index.hero.title"),
+            description: t("pages.index.hero.description"),
+            primaryLabel: t("pages.index.hero.primaryLabel"),
             primaryHref: "#features",
           },
         },
@@ -26,12 +27,21 @@ export const starterPages: ThemeStarterPage[] = [
           type: "FeatureGrid",
           props: {
             id: "FeatureGrid-1",
-            title: "Designed for editable sites",
-            description: "Starter sections show agents and editors how this theme is structured.",
+            title: t("pages.index.features.title"),
+            description: t("pages.index.features.description"),
             features: [
-              { title: "Typed fields", description: "Each section exposes a clear field schema." },
-              { title: "Starter pages", description: "Templates show realistic section composition." },
-              { title: "CLI workflow", description: "Build, validate, preview, and publish from one tool." },
+              {
+                title: t("pages.index.features.items.typedFields.title"),
+                description: t("pages.index.features.items.typedFields.description"),
+              },
+              {
+                title: t("pages.index.features.items.starterPages.title"),
+                description: t("pages.index.features.items.starterPages.description"),
+              },
+              {
+                title: t("pages.index.features.items.cliWorkflow.title"),
+                description: t("pages.index.features.items.cliWorkflow.description"),
+              },
             ],
           },
         },
@@ -39,8 +49,8 @@ export const starterPages: ThemeStarterPage[] = [
           type: "FeaturedPosts",
           props: {
             id: "FeaturedPosts-1",
-            title: "Featured posts",
-            description: "Use CMS posts to keep the homepage fresh without manual card editing.",
+            title: t("pages.index.featuredPosts.title"),
+            description: t("pages.index.featuredPosts.description"),
             postList: { strategy: "featured", limit: 3 },
           },
         },
@@ -48,9 +58,9 @@ export const starterPages: ThemeStarterPage[] = [
           type: "CallToAction",
           props: {
             id: "CallToAction-1",
-            title: "Launch your first page",
-            description: "Customize this starter template or let an agent generate a new draft.",
-            buttonLabel: "Get in touch",
+            title: t("pages.index.callToAction.title"),
+            description: t("pages.index.callToAction.description"),
+            buttonLabel: t("pages.index.callToAction.buttonLabel"),
             buttonHref: "/contact-us",
           },
         },
@@ -59,7 +69,7 @@ export const starterPages: ThemeStarterPage[] = [
   },
   {
     slug: "services",
-    title: "Services",
+    title: t("pages.services.title"),
     data: {
       root: { props: {} },
       content: [
@@ -67,10 +77,10 @@ export const starterPages: ThemeStarterPage[] = [
           type: "Hero",
           props: {
             id: "Hero-Services",
-            eyebrow: "Services",
-            title: "Show what you offer",
-            description: "Use this page to explain core services, packages, or capabilities.",
-            primaryLabel: "Contact us",
+            eyebrow: t("pages.services.hero.eyebrow"),
+            title: t("pages.services.hero.title"),
+            description: t("pages.services.hero.description"),
+            primaryLabel: t("pages.services.hero.primaryLabel"),
             primaryHref: "/contact-us",
           },
         },
@@ -78,8 +88,8 @@ export const starterPages: ThemeStarterPage[] = [
           type: "FeatureGrid",
           props: {
             id: "FeatureGrid-Services",
-            title: "Service highlights",
-            description: "Replace these cards with the most important ways you help customers.",
+            title: t("pages.services.features.title"),
+            description: t("pages.services.features.description"),
           },
         },
       ],
@@ -87,7 +97,7 @@ export const starterPages: ThemeStarterPage[] = [
   },
   {
     slug: "team",
-    title: "Team",
+    title: t("pages.team.title"),
     data: {
       root: { props: {} },
       content: [
@@ -95,10 +105,10 @@ export const starterPages: ThemeStarterPage[] = [
           type: "Hero",
           props: {
             id: "Hero-Team",
-            eyebrow: "Team",
-            title: "Introduce the people behind the work",
-            description: "Share experience, roles, and the human story behind the project.",
-            primaryLabel: "Work with us",
+            eyebrow: t("pages.team.hero.eyebrow"),
+            title: t("pages.team.hero.title"),
+            description: t("pages.team.hero.description"),
+            primaryLabel: t("pages.team.hero.primaryLabel"),
             primaryHref: "/contact-us",
           },
         },
@@ -106,9 +116,9 @@ export const starterPages: ThemeStarterPage[] = [
           type: "Testimonial",
           props: {
             id: "Testimonial-Team",
-            quote: "Use this block for a founder note, client quote, or team philosophy.",
-            author: "Team lead",
-            role: "Founder",
+            quote: t("pages.team.testimonial.quote"),
+            author: t("pages.team.testimonial.author"),
+            role: t("pages.team.testimonial.role"),
           },
         },
       ],
@@ -116,7 +126,7 @@ export const starterPages: ThemeStarterPage[] = [
   },
   {
     slug: "about-us",
-    title: "About",
+    title: t("pages.about.title"),
     data: {
       root: { props: {} },
       content: [
@@ -124,10 +134,10 @@ export const starterPages: ThemeStarterPage[] = [
           type: "Hero",
           props: {
             id: "Hero-About",
-            eyebrow: "About",
-            title: "A clean starting point for your story",
-            description: "Use this page to introduce the project, audience, and promise.",
-            primaryLabel: "Contact us",
+            eyebrow: t("pages.about.hero.eyebrow"),
+            title: t("pages.about.hero.title"),
+            description: t("pages.about.hero.description"),
+            primaryLabel: t("pages.about.hero.primaryLabel"),
             primaryHref: "/contact-us",
           },
         },
@@ -135,9 +145,9 @@ export const starterPages: ThemeStarterPage[] = [
           type: "Testimonial",
           props: {
             id: "Testimonial-About",
-            quote: "This starter theme keeps the editable surface focused and predictable.",
+            quote: t("pages.about.testimonial.quote"),
             author: "SudaCloud",
-            role: "Theme team",
+            role: t("pages.about.testimonial.role"),
           },
         },
       ],
@@ -145,7 +155,7 @@ export const starterPages: ThemeStarterPage[] = [
   },
   {
     slug: "contact-us",
-    title: "Contact",
+    title: t("pages.contact.title"),
     data: {
       root: { props: {} },
       content: [
@@ -153,10 +163,10 @@ export const starterPages: ThemeStarterPage[] = [
           type: "Hero",
           props: {
             id: "Hero-Contact",
-            eyebrow: "Contact",
-            title: "Let's talk",
-            description: "Tell visitors how to reach you and what happens next.",
-            primaryLabel: "Email us",
+            eyebrow: t("pages.contact.hero.eyebrow"),
+            title: t("pages.contact.hero.title"),
+            description: t("pages.contact.hero.description"),
+            primaryLabel: t("pages.contact.hero.primaryLabel"),
             primaryHref: "mailto:hello@example.com",
           },
         },
@@ -164,9 +174,9 @@ export const starterPages: ThemeStarterPage[] = [
           type: "CallToAction",
           props: {
             id: "CallToAction-Contact",
-            title: "Start the conversation",
-            description: "Replace this copy with your preferred contact details or form link.",
-            buttonLabel: "Send an email",
+            title: t("pages.contact.callToAction.title"),
+            description: t("pages.contact.callToAction.description"),
+            buttonLabel: t("pages.contact.callToAction.buttonLabel"),
             buttonHref: "mailto:hello@example.com",
           },
         },

package/templates/theme/src/runtime.client.ts

@@ -1,5 +0,0 @@
-"use client";
-
-import theme from "./index.js";
-
-export default theme;