@sudajs/cli 0.9.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "type": "module",
   "bin": {
     "suda": "./bin/suda.js"
@@ -32,7 +32,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "zod": "^3.24.1",
-    "@sudajs/theme-engine": "2.3.0"
+    "@sudajs/theme-engine": "2.3.1"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",

package/templates/theme/AGENTS.md

@@ -2,57 +2,81 @@
 
 This directory is a standalone Vite + React + Tailwind Suda theme generated by `suda theme init`.
 
-## Contract
+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.
+
+## Theme contract
 
 - Keep `renderMode: "ssr"` in `src/manifest.ts`.
 - Keep source entries at `src/index.tsx`, `src/runtime.client.ts`, and `src/styles.css`.
+- Export a complete `ThemeModule` from `src/index.tsx`: `manifest`, `pageConfig`, `layoutConfig`, `defaultLayout`, and `starterPages`.
+- Keep `pageConfig` focused on page content sections. Keep `layoutConfig` focused on shared site chrome such as root, header, page outlet, and footer.
 - Do not edit generated files under `dist/`; run `pnpm build` to regenerate them.
 - React, React DOM, Puck, and `@sudajs/theme-engine` are host-provided peers. Do not bundle private copies into the theme runtime.
+- Keep persisted props JSON-serializable. Do not store functions, React nodes, class instances, database ids for media, or environment-specific absolute filesystem paths.
+
+## Component strategy
+
+- Create theme-specific components and sections first. Every page component should express this theme's brand, industry, visual rhythm, and content model.
+- Do not register `createEngineComponents()`, `createBaseBlocks()`, or `createContainers()` in `pageConfig.components` when creating a theme. Generic engine components are fallback editing tools for users, not the foundation of a theme template.
+- Prefer purpose-built sections such as hero, services, product highlights, feature comparisons, gallery, process, pricing, testimonial, FAQ, article list, contact, and CTA when the theme needs those patterns.
+- Keep section APIs semantic. Expose props that describe content and editor decisions, not implementation details.
+- Keep `fields`, `defaultProps`, and `render` in sync. Every editor field should have a sensible default, and render functions should tolerate omitted optional values.
+- Put editor controls in props when they change rendering, for example `showLogo`, `mediaPosition`, `tone`, or `columns`; pair dependent controls with `visibleIf` rather than hiding logic only in JSX.
+
+## Layout and slot rules
+
+- Page-level sections and components must not declare native Puck `slot` fields. Do not write `fields: { content: { type: "slot" } }` in page components.
+- Native Puck slots are reserved for Suda-provided layout/container primitives and theme layout components. The normal template pattern is the one in `src/layout.tsx`: `rootConfig` renders `children`, `PageOutlet` renders `getPageSlot(puck?.metadata)`, and `Header` / `Footer` surround that outlet in `defaultLayout`.
+- Do not add arbitrary nested page composition through native slots. It makes AI-generated pages unpredictable and hard to validate.
+- If a page section needs controlled nested content, use Suda `blockSlots`, not a hand-written Puck slot field. `blockSlots` lets the theme define exactly which local block kinds are allowed inside that section.
+- Do not use legacy DropZone or `zones` patterns.
 
-## Styling
+## Styling and assets
 
 - Tailwind v4 starts in `src/styles.css` with `@import "tailwindcss";` and `@source "./**/*.{ts,tsx}";`.
-- Theme-local assets live in top-level `assets/`; the CLI copies them to `dist/assets/` during build. Use `themeAsset("assets/...")` instead of importing images from React code.
+- Theme-local assets live in top-level `assets/`; the CLI copies them to `dist/assets/` during build.
+- Use `themeAsset("assets/...")` for theme-bundled assets in default props and starter pages. Do not import images from React code.
+- Use `resolveAsset(puck?.metadata, value)` from `@sudajs/theme-engine/runtime` before rendering user-selected media fields.
+- Scope theme CSS with the generated theme key classes. Avoid global resets that could affect the host editor or other themes.
 - Preview screenshots are required at `assets/preview/desktop.png`, `assets/preview/tablet.png`, and `assets/preview/mobile.png`; run `suda theme capture` to generate them.
-- Customize `vite.config.ts`, `postcss.config.mjs`, and `src/styles.css` as needed.
+- Customize `vite.config.ts`, `postcss.config.mjs`, and `src/styles.css` only when the theme needs it.
 
-## Commands
+## Field authoring rules
 
-```bash
-pnpm install
-pnpm lint
-pnpm typecheck
-pnpm format
-pnpm dev       # Vite-powered local preview
-pnpm build     # Vite build + Suda artifact finalize + AI metadata check
-pnpm validate
-suda theme check
-```
+Use the most specific field type available. A generic `text` field may pass typecheck, but it is wrong when a semantic Suda field exists.
+
+- 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 `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.
+- For card grids, feature lists, pricing tables, logo walls, gallery grids, and any multi-column component, expose a `columns` prop with a `range` or `select` field and a sensible default.
+- Use `visibleIf: ({ props }, { fields }) => boolean` for synchronous field visibility that depends on sibling props or resolved fields. Keep it pure and fast.
+- Use Puck `resolveFields` only for heavier dynamic field changes that cannot be expressed with `visibleIf`.
+- Add field-level `ai.instructions`, `ai.required`, `ai.exclude`, `ai.stream`, or `ai.bind` when a prop needs generation guidance beyond its label and type. Use `ai.stream: false` for atomic values such as URLs that should not stream partially.
 
 ## AI metadata
 
-Every component and layout component should declare useful `ai.instructions`. Missing component-level instructions fail `suda theme check` and block publish.
+Every page component and layout component must declare useful `ai.instructions`. Missing component-level instructions fail `suda theme check` and block publish.
 
-Use `visibleIf: ({ props }, { fields }) => boolean` for synchronous field visibility that depends on sibling props or resolved fields. Keep it pure and fast; use Puck `resolveFields` directly for heavier dynamic field changes. AI and MCP schemas expose `visibleIf` fields as dynamic visibility so agents know the editor surface can change with props.
+Good component instructions explain:
 
-## Field authoring rules
+- Purpose: what content or business role the component serves.
+- Use when / avoid when: how AI should choose this component instead of a similar one.
+- Placement: where it normally belongs in a page.
+- Frequency: whether it should appear once, multiple times, or only near another section.
+- Composition: required neighboring content or local blocks, when relevant.
 
-- Prefer Suda field helpers over generic text fields: use `url` for links and routes, `image` for images, `video` for videos, `media` for mixed media, `color` for colors, `icon` for icon names, `font` for font selections, `range` for bounded numbers, `spacing` for spacing tokens, and `menu` for navigation items.
-- Use `select` or `radio` when authors must choose from a fixed set of values. Keep option values stable and serializable.
-- Use `array` for repeatable items and `object` for grouped settings. Keep nested field names aligned with the prop shape and `defaultProps`.
-- For card grids, feature lists, pricing tables, logo walls, gallery grids, and any multi-column component, expose a `columns` prop with a `range` or `select` field and a sensible default.
-- Use `textarea` for multi-sentence copy and `text` only for short labels, headings, slugs, or plain strings that are not URLs/media/color/icon/font values.
-- Keep `fields`, `defaultProps`, and `render` in sync: every editor field should have a sensible default and render should tolerate omitted optional values.
-- Put editor-only controls in props when they change rendering, for example `showLogo`; pair dependent controls with `visibleIf` rather than hiding logic only in JSX.
-- Keep persisted props JSON-serializable. Do not store functions, React nodes, class instances, database ids for media, or environment-specific absolute filesystem paths.
-- Add optional field-level `ai.instructions`, `ai.required`, or `ai.exclude` when a prop needs generation guidance beyond its label and type.
+Use `ai.exclude: true` only for structural or editor-only components, and still provide instructions explaining why AI must not generate them. `PageOutlet` is the standard example.
 
 ## Block slot authoring rules
 
-Prefer `blockSlots` when a section owns nested content that benefits from independent editor selection and configuration, such as hero actions, pricing cards, feature rows, stats, or timeline items. This is usually more editor-friendly than modeling those items as plain `array` / `object` fields because each local block can be selected and configured on its own in the visual editor. Keep ordinary section props in `fields`; `fields` is optional and does not need to list every prop.
+Use `blockSlots` when a section owns controlled local content that benefits from independent editor selection and configuration, such as hero actions, pricing cards, feature rows, stats, timeline items, or contact methods. Keep ordinary section props in `fields`.
 
-- Type the slot prop as Puck `Slot` and declare `blockSlots` with the same prop key. Non-slot props should stay in `fields` or nested `array` / `object` fields.
+- Type the slot prop as Puck `Slot` and declare `blockSlots` with the same prop key. This is the Suda block-slot API; do not create a native `fields.<key>.type = "slot"` yourself.
 - Define local block kinds under `blockSlots.<slotName>.blocks`. Local blocks support normal Suda fields, `label`, `defaultProps`, `render`, `metadata`, `inline`, `permissions`, and optional `ai`.
+- Keep local blocks specific to the owning section. They are not reusable global page components.
 - Do not add nested `blockSlots` or `cms` to local blocks. Block slots are one level deep in the theme authoring API.
 - Do not put the slot prop in the host component's `defaultProps`; use `defaultBlocks` on the slot instead.
 - Do not hand-write `id` in local block `defaultProps`, `defaultBlocks[].props`, or starter page nested block props. The editor/runtime owns block ids.
@@ -71,7 +95,8 @@ type HeroProps = {
 export const Hero: SudaComponentConfig<HeroProps> = {
   label: "Hero",
   ai: {
-    instructions: "Primary page introduction with editable call-to-action blocks.",
+    instructions:
+      "Primary page introduction for landing pages. Use once near the top with one or two local action blocks.",
   },
   fields: {
     title: { type: "text", label: "Title" },
@@ -108,7 +133,7 @@ export const Hero: SudaComponentConfig<HeroProps> = {
 };
 ```
 
-Starter page data should use the public host component type and a standard slot array on the slot prop. Use local block `kind` values as nested `type` values.
+Starter page data should use the public host component type and a standard array on the block-slot prop. Use local block `kind` values as nested `type` values.
 
 ```ts
 {
@@ -128,3 +153,35 @@ Starter page data should use the public host component type and a standard slot
   },
 }
 ```
+
+## Starter pages
+
+- Provide realistic starter pages in `src/templates.ts`; do not ship placeholder-only pages.
+- Every starter page is Puck `Data` with `root: { props: {} }` and `content: [...]`.
+- Each top-level component instance in starter page `content` must include a stable `props.id`.
+- Use only components registered in `pageConfig.components` for top-level page content.
+- Match starter page content to the theme's intended audience and category. The home page should show the theme's best composition, not just every component in order.
+- Use `themeAsset("assets/...")` for bundled starter media.
+
+## CMS-aware themes
+
+- If the theme supports posts or tags, declare `content.views` on the exported `ThemeModule`.
+- Add one starter page with matching `cmsView` for every declared CMS view.
+- Declare component-level `cms` capabilities only on components that can render that CMS source.
+- Use `cmsBinding` in starter page props when a component should receive CMS data at render time.
+- Keep static fallback props for CMS components so the page still renders meaningfully when CMS payloads are absent.
+
+## Commands
+
+```bash
+pnpm install
+pnpm lint
+pnpm typecheck
+pnpm format
+pnpm dev       # Vite-powered local preview
+pnpm build     # Vite build + Suda artifact finalize + AI metadata check
+pnpm validate
+suda theme check
+```
+
+Before publishing or handing off a finished theme, run `pnpm typecheck`, `pnpm lint`, `pnpm build`, and `pnpm validate`. Use `suda theme check` when iterating on AI metadata.