@sudajs/cli 0.12.2 → 0.12.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "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.1"
+    "@sudajs/theme-engine": "5.0.0"
   },
   "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
@@ -98,7 +139,7 @@ Field source of truth:
   generation reliable.
 - Use `description`, `placeholder`, and `visibleIf` only when they help the
   editor or AI choose the right value.
-- Suda extended field types are `url`, `icon`, `font`, `menu`, `color`,
+- Suda extended field types are `url`, `icon`, `color`,
   `range`, `spacing`, `media`, `image`, `video`, and `posts`. These are valid
   in `fields` and are normalized by `@sudajs/theme-engine`.
 
@@ -148,8 +189,6 @@ fields: {
   download: { type: "media", kind: "file", label: t("common.fields.file") },
   icon: { type: "icon", label: t("common.fields.icon") },
   accentColor: { type: "color", label: t("common.fields.color") },
-  font: { type: "font", label: t("common.fields.font") },
-  links: { type: "menu", label: t("common.fields.menu") },
   spacing: { type: "spacing", label: t("common.fields.spacing") },
 
   // Dynamic post lists. Use this only on page sections that intentionally
@@ -357,7 +396,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 +468,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.
@@ -449,11 +490,11 @@ radius, shadows, or spacing.
 - Section props may expose semantic choices such as `tone`, `variant`,
   `columns`, `mediaPosition`, `showImage`, or `spacing`. Map those choices to
   the existing design tokens and shared CSS classes.
-- Do not add raw `color`, `font`, `spacing`, `radius`, or `shadow` fields to a
+- Do not add raw `color`, typography, `spacing`, `radius`, or `shadow` fields to a
   section just because the CSS has a value. Expose a design token field only
   when the user should intentionally customize that value per component
   instance. Otherwise, keep the value in the theme CSS.
-- Use `color`, `font`, and `spacing` field types only for real editor-facing
+- Use `color` and `spacing` field types only for real editor-facing
   design controls. Use `select`/`radio` for named variants that are already
   part of the theme design system.
 - Local blocks inside `blockSlots` inherit the host section's design system.
@@ -491,10 +532,11 @@ Use the most specific field type available. A generic `text` field may pass type
 
 - Always use `url` for links and routes, including anchors, `mailto:` links, and external URLs. Do not use `text` for href-like props.
 - Use `image` for images, `video` for videos, and `media` only when the same prop intentionally accepts mixed media.
-- Use `color` for color values, `icon` for icon names, `font` for font selections, `range` for bounded numbers, `spacing` for spacing tokens, and `menu` for navigation items.
+- Use `color` for color values, `icon` for icon names, `range` for bounded numbers, and `spacing` for spacing tokens.
+- Use `select` for typography choices and `array`/`object` fields for navigation lists.
 - Use `select` or `radio` for fixed choices. Keep option values stable, short, and serializable.
 - Use `array` for repeatable items and `object` for grouped settings. Keep nested field names aligned with the prop shape and `defaultProps`.
-- Use `textarea` for multi-sentence copy. Use `text` only for short labels, headings, slugs, names, or plain strings that are not URLs, media, colors, icons, fonts, or menus.
+- Use `textarea` for multi-sentence copy. Use `text` only for short labels, headings, slugs, names, or plain strings that are not URLs, media, colors, icons, typography choices, or navigation lists.
 - Use `t(...)` for every editor-facing `label` in components, fields, nested
   `arrayFields` / `object.fields`, local blocks, and option lists. Add matching
   keys to `src/locales/en.json` at the same time.

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": {