@sudajs/cli 0.12.1 → 0.12.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "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": "4.0.0"
+    "@sudajs/theme-engine": "4.0.2"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",

package/templates/theme/AGENTS.md

@@ -4,6 +4,47 @@ This directory is a standalone Vite + React + Tailwind Suda theme generated by `
 
 Your job in a theme project is to create a complete, publishable theme with theme-specific components, realistic starter pages, scoped styling, assets, and AI metadata. Do not build pages by assembling generic engine components; those are reserved for end users who need supplemental editing blocks after the theme is installed.
 
+## Component naming and editor organization
+
+Use the clean Puck Cloud component naming style as a reference for
+editor-facing section names and public component keys. Do not copy its component
+list 1:1; learn the style: names should be short, concrete, and easy to infer
+from the editor without opening the component.
+
+- Group components by page role when `pageConfig.categories` is used. Category
+  `title` values must use `t(...)`, the same as component and field labels.
+  Keep the translated text short and task-oriented, such as `Introduction`,
+  `Content`, `Social Proof`, `Business`, `CMS`, and `Layout`, ordered roughly
+  by where those sections appear in a page.
+- Name components with concise PascalCase nouns that describe the visitor-facing
+  pattern. For example, `ArticleCard` should clearly suggest an article preview
+  card, `FeatureCards` should suggest a group of feature cards, and `ContactUs`
+  should suggest a contact section. Use names that fit the theme's actual
+  sections rather than forcing a fixed list.
+- Avoid theme names, implementation details, and filler suffixes such as
+  `Section`, `Component`, `Block`, `New`, or `Custom` unless the word is part
+  of the public pattern users recognize.
+- When a theme needs multiple components with the same broad purpose, prefer a
+  friendly semantic variant name that tells editors what is different at a
+  glance. Use the content, media, layout, density, or page job as the
+  differentiator, such as `HeroImage`, `HeroVideo`, `MediaHero`,
+  `FeatureCards`, `FeatureList`, `PricingTable`, `PricingCards`,
+  `TestimonialsCarousel`, or `TestimonialsGrid`.
+- Use numbered variants only as a fallback when the variants genuinely share
+  the same purpose and no concise semantic name would make the difference
+  clearer. In that case keep the base name and append a numbered variant to the
+  public key and editor label, for example `FeatureCards-1`,
+  `FeatureCards-2`, `Hero-1`, `Hero-2`, `Cta-1`, or `Cta-2`. Treat `-1` as the
+  primary or most generally useful option, and use later numbers for variants
+  with a clearly different visual rhythm, content density, or business
+  emphasis.
+- Explain the difference between semantic or numbered variants in
+  `ai.instructions` and placement guidance so AI chooses the right one instead
+  of treating them as interchangeable duplicates.
+- Keep instance ids separate from component type names. `content[].type` must
+  match the public component key, while `content[].props.id` remains a stable
+  unique instance id for that concrete page item.
+
 ## Theme-building workflow
 
 When you add or change a section, complete the whole theme authoring loop in
@@ -357,7 +398,7 @@ Theme editor labels are localized by the host editor. Use the template's
 other editor-facing configuration string.
 
 - Import `t` from `./i18n.js` in files that define `pageConfig`, `layoutConfig`,
-  fields, options, or local blocks.
+  categories, fields, options, or local blocks.
 - Write labels as stable dot-path keys, for example
   `label: t("sections.hero.fields.title")`, not hardcoded strings.
 - Add every key used with `t(...)` to `src/locales/en.json`. This file is the
@@ -429,10 +470,12 @@ radius, shadows, or spacing.
   `mutedForeground`) and the radius tokens the CSS consumes (`card`, `button`,
   `input`). Do not invent platform-facing token keys without checking the
   generated types first.
-- Expose the design system at the layout root only:
-  `designSystem: designSystemField(t("common.fields.designSystem"),
-  sourceManifest.designSystem)`, with
-  `createThemeDesignDefault(sourceManifest.designSystem)` in `ROOT_DEFAULTS`.
+- Expose the design system at the layout root only, for example:
+  ```ts
+  designSystem: designSystemField(t("common.fields.designSystem"), sourceManifest.designSystem);
+  ```
+  Use `createThemeDesignDefault(sourceManifest.designSystem)` in
+  `ROOT_DEFAULTS`.
 - In the root render, resolve the value once with
   `resolveThemeDesignTokens(sourceManifest.designSystem, props.designSystem)`
   and apply `createThemeDesignCssVariables(tokens)` to the theme root element.

package/templates/theme/src/config.ts

@@ -1,10 +1,17 @@
 import type { LayoutData, SudaConfig } from "@sudajs/theme-engine";
 
+import { t } from "./i18n.js";
 import { LAYOUT_COMPONENTS, rootConfig } from "./layout.js";
 import { SECTION_COMPONENTS } from "./sections.js";
 
 export const pageConfig: SudaConfig = {
   components: SECTION_COMPONENTS,
+  categories: {
+    sections: {
+      title: t("common.categories.sections"),
+      components: ["Hero", "FeatureGrid", "FeaturedPosts", "Testimonial", "CallToAction"],
+    },
+  },
 };
 
 export const layoutConfig: SudaConfig = {

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

@@ -1,4 +1,9 @@
 {
+  "common": {
+    "categories": {
+      "sections": "Sections"
+    }
+  },
   "layout": {
     "root": {
       "fields": {